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