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 <rsh-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 (usually either /usr/ucb/oldrdist or
       /usr/old/rdist) and that program is available at run time.

       Rdist can use either the  rcmd(3)  function  call  or  the
       rsh(1c), remote shell, command to access each target host.
       The method used  is  selected  at  compile-time.   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



                         January 29, 1996                       1





RDIST(1)                                                 RDIST(1)


              /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.

       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



                         January 29, 1996                       2





RDIST(1)                                                 RDIST(1)


              .  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.



                         January 29, 1996                       3





RDIST(1)                                                 RDIST(1)


                     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.



                         January 29, 1996                       4





RDIST(1)                                                 RDIST(1)


              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 <rsh-path>
              Set the path to the rsh(1c) command.  The  rsh-path
              may  be  a  colon  separated list of possible path-
              names.  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



                         January 29, 1996                       5





RDIST(1)                                                 RDIST(1)


              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.




                         January 29, 1996                       6





RDIST(1)                                                 RDIST(1)


              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).




                         January 29, 1996                       7





RDIST(1)                                                 RDIST(1)


       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



                         January 29, 1996                       8





RDIST(1)                                                 RDIST(1)


       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



                         January 29, 1996                       9





RDIST(1)                                                 RDIST(1)


       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.

       RSH    Name of the default remote shell  program  to  use.
              Default is /usr/bin/rsh.

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

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





                         January 29, 1996                      10





RDIST(1)                                                 RDIST(1)


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.































                         January 29, 1996                      11