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