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