TN0091

Configuring a Local UPS Database
(While Still Using the Centrally Supported AFS database)

CD/OSS
Applications Support

Background:

To minimize duplicate effort in supporting software, a centally supported UPS database in AFS space is maintained by the product developers. Systems running AFS are encouraged to use the AFS ups database for the majority of their software needs. However, there are cases where a local ups database is needed in addition to the AFS ups database (locally maintained or developed software, different version requirements, etc.). This document describes the steps that are necessary in order to configure a local ups database while still using the AFS ups database.

A system in AFS space does not need to run the bootstrap procedure -- ups, upd, and perl are already available to you via the ups database in AFS space. This greatly simplifies the configuration process.

Note that the concepts in this document are equally applicable to local ups databases on machines in an NIS cluster with its own common NFS-mounted database -- with suitable modification to the particular details (replace /afs/fnal.gov/ups with the appropriate path to the NFS-mounted area, e.g., /fnal/ups).

A ups database is entirely defined by two files:

dbconfig:
Configures the ups information for this database. The most important elements are:

PROD_DIR_PREFIX
the path under which all product files live (e.g., $PARENT_DIR/prd)
SETUPS_DIR
the directory where FUE initialization scripts live (e.g., $PARENT_DIR/etc)
UPD_USERCODE_DIR
the directory containing upd configuration (e.g., $PARENT_DIR/db/.updfiles)

updconfig:
configures the upd information for this database. This defines the file hierarchy for the products installed into this database. The defaults from $UPD_DIR/ups/updconfig.template are generally sufficient.

If you want to create a database of your own on any system which already has ups/upd installed, you need to create [at least] these two files.

Decisions, Decisions:

To configure a local ups database, you need to make a few decisions:

What directory should contain the local ups database?
You can make your life much easier by choosing one of the 'standard' locations in common use at Fermilab (i.e., already included in the upsdb_list file in AFS space):
- /local/ups (standard naming convention provided by the Fermi RedHat Linux bootstrap for satellite nodes)
- /fnal/ups (standard naming convention provided by several bootstrap configurations for product server nodes)
- /usr/products (another popular naming convention)
- /usr/products/CMSUN1 (naming convention for CMS local databases)
If you choose a different location, you will need to perform some extra steps to ensure that $PRODUCTS includes your database.
What account should own these files?
A common default is the products account. In all subsequent documentation, we assume that ~products owns the local ups database and product files; make appropriate substitutions if you choose a different account.
What products do you want/need to install into your local ups database?
In particular, you need to decide if you want to maintain local copies of coreFUE (ups, upd, and perl).
Benefits of having coreFUE installed locally:
1. You will be able to use ups, upd and perl even when AFS space is unavailable. (You will only be able to setup the products that are installed into local filespace, however).
2. You are afforded more flexibility in your local database file naming conventions (i.e., you are not limited to one of the pre-configured well-known naming conventions recognized by AFS space).
Disadvantages of having coreFUE installed locally:
1. You will need to pay attention to the status of three additional products (ups, upd and perl) and update them as necessary.
2. You will probably forget to update ups and upd until they start having problems. You'll spend a lot of time calling the helpdesk, looking for problems with the AFS database, wondering what is broken -- and finally will remember that it's your local (and out-of-date) copy of ups/upd that is broken.
3. You will need to worry more about the perl files in /usr/local/bin.
4. You will probably forget to update perl (and the files in /usr/local/bin) until you start having strange problems. You'll spend a lot of time calling the helpdesk, looking for problems with the AFS database, wondering what is broken -- and finally will remember that it's your local (and out-of-date) copy of perl that is broken.
5. Your configuration will be more complicated.
We recommend that you not install local copies of coreFUE unless they are needed.

Configuring a Local ups database:

The following steps are sufficient to create a local ups database. The astute reader will notice that there are an infinite number of alternatives; these are, however, sufficient for most purposes.

Create the top-level directory. Make sure that your products account (or whoever should own the product files) can read and write to that directory. This is the directory under which all the ups database and the product files will reside. For all subsequent documentation, we will refer to this directory as $PARENT_DIR.

Log in as products and create the following directories:

   $ cd $PARENT_DIR			# fill in appropriately
   $ mkdir db				# contains the database
   $ mkdir db/.upsfiles			# local ups config goes here
   $ mkdir db/.updfiles			# local upd config goes here
   $ mkdir prd				# local product file hierarchy begins here
   $ mkdir man				# local man pages go here
   $ mkdir catman			# local catman pages go here

Create the UPS configuration for your local database.

   $ setup ups				# using the copy in AFS space!
   $ cd $PARENT_DIR/db/.upsfiles	# location of your local configuration
   $ cp $UPS_DIR/ups/dbconfig.template \   # copy the template dbconfig file
	./dbconfig			   #  to your area

Then edit your dbconfig file and replace /fnal/ups with your $PARENT_DIR (not necessary if you choose to use the /fnal/ups naming convention).

Create the UPD configuration for your local database.

   $ setup upd				# using the copy in AFS space!
   $ cd $PARENT_DIR/db/.updfiles	# location of your local configuration
   $ cp $UPD_DIR/ups/updconfig.template ./updconfig

In most cases the default updconfig file should be perfectly adequate.

Create the FUE initialization files for your system.
These are the files that will be called when users log in (or when other processes start) in order to initialize the FUE environment.
- If your configuration follows a well-known naming convention (/fnal/ups, /local/ups, /usr/products or /usr/products/CMSUN1) you can take advantage of the configuration already present (and maintained) in AFS space by creating symbolic links that you never need to modify again:
```
   $ cd $PARENT_DIR			# location of your local configuration
   $ ln -s /afs/fnal.gov/ups/etc ./etc	# your SETUPS_DIR is a link to AFS
```
  If you are creating the 'courtesy links', you should log in as 'root' and:
```
   $ cd /usr/local/etc
   $ ln -s /afs/fnal.gov/ups/etc/setups.csh ./setups.csh
   $ ln -s /afs/fnal.gov/ups/etc/setups.sh  ./setups.sh
```
- If your configuration does not conform to a well-known convention, please follow the instructions in the Additional Steps for Unfamiliar Naming Conventions.

Your local database is now configured and ready to be used as normal. You should reinitialize the FUE environment for your process by:

   $ unset PRODUCTS			# or 'unsetenv PRODUCTS'
   $ . $PARENT_DIR/setups.sh		# or 'source $PARENT_DIR/setups.csh'

Your $PRODUCTS environmental variable should now include both databases (with the local database coming before the AFS database).

Installing Products Into Your Local ups Database

Once you have created the dbconfig (for ups) and updconfig (for upd) configuration files, you are ready to use the copy of upd in AFS space to install whatever products are necessary on your system.

To install products locally:

   $ setup upd				# initialize upd
   $ upd install \			# install
	-z $PARENT_DIR/db \		#   into LOCAL database ONLY
	 ...			#

Note that if you omit the -z $PARENT_DIR/db (i.e., you default to $PRODUCTS), then any product dependencies which are already installed in AFS space will not be re-installed locally.

If you want a particular product to be 'self-sufficient' (i.e., all of the required pieces are available locally even in the absence of AFS), use the syntax
```
   $ upd install -z $PARENT_DIR/db product [version] ...
```
which will install the product and all of its dependencies into the local ups database (without even looking in AFS space to see if any of the components have already been installed there).
If you want to install only a particular product locally (e.g., for development) but you want to keep all of its dependencies in AFS space, use the syntax
```
   $ upd install -j -z $PARENT_DIR/db product [version] ...
```
This will install the parent product locally, without installing any of the dependent products.

Additional Steps for Unfamiliar Naming Conventions

If your ups database configuration does not conform to one of the well-known conventions in AFS space, you will need a way of making sure that your local ups database is included in $PRODUCTS. There are three ways to accomplish this:

Lobby to be added to the list of well-known conventions.
Send mail to ups@fnal.gov stating the name of the local ups database, and a good reason why it should be mentioned in the lab-wide AFS upsdb_list (list of known local databases). Visa and MasterCard accepted.
Use $UPS_EXTRA_DIR.
Make sure that everybody who needs access to your local ups database modifies all of their login scripts (and other scripts) to set the UPS_EXTRA_DIR environmental variable to your database before they source the setups.[c]sh script. This is a viable alternative if there is only a small community of people who need this database (e.g., a small group of developers on your local system).
For example:
```
   # cshell example of $UPS_EXTRA_DIR
   #
   setenv UPS_EXTRA_DIR /our/unfamiliar/local/db
   source /afs/fnal.gov/ups/etc/setups.csh
```
Any directories in $UPS_EXTRA_DIR will be prepended to the database directories listed in the upsdb_list file the first time you source the setups.[c]sh script. (Of course, you can always prepend the appropriate database to your $PRODUCTS manually at any time).
Install coreFUE locally.
Maintain your own version of the setups.[c]sh scripts by installing a local copy of the coreFUE product into your database:
```
   $ setup upd				# the copy from AFS space
   $ upd install \			# use the known upd to install
	coreFUE \			#   the coreFUE product
	-z $PARENT_DIR/db \		#   into your local database
	-G -c				#   and go 'current' immediately
```
Then make sure that your copy of the $SETUPS_DIR/upsdb_list contains all of the directories that you wish to include in $PRODUCTS (including the AFS ups database).
If you are creating the 'courtesy links', you should log in as 'root' and:
```
   $ cd /usr/local/etc
   $ ln -s $PARENT_DIR/etc/setups.csh ./setups.csh
   $ ln -s $PARENT_DIR/etc/setups.sh  ./setups.sh
```
Remember, you will need to keep these local copies of ups, upd, perl up to date!

Updating your /usr/local/bin

A very few fullFUE components still require files (or links to files) in /usr/local/bin. Whether you get these products from AFS space or from a local database, the process for updating your copy of /usr/local/bin is the same:
```
   $ source /usr/local/etc/setups.csh	# or '. /usr/local/etc/setups.sh'
   $ ups installAsRoot perl		#  programming shell
   $ ups installAsRoot tcsh		#  login shell
   $ ups installAsRoot bash		#  login shell
   $ ups installAsRoot python		#  programming shell
```
This document was created in January 2000 by llc.
History:
17May2000: replace "ups current" with "ups installAsroot" for perl, tcsh, bash, python; fix section on how to install main product locally but keep dependencies in AFS space.