rdist to the Rescue!

Judith Ashworth

rdist is a BSD UNIX remote file distribution utility that updates files and directories on remote systems. This utility is quite useful to system administrators for maintaining workstation system files such as root account files which cannot be distributed with NIS (Network Information System -- formerly known as Yellow Pages), for installing bug fixes on remote systems, and as a substitute for NIS.

During execution, rdist retains the ownership, permissions, and timestamp of the file being transferred. It compares the size and timestamp of the file with the current file on the remote system before doing the transfer, and indicates which workstations were updated. You can also keep the files you want to transfer separate from the corresponding file on the master system by giving rdist different source and destination paths.

So how can rdist help you? Well, one way is as a substitute for NIS. Suppose you have a number of systems originally set up as standalones, and they suddenly need to share the system files usually distributed with NIS. Typically, this would happen when you have the least amount of time to set up an NIS master and get all the client machines on its domain and running ypbind. You would probably have to wait until you could schedule some possible downtime to ensure you get it all working.

rdist to the rescue! You can easily transfer a file of any type using this utility -- the trick is defining what file you want to transfer, what systems you want to transfer it to, and what you want it called when it gets there.

Using rdist

Fortunately, it's very easy to do once you know how. Before using rdist, you would create a file for transfer definitions, which are instructions to rdist on what to copy where. In the simplest use of rdist, the file would be called distfile, and it would be located in the current working directory when you execute rdist.

The basic format of a transfer definition in the distfile is:

<source path> -> <remote host name>
install <destination path>;

where <source path> is the full path of the file or directory to transfer, <remote host name> is the name of the system to transfer to, and <destination path> is what to call it on the remote system.

<source path> may be a list of files in the format:

( path1 path2 pathN )

Similarly, <remote host name> may be a list of host names, using the same format. However, you may not use a list for <destination path>.

The distfile can be divided up into sections called "packages" that group transfer definitions together so that they may be executed individually by using rdist with the package label. Once the distfile is created, the rdist command is executed by typing:

rdist <package name>

In cases where you need to keep files synchronized, you can put an entry into the root crontab file that will automatically execute rdist for you (see the crontab man pages, crontab(1) and crontab(5), for more information on using crontab). If you decide to do this, make sure you use the -f distfile option to specify the path of the distfile (see the rdist man page for a detailed description of this and other options to rdist).

Simulating NIS

Here's the solution to our NIS simulation problem. Although in most cases, NIS is the best method for keeping these files up-to-date, you can simulate a portion of what NIS does by using rdist to transfer the /etc/passwd, /etc/hosts, /etc/group, /etc/aliases, /etc/auto.master, /etc/auto.home, and /etc/auto.direct files yourself.

For the sake of brevity, suppose that only nine systems are affected, and that they are named after Santa's reindeer. Since the files to be transferred are owned by root, the rdist command will have to be run as root, and root on the master system must have login privileges on all the workstations involved. This means having the name of the master system in the /.rhosts file of these workstations.

Caution! Putting the name of any system in the /.rhosts file allows that system to rlogin as root without a password! So putting the name of the master system in the /.rhosts file is a potential security risk, and you must keep tight security controls on the master system.

For the following examples, I have chosen to create a distfile in the /sysadmin directory on the system called santa. The contents of /sysadmin/distfile for this problem would look something like Listing 1.

What does all this mean? The nis: line begins a package definition: it signifies that the following lines can be executed as a group by referring to nis on the command line. There can be many packages in the same distfile, each separated by a package label, and each can be executed separately. The next five lines indicate the files to transfer and the systems to transfer them to. The last line says to install the files on each system at the same destination as the source.

Since it is common for a list of hosts to be reused from package to package, rdist has a limited macro facility which allows you to define a macro to represent a list, and then refer to the list by the macro name. The facility is similar to using shell variables. I could have defined a macro called HOSTS, and another called NIS_FILES, and changed the transfer definition as in Listing 2. Using a macro instead of typing a list of files or host names makes the distfile easier to read, and the macro can be reused in another package.

Although simulating NIS in this manner may work quite well for a small number of systems, it should not be seen as a long-term solution. It should only be used in the situation where standalone systems need to share this information immediately, and then only on a temporary basis until NIS can be set up. A system where NIS is not available would be an exception, and in this case rdist would provide a permanent solution.

One of the disadvantages to using this method of distributing system information is that users have to log in to the master system in order to change their passwords for all client systems. In addition, these systems would not get updated with new password information until the next time the /etc/passwd file is updated, so some sort of automatic transfer or monitoring should be set up.

This method has several other, perhaps undesirable, side effects:

1. Because it replaces the /etc/passwd file on the client systems, any locally defined entries will be removed. Also, it will change the root entry to be that of the master.

2. It will change the loghost for the clients to the system defined in the /etc/hosts file of the master system.

3. Local mail alias information will be replaced in favor of the master system's definitions.

4. Local group definitions will also be replaced by the master definitions.

Transferring Automounter Mapping Files

Caution should be used when transferring automounter mapping files (/etc/auto.master, /etc/auto.home, and /etc/auto.direct), whether the transfer is being done with rdist or NIS. A file system recursion problem will result if a client is also a file server whose exported file system appears in one of the maps. If this is the case, you must provide different maps to NFS servers. This can be done using rdist on the master system and specifying different source and destination paths.

For example, assume that rudolf is an NFS server for the /opt file system. The /opt file system contains a bunch of applications, so of course, every workstation needs to access it. As the system administrator for these systems, I want to have the /opt file system automounted, but I don't want it to appear in the auto.direct file for rudolf. Also, I want to maintain the auto.direct file for rudolf on santa.

rdist to the rescue again! Listing 3 shows you how to modify the distfile example for this situation. You will see that I removed /etc/auto.direct from the list of NIS_FILES, and created a new package called maps. I also created a new macro called MAP_HOSTS, which does not contain rudolf. The map package has two transfer definitions in it. One transfers /etc/auto.direct to the MAP_HOSTS, and the other transfers /sysadmin/auto.direct.rudolf to rudolf, and installs it as /etc/auto.direct.

Now, to get the system files transferred using the nis package alone you would type:

rdist nis

on santa, while in the /sysadmin directory. If the /etc/passwd file alone had changed, the screen would look something like this:

santa:/sysadmin> 2 # rdist nis
updating host dasher
updating: /etc/passwd
updating host dancer
updating: /etc/passwd :
updating host rudolf
updating: /etc/passwd

rdist displays a message for each host, followed by an update message for each file transferred. If a file did not already exist, the message would say "installing" rather than "updating." One advantage of using rdist over writing a script for this sort of file tranfer is that the file is not transferred if there have been no changes.

Other Uses for rdist

Another good use for rdist is keeping root account files like .login and .cshrc consistent from system to system. Suppose you are responsible for fifty remote systems and periodically need to rlogin to them as root. Remote system administration can be difficult when you have different aliases, environment variables, etc., set up on each system. The root environment can be even more of a problem if workstation owners can change these files. Now you can use rdist to ensure that the .login and .cshrc files remain in sync on every system! Just add the package definition to the distfile as shown in Listing 4.

Since this use of rdist is a good candidate for routine automatic transfer, Listing 5 shows an example of a crontab entry which would execute the root package every Monday morning at 7:00 A.M.

Here's another example of rdist's capabilities. Suppose you administer a master server that maintains utilities for a large client base, including other master servers on different domains. Making sure that clients have the most up-to-date versions of these utilities while keeping them from NFS mounting across gateways can be quite a hassle.

Since it is capable of maintaining entire directories, rdist can easily solve this problem, and, in fact, there is an example in the rdist man page. The tough part is defining which servers the clients will be allowed to mount the directory from, and then making sure the master that has the current utilities has root login privileges, as discussed earlier.

Whether you use it to distribute files and directories on an as-needed basis, or to routinely synchronize important system files, rdist can be a powerful tool for administering remote systems. The rdist utility has several other capabilities that are described in the man page. It can compare a file's timestamp to a timestamp file in order to determine if the file needs to be transferred, save a file as a particular user on the remote machine, notify a specified user about files transferred and errors encountered, and it can even execute a command after each file is transferred. These capabilities are beyond the scope of this article, but now that you know the basics, you are well on your way to understanding the rest!

Abouth the Author

Judith Ashworth was first exposed to the UNIX operating system in 1983 while working for the University of Texas at Austin Computation Center, and has been working with UNIX solidly since 1989. Since that time she has done both GUI (Graphical User Interface) application development and UNIX system administration. She is currently working for Sun Microsystems Customer Services, where she does UNIX System Installation, Consulting, and Software Support.