rdist(1)							   User Commands							  rdist(1)

NAME

       rdist - remote file distribution program

SYNOPSIS

       rdist [-b] [-D] [-h] [-i] [-n] [-q] [-R] [-a] [-x] [-PN | -PO]  [-k realm] [-v] [-w] [-y] [ -d macro = value] [-f distfile]  [-m host]...

       rdist [-b] [-D] [-h] [-i] [-n] [-q] [-R] [-a] [-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 are executing. (Note: 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 modification time differs from the original on the local host.
       With the -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  indicated  distfile  for
       instructions  on updating files and/or directories. 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 instructions.

       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 being transferred is  also
       possible. The rdist session can be kerberized using any of the following Kerberos specific options : -a, -PN or -PO, -x, and -k realm. Some
       of these options (-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 in krb5_auth_rules(5). If this authorization fails, fallback to normal rdist using rhosts will occur only if
       the  -PO  option  is used explicitly on the command line or is specified in 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 user must have an entry in the .rhosts file in the home directory. See hosts.equiv(4) for more information.

OPTIONS

       The following options are supported:

       -a

	   This  option  explicitly enables Kerberos authentication and 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, the user is allowed to carry out the rdist transfer.

       -b

	   Binary comparison. Performs a binary comparison and updates files if they differ, rather than merely comparing dates and sizes.

       -c pathname ... [login@]hostname[:destpath]

	   Copies each pathname to the named host; if destpath is specified, it will not update any pathname on the named  host.  (Relative  file-
	   names  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.

       -f distfile

	   Uses the description file distfile. A `-' as the distfile 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 will normally try to maintain 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).

       -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 is regarded much more secure, but is not interoperable with older (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" pro-
	   tocol 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 mas-
	   ter (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 destination directory name. Normally, only the last component 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/dir2 instead 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.

       -y

	   Younger mode. Does not update remote copies that are younger than the master copy, but issues a warning message instead. Only modifica-
	   tion 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 followed by a `->' or the opening parenthesis of a filename list.

   Comments
       Comments 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 have been changed since some given date. The source list specifies 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 par-
       tial  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 (specified by the date/time of the time_stamp file). Typically, only notify is used with the  '::'	format	of
       the command line.

   Macros
       rdist  has  a  limited  macro facility. Macros are only expanded in filename or hostname lists, and in the argument lists of certain primi-
       tives.  Macros cannot be used to stand for 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 may 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 authenticated to one of the principals named in the  ~/.k5login  file.  Other-
       wise,  the originating user will be 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 the authenticated-principal-name -> local-user-name mapping rules. The .k5login file (for  access  control)
       comes into play only when Kerberos authentication is being done.

   Metacharacters
       The shell meta-characters: [, ], {, }, * and ? are recognized and expanded (on the local host only) just as they are with csh(1). Metachar-
       acters 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 rela-
       tive to the current working directory. Multiple file names must be enclosed within parentheses.

   Primitives
       The following primitives can be used to specify actions rdist 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 are created. To help  prevent  disasters,  a  non-
	   empty  directory on a target host is not replaced with a regular file 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 master 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 destination host is the same as the local host unless the destination 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 may 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 each regular-expression pattern (see ed(1) for more information on regular expressions).
	   Note that `' and `$' characters must be escaped in the distfile.  Shell variables can also be used within  a  pattern,  however  shell
	   filename expansion is not supported.

       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 no filename argument is
	   present, the command-line is performed for every updated file, with the shell variable FILE set to the file's name on the  local  host.
	   The	quotation  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 executing each command-line is the user's home directory on the remote host.

   IPv6
       The rdist command is IPv6-enabled. See ip6(7P). IPv6 is not currently supported with Kerberos V5 authentication.

EXAMPLES

       Example 1: A sample distfile

       The following sample distfile instructs rdist to maintain identical copies of a shared library, a  shared-library  initialized  data  file,
       several include files, and a directory, on hosts named hermes and magus. On magus, commands are executed as super-user. rdist notifies mer-
       lin@druid whenever it discovers that a local file has changed relative to a timestamp file. (Parentheses are used when the source or desti-
       nation 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 users

       /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 file

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWrcmdc 		   |
       +-----------------------------+-----------------------------+

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)

DIAGNOSTICS

       A complaint about mismatch of rdist version numbers may really stem from some problem with starting your shell, for example, you are in too
       many groups.

WARNINGS

       The super-user does not have its accustomed access privileges on NFS mounted file systems. Using rdist to copy to such a  file  system  may
       fail, or the copies may 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.

       rdist aborts on files that have a negative modification time (before Jan 1, 1970).

       There should be a "force" option to allow replacement of non-empty directories by regular files or symlinks. A means of updating file modes
       and owners of otherwise identical files is also needed.

SunOS 5.10							    14 May 2003 							  rdist(1)