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