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