PSR: Installation Instructions

• Installation
• Usage

Installation

1. First, obtain and expand OpenPBS. It is not necessary to configure or install OpenPBS yet, since you will be patching its source.

2. Download the PSR package from the LAM download page.

3. Expand the PSR distribution:

      unix% gunzip -c psr-1.2.tar.gz | tar xf -
   

   or

      unix% uncompress -c psr-1.2.tar.Z | tar xf -
   

4. Change into the psr-1.2 directory and run the configure script. You will need to specify whether to use the Transarc or krb4 libraries, as well as specify the location of several files. The flags available to configure are listed below:

   --with-transarc[=DIR]	Use the Transarc-provided development libraries and header files. If DIR is not provided, /usr/afsws is used.
   --with-krb4[=DIR]	Use the freeware krb4 AFS libraries. If DIR is not provided, /usr/local is used.
   --with-rsareflib=DIR	Specify the location of rsaref.a. If this flag is not specified, /usr/local/lib is used.
   --with-rsarefinc=DIR	Specify the location of rsaref.h. If this flag is not specified, /usr/local/include is used.
   --prefix=DIR	Specify the location where to install PSR. If this flag is not specified, /usr/local is used.

5. Run "make". GNU make is not necessary.

6. Run "make install" to install the following files:

      $prefix/bin/dauthr
      $prefix/bin/dauth_shepherd
      $prefix/bin/mkpsrauthkeys
      $prefix/bin/pwstore
   

   The first two are used internally by the PSR (i.e., launched automatically by the PBS MOM) to get a token and refresh it as necessary. These two files need to be available at the same location on every compute node in PBS.

   mkpsrauthkeys is used to make public/private key pairs for system administrators. pwstore is used by users to encrypt their plain-text passwords to a given public key.

      $prefix/lib/libpsr_afs.a
      $prefix/lib_libdauthr.a
      $prefix/include/psr_config.h
   

   These library and header files will be used in building the PBS MOM.

      $prefix/share/psr/resmom_openpbs_2.3.psrpatch
   

   This file is used to patch the OpenPBS source code to automatically launch and kill the PSR support programs.

7. Apply the PBS patch in the top-level OpenPBS directory:

      unix% cd top-pbs-dir
      unix% patch -p0 < $prefix/share/psr/resmom_openpbs_2.3.psrpatch
   

8. Configure, build, and install OpenPBS as normal.

Usage

1. The PSR binaries must be installed on each node that they will be invoked by PBS.

2. System administrators can use the "mkpsrauthrkeys" program to generate a public/private key pair. It may take a few minutes; be patient. Options available:

   -v	Be verbose.
   -p publikckeyfile	Save the public key in this file. If this argument is not specified, `hostname`.pubkey is used.
   -s secretkeyfile	Save the secretkey in this file. If this argument is not specified, /etc/psr_auth.seckey is used.
   -n keyname	Give a name for the keys. If this argument is not specified, the hostname where mkpsrauthrkeys is run is used.

   Example:

      unix% mkpsrauthrkeys -n "lab_pbs_cluster" \
   	 -s lab.secret -p lab.public
   

3. The secret key must be installed on all the compute nodes in /etc/psr_authr.seckey. The permissions must be 0600.

4. The public key should be installed in some well-known and publicly available location.

5. Users run the "pwstore" command to encrypt their password and store it in $HOME/.psr_authr/KEYNAME. The KEYNAME is from the "-n" argument that was given to mkpsrauthrkeys. pwstore does not attempt to make the $HOME/.psr_authr directory -- if this directory does not exist, saving the encrypted key will fail.

   pwstore does not attempt to make this directory because the wide variety of acceptable permissions that should be assigned to this directory (whether AFS or Unix) can vary widely for different sites. As such, it is recommended that a script be used to "wrap" access to the pwstore command that checks for the existence of the $HOME/.psr_authr directory, runs pwstore with the appropriate public key, etc. A sample script for this purpose can be found in pbs/sample_pwstore_script. With this script, each user only has to run "sample_pwstore_script" and enter their AFS password. No confusing command line options need to be specified.

   The following options are available to pwstore:

   -v	Be verbose.
   -e encryptedfile	Specify where to save the encrypted password. If this option is not specified, $HOME/.psr_authr is used.

   The public key file must be given as a command line arugment. Example:

      unix% pwstore -v -e $HOME/.psr_authr/mypw.seckey \
   	 /usr/local/share/psr/lab.public
   

6. When the user submits a job, the PBS MOM will fork off the PSR executable which will automatically decrypt the password and use it to obtain an AFS token. A quick way to ensure that everything is working is to submit an interactive job and run the "tokens" AFS command to see if you obtained an AFS token properly.