Provided by: rdist_6.1.5-21_amd64 bug

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 distfile 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 argument 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 backward 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  location  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 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 program 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 syntax 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 connection 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 distfile.  Value can be the empty string, one name, or a list of
              names surrounded by parentheses and separated 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  MESSAGE  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.  Normally, only the last component of a name  is  used  when  renaming
                     files.  This will preserve 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 message is printed for files
                     which are newer than the master copy.

              compare
                     Binary comparison. Perform a binary comparison  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  normally  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 symbolic  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
                     directories.

              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 program - such as ssh(1) -  which  understands  rsh(1c)  command  line
              syntax  and  which  provides  an  appropriate  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/bin/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 maintain 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 specific 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 serious 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  second  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
       distribution.  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 format:

            <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 constructed 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 backslash.
       The `~' character is also expanded in the same way as csh but is  expanded  separately  on
       the  local  and  destination 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 specified, 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 destination 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  doubled 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 `;'.  Commands 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 completed 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/sbin/sendmail "/usr/sbin/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  (destination) 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.