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