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 begin with # and end with a NEWLINE.

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 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 (specified by the date/time of the time_stamp file). Typically, only notify is used with the '::' format of the command line.

rdist 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 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.

The shell meta-characters: [, ], {, }, * and ? are recognized 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.

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. Multiple file names must be enclosed within parentheses.

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.

The rdist command is IPv6-enabled. See ip6(7P).

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 merlin@druid whenever it discovers that a local file has changed relative to a timestamp file. (Parentheses are used when the source or destination 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 ;