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