Annotation of src/usr.bin/oldrdist/oldrdist.1, Revision 1.20
1.20 ! jmc 1: .\" $OpenBSD: oldrdist.1,v 1.19 2010/07/15 20:51:38 schwarze 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.20 ! jmc 32: .Dd $Mdocdate: July 15 2010 $
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
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
1.18 schwarze 105: .Ed
106: .Bd -filled -offset indent-two -compact
1.1 dm 107: .Li install
108: .Op Ar dest ;
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
1.19 schwarze 245: .Ql \&[ ,
1.7 aaron 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.20 ! jmc 275: .Bl -column "`except_pat'" "<pattern list>" "opt_dest_name" "`;'" -offset indent
! 276: .It `install' Ta "<options>" Ta opt_dest_name Ta `;'
! 277: .It `notify' Ta "<name list>" Ta "" Ta `;'
! 278: .It `except' Ta "<name list>" Ta "" Ta `;'
! 279: .It `except_pat' Ta "<pattern list>" Ta "" Ta `;'
! 280: .It `special' Ta "<name list>" Ta string Ta `;'
1.1 dm 281: .El
282: .Pp
283: The
284: .Ic install
285: command is used to copy out of date files and/or directories.
286: Each source file is copied to each host in the destination list.
287: Directories are recursively copied in the same way.
1.3 aaron 288: .Ar opt_dest_name
1.1 dm 289: is an optional parameter to rename files.
290: If no
291: .Ic install
292: command appears in the command list or
293: the destination name is not specified,
294: the source file name is used.
295: Directories in the path name will be created if they
296: do not exist on the remote host.
1.7 aaron 297: .Pp
1.1 dm 298: To help prevent disasters, a non-empty directory on a target host will
299: never be replaced with a regular file or a symbolic link.
1.7 aaron 300: However, under the
301: .Fl R
302: option a non-empty directory will be removed
1.1 dm 303: if the corresponding filename is completely absent on the master host.
304: The
305: .Ar options
1.7 aaron 306: are
307: .Fl R ,
308: .Fl h ,
309: .Fl i ,
310: .Fl v ,
311: .Fl w ,
312: .Fl y ,
313: and
314: .Fl b
1.1 dm 315: and have the same semantics as
316: options on the command line except they only apply to the files
317: in the source list.
318: The login name used on the destination host is the same as the local host
1.7 aaron 319: unless the destination name is of the format
320: .Dq login@host .
1.1 dm 321: .Pp
322: The
323: .Ic notify
324: command is used to mail the list of files updated (and any errors
325: that may have occurred) to the listed names.
1.7 aaron 326: If no
327: .Ql @
328: appears in the name, the destination host is appended to the name
1.1 dm 329: (e.g., name1@host, name2@host, ...).
330: .Pp
331: The
332: .Ic except
1.3 aaron 333: command is used to update all of the files in the source list except
1.1 dm 334: for the files listed in
1.7 aaron 335: .Ar name list .
1.1 dm 336: This is usually used to copy everything in a directory except certain files.
337: .Pp
338: The
339: .Ic except_pat
340: command is like the
341: .Ic except
342: command except that
343: .Ar pattern list
344: is a list of regular expressions
345: (see
1.7 aaron 346: .Xr ed 1
1.1 dm 347: for details).
348: If one of the patterns matches some string within a file name, that file will
349: be ignored.
1.7 aaron 350: Note that since
351: .Ql \e
352: is a quote character, it must be doubled to become
353: part of the regular expression.
354: Variables are expanded in
1.1 dm 355: .Ar pattern list
1.7 aaron 356: but not shell file pattern matching characters.
357: To include a
358: .Ql $ ,
359: it must be escaped with
360: .Ql \e .
1.1 dm 361: .Pp
362: The
363: .Ic special
364: command is used to specify
1.7 aaron 365: .Xr sh 1
1.1 dm 366: commands that are to be executed on the
367: remote host after the file in
368: .Ar name list
369: is updated or installed.
370: If the
371: .Ar name list
372: is omitted then the shell commands will be executed
1.7 aaron 373: for every file updated or installed.
374: The shell variable FILE is set
1.1 dm 375: to the current filename before executing the commands in
1.7 aaron 376: .Ar string .
1.3 aaron 377: .Ar string
1.7 aaron 378: starts and ends with
379: .Ql \&"
380: and can cross multiple lines in
1.1 dm 381: .Ar distfile .
1.7 aaron 382: Multiple commands to the shell should be separated by
383: .Ql \&; .
1.1 dm 384: Commands are executed in the user's home directory on the host
385: being updated.
386: The
387: .Ar special
388: command can be used to rebuild private databases, etc.
389: after a program has been updated.
390: .Pp
391: The following is a small example:
392: .Bd -literal -offset indent
393: HOSTS = ( matisse root@arpa )
394:
395: FILES = ( /bin /lib /usr/bin /usr/games
396: \t/usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h}
397: \t/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist )
398:
399: EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc
400: \tsendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont )
401:
402: ${FILES} -> ${HOSTS}
403: \tinstall -R ;
404: \texcept /usr/lib/${EXLIB} ;
405: \texcept /usr/games/lib ;
406: \tspecial /usr/lib/sendmail "/usr/lib/sendmail -bz" ;
407:
408: srcs:
409: /usr/src/bin -> arpa
410: \texcept_pat ( \e\e.o\e$ /SCCS\e$ ) ;
411:
412: IMAGEN = (ips dviimp catdvi)
413:
414: imagen:
415: /usr/local/${IMAGEN} -> arpa
416: \tinstall /usr/local/lib ;
417: \tnotify ralph ;
418:
419: ${FILES} :: stamp.cory
420: \tnotify root@cory ;
421: .Ed
422: .Sh FILES
423: .Bl -tag -width /tmp/rdist* -compact
424: .It Pa distfile
425: input command file
426: .It Pa /tmp/rdist*
427: temporary file for update lists
428: .El
1.11 jmc 429: .Sh DIAGNOSTICS
430: A complaint about mismatch of
431: .Nm
432: version numbers may really stem
433: from some problem with starting your shell, e.g., you are in too many groups.
1.1 dm 434: .Sh SEE ALSO
1.3 aaron 435: .Xr csh 1 ,
1.1 dm 436: .Xr sh 1 ,
437: .Xr stat 2
438: .Sh HISTORY
439: The
1.9 aaron 440: .Nm
1.1 dm 441: command appeared in
442: .Bx 4.3 .
443: .Sh BUGS
444: Source files must reside on the local host where
1.9 aaron 445: .Nm
1.1 dm 446: is executed.
447: .Pp
448: There is no easy way to have a special command executed after all files
449: in a directory have been updated.
450: .Pp
451: Variable expansion only works for name lists; there should be a general macro
452: facility.
453: .Pp
1.9 aaron 454: .Nm
1.1 dm 455: aborts on files which have a negative mtime (before Jan 1, 1970).
456: .Pp
1.8 aaron 457: There should be a
1.7 aaron 458: .Dq force
459: option to allow replacement of non-empty directories
460: by regular files or symlinks.
461: A means of updating file modes and owners
1.1 dm 462: of otherwise identical files is also needed.