rdist Command

Commands Reference, Volume 4

rdist Command

Purpose

Distributes identical copies of files on multiple hosts.

Syntax

To Use a Distribution File

rdist [ -n ] [ -q ] [ -b ] [ -D ] [ -R ] [ -h ] [ -i ] [ -v ] [ -w ] [ -y ] [ -f FileName ] [ -d Argument=Value ] [ -m Host ] ... [ Name ] ...

To Interpret Arguments as a Small Distribution File

rdist [ -n ] [ -q ] [ -b ] [ -D ] [ -R ] [ -h ] [ -i ] [ -v ] [ -w ] [ -y ] -c Name ... [ Login@ ] Host [ Destination ]

Description

Attention: Do not attempt to use the rdist command to send a file larger than 2 Gigabytes in size to a pre-AIX 4.2 or non-AIX machine. Doing so will result in undefined behaviors, and in rare cases, the loss of data.

The rdist command maintains identical copies of files on multiple hosts. The rdist command preserves the owner, group, mode, and modified time of files, if possible, and can update programs that are running. The rdist command can receive direction from the following sources:

The default distribution file, distfile file in your $HOME directory.
A different distribution file, specified by the -f flag.
Command-line arguments that augment or override variable definitions in the distribution file.
Command-line arguments that serve as a small distribution file.

If you do not use the -f flag, the rdist command looks for distfile file in your $HOME directory. If it doesn't find a distfile file, it looks for Distfile file.

The value specified by the Name parameter is read as the name of a file to be updated or a subcommand to execute. If you do not specify a value for the Name parameter on the command line, the rdist command updates all the files and directories listed in the distribution file. If you specify - (minus sign) for the Name parameter, the rdist command uses standard input. If the name of a file specified by the Name parameter is the same as the name of a subcommand, the rdist command interprets the Name parameter as a subcommand.

The rdist command requires that a .rhosts file be configured on each host. See ".rhosts File Format for TCP/IP" in AIX Files Reference for details.

Notes:
If the rdist command is not present in the /usr/bin/rdist directory on a remote machine, create a link from the /usr/bin/rdist directory to the actual location of the rdist command. This location is usually the /usr/ucb/rdist directory.

Currently, the rdist command can handle only 7-bit ASCII file names.

Flags

-b	Performs a binary comparison and updates files if they differ.
-c	Directs the rdist command to interpret the remaining arguments as a small distribution file. Available arguments are: Name Specifies single name or list of names separated by blanks. The value can be either a file or a subcommand. [Login@]Host Specifies the machine to be updated and, optionally, the login name to be notified of the update. Destination Specifies a file on the remote machine if a single name is specified in the Name argument; specifies a directory if more than one name is specified. Note: Do not use the -c flag with the -f, -d, or -m flag.
-d Argument=Value	Defines the Argument variable as having the value specified by the Value variable. The -d flag defines or overrides variable definitions in the distfile file. The Value variable can be specified as an empty string, one name, or a list of names surrounded by parentheses and separated by tabs or spaces.
-D	Turns on the debugging output.
-f FileName	Specifies the name of the distribution file. If you do not use the -f flag, the default value is the distfile or Distfile file in your $HOME directory.
-h	Copies the file that the link points to rather than the link itself.
-i	Ignores unresolved links. The rdist command maintains the link structure of files being transferred and warns users if it cannot find all the links.
-m Host	Limits which machines are to be updated. You can use the -m Host option multiple times to limit updates to a subset of the hosts listed in the distfile file.
-n	Prints the subcommands without executing them. Use the -n flag to debug the distfile file.
-q	Operates in quiet mode. The -q option suppresses printing of modified files on standard output.
-R	Removes extraneous files. If a directory is being updated, any files that exist on the remote host but not in the master directory are removed. Use the -R flag to maintain identical copies of directories.
-v	Verifies that the files are up-to-date on all hosts; files that are out-of-date are then displayed. However, the rdist -v command neither changes files nor sends mail.
-w	Appends the entire path name of the file to the destination directory name. Normally, the rdist command uses only the last component of a name for renaming files, preserving the directory structure of the copied files.
	When the -w flag is used with a file name that begins with a ~ (tilde), everything except the home directory is appended to the destination name. File names that do not begin with a / (slash) or a ~ (tilde) use the destination user's home directory as the root directory for the rest of the file name.
-y	Prevents recent copies of files from being replaced by files that are not as recent. Files are normally updated when their time stamp and size differ. The -y flag prevents the rdist command from updating files more recent than the master file.

Distribution File (distfile File)

The distribution file specifies the files to copy, destination hosts for distribution, and operations to perform when updating files to be distributed with the rdist command. Normally, the rdist command uses the distfile file in your $HOME directory. You can specify a different file If you use the -f flag.

Entry Formats

Each entry in the distribution file has one of the following formats:

VariableName = NameList	Defines variables used in other entries of the distribution file (SourceList, DestinationList, or SubcommandList).
[Label:] SourceList -> DestinationList SubcommandList
	Directs the rdist command to distribute files named in the SourceList variable to hosts named in the DestinationList variable. Distribution file commands perform additional functions.
[Label:] SourceList :: TimeStampFile SubcommandList
	Directs the rdist command to update files that have changed since a given date. Distribution file subcommands perform additional functions. Each file specified with the SourceList variable is updated if the file is newer than the time-stamp file. This format is useful for restoring files.

Labels are optional and used to identify a subcommand for partial updates.

Entries

VariableName	Identifies the variable used in the distribution file.
NameList	Specifies a list of files and directories, hosts, or subcommands.
SourceList	Specifies files and directories on the local host for the rdist command to use as the master copy for distribution.
DestinationList	Indicates hosts to receive copies of the files.
SubcommandList	Lists distribution file subcommands to be executed.

The rdist command treats new-line characters, tabs, and blanks as separators. Distribution file variables for expansion begin with a $ (dollar sign) followed by a single character or a name enclosed in {} (braces). Comments begin with a # (pound sign) and end with a new-line character.

Source and Destination List Format

The distribution file source and destination lists comprise zero or more names separated by blanks, as shown in the following format:

[Name1] [Name2] [Name3] ...

The rdist command recognizes and expands the following shell metacharacters on the local host in the same way as for the csh command.

[ (left bracket)
] (right bracket)
{ (left brace)
} (right brace)
( (left parenthesis)
) (right parenthesis)
* (asterisk)
? (question mark)

To prevent these characters from being expanded, precede them with a \ (backslash). The rdist command also expands the ~ (tilde) in the same way as for the csh command, but does so separately on the local and destination hosts.

Distribution File Subcommands

Multiple commands to the shell must be separated by a ; (semicolon). Commands are executed in the user's home directory on the host being updated. The special subcommand can be used to rebuild private databases after a program has been updated.

The distribution file subcommand list may contain zero or more of the following subcommands:

install Options [OptionalDestName];
	Copies out-of-date files and directories. The rdist command copies each source file or directory to each host in the destination list. The available options as specified by the Options variable are the rdist command flags -b, -h, -i, -R, -v, -w, and -y. These options only apply to the files specified by the SourceList variable. When you use the -R flag, nonempty directories are removed if the corresponding file name is absent on the master host. The OptionalDestName parameter renames files. If no install subcommand appears in the subcommand list or the destination name is not specified, the source file name is used. Directories in the path name are created if they do not exist on the remote host. 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.
notify NameList;	Mails the list of updated files and any errors that may have occurred to the listed names (the NameList parameter). If no @ (at sign) appears in the name, the destination host is appended to the name (name@host).
except NameList;	Causes the rdist command to update all the files specified by the SourceList entry except for those files specified by the NameList variable.
except_pat NameList;	Prevents the rdist command from updating any files that contain a string that matches a member of the list specified by the NameList variable.
special NameList "String";
	Specifies shell commands (the "String" variable) to be executed on the remote host after the file specified by the NameList variable is updated or installed. If the NameList variable is omitted, the shell commands are executed for every file updated or installed. The shell variable FILE is set to the current file name before the rdist command executes the "String" variable. The "String" value must be enclosed in " " (double quotation marks) and can cross multiple lines in the distribution file.

Exit Status

This command returns the following exit values:

0	Specifies that the command completed successfully.
>0	Specifies that an error occurred.

Examples

Examples of the Format: VariableName = NameList

To indicate which hosts' files to update, enter a line similar to the following:
```
HOSTS =( matisse root@arpa )
```
where the HOSTS variable is defined to be matisse and root@arpa. The rdist command updates files on the hosts matisse and root@arpa. You could use this variable as a destination list.
To indicate a name to use as a value for a SourceList entry, enter a line similar to the following:
```
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 )
```
where the FILES value is defined to be the files to be used for the SourceList entry.
To indicate which files to exclude from the updating process, enter a line similar to the following:
```
EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc
    sendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont)
```
where the EXLIB value is defined as a list of files to exclude from the updating process.
To copy all files from /usr/src/bin to arpa expanding the namelist variable so that all files except those present in the namelist variable and having .o as an extension are copied:
```
/usr/src/bin ->arpa 
except_pat(\e\e.o\e ${<namelist> /SCCS\e ${<namelist>}
```
or
```
/usr/src/bin ->arpa 
except_pat(\\.o\e ${<namelist> /SCCS\e ${<namelist>}
```
To copy all files from /usr/src/bin to arpa except those with an .o extension:
```
/usr/src/bin ->arpa 
except_pat(\\.o\$ /SCCS\$ 
```

Examples of the Format: [label:] SourceList -> DestinationList SubcommandList

To copy a source list of files to a destination list of hosts, enter a line similar to the following:
```
${FILES} ->${HOSTS}
    install -R
    except /usr/lib/${EXLIB}  ;
    except /usr/games/lib  ;
    special /usr/sbin/sendmail "/usr/sbin/sendmail.bz"  ;
```
The [Label:] entry of the line is optional and not shown here. The $ (dollar sign) and the {} (braces) cause the file names FILES, HOSTS, and EXLIB to be expanded into the lists designated for them in the previous examples. The rest of the example comprises the subcommand list.
To use the [Label:] entry, enter the line as follows:
```
srcsL:
/usr/src/bin -> arpa
    except_pat (\e\e.o\e$ /SCCS\e$ ) ;
```
The label is srcsL: and can be used to identify this entry for updating. The /usr/src/bin file is the source to be copied and host arpa is the destination of the copy. The third line contains a subcommand from the subcommand list.
To use a time-stamp file, enter a line similar to the following:
```
${FILES} :: stamp.cory
    notify root@cory
```
The $ (dollar sign) and {} (braces) cause the name specified by FILES to be expanded into the list designated for it. The time-stamp file is stamp.cory. The last line is a subcommand from the subcommand list.

Files

/usr/bin/rdist	Contains the rdist command.
$HOME/distfile
	Contains a list of subcommands to be read by the rdist command.
/tmp/rdist	Contains an update list. This is a temporary file.

Related Information

The csh command, ksh command, sh command.

The .rhosts file format.

Network Overview in AIX Version 4.3 System Management Guide: Communications and Networks.