rdist



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 <trans-
       port-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 pos-
       sible 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.  Oth-
       erwise, 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  spe-
       cific 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  (the  path  /usr/bin/oldrdist 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 program can be specified at run-time on the com-
       mand 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 con-
       nection 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  paren-
              theses 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  dist-
              file  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  sepa-
              rated  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 desti-
                     nation directory name.  Normally, 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  exam-
                     ple,  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 tar-
              get host.

       -P <transport-path>
              Set the path to the transport command to be used.  This is  nor-
              mally  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/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 con-
       tain 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 sys-
       log(3) system facility which uses an ascending order scheme.  The  fol-
       lowing 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  explic-
                     itly 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  mes-
       sages  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  other-
       wise 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 recog-
       nized 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 direc-
       tory 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  directo-
       ries.  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  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 ‘;’.  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/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 (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.



4.3 Berkeley Distribution        June 13, 1998                        RDIST(1)

Man(1) output converted with man2html