RDIST(1)                                                 RDIST(1)

NAME
       rdist - remote file distribution client program

SYNOPSIS
       rdist [ -DFn ] [ -A num ] [ -a num ] [ -d var=value ] [ -l
       <local logopts> ] [ -L <remote logopts> ] [ -f distfile  ]
       [  -M maxproc ] [ -m host ] [ -o distopts ] [ -t timeout ]
       [ -p <rdistd-path> ] [ -P <transport-path> ] [ name ...  ]

       rdist -DFn -c name ...  [login@]host[:dest]

       rdist -Server

       rdist -V

DESCRIPTION
       Rdist  is  a program to maintain identical copies of files
       over multiple hosts.  It preserves the owner, group, mode,
       and  mtime  of  files  if possible and can update programs
       that are executing.  Rdist reads commands from distfile to
       direct the updating of files and/or directories.  If dist-
       file is `-', the standard input is used.  If no -f  option
       is  present,  the program looks first for `distfile', then
       `Distfile' to use as the input.  If no names are specified
       on  the  command  line, rdist will update all of the files
       and directories listed in distfile.  Otherwise, the  argu-
       ment  is  taken  to be the name of a file to be updated or
       the label of a command to execute. If label and file names
       conflict,  it is assumed to be a label.  These may be used
       together to update specific files using specific commands.

       The  -c  option  forces  rdist  to interpret the remaining
       arguments as a small distfile.  The equivalent distfile is
       as follows.

            ( name ... ) -> [login@]host
                 install   [dest] ;

       The  -Server option is recognized to provide partial back-
       ward compatible support for older versions of rdist  which
       used  this option to put rdist into server mode.  If rdist
       is started with the -Server command line option,  it  will
       attempt  to  exec  (run)  the  old version of rdist.  This
       option will only work if rdist was compiled with the loca-
       tion  of the old rdist (the path is used on Red Hat linux)
       and that program is available at run time.

       Rdist can use either the rcmd(3) function call or  run  an
       arbitrary transport program such as rsh(1c) to access each
       target host.  The method used is selected at compile-time.
       However,  if  the later method is used, the transport pro-
       gram can be specified at run-time on the command line with
       the  default being rsh(1c).  If the rsh(1c) method is used
       and the target host is the string localhost and the remote
       user  name  is the same as the local user name, rdist will
       run the command

              /bin/sh -c rdistd -S

       Otherwise rdist run will run the command

              rsh host -l remuser rdistd -S

       where host is the name of the target host, remuser is  the
       name  of the user to make the connection as and, rdistd is
       the rdist server command  on  the  target  host  as  shown
       below.   To use a transport program other than rsh(1c) use
       the -P option.  Whatever transport program is  used,  must
       be compatible with the above specified syntax for rsh(1c).
       If the transport program is not, it should be wrapped in a
       shell  script which does understand this command line syn-
       tax and which then executes the real transport program.

       Here's an example which uses ssh(1) as the transport:

              rdist -P /usr/local/bin/ssh -f myDistfile

       If the rcmd(3) method is used, then rdist makes  the  con-
       nection  to  the  target  host  itself and runs the rdistd
       server program as shown below.  The default, and preferred
       method, is to use rsh(1c) to make the connection to target
       hosts.  This allows rdist to be run without  being  setuid
       to ``root''.

       On each target host Rdist will attempt to run the command

              rdistd -S

       or

              <rdistd path> -S

       if  the  -p  option  was  specified.   If  no -p option is
       included, or the  <rdistd  path>  is  a  simple  filename,
       rdistd  or <rdistd path> must be somewhere in the $PATH of
       the user running rdist on the remote (target) host.

OPTIONS
       -A num Set the minimum number of free files (inodes) on  a
              filesystem  that  must exist for rdist to update or
              install a file.

       -a num Set the minimum amount of free space (in bytes)  on
              a filesystem that must exist for rdist to update or
              install a file.

       -D     Enable copious debugging messages.

       -d var=value
              Define var to have value.  This option is  used  to
              define or override variable definitions in the dis-
              tfile.  Value can be the empty string, one name, or
              a list of names surrounded by parentheses and sepa-
              rated by tabs and/or spaces.

       -F     Do not fork any child rdist processes.  All clients
              are updated sequentially.

       -f distfile
              Set  the name of the distfile to use to be distfile
              .  If distfile is specified as  ``-''  (dash)  then
              read from standard input (stdin).

       -l logopts
              Set local logging options.  See the section MESSAGE
              LOGGING for details on the syntax for logopts.

       -L logopts
              Set remote logging options.  logopts is the same as
              for  local  logging except the values are passed to
              the remote server (rdistd).  See the  section  MES-
              SAGE LOGGING for details on the syntax for logopts.

       -M num Set the maximum number  of  simultaneously  running
              child rdist processes to num.  The default is 4.

       -m machine
              Limit which machines are to be updated. Multiple -m
              arguments can be given to limit updates to a subset
              of the hosts listed in the distfile.

       -n     Print  the  commands  without  executing them. This
              option is useful for debugging distfile.

       -odistopts
              Specify the dist options to enable.  distopts is  a
              comma  separated  list  of options which are listed
              below.  The valid values for distopts are:

              verify Verify that the files are up to date on  all
                     the  hosts.  Any  files that are out of date
                     will be  displayed  but  no  files  will  be
                     changed nor any mail sent.

              whole  Whole  mode. The whole file name is appended
                     to the  destination  directory  name.   Nor-
                     mally,  only the last component of a name is
                     used when renaming files.   This  will  pre-
                     serve  the  directory structure of the files
                     being  copied  instead  of  flattening   the
                     directory structure. For example, rdisting a
                     list of  files  such  as  /path/dir1/f1  and
                     /path/dir2/f2 to /tmp/dir would create files
                     /tmp/dir/path/dir1/f1                    and
                     /tmp/dir/path/dir2/f2       instead       of
                     /tmp/dir/dir1/f1 and /tmp/dir/dir2/f2.

              noexec Automatically exclude executable files  that
                     are in a.out(5) format from being checked or
                     updated.

              younger
                     Younger mode. Files are normally updated  if
                     their mtime and size (see stat(2)) disagree.
                     This option causes rdist not to update files
                     that are younger than the master copy.  This
                     can be used to prevent newer copies on other
                     hosts  from  being replaced.  A warning mes-
                     sage is printed for files  which  are  newer
                     than the master copy.

              compare
                     Binary comparison. Perform a binary compari-
                     son and update files if they  differ  rather
                     than comparing dates and sizes.

              follow Follow  symbolic  links.  Copy the file that
                     the link points  to  rather  than  the  link
                     itself.

              ignlnks
                     Ignore  unresolved  links.   Rdist will nor-
                     mally try to maintain the link structure  of
                     files being transferred and warn the user if
                     all the links cannot be found.

              chknfs Do not check or update files on target  host
                     that reside on NFS filesystems.

              chkreadonly
                     Enable check on target host to see if a file
                     resides on a  read-only  filesystem.   If  a
                     file  does,  then no checking or updating of
                     the file is attempted.

              chksym If the target on the remote host is  a  sym-
                     bolic  link,  but is not on the master host,
                     the remote target will be  left  a  symbolic
                     link.  This behavior is generally considered
                     a bug in the original version of rdist,  but
                     is present to allow compatibility with older
                     versions.

              quiet  Quiet mode. Files that  are  being  modified
                     are  normally  printed  on  standard output.
                     This option suppresses this.

              remove Remove extraneous files. If a  directory  is
                     being  updated,  any files that exist on the
                     remote host that do not exist in the  master
                     directory  are  removed.  This is useful for
                     maintaining truly identical copies of direc-
                     tories.

              nochkowner
                     Do  not  check  user ownership of files that
                     already exist.  The file ownership  is  only
                     set when the file is updated.

              nochkgroup
                     Do  not  check group ownership of files that
                     already exist.  The file ownership  is  only
                     set when the file is updated.

              nochkmode
                     Do  not  check file and directory permission
                     modes.  The permission mode is only set when
                     the file is updated.

              nodescend
                     Do  not  descend into a directory.  Normally
                     rdist will  recursively  check  directories.
                     If  this  option  is enabled, then any files
                     listed in the file list in the distfile that
                     are directories are not recursively scanned.
                     Only the existence, ownership, and  mode  of
                     the directory are checked.

              numchkgroup
                     Use  the  numeric  group  id  (gid) to check
                     group ownership instead of the group name.

              numchkowner
                     Use the numeric user id (uid) to check  user
                     ownership instead of the user name.

              savetargets
                     Save  files  that  are  updated  instead  of
                     removing them.   Any  target  file  that  is
                     updates   is   first  rename  from  file  to
                     file.OLD.

              sparse Enable checking  for  sparse  (aka  wholely)
                     files.   One  of  the  most  common types of
                     sparse files are those produced by  ndbm(3).
                     This  option adds some additional processing
                     overhead so it should only  be  enabled  for
                     targets likely to contain sparse files.

       -p <rdistd-path>
              Set  the  path  where the rdistd server is searched
              for on the target host.

       -P <transport-path>
              Set the path to the transport command to  be  used.
              This  is normally rsh(1c) but can be any other pro-
              gram - such as ssh(1) - which  understands  rsh(1c)
              command line syntax and which provides an appropri-
              ate connection to the remote host.  The  transport-
              path  may  be  a  colon  seperated list of possible
              pathnames.  In this case, the  first  component  of
              the     path    to    exist    is    used.     i.e.
              /usr/ucb/rsh:/usr/bin/remsh , /usr/bsd/rsh.

       -t timeout
              Set the timeout period (in seconds) for waiting for
              responses   from  the  remote  rdist  server.   The
              default is 900 seconds.

       -V     Print version information and exit.

MESSAGE LOGGING
       Rdist uses a collection of predefined  message  facilities
       that each contain a list of message types specifying which
       types of messages to send to  that  facility.   The  local
       client  (rdist)  and the remote server (rdistd) each main-
       tain their own copy of what types of messages  to  log  to
       what facilities.

       The  -l  logopts  option to rdist tells rdist what logging
       options to use locally.  The -L logopts  option  to  rdist
       tells  rdist  what  logging  options to pass to the remote
       rdistd server.

       The form of logopts should be of form

              facility=types:facility=types...

       The valid facility names are:

              stdout Messages to standard output.

              file   Log to a file.  To specify  the  file  name,
                     use   the   format  ``file=filename=types''.
                     e.g.  ``file=/tmp/rdist.log=all,debug''.

              syslog Use the syslogd(8) facility.

              notify Use  the  internal  rdist  notify  facility.
                     This  facility  is  used in conjunction with
                     the notify keyword in a distfile to  specify
                     what  messages  are  mailed  to  the  notify
                     address.

       types should be a comma separated list of  message  types.
       Each  message  type  specified enables that message level.
       This is unlike the syslog(3) system facility which uses an
       ascending  order  scheme.   The  following  are  the valid
       types:

              change Things that  change.   This  includes  files
                     that are installed or updated in some way.

              info   General information.

              notice General info about things that change.  This
                     includes  things  like  making   directories
                     which  are needed in order to install a spe-
                     cific target, but which are  not  explicitly
                     specified in the distfile.

              nerror Normal errors that are not fatal.

              ferror Fatal errors.

              warning
                     Warnings about errors which are not as seri-
                     ous as nerror type messages.

              debug  Debugging information.

              all    All but debug messages.

       Here is a sample command line option:

              -l stdout=all:syslog=change,notice:file=/tmp/rdist.log=all

       This entry will set local message logging to have all  but
       debug  messages sent to standard output, change and notice
       messages will be sent to syslog(3), and all messages  will
       be written to the file /tmp/rdist.log.

DISTFILES
       The  distfile  contains a sequence of entries that specify
       the files to be copied, the destination  hosts,  and  what
       operations  to  perform to do the updating. Each entry has
       one of the following formats.

              <variable name> `=' <name list>
              [ label: ] <source list> `->' <destination list> <command list>
              [ label: ] <source list> `::' <time_stamp file> <command list>

       The first format is used for defining variables.  The sec-
       ond  format is used for distributing files to other hosts.
       The third format is used for making lists  of  files  that
       have  been changed since some given date.  The source list
       specifies a list of files and/or directories on the  local
       host which are to be used as the master copy for distribu-
       tion.  The destination list is the list of hosts to  which
       these  files  are  to  be copied.  Each file in the source
       list is added to a list of changes if the file is  out  of
       date on the host which is being updated (second format) or
       the file is newer than the time stamp file (third format).

       Labels  are  optional. They are used to identify a command
       for partial updates.

       Newlines, tabs, and blanks are only used as separators and
       are  otherwise  ignored.  Comments  begin with `#' and end
       with a newline.

       Variables to be expanded begin with `$'  followed  by  one
       character  or  a  name  enclosed  in curly braces (see the
       examples at the end).

       The source and destination lists have the  following  for-
       mat:

            <name>
       or
            `(' <zero or more names separated by white-space> `)'

       These  simple  lists can be modified by using one level of
       set addition, subtraction, or intersection like this:

            list '-' list
       or
            list '+' list
       or
            list '&' list

       If  additional  modifications  are  needed  (e.g.,   ``all
       servers   and   client   machines  except  for  the  OSF/1
       machines'') then the list will have to be explicitly  con-
       structed in steps using "temporary" variables.

       The shell meta-characters `[', `]', `{', `}', `*', and `?'
       are recognized and expanded (on the local  host  only)  in
       the  same way as csh(1).  They can be escaped with a back-
       slash.  The `~' character is also expanded in the same way
       as  csh but is expanded separately on the local and desti-
       nation hosts.  When the -owhole option is used with a file
       name  that  begins  with  `~',  everything except the home
       directory is appended to the destination name.  File names
       which  do  not  begin  with `/' or `~' use the destination
       user's home directory as the root directory for  the  rest
       of the file name.

       The  command list consists of zero or more commands of the
       following format.

              `install'     <options>    opt_dest_name `;'
              `notify'      <name list>  `;'
              `except'      <name list>  `;'
              `except_pat'  <pattern list>`;'
              `special'     <name list>  string `;'
              `cmdspecial'  <name list>  string `;'

       The install command is used to  copy  out  of  date  files
       and/or  directories.   Each  source file is copied to each
       host in the destination list.  Directories are recursively
       copied  in  the  same  way.   Opt_dest_name is an optional
       parameter to rename files.  If no install command  appears
       in  the command list or the destination name is not speci-
       fied, the source file name is used.   Directories  in  the
       path  name  will  be  created  if they do not exist on the
       remote host.  The -o distopts option  as  specified  above
       under  OPTIONS,  has  the same semantics as on the command
       line except they only apply to the  files  in  the  source
       list.   The login name used on the destination host is the
       same as the local host unless the destination name  is  of
       the format ``login@host".

       The  notify  command  is  used  to  mail the list of files
       updated (and any errors that may  have  occurred)  to  the
       listed names.  If no `@' appears in the name, the destina-
       tion host is  appended  to  the  name  (e.g.,  name1@host,
       name2@host, ...).

       The  except  command is used to update all of the files in
       the source list except for the files listed in name  list.
       This  is  usually  used  to copy everything in a directory
       except certain files.

       The except_pat command is like the except  command  except
       that  pattern  list  is a list of regular expressions (see
       ed(1) for details).  If one of the patterns  matches  some
       string  within  a  file  name,  that file will be ignored.
       Note that since `\' is a quote character, it must be  dou-
       bled  to become part of the regular expression.  Variables
       are expanded in pattern list but not  shell  file  pattern
       matching characters.  To include a `$', it must be escaped
       with `\'.

       The special command is used to specify sh(1) commands that
       are  to  be  executed on the remote host after the file in
       name list is updated or installed.  If the  name  list  is
       omitted then the shell commands will be executed for every
       file updated or installed.  String starts  and  ends  with
       `"'  and  can  cross multiple lines in distfile.  Multiple
       commands to the shell should be separated  by  `;'.   Com-
       mands  are  executed  in  the user's home directory on the
       host being updated.  The special command can  be  used  to
       rebuild  private databases, etc.  after a program has been
       updated.  The following environment variables are set  for
       each special command:

       FILE   The  full  pathname of the local file that was just
              updated.

       REMFILE
              The full pathname of the remote file that was  just
              updated.

       BASEFILE
              The  basename  of  the  remote  file  that was just
              updated.

       The cmdspecial command is similar to the special  command,
       except it is executed only when the entire command is com-
       pleted instead of after each file is updated.  The list of
       files  is placed in the environment variable $FILES.  Each
       file name in $FILES is separated by a `:' (colon).

       If a hostname ends in a ``+'' (plus sign), then  the  plus
       is  stripped  off  and  NFS  checks are disabled.  This is
       equivalent to disabling the -ochknfs option just for  this
       one host.

       The following is a small example.

              HOSTS = ( matisse root@arpa)

              FILES = ( /bin /lib /usr/bin /usr/games
                            /usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h}
                            /usr/lib /usr/man/man? /usr/ucb /usr/local/rdist )

              EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc
                            sendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont )

              ${FILES} -> ${HOSTS}
                            install -oremove,chknfs ;
                            except /usr/lib/${EXLIB} ;
                            except /usr/games/lib ;
                            special /usr/lib/sendmail "/usr/lib/sendmail -bz" ;

              srcs:
              /usr/src/bin -> arpa
                            except_pat ( \\.o\$ /SCCS\$ ) ;

              IMAGEN = (ips dviimp catdvi)

              imagen:
              /usr/local/${IMAGEN} -> arpa
                            install /usr/local/lib ;
                            notify ralph ;

              ${FILES} :: stamp.cory
                            notify root@cory ;

ENVIRONMENT
       TMPDIR Name  of  temporary  directory  to use.  Default is
              /tmp.

FILES
       distfile       - input command file
       $TMPDIR/rdist* - temporary file for update lists

SEE ALSO
       sh(1), csh(1), stat(2), rsh(1c), rcmd(3)

DIAGNOSTICS
NOTES
       If the basename of a file   (the  last  component  in  the
       pathname)  is ".", then rdist assumes the remote (destina-
       tion) name is a directory.  i.e.  /tmp/.  means that  /tmp
       should be a directory on the remote host.

       The  following  options are still recognized for backwards
       compatibility:

              -v -N -O -q -b -r -R -s -w -y -h -i -x

BUGS
       Source files must reside on the local host where rdist  is
       executed.

       Variable expansion only works for name lists; there should
       be a general macro facility.

       Rdist aborts on files which have a negative mtime  (before
       Jan 1, 1970).

       If  a hardlinked file is listed more than once in the same
       target, then rdist will report missing  links.   Only  one
       instance of a link should be listed in each target.

                          June 13, 1998                         1