Creating the Distfile

The distfile used by the master host contains a sequence of entries that specify the files to be copied, the destination hosts, and the operations to be performed to do the updating. Since a distfile is an ASCII file, you can create it with any text editor. If you are familiar with the make program, the structure of a distfile is somewhat similar to a makefile.

The following syntax rules apply:

Newlines, tabs, and blanks are used as separators and are ignored.
Comments begin with "#" and end with a newline.
Shell meta characters ([, ], {, }, *, and ?) are expanded on the master host in the same way as with the csh command. Use a backslash (\) to escape a meta character. (Type man 1 csh for more information.)
File names that do not begin with "/" or "~" are assumed to be relative to the user's home directory on each remote host.

A distfile contains the following types of entries:

Definitions of variables to be used with distfile commands.
Commands that distribute files to other hosts.
Commands to create lists of files that have been changed since a specified date.

Each of these types of entries is described in the following sections.

Variable Definitions

Variables can be used to represent a list of items, such as the names of files to be distributed or the remote hosts to be updated. Variables can be defined anywhere in the distfile, but they are usually grouped together at the beginning of the file. Variables are then used in command entries. The format for defining variables is:

variable_name = name_list

variable_name is a name by which the variable is referenced.

name_list consists of item names separated by white space, enclosed in parentheses.

Spaces or tabs immediately to the left and right of the "=" are ignored. Subsequent appearances of ${variable_name} in the distfile (except in comments) are replaced by name_list. (Braces can be omitted if variable_name consists of just one character.)

Variable definitions can also be specified in the command line when invoking rdist; variable definitions in the command line override definitions in the distfile (see “Starting rdist”).

The following are examples of three variable definition entries in a distfile:

HOSTS = ( matisse root@arpa)
 
FILES = ( /bin /lib /usr/bin /usr/games
        /usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h
                   /usr/lib /usr/man/man? /usr/ucb
                   /usr/local/rdist `cat ./std-files` )
 
EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc
        sendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont )

The first entry defines the variable HOSTS to represent two remote hosts, matisse and arpa, that are to be updated. Note that if a remote host is specified in the form user@host, user is the user name on host that is used to update files and directories on that host. Otherwise, the user name on the master host is used to update the remote host.

The second entry defines the variable FILES to represent the files and directories to be updated on the remote hosts. The shell meta characters {, }, and * in the second line of this entry are used in a "shorthand" that represents the files /usr/include/*.h, /usr/include/stand/*.h, /usr/include/sys/*.h, /usr/include/vax*/*.h, etc. The * character is used as a wildcard. Note that you can use commands, such as cat, within single backquotes (`) in the variable list.

The last entry defines the variable EXLIB to represent the files that should not be updated on the remote hosts.

Examples of how variables are used in distfile command entries are shown in the following sections.

File Distribution Commands

Distfile command entries that distribute files to a remote host are specified in the following format:

[label:] source_list -> destination_list command_list ;

label: is optional and is used to group command entries. You can use labels to perform a partial update. Normally, rdist updates all the files and directories listed in a distfile. You can invoke rdist with a specific label; in this case, rdist executes only the entries under the specified label.

source_list specifies the directories or files on the master host that are to be used as the master copy for distributing to the remote hosts.

destination_list specifies the list of remote hosts to which source_list is to be distributed.

source_list and destination_list can consist of the following:

Single name (for example, matisse).
Variable defined previously in the distfile. Variables to be expanded begin with "$", followed by the variable name in curly braces (for example, ${HOSTS}).
List of names, separated by white space and enclosed in parentheses (for example, ( /usr/lib /usr/bin /usr/ucb )).

command_list consists of one or more of the commands listed in Table 10-1 “Distfile Commands”. Each command must end in a semicolon (;).

Table 10-1 Distfile Commands

`install`	Copies source files/directories to each host in the destination list. Any of the following options can be specified: `-b` performs a binary comparison and updates files if they differ. Without this option, `rdist` updates files only if the size or modification time differs. `-h` follows symbolic links on the master host and copies the file(s) that the link points to. Without this option, `rdist` copies the name of a symbolic link. `-i` ignores unresolved links. Without this option, `rdist` tries to maintain the link structure of the files being copied and sends out warnings if any link cannot be found. `-R` removes files in the remote host's directory that do not exist in the corresponding directory on the master host. `-v` displays the files that are out of date on the remote host but does not update any files or send any mail. `-w` appends the full pathname (including directory subtree) to a destination directory name. For example, if file `/dira/filea` is copied to `dirb`, the result ant file is `/dirb/dira/filea`. Without this option, the preceding copy operation would result in `/dirb/filea`. `-y` does not update files on the remote host that are newer than the master copy. `destpath` installs the file on the remote host as the specified path name.
`notify user[@host]`	Mails a list of updated files and/or any errors that have occurred to a specified receiver. If `host` is not specified, the remote host name is assumed.
`except file_list`	Updates all files in the source list except for the file(s) specified in `file_list`.
`except_pat pattern`	Updates all files in the source list except for those files whose names contain the pattern `pattern`. The characters "\" and "$" must be escaped with a backslash (\).
`special [file] "command"`	Specifies command(s) that are to be executed on the remote host after each specified file is updated or installed. Used to rebuild databases and configuration files after a program has been updated. If `file` is not specified, `command` is performed for every updated file. `command` can contain multiple commands, each separated by semicolons. The user's home directory on the remote host is the default working directory for each command.

If there is no install command in a distfile or if the destpath option is not used with the install command, the name of the file on the master host is given to the remote host's file. Parent directories in a file's path are created on a remote host if they do not exist. rdist does not replace non-empty directories on a remote host. However, if the -R option is specified with the install command, a non-empty directory is removed on the remote host if the corresponding directory does not exist on the master host.

For a detailed description of commands and their options, type man 1 rdist at the HP-UX prompt.

The following two examples of file distribution commands use the variable definitions that were shown previously:

${FILES} -> ${HOSTS}
     install -R ;
     except /usr/lib/${EXLIB} ;
     except /usr/games/lib ;
 
srcs:
     /usr/src/bin -> arpa
     except_pat ( \\.o$ /SCCS\$ ) ;

The first example distributes the source files defined in the variable FILES to the destination hosts defined in the variable HOSTS. rdist copies the files to each remote host, removing files in the remote host's directory that do not exist on the master directory. rdist does not update files in /usr/lib/${EXLIB} or in /usr/games/lib.

The second example (labeled srcs) distributes the directory /usr/src/bin to the host arpa; object files or files that are under SCCS control are not copied.

Changed Files List Commands

The third type of distfile entry is used to make a list of files that have been changed on the master host since a specified date. The format for this type of entry is as follows:

[label:] source_list :: timestamp_file command_list ;

label: and source_list are specified in the same manner as in the entries to distribute files.

timestamp_file is a file on the local host, whose modification time is used as a timestamp. source_list files on the local host that are newer than the timestamp are noted in a list.

Use the notify command to mail the list of changed files to a specified user. The following is an example of this type of entry:

${FILES} :: stamp.cory
    notify root@cory ;

In the above example, the list of files that are newer than the timestamp in stamp.cory are mailed to the user root@cory. Note that with the notify command, if no "@" appears in the user name, the remote host name is assumed.

Creating the Distfile

Technical documentation

» Table of Contents

» Index

Variable Definitions

File Distribution Commands

Changed Files List Commands