Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RDIST(1)							      RDIST(1)

       rdist - remote file distribution	client program

       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

       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


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

       -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

       -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

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

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

		     Binary comparison.	Perform	a binary comparison and	update
		     files  if	they  differ  rather  than comparing dates and

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

		     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.

		     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.

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

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

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

		     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.

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

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

		     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.

       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


       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.

	      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

       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.

		     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

       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

       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:

	    `('	<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
	    list '+' list
	    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

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

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

	      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 `:'

       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/lib /usr/man/man? /usr/ucb /usr/local/rdist )

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

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

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

	      IMAGEN = (ips dviimp catdvi)

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

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

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

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

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

       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

       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)


Want to link to this manual page? Use this URL:

home | help