Annotation of src/usr.bin/oldrdist/oldrdist.1, Revision 1.21
1.21 ! jmc 1: .\" $OpenBSD: oldrdist.1,v 1.20 2011/09/03 22:59:07 jmc Exp $
1.7 aaron 2: .\"
1.1 dm 3: .\" Copyright (c) 1985, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
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.10 millert 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 dm 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: .\"
30: .\" from: @(#)rdist.1 8.2 (Berkeley) 12/30/93
31: .\"
1.21 ! jmc 32: .Dd $Mdocdate: September 3 2011 $
1.14 jmc 33: .Dt OLDRDIST 1
1.5 aaron 34: .Os
1.1 dm 35: .Sh NAME
1.14 jmc 36: .Nm oldrdist
1.1 dm 37: .Nd remote file distribution program
38: .Sh SYNOPSIS
1.14 jmc 39: .Nm oldrdist
1.16 sobrado 40: .Op Fl bhinqRvwy
41: .Op Fl d Ar var=value
1.1 dm 42: .Op Fl f Ar distfile
43: .Op Fl m Ar host
44: .Op Ar name ...
1.14 jmc 45: .Nm oldrdist
1.16 sobrado 46: .Op Fl bhinqRvwy
1.1 dm 47: .Fl c
48: .Ar name ...
49: .Oo login@ Oc Ns Ar host Ns Op :dest
50: .Sh DESCRIPTION
1.9 aaron 51: .Nm
1.1 dm 52: is a program to maintain identical copies of files over multiple hosts.
53: It preserves the owner, group, mode, and mtime of files if possible and
54: can update programs that are executing.
1.9 aaron 55: .Nm
1.1 dm 56: reads commands from
57: .Ar distfile
58: to direct the updating of files and/or directories.
59: .Pp
60: Options specific to the first SYNOPSIS form:
1.12 jmc 61: .Bl -tag -width "-f distfile"
1.3 aaron 62: .It Fl f Ar distfile
63: Use the specified
64: .Ar distfile .
1.1 dm 65: If
66: .Ar distfile
1.7 aaron 67: is
1.21 ! jmc 68: .Sq - ,
1.7 aaron 69: the standard input is used.
1.1 dm 70: .El
71: .Pp
1.21 ! jmc 72: If the
1.1 dm 73: .Fl f
74: option is not specified, the program looks first for
75: .Dq Pa distfile ,
76: then
77: .Dq Pa Distfile
78: to use as the input.
79: If no names are specified on the command line,
1.9 aaron 80: .Nm
1.1 dm 81: will update all of the files and directories listed in
1.7 aaron 82: .Ar distfile .
1.1 dm 83: Otherwise, the argument is taken to be the name of a file to be updated
1.7 aaron 84: or the label of a command to execute.
85: If label and file names conflict, it is assumed to be a label.
1.1 dm 86: These may be used together to update specific files
87: using specific commands.
88: .Pp
89: Options specific to the second SYNOPSIS form:
1.12 jmc 90: .Bl -tag -width "Fl c"
1.1 dm 91: .It Fl c
92: Forces
1.9 aaron 93: .Nm
1.1 dm 94: to interpret the remaining arguments as a small
1.7 aaron 95: .Ar distfile .
1.1 dm 96: .Pp
1.15 jmc 97: The equivalent distfile is as follows:
98: .Bd -filled -offset indent
1.1 dm 99: .Pq Ar name ...
100: .Li ->
101: .Op Ar login@
102: .Ar host
1.18 schwarze 103: .Ed
104: .Bd -filled -offset indent-two -compact
1.1 dm 105: .Li install
106: .Op Ar dest ;
107: .Ed
108: .El
109: .Pp
110: Options common to both forms:
1.12 jmc 111: .Bl -tag -width "Fl b"
1.1 dm 112: .It Fl b
1.7 aaron 113: Binary comparison.
114: Perform a binary comparison and update files if they differ
1.1 dm 115: rather than comparing dates and sizes.
116: .It Fl d Ar var=value
117: Define
118: .Ar var
119: to have
1.7 aaron 120: .Ar value .
1.1 dm 121: The
122: .Fl d
123: option is used to define or override variable definitions in the
1.7 aaron 124: .Ar distfile .
1.1 dm 125: .Ar Value
126: can be the empty string, one name, or a list of names surrounded by
127: parentheses and separated by tabs and/or spaces.
128: .It Fl h
1.7 aaron 129: Follow symbolic links.
130: Copy the file that the link points to rather than the link itself.
1.1 dm 131: .It Fl i
132: Ignore unresolved links.
1.9 aaron 133: .Nm
1.1 dm 134: will normally try to maintain the link structure of files being transferred
135: and warn the user if all the links cannot be found.
136: .It Fl m Ar host
1.7 aaron 137: Limit which machines are to be updated.
138: Multiple
1.1 dm 139: .Fl m
140: arguments can be given to limit updates to a subset of the hosts listed in the
1.7 aaron 141: .Ar distfile .
1.1 dm 142: .It Fl n
1.7 aaron 143: Print the commands without executing them.
144: This option is useful for debugging
145: .Ar distfile .
1.1 dm 146: .It Fl q
1.7 aaron 147: Quiet mode.
148: Files that are being modified are normally printed on standard output.
149: The
1.1 dm 150: .Fl q
151: option suppresses this.
152: .It Fl R
1.7 aaron 153: Remove extraneous files.
154: If a directory is being updated, any files that exist
1.1 dm 155: on the remote host that do not exist in the master directory are removed.
156: This is useful for maintaining truly identical copies of directories.
157: .It Fl v
1.7 aaron 158: Verify that the files are up to date on all the hosts.
159: Any files
1.1 dm 160: that are out of date will be displayed but no files will be changed
161: nor any mail sent.
162: .It Fl w
1.7 aaron 163: Whole mode.
164: The whole file name is appended to the destination directory
165: name.
166: Normally, only the last component of a name is used when renaming files.
1.1 dm 167: This will preserve the directory structure of the files being
1.7 aaron 168: copied instead of flattening the directory structure.
169: For example,
1.1 dm 170: renaming a list of files such as ( dir1/f1 dir2/f2 ) to dir3 would create
171: files dir3/dir1/f1 and dir3/dir2/f2 instead of dir3/f1 and dir3/f2.
172: .It Fl y
1.7 aaron 173: Younger mode.
174: Files are normally updated if their
1.1 dm 175: .Ar mtime
176: and
177: .Ar size
178: (see
1.7 aaron 179: .Xr stat 2 )
180: disagree.
181: The
1.1 dm 182: .Fl y
183: option causes
1.9 aaron 184: .Nm
1.1 dm 185: not to update files that are younger than the master copy.
186: This can be used
187: to prevent newer copies on other hosts from being replaced.
188: A warning message is printed for files which are newer than the master copy.
189: .El
190: .Pp
1.3 aaron 191: .Ar distfile
1.1 dm 192: contains a sequence of entries that specify the files
193: to be copied, the destination hosts, and what operations to perform
1.7 aaron 194: to do the updating.
195: Each entry has one of the following formats:
1.15 jmc 196: .Bd -literal -offset indent
1.1 dm 197: <variable name> `=' <name list>
198: [label:]<source list> `\->' <destination list> <command list>
199: [label:]<source list> `::' <time_stamp file> <command list>
200: .Ed
201: .Pp
202: The first format is used for defining variables.
203: The second format is used for distributing files to other hosts.
204: The third format is used for making lists of files that have been changed
205: since some given date.
206: The
207: .Ar source list
208: specifies a
209: list of files and/or directories on the local host which are to be used
210: as the master copy for distribution.
211: The
212: .Ar destination list
213: is the list of hosts to which these files are to be
1.7 aaron 214: copied.
215: Each file in the source list is added to a list of changes
1.1 dm 216: if the file is out of date on the host which is being updated (second format) or
217: the file is newer than the time stamp file (third format).
218: .Pp
1.7 aaron 219: Labels are optional.
220: They are used to identify a command for partial updates.
1.1 dm 221: .Pp
222: Newlines, tabs, and blanks are only used as separators and are
1.7 aaron 223: otherwise ignored.
224: Comments begin with
225: .Ql #
226: and end with a newline.
227: .Pp
228: Variables to be expanded begin with
229: .Ql $
230: followed by one character or
1.1 dm 231: a name enclosed in curly braces (see the examples at the end).
232: .Pp
233: The source and destination lists have the following format:
234: .Bd -literal -offset indent
235: <name>
236: .Ed
237: or
238: .Bd -literal -offset indent -compact
1.6 aaron 239: `(' <zero or more names separated by whitespace> `)'
1.1 dm 240: .Ed
241: .Pp
1.7 aaron 242: The shell meta-characters
1.19 schwarze 243: .Ql \&[ ,
1.7 aaron 244: .Ql \&] ,
245: .Ql { ,
246: .Ql } ,
247: .Ql * ,
248: and
1.13 jmc 249: .Ql \&?
1.1 dm 250: are recognized and expanded (on the local host only) in the same way as
1.7 aaron 251: .Xr csh 1 .
1.1 dm 252: They can be escaped with a backslash.
1.7 aaron 253: The
254: .Ql ~
255: character is also expanded in the same way as
1.1 dm 256: .Xr csh 1
257: but is expanded separately on the local and destination hosts.
258: When the
259: .Fl w
1.7 aaron 260: option is used with a file name that begins with
261: .Ql ~ ,
262: everything except the
1.1 dm 263: home directory is appended to the destination name.
1.7 aaron 264: File names which do not begin with
265: .Ql /
266: or
267: .Ql ~
268: use the destination user's
1.1 dm 269: home directory as the root directory for the rest of the file name.
270: .Pp
271: The command list consists of zero or more commands of the following
1.3 aaron 272: format:
1.20 jmc 273: .Bl -column "`except_pat'" "<pattern list>" "opt_dest_name" "`;'" -offset indent
274: .It `install' Ta "<options>" Ta opt_dest_name Ta `;'
275: .It `notify' Ta "<name list>" Ta "" Ta `;'
276: .It `except' Ta "<name list>" Ta "" Ta `;'
277: .It `except_pat' Ta "<pattern list>" Ta "" Ta `;'
278: .It `special' Ta "<name list>" Ta string Ta `;'
1.1 dm 279: .El
280: .Pp
281: The
282: .Ic install
283: command is used to copy out of date files and/or directories.
284: Each source file is copied to each host in the destination list.
285: Directories are recursively copied in the same way.
1.3 aaron 286: .Ar opt_dest_name
1.1 dm 287: is an optional parameter to rename files.
288: If no
289: .Ic install
290: command appears in the command list or
291: the destination name is not specified,
292: the source file name is used.
293: Directories in the path name will be created if they
294: do not exist on the remote host.
1.7 aaron 295: .Pp
1.1 dm 296: To help prevent disasters, a non-empty directory on a target host will
297: never be replaced with a regular file or a symbolic link.
1.7 aaron 298: However, under the
299: .Fl R
300: option a non-empty directory will be removed
1.1 dm 301: if the corresponding filename is completely absent on the master host.
302: The
303: .Ar options
1.7 aaron 304: are
305: .Fl R ,
306: .Fl h ,
307: .Fl i ,
308: .Fl v ,
309: .Fl w ,
310: .Fl y ,
311: and
312: .Fl b
1.1 dm 313: and have the same semantics as
314: options on the command line except they only apply to the files
315: in the source list.
316: The login name used on the destination host is the same as the local host
1.7 aaron 317: unless the destination name is of the format
318: .Dq login@host .
1.1 dm 319: .Pp
320: The
321: .Ic notify
322: command is used to mail the list of files updated (and any errors
323: that may have occurred) to the listed names.
1.7 aaron 324: If no
325: .Ql @
326: appears in the name, the destination host is appended to the name
1.1 dm 327: (e.g., name1@host, name2@host, ...).
328: .Pp
329: The
330: .Ic except
1.3 aaron 331: command is used to update all of the files in the source list except
1.1 dm 332: for the files listed in
1.7 aaron 333: .Ar name list .
1.1 dm 334: This is usually used to copy everything in a directory except certain files.
335: .Pp
336: The
337: .Ic except_pat
338: command is like the
339: .Ic except
340: command except that
341: .Ar pattern list
342: is a list of regular expressions
343: (see
1.7 aaron 344: .Xr ed 1
1.1 dm 345: for details).
346: If one of the patterns matches some string within a file name, that file will
347: be ignored.
1.7 aaron 348: Note that since
349: .Ql \e
350: is a quote character, it must be doubled to become
351: part of the regular expression.
352: Variables are expanded in
1.1 dm 353: .Ar pattern list
1.7 aaron 354: but not shell file pattern matching characters.
355: To include a
356: .Ql $ ,
357: it must be escaped with
358: .Ql \e .
1.1 dm 359: .Pp
360: The
361: .Ic special
362: command is used to specify
1.7 aaron 363: .Xr sh 1
1.1 dm 364: commands that are to be executed on the
365: remote host after the file in
366: .Ar name list
367: is updated or installed.
368: If the
369: .Ar name list
370: is omitted then the shell commands will be executed
1.7 aaron 371: for every file updated or installed.
372: The shell variable FILE is set
1.1 dm 373: to the current filename before executing the commands in
1.7 aaron 374: .Ar string .
1.3 aaron 375: .Ar string
1.7 aaron 376: starts and ends with
377: .Ql \&"
378: and can cross multiple lines in
1.1 dm 379: .Ar distfile .
1.7 aaron 380: Multiple commands to the shell should be separated by
381: .Ql \&; .
1.1 dm 382: Commands are executed in the user's home directory on the host
383: being updated.
384: The
385: .Ar special
386: command can be used to rebuild private databases, etc.
387: after a program has been updated.
388: .Pp
389: The following is a small example:
390: .Bd -literal -offset indent
391: HOSTS = ( matisse root@arpa )
392:
393: FILES = ( /bin /lib /usr/bin /usr/games
394: \t/usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h}
395: \t/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist )
396:
397: EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc
398: \tsendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont )
399:
400: ${FILES} -> ${HOSTS}
401: \tinstall -R ;
402: \texcept /usr/lib/${EXLIB} ;
403: \texcept /usr/games/lib ;
404: \tspecial /usr/lib/sendmail "/usr/lib/sendmail -bz" ;
405:
406: srcs:
407: /usr/src/bin -> arpa
408: \texcept_pat ( \e\e.o\e$ /SCCS\e$ ) ;
409:
410: IMAGEN = (ips dviimp catdvi)
411:
412: imagen:
413: /usr/local/${IMAGEN} -> arpa
414: \tinstall /usr/local/lib ;
415: \tnotify ralph ;
416:
417: ${FILES} :: stamp.cory
418: \tnotify root@cory ;
419: .Ed
420: .Sh FILES
421: .Bl -tag -width /tmp/rdist* -compact
422: .It Pa distfile
423: input command file
424: .It Pa /tmp/rdist*
425: temporary file for update lists
426: .El
1.11 jmc 427: .Sh DIAGNOSTICS
428: A complaint about mismatch of
429: .Nm
430: version numbers may really stem
431: from some problem with starting your shell, e.g., you are in too many groups.
1.1 dm 432: .Sh SEE ALSO
1.3 aaron 433: .Xr csh 1 ,
1.1 dm 434: .Xr sh 1 ,
435: .Xr stat 2
436: .Sh HISTORY
437: The
1.9 aaron 438: .Nm
1.1 dm 439: command appeared in
440: .Bx 4.3 .
441: .Sh BUGS
442: Source files must reside on the local host where
1.9 aaron 443: .Nm
1.1 dm 444: is executed.
445: .Pp
446: There is no easy way to have a special command executed after all files
447: in a directory have been updated.
448: .Pp
449: Variable expansion only works for name lists; there should be a general macro
450: facility.
451: .Pp
1.9 aaron 452: .Nm
1.1 dm 453: aborts on files which have a negative mtime (before Jan 1, 1970).
454: .Pp
1.8 aaron 455: There should be a
1.7 aaron 456: .Dq force
457: option to allow replacement of non-empty directories
458: by regular files or symlinks.
459: A means of updating file modes and owners
1.1 dm 460: of otherwise identical files is also needed.