ups v4 Installation/Upgrade Summary

History:

18 November 1998: add instructions to make sure that the correct version of perl is being used when ups_convert is called to convert the old ups databases.
16 September 1998: clarify what is needed in beta testing upd.
12 August 1998: and clean up a few more points of confusion noticed at the second ups fest. Added some sample configurations for the initial portion to help prevent typos and make things go more smoothly.
7 August 1998: correct a few other minor omissions noticed by Wayne Baisley.
4 August 1998: correct a few typos noticed by Alan Jonckheere and Maureen Mihalek. Update the versions of ups and upd referenced herein. Be explicit about creating new partitions if necessary.
8 July 1998: reorganize to make use of environmental variables instead of /path/to/place syntax, after feedback from the [first?] ups fest. Add "dropit" and "funame" backwards compatible links.
7 July 1998: add link to "fill-in-the-blank checklist"
24 June 1998: minor formatting corrections; prevent confusion by renaming old-style ups and upd product declarations in the new database; emphasize that start/stop modifications must be made on a per-machine basis.
12 June 1998: add FUE recommendations regarding /usr/local/etc/setups.[c]sh compatibility for on-site machines.
4 June 1998: correct template file paths and directories for updconfig.template
19 May 1998: add caveat about the time it takes for "ups declare -c perl" (lots of man pages)
18 May 1998: initial public release.

Abstract:

This document is a quick summary of the steps required to successfully upgrade from ups v3.x (or earlier) to v4_x. The more detailed and explanatory ups installation document should be read before attempting any ups upgrades!

Get a good backup.
Prepare "back-door" /usr/local/etc/fermi.ups1.[c]shrc and /usr/local/etc/setups1.[c]sh files.

cd /usr/local/etc
cp setups.sh  setups1.sh
cp setups.csh setups1.csh
cp fermi.shrc  fermi.ups1.shrc
cp fermi.cshrc fermi.ups1.cshrc
${EDITOR} fermi.ups1.shrc		# change setups.sh -> setups1.sh
${EDITOR} fermi.ups1.cshrc		# change setups.csh - setups1.csh

Create any new required disk partitions such as /fnal/ups. If this area is NFS mounted on other nodes, add it to your mount maps and/or automount configuration. Add it to your backup schemes.

Know where your new ups databases should live, and what they should look like.
Especially important: SETUPS_DIR, UPD_USERCODE_DIR, PROD_DIR_PREFIX, and product root file hierarchy naming conventions. (Use the fill-in-the-blank checklist to help).

These sample configurations scripts may be enormously helpful! They include pre-typed commands for "typical" configurations:

A typical /fnal/ups hierarchy:
- sh family
- csh family
A typical /usr/products hierarchy:
- sh family
- csh family
A typical ~products hierarchy:
- sh family
- csh family

If you download one of these, you can edit it much more easily than typing in all of the commands shown below!

#############################################################
#  Set the following environmental variables as appropriate.
#  CHANGE THE FOLLOWING TO MATCH YOUR CONFIGURATION FROM THE
#   FILL-IN-THE-BLANK CHECKLIST!
#  For [t]csh users, syntax is 
#    setenv VARIABLE value
#############################################################

OLD_PRODUCTS=/usr/products/ups_database/declared; export OLD_PRODUCTS
OLD_STARTUP=/usr/products/ups_database/startup; export OLD_STARTUP
OLD_SHUTDOWN=/usr/products/ups_database/shutdown; export OLD_SHUTDOWN

#
# Use the naming conventions for YOUR cluster!!!
#
PROD_DIR_PREFIX=/fnal/ups; export PROD_DIR_PREFIX
NEW_PRODUCTS=${PROD_DIR_PREFIX}/db; export NEW_PRODUCTS
SETUPS_DIR=${PROD_DIR_PREFIX}/etc; export SETUPS_DIR

UPS_CONFIG_DIR=${NEW_PRODUCTS}/.upsfiles; export UPS_CONFIG_DIR
UPD_USERCODE_DIR=${NEW_PRODUCTS}/.updfiles; export UPD_USERCODE_DIR
NEW_STARTUP=${UPS_CONFIG_DIR}/startup; export NEW_STARTUP
NEW_SHUTDOWN=${UPS_CONFIG_DIR}/shutdown; export NEW_SHUTDOWN
STATISTICS=${UPS_CONFIG_DIR}/statistics

MAN_TARGET_DIR=${PROD_DIR_PREFIX}/man; export MAN_TARGET_DIR
CATMAN_TARGET_DIR=${PROD_DIR_PREFIX}/catman; export CATMAN_TARGET_DIR
INFO_TARGET_DIR=${PROD_DIR_PREFIX}/Info; export INFO_TARGET_DIR

#
# Use the appropriate flavor for the machine you're using!
#
OS_FLAVOR=IRIX+5; export OS_FLAVOR

#
# Use the naming conventions for YOUR cluster!!!
#
UPS_VERSION=v4_2; export UPS_VERSION      # Use most recent version!
NEW_UPS_ROOT=ups/${UPS_VERSION}/${OS_FLAVOR}; export NEW_UPS_ROOT
NEW_UPS_DIR=${PROD_DIR_PREFIX}/${NEW_UPS_ROOT}; export NEW_UPS_DIR

#
# Use the naming conventions for YOUR cluster!!!
#
PERL_VERSION=v5_004; export PERL_VERSION  # Use most recent version!
NEW_PERL_ROOT=perl/${PERL_VERSION}/${OS_FLAVOR}; export NEW_PERL_ROOT
NEW_PERL_DIR=${PROD_DIR_PREFIX}/${NEW_PERL_ROOT}; export NEW_PERL_DIR

#
# Use the naming conventions for YOUR cluster!!!
#
UPD_VERSION=v4_2_4; export UPD_VERSION    # Use most recent version!
NEW_UPD_ROOT=upd/${UPD_VERSION}/NULL; export NEW_UPD_ROOT
NEW_UPD_DIR=${PROD_DIR_PREFIX}/${NEW_UPD_ROOT}; export NEW_UPD_DIR

Obtain and unwind the most recent tarfiles for ups, upd, and perl.

#############################################################
#  Create the parent product root directories
#############################################################
mkdir -p ${NEW_UPS_DIR}
mkdir -p ${NEW_UPD_DIR}
mkdir -p ${NEW_PERL_DIR}

#############################################################
#  Unwind the products into these directories.
#############################################################

Create and configure the new ups and upd database(s).
The ups-mkdir script can be downloaded and invoked to make all of the directories if you've set the appropriate environmental variables (it's easier than typing all of the "mkdir" commands in the section below).

#############################################################
#  Create the ups database and associated directories
#  (Do this for each db)
#############################################################
mkdir -p ${NEW_PRODUCTS} 
mkdir -p ${UPS_CONFIG_DIR}
mkdir -p ${UPD_USERCODE_DIR}
mkdir -p ${SETUPS_DIR}
mkdir -p ${NEW_STARTUP}
mkdir -p ${NEW_SHUTDOWN}
mkdir -p ${STATISTICS}
chmod -R g+w ${NEW_PRODUCTS}
chmod 777 ${STATISTICS}

mkdir -p ${MAN_TARGET_DIR}
mkdir -p ${CATMAN_TARGET_DIR}
mkdir -p ${INFO_TARGET_DIR}
chmod g+w ${MAN_TARGET_DIR} ${CATMAN_TARGET_DIR} ${INFO_TARGET_DIR}

#############################################################
#  Create the dbconfig file, using a template
#  (Do this for each db)
#############################################################
cd ${UPS_CONFIG_DIR}
cp ${NEW_UPS_DIR}/ups/dbconfig.template ./dbconfig
${EDITOR} ./dbconfig

#############################################################
#  Create the list of ups databases, using a template
#  (Only for the SETUPS_DIR from the db containing ups)
#############################################################
cd ${SETUPS_DIR}
cp ${NEW_UPS_DIR}/ups/upsdb_list.template ./upsdb_list
${EDITOR} ./upsdb_list

#############################################################
#  Configure upd, using a template
#  (Only for the db containing upd)
#############################################################
cd ${UPD_USERCODE_DIR}
cp ${NEW_UPD_DIR}/ups/updusr.pm.template ./updusr.pm
cp ${NEW_UPD_DIR}/ups/updconfig.template ./updconfig
${EDITOR} ./updconfig

#############################################################
#  Copy any existing ups start/stop scripts
#  (Only for the db containing ups)
#############################################################
cp ${OLD_STARTUP}/*  ${NEW_STARTUP}
cp ${OLD_SHUTDOWN}/* ${NEW_SHUTDOWN}

Convert all old ups databases.

#
# make sure you're using the new perl:
#
PERL_DIR=${NEW_PERL_DIR}; export PERL_DIR
. ${PERL_DIR}/ups/setup.sh
#
# make sure you're using the new ups:
#
UPS_DIR=${NEW_UPS_DIR}; export UPS_DIR
OLD_PRODUCTS=/usr/products/ups_database/declared; export OLD_PRODUCTS
PRODUCTS=${NEW_PRODUCTS}; export PRODUCTS
#
# perform the conversion:
#
${UPS_DIR}/bin/ups_convert

# then, once you have converted, get rid of the declarations of
#  the OLD ups and the OLD upd:

cd $PRODUCTS
mv ups ups.old			# prevent confusion with old ups
mv upd upd.old			# prevent confusion with old upd

Declare for beta testing.

#
# Prevent confusion if you're in a Bourne-shell family
cd $HOME; mv .shrc .shrc-save	# prevent confusion

#
# Set UPS_SHELL to sh or csh, whichever family you're using now
#
UPS_SHELL=sh; export UPS_SHELL              # or setenv UPS_SHELL csh
UPS_DIR=${NEW_UPS_DIR}; export UPS_DIR      # or setenv UPS_DIR ${NEW_UPS_DIR}
PRODUCTS=${NEW_PRODUCTS}; export PRODUCTS   # or setenv PRODUCTS ${NEW_PRODUCTS}

. ${UPS_DIR}/ups/setup.sh                   # or source ${UPS_DIR}/ups/setup.csh
   

${UPS_DIR}/bin/ups declare \
         -r ${NEW_UPS_DIR} \            # or use NEW_UPS_ROOT for portability
         -2 \                  		# equivalent to -f OS.major-release
         -m ups.table \        		# new requirement!
         ups ${UPS_VERSION}

${UPS_DIR}/bin/ups declare \
         -r ${NEW_PERL_DIR} \		# NEW_PERL_ROOT will NOT work at present - bug in perl "configure" script
         -2 \                  		# equivalent to -f OS.major-release
         -m perl.table \       		# new requirement!
         perl ${PERL_VERSION}

${UPS_DIR}/bin/ups declare \
         -r ${NEW_UPD_DIR} \		# or use NEW_UPD_ROOT for portability
         -0 \                  		# equivalent to -f NULL
         -m upd.table \        		# new requirement!
         upd ${UPD_VERSION}

Beta test (if desired). You will need to declare perl "current" in order to beta test upd (because ups depends on the "current" version of perl), or you can use the "-j" switch when you setup upd (and manually setup perl):

###################################################
#
# sh family syntax for configuring a process
#   so that it can beta test:
#
###################################################
unset UPS_DIR PRODUCTS
unset setup unsetup ups
UPS_DIR=/path/to/your/ups_dir		# the value you used for ${NEW_UPS_DIR}
PRODUCTS=/path/to/your/db		# the value you used for ${PRODUCTS}
UPS_SHELL=sh
export UPS_DIR PRODUCTS UPS_SHELL
. $UPS_DIR/ups/setup.sh

#
# then continue with typical ups commands:
#
setup ups ${UPS_VERSION}
ups list -aK+
ups verify -a ups
...

#
# to test upd before perl is declared current:
#
setup perl ${PERL_VERSION}
setup -j upd ${UPD_VERSION}
upd list -aK+
...

###################################################
#
# csh family syntax for configuring a process
#   so that it can beta test:
#
###################################################
unsetenv UPS_DIR PRODUCTS
unalias setup unsetup ups
setenv UPS_DIR /path/to/your/ups_dir	# the value you used for ${NEW_UPS_DIR}
setenv PRODUCTS /path/to/your/db	# the value you used for ${PRODUCTS}
setenv UPS_SHELL csh
source $UPS_DIR/ups/setup.csh

#
# then continue with typical ups commands:
#
setup ups ${UPS_VERSION}
ups list -aK+
ups verify -a ups
...

#
# to test upd before perl is declared current:
#
setup perl ${PERL_VERSION}
setup -j upd ${UPD_VERSION}
upd list -aK+
...

######################################################
#
# You may prefer to declare perl "current" before you
#  beta test upd.  (see below for the correct syntax)
#
######################################################

Go Live.

${UPS_DIR}/bin/ups declare -z ${NEW_PRODUCTS} -c -2 ups ${UPS_VERSION}
${UPS_DIR}/bin/ups declare -z ${NEW_PRODUCTS} -c -2 perl ${PERL_VERSION}
${UPS_DIR}/bin/ups declare -z ${NEW_PRODUCTS} -c -0 upd ${UPD_VERSION}

${EDITOR}/usr/local/etc/fermi.cshrc	# change /usr/local/etc/setups.csh 
                                        #   the VALUE of $SETUPS_DIR/setups.csh
					#   (e.g., /fnal/ups/etc/setups.csh
					#   or    /usr/products/etc/setups.csh)
${EDITOR}/usr/local/etc/fermi.shrc	# change /usr/local/etc/setups.sh 
                                        #   the VALUE of $SETUPS_DIR/setups.sh
					#   (e.g., /fnal/ups/etc/setups.sh
					#   or    /usr/products/etc/setups.sh)

Make backwards compatible setups.* links in /usr/local/etc.
(Don't do this if SETUPS_DIR is set to /usr/local/etc!)

cd /usr/local/etc
rm setups.sh
rm setups.csh

ln -s ${SETUPS_DIR}/setups.sh  ./setups.sh
ln -s ${SETUPS_DIR}/setups.csh ./setups.csh

Make backwards compatible funame and dropit links in /usr/local/bin.

cd /usr/local/bin
rm funame
rm dropit

ln -s ${NEW_UPS_DIR}/bin/funame ./funame
ln -s ${NEW_UPS_DIR}/bin/dropit ./dropit

On each machine, modify any system boot files that call the old ups startup scripts.
Look for ups calls in /etc/init.d (or /etc/rc.local for AIX). Change path from old startup directory to new startup directory.

#
# Example for IRIX system:
#
cd /etc/init.d
grep ups *		# look for any files containing calls to
			#   ups_startup or ups_startup.sh or 
			#   ups_startup.csh
			# Edit those file, changing the path
			#   to the VALUE of the NEW_STARTUP_DIR
			#   (e.g., /fnal/ups/db/.upsfiles/startup 
			#   or /usr/products/db/.upsfiles/startup, etc.)

Reboot all nodes using these ups databases.
Not strictly necessary, but strongly recommended. In any case, all users should log out at this point; processes that were started in the OLD ups environment will be hopelessly confused (and will issue strange ups-related error messages) in the NEW ups environment.
Update table files.
Documentation not yet available.