Annotation of src/usr.bin/rdist/rdist.1, Revision 1.14
1.14 ! millert 1: .\" $OpenBSD: rdist.1,v 1.13 2002/05/09 19:19:33 millert Exp $
1.2 dm 2: .\"
3: .\" Copyright (c) 1983 Regents of the University of California.
4: .\" All rights reserved.
1.1 deraadt 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: .\"
1.6 millert 34: .\" $From: rdist.man,v 6.34 1996/01/29 22:37:19 mcooper Exp $
1.2 dm 35: .\" @(#)rdist.1 6.6 (Berkeley) 5/13/86
1.1 deraadt 36: .\"
1.14 ! millert 37: .Dd May 9, 2002
! 38: .Dt RDIST 1
! 39: .Os
! 40: .Sh NAME
! 41: .Nm rdist
! 42: .Nd remote file distribution client program
! 43: .Sh SYNOPSIS
! 44: .Nm rdist
! 45: .Op Fl DFn
! 46: .Op Fl A Ar num
! 47: .Op Fl a Ar num
! 48: .Op Fl d Ar var=value
! 49: .Op Fl l Ar <local logopts>
! 50: .Op Fl L Ar <remote logopts>
! 51: .Op Fl f Ar distfile
! 52: .Op Fl M Ar maxproc
! 53: .Op Fl m Ar host
! 54: .Op Fl o Ar distopts
! 55: .Op Fl t Ar timeout
! 56: .Op Fl p Ar <rdistd-path>
! 57: .Op Fl P Ar <rsh-path>
! 58: .Op Ar name ...
! 59: .Pp
! 60: .Nm rdist
! 61: .Fl DFn
! 62: .Fl c Ar name ...
! 63: .Ar [login@]host[:dest]
! 64: .Pp
! 65: .Nm rdist
! 66: .Fl Server
! 67: .Pp
! 68: .Nm rdist
! 69: .Fl V
! 70: .Sh DESCRIPTION
! 71: .Nm
1.8 aaron 72: is a program to maintain identical copies of files over multiple hosts.
1.1 deraadt 73: It preserves the owner, group, mode, and mtime of files if possible and
74: can update programs that are executing.
1.14 ! millert 75: .Nm
1.1 deraadt 76: reads commands from
1.14 ! millert 77: .Pa distfile
1.1 deraadt 78: to direct the updating of files and/or directories.
79: If
1.14 ! millert 80: .Pa distfile
! 81: is
! 82: .Sq - ,
! 83: the standard input is used.
1.2 dm 84: If no
1.14 ! millert 85: .Fl f
! 86: option is present, the program looks first for
! 87: .Pa distfile ,
! 88: then
! 89: .Pa Distfile
! 90: to use as the input.
1.1 deraadt 91: If no names are specified on the command line,
1.14 ! millert 92: .Nm
1.1 deraadt 93: will update all of the files and directories listed in
1.14 ! millert 94: .Pa distfile .
1.1 deraadt 95: Otherwise, the argument is taken to be the name of a file to be updated
1.14 ! millert 96: or the label of a command to execute.
! 97: If label and file names conflict, it is assumed to be a label.
! 98: These may be used together to update specific files using specific commands.
! 99: .Pp
1.2 dm 100: The
1.14 ! millert 101: .Fl c
1.2 dm 102: option forces
1.14 ! millert 103: .Nm
1.1 deraadt 104: to interpret the remaining arguments as a small
1.14 ! millert 105: .Pa distfile .
1.1 deraadt 106: The equivalent distfile is as follows.
1.14 ! millert 107: .Bd -literal -offset indent
1.2 dm 108: ( \fIname\fP ... ) -> [\fIlogin\fP@]\fIhost\fP
1.14 ! millert 109: install [\fIdest\fP] ;
! 110: .Ed
! 111: .Pp
1.2 dm 112: The
1.14 ! millert 113: .Fl Server
1.2 dm 114: option is recognized to provide partial backward compatible support
115: for older versions of
1.14 ! millert 116: .Nm
1.2 dm 117: which used this option to put
1.14 ! millert 118: .Nm
1.2 dm 119: into server mode.
120: If
1.14 ! millert 121: .Nm
1.8 aaron 122: is started with the
1.14 ! millert 123: .Fl Server
1.2 dm 124: command line option, it will attempt to exec (run) the old version of
1.14 ! millert 125: .Nm rdist ,
! 126: .Pa /usr/bin/oldrdist .
! 127: .Pp
! 128: .Nm
1.13 millert 129: uses a remote shell command to access each target host.
130: By default,
1.14 ! millert 131: .Xr ssh 1
1.13 millert 132: is used, unless overridden by the
1.14 ! millert 133: .Fl P
! 134: option or the
! 135: .Ev RSH
! 136: environment variable.
1.13 millert 137: If the target host is the string
1.14 ! millert 138: .Em localhost
! 139: and the remote user name is the same as the local user name,
! 140: .Nm
1.2 dm 141: will run the command
1.14 ! millert 142: .Bd -literal -offset indent
! 143: /bin/sh -c rdistd -S
! 144: .Ed
! 145: .Pp
! 146: Otherwise,
! 147: .Nm
1.2 dm 148: run will run the command
1.14 ! millert 149: .Bd -literal -offset indent
1.13 millert 150: \fBssh \fIhost\fB -l \fIremuser \fBrdistd -S\fR
1.14 ! millert 151: .Ed
! 152: .Pp
1.8 aaron 153: where
1.14 ! millert 154: .Em host
1.2 dm 155: is the name of the target host,
1.14 ! millert 156: .Em remuser
1.2 dm 157: is the name of the user to make the connection as and,
1.14 ! millert 158: .Em rdistd
1.2 dm 159: is the rdist server command on the target host as shown below.
1.14 ! millert 160: .Pp
1.2 dm 161: On each target host
1.14 ! millert 162: .Nm
1.2 dm 163: will attempt to run the command
1.14 ! millert 164: .Bd -literal -offset indent
! 165: rdistd -S
! 166: .Ed
! 167: .Pp
1.2 dm 168: or
1.14 ! millert 169: .Bd -literal -offset indent
! 170: <rdistd path> -S
! 171: .Ed
! 172: .Pp
1.2 dm 173: if the
1.14 ! millert 174: .Fl p
1.2 dm 175: option was specified.
176: If no
1.14 ! millert 177: .Fl p
! 178: option is included, or the
! 179: .Ar <rdistd path>
1.2 dm 180: is a simple filename,
1.14 ! millert 181: .Em rdistd
1.2 dm 182: or
1.14 ! millert 183: .Em <rdistd path>
1.8 aaron 184: must be somewhere in the
1.14 ! millert 185: .Ev PATH
1.2 dm 186: of the user running
1.14 ! millert 187: .Nm
1.2 dm 188: on the remote (target) host.
1.14 ! millert 189: .Pp
! 190: The options are as follows:
! 191: .Bl -tag -width Ds
! 192: .It Fl A Ar num
1.2 dm 193: Set the minimum number of free files (inodes) on a filesystem that must exist
1.8 aaron 194: for
1.14 ! millert 195: .Nm
1.2 dm 196: to update or install a file.
1.14 ! millert 197: .It Fl a Ar num
1.2 dm 198: Set the minimum amount of free space (in bytes) on a filesystem that must exist
1.8 aaron 199: for
1.14 ! millert 200: .Nm
1.2 dm 201: to update or install a file.
1.14 ! millert 202: .It Fl D
1.2 dm 203: Enable copious debugging messages.
1.14 ! millert 204: .It Fl d Ar var=value
1.1 deraadt 205: Define
1.14 ! millert 206: .Ar var
1.1 deraadt 207: to have
1.14 ! millert 208: .Ar value .
1.2 dm 209: This
1.1 deraadt 210: option is used to define or override variable definitions in the
1.14 ! millert 211: .Pa distfile .
! 212: .Ar value
1.1 deraadt 213: can be the empty string, one name, or a list of names surrounded by
214: parentheses and separated by tabs and/or spaces.
1.14 ! millert 215: .It Fl F
1.8 aaron 216: Do not fork any child
1.14 ! millert 217: .Nm
1.2 dm 218: processes.
219: All clients are updated sequentially.
1.14 ! millert 220: .It Fl f Ar distfile
1.2 dm 221: Set the name of the distfile to use to be
1.14 ! millert 222: .Ar distfile .
1.8 aaron 223: If
1.14 ! millert 224: .Ar distfile
1.2 dm 225: is specified as
1.14 ! millert 226: .Dq -
! 227: (dash) then read from standard input (stdin).
! 228: .It Fl l Ar logopts
1.2 dm 229: Set local logging options.
1.8 aaron 230: See the section
1.14 ! millert 231: .Sy MESSAGE LOGGING
1.2 dm 232: for details on the syntax for
1.14 ! millert 233: .Ar logopts .
! 234: .It Fl L Ar logopts
1.2 dm 235: Set remote logging options.
1.14 ! millert 236: .Ar logopts
! 237: is the same as for local logging except the values are passed to the remote
1.2 dm 238: server (\fIrdistd\fR).
1.8 aaron 239: See the section
1.14 ! millert 240: .Sy MESSAGE LOGGING
1.2 dm 241: for details on the syntax for
1.14 ! millert 242: .Ar logopts .
! 243: .It Fl M Ar num
! 244: Set the maximum number of simultaneously running child
! 245: .Nm
1.2 dm 246: processes to
1.14 ! millert 247: .Ar num .
1.2 dm 248: The default is 4.
1.14 ! millert 249: .It Fl m Ar machine
1.1 deraadt 250: Limit which machines are to be updated. Multiple
1.14 ! millert 251: .Fl m
1.1 deraadt 252: arguments can be given to limit updates to a subset of the hosts listed in the
1.14 ! millert 253: .Pa distfile .
! 254: .It Fl n
! 255: Print the commands without executing them.
! 256: This option is useful for debugging a
! 257: .Pa distfile .
! 258: .It Fl o Ns Ar distopts
1.2 dm 259: Specify the dist options to enable.
1.14 ! millert 260: .Ar distopts
1.2 dm 261: is a comma separated list of options which are listed below.
262: The valid values for
1.14 ! millert 263: .Ar distopts
1.2 dm 264: are:
1.14 ! millert 265: .Bl -tag -width Ds
! 266: .It Sy verify
! 267: Verify that the files are up to date on all the hosts.
! 268: Any files that are out of date will be displayed but no files will be
! 269: changed nor will any mail be sent.
! 270: .It Sy whole
! 271: Whole mode.
! 272: The whole file name is appended to the destination directory name.
! 273: Normally, only the last component of a name is used when renaming files.
1.1 deraadt 274: This will preserve the directory structure of the files being
1.14 ! millert 275: copied instead of flattening the directory structure.
! 276: For example, rdisting a list of files such as
! 277: .Pa /path/dir1/f1
1.2 dm 278: and
1.14 ! millert 279: .Pa /path/dir2/f2
1.8 aaron 280: to
1.14 ! millert 281: .Pa /tmp/dir
! 282: would create files
! 283: .Pa /tmp/dir/path/dir1/f1
1.8 aaron 284: and
1.14 ! millert 285: .Pa /tmp/dir/path/dir2/f2
1.8 aaron 286: instead of
1.14 ! millert 287: .Pa /tmp/dir/dir1/f1
1.8 aaron 288: and
1.14 ! millert 289: .Pa /tmp/dir/dir2/f2 .
! 290: .It Sy noexec
1.8 aaron 291: Automatically exclude executable files that are in
1.14 ! millert 292: .Xr a.out 5
1.8 aaron 293: format from being checked or updated.
1.14 ! millert 294: .It Sy younger
! 295: Younger mode.
! 296: Files are normally updated if their
! 297: .Em mtime
1.1 deraadt 298: and
1.14 ! millert 299: .Em size
1.1 deraadt 300: (see
1.14 ! millert 301: .Xr stat 2 )
! 302: disagree.
! 303: This option causes
! 304: .Nm
1.1 deraadt 305: not to update files that are younger than the master copy.
1.14 ! millert 306: This can be used to prevent newer copies on other hosts from being replaced.
1.1 deraadt 307: A warning message is printed for files which are newer than the master copy.
1.14 ! millert 308: .It Sy compare
! 309: Binary comparison.
! 310: Perform a binary comparison and update files if they differ rather than
! 311: comparing dates and sizes.
! 312: .It Sy follow
! 313: Follow symbolic links.
! 314: Copy the file that the link points to rather than the link itself.
! 315: .It Sy ignlnks
1.2 dm 316: Ignore unresolved links.
1.14 ! millert 317: .Nm
1.2 dm 318: will normally try to maintain the link structure of files being transferred
319: and warn the user if all the links cannot be found.
1.14 ! millert 320: .It Sy chknfs
! 321: Do not check or update files on target host that reside on NFS filesystems.
! 322: .It Sy chkreadonly
! 323: Enable check on target host to see if a file resides on a read-only filesystem.
1.2 dm 324: If a file does, then no checking or updating of the file is attempted.
1.14 ! millert 325: .It Sy chksym
1.2 dm 326: If the target on the remote host is a symbolic link, but is not on the
327: master host, the remote target will be left a symbolic link.
328: This behavior is generally considered a bug in the original version of
1.14 ! millert 329: .Nm rdist ,
1.2 dm 330: but is present to allow compatibility with older versions.
1.14 ! millert 331: .It Sy quiet
! 332: Quiet mode.
! 333: Files that are being modified are normally printed on standard output.
! 334: This option suppresses that.
! 335: .It Sy remove
! 336: Remove extraneous files.
! 337: If a directory is being updated, any files that exist on the remote host
! 338: that do not exist in the master directory are removed.
1.2 dm 339: This is useful for maintaining truly identical copies of directories.
1.14 ! millert 340: .It Sy nochkowner
1.2 dm 341: Do not check user ownership of files that already exist.
342: The file ownership is only set when the file is updated.
1.14 ! millert 343: .It Sy nochkgroup
1.2 dm 344: Do not check group ownership of files that already exist.
345: The file ownership is only set when the file is updated.
1.14 ! millert 346: .It Sy nochkmode
1.2 dm 347: Do not check file and directory permission modes.
348: The permission mode is only set when the file is updated.
1.14 ! millert 349: .It Sy nodescend
1.2 dm 350: Do not descend into a directory.
1.14 ! millert 351: Normally,
! 352: .Nm
1.2 dm 353: will recursively check directories.
1.14 ! millert 354: If this option is enabled, then any files listed in the file list in the
! 355: distfile that are directories are not recursively scanned.
1.2 dm 356: Only the existence, ownership, and mode of the directory are checked.
1.14 ! millert 357: .It Sy numchkgroup
1.9 aaron 358: Use the numeric group ID (GID) to check group ownership instead of
1.2 dm 359: the group name.
1.14 ! millert 360: .It Sy numchkowner
1.9 aaron 361: Use the numeric user ID (UID) to check user ownership instead of
1.2 dm 362: the user name.
1.14 ! millert 363: .It Sy savetargets
1.2 dm 364: Save files that are updated instead of removing them.
365: Any target file that is updates is first rename from
1.14 ! millert 366: .Pa file
1.2 dm 367: to
1.14 ! millert 368: .Pa file.OLD .
! 369: .It Sy sparse
! 370: Enable checking for sparse (aka
! 371: .Dq wholely )
! 372: files.
! 373: One of the most common types of sparse files are those produced by
! 374: .Xr db 3 .
1.3 dm 375: This option adds some additional processing overhead so it should
376: only be enabled for targets likely to contain sparse files.
1.14 ! millert 377: .El
! 378: .It Fl p Ar <rdistd-path>
1.2 dm 379: Set the path where the rdistd server is searched for on the target host.
1.14 ! millert 380: .It Fl P Ar <rsh-path>
! 381: Set the path to the remote shell command.
1.2 dm 382: The
383: .I rsh-path
1.7 deraadt 384: may be a colon separated list of possible pathnames.
1.2 dm 385: In this case, the first component of the path to exist is used.
1.14 ! millert 386: e.g.,
! 387: .Pa "/usr/bin/ssh:/usr/bin/rsh" ,
! 388: .Pa /usr/bin/ssh .
! 389: .It Fl t Ar timeout
1.8 aaron 390: Set the timeout period (in seconds) for waiting for responses from the remote
1.14 ! millert 391: .Nm
1.2 dm 392: server.
393: The default is 900 seconds.
1.14 ! millert 394: .It Fl V
1.2 dm 395: Print version information and exit.
1.14 ! millert 396: .Sh MESSAGE LOGGING
! 397: .Nm
1.2 dm 398: uses a collection of predefined message
1.14 ! millert 399: .Em facilities
1.2 dm 400: that each contain a list of message
1.14 ! millert 401: .Sy types
1.8 aaron 402: specifying which types of messages to send to that
1.14 ! millert 403: .Em facility .
1.2 dm 404: The local client (\fIrdist\fR) and the remote server (\fIrdistd\fR) each
1.14 ! millert 405: maintain their own copy of what types of messages to log to what facilities.
! 406: .Pp
1.8 aaron 407: The
1.14 ! millert 408: .Fl l
! 409: .Em logopts
1.2 dm 410: option to
1.14 ! millert 411: .Nm
1.2 dm 412: tells
1.14 ! millert 413: .Nm
1.2 dm 414: what logging options to use locally.
1.8 aaron 415: The
1.14 ! millert 416: .Fl L
! 417: .Em logopts
1.2 dm 418: option to
1.14 ! millert 419: .Nm
1.2 dm 420: tells
1.14 ! millert 421: .Nm
1.2 dm 422: what logging options to pass to the remote
1.14 ! millert 423: .Em rdistd
1.2 dm 424: server.
1.14 ! millert 425: .Pp
! 426: .Em logopts
! 427: should be of the form
! 428: .Bd -literal -offset indent
1.2 dm 429: \fIfacility\fB=\fItypes\fB:\fIfacility\fB=\fItypes...
1.14 ! millert 430: .Ed
! 431: .Pp
1.2 dm 432: The valid facility names are:
1.14 ! millert 433: .Bl -tag -width Ds
! 434: .It Sy stdout
1.2 dm 435: Messages to standard output.
1.14 ! millert 436: .It Sy file
! 437: Log to a file.
! 438: To specify the file name, use the format
! 439: .Dq \fBfile=\fIfilename\fB=\fItypes\fR .
1.12 aaron 440: e.g.,
1.14 ! millert 441: .Dq \fBfile=\fI/tmp/rdist.log\fB=\fIall,debug\fR .
! 442: .It Sy syslog
1.8 aaron 443: Use the
1.14 ! millert 444: .Xr syslogd 8
1.2 dm 445: facility.
1.14 ! millert 446: .It Sy notify
1.2 dm 447: Use the internal
1.14 ! millert 448: .Nm
! 449: .Sy notify
1.2 dm 450: facility.
451: This facility is used in conjunction with the
1.14 ! millert 452: .Sy notify
1.8 aaron 453: keyword in a
1.14 ! millert 454: .Pa distfile
1.2 dm 455: to specify what messages are mailed to the
1.14 ! millert 456: .Sy notify
1.2 dm 457: address.
1.14 ! millert 458: .El
! 459: .Pp
! 460: .Em types
! 461: should be a comma separated list of message types.
! 462: Each message type specified enables that message level.
! 463: This is unlike the
! 464: .Xr syslog 3
1.2 dm 465: system facility which uses an ascending order scheme.
1.14 ! millert 466: The following are the valid
! 467: .Em types:
! 468: .Bl -tag -width Ds
! 469: .It Sy change
1.2 dm 470: Things that change.
471: This includes files that are installed or updated in some way.
1.14 ! millert 472: .It Sy info
1.2 dm 473: General information.
1.14 ! millert 474: .It Sy notice
1.2 dm 475: General info about things that change.
476: This includes things like making directories which are needed in order
1.14 ! millert 477: to install a specific target, but which are not explicitly specified in the
! 478: .Pa distfile.
! 479: .It Sy nerror
1.2 dm 480: Normal errors that are not fatal.
1.14 ! millert 481: .It Sy ferror
1.2 dm 482: Fatal errors.
1.14 ! millert 483: .It Sy warning
1.2 dm 484: Warnings about errors which are not as serious as
1.14 ! millert 485: .Sy nerror
1.2 dm 486: type messages.
1.14 ! millert 487: .It Sy debug
1.2 dm 488: Debugging information.
1.14 ! millert 489: .It Sy all
1.2 dm 490: All but debug messages.
1.14 ! millert 491: .El
! 492: .Pp
1.2 dm 493: Here is a sample command line option:
1.14 ! millert 494: .Bd -literal -offset indent
! 495: -l stdout=all:syslog=change,notice:file=/tmp/rdist.log=all
! 496: .Ed
! 497: .Pp
1.2 dm 498: This entry will set local message logging to have all but debug
499: messages sent to standard output, change and notice messages will
1.8 aaron 500: be sent to
1.14 ! millert 501: .Xr syslog 3 ,
1.2 dm 502: and all messages will be written to the file
1.14 ! millert 503: .Pa /tmp/rdist.log .
! 504: .Sh DISTFILES
1.2 dm 505: The
1.14 ! millert 506: .Pa distfile
1.1 deraadt 507: contains a sequence of entries that specify the files
508: to be copied, the destination hosts, and what operations to perform
509: to do the updating. Each entry has one of the following formats.
1.14 ! millert 510: .Bd -literal -offset indent
1.1 deraadt 511: <variable name> `=' <name list>
1.2 dm 512: [ label: ] <source list> `\->' <destination list> <command list>
513: [ label: ] <source list> `::' <time_stamp file> <command list>
1.14 ! millert 514: .Ed
! 515: .Pp
1.1 deraadt 516: The first format is used for defining variables.
517: The second format is used for distributing files to other hosts.
518: The third format is used for making lists of files that have been changed
519: since some given date.
1.14 ! millert 520: The
! 521: .Em source list
! 522: specifies a list of files and/or directories on the local host which are to
! 523: be used as the master copy for distribution.
! 524: The
! 525: .Em destination list
! 526: is the list of hosts to which these files are to be copied.
! 527: Each file in the source list is added to a list of changes if the file
! 528: is out of date on the host which is being updated (second format) or
1.1 deraadt 529: the file is newer than the time stamp file (third format).
1.14 ! millert 530: .Pp
! 531: Labels are optional.
! 532: They are used to identify a command for partial updates.
! 533: .Pp
1.1 deraadt 534: Newlines, tabs, and blanks are only used as separators and are
1.14 ! millert 535: otherwise ignored.
! 536: Comments begin with
! 537: .Sq #
! 538: and end with a newline.
! 539: .Pp
! 540: Variables to be expanded begin with
! 541: .Sq $
! 542: followed by one character or a name enclosed in curly braces
! 543: (see the examples at the end).
! 544: .Pp
1.1 deraadt 545: The source and destination lists have the following format:
1.14 ! millert 546: .Bd -literal -offset indent
1.1 deraadt 547: <name>
1.14 ! millert 548: .Ed
1.1 deraadt 549: or
1.14 ! millert 550: .Bd -literal -compact -offset indent
1.10 aaron 551: `(' <zero or more names separated by whitespace> `)'
1.14 ! millert 552: .Ed
! 553: .Pp
1.2 dm 554: These simple lists can be modified by using one level of set addition,
555: subtraction, or intersection like this:
1.14 ! millert 556: .Bd -literal -offset indent
1.2 dm 557: list '-' list
1.14 ! millert 558: .Ed
1.2 dm 559: or
1.14 ! millert 560: .Bd -literal -compact -offset indent
1.2 dm 561: list '+' list
1.14 ! millert 562: .Ed
1.2 dm 563: or
1.14 ! millert 564: .Bd -literal -compact -offset indent
1.2 dm 565: list '&' list
1.14 ! millert 566: .Ed
! 567: .Pp
! 568: If additional modifications are needed (e.g.,
! 569: .Do
! 570: all servers and client machines except for the OSF/1 machines
! 571: .Dc )
! 572: then the list will have to be explicitly constructed in steps using
! 573: .Dq temporary
! 574: variables.
! 575: .Pp
1.1 deraadt 576: The shell meta-characters `[', `]', `{', `}', `*', and `?'
577: are recognized and expanded (on the local host only) in the same way as
1.14 ! millert 578: .Xr csh 1 .
1.1 deraadt 579: They can be escaped with a backslash.
580: The `~' character is also expanded in the same way as
1.14 ! millert 581: .Xr csh 1
1.1 deraadt 582: but is expanded separately on the local and destination hosts.
583: When the
1.14 ! millert 584: .Fl o Ns Ar whole
1.1 deraadt 585: option is used with a file name that begins with `~', everything except the
586: home directory is appended to the destination name.
587: File names which do not begin with `/' or `~' use the destination user's
588: home directory as the root directory for the rest of the file name.
1.14 ! millert 589: .Pp
1.1 deraadt 590: The command list consists of zero or more commands of the following
591: format.
1.14 ! millert 592: .Bl -column "except_pat" "<pattern list>" "opt_dest_name" ";" -offset indent
! 593: .It `install' Ta <options> Ta opt_dest_name Ta `;'
! 594: .It `notify' Ta <name list> Ta "" Ta `;'
! 595: .It `except' Ta <name list> Ta "" Ta `;'
! 596: .It `except_pat' Ta <pattern list> Ta "" Ta `;'
! 597: .It `special' Ta <name list> Ta string Ta `;'
! 598: .It `cmdspecial' Ta <name list> Ta string Ta `;'
! 599: .El
! 600: .Pp
1.1 deraadt 601: The
1.14 ! millert 602: .Em install
1.1 deraadt 603: command is used to copy out of date files and/or directories.
604: Each source file is copied to each host in the destination list.
605: Directories are recursively copied in the same way.
1.14 ! millert 606: .Em opt_dest_name
1.1 deraadt 607: is an optional parameter to rename files.
608: If no
1.14 ! millert 609: .Em install
! 610: command appears in the command list or the destination name is not specified,
1.1 deraadt 611: the source file name is used.
612: Directories in the path name will be created if they
613: do not exist on the remote host.
1.2 dm 614: The
1.14 ! millert 615: .Fl o Ns Ar distopts
! 616: option as specified above has the same semantics as
! 617: on the command line except
! 618: .Ar distopts
! 619: only apply to the files in the source list.
1.1 deraadt 620: The login name used on the destination host is the same as the local host
1.14 ! millert 621: unless the destination name is of the format
! 622: .Dq login@host .
! 623: .Pp
1.1 deraadt 624: The
1.14 ! millert 625: .Em notify
1.1 deraadt 626: command is used to mail the list of files updated (and any errors
627: that may have occurred) to the listed names.
628: If no `@' appears in the name, the destination host is appended to
629: the name
630: (e.g., name1@host, name2@host, ...).
1.14 ! millert 631: .Pp
1.1 deraadt 632: The
1.14 ! millert 633: .Em except
1.1 deraadt 634: command is used to update all of the files in the source list
1.14 ! millert 635: .Sy except
! 636: for the files listed in
! 637: .Em name list .
1.1 deraadt 638: This is usually used to copy everything in a directory except certain files.
1.14 ! millert 639: .Pp
1.1 deraadt 640: The
1.14 ! millert 641: .Em except_pat
1.1 deraadt 642: command is like the
1.14 ! millert 643: .Em except
! 644: command except that
! 645: .Em pattern list
! 646: is a list of regular expressions
1.1 deraadt 647: (see
1.14 ! millert 648: .Xr ed 1
1.1 deraadt 649: for details).
650: If one of the patterns matches some string within a file name, that file will
651: be ignored.
652: Note that since `\e' is a quote character, it must be doubled to become
1.14 ! millert 653: part of the regular expression.
! 654: Variables are expanded in
! 655: .Em pattern list
! 656: but not shell file pattern matching characters.
! 657: To include a `$', it must be escaped with `\e'.
! 658: .br
! 659: .Pp
1.1 deraadt 660: The
1.14 ! millert 661: .Em special
1.1 deraadt 662: command is used to specify
1.14 ! millert 663: .Xr sh 1
! 664: commands that are to be executed on the remote host after the file in
! 665: .Em name list
! 666: is updated or installed.
! 667: If the
! 668: .Em name list
! 669: is omitted then the shell commands will be executed for every file
! 670: updated or installed.
! 671: .Em string
1.1 deraadt 672: starts and ends with `"' and can cross multiple lines in
1.14 ! millert 673: .Pa distfile.
1.1 deraadt 674: Multiple commands to the shell should be separated by `;'.
675: Commands are executed in the user's home directory on the host
676: being updated.
677: The
1.14 ! millert 678: .Em special
1.1 deraadt 679: command can be used to rebuild private databases, etc.
680: after a program has been updated.
1.8 aaron 681: The following environment variables are set for each
1.14 ! millert 682: .Em special
1.2 dm 683: command:
1.14 ! millert 684: .Bl -tag -width "BASEFILE"
! 685: .It Ev FILE
1.2 dm 686: The full pathname of the local file that was just updated.
1.14 ! millert 687: .It Ev REMFILE
1.2 dm 688: The full pathname of the remote file that was just updated.
1.14 ! millert 689: .It BASEFILE
1.2 dm 690: The basename of the remote file that was just updated.
1.14 ! millert 691: .El
! 692: .Pp
1.2 dm 693: The
1.14 ! millert 694: .Em cmdspecial
1.2 dm 695: command is similar to the
1.14 ! millert 696: .Em special
1.2 dm 697: command, except it is executed only when the entire command is completed
698: instead of after each file is updated.
1.14 ! millert 699: The list of files is placed in the
! 700: .Ev FILES
! 701: environment variable.
1.2 dm 702: Each file name in
1.14 ! millert 703: .Ev FILES
1.2 dm 704: is separated by a `:' (colon).
1.14 ! millert 705: .Pp
! 706: If a hostname ends in a `+' (plus sign), then the plus
1.2 dm 707: is stripped off and NFS checks are disabled.
708: This is equivalent to disabling the
1.14 ! millert 709: .Fl o Ns Ar chknfs
1.2 dm 710: option just for this one host.
1.14 ! millert 711: .Pp
1.2 dm 712: The following is a small example.
1.14 ! millert 713: .Bd -literal -offset indent
1.2 dm 714: HOSTS = ( matisse root@arpa)
1.1 deraadt 715:
716: FILES = ( /bin /lib /usr/bin /usr/games
1.2 dm 717: /usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h}
718: /usr/lib /usr/man/man? /usr/ucb /usr/local/rdist )
1.1 deraadt 719:
1.14 ! millert 720: EXLIB = ( Mail.rc aliases aliases.db crontab dshrc
! 721: sendmail.cf sendmail.hf sendmail.st uucp vfont )
1.1 deraadt 722:
723: ${FILES} -> ${HOSTS}
1.2 dm 724: install -oremove,chknfs ;
725: except /usr/lib/${EXLIB} ;
726: except /usr/games/lib ;
1.14 ! millert 727: special /usr/lib/sendmail "/usr/lib/sendmail -bi" ;
1.1 deraadt 728:
729: srcs:
730: /usr/src/bin -> arpa
1.2 dm 731: except_pat ( \e\e.o\e$ /SCCS\e$ ) ;
1.1 deraadt 732:
733: IMAGEN = (ips dviimp catdvi)
734:
735: imagen:
736: /usr/local/${IMAGEN} -> arpa
1.2 dm 737: install /usr/local/lib ;
738: notify ralph ;
1.1 deraadt 739:
740: ${FILES} :: stamp.cory
1.2 dm 741: notify root@cory ;
1.14 ! millert 742: .Ed
! 743: .Sh ENVIRONMENT
! 744: .Bl -tag -width "TMPDIR"
! 745: .It TMPDIR
! 746: Name of temporary directory to use.
! 747: Default is
! 748: .Pa /tmp.
! 749: .It RSH
! 750: Name of the default remote shell program to use.
! 751: Default is
! 752: .Pa ssh .
! 753: .El
! 754: .Sh FILES
! 755: .Bl -tag -width "$TMPDIR/rdist*" -compact
! 756: .It distfile
! 757: input command file
! 758: .It $TMPDIR/rdist*
! 759: temporary file for update lists
! 760: .El
! 761: .Sh SEE ALSO
! 762: .Xr sh 1 ,
! 763: .Xr csh 1 ,
! 764: .Xr rsh 1 ,
! 765: .Xr ssh 1 ,
! 766: .Xr stat 2 ,
! 767: .Xr rcmdsh 3
! 768: .Sh NOTES
! 769: If the basename of a file (the last component in the pathname) is ".", then
! 770: .Nm
1.2 dm 771: assumes the remote (destination) name is a directory.
1.11 aaron 772: i.e.,
1.14 ! millert 773: .Pa /tmp/ .
1.2 dm 774: means that
1.14 ! millert 775: .Pa /tmp
1.2 dm 776: should be a directory on the remote host.
1.14 ! millert 777: .Pp
1.2 dm 778: The following options are still recognized for backwards compatibility:
1.14 ! millert 779: .Pp
! 780: .Bd -filled -offset indent
! 781: .Fl v
! 782: .Fl N
! 783: .Fl O
! 784: .Fl q
! 785: .Fl b
! 786: .Fl r
! 787: .Fl R
! 788: .Fl s
! 789: .Fl w
! 790: .Fl y
! 791: .Fl h
! 792: .Fl i
! 793: .Fl x
! 794: .Ed
! 795: .Sh BUGS
1.2 dm 796: Source files must reside on the local host where rdist is executed.
1.14 ! millert 797: .Pp
1.1 deraadt 798: Variable expansion only works for name lists; there should be a general macro
799: facility.
1.14 ! millert 800: .Pp
! 801: .Nm
1.1 deraadt 802: aborts on files which have a negative mtime (before Jan 1, 1970).
1.14 ! millert 803: .Pp
1.2 dm 804: If a hardlinked file is listed more than once in the same target,
1.8 aaron 805: then
1.14 ! millert 806: .Nm
1.2 dm 807: will report missing links.
808: Only one instance of a link should be listed in each target.