SourceFiles.org - Use the Source, Luke

<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html>
<head>

<center><img SRC="fupdate.gif" height=45 width=180>  
  
<a href="http://cs.nmu.edu/~lhanson/fupdate/index.html">Home</a>   |   Readme   |   <a href="http://cs.nmu.edu/~lhanson/fupdate/downloads.html">Downloads</a>   |   <a href="mailto:lhanson@nmu.edu?SUBJECT=fupdate">Contact</a></center>

<h2>
README 
v0.0.1 
3.25.00</h2>
    First off: This code is distributed WITHOUT ANY WARRANTY. Use it at your own risk, I take no responsibility for anything. See the <a href="LICENSE">LICENSE</a> file for details.  
<blockquote><a href="INTRO">INTRO</a>
 <a href="REQUIREMENTS">REQUIREMENTS</a> <a href="INSTALLATION">INSTALLATION</a> <a href="CONFIGURATION">CONFIGURATION</a> <a href="USAGE">USAGE</a>
 <a href="EXAMPLES">EXAMPLES</a>
 <a href="KNOWN PROBLEMS/BUGS">KNOWN PROBLEMS/BUGS</a> <a href="TODO">TODO</a>
 <a href="REVISION HISTORY">REVISION HISTORY</a></blockquote>

<a NAME="INTRO"></a>INTRO
    fupdate is a program that is capable of checking sets of files on multiple hosts and determining which host has the newest revision. Based on this, it will distribute the newest version of the file to the other hosts.
     This project evolved from my tinkering with shell scripts and thinking about all the neat things that can be done. I originally started writing it because I use several different machines during the course of a day, and wanted my Netscape bookmarks to follow me around. I realize that it would be much better if written in a real language, but I'd like to move on to other things. There's so much more to play with.     I've looked around for other programs that would get the job done. There are some good ones, but none of them seem to do exactly what I wanted. I don't think packages like rdist or Mirror are really targeted for this kind of task. If I'm wrong, let me know!     I'm not sure how much continuing development will go into this, but probably not much (unless I get some feedback). If just one other person finds a use for this code, I'll be completely satisfied. I'll also be more than willing to work with anybody to improve this, so if you see something that doesn't work right, is annoying, could be done better, or if you just want it to do something that it doesn't already, please feel free to let me know.
  
  
<a NAME="REQUIREMENTS"></a>REQUIREMENTS As of this initial release, fupdate has not been tested on anything but Linux 2.2.x. The script relies on many of the standard utilities lying around on a nix system. It relies completely on ftp to communicate between hosts, so you need to have a .netrc file in order to automatically log into your ftp accounts. If you encounter any problems with running fupdate on your system, let me know and I'll help as much as I can.     The .netrc file needed to automate ftp logins must exist at ~/.netrc and must contain a line for each host entered into your config file. Each .netrc entry follows this format:  
<blockquote>machine hostname* login yourLoginName password yourPassword</blockquote>

Items between *'s need to be changed to reflect your needs. Once this file is set up correctly, fupdate will be able to access your ftp accounts to get at any files it needs.  
  
<a NAME="INSTALLATION"></a>INSTALLATION     The script isn't very picky about where it lives. At this point it's set up to live in an individual user's home directory, although if there's any demand I will tweak it to be run globally from /usr/local/bin or somewhere like that. You can certainly set it up any way you want, but there may be unforseen kinks to work out.  
  
<a NAME="CONFIGURATION"></a>CONFIGURATION     For fupdate to know what you want it to do, you have to modify the `config` file, which should be located in the same directory as fupdate. To activate options, uncomment them and fill in any necessary data. This file is commented to help you out, but here is a little bit more detail:
     First, you need to decide where you want output to go. You can select any number of the following 3 options.  
  
<table BORDER=0 WIDTH="100%" NOSAVE >
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>screenOutput</td>

<td>     If you're running this right from the prompt, you DO want this! Otherwise you'll have no feedback in case of problems. Also note that if you run fupdate from a cron job, this type of output will automatically be mailed to you.</td> </tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE>mailOutput:email@address</td>

<td>     This option will mail the output to the address following the colon. Support for multiple addresses would be easy if somebody requests it.</td>
</tr>

<tr VALIGN=TOP NOSAVE>
<td NOSAVE>logOutput:/path/logfile</td>

<td>     Logs the output to the file specified after the colon. The pathname can be relative or absolute. Make sure you have write permission to the directory you specify.</td> </tr>
</table>

Now you need to specify how verbose you want the output to be (LOW, MEDIUM, or HIGH).
  
<blockquote>LOW will basically tell you about errors and transfer results. MEDIUM is just that. It tells you what's going on in more detail. HIGH is good for debugging, or if you just want to know more about what's going on.</blockquote>

Logging is an area that probably needs to be ironed out some more. Without a second opinion, I just went with what I thought was useful info in useful places. This can easily be tweaked or customized according to need or personal preference.     The last, and most important, you need to specify groups of files that you want updated. These are split up into Groups.  Each Group begins with a header telling fupdate the name you will use to refer to that group, like "Group:myGroup". Each line after this header (but before the next Group) has three fields, and represents a copy of the file we're dealing with. My main reason for writing this is to keep my Netscape bookmarks updated, so here's a Group listing that I could use:  
<blockquote>Group:bookmarks
     # servername:remote directory/:filename (This is just a comment)
     bart:/home/brodsky/.netscape/:bookmarks.html    upthepunx.org:/home/brodsky/.netscape/:bookmarks.html     localhost:/home/brodsky/archive/:bookmarks.html.BAK  </blockquote>
    This entry represents three hosts that I want my bookmarks tracked on. The first three "remote directory" fields are all the same, because on all machines I have the same username and the bookmark file is located in the same place. The last field, "remote filename", is the same for the first three because the bookmark file has the same name on all the systems. The last entry would give me a backup copy of my bookmark file in my "archive" directory on "homer." You can have as many groups as you want, syncronizing any files you want. Note the types of values that the servername field can have.
     You may notice that the filename is the same for most of the entries. For most applications you'd want to keep the filename the same, so this seems a bit redundant...however, for the most flexibility I chose to have the filename specified for each machine.     Be aware that the script is somewhat picky about the config file. For example, lines with #'s anywhere in them will be ignored.  
  
<a NAME="USAGE"></a>USAGE
    There are two basic methods in which to actually run fupdate:
--- Invoke it from the command line. Usage is as follows:     fupdate [ option ] [ group1 group2 ... ]     Options:
         -a or --all Processes ALL groups
         --help Prints usage info         --version Prints the version --- Run it from an entry in your crontab     You can have your files periodically updated automatically by creating an appropriate cronab entry. See the next section for examples of this.
  
  
<a NAME="EXAMPLES"></a>EXAMPLES     Here's a scenario: you're working on a development project, but you work on it from several different machines. Your configuration file would have a "Development" group, with lines for each file in the project. When you're done changing code and want to sync up ALL of the machines with the newest updates, you would simply run `fupdate Development` to update the files from the command line. If you have the screenOutput option enabled, you could watch the update take place. Or, if it's a large project and takes a while to run, you could select mailOutput or logOutput (or both) and do a `fupdate Development &` to execute the program in the background. You can later check the log (or your mail) to see the results.     Yet another option would be to have your project automatically updated periodically. To do this, you would need to set up a cron job on the computer you use the most. It's best to choose ONE machine to do the syncing; more won't hurt, but will use more resources for something that one machine can handle. So, running `crontab -e` will open up an editing session for your crontab. Now if I wanted my files updated every day at 3am, I'd create an entry like this...
00    3    *    *    *    /home/brodsky/fupdate/fupdate Development     There is a problem with this entry, however. Cron automatically mails you any output that the program tries to write to stdout. Even if you only enable logOutput, so as not to be bothered by email, certain errors generated by fupdate (more specifically, the programs it calls) unavoidably write to standard output, resulting in cron sending you silly little emails. A better idea would be to force any noise generated by fupdate to be thrown away, leaving you with only the output you ask for in the configuration file. So here's a better entry... 00    3    *    *    *    /home/brodsky/fupdate/fupdate Development 2>&1 > /dev/null
    Now you have complete control over the output through the configuration file. Check the docs if you're unsure of how to use crontab.     As you can see, fupdate can be set up to be useful in a variety of situations. In any case, however, you should always run the program from the command prompt with screenOutput enabled and logLevel=HIGH to test out new Groups before you let them run without supervision.  
  
<a NAME="KNOWN PROBLEMS/BUGS"></a>KNOWN PROBLEMS/BUGS     The biggest problem: it's written in straight shell script. Not very cool.
     The script relies upon .netrc to have the correct ftp login information, otherwise it will hang up at the "Password:" prompt of the ftp login.
     Chances are, the times on different machines aren't perfectly syncronized. If the times are significantly off, errors may occur. For example, machine A's clock is 5 minutes ahead of machine 5. Now, if you modify a file on machine B less than 5 minutes after its counterpart on machine A, and then run fupdate, it will appear to fupdate that the copy on machine A is newer, because its timestamp is more recent. Machine A's copy will be distributed, and overwrite the one on machine B (which is really most recent). So be aware of any time discrepancies. Future versions could include compensation for this.     If all files are effectively current, the modification times will still appear to be different because ftp can't simultaneously update all the files in one instant. Transfers will take place no matter what.
  
  
<a NAME="TODO"></a>TODO
    Toss out only the config entries with # as the FIRST character.
     Implement a "test" option that echoes the steps fupdate would take, but without actually overwriting any files.     Allow for alternate config files.     Compensate for system time differences as mentioned above.     As noted in the KNOWN PROBLEMS/BUGS section, transfers will occur even if all the files contain exactly the same data. Perhaps fuptime could keep a local record of file sizes and effective modtimes to reference, determining if a file REALLY needs updating.  
  
<a NAME="REVISION HISTORY"></a>REVISION HISTORY     0.0.1 - Society initially infected with fupdate </body>
</html>