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