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