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