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