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