RDIST(1)		    General Commands Manual		      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)