information on
environment variables that affect execution of the command or are
affected by it

a list of internal
functions the command performs (if more extensive than suggested by
the command description)

command examples

23.1 setup

Issue the setup command
for a product prior to invoking the product. The setup command
performs the necessary operations in your login environment to make
an installed, declared product instance accessible to you.
Typically, the operations include modifying environment variables
or adding to your $PATH.

Prints out extra debugging information.
(-vv for more, -vvv for even more)

-V

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-z
<databaseList>

Specifies the database(s) in which to look
for the product and its dependencies

-Z

Times the command (does not include time for
sourcing of temp file for setup)

-.

shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table"

The flavor options

Flavor may be specified using
-f,
using -H by itself or
in combination with any of the valid numbers or just using one of the valid
numbers.
These options are not valid with each other (except -H with a number
option).

If a dependency is specified
in the table file with a particular flavor, the flavor specified on
the command line is ignored for that dependency.

Table 23.1.3-b:

-f
<flavor>

Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but
UPS looks only at the first in the list.

-H
<flavor>

Useful to set the host to a different type, such as when
installing products for another platform. Can be used in combination
with the valid flavor numbers, 0, 1, 2, ...

If it is used without an accompanying
number,
UPS finds the best match instance for the specified flavor
family. (The first one that matches in the ups flavor -l command.)

-0

Specifies flavor for operating system generic to NULL.

-1, -2, -3, -4, -5

Specifies flavor for operating
system generic, starting with basic OS, and adding details with each
increase in number for Basic OS + version + release + patch + build.

23.1.4 More Detailed
Description

In general,
UPS products require that the setup command be
issued on a product instance before invoking it (unless it is a
dependent product of one that is already setup). The setup
processes are intended to make the appropriate changes to the user's
software environment to make the requested product
available for use.

Only one instance of a product
can be setup at a time. Each time you run setup on an
additional instance of the same product, the previously active
instance is automatically unsetup first.

Internal Processes

Check node
authorization

If necessary, process
UNSETUP action

Process SETUP
action

Source the temp
file

Environment Variables
Set by Default During setup

When an instance is setup,
either or both of the two environment variables
$<PRODUCT>_DIR and $SETUP_<PRODUCT> may get defined. By
default, both do.

$<PRODUCT>_DIR

points to the root directory of the product instance selected
by the setup
command

$SETUP_<PRODUCT>

a string containing all the information that the unsetup command
needs in order to identify the instance when it is time to remove
access to the product

In both of them,
<PRODUCT> is the name of the product in upper case. Using
the product
upd (on the fermicloud050) as an example:

% setup upd
% echo $UPD_DIR

/fnal/ups/db/../prd/upd/v4_8_0/NULL

% echo $SETUP_UPD

upd v4_8_0 -f NULL -z /fnal/ups/db

Use of the
$SETUP_<PRODUCT> Variable by unsetup

unsetup uses the
environment variable $SETUP_<PRODUCT>, by default, to
determine which instance to unsetup. If this variable was
not set during product setup (i.e., the setup default
functions were not run, or
setupEnv() was not run), then when you run unsetup, you
must specify on the command line which instance to unsetup; running
simply unsetup
<product> causes no action to be taken. See
Use of the $SETUP_<PRODUCT> Variable under section
23.2
unsetup for more information regarding the unsetup
command.

23.1.5 setup
Examples

In the following examples, when we say that all dependencies of a
product get set up, we mean all except optional dependencies that
are unavailable.

Setup default instance
of product

% setup git

This sets up the current
instance of the product
git for the best match flavor of your OS. If the product
has any dependencies, they get setup too, by default.

% setup -v git

This command sets up the same
instance as above, but displays verbose information (usually used
for debugging, but useful to see what's going on). If any file that
is "opened for read" does not exist, you'll see ERROR at the end of the line. This
is often but not always a fatal error. The output looks like
this:

Restrict the setup of
dependent products

Use of the -R option sets
up the specified product and its required dependencies only.

% setup -j ruby

Use of the -j option sets
up only the specified product; none of its dependencies get
setup.

Setup a chained instance
(other than the default "current")

% setup -t prod1
% setup -g test prod1

Either of these commands sets
up the instance of
prod1 chained to "test" (for the default flavor). To setup any
chained instance other than current, include the chain flag in the
command.

Setup a product
specifying its version

% setup prod1 v5_23a

This command sets up version
v5_23a of
prod1 whether or not it has a chain. Run a ups list command
to get the version information.

Setup a product declared
with qualifiers

% setup -q BUILD prod1

This command sets up the
current instance of
prod1 for the operating system on which you're working,
along with its build dependencies (assuming the qualifier BUILD has
been implemented in the product files in the standard way, see
section 17.2.3
Products Requiring Build (In-House and
Third-Party)).

Remember that qualifiers are case-sensitive.

Setup a product and
activate extended functionality

To setup the instance of
product
prod1 chained to development, and all of
prod1's dependencies, and to activate extended setup
actions, enter:

% setup -d -e prod1

The -e option sets
$UPS_EXTENDED on for
prod1 and for any of its
UPS product requirements that were declared with the
-e
option. This is used to activate any extended functionality the
product provider may have included in the setup action for this
instance (e.g., defining extra environment variables).

23.2 unsetup

The unsetup command
makes the specified product no longer available for use. It undoes
the changes made to the environment by setup. You may
need to explicitly unsetup a
UPS product if you are short on environment variable space
and want to get rid of extra environment variables or shorten the
$PATH variable length; otherwise you typically don't need to run
this command.

Requires
UPS to rely only on information supplied on the command line
to locate the product instance (prevents
UPS from searching in a database)

-q
<qualifierList>

qualifiers : colon separated list of required or optional qualifiers
that are to be part of the instance

-r
<prodRootDir>

Specifies the product root directory

-s

Lists what command would do; but does not
execute the command

-t

Finds product instance chained to
"test"

-U
<upsDir>

Specifies location of ups directory; default value is
ups

-v(vv)

Prints out extra debugging information, vv for more, vvv for more.

-V

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-z
<databaseList>

Specifies the database(s) in which the
product(s) are declared

-Z

Times the command (does not include time for
sourcing of temp file for setup/unsetup)

.

shorthand for
-r `pwd` -M ups -m ${UPS_PRODUCT}.table

23.2.3 More Detailed
Description

unsetup is
intended to undo the changes to your software environment made
during product setup. It makes the product no longer available for
use. You may need to explicitly unsetup a
UPS product if you are short on environment variable space
and want to get rid of extra environment variables or shorten the
$PATH variable length. Unsetup gets done automatically for you when
you setup a different instance of the same product.

When you no longer need to
access a product, in most cases you can simply type:

% unsetup <product>

for example:

% unsetup prod1

Sometimes this isn't
sufficient. The $SETUP_<PRODUCT> variable governs the
behavior, as described below.

Use of the
$SETUP_<PRODUCT> Variable

unsetup uses the
environment variable $SETUP_<PRODUCT>, by default, to
determine which instance to unsetup. If this variable was
not set during product setup (i.e., the setup default
functions were not run, or
setupEnv() was not run), then you must specify on the
command line which instance to unsetup; running simply unsetup
<product> causes no action to be taken.

If $SETUP_<PRODUCT> has
been set (the usual case), it is best to run unsetup with no
options (except possibly -j as discussed
below). If any instance-identifying information besides product
name is specified on the unsetup command
line, this information gets ignored.

Behavior of unsetup for
Product Dependencies

The behavior of unsetup as
regards product dependencies depends upon a couple of factors:

whether an UNSETUP
action exists in the main product's table file

whether
$SETUP_<PRODUCT> has been defined for the product
dependency

If ACTION=UNSETUP is defined
for the main product, then:

if it includes
the function unsetupRequired
for the dependency with
no instance-identifying information (e.g., unsetupRequired
(<dep_product>) only; no options or version), and if
$SETUP_<PRODUCT> is defined for the dependency, unsetup will be
run on the instance identified by $SETUP_<PRODUCT>.

if it includes
the function unsetupRequired
for the dependency with
no instance-identifying information (e.g., unsetupRequired
(<dep_product>) only; no options or version), and if
$SETUP_<PRODUCT> is
not defined for the dependency, no unsetup will be
performed for the dependency.

if it includes
the function unsetupRequired
for the dependency with some instance-identifying information
(e.g., unsetupRequired -q
"build" <dep_product>), then unsetup is run
on this specified instance of the product dependency; if
$SETUP_<PRODUCT> is defined for the dependency, it is
ignored.

If ACTION=UNSETUP is
not defined for the main product, then:

if
$SETUP_<PRODUCT> is defined for the product dependency, then
unsetup will be
run on the instance identified by $SETUP_<PRODUCT>.

if
$SETUP_<PRODUCT> is
not defined for the dependency, no unsetup will be
performed for the dependency.

If you use the -j option in the
unsetup command
of the main product, only the main product gets unsetup; its
product dependencies are left untouched.

Internal Processes

Check node
authorization

Process UNSETUP
action

Source the temp
file

The UNSETUP default functions
are to undo the default SETUP functions (i.e., unset
$<PRODUCT>_DIR and $SETUP_<PRODUCT>).

Note: If there is no UNSETUP
action, then unsetup undoes
everything done in SETUP action. However, if SETUP includes
non-reversible functions, these cannot be undone by unsetup.

23.2.4 unsetup
Examples

% unsetup lxr

This command unsets the product
lxr. When you no longer need to access a product, in most
cases you can simply use the product name to identify it.

% unsetup -j ruby

The -j option in
this command causes
UPS to unsetup the product, while leaving all its dependencies setup.

23.3 ups configure

For any product instance whose
table file includes a CONFIGURE action, the ups configure
command executes this action. A CONFIGURE action usually includes
functions to construct symbolic links, copy files, or perform
automatic local customization of the product. The ups configure
command gets run by default by ups declare when
the product is initially declared to a database (see section
23.5
ups declare, in particular the -C option), but
can be run manually as needed (e.g., on nodes of different
flavors).

23.3.1 Command
Syntax

% ups configure [<options>] <product> [<version>]

23.3.2 Commonly Used
Options

Table 23.3.2-a:

-f
<flavor>

A valid number or -H (alone or with a valid number)

-g
<chainName>

Or one of -c, -d, -n, -o, -t

-q
<qualifierList>

colon separated list of required or optional qualifiers
that are to be part of the instance

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-z
<databaseList>

Specifies the database(s) in which to look
for the product and its dependencies

-Z

Times the command (does not include time for
sourcing of temp file for setup/unsetup)

.

shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table

23.3.4 More Detailed
Description

Installation/configuration
procedures that can be completely automated are typically collected
in the table file in a CONFIGURE action (actions
are described in Chapter 34:
Actions and ACTION Keyword Values), or in a script
called configure which
is called from the table file. The configuration may involve
creating links to the product root directory from other areas. If
the area is not identical for each machine flavor accessing the
UPS database in which the product instance has been declared
(i.e., the same path but separate areas), then you will need to run
the ups
configure command manually once per flavor, on a node of
that flavor. If each node mounts a unique area, you generally have
to run special commands (e.g., ups install,
ups
initialize, etc.) that are documented in the product's
INSTALL_NOTE file. If
you are not sure whether you need to configure a product instance
on each flavor/node, look through the configuration steps in the
table file to see what they do.

Internal Processes

Check node
authorization

Process CONFIGURE
action

Execute temp file

23.3.5 ups configure
Examples

Assuming prod1
is a product that requires ups configure to
be run manually for each machine flavor in a cluster. The sample
command, which should be issued from a machine of flavor Linux+2
runs the CONFIGURE action in the table file associated with the
product
prod1, version v1_6_4 for flavor Linux+2.

% ups configure prod1 v1_6_4 -f Linux+2

A
command like this, but with the appropriate flavor, must be run for
each machine flavor represented in the cluster.

23.4 ups copy

The ups copy command
was designed as a
UPS product development tool allowing a new instance of a
product to be declared "like" another.

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-W

Uses environment variables (e.g.,
$SETUP_<PRODUCT>) to identify dependent product instances for
target product (that is, it uses instances that are already setup
in preference to what is listed in table file)

-X

Executes the ups declare
command instead of just echoing it

-z
<databaseList>

Specifies the database(s) in which to look
for the product and its dependencies

-Z

Times the command

23.4.4 Options Valid
with -G

In order to distinguish the
target product instance from the source, the declarations for the
two instances must differ by at least one instance-identifying
element. The -G option
provides the means to specify the target instance identifiers; it
takes a list of ups declare
command line elements as an argument. Any identifier not specified
via -G retains the
value of the source instance. The elements valid for use with
-G
include <product>,
<version>
and the following subset of the ups declare
options:

See section 23.5
ups declare for details on each option. If the argument
to -G includes the
product version, the product name must be included ahead of the
version; the first unflagged element is always interpreted as the
product name and the second as the version.

23.4.5 More Detailed
Description

The command ups copy is
intended mainly for product developers declaring new instances on
their development systems. It simplifies declaration of new
instances of products that already exist in a
UPS database. There is no restriction against using
ups
copy to copy the installation of a different product,
however it's usually not particularly helpful in that
situation.

Notes:

ups copy runs
ups
declare if you use the -X (uppercase
-x)
option; if not used, the declare command is just echoed.

Use the -G option to
specify declaration information that is to be different from the
installation you're using as a model. At least one
instance-identifying element must be specified using -G to
distinguish the source from the target instance.

If you use the option
-W,
you will pick up the current environment. For example, if the
previously declared instance depends on v1_0 of some product (e.g.,
joe v1_0), but the new instance should have
joe v2_0 as a dependency, first run setup joe v2_0,
then run ups copy with
-W.

Internal Processes

Process COPY
action

Create a table file
entry for new instance (may use environment for
UPS product requirements)

23.4.6 ups copy
Examples

This command runs a
ups
copy command for
dog version v3, without the -X option so
that the ups declare
command just gets echoed, not executed. The -G argument here
gives the product name and version plus options to be used by the
ups
declare command: the flavor (-f Linux+2), a
qualifier (-q test), the
table file name and location (given via -m and
-M),
and the product root directory (given via -r). The command
output looks like this:

Specifies table file directory; when
initially declaring a product, sets the keyword TABLE_DIR. Specify
only if file is not in one of the two default locations, namely
under $PRODUCTS/<product> or in the
ups directory.

-n

Chains the product instance to "new"; when
this chain gets declared, the corresponding ACTION=NEW in the table
file gets executed, if it exists.

-o

Chains the product instance to "old"; when
this chain gets declared, the corresponding ACTION=OLD in the table
file gets executed, if it exists.

-O
"<flags>"

Sets the value of $UPS_OPTIONS to
<flags>.

-q
<qualifiers>

When initially declaring a product,
-q
specifies required and/or optional qualifiers to include in the
declaration, and sets the keyword QUALIFIERS.

A note for developers: you may find it
convenient to use the construction -r \pwd\ if
you're working in the product root directory.

-t

Chains the product instance to "test"; when
this chain gets declared, the corresponding ACTION=TEST in the
table file gets executed, if it exists.

-T <path or
URL>

Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. When
initially declaring a product, it sets the keyword
ARCHIVE_FILE.

-u
<compileDir>

Specifies the directory for the output file
(which is named via the -b option) for
the ups
compile command; sets the keyword COMPILE_DIR.

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-z
<databaseList>

Specifies the database in which to declare
the product (see section 27.1
Database Selection Algorithm); or, if adding a chain,
specifies the database(s) in which product is declared

-Z

Times the command

23.5.4 More Detailed
Description

Declaring an Instance
for the First Time

In the ups declare
command:

-C prevents
execution of the CONFIGURE action, if any, and is normally not
included. The default (and usually desired) behavior is to execute
the CONFIGURE action.

You must include a
flavor specification, there is no default flavor when a product is
first declared. It sets the value of the FLAVOR keyword.

Most products require a table file. The table
file must exist before running ups declare. In
most cases you need to include the table file name (-m). (Since in a
very few cases a table file isn't required, -m is not a
strictly required option.)

If the product's table
file was placed in either of the two default locations (under
/path/to/database/<product>
or in the product's ups
directory), then -M
<table_file_dir> is not needed. Only use the
-M
option if you have moved the table file to a separate location
where
UPS won't otherwise find it.

In most cases you need
to include product root directory (-r). Exceptions
include wrapper products which consist only of a table file, and
thus have no product root directory.

If the product's
ups directory tar file
was unwound in the default location ($<PRODUCT>_DIR/ups), then
-U
<ups_dir> is not needed. If the ups directory is located elsewhere
(or named differently), this specification must be included. In
general, you should not include this qualifier.

If you choose not to
specify the target database explicitly (-z
<database>),
UPS chooses it automatically via the $PRODUCTS variable. If
$PRODUCTS points to multiple databases, you need to be a little
careful about database selection. The database matching algorithm
is described in section 27.1
Database Selection Algorithm.

If the product has
dependencies that are declared in different databases,
UPS must be able to find all of them in order to resolve the
dependencies. You can rely on $PRODUCTS if all the necessary
databases are included in it. Otherwise specify them on the command
line (e.g., -z
<database1>:<database2>:...> or -z
$PRODUCTS:<database1>:<database2>:...).

You may include chain
information on this command. See the description below.

Adding Chains to an
Existing Instance

When you add one or more chains
to an existing instance,
UPS doesn't allow you to change anything else about that
instance. Regarding the options to specify:

You of course need to
specify the chain or chains to add using either -g
<chain_name> or one of -c, -d, -n, -o, -t.

-C prevents the
corresponding chain action(s) in the table file from being
executed.

23.5.5 ups declare
Examples

Declare a product with
no chain using defaults where possible

UPS
finds the product in the directory given by the -r option, and
declares it to a database in $PRODUCTS according to the selection
algorithm discussed in 27.1
Database Selection Algorithm. The product instance gets
declared with the specified name, version and flavor, and no
qualifiers.
UPS looks for the table file, called myprod.table in the two default
locations (command fails if table file doesn't exist, or is not
found in either location).

Declare a product with
no chain using defaults where possible

For this example, we assume the
local machine flavor is FictionalOS+a.b.
UPS finds the product in the directory given by the
-r
option. The specified path is taken relative to PROD_DIR_PREFIX.
UPS declares the product to one of the listed databases
according to the selection algorithm discussed in 27.1
Database Selection Algorithm. Each of the dependencies,
if any, must exist in at least one of the listed databases.

The product instance gets
declared with the specified name, version, no qualifiers, and the
chain "test". The flavor declaration is the level -2 specification
of the machine, namely FictionalOS+a.
UPS looks for the table file, called myprod2.table in the two default
locations (command fails if table file doesn't exist, or is not
found in either location).

Add a chain to a
previously declared instance

This command declares the
product instance of the previous example "current" (via the
-c
option). Generally, a product is first declared as "test", and then
after a "debugging period" (often several weeks), an updated
release is cut and chained to "current". Notes:

In most
UPS/UPD commands you specify either chain (often defaulted
to "current") or version. Here you need both: the version is
required to identify the instance, and the chain is required
because it is being assigned.

You should specify the
database /my/local/db
first since that's how it was initially declared.
UPS will traverse the databases in the same order to find
the right instance.

23.6 ups depend

The ups depend
command lists product dependencies of the specified product
instance(s) as declared in the (local) database. On user nodes it
is generally used to determine what products will get setup along
with the "parent" product.
UPD uses it on product servers to determine what
dependencies to install.

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-z
<databaseList>

Specifies the database(s) in which to look
for the product and its dependencies

-Z

Times the command

23.7.4 More Detailed
Description

The ups exist
command is used to test whether a setup command
issued with the same command line elements is likely to succeed. As
for all the
UPS/UPD commands, if the setup command
finds a corresponding action in the selected table file, it

translates the
functions listed under the action into shell commands,

writes them to
a temporary script in $TMPDIR (if $TMPDIR isn't set, the default is
/tmp), and

invokes the
script to execute the shell commands.

ups exist checks
for a properly declared matching instance, and verifies that you
have the necessary permissions to create the temporary script. If
so, it creates the script, but it does not execute it.

ups
exist sets the $? variable to 0 if it was able to create the
temporary file, or to 1
for error.

This command is rarely used
from the command line, and is more useful in scripts where a failed
setup could cause the script to abort. When issued from the command
line, it returns no output if the command succeeds.

Internal Processes

Check node
authorization

If necessary, process
UNSETUP action

Simulate SETUP
action

23.7.5 ups exist
Examples

This command is rarely used
from the command line, and is more useful in scripts where a failed
setup could cause the script to abort. When issued from the command
line, it returns no output if the command succeeds.

ups
exist sets the $? variable to 0 if it was able to create the
temporary file, or to 1
for error. As an example, we can run ups list and
find that there is a current instance of the product
prod1 for the flavor FictionalOS+a but not for FictionalOS+a.b. Running
ups
exist for each flavor, we see that the variables get set
accordingly.

$ ups exist prod1 -f FictionalOS+a; echo $?

0

$ ups exist prod1 -f FictionalOS+a.b; echo $?

1

23.8 ups flavor

The ups flavor
command with no options returns the flavor of the machine. If a
flavor level is specified (e.g., -0, -1 ...), it
returns the flavor according to that level. ups flavor
generates a flavor table if the -H option is
used. The flavor levels and the term
flavor table are defined in section 23.8.4
More Detailed Description.

23.8.3 All Valid
Options

Specifies host flavor family from which to
build a flavor table. If used with any of -0, -1, -2, -3, -4, -5, specifies
corresponding level of specified host flavor family.

-l

Produces a flavor table.

-v(vvv)

Prints out extra debugging information.

-Z

Times the command.

-0

Specifies flavor as NULL

-1

Pick flavor for operating system generic to the vendor

-2

Pick flavor for operating system to level of major version number

-3

Pick more specific flavor for operating system (includes start of
minor version numbers)

-4

Pick still more specific flavor for operating system (includes more
of minor version numbers)

-5

Pick most specific flavor for operating system (includes all of
minor version numbers)

23.8.4 More Detailed
Description

The ups flavor
command returns flavor information about the machine issuing the
command, or for a flavor requested via the -H option. When
entered with no options, the command returns the full OS
specification of the machine.

When entered with the
-l
(long) option, ups flavor
returns what we call a
flavor table, which is a list including every level of
specificity for a flavor that you could use to find or declare a
product instance. For example, on novagpvm02, it
outputs:

If -H
<flavor> is used with -l, ups flavor
builds a flavor table for the flavor given by -H. This is
useful if you're not sure what levels are allowable for a
particular basic flavor. The flavor table lists flavors starting at
the level you specify. Compare the following two commands and
output:

You can specify a particular
level using the number options, with the highest number being the
most specific.

23.8.5 ups flavor
Examples

Find full flavor
specification of machine

% ups flavor

This command returns the full
OS specification of the machine up to the build number for the patch
(when these levels of specification exist), for example:

Linux64bit+2.6-2.5

Create a flavor table
for machine's OS

% ups flavor -l

This command returns a flavor
table for the flavor of the machine. For example, on a (fictional)
Linux+2.6 machine it outputs:

Linux+2.6.1-4
Linux+2.6.1
Linux+2.6
Linux+2
Linux
NULL
ANY

Find flavor
specification of machine, at different levels

% ups flavor -4

The -4 option
requests the machine's flavor as the most significant OS
specification or the full specification, e.g.,:

Linux+2.6.1

% ups flavor -3

The -3 option
requests the machine's flavor as basic OS and version and release, e.g.,:

Linux+2.6

The -2 option
requests the machine's flavor as basic OS and version, e.g.,:

Linux+2.6

% ups flavor -1

The -1 option
requests the machine's flavor as the OS value up to the generic OS,
e.g.,:

Linux

% ups flavor -0

This always returns the NULL
string.

Create a flavor table
for host flavor, at different levels

% ups flavor -lH FictionalOS+a.6

This creates a flavor table
listing flavors starting at the level specified via -H, in this case
"level 3":

FictionalOS+a.6
FictionalOS+a
FictionalOS
NULL
ANY

% ups flavor -lH FictionalOS+a

This creates a flavor table
listing flavors starting at the level specified via -H, in this case
"level 2":

FictionalOS+a
FictionalOS
NULL
ANY

23.9 ups get

The ups get command
is rarely used by anyone except product developers/maintainers. It
t just scans the all actions for a product (setup, etc. in the table file) and looks
for things that are files, and lists them.

The ups get command
was designed primarily for use by
UPD, which calls it internally. As such it is rarely used
outside of that context.

23.9.1 Command
Syntax

% ups get -F [<other_options>] <product> [<version>]

23.9.2 All valid
options

Table 23.9.2-a:

-? ("-?" for
csh)

Prints command description and option usage
information to screen

-c

Finds product instance chained to
"current"

-d

Finds product instance chained to
"development"

-f
<flavor>

Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but
UPS looks only at the first in the list.

-F

Prints to screen a list of files that are
associated with the product but which are maintained external to
the products area (excluding table file)

-g
<chainName>

Finds product instance chained to
<chainName>

-H
<flavor>

Specifies flavor and builds a flavor list for
that family starting at the level specified.
UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but
UPS looks only at the first in the list.

23.10 ups help

The ups help command
lists all the
UPS commands with brief definitions. There are no options
for this command.

23.10.1 ups help
Example

% ups help

UPS commands:
for specific command options use "ups COMMAND -?"
configure : Environmentally configure a product instance.
copy : Allow one instance of a product to be declared "like" another.
declare : Add a product instance or a chain to a UPS Database.
depend : List (for a specified UPS product instance) UPS product
requirements or all UPS product instances that have the
specified UPS product instance as a requirement.
exist : Determine if a setup command with the same options
would likely succeed.
flavor : Print flavor of a machine, optionally by level, or table
generated for searching
get : Return a list of all files that are needed by a product
instance and do not live under the product root directory.
help : Output help information for all UPS commands
list : List UPS Database information about product instances.
modify : Allow editor modification of the UPS Database files.
The altered files are verified before being rewritten.
setup : Prepare the environment in order to be able to use a product
instance.
start : Perform any necessary actions for a product instance at system
boot.
stop : Perform any necessary actions for a product instance at
system shutdown.
tailor : Perform any product instance tailoring that needs to be done
once (specify hardware device location) or needs user input.
touch : Will change a ups file modify time (MODIFIED) to current time
(it will probaly also change the modifier (MODIFIER)).
unconfigure : Undo any actions performed by the configure command.
undeclare : Remove a product instance from a UPS Database.
if chain(s) are specified ONLY the chain(s) will version will
be removed
unsetup : Return the environment to a pre-setup state.
verify : Check the specified instances for correct formatting and
information.

23.11 ups list

The ups list command
returns information about the declared product instances in a
UPS database. Two output styles are provided: a formatted
one that is easy for users to read, and a condensed one for parsing
by a subsequent command or a script.

Prints out extra debugging information.
(-vv for more, -vvv for even more)

-z
<databaseList>

Specifies the database(s) in which to look
for the product and its dependencies

-Z

Times the command (does not include time for
sourcing of temp file for setup)

-.

shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table"

23.11.4 More Detailed
Description

ups list is
useful for finding out what products are in the database that you
use, what the current version of a product is for your machine's
flavor, and other information. Product installers and other
administrative users can use it to get detailed information about a
product's installation and to find product files.

You can specify the information
you want contained in the output by including various options in
the command. As is standard in
UPS, if no chain, version or flavor is specified, and
-a
(for all instances) is
not specified,
UPS returns only the instance declared as current for the
best-matched flavor of the requesting machine.

Formatted Output
Style

One output style is for visual
parsing (this is the default output, which we call
formatted), with output that looks like:

Notice that the product name,
version, flavor, qualifiers and chain(s) are the default fields
that get returned. The database (first line of the output) is
included as a header, not as part of the per-instance data. Each
piece of data returned for an instance is preceded by its keyword
for identification.

You cannot choose arbitrary
output fields for the selected instances using this output format.
However, you can use the -l option to
give an exhaustive listing of information contained in the
UPS database about the requested product.

If $PRODUCTS contains multiple
databases, output is returned for each one and labelled
accordingly, for example:

Notice that more than one instance
of the product may exist for a given database.

Condensed Output
Style

The other output format is a
script-readable (or
condensed) format, provided to allow parsing by a subsequent
command. Use the -K option to
request output in the condensed format. The -K option
requires an argument list specifying which fields to include in the
output, for example:

additional instance specification information
often used to indicate compilation options used by developer

CHAIN

product instance chain

+

all of the above

DATABASE (or DB)

the
UPS database path; useful if more than one on system

DECLARER

logon id of person who declared the
instance

DECLARED

date/time that product instance was
declared

MODIFIER

logon id of person who modified/updated the
instance

MODIFIED

date/time that product instance was
modified/updated

If $PRODUCTS contains multiple
databases, output is returned for selected products in all of them.
However, the database is identified for each output line only if
the keyword DATABASE or DB is included in the argument string
(e.g., -K+:DB requests
the standard output fields followed by the database path).

A few of the keywords allow
the "at" symbol, @ to be prepended, which provides a sort of
shorthand for long path names:

Table 23.11.4-b:

@PROD_DIR

entire path for the directory where the
product is installed (usually equivalent to
PROD_DIR_PREFIX/PROD_DIR)

@TABLE_FILE

entire path for the table file

@UPS_DIR

product's ups directory; if it is not an
absolute path, then it is taken relative to @PROD_DIR

The full list of keywords that
can be used with ups list -K and
upd list
-K follows, with descriptions:

product root directory prefix (area where all
or most product instances are maintained)

QUALIFIERS

additional instance specification information
often used to indicate compilation options used by developer

SETUPS_DIR

location of setups.[c]sh files and other
UPS initialization files

STATISTICS

flag to record statistics for specified
products

TABLE_DIR

location of table file

TABLE_FILE

name of table file

@TABLE_FILE

entire path for the table file.

UPD_USERCODE_DIR

Directory where
UPD configuration files are maintained

UPS_DIR

location of ups directory (if not absolute
path, then taken relative to PROD_DIR, usually)

@UPS_DIR

entire path to ups directory

VERSION

product version

23.11.5 ups list
Examples

List all current
products

% ups list

The simplest way to request a
listing of all the current products installed in your default
UPS database is to use the ups list command
with no options or arguments. The per-product output spans a few
lines, though, and can be cumbersome, e.g.,:

List standard
information for all instances of product for your machine's
flavor

% ups list -a2K+ git

To request information on all
instances of a product limited to the OS of your machine, you can
include the -f option (for
flavor), or enter a command like this one, where -a is for all,
-2
is for the "level 2" designation of your machine's OS, and
-K+
is for condensed output:

List all keywords for a
product (long listing)

% ups list minos -l

This command requests detailed
information (-l for long
listing) about the default instance of the product. Administrative users may often need this level of
detailed information about a product. The -l option is not
valid with the -K option. The
output looks like this:

ups list -K can
be used to locate a product's root directory, table file, and
ups directory when used
with the keywords corresponding to these quantities

Compare the following three
commands and their output. UPS_DIR
represents the location of the product's ups directory. If it is not an
absolute path, then it is taken relative to @PROD_DIR, if
specified (as shown in the second command). @UPS_DIR is the
absolute path.

Compare the following two
commands and their output. table_file
represents only the name of the table file, not its path.
@table_file is
the entire path for the table file. See section 29.4
Determination of ups Directory and Table File Locations
for information on how
UPS determines the table file directory.

Parse output from "ups
list -K" in perl

Here we provide guidance on
parsing ups
list output in
perl, with all the appropriate quoting and spacing. The
following example first defines the file handle UPS_LIST_OUTPUT to contain the
piped output of the command $UPS_DIR/bin/ups list
-aK+ (where $UPS_DIR is
translated inside of
perl via the $ENV{UPS_DIR}
statement, which is the translation of the environmental variable
UPS_DIR). It then defines the array @fields, and parses the output into
a set of five variables.

Parsing output from "ups
list -K" in a sh script

You can parse the output from a
command of the form ups list -K by
piping it into a "while
loop"
sh script. Here is an example; explanations follow the
code:

ups list -K... |
while read line
do
eval set : $line
shift
# now do things with $1 $2 $3...
done

As the condition of the
while loop, the read line
command reads the lines of output into the variable
line. To get rid of the quotes, the loop runs eval set : $line
on each line (this syntax ensures that the set command
actually sets the variables $1, $2, and so on, instead of setting
shell behavior in case the first argument starts with a dash). The
shift that
follows then gets rid of the colon.

23.12 ups modify

The ups modify
command allows you to manually edit any of the database product
files. It performs syntax and content validation before and after
the editing session.

23.12.3 All Valid
Options

Invokes the specified editor. If not given,
uses the editor specified by $EDITOR. If not set, uses
vi by default.

-f
<flavor>

Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but
UPS looks only at the first in the list.

-H
<flavor>

Specifies flavor and builds a flavor list for
that family starting at the level specified.
UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but
UPS looks only at the first in the list.

23.12.5 ups modify
Example

In this example, we select the
version file (via -N) for the
product
git v1_8_5_3. Since
-E
is not given,
UPS will use the editor set in $EDITOR, or
vi if that variable is not set. First,
UPS runs ups verify and
produces the output:

Pre modification verification pass complete.

No errors were detected. The
version file is next displayed in the editor.

To illustrate
an unsuccessful validation, we add a bogus line:

TESTKEYWORD = value and save and quit. UPS returns the following messages, and we opt to save the erroneous change:
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
Post modification verification pass complete.
Do you wish to save this modification [y/n] ? yUPS quits, saving the file as we requested.

To illustrate
successful validation, we'll correct the error introduced above. We
run the same ups modify
command.
UPS finds the error during the pre-edit validation:

INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
Pre modification verification pass complete. We remove the incorrect line from the version file, then save and quit. UPS displays the following message, and we elect to save the change (y):
Post modification verification pass complete.
Do you wish to save this modification [y/n] ? yUPS quits, saving the file as requested.

23.13 ups parent

The ups parent
command can be used to determine which products depend on the
specified product instance(s) as declared in the (local) database.
This command is useful when deciding whether a product instance can
be removed without causing problems for other products. If you need to look things
up frequently, you might want to run the command with the -a option, dump
the output to a file, and search in there.

23.14 ups start

The ups start
command is used to invoke appropriately configured products at
system boot time. This is used primarily for products that need to
load drivers, start daemons or perform other actions required at
boot time. This command is generally not run manually, rather it
gets executed from within a
UPS control file.

The ups stop command
(see section 23.15
ups stop) is used to stop products that are started this
way.

Run the command from a
control file

This command starts the default
instance of the product
ObjectCenter for the flavor Linux, and requests verbose
output (-v).

% ups start -v -f Linux ObjectCenter

If the logon id is
root, the line in the control file may look like:

ups start -v -f Linux ObjectCenter

If the logon id is other than
root, the line in the control file must look like:

/bin/su - products -c "ups start -v -f Linux ObjectCenter"

23.15 ups stop

The ups stop command
is used to stop appropriately configured products at system
shutdown. This command is generally not run manually, rather it
gets executed from within a
UPS control file, and operates on products that were invoked
using ups
start (see section 23.14
ups start). Typically, these products are ones which
need to load drivers, start daemons or perform other actions
required at boot time.

Installing a
UPS product to start and/or stop automatically, for which
you need to:

Determine if auto
start/stop feature is enabled

Determine if product is
appropriate for autostart

Edit control
file(s)

Restart the system

Internal Processes

Check node
authorization

Process STOP
action

Execute the temp
file

23.15.5 ups stop
Examples

Run the command
interactively

This command stops the default
instance of the product
apache:

% ups stop apache

It prints to screen a message
of the format:

Stopping Apache server for fnkits.fnal.gov on port 8000

Run the command from a
control file

This command stops the default
instance of the product
ObjectCenter for the flavor Linux, and requests verbose
output (-v).

% ups stop -v -f Linux ObjectCenter

If the logon id is
root, the line in the control file may look like:

ups stop -v -f Linux ObjectCenter

If the logon id is other than
root, the line in the control file must look like:

/bin/su - products -c "ups stop -v -f Linux ObjectCenter"

23.16 ups tailor

For any product instance whose
table file includes a TAILOR action, the ups tailor
command must be run manually at product installation time after the
product is declared to the database in order to execute this
action. A TAILOR action typically includes installation functions
which require input from the installer.

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-z
<databaseList>

Specifies the database(s) in which to look
for the product and its dependencies

-Z

Times the command (does not include time for
sourcing of temp file for setup/unsetup)

-.

shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table"

23.16.4 More Detailed
Description

Tailoring is the aspect of the
product implementation that requires input from the product
installer (e.g., specifying the location of hardware devices for a
software driver package). If the product requires tailoring, a file
is usually supplied in the format of an interactive executable
(script or compiled binary), and it is run via a function under the
ACTION=TAILOR line in the table file. Configure, tailor and other
supplemental installation scripts are usually maintained in the
product's $<PRODUCT>_DIR/ups directory.
You must explicitly tailor the product instance using the
UPS command ups tailor;
tailoring is
not performed automatically.

Tailoring is generally allowed
on any node of a cluster, however we strongly recommend that you
perform any node-specific tailoring from that node, or
flavor-specific tailoring from a node of that flavor to avoid
mismatches.

23.17 ups touch

The ups touch
command changes the values of the keywords MODIFIED and MODIFIER in
the version file to the current time and the current user,
respectively.

If you make any changes to a
product's database files by hand (e.g., not via ups modify), you
should run ups touch
afterwards.
You can also run it to prevent an update if you choose to run
upd
update on several product instances at a time.

23.18 ups
unconfigure

For any product instance whose
table file includes an UNCONFIGURE action, the ups unconfigure
command executes this action. An UNCONFIGURE action usually
includes functions that reverse, approximately or fully, the
functions run by the CONFIGURE action. The ups unconfigure
command gets run by default by ups undeclare
when the product is removed from a database (see section 23.19
ups undeclare, in particular the -C option), but
can be run manually as needed.

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-z
<databaseList>

Specifies the database(s) in which to look
for the product and its dependencies

-Z

Times the command (does not include time for
sourcing of temp file for setup/unsetup)

23.18.4 More Detailed
Description

A product's configuration may
involve creating links to the product root directory from other
areas (see section 16.1.3
Third-Party Products Requiring a Hard-Coded Path). If
the area is not identical for each node accessing the
UPS database in which the product instance has been declared
(i.e., same path but separate areas), then the ups configure
command needs to be run manually on each node that mounts a unique
area. Similarly, when removing such a product from a database, you
will need to run the ups unconfigure
command manually on each node. If you are not sure whether you need
to unconfigure a product instance on each node, look through the
ACTION=UNCONFIGURE steps in the table file to see what they do.

This command should take care
of the "unconfiguration" on all the machines of flavor Linux+2 in the cluster. A
command like this, but with the appropriate flavor, must be run for
each machine flavor represented in the cluster.

23.19 ups undeclare

The ups undeclare
command is used for two separate purposes:

to remove an
instance from a database (and optionally remove its product root
directory); the information that gets removed includes:

the version file, or the
portion of the version file, that pertains to the instance

any chain files, or the
portions of any chain files, that pertain to the instance

Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen

-z
<databases>

Specifies the database(s) to use

-Z

Times the command

23.19.4 More Detailed
Description

Removing a Product
Instance

Usingups undeclare
is the recommended procedure for removing product instances.
Removing them manually does not ensure that all the files get
deleted or that chains get updated properly, which can lead to a
fragmented products area.

To undeclare a product
instance, you must specify the
version of the instance, not its
chain, in the ups undeclare
command.
Specifying the chain removes only that chain, not the instance
itself. When an instance gets "undeclared", all information
pertaining to it is removed from the
UPS database in question; this includes:

the version file, or the
portion of the version file, that pertains to the instance

any chain files, or the
portions of any chain files, that pertain to the instance

You can also opt to remove the
product instance's directory tree starting from its root directory.
To do so, use one of the options -y or
-Y
(-y
queries you for confirmation, -Y does
not).

Before removing anything, you
should find out if any other products have the product instance in
question declared as a dependency. If so, you may want to reconsider removing
it. Removal of the product instance may affect the operation of its
parent products.

We recommend always including a
flavor option if you have a multi-flavor database.

The ups undeclare
command executes ups unconfigure
by default (the UNCONFIGURE process can be suppressed by using the
-C
option, however normally you want this process to execute).

Special case: If a product has a CONFIGURE action that modifies
files outside of its product root directory, and if this instance
is used by more than one node, flavor or file system, then you may
need to run ups undeclare or
ups
unconfigure on all of the nodes before removing the product
files on any node. Check the product's table file.

Removing a Chain from an
Instance

To remove a chain, include the
chain specification in the ups undeclare
command, but do not include the version. Including both the chain
and version is bound to be either redundant or incompatible, and
may result in removing the product declaration! We recommend always
including the -f
<flavor> option if you have a multi-flavored
database.

Internal Processes

Find database to
use

If necessary process
all appropriate `UNCHAIN' actions

Process the UNCONFIGURE
action

Process the UNDECLARE
action

If necessary delete the
product's home area

Execute the temp
file

23.19.5 ups undeclare
Examples

Undeclare an
instance

% ups undeclare -f Linux+2 tcl v8 -y

In this example, we undeclare
and remove current instance (by default) of the product
tcl v8 for the flavor Linus+2 (-f option) from
the default database. Notice that the version is included for
instance identification as required. We opt to remove the product
root directory after query (lowercase -y option):

Undeclare a chain

In this command, we remove the
"current" chain (-c option) from
the instance of
ximagetools declared as current for the flavor NULL
(-f
option). Notice that the version is not included!

If multiple flavor/qualifier pairs share the chain file in question
(in which case you need to specify the flavor/qualifier information
on the command line), only the portion of the chain file pertaining
to the specified instance will get removed; the file itself will
not be deleted.

23.20 ups verify

The ups verify
command checks the integrity of the database files for the
specified product(s), and lists any errors and inconsistencies that
it finds.

The ups verify
command gets run by ups modify
before and after file editing (see section 23.12
ups modify). ups verify can
also be run manually as needed.

Specifies the database(s) in which to look
for the product and its dependencies

-Z

Times the command (does not include time for
sourcing of temp file for setup/unsetup)

23.20.4 ups verify
Example

% ups verify -z $MYDB prod1

For this example, we have given
an erroneous value to the TABLE_FILE keyword in the version file
for this product. The command output shows:

ERROR: No instance matches were made between the
version file (/home/t1/aheavey/upsII/declared/prod1/v1_0.version) and the
table file (v1_1.table) for flavor (NULL) and qualifiers ()
ERROR: Possible UPS database (/home/t1/aheavey/upsII/declared) corruption in pro
duct 'prod1'.
ERROR: No instance matches were made between the chain file (/home/t1/aheavey/up
sII/declared/prod1/current.chain) and the version file (v1_0.version)
ERROR: Possible UPS database (/home/t1/aheavey/upsII/declared) corruption in pro
duct 'prod1'.