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

FreeBSD Manual Pages


home | help
RDIST(1)		    General Commands Manual		      RDIST(1)

       rdist - remote file distribution	client program

       rdist  [	 -DFn ]	[ -A num ] [ -a	num ] [	-d var=value ] [ -l _local lo-
       gopts_ ]	[ -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 (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 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 se-
       tuid 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 re-
		     cursively 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

		     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 in-
		     stead 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 op-
       tions 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  ad-

       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  in-
		     stalled 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 lo-
       cal 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 for-
       mat) 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  ex-
       panded  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 ap-
       pended 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

	      `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 in-
       clude 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