1RDIST(1)                    General Commands Manual                   RDIST(1)
2
3
4

NAME

6       rdist - remote file distribution client program
7

SYNOPSIS

9       rdist  [  -DFn  ]  [  -A  num ] [ -a num ] [ -d var=value ] [ -l <local
10       logopts> ] [ -L <remote logopts> ] [ -f distfile ] [ -M maxproc ] [  -m
11       host ] [ -o distopts ] [ -t timeout ] [ -p <rdistd-path> ] [ -P <trans‐
12       port-path> ] [ name ...  ]
13
14       rdist -DFn -c name ...  [login@]host[:dest]
15
16       rdist -Server
17
18       rdist -V
19

DESCRIPTION

21       Rdist is a program to maintain identical copies of files over  multiple
22       hosts.  It preserves the owner, group, mode, and mtime of files if pos‐
23       sible and can update programs that are executing.  Rdist reads commands
24       from  distfile  to direct the updating of files and/or directories.  If
25       distfile is `-', the standard input  is  used.   If  no  -f  option  is
26       present, the program looks first for `distfile', then `Distfile' to use
27       as the input.  If no names are specified on  the  command  line,  rdist
28       will  update all of the files and directories listed in distfile.  Oth‐
29       erwise, the argument is taken to be the name of a file to be updated or
30       the label of a command to execute. If label and file names conflict, it
31       is assumed to be a label.  These may be used together  to  update  spe‐
32       cific files using specific commands.
33
34       The  -c  option  forces rdist to interpret the remaining arguments as a
35       small distfile.  The equivalent distfile is as follows.
36
37            ( name ... ) -> [login@]host
38                 install   [dest] ;
39
40
41       The -Server option is recognized to provide partial backward compatible
42       support for older versions of rdist which used this option to put rdist
43       into server mode.  If rdist is started with the  -Server  command  line
44       option,  it  will attempt to exec (run) the old version of rdist.  This
45       option will only work if rdist was compiled with the  location  of  the
46       old  rdist  (the  path  /usr/bin/oldrdist is used on Red Hat linux) and
47       that program is available at run time.
48
49       Rdist can use either the rcmd(3) function  call  or  run  an  arbitrary
50       transport  program  such  as  rsh(1c)  to access each target host.  The
51       method used is selected at compile-time.  However, if the later  method
52       is used, the transport program can be specified at run-time on the com‐
53       mand line with the default being rsh(1c).  If  the  rsh(1c)  method  is
54       used  and  the  target host is the string localhost and the remote user
55       name is the same as the local user name, rdist will run the command
56
57              /bin/sh -c rdistd -S
58
59       Otherwise rdist run will run the command
60
61              rsh host -l remuser rdistd -S
62
63       where host is the name of the target host, remuser is the name  of  the
64       user  to make the connection as and, rdistd is the rdist server command
65       on the target host as shown below.  To use a  transport  program  other
66       than  rsh(1c)  use  the -P option.  Whatever transport program is used,
67       must be compatible with the above specified syntax for rsh(1c).  If the
68       transport  program is not, it should be wrapped in a shell script which
69       does understand this command line syntax and which  then  executes  the
70       real transport program.
71
72       Here's an example which uses ssh(1) as the transport:
73
74              rdist -P /usr/local/bin/ssh -f myDistfile
75
76
77       If  the  rcmd(3) method is used, then rdist makes the connection to the
78       target host itself and runs the rdistd server program as  shown  below.
79       The  default,  and preferred method, is to use rsh(1c) to make the con‐
80       nection to target hosts.  This allows rdist to  be  run  without  being
81       setuid to ``root''.
82
83       On each target host Rdist will attempt to run the command
84
85              rdistd -S
86
87       or
88
89              <rdistd path> -S
90
91       if  the  -p  option was specified.  If no -p option is included, or the
92       <rdistd path> is a simple filename, rdistd or  <rdistd  path>  must  be
93       somewhere in the $PATH of the user running rdist on the remote (target)
94       host.
95

OPTIONS

97       -A num Set the minimum number of free files (inodes)  on  a  filesystem
98              that must exist for rdist to update or install a file.
99
100       -a num Set  the minimum amount of free space (in bytes) on a filesystem
101              that must exist for rdist to update or install a file.
102
103       -D     Enable copious debugging messages.
104
105       -d var=value
106              Define var to have value.  This option  is  used  to  define  or
107              override variable definitions in the distfile.  Value can be the
108              empty string, one name, or a list of names surrounded by  paren‐
109              theses and separated by tabs and/or spaces.
110
111       -F     Do  not fork any child rdist processes.  All clients are updated
112              sequentially.
113
114       -f distfile
115              Set the name of the distfile to use to be distfile .   If  dist‐
116              file  is specified as ``-'' (dash) then read from standard input
117              (stdin).
118
119       -l logopts
120              Set local logging options.  See the section MESSAGE LOGGING  for
121              details on the syntax for logopts.
122
123       -L logopts
124              Set  remote  logging  options.  logopts is the same as for local
125              logging except the  values  are  passed  to  the  remote  server
126              (rdistd).   See  the  section MESSAGE LOGGING for details on the
127              syntax for logopts.
128
129       -M num Set the maximum number of  simultaneously  running  child  rdist
130              processes to num.  The default is 4.
131
132       -m machine
133              Limit  which  machines  are to be updated. Multiple -m arguments
134              can be given to limit updates to a subset of the hosts listed in
135              the distfile.
136
137       -n     Print the commands without executing them. This option is useful
138              for debugging distfile.
139
140       -odistopts
141              Specify the dist options to enable.  distopts is a  comma  sepa‐
142              rated  list of options which are listed below.  The valid values
143              for distopts are:
144
145              verify Verify that the files are up to date on  all  the  hosts.
146                     Any  files  that are out of date will be displayed but no
147                     files will be changed nor any mail sent.
148
149              whole  Whole mode. The whole file name is appended to the desti‐
150                     nation directory name.  Normally, only the last component
151                     of a name is used when renaming files.   This  will  pre‐
152                     serve  the  directory structure of the files being copied
153                     instead of flattening the directory structure. For  exam‐
154                     ple,  rdisting  a list of files such as /path/dir1/f1 and
155                     /path/dir2/f2   to   /tmp/dir    would    create    files
156                     /tmp/dir/path/dir1/f1  and  /tmp/dir/path/dir2/f2 instead
157                     of /tmp/dir/dir1/f1 and /tmp/dir/dir2/f2.
158
159              noexec Automatically  exclude  executable  files  that  are   in
160                     a.out(5) format from being checked or updated.
161
162              younger
163                     Younger  mode.  Files are normally updated if their mtime
164                     and size (see stat(2)) disagree. This option causes rdist
165                     not  to  update  files  that  are younger than the master
166                     copy.  This can be used to prevent newer copies on  other
167                     hosts  from being replaced.  A warning message is printed
168                     for files which are newer than the master copy.
169
170              compare
171                     Binary comparison. Perform a binary comparison and update
172                     files  if  they  differ  rather  than comparing dates and
173                     sizes.
174
175              follow Follow symbolic links. Copy the file that the link points
176                     to rather than the link itself.
177
178              ignlnks
179                     Ignore  unresolved  links.   Rdist  will  normally try to
180                     maintain the link structure of  files  being  transferred
181                     and warn the user if all the links cannot be found.
182
183              chknfs Do  not  check or update files on target host that reside
184                     on NFS filesystems.
185
186              chkreadonly
187                     Enable check on target host to see if a file resides on a
188                     read-only  filesystem.   If a file does, then no checking
189                     or updating of the file is attempted.
190
191              chksym If the target on the remote host is a symbolic link,  but
192                     is not on the master host, the remote target will be left
193                     a symbolic link.  This behavior is generally considered a
194                     bug  in  the original version of rdist, but is present to
195                     allow compatibility with older versions.
196
197              quiet  Quiet mode. Files that are being  modified  are  normally
198                     printed on standard output. This option suppresses this.
199
200              remove Remove extraneous files. If a directory is being updated,
201                     any files that exist on the remote host that do not exist
202                     in  the master directory are removed.  This is useful for
203                     maintaining truly identical copies of directories.
204
205              nochkowner
206                     Do not check user ownership of files that already  exist.
207                     The file ownership is only set when the file is updated.
208
209              nochkgroup
210                     Do not check group ownership of files that already exist.
211                     The file ownership is only set when the file is updated.
212
213              nochkmode
214                     Do not check file and directory  permission  modes.   The
215                     permission mode is only set when the file is updated.
216
217              nodescend
218                     Do  not  descend  into  a directory.  Normally rdist will
219                     recursively  check  directories.   If  this   option   is
220                     enabled,  then  any  files listed in the file list in the
221                     distfile  that  are  directories  are   not   recursively
222                     scanned.   Only the existence, ownership, and mode of the
223                     directory are checked.
224
225              numchkgroup
226                     Use the numeric group id (gid) to check  group  ownership
227                     instead of the group name.
228
229              numchkowner
230                     Use  the  numeric  user  id (uid) to check user ownership
231                     instead of the user name.
232
233              savetargets
234                     Save files that are updated  instead  of  removing  them.
235                     Any target file that is updates is first rename from file
236                     to file.OLD.
237
238              sparse Enable checking for sparse (aka wholely) files.   One  of
239                     the  most common types of sparse files are those produced
240                     by ndbm(3).  This option adds some additional  processing
241                     overhead  so it should only be enabled for targets likely
242                     to contain sparse files.
243
244       -p <rdistd-path>
245              Set the path where the rdistd server is searched for on the tar‐
246              get host.
247
248       -P <transport-path>
249              Set  the path to the transport command to be used.  This is nor‐
250              mally rsh(1c) but can be any other program - such  as  ssh(1)  -
251              which understands rsh(1c) command line syntax and which provides
252              an appropriate connection to the remote  host.   The  transport-
253              path  may  be  a colon seperated list of possible pathnames.  In
254              this case, the first component of the path  to  exist  is  used.
255              i.e.  /usr/ucb/rsh:/usr/bin/remsh , /usr/bsd/rsh.
256
257       -t timeout
258              Set  the  timeout  period (in seconds) for waiting for responses
259              from the remote rdist server.  The default is 900 seconds.
260
261       -V     Print version information and exit.
262

MESSAGE LOGGING

264       Rdist uses a collection of predefined message facilities that each con‐
265       tain a list of message types specifying which types of messages to send
266       to that facility.  The local  client  (rdist)  and  the  remote  server
267       (rdistd)  each maintain their own copy of what types of messages to log
268       to what facilities.
269
270       The -l logopts option to rdist tells rdist what logging options to  use
271       locally.   The  -L  logopts  option  to  rdist tells rdist what logging
272       options to pass to the remote rdistd server.
273
274       The form of logopts should be of form
275
276              facility=types:facility=types...
277
278       The valid facility names are:
279
280              stdout Messages to standard output.
281
282              file   Log to a file.  To specify the file name, use the  format
283                     ``file=filename=types''.                             e.g.
284                     ``file=/tmp/rdist.log=all,debug''.
285
286              syslog Use the syslogd(8) facility.
287
288              notify Use the internal rdist notify facility.  This facility is
289                     used in conjunction with the notify keyword in a distfile
290                     to  specify  what  messages  are  mailed  to  the  notify
291                     address.
292
293       types  should be a comma separated list of message types.  Each message
294       type specified enables that message level.  This  is  unlike  the  sys‐
295       log(3)  system facility which uses an ascending order scheme.  The fol‐
296       lowing are the valid types:
297
298              change Things  that  change.   This  includes  files  that   are
299                     installed or updated in some way.
300
301              info   General information.
302
303              notice General  info  about  things  that change.  This includes
304                     things like making directories which are needed in  order
305                     to  install  a specific target, but which are not explic‐
306                     itly specified in the distfile.
307
308              nerror Normal errors that are not fatal.
309
310              ferror Fatal errors.
311
312              warning
313                     Warnings about errors which are not as serious as  nerror
314                     type messages.
315
316              debug  Debugging information.
317
318              all    All but debug messages.
319
320       Here is a sample command line option:
321
322              -l stdout=all:syslog=change,notice:file=/tmp/rdist.log=all
323
324       This  entry  will  set local message logging to have all but debug mes‐
325       sages sent to standard output, change and notice messages will be  sent
326       to   syslog(3),   and   all  messages  will  be  written  to  the  file
327       /tmp/rdist.log.
328

DISTFILES

330       The distfile contains a sequence of entries that specify the  files  to
331       be  copied, the destination hosts, and what operations to perform to do
332       the updating. Each entry has one of the following formats.
333
334              <variable name> `=' <name list>
335              [ label: ] <source list> `->' <destination list> <command list>
336              [ label: ] <source list> `::' <time_stamp file> <command list>
337
338       The first format is used for defining variables.  The second format  is
339       used  for  distributing files to other hosts.  The third format is used
340       for making lists of files that have been changed since some given date.
341       The  source  list  specifies  a list of files and/or directories on the
342       local host which are to be used as the master  copy  for  distribution.
343       The  destination  list is the list of hosts to which these files are to
344       be copied.  Each file in the source list is added to a list of  changes
345       if  the  file is out of date on the host which is being updated (second
346       format) or the file is newer than the time stamp file (third format).
347
348       Labels are optional. They are used to identify a  command  for  partial
349       updates.
350
351       Newlines,  tabs,  and blanks are only used as separators and are other‐
352       wise ignored. Comments begin with `#' and end with a newline.
353
354       Variables to be expanded begin with `$' followed by one character or  a
355       name enclosed in curly braces (see the examples at the end).
356
357       The source and destination lists have the following format:
358
359            <name>
360       or
361            `(' <zero or more names separated by white-space> `)'
362
363       These  simple lists can be modified by using one level of set addition,
364       subtraction, or intersection like this:
365
366            list '-' list
367       or
368            list '+' list
369       or
370            list '&' list
371
372       If additional modifications are needed (e.g., ``all servers and  client
373       machines except for the OSF/1 machines'') then the list will have to be
374       explicitly constructed in steps using "temporary" variables.
375
376       The shell meta-characters `[', `]', `{', `}', `*', and `?'  are  recog‐
377       nized  and expanded (on the local host only) in the same way as csh(1).
378       They can be escaped with  a  backslash.   The  `~'  character  is  also
379       expanded in the same way as csh but is expanded separately on the local
380       and destination hosts.  When the -owhole option is  used  with  a  file
381       name  that  begins  with  `~',  everything except the home directory is
382       appended to the destination name.  File names which do not  begin  with
383       `/' or `~' use the destination user's home directory as the root direc‐
384       tory for the rest of the file name.
385
386       The command list consists of zero or more  commands  of  the  following
387       format.
388
389              `install'     <options>    opt_dest_name `;'
390              `notify'      <name list>  `;'
391              `except'      <name list>  `;'
392              `except_pat'  <pattern list>`;'
393              `special'     <name list>  string `;'
394              `cmdspecial'  <name list>  string `;'
395
396
397       The  install  command is used to copy out of date files and/or directo‐
398       ries.  Each source file is copied to each host in the destination list.
399       Directories  are  recursively copied in the same way.  Opt_dest_name is
400       an optional parameter to rename files.  If no install  command  appears
401       in  the  command  list  or  the  destination name is not specified, the
402       source file name is used.  Directories in the path name will be created
403       if  they  do  not  exist on the remote host.  The -o distopts option as
404       specified above under OPTIONS, has the same semantics as on the command
405       line except they only apply to the files in the source list.  The login
406       name used on the destination host is the same as the local host  unless
407       the destination name is of the format ``login@host".
408
409       The  notify  command is used to mail the list of files updated (and any
410       errors that may have occurred) to the listed names.  If no `@'  appears
411       in  the  name,  the  destination  host  is  appended to the name (e.g.,
412       name1@host, name2@host, ...).
413
414       The except command is used to update all of the  files  in  the  source
415       list except for the files listed in name list.  This is usually used to
416       copy everything in a directory except certain files.
417
418       The except_pat command is like the except command except  that  pattern
419       list  is a list of regular expressions (see ed(1) for details).  If one
420       of the patterns matches some string within a file name, that file  will
421       be  ignored.  Note that since `\' is a quote character, it must be dou‐
422       bled to become part of the regular expression.  Variables are  expanded
423       in  pattern  list  but  not shell file pattern matching characters.  To
424       include a `$', it must be escaped with `\'.
425
426       The special command is used to specify sh(1) commands that  are  to  be
427       executed  on  the remote host after the file in name list is updated or
428       installed.  If the name list is omitted then the shell commands will be
429       executed  for  every file updated or installed.  String starts and ends
430       with `"' and can cross multiple lines in distfile.   Multiple  commands
431       to  the shell should be separated by `;'.  Commands are executed in the
432       user's home directory on the host being updated.  The  special  command
433       can  be  used  to  rebuild private databases, etc.  after a program has
434       been updated.  The following environment variables  are  set  for  each
435       special command:
436
437       FILE   The full pathname of the local file that was just updated.
438
439       REMFILE
440              The full pathname of the remote file that was just updated.
441
442       BASEFILE
443              The basename of the remote file that was just updated.
444
445       The  cmdspecial command is similar to the special command, except it is
446       executed only when the entire command is  completed  instead  of  after
447       each  file  is updated.  The list of files is placed in the environment
448       variable $FILES.  Each file name  in  $FILES  is  separated  by  a  `:'
449       (colon).
450
451       If  a  hostname  ends in a ``+'' (plus sign), then the plus is stripped
452       off and NFS checks are disabled.  This is equivalent to  disabling  the
453       -ochknfs option just for this one host.
454
455       The following is a small example.
456
457              HOSTS = ( matisse root@arpa)
458
459              FILES = ( /bin /lib /usr/bin /usr/games
460                            /usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h}
461                            /usr/lib /usr/man/man? /usr/ucb /usr/local/rdist )
462
463              EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc
464                            sendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont )
465
466              ${FILES} -> ${HOSTS}
467                            install -oremove,chknfs ;
468                            except /usr/lib/${EXLIB} ;
469                            except /usr/games/lib ;
470                            special /usr/lib/sendmail "/usr/lib/sendmail -bz" ;
471
472              srcs:
473              /usr/src/bin -> arpa
474                            except_pat ( \\.o\$ /SCCS\$ ) ;
475
476              IMAGEN = (ips dviimp catdvi)
477
478              imagen:
479              /usr/local/${IMAGEN} -> arpa
480                            install /usr/local/lib ;
481                            notify ralph ;
482
483              ${FILES} :: stamp.cory
484                            notify root@cory ;
485
486

ENVIRONMENT

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

FILES

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

SEE ALSO

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

DIAGNOSTICS

NOTES

499       If the basename of a file  (the last component in the pathname) is ".",
500       then rdist assumes the remote (destination) name is a directory.   i.e.
501       /tmp/.  means that /tmp should be a directory on the remote host.
502
503       The following options are still recognized for backwards compatibility:
504
505              -v -N -O -q -b -r -R -s -w -y -h -i -x
506
507

BUGS

509       Source files must reside on the local host where rdist is executed.
510
511       Variable expansion only works for name lists; there should be a general
512       macro facility.
513
514       Rdist aborts on files which have a negative mtime (before Jan 1, 1970).
515
516       If a hardlinked file is listed more than once in the same target,  then
517       rdist will report missing links.  Only one instance of a link should be
518       listed in each target.
519
520
521
5224.3 Berkeley Distribution        June 13, 1998                        RDIST(1)
Impressum