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