1.\" Copyright (c) 1985, 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)rdist.1 6.11 (Berkeley) 7/27/91 33.\" 34.Dd July 27, 1991 35.Dt RDIST 1 36.Os BSD 4.3 37.Sh NAME 38.Nm rdist 39.Nd remote file distribution program 40.Sh SYNOPSIS 41.Nm rdist 42.Op Fl nqbRhivwy 43.Op Fl f Ar distfile 44.Op Fl d Ar var=value 45.Op Fl m host 46.Op Ar name ... 47.Nm rdist 48.Op Fl nqbRhivwy 49.Fl c 50.Ar name ... 51.Oo login@ Oc Ns Ar host Ns Op :dest 52.Sh DESCRIPTION 53.Nm Rdist 54is a program to maintain identical copies of files over multiple hosts. 55It preserves the owner, group, mode, and mtime of files if possible and 56can update programs that are executing. 57.Nm Rdist 58reads commands from 59.Ar distfile 60to direct the updating of files and/or directories. 61.Pp 62Options specific to the first SYNOPSIS form: 63.Pp 64.Bl -tag -width indent 65.It Fl 66If 67.Ar distfile 68is 69.Sq Fl , 70the standard input is used. 71.It Fl f Ar distfile 72Use the specified 73.Ar distfile. 74.El 75.Pp 76If either the 77.Fl f 78or 79.Sq Fl 80option is not specified, the program looks first for 81.Dq Pa distfile , 82then 83.Dq Pa Distfile 84to use as the input. 85If no names are specified on the command line, 86.Nm rdist 87will update all of the files and directories listed in 88.Ar distfile . 89Otherwise, the argument is taken to be the name of a file to be updated 90or the label of a command to execute. If label and file names conflict, 91it is assumed to be a label. 92These may be used together to update specific files 93using specific commands. 94.Pp 95Options specific to the second SYNOPSIS form: 96.Pp 97.Bl -tag -width Fl c 98.It Fl c 99Forces 100.Nm rdist 101to interpret the remaining arguments as a small 102.Ar distfile . 103.Pp 104The equivalent distfile is as follows. 105.Pp 106.Bd -filled -offset indent -compact 107.Pq Ar name ... 108.Li -> 109.Op Ar login@ 110.Ar host 111.Bd -filled -offset indent -compact 112.Li install 113.Op Ar dest ; 114.Ed 115.Ed 116.El 117.Pp 118Options common to both forms: 119.Pp 120.Bl -tag -width Ic 121.It Fl b 122Binary comparison. Perform a binary comparison and update files if they differ 123rather than comparing dates and sizes. 124.It Fl d Ar var=value 125Define 126.Ar var 127to have 128.Ar value . 129The 130.Fl d 131option is used to define or override variable definitions in the 132.Ar distfile . 133.Ar Value 134can be the empty string, one name, or a list of names surrounded by 135parentheses and separated by tabs and/or spaces. 136.It Fl h 137Follow symbolic links. Copy the file that the link points to rather than the 138link itself. 139.It Fl i 140Ignore unresolved links. 141.Nm Rdist 142will normally try to maintain the link structure of files being transfered 143and warn the user if all the links cannot be found. 144.It Fl m Ar host 145Limit which machines are to be updated. Multiple 146.Fl m 147arguments can be given to limit updates to a subset of the hosts listed the 148.Ar distfile . 149.It Fl n 150Print the commands without executing them. This option is 151useful for debugging 152.Ar distfile . 153.It Fl q 154Quiet mode. Files that are being modified are normally 155printed on standard output. The 156.Fl q 157option suppresses this. 158.It Fl R 159Remove extraneous files. If a directory is being updated, any files that exist 160on the remote host that do not exist in the master directory are removed. 161This is useful for maintaining truely identical copies of directories. 162.It Fl v 163Verify that the files are up to date on all the hosts. Any files 164that are out of date will be displayed but no files will be changed 165nor any mail sent. 166.It Fl w 167Whole mode. The whole file name is appended to the destination directory 168name. Normally, only the last component of a name is used when renaming files. 169This will preserve the directory structure of the files being 170copied instead of flattening the directory structure. For example, 171renaming a list of files such as ( dir1/f1 dir2/f2 ) to dir3 would create 172files dir3/dir1/f1 and dir3/dir2/f2 instead of dir3/f1 and dir3/f2. 173.It Fl y 174Younger mode. Files are normally updated if their 175.Ar mtime 176and 177.Ar size 178(see 179.Xr stat 2 ) 180disagree. The 181.Fl y 182option causes 183.Nm rdist 184not to update files that are younger than the master copy. 185This can be used 186to prevent newer copies on other hosts from being replaced. 187A warning message is printed for files which are newer than the master copy. 188.El 189.Pp 190.Ar Distfile 191contains a sequence of entries that specify the files 192to be copied, the destination hosts, and what operations to perform 193to do the updating. Each entry has one of the following formats. 194.Pp 195.Bd -literal -offset indent -compact 196<variable name> `=' <name list> 197[label:]<source list> `\->' <destination list> <command list> 198[label:]<source list> `::' <time_stamp file> <command list> 199.Ed 200.Pp 201The first format is used for defining variables. 202The second format is used for distributing files to other hosts. 203The third format is used for making lists of files that have been changed 204since some given date. 205The 206.Ar source list 207specifies a 208list of files and/or directories on the local host which are to be used 209as the master copy for distribution. 210The 211.Ar destination list 212is the list of hosts to which these files are to be 213copied. Each file in the source list is added to a list of changes 214if the file is out of date on the host which is being updated (second format) or 215the file is newer than the time stamp file (third format). 216.Pp 217Labels are optional. They are used to identify a command for partial updates. 218.Pp 219Newlines, tabs, and blanks are only used as separators and are 220otherwise ignored. Comments begin with `#' and end with a newline. 221.Pp 222Variables to be expanded begin with `$' followed by one character or 223a name enclosed in curly braces (see the examples at the end). 224.Pp 225The source and destination lists have the following format: 226.Bd -literal -offset indent 227<name> 228.Ed 229or 230.Bd -literal -offset indent -compact 231`(' <zero or more names separated by white-space> `)' 232.Ed 233.Pp 234The shell meta-characters `[', `]', `{', `}', `*', and `?' 235are recognized and expanded (on the local host only) in the same way as 236.Xr csh 1 . 237They can be escaped with a backslash. 238The `~' character is also expanded in the same way as 239.Xr csh 1 240but is expanded separately on the local and destination hosts. 241When the 242.Fl w 243option is used with a file name that begins with `~', everything except the 244home directory is appended to the destination name. 245File names which do not begin with `/' or `~' use the destination user's 246home directory as the root directory for the rest of the file name. 247.Pp 248The command list consists of zero or more commands of the following 249format. 250.Bd -ragged -offset indent -compact 251.Bl -column except_patx pattern\ listx 252.It `install' <options> opt_dest_name `;' 253.It `notify' <name list> `;' 254.It `except' <name list> `;' 255.It `except_pat' <pattern list> `;' 256.It `special' <name list> string `;' 257.El 258.Ed 259.Pp 260The 261.Ic install 262command is used to copy out of date files and/or directories. 263Each source file is copied to each host in the destination list. 264Directories are recursively copied in the same way. 265.Ar Opt_dest_name 266is an optional parameter to rename files. 267If no 268.Ic install 269command appears in the command list or 270the destination name is not specified, 271the source file name is used. 272Directories in the path name will be created if they 273do not exist on the remote host. 274To help prevent disasters, a non-empty directory on a target host will 275never be replaced with a regular file or a symbolic link. 276However, under the `\-R' option a non-empty directory will be removed 277if the corresponding filename is completely absent on the master host. 278The 279.Ar options 280are `\-R', `\-h', `\-i', `\-v', `\-w', `\-y', and `\-b' 281and have the same semantics as 282options on the command line except they only apply to the files 283in the source list. 284The login name used on the destination host is the same as the local host 285unless the destination name is of the format ``login@host". 286.Pp 287The 288.Ic notify 289command is used to mail the list of files updated (and any errors 290that may have occured) to the listed names. 291If no `@' appears in the name, the destination host is appended to 292the name 293(e.g., name1@host, name2@host, ...). 294.Pp 295The 296.Ic except 297command is used to update all of the files in the source list 298.Ic except 299for the files listed in 300.Ar name list . 301This is usually used to copy everything in a directory except certain files. 302.Pp 303The 304.Ic except_pat 305command is like the 306.Ic except 307command except that 308.Ar pattern list 309is a list of regular expressions 310(see 311.Xr ed 1 312for details). 313If one of the patterns matches some string within a file name, that file will 314be ignored. 315Note that since `\e' is a quote character, it must be doubled to become 316part of the regular expression. Variables are expanded in 317.Ar pattern list 318but not shell file pattern matching characters. To include a `$', it 319must be escaped with `\e'. 320.Pp 321The 322.Ic special 323command is used to specify 324.Xr sh 1 325commands that are to be executed on the 326remote host after the file in 327.Ar name list 328is updated or installed. 329If the 330.Ar name list 331is omitted then the shell commands will be executed 332for every file updated or installed. The shell variable `FILE' is set 333to the current filename before executing the commands in 334.Ar string . 335.Ar String 336starts and ends with `"' and can cross multiple lines in 337.Ar distfile . 338Multiple commands to the shell should be separated by `;'. 339Commands are executed in the user's home directory on the host 340being updated. 341The 342.Ar special 343command can be used to rebuild private databases, etc. 344after a program has been updated. 345.Pp 346The following is a small example: 347.Bd -literal -offset indent 348HOSTS = ( matisse root@arpa ) 349 350FILES = ( /bin /lib /usr/bin /usr/games 351\t/usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h} 352\t/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) 353 354EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc 355\tsendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont ) 356 357${FILES} -> ${HOSTS} 358\tinstall -R ; 359\texcept /usr/lib/${EXLIB} ; 360\texcept /usr/games/lib ; 361\tspecial /usr/lib/sendmail "/usr/lib/sendmail -bz" ; 362 363srcs: 364/usr/src/bin -> arpa 365\texcept_pat ( \e\e.o\e$ /SCCS\e$ ) ; 366 367IMAGEN = (ips dviimp catdvi) 368 369imagen: 370/usr/local/${IMAGEN} -> arpa 371\tinstall /usr/local/lib ; 372\tnotify ralph ; 373 374${FILES} :: stamp.cory 375\tnotify root@cory ; 376.Ed 377.Sh FILES 378.Bl -tag -width /tmp/rdist* -compact 379.It Pa distfile 380input command file 381.It Pa /tmp/rdist* 382temporary file for update lists 383.El 384.Sh SEE ALSO 385.Xr sh 1 , 386.Xr csh 1 , 387.Xr stat 2 388.Sh HISTORY 389The 390.Nm rdist 391command appeared in 392.Bx 4.3 . 393.Sh DIAGNOSTICS 394A complaint about mismatch of rdist version numbers may really stem 395from some problem with starting your shell, e.g., you are in too many groups. 396.Sh BUGS 397Source files must reside on the local host where 398.Nm rdist 399is executed. 400.Pp 401There is no easy way to have a special command executed after all files 402in a directory have been updated. 403.Pp 404Variable expansion only works for name lists; there should be a general macro 405facility. 406.Pp 407.Nm Rdist 408aborts on files which have a negative mtime (before Jan 1, 1970). 409.Pp 410There should be a `force' option to allow replacement of non-empty directories 411by regular files or symlinks. A means of updating file modes and owners 412of otherwise identical files is also needed. 413