Remote Deployment with Rdist

Last update: 27 Jan 2003

Introduction

The fact that our production UNIX environment is standalone and not transparent with the development environment provided by SCS, creates a great challenge to software deployment and maintenance. The main obstacle is the difficulty in automating file distribution from development platforms to remote production systems and the concerns in security. With the new release of Rdist (Remote File Distribution program) available that supports SSH protocol, it becomes feasible for us to realize the deployment in an automated manner. Rdist is a remote file distribution program that maintains identical copies of files over multiple hosts. It preserves the attributes of files (such as owner, group, access mode, modification time and etc.) if possible and can update programs that are executing. This document describes how this program can be utilized as a vehicle for our software deployment.

Rdist - Remote File Distribution

Rdist is a client sever program.

rdist

The client is rdist which reads commands from a configuration file Distfile to direct the updating of files and/or directories listed in the Distfile, similar to how make reads recipes from a Makefile. It is the Distfile that contains a sequence of entries, specifying files to be copied, destination paths, the destination hosts, and what operations to perform when updating.

rdistd

Rdistd is the server part for rdist. It is run on target (remote) host, triggered by rdist via ssh using the command:
       
    ssh host -l remuser rdistd -S  
where host is the name of target host, remuser is the name of user who makes the connection and, ristd is the rdist server program on the target host. The -S argument must be specified to prevent rdistd from being accidently started by users.

Together these programs provide a secure and controllable file distribution between hosts - a vehicle for the deployment.

Setup

Installation

The package is installed in
/afs/slac/g/cd/soft/package/rdist/rdist-6.1.5. 
and built for Solaris. The client is
/afs/slac/g/cd/soft/package/rdist/rdist-6.1.5/bin/rdist,
which you can run from any development UNIX machine. opi00gtw04 is a preferred platform well configured for our deployment. The server is rdistd, which is installed, for instance in
/usr/local/sbin
on the production PEPII gateway machines opi00gtw0[0-2]. Make sure /afs/slac/g/cd/soft/package/rdist/rdist-6.1.5/bin is in your PATH and ahead of /usr/bin and /bin; otherwise, the old version that comes with Solaris OS distribution and is in /usr/bin and /bin will be used. The old version of rdist has no support of SSH protocol.

The Transport Protocol

By default, Rdist uses rsh to make connections to the target hosts; however, the transport protocol can be specified at run-time on the command line. The latest distribution of Rdist comes with support of ssh. It is required by SLAC to use ssh to make connections to the target hosts. To use a transport program other than rsh, use -P option. An example to use ssh as the transport is

   rdist -P /usr/local/bin/ssh 
It is important to note that rdistd must be on the target host in the $PATH of the user who runs rdist; otherwise, use the -p option to set the path where rdistd is searched for on the target host. For instance, the rdistd server program is installed in /usr/sbin on PEPII gateway machines, thus
   rdist -P /usr/local/bin/ssh -p /usr/sbin/rdistd 
will make a connection via ssh and start rdistd on the target host.

Authorization

To automate the deployment without typing password, RSA based authentication is used. First, you need to generate your RSA key pair on a UNIX development machine (say flora). Log in using your afs account and issue the following command.
    ssh-keygen -t rsa1
Responds to all prompts with a return . Your public key will be saved in $HOME/.ssh/identity.pub.

This key must be then added to the authorized key list on the target machine, e.g. in ~cddev/.ssh/authorized_key on PEPII gateway machines. Ask the owner of cddev account (Kristi Luchini) to do the following:

Lastly, a public UNIX machine needs to be reconfigured as a deployment platform. Edit /etc/ssh/ssh_config and enable the following entry. This will be done by system admin.

 
  NoHostAuthenticationForLocalhost yes

Remote Deployment with Rdist

Message logging

Client rdist and server rdistd each maintain their own copy of log file. The -l logopts option to rdist instructs what logging options to use locally; the -L logopts option to ridst tells rdist what logging options to pass to rdistd running on the target machine. Logopts option controls what types of messages to log to what facilities. The form of logopts is like

         facility=types:facility=types... 
The valid facilities include stdout, file, and etc; the valid types of messages are change, debug, ferror, all and etc. For instance,
         -l stdout=change:file=/tmp/rdist.log=all
would send change message to standard output, all messages to the files /tmp/rdist.log.

Debug

One option is particularly useful for debug. With option -n, rdist will run and print the commands, but no actual action will be taken. This helps exam the syntax in Distfile and give you a chance to verify what is to be deployed and to where. It is highly recommended to use this option before you start formal deployment using rdist. Remember using -n !

-odistopts

Use -odistopts to specify how files to be updated on the target host. distopts is a comma separated list of options. See 'man rdist' for valid values. For instance, -oremove removes any files that exist on the target host but not in the master copy on the deployment host. This is very useful for maintaining truly identical copies between hosts. It is this option that is used in our filesystem sync procedure - essential for failover for PEPII gateway machines. One important option is -osavetargets, which saves file as file.OLD on the target host before it gets updated by deployment procedure. This can be used as a back-out.

Distfile

Use -f Distfile to specify the name of Distfile. The Distfile contains a sequence of entries that specify the files to be copied, destination paths, the destination hosts, and what operations to perform when updating. It is similar to Makefile from which make reads recipes. Each entry has one of the following formats:
  variable_name '=' name_list
  source_list '->' destination_list command_list
  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. For detail syntax, please read 'man rdist'.

Test

In the test below, I created a simple Distfile in /afs/slac/g/cd/soft/support/package/rdist/deployment. In the Distfile, I define opi00gtw00 as the remote host, a list of files (/u/cd/jingchen/test/*.dl) and a directory (/u/cd/jingchen/test/bin) in AFS to be deployed, followed by specifying installation of these files to /u1/jingchen/del on the remote host.




Jingchen Zhou

jingchen@slac.stanford.edu