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