| blob | db3adbd46fd2d3fc1fb231b95ca56dec26dac79f |
1 '\" te
2 .\" Copyright (c) 1985 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
3 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
4 .TH RDIST 1 "Dec 23, 2008"
5 .SH NAME
6 rdist \- remote file distribution program
7 .SH SYNOPSIS
8 .LP
9 .nf
10 \fBrdist\fR [\fB-b\fR] [\fB-D\fR] [\fB-h\fR] [\fB-i\fR] [\fB-n\fR] [\fB-q\fR] [\fB-R\fR] [\fB-a\fR] [\fB-K\fR] [\fB-x\fR]
11 [\fB-PN\fR | \fB-PO\fR] [\fB-k\fR \fIrealm\fR] [\fB-v\fR] [\fB-w\fR] [\fB-y\fR]
12 [\fB-d\fR \fImacro\fR \fI=\fR \fIvalue\fR] [\fB-f\fR \fIdistfile\fR] [\fB-m\fR \fIhost\fR]...
13 .fi
15 .LP
16 .nf
17 \fBrdist\fR [\fB-b\fR] [\fB-D\fR] [\fB-h\fR] [\fB-i\fR] [\fB-n\fR] [\fB-q\fR] [\fB-R\fR] [\fB-a\fR] [\fB-K\fR] [\fB-x\fR]
18 [\fB-PN\fR | \fB-PO\fR] [\fB-k\fR \fIrealm\fR] [\fB-v\fR] [\fB-w\fR] [\fB-y\fR] \fB-c\fR \fIpathname\fR...
19 [\fIlogin\fR @] \fIhostname\fR [: \fIdestpath\fR]
20 .fi
22 .SH DESCRIPTION
23 .sp
24 .LP
25 The \fBrdist\fR utility maintains copies of files on multiple hosts. It
26 preserves the owner, group, mode, and modification time of the master copies,
27 and can update programs that are executing. (\fBrdist\fR does not propagate
28 ownership or mode changes when the file contents have not changed.) Normally, a
29 copy on a remote host is updated if its size or modification time differs from
30 the original on the local host. With the \fB-y\fR option (younger mode), only
31 the modification times are checked, not the size. See \fBOPTIONS\fR below.
32 .sp
33 .LP
34 There are two forms of the \fBrdist\fR command. In the first form shown in the
35 \fBSYNOPSIS\fR section above, \fBrdist\fR reads the indicated \fIdistfile\fR
36 for instructions on updating files and/or directories. If \fIdistfile\fR is
37 `\fB\(mi\fR\&', the standard input is used. If no \fB-f\fR option is present,
38 \fBrdist\fR first looks in its working directory for \fBdistfile\fR, and then
39 for \fBDistfile\fR, for instructions.
40 .sp
41 .LP
42 The second form shown in \fBSYNOPSIS\fR uses the \fB-c\fR option and specifies
43 paths as command line options.
44 .sp
45 .LP
46 The user can opt for a secure session of \fBrdist\fR which uses Kerberos V5 for
47 authentication. Encryption of the data being transferred is also possible. The
48 \fBrdist\fR session can be kerberized using any of the following Kerberos
49 specific options : \fB-a\fR, \fB-PN\fR or \fB-PO\fR, \fB-x\fR, and \fB-k\fR
50 \fIrealm\fR. Some of these options (\fB-a\fR, \fB-x\fR, \fB-PN\fR or \fB-PO\fR,
51 and \fB-f\fR or \fB-F\fR) can also be specified in the \fB[appdefaults]\fR
52 section of \fBkrb5.conf\fR(4). The usage of these options and the expected
53 behavior is discussed in the OPTIONS section below. If Kerberos authentication
54 is used, authorization to the account is controlled by rules in
55 \fBkrb5_auth_rules\fR(5). If this authorization fails, fallback to normal
56 \fBrdist\fR using rhosts occurs only if the \fB-PO\fR option is used explicitly
57 on the command line or is specified in \fBkrb5.conf\fR(4). Also notice that the
58 \fB-PN\fR or \fB-PO\fR, \fB-x\fR, and \fB-k\fR \fIrealm\fR options are just
59 supersets of the \fB-a\fR option. In order to use the non-secure version of
60 \fBrdist\fR across machines, each host machine must have a
61 \fB/etc/host.equiv\fR file, or the user must have an entry in the
62 \fB\&.rhosts\fR file in the home directory. See \fBhosts.equiv\fR(4) for more
63 information.
64 .SH OPTIONS
65 .sp
66 .LP
67 The following options are supported:
68 .sp
69 .ne 2
70 .na
71 \fB\fB-a\fR\fR
72 .ad
73 .sp .6
74 .RS 4n
75 This option explicitly enables Kerberos authentication and trusts the
76 \fB\&.k5login\fR file for access-control. If the authorization check by
77 \fBin.rshd\fR(1M) on the server-side succeeds and if the \fB\&.k5login\fR file
78 permits access, the user is allowed to carry out the \fBrdist\fR transfer.
79 .RE
81 .sp
82 .ne 2
83 .na
84 \fB\fB-b\fR\fR
85 .ad
86 .sp .6
87 .RS 4n
88 Binary comparison. Performs a binary comparison and updates files if they
89 differ, rather than merely comparing dates and sizes.
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB\fB-c\fR
96 \fIpathname\fR .\|.\|.[\fIlogin\|\fR\fB@\fR]\fIhostname\fR[\fB:\fR\fIdestpath\|\fR]\fR
97 .ad
98 .sp .6
99 .RS 4n
100 Copies each \fIpathname\fR to the named host; if \fIdestpath\fR is specified,
101 it does not update any \fIpathname\fR on the named host. (Relative filenames
102 are taken as relative to your home directory.) If the `\fIlogin\fR\fB\|@\fR\&'
103 prefix is given, the update is performed with the user \fBID\fR of \fIlogin\fR.
104 If the `\fB:\fR\fIdestpath\fR' is given, the remote file is installed as that
105 pathname.
106 .RE
108 .sp
109 .ne 2
110 .na
111 \fB\fB-d\fR \fImacro\fR\fB=\fR\fIvalue\fR\fR
112 .ad
113 .sp .6
114 .RS 4n
115 Defines \fImacro\fR to have \fIvalue\fR. This option is used to define or
116 override macro definitions in the distfile. \fIvalue\fR can be the empty
117 string, one name, or a list of names surrounded by parentheses and separated by
118 white space.
119 .RE
121 .sp
122 .ne 2
123 .na
124 \fB\fB-D\fR\fR
125 .ad
126 .sp .6
127 .RS 4n
128 Enables debugging.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fB-f\fR \fIdistfile\fR\fR
135 .ad
136 .sp .6
137 .RS 4n
138 Uses the description file \fIdistfile\fR. A `\fB\(mi\fR\&' as the
139 \fIdistfile\fR argument denotes the standard input.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fB-h\fR\fR
146 .ad
147 .sp .6
148 .RS 4n
149 Follows symbolic links. Copies the file that the link points to rather than the
150 link itself.
151 .RE
153 .sp
154 .ne 2
155 .na
156 \fB\fB-i\fR\fR
157 .ad
158 .sp .6
159 .RS 4n
160 Ignores unresolved links. \fBrdist\fR normally tries to maintain the link
161 structure of files being transferred and warn the user if all the links cannot
162 be found.
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fB-k\fR \fIrealm\fR\fR
169 .ad
170 .sp .6
171 .RS 4n
172 Causes \fBrdist\fR to obtain tickets for the remote host in \fIrealm\fR instead
173 of the remote host's realm as determined by \fBkrb5.conf\fR(4).
174 .RE
176 .sp
177 .ne 2
178 .na
179 \fB\fB-K\fR\fR
180 .ad
181 .sp .6
182 .RS 4n
183 This option explicitly disables Kerberos authentication. It can be used to
184 override the \fBautologin\fR variable in \fBkrb5.conf\fR(4).
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fB-m\fR \fIhost\fR\fR
191 .ad
192 .sp .6
193 .RS 4n
194 Limits which machines are to be updated. Multiple \fB-m\fR arguments can be
195 given to limit updates to a subset of the hosts listed in the distfile.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fB-n\fR\fR
202 .ad
203 .sp .6
204 .RS 4n
205 Prints the commands without executing them. This option is useful for debugging
206 a distfile.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fB-PO\fR\fR
213 .ad
214 .br
215 .na
216 \fB\fB-PN\fR\fR
217 .ad
218 .sp .6
219 .RS 4n
220 Explicitly requests new (\fB-PN\fR) or old (\fB-PO\fR) version of the Kerberos
221 "\fBrcmd\fR" protocol. The new protocol avoids many security problems prevalant
222 in the old one and is regarded much more secure, but is not interoperable with
223 older (MIT/SEAM) servers. The new protocol is used by default, unless
224 explicitly specified using these options or through \fBkrb5.conf\fR(4). If
225 Kerberos authorization fails when using the old "\fBrcmd\fR" protocol, there is
226 fallback to regular, non-kerberized \fBrdist\fR. This is not the case when the
227 new, more secure "\fBrcmd\fR" protocol is used.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fB-q\fR\fR
234 .ad
235 .sp .6
236 .RS 4n
237 Quiet mode. Does not display the files being updated on the standard output.
238 .RE
240 .sp
241 .ne 2
242 .na
243 \fB\fB-R\fR\fR
244 .ad
245 .sp .6
246 .RS 4n
247 Removes extraneous files. If a directory is being updated, removes files on the
248 remote host that do not correspond to those in the master (local) directory.
249 This is useful for maintaining truly identical copies of directories.
250 .RE
252 .sp
253 .ne 2
254 .na
255 \fB\fB-v\fR\fR
256 .ad
257 .sp .6
258 .RS 4n
259 Verifies that the files are up to date on all the hosts. Any files that are out
260 of date are displayed, but no files are updated, nor is any mail sent.
261 .RE
263 .sp
264 .ne 2
265 .na
266 \fB\fB-w\fR\fR
267 .ad
268 .sp .6
269 .RS 4n
270 Whole mode. The whole file name is appended to the destination directory name.
271 Normally, only the last component of a name is used when renaming files. This
272 preserves the directory structure of the files being copied, instead of
273 flattening the directory structure. For instance, renaming a list of files such
274 as \fBdir1/dir2\fR to \fBdir3\fR would create files \fBdir3/dir1\fR and
275 \fBdir3/dir2\fR instead of \fBdir3\fR and \fBdir3\fR. When the \fB-w\fR option
276 is used with a filename that begins with \fB~\fR, everything except the home
277 directory is appended to the destination name.
278 .RE
280 .sp
281 .ne 2
282 .na
283 \fB\fB-x\fR\fR
284 .ad
285 .sp .6
286 .RS 4n
287 Causes the information transferred between hosts to be encrypted. Notice that
288 the command is sent unencrypted to the remote system. All subsequent transfers
289 are encrypted.
290 .RE
292 .sp
293 .ne 2
294 .na
295 \fB\fB-y\fR\fR
296 .ad
297 .sp .6
298 .RS 4n
299 Younger mode. Does not update remote copies that are younger than the master
300 copy, but issues a warning message instead. Only modification times are
301 checked. No comparison of size is made.
302 .RE
304 .SH USAGE
305 .SS "White Space Characters"
306 .sp
307 .LP
308 NEWLINE, TAB, and SPACE characters are all treated as white space; a mapping
309 continues across input lines until the start of the next mapping: either a
310 single \fIfilename\fR followed by a `\fB->\fR' or the opening parenthesis of a
311 filename list.
312 .SS "Comments"
313 .sp
314 .LP
315 Comments begin with \fB#\fR and end with a NEWLINE.
316 .SS "Distfiles"
317 .sp
318 .LP
319 The distfile contains a sequence of entries that specify the files to be
320 copied, the destination files to be copied, the destination hosts, and what
321 operations to perform to do the updating. Each entry has one of the following
322 formats:
323 .sp
324 .in +2
325 .nf
326 \fIvariable_name\fR '=' \fIname_list\fR
327 [ label: ] \fIsource_list\fR '\fB->\fR' \fIdestination_list\fR \fIcommand_list\fR
328 [ label: ] \fIsource_list\fR '\fB::\fR' \fItime_stamp_file\fR \fIcommand_list\fR
329 .fi
330 .in -2
332 .sp
333 .LP
334 The first format is used for defining variables. The second format is used for
335 distributing files to other hosts. The third format is used for making lists of
336 files that have been changed since some given date. The source list specifies a
337 list of files and/or directories on the local host that are to be used as the
338 master copy for distribution. The destination list is the list of hosts to
339 which these files are to be copied. Each file in the source list is added to a
340 list of changes if the file is out of date on the host that is being updated
341 (second format) or if the file is newer than the time stamp file (third
342 format). Labels are optional. They are used to identify a command for partial
343 updates. The colon (\fB:\fR) is used after an optional label, while the double
344 colon (\fB::\fR) is used for making lists of files that have been changed since
345 a certain date (specified by the date/time of the \fItime_stamp\fR file).
346 Typically, only \fBnotify\fR is used with the '\fB::\fR' format of the command
347 line.
348 .SS "Macros"
349 .sp
350 .LP
351 \fBrdist\fR has a limited macro facility. Macros are only expanded in filename
352 or hostname lists, and in the argument lists of certain primitives. Macros
353 cannot be used to stand for primitives or their options, or the `\fB->\fR' or
354 `\fB::\fR' symbols.
355 .sp
356 .LP
357 A macro definition is a line of the form:
358 .sp
359 .in +2
360 .nf
361 \fImacro\fR \fB=\fR \fIvalue\fR
362 .fi
363 .in -2
365 .sp
366 .LP
367 A macro reference is a string of the form:
368 .sp
369 .in +2
370 .nf
371 \fB${\fR\fImacro\fR\fB}\fR
372 .fi
373 .in -2
375 .sp
376 .LP
377 although (as with \fBmake\fR(1S)) the braces can be omitted if the macro name
378 consists of just one character.
379 .SS "Kerberos Access-Control file"
380 .sp
381 .LP
382 For the kerberized \fBrdist\fR session, each user might have a private
383 authorization list in a file \fB\&.k5login\fR in their home directory. Each
384 line in this file should contain a Kerberos principal name of the form
385 \fIprincipal\fR/\fIinstance\fR@\fIrealm\fR. If there is a \fB~/.k5login\fR
386 file, then access is granted to the account if and only if the originater user
387 is authenticated to one of the principals named in the \fB~/.k5login\fR file.
388 Otherwise, the originating user is granted access to the account if and only if
389 the authenticated principal name of the user can be mapped to the local account
390 name using the \fIauthenticated-principal-name\fR \(-> \fIlocal-user-name\fR
391 mapping rules. The \fB\&.k5login\fR file (for access control) comes into play
392 only when Kerberos authentication is being done.
393 .SS "Metacharacters"
394 .sp
395 .LP
396 The shell meta-characters: \fB[\fR, \fB]\fR, \fB{\fR, \fB}\fR, \fB*\fR and
397 \fB?\fR are recognized and expanded (on the local host only) just as they are
398 with \fBcsh\fR(1). Metacharacters can be escaped by prepending a backslash.
399 .sp
400 .LP
401 The \fB~\fR character is also expanded in the same way as with \fBcsh\fR;
402 however, it is expanded separately on the local and destination hosts.
403 .SS "Filenames"
404 .sp
405 .LP
406 File names that do not begin with `\fB\|/\|\fR\&' or `\fB\|~\|\fR\&' are taken
407 to be relative to user's home directory on each destination host; they are
408 \fInot\fR relative to the current working directory. Multiple file names must
409 be enclosed within parentheses.
410 .SS "Primitives"
411 .sp
412 .LP
413 The following primitives can be used to specify actions \fBrdist\fR is to take
414 when updating remote copies of each file.
415 .sp
416 .ne 2
417 .na
418 \fB\fBinstall\fR [\fB-b\fR] [\fB-h\fR] [\fB-i\fR] [\fB-R\fR] [\fB-v\fR]
419 [\fB-w\fR] [\fB-y\fR] [\fInewname\fR]\fR
420 .ad
421 .sp .6
422 .RS 4n
423 Copy out of date files and directories (recursively). If no \fInewname\fR
424 operand is given, the name of the local file is given to the remote host's
425 copy. If absent from the remote host, parent directories in a filename's path
426 are created. To help prevent disasters, a non-empty directory on a target host
427 is not replaced with a regular file or a symbolic link by \fBrdist\fR. However,
428 when using the \fB-R\fR option, a non-empty directory is removed if the
429 corresponding filename is completely absent on the master host.
430 .sp
431 The options for \fBinstall\fR have the same semantics as their command line
432 counterparts, but are limited in scope to a particular map. The login name used
433 on the destination host is the same as the local host unless the destination
434 name is of the format \fIlogin@host\fR. In that case, the update is performed
435 under the username \fIlogin\fR.
436 .RE
438 .sp
439 .ne 2
440 .na
441 \fB\fBnotify\fR \fIaddress.\|.\|.\fR\fR
442 .ad
443 .sp .6
444 .RS 4n
445 Send mail to the indicated email \fIaddress\fR of the form:
446 .sp
447 \fIuser@host\fR
448 .sp
449 that lists the files updated and any errors that might have occurred. If an
450 address does not contain a `\fB@\fR\fIhost\|\fR' suffix, \fBrdist\fR uses the
451 name of the destination host to complete the address.
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB\fBexcept\fR \fIfilename .\|.\|.\fR\fR
458 .ad
459 .sp .6
460 .RS 4n
461 Omit from updates the files named as arguments.
462 .RE
464 .sp
465 .ne 2
466 .na
467 \fB\fBexcept_pat\fR \fIpattern .\|.\|.\fR\fR
468 .ad
469 .sp .6
470 .RS 4n
471 Omit from updates the filenames that match each regular-expression
472 \fIpattern\fR (see \fBed\fR(1) for more information on regular expressions).
473 Note that \fB`\e'\fR and \fB`$'\fR characters must be escaped in the distfile.
474 Shell variables can also be used within a pattern, however shell filename
475 expansion is not supported.
476 .RE
478 .sp
479 .ne 2
480 .na
481 \fB\fBspecial\fR [\fIfilename\fR] .\|.\|. \fB"\fR\fIcommand-line\|\fR\fB"\fR\fR
482 .ad
483 .sp .6
484 .RS 4n
485 Specify a Bourne shell, \fBsh\fR(1) command line to execute on the remote host
486 after each named file is updated. If no \fIfilename\fR argument is present, the
487 \fIcommand-line\fR is performed for every updated file, with the shell variable
488 \fBFILE\fR set to the file's name on the local host. The quotation marks allow
489 \fIcommand-line\fR to span input lines in the distfile; multiple shell commands
490 must be separated by semicolons (\fB;\fR).
491 .sp
492 The default working directory for the shell executing each \fIcommand-line\fR
493 is the user's home directory on the remote host.
494 .RE
496 .SS "IPv6"
497 .sp
498 .LP
499 The \fBrdist\fR command is IPv6-enabled. See \fBip6\fR(7P). \fBIPv6\fR is not
500 currently supported with Kerberos V5 authentication.
501 .SH EXAMPLES
502 .LP
503 \fBExample 1 \fRA Sample distfile
504 .sp
505 .LP
506 The following sample distfile instructs \fBrdist\fR to maintain identical
507 copies of a shared library, a shared-library initialized data file, several
508 include files, and a directory, on hosts named \fBhermes\fR and \fBmagus\fR. On
509 \fBmagus\fR, commands are executed as super-user. \fBrdist\fR notifies
510 \fBmerlin@druid\fR whenever it discovers that a local file has changed relative
511 to a timestamp file. (Parentheses are used when the source or destination list
512 contains zero or more names separated by white-space.)
514 .sp
515 .in +2
516 .nf
517 \fBHOSTS = ( hermes root@magus )
519 FILES = ( /usr/local/lib/libcant.so.1.1
520 /usrlocal/lib/libcant.sa.1.1 /usr/local/include/{*.h}
521 /usr/local/bin )
523 (${FILES}) -> (${HOSTS})
524 install \(miR ;
525 ${FILES} :: /usr/local/lib/timestamp
526 notify merlin@druid ;\fR
527 .fi
528 .in -2
529 .sp
531 .SH FILES
532 .sp
533 .ne 2
534 .na
535 \fB\fB~/.rhosts\fR\fR
536 .ad
537 .RS 23n
538 User's trusted hosts and users
539 .RE
541 .sp
542 .ne 2
543 .na
544 \fB\fB/etc/host.equiv\fR\fR
545 .ad
546 .RS 23n
547 system trusted hosts and users
548 .RE
550 .sp
551 .ne 2
552 .na
553 \fB\fB/tmp/rdist*\fR\fR
554 .ad
555 .RS 23n
556 Temporary file for update lists
557 .RE
559 .sp
560 .ne 2
561 .na
562 \fB\fB$HOME/.k5login\fR\fR
563 .ad
564 .RS 23n
565 File containing Kerberos principals that are allowed access
566 .RE
568 .sp
569 .ne 2
570 .na
571 \fB\fB/etc/krb5/krb5.conf\fR\fR
572 .ad
573 .RS 23n
574 Kerberos configuration file
575 .RE
577 .SH SEE ALSO
578 .sp
579 .LP
580 \fBcsh\fR(1), \fBed\fR(1), \fBmake\fR(1S), \fBsh\fR(1), \fBin.rshd\fR(1M),
581 \fBstat\fR(2), \fBhosts.equiv\fR(4), \fBkrb5.conf\fR(4), \fBattributes\fR(5),
582 \fBkrb5_auth_rules\fR(5), \fBip6\fR(7P)
583 .SH DIAGNOSTICS
584 .sp
585 .LP
586 A complaint about mismatch of \fBrdist\fR version numbers might really stem
587 from some problem with starting your shell, for example, you are in too many
588 groups.
589 .SH WARNINGS
590 .sp
591 .LP
592 The super-user does not have its accustomed access privileges on \fBNFS\fR
593 mounted file systems. Using \fBrdist\fR to copy to such a file system might
594 fail, or the copies might be owned by user "nobody".
595 .SH BUGS
596 .sp
597 .LP
598 Source files must reside or be mounted on the local host.
599 .sp
600 .LP
601 There is no easy way to have a special command executed only once after all
602 files in a directory have been updated.
603 .sp
604 .LP
605 Variable expansion only works for name lists; there should be a general macro
606 facility.
607 .sp
608 .LP
609 \fBrdist\fR aborts on files that have a negative modification time (before Jan
610 1, 1970).
611 .sp
612 .LP
613 There should be a "force" option to allow replacement of non-empty directories
614 by regular files or symlinks. A means of updating file modes and owners of
615 otherwise identical files is also needed.