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