These are instructions for configuring sifter after installation. You should already have a rough idea what the program does, and how it behaves before you try to configure it.

You need to put a configuration file called .siftrc in your home directory. This is the master master configuration file. It tells sifter which computers you wish to share files with, how you will connect with these files, and which are the main or root directories that should be transfered.

It also has a set of translation rules that tell sifter how it should rename files during transfer, or which files should not be transfered at all.

You may also put a file called .siftrc in any subdirectory where you want to override the translation rules defined in your home directory. These rules are only valid in the directory where the file is found, and any of its subdirectories.

You may wish to look at my configuration file for an example. I will discuss it in more detail later in this description.

Or you may want to start with a simple configuration file. It probably sends more files than you really want to.

The configuration file can use regular expressions in many places. There are two forms that a regular expression can take:

• Simple "star" form (default). In this form, an asterisk is used as a wild card. For example dog.* matches dog.txt.
• GNU/Perl or extended form. A full regular expression can be used if you surround it by quotes and start it with "re". For example,

         re"(dog)?[0-9]*cat"
         

  matches dog2cat and 412cat. This form can not be used in translations (to change file names, see below), only in conditions.

File Format

What's in the .siftrc file:

• Comments start with a pound sign '#' and end at the end of the line.
• Aliases for machine names:

         alias NAME = LIST;
         

  where NAME is the alias that will be used for all data files and translations, and LIST is a comma separated list of machines that will use this alias. For example, my work machine's hostname is usually ex129927.rdyne.boeing.com, unless I.T. changes the domain name (which they do, at random). SO I use:

         alias work = ex129927*;
         

• user names. (not used right now.) Some day you can map user id's from one machine to another. But you can't do it yet!
• Variable definitions:

         def NAME = STRING;
         

  This defines a variable as a string so that it can be used as shorthand later on. For example if you have def x = "full/path/for/x";, then later on $x will be replaced with the whole string. (Or you can use $[x]). Several variables are pre-defined:

  local

  The hostname of the local computer. If an alias was used, this is the alias.

  localHost

  The full hostname of the local computer.

  remote

  The hostname of the remote computer.

  user.home

  The user's home directory.

  Variables can also be defined at runtime using the -D variable=val switch.
• Connection methods:

         connect LOCAL -> REMOTE  METHOD ...;
         

  LOCAL and REMOTE are the local and remote names of computers for transfering. You can define several connections if you want three way mirrors, but you should be careful: I haven't thought too carefully about three-way transfers.

  METHOD is currently either "file", "floppy", "telnet", or "rsh":

  file

  connect LOCAL -> REMOTE  file: FILE;

  FILE is the filename used for the transfer. The data is written to a file which can be coppied however you wish.

  floppy

  connect LOCAL -> REMOTE  floppy: FILE;

  FILE is the full pathname of a file on the floppy disk, such as "/floppy/sifter.dat" or "/mnt/floppy/sifter.dat". The unix command "mount" and "umount" will be run on the dirctory part of the pathname so that multiple floppies can be used when one fills up.

  rsh

  connect LOCAL -> REMOTE  rsh PATH { SCRIPT };

  PATH is the command used to start an rsh process. SCRIPT is a list of quoted strings that are piped to the rsh process. The last command should be the one needed to start sifter. The local process will append some switches to this last string to let the remote process know it should run in passive mode.

  telnet

  connect LOCAL -> REMOTE  telnet;

  This isn't tested very well. (or at all) It will probably go away.

• Root directories. This gives the root directory to search for files that should be sent.

         dir HOST1 : DIR1 -> HOST2 : DIR2;
         

  The directories must be full paths and cannot contain wild cards, but they can use variables. There can be several root directories. For example, I might use:

         dir home:/home/fredgc -> work:/home/fdgylysc;
         dir home:/usr/src/argoblath -> work:/usr/src/argoblath;    
         

• Lists of translations. A list is enclosed in curly braces, and each translation ends in a semicolon. A translation is used for the program to decide which files to send, and to rename files when they are sent. A translation looks like this:

         CONDITION (, CONDITION2)*  : NAME1 -> NAME2;
         

  The program uses the comma seprated list of conditions to decide which files to send. If there are no conditions, then all files match. NAME1 and NAME2 are used to rename files. If NAME2 is "/dev/null", then the file is not sent. The names can be simple regular expressions, as long as both NAME1 and NAME2 have the same number of asterisks (wild cards). If NAME1 or NAME2 is blank, The wildcard name "*" is used.

  For a translation to be used, all conditions must match, and the filename must match NAME1. An example would be:

         {
         # Don't send .o files or .class files.
            *.o, *.class : -> /dev/null;  
         # Replace the file ending .txt with host name.
            :  *.txt -> *.$local;  
         # If it is in the bin directory, and it has file type 'perl', and
         # the filename ends in '.pl', then remove the '.pl' ending and send it.
             (dir = *bin) & (magic = perl) : *.pl -> *; 
         # don't send compiled programs
             (permission = *x*) & (magic = ELF)
                 : -> /dev/null;
         }
         

  Conditions are of the form KEY = VALUE or KEY != VALUE. KEY can be one of:

  name

  for filename (this is the default if KEY is not specified).

  dir

  for the directory of the file.

  user

  for the user name of the owner of the file (untested! don't use!).

  group

  for the group name of the owner of the file (untested! don't use!).

  permission

  for the permssion string of the file (such as "rwxr-xr-x").

  magic

  for the output of the program "file". This looks for VALUE anywhere in the output of "file".

  The key will be compared against the value, which can be a string, or a regular expression. (see regular expressions above).

  Boolean arithmentic can be used with conditions: "|" (bar), or "," (comma) can be used for "or"; "&" (ampersand) is used for "and" and "!" (exclamation point) is "not". (Order of operation is "not" then "and" then "or").

  Before a list of translations, you can specify which hosts the list is valid for:

         HOST1 -> HOST2 { ...}
         

  This will only apply these translations when files are sent from HOST1 to HOST2.

Example

As an example, here is the configuration file I'm using. I have access to three machines: my home machine, which I've named "goose", running linux. My PC at work, with a hostname of "ex129927.rdyne.boeing.com", and a farm of Sun machines named "us200", "us201", "us202", .... and their file server "goliath". The Sun machines run some type of Solaris or SunOS. I can only access Goliath through samba, so I can't keep my file permissions straight without using sifter.

Mostly I want to transfer my source code, and my .Xdefault type files. However, I want to keep different versions of .Xdefault files since there is some difference between the machines.

I have decided that most of the files I have in my root (home) directory do not need to be transfered, so I set up the configuration to send an explicit list, and then ignore any other file in my home directory. This works, since sifter only uses the first translation that matches.

I have a different user ID at home and work (but that part of the code doesn't work yet...)

We are behind a firewall at work, so when I take files home, I use a floppy drive. I rarely need more than one floppy, but sometimes I do.