User Commands rdist(1)
NAME
rdist - remote file distribution program
SYNOPSIS
rdist [-b] [-D] [-h] [-i] [-n] [-q] [-R] [-a] [-K] [-x]
[-PN | -PO] [-k realm] [-v] [-w] [-y]
[-d macro = value] [-f distfile] [-m host]...
rdist [-b] [-D] [-h] [-i] [-n] [-q] [-R] [-a] [-K] [-x]
[-PN | -PO] [-k realm] [-v] [-w] [-y] -c pathname...
[login @] hostname [: destpath]DESCRIPTION
The rdist utility maintains copies of files on multiple
hosts. It preserves the owner, group, mode, and modification time of the master copies, and can update programs that areexecuting. (rdist does not propagate ownership or mode
changes when the file contents have not changed.) Normally,a copy on a remote host is updated if its size or modifica-
tion time differs from the original on the local host. Withthe -y option (younger mode), only the modification times
are checked, not the size. See OPTIONS below.There are two forms of the rdist command. In the first form
shown in the SYNOPSIS section above, rdist reads the indi-
cated distfile for instructions on updating files and/ordirectories. If distfile is `-', the standard input is used.
If no -f option is present, rdist first looks in its working
directory for distfile, and then for Distfile, for instruc-
tions.The second form shown in SYNOPSIS uses the -c option and
specifies paths as command line options.The user can opt for a secure session of rdist which uses
Kerberos V5 for authentication. Encryption of the data beingtransferred is also possible. The rdist session can be ker-
berized using any of the following Kerberos specific options: -a, -PN or -PO, -x, and -k realm. Some of these options
(-a, -x, -PN or -PO, and -f or -F) can also be specified in
the [appdefaults] section of krb5.conf(4). The usage of these options and the expected behavior is discussed in the OPTIONS section below. If Kerberos authentication is used, authorization to the account is controlled by rules inkrb5_auth_rules(5). If this authorization fails, fallback to
normal rdist using rhosts occurs only if the -PO option is
used explicitly on the command line or is specified inSunOS 5.11 Last change: 23 Dec 2008 1
User Commands rdist(1)
krb5.conf(4). Also notice that the -PN or -PO, -x, and -k
realm options are just supersets of the -a option. In order
to use the non-secure version of rdist across machines, each
host machine must have a /etc/host.equiv file, or the usermust have an entry in the .rhosts file in the home direc-
tory. See hosts.equiv(4) for more information. OPTIONS The following options are supported:-a
This option explicitly enables Kerberos authenticationand trusts the .k5login file for access-control. If the
authorization check by in.rshd(1M) on the server-side
succeeds and if the .k5login file permits access, theuser is allowed to carry out the rdist transfer.
-b
Binary comparison. Performs a binary comparison andupdates files if they differ, rather than merely compar-
ing dates and sizes.-c pathname ...[login@]hostname[:destpath]
Copies each pathname to the named host; if destpath is specified, it does not update any pathname on the named host. (Relative filenames are taken as relative to your home directory.) If the `login@' prefix is given, the update is performed with the user ID of login. If the `:destpath' is given, the remote file is installed as that pathname.-d macro=value
Defines macro to have value. This option is used to define or override macro definitions in the distfile. value can be the empty string, one name, or a list of names surrounded by parentheses and separated by white space.-D
Enables debugging.SunOS 5.11 Last change: 23 Dec 2008 2
User Commands rdist(1)
-f distfile
Uses the description file distfile. A `-' as the dist-
file argument denotes the standard input.-h
Follows symbolic links. Copies the file that the link points to rather than the link itself.-i
Ignores unresolved links. rdist normally tries to main-
tain the link structure of files being transferred and warn the user if all the links cannot be found.-k realm
Causes rdist to obtain tickets for the remote host in
realm instead of the remote host's realm as determined by krb5.conf(4).-K
This option explicitly disables Kerberos authentication. It can be used to override the autologin variable in krb5.conf(4).-m host
Limits which machines are to be updated. Multiple -m
arguments can be given to limit updates to a subset of the hosts listed in the distfile.-n
Prints the commands without executing them. This option is useful for debugging a distfile.-PO
-PN
Explicitly requests new (-PN) or old (-PO) version of
the Kerberos "rcmd" protocol. The new protocol avoids many security problems prevalant in the old one and isSunOS 5.11 Last change: 23 Dec 2008 3
User Commands rdist(1)
regarded much more secure, but is not interoperable witholder (MIT/SEAM) servers. The new protocol is used by default, unless explicitly specified using these options or through krb5.conf(4). If Kerberos authorization fails when using the old "rcmd" protocol, there is fallback to
regular, non-kerberized rdist. This is not the case when
the new, more secure "rcmd" protocol is used.-q
Quiet mode. Does not display the files being updated on the standard output.-R
Removes extraneous files. If a directory is being updated, removes files on the remote host that do not correspond to those in the master (local) directory. This is useful for maintaining truly identical copies of directories.-v
Verifies that the files are up to date on all the hosts. Any files that are out of date are displayed, but no files are updated, nor is any mail sent.-w
Whole mode. The whole file name is appended to the des-
tination directory name. Normally, only the last com-
ponent of a name is used when renaming files. This preserves the directory structure of the files being copied, instead of flattening the directory structure. For instance, renaming a list of files such as dir1/dir2 to dir3 would create files dir3/dir1 and dir3/dir2instead of dir3 and dir3. When the -w option is used
with a filename that begins with ~, everything except the home directory is appended to the destination name.-x
Causes the information transferred between hosts to be encrypted. Notice that the command is sent unencrypted to the remote system. All subsequent transfers are encrypted.SunOS 5.11 Last change: 23 Dec 2008 4
User Commands rdist(1)
-y
Younger mode. Does not update remote copies that areyounger than the master copy, but issues a warning mes-
sage instead. Only modification times are checked. No comparison of size is made.USAGE
White Space Characters NEWLINE, TAB, and SPACE characters are all treated as white space; a mapping continues across input lines until the start of the next mapping: either a single filename followedby a `->' or the opening parenthesis of a filename list.
CommentsComments begin with # and end with a NEWLINE.
Distfiles The distfile contains a sequence of entries that specify the files to be copied, the destination files to be copied, the destination hosts, and what operations to perform to do the updating. Each entry has one of the following formats:variable_name '=' name_list
[ label: ] source_list '->' destination_list command_list
[ label: ] source_list '::' time_stamp_file command_list
The first format is used for defining variables. The second format is used for distributing files to other hosts. The third format is used for making lists of files that havebeen changed since some given date. The source list speci-
fies a list of files and/or directories on the local host that are to be used as the master copy for distribution. The destination list is the list of hosts to which these files are to be copied. Each file in the source list is added to a list of changes if the file is out of date on the host that is being updated (second format) or if the file is newer than the time stamp file (third format). Labels are optional. They are used to identify a command for partial updates. The colon (:) is used after an optional label, while the double colon (::) is used for making lists of files that have been changed since a certain date (specifiedby the date/time of the time_stamp file). Typically, only
notify is used with the '::' format of the command line. Macrosrdist has a limited macro facility. Macros are only expanded
in filename or hostname lists, and in the argument lists of certain primitives. Macros cannot be used to stand forSunOS 5.11 Last change: 23 Dec 2008 5
User Commands rdist(1)
primitives or their options, or the `->' or `::' symbols.
A macro definition is a line of the form: macro = value A macro reference is a string of the form:${macro}
although (as with make(1S)) the braces can be omitted if the macro name consists of just one character.Kerberos Access-Control file
For the kerberized rdist session, each user might have a
private authorization list in a file .k5login in their home directory. Each line in this file should contain a Kerberos principal name of the form principal/instance@realm. If there is a ~/.k5login file, then access is granted to the account if and only if the originater user is authenticatedto one of the principals named in the ~/.k5login file. Oth-
erwise, the originating user is granted access to the account if and only if the authenticated principal name of the user can be mapped to the local account name using theauthenticated-principal-name -> local-user-name mapping
rules. The .k5login file (for access control) comes into play only when Kerberos authentication is being done. MetacharactersThe shell meta-characters: [, ], {, }, * and ? are recog-
nized and expanded (on the local host only) just as they are with csh(1). Metacharacters can be escaped by prepending a backslash. The ~ character is also expanded in the same way as with csh; however, it is expanded separately on the local and destination hosts. Filenames File names that do not begin with `/' or `~' are taken to be relative to user's home directory on each destination host;they are not relative to the current working directory. Mul-
tiple file names must be enclosed within parentheses. PrimitivesSunOS 5.11 Last change: 23 Dec 2008 6
User Commands rdist(1)
The following primitives can be used to specify actionsrdist is to take when updating remote copies of each file.
install [-b] [-h] [-i] [-R] [-v] [-w] [-y] [newname]
Copy out of date files and directories (recursively). If no newname operand is given, the name of the local file is given to the remote host's copy. If absent from the remote host, parent directories in a filename's path arecreated. To help prevent disasters, a non-empty direc-
tory on a target host is not replaced with a regularfile or a symbolic link by rdist. However, when using
the -R option, a non-empty directory is removed if the
corresponding filename is completely absent on the mas-
ter host. The options for install have the same semantics as their command line counterparts, but are limited in scope to a particular map. The login name used on the destinationhost is the same as the local host unless the destina-
tion name is of the format login@host. In that case, the update is performed under the username login. notify address... Send mail to the indicated email address of the form: user@host that lists the files updated and any errors that might have occurred. If an address does not contain a `@host'suffix, rdist uses the name of the destination host to
complete the address. except filename ... Omit from updates the files named as arguments.except_pat pattern ...
Omit from updates the filenames that match eachregular-expression pattern (see ed(1) for more informa-
tion on regular expressions). Note that `\' and `$'
characters must be escaped in the distfile. Shell vari-
ables can also be used within a pattern, however shell filename expansion is not supported.SunOS 5.11 Last change: 23 Dec 2008 7
User Commands rdist(1)
special [filename] ... "command-line"
Specify a Bourne shell, sh(1) command line to execute on the remote host after each named file is updated. If nofilename argument is present, the command-line is per-
formed for every updated file, with the shell variableFILE set to the file's name on the local host. The quo-
tation marks allow command-line to span input lines in
the distfile; multiple shell commands must be separated by semicolons (;). The default working directory for the shell executingeach command-line is the user's home directory on the
remote host. IPv6The rdist command is IPv6-enabled. See ip6(7P). IPv6 is not
currently supported with Kerberos V5 authentication.EXAMPLES
Example 1 A Sample distfileThe following sample distfile instructs rdist to maintain
identical copies of a shared library, a shared-library ini-
tialized data file, several include files, and a directory,on hosts named hermes and magus. On magus, commands are exe-
cuted as super-user. rdist notifies merlin@druid whenever it
discovers that a local file has changed relative to a times-
tamp file. (Parentheses are used when the source or destina-
tion list contains zero or more names separated by white-
space.) HOSTS = ( hermes root@magus ) FILES = ( /usr/local/lib/libcant.so.1.1 /usrlocal/lib/libcant.sa.1.1 /usr/local/include/{*.h} /usr/local/bin )(${FILES}) -> (${HOSTS})
install -R ;
${FILES} :: /usr/local/lib/timestamp
notify merlin@druid ; FILES ~/.rhosts User's trusted hosts and usersSunOS 5.11 Last change: 23 Dec 2008 8
User Commands rdist(1)
/etc/host.equiv system trusted hosts and users/tmp/rdist* Temporary file for update lists
$HOME/.k5login File containing Kerberos principals
that are allowed access /etc/krb5/krb5.conf Kerberos configuration fileATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:_______________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|________________________________|
| Availability | service/network/network-clients|
|_____________________________|________________________________|
SEE ALSO
csh(1), ed(1), make(1S), sh(1), in.rshd(1M), stat(2), hosts.equiv(4), krb5.conf(4), attributes(5),krb5_auth_rules(5), ip6(7P)
DIAGNOSTICSA complaint about mismatch of rdist version numbers might
really stem from some problem with starting your shell, for example, you are in too many groups. WARNINGSThe super-user does not have its accustomed access
privileges on NFS mounted file systems. Using rdist to copy
to such a file system might fail, or the copies might be owned by user "nobody".BUGS
Source files must reside or be mounted on the local host. There is no easy way to have a special command executed only once after all files in a directory have been updated. Variable expansion only works for name lists; there should be a general macro facility.SunOS 5.11 Last change: 23 Dec 2008 9
User Commands rdist(1)
rdist aborts on files that have a negative modification time
(before Jan 1, 1970). There should be a "force" option to allow replacement ofnon-empty directories by regular files or symlinks. A means
of updating file modes and owners of otherwise identical files is also needed.SunOS 5.11 Last change: 23 Dec 2008 10