Commands Reference, Volume 4

rdist Command

This document describes the old AIX rdist command located in the usr/bin/rdist file as well as the new usr/sbin/rdist command which is used with the new rdistd daemon.

Purpose

Remote file distribution client program

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

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 the 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 5L Version 5.2 Files Reference for details.

1. 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.
2. Currently, the rdist command can handle only 7-bit ASCII file names.

Flags

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:

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

Entries

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:

Exit Status

This command returns the following exit values:

Examples

Examples of the Format: VariableName = NameList

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

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

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

4. 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>}

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

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

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

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

Related Information

The csh command, ksh command, sh command.

The .rhosts file format.

Network Overview in AIX 5L Version 5.2 System Management Guide: Communications and Networks.

usr/sbin/rdist Command

Purpose

Client program for distributing files remotely.

Syntax

To Use a Distribution File

/usr/sbin/rdist [ -Fn ] [ -A num ] [ -a num ] [ -d var=value] [ -l < local logopts> ] [ -L <remote logopts> ] [ -f distfile] [ -M maxproc -m host ] [ -o distops ] [ -t timeout ] [ -p <rdist-path> ] [ -P <transport-path> ] [ name ... ]

To Interpret Arguments as a Small Distribution File

/usr/sbin/rdist -Fn -c name ... [ login@ ] host [ :dest ]

To Invoke the Old rdist as a Server

/usr/sbin/rdist -Server

For Version Information

/usr/sbin/rdist -V

Description

rdist is a program to maintain identical copies of files over multiple hosts. It preserves the owner, group, mode, and modification time of files if possible and can update programs that are running. The rdist command can receive direction from the following sources:

• The distribution file distfile in the current directory.
• The standard input if distfile is specified as -.
• If the -f flag is not used, rdist looks for the file named distfile and Distfile.
• If the -c flag is used, the trailing arguments are interpreted as a small distfile. The equivalent distfile is as follows.

  ( filename ... ) -> [user@]host
       install       [dest name] ;

If no name arguments are specified, rdist will update all of the files and directories listed in distfile. Otherwise, the argument is taken to be the name of a file to be updated or the label of a command to execute. If the label and file names conflict, it is assumed to be a label. These may be used together to update specific files using specific commands.

The -Server option provides backward compatibility for older versions of rdist which used this option to put rdist into server mode. If rdist is started with the -Server command line option, it will attempt to run the old version of rdist. This option will only work if the old rdist is located at /usr/bin/rdist.

rdist uses an arbitrary transport program to access each target host. The transport program can be specified on the command line with the -P flag. If the -P flag is not used, rsh is taken as the transport program. If the rsh method is used and the target host is the string localhost and the remote user name is the same as the local user name, rdist will attempy to run the following command:

/bin/sh -c rdistd -S

Otherwise rdist will run the following command:

rsh host -l remuser rdistd -S

In the example above, the host parameter is the name of the target host, remuser is the name of the user to make the connection as and, rdistd is the rdist server command on the target host.

The transport program must be compatible with the above syntax for rsh. If not, the transport program should be wrapped in a shell script which understands this command line syntax.

On each target host rdist will attempt to run the following command:

rdistd -S

or

<rdistd path> -S

In the example above, the -p flag was specified. If -p flag is not included, or the <rdistd path> is a simple filename, rdistd or <rdistd path> must be somewhere in the PATH of the user running rdist on the remote (target) host.

The rdist command uses the following environment variables:

Flags

Message Logging

The rdist command provides a set of message facilities, each of which contains a list of message types specifying which types of messages to send to that facility. The local client (rdist) and the remote server (rdistd) each maintain separate copies of what types of messages to log to what facilities.

The -l logopts flag specifies what logging options to use locally on the client. The -L logopts flag specifies what logging options to pass to the remote rdistd server.

The form of logopts should be the following:

facility=types:facility= types... 

The valid facility names are as follows:

stdout

Messages to standard output.

file

Messages are sent to a file. The file name can be specified by the format file = filename = types.

syslog

Messages are sent to the syslogd facility.

notify

Messages are sent to the internal rdistnotify facility. This facility is used in conjunction with the notify keyword in a distfile to specify what messages are mailed to the notify address.

types should be a comma separated list of message types. Each message type specified enables that message level. This is unlike the syslog system facility which uses an ascending order scheme. The following are the valid types:

change

Log messages for things that change.

info

Log general information.

notice

Log messages for general info about things that change. This includes things like making directories which are needed in order to install a specific target, but which are not explicitly specified in the distfile.

nerror

Log messages for normal errors that are not fatal.

ferror

Log messages for fatal errors.

warning

Log warnings about errors which are not as serious as nerror type messages.

verbose

Log messages for more information than normal, but less than debugging level.

debug

Log debugging information.

all

Log all but debug messages.

The Distribution 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.

Entry Formats

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

Labels are optional. They are used to identify a command for partial updates.

Entries

The rdist command treats newline 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 newline 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. When the -o whole option is used with a file name that begins with a tilde, everything except the home directory is appended to the destination name. File names which do not begin with a forward slash or a tilde use the destination user's home directory as the root directory for the rest of the file name.

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:

NFS checks are disabled if a hostname ends in a plus sign. This is equivalent to disabling the -o chknfs option just for this one host.

Exit Status

This command returns the following exit values:

Examples

1. To indicate which hosts' files to update, enter a line similar to the following:

   HOSTS =( matisse root@arpa )

   In the above example, 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.

2. 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 )

   In the above example, the FILES value is defined to be the files to be used for the SourceList entry.

3. 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)

   In the above example, the EXLIB value is defined as a list of files to exclude from the updating process.

4. 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>}

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

1. 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. Thedollar 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.

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

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

Related Information

The csh command, rcmd() system call, rdistd command,rsh command, sh command, stat() system call.