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