TOC PREV NEXT
Fermilab CD logo Complete Guide and Reference Manual for UPS and UPD

Chapter Contents

Chapter 23: UPS Command Reference
  23.1 setup
    23.1.1 Command Syntax
    23.1.2 Commonly Used Options
    23.1.3 All Valid Options
    23.1.4 More Detailed Description
    23.1.5 setup Examples
  23.2 unsetup
    23.2.1 Command Syntax
    23.2.2 All Valid Options
    23.2.3 More Detailed Description
    23.2.4 unsetup Examples
  23.3 ups configure
    23.3.1 Command Syntax
    23.3.2 Commonly Used Options
    23.3.3 All Valid Options
    23.3.4 More Detailed Description
    23.3.5 ups configure Examples
  23.4 ups copy
    23.4.1 Command Syntax
    23.4.2 Commonly Used Options
    23.4.3 All Valid Options
    23.4.4 Options Valid with -G
    23.4.5 More Detailed Description
    23.4.6 ups copy Examples
  23.5 ups declare
    23.5.1 Command Syntax
    23.5.2 Commonly Used Options
    23.5.3 All Valid Options
    23.5.4 More Detailed Description
    23.5.5 ups declare Examples
  23.6 ups depend
    23.6.1 Command Syntax
    23.6.2 Commonly Used Options
    23.6.3 All Valid Options
    23.6.4 ups depend Examples
  23.7 ups exist
    23.7.1 Command Syntax
    23.7.2 Commonly Used Options
    23.7.3 All Valid Options
    23.7.4 More Detailed Description
    23.7.5 ups exist Examples
  23.8 ups flavor
    23.8.1 Command Syntax
    23.8.2 Commonly Used Options
    23.8.3 All Valid Options
    23.8.4 More Detailed Description
    23.8.5 ups flavor Examples
  23.9 ups get
    23.9.1 Command Syntax
    23.9.2 All valid options
    23.9.3 ups get Example
  23.10 ups help
    23.10.1 ups help Example
  23.11 ups list
    23.11.1 Command Syntax
    23.11.2 Commonly Used Options
    23.11.3 All Valid Options
    23.11.4 More Detailed Description
    23.11.5 ups list Examples
  23.12 ups modify
    23.12.1 Command Syntax
    23.12.2 Commonly Used Options
    23.12.3 All Valid Options
    23.12.4 More Detailed Description
    23.12.5 ups modify Example
  23.13 ups parent
    23.13.1 Command Syntax
    23.13.2 Commonly Used Options
    23.13.3 All Valid Options
    23.13.4 More Detailed Description
    23.13.5 ups parent Example
  23.14 ups start
    23.14.1 Command Syntax
    23.14.2 Commonly Used Options
    23.14.3 All Valid Options
    23.14.4 More Detailed Description
    23.14.5 ups start Examples
  23.15 ups stop
    23.15.1 Command Syntax
    23.15.2 Commonly Used Options
    23.15.3 All Valid Options
    23.15.4 More Detailed Description
    23.15.5 ups stop Examples
  23.16 ups tailor
    23.16.1 Command Syntax
    23.16.2 Commonly Used Options
    23.16.3 All Valid Options
    23.16.4 More Detailed Description
    23.16.5 ups tailor Example
  23.17 ups touch
    23.17.1 Command Syntax
    23.17.2 Commonly Used Options
    23.17.3 All Valid Options
    23.17.4 ups touch Example
  23.18 ups unconfigure
    23.18.1 Command Syntax
    23.18.2 Commonly Used Options
    23.18.3 All Valid Options
    23.18.4 More Detailed Description
    23.18.5 ups unconfigure Example
  23.19 ups undeclare
    23.19.1 Command Syntax
    23.19.2 Commonly Used Options
    23.19.3 All Valid Options
    23.19.4 More Detailed Description
    23.19.5 ups undeclare Examples
  23.20 ups verify
    23.20.1 Command Syntax
    23.20.2 Commonly Used Options
    23.20.3 All Valid Options
    23.20.4 ups verify Example


Chapter 23: UPS Command Reference


This chapter contains full usage information on all the UPS commands. In particular, for each command you will find:

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.

23.1.1 Command Syntax

% setup [<options>] <product> [<version>] 

23.1.2 Commonly Used Options

See section 23.1.3 All Valid Options for descriptions of each option.

Table 23.1.2-a:
-f <flavor>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-z <databaseList>

23.1.3 All Valid Options

Table 23.1.3-a:
-? ("-?" for csh)
Prints command description and option usage information to screen
-B <depProdName>= "<options>"
Specifies options to prepend to the setupRequired line (in table file) for the dependent product <depProdName>

-c
Finds product instance chained to "current"
-d
Finds product instance chained to "development"
-e
Sets $UPS_EXTENDED (to the value 1). This is useful for SETUP actions which call scripts.
-f <flavor>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-j
Ignores dependencies, sets up just specified top-level product
-k
Prevents execution of unsetup files prior to (subsequent) setup
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>. This is useful for SETUP actions which call scripts.
-P
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>
Finds product instance with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory
-R
Sets up only the required (non-optional) dependencies.
-s
Lists what command would do; but does not execute the command
-t
Specifies product instance chained to "test"
-U <upsDir>
Specifies location of ups directory; default value is ups (relative to the product root directory)
-v(vv)
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.
(no number)
Specifies flavor for operating system to the highest detail defied, 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

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:

UPSMAT: Searching UPS database - /fnal/ups/db
UPSFIL: /fnal/ups/db/.upsfiles/dbconfig - Open file for read
UPSFIL: /fnal/ups/db/.upsfiles/dbconfig - Read 6 item(s)
UPSMAT: Looking for Product = git
UPSMAT: Matching with Chain - current
UPSFIL: /fnal/ups/db/git/current.chain - Open file for read
UPSFIL: /fnal/ups/db/git/current.chain - Read 2 item(s)
UPSMAT:  get_instance: flavor Linux64bit+2.6-2.12 quals
Found one!
First post!
UPSMAT: Found 1 instances in /fnal/ups/db/git/current.chain
UPSMAT: Matching with Version v1_8_5_3 in Product git
UPSMAT: Using Flavor = Linux64bit+2.6-2.12, and Qualifiers =
(and much more)

Restrict the setup of dependent products

% setup -R ruby 

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.

23.2.1 Command Syntax

% unsetup [<options>] <product> [<version>] 

23.2.2 All Valid Options

Typically, this command is issued with no options.

Table 23.2.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"
-e
Sets $UPS_EXTENDED (to the value 1).
-f <flavor>
Described in "The flavor options".
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-j
Ignores dependencies, runs unsetup on just on top level product
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<options>"
Sets the value of $UPS_OPTIONS to <options>.
-P
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:

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

  1. 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>.
  2. 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.
  3. 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:

  1. if $SETUP_<PRODUCT> is defined for the product dependency, then unsetup will be run on the instance identified by $SETUP_<PRODUCT>.
  2. 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

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

-z <databaseList>
database : use this database to get instance information

23.3.3 All Valid Options

Table 23.3.3-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>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>.
-P
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>
Finds product instance with the specified qualifiers (required and/or optional)
-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(vvv)
Prints out extra debugging information.
-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/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

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.

23.4.1 Command Syntax

% ups copy -G "<ups_declare_options> <product> <version>" \ [<options>] <product> <version>  

23.4.2 Commonly Used Options

See section 23.4.3 All Valid Options for descriptions of each option.

Table 23.4.2-a:
-f <flavor>
A valid number of -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-G "<options>"

-q <qualifierList>

-r <prodRootDir>

-T <path or URL>

-W

-X

-z <databaseList>

23.4.3 All Valid Options

Table 23.4.3-a:
-? ("-?" for csh)
Prints command description and option usage information to screen
-A nodes
Authorized nodes
-b compileFile
compile file name (.sh and .csh will be added automatically)
-c
Finds source product instance chained to "current"
-C
don't do configure
-d
Finds source product instance chained to "development"
-D origin
products' master source file
-f <flavor>
-g <chainName>
Finds product instance chained to <chainName>
-G "<options>"
Specifies options to be passed to the ups declare command for target product instance; see below
-H <flavor>
-m <tableFileName>
Specifies table file name of source product instance
-M <tableFileDir>
Specifies table file directory of source product instance
-n
Finds source product instance chained to "new"
-o
Finds source product instance chained to "old"
-O "<options>"
Sets the value of $UPS_OPTIONS to <options>.
-p "description"
product description
-q <qualifierList>
Finds product instance on distribution node with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory of source product instance
-t
Finds source product instance chained to "test"
-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.
-u <compileDir>
directory of file to put compiled information into
-U <upsDir>
Specifies location of ups directory of source product instance; default value is ups
-v(vvv)
Prints out extra debugging information.
-V
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:

-A <nodeList>, -c, -d, -D <origin>, -f <flavor>, -g <chainName>, -n, -o, -O "<flagList>", -p "<description>", -q <qualifierList>, -t, -z <databaseList>, -0, -1, -2, -3, -4

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:

Internal Processes

23.4.6 ups copy Examples

% ups copy dog v1 -G "dog v3 -f Linux+2 -q test -m v3.table -M ups\ 
-r /path/to/dog/v3" 

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:

/var/tmp/baaa006ni_table_dog  
ups declare dog v3 -f "Linux+2" -q "test" -r "/path/to/dog/v3"\ 
 -U "ups" -m "v3.table" -M "ups" 

The second command is identical to the first example except that the -X option instructs it to execute the ups declare command:

% ups copy dog v1 -G "dog v3 -f Linux+2 -q test -r /path/to/dog/v3 \ 
-M ups -m v3.table" -X 

23.5 ups declare

The ups declare command is used for two separate purposes:

  1. to initially declare an instance to a database (and optionally add a chain at the same time)
  2. to add a chain to a previously declared instance

23.5.1 Command Syntax

For initially declaring an instance

% ups declare <flavor_option> -r <prodRootDir> [<other_options>] \ 
<product> <version> 

For declaring a chain

% ups declare <chain_option> [<other_options>] <product> \ 
<version> 

23.5.2 Commonly Used Options

See section 23.5.3 All Valid Options for descriptions of each option.

For initially declaring an instance

Table 23.5.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
-m <tableFileName>

-q <qualifierList>

-r <prodRootDir>

-z <databaseList>

For declaring a chain

Table 23.5.2-b:
-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>

-z <databaseList>

23.5.3 All Valid Options

Table 23.5.3:
-? ("-?" for csh)
Prints command description and option usage information to screen.
-A <nodeList>
Specifies nodes authorized to access the product; sets the keyword AUTHORIZED_NODES
-b <compileFile>
Specifies name of the output file for the ups compile command (described in Chapter 38: Use of Compile Scripts in Table Files); sets the keyword COMPILE_FILE
-c
Chains the product instance to "current"; when this chain gets declared, the corresponding ACTION=CURRENT in the table file gets executed, if it exists.
-C
When initially declaring a product, -C prevents execution of the CONFIGURE action.
When declaring a chain, -C prevents execution of the corresponding chain action.
-d
Chains the product instance to "development"; when this chain gets declared, the corresponding ACTION=DEVELOPMENT in the table file gets executed, if it exists.
-D "<origin>"
Specifies the product's master source file; sets the keyword ORIGIN (all spaces get removed from <origin> for the keyword value)
-f <flavor>
-g <chainName>
Chains the product instance to <chainName> (this is useful for user-defined chains). When any chain gets declared, the corresponding ACTION=<CHAIN_NAME> in the table file gets executed.
-H <flavor>
-L
Adds the STATISTICS keyword to the version file, thereby instructing UPS to keep statistics on this product instance.
-m <tableFileName>
Specifies table file name; when initially declaring a product, sets the keyword TABLE_FILE.
-M <tableFileDir>
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.
When adding a chain, -q specifies required and/or optional qualifiers to identify the instance.
-r <prodRootDir>
Specifies the product root directory; when initially declaring a product, sets the keyword PROD_DIR.
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.
-U <upsDir>
Specifies location of ups directory; default value is ups; when initially declaring a product, sets the keyword UPS_DIR
-v(vvv)
Prints out extra debugging information.
-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 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:

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:

Internal Processes

23.5.5 ups declare Examples

Declare a product with no chain using defaults where possible

% ups declare myprod v1_0 -f Linux+2 -m myprod.table \ 
            -r /path/to/myprod/v1_0/Linux+2 

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

% ups declare myprod2 v1_0 -2 -g test -m myprod2.table \
           -r myprod2/v1_0/FictionalOS+a -z /my/local/db:$PRODUCTS 

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

% ups declare myprod2 v1_0 -2 -g test -m myprod2.table \  
         -r myprod2/v1_0/FictionalOS+a -z /my/local/db:$PRODUCTS 
% ups declare myprod2 v1_0 -2 -c -z /my/local/db:$PRODUCTS 

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:

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.

23.6.1 Command Syntax

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

23.6.2 Commonly Used Options

See section 23.6.3 All Valid Options for descriptions of each option.

Table 23.6.2-a:
-f <flavor>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-j

-K <keywordList>

-l

-q <qualifierList>

-R

-z <databaseList>

23.6.3 All Valid Options

Table 23.6.3-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>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-j
Ignores lower level dependencies, finds direct dependencies of top level product only
-K <keywordList>
Returns values of specified keywords only; valid keywords are listed in section 28.4 List of Supported Keywords
-l
Produces a long listing including all the table file functions that would be executed in a setup command.
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-q <qualifierList>
Finds product instance with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory
-R
Lists only the required (non-optional) dependencies.
-t
Finds product instance chained to "test"
-U <upsDir>
Specifies location of ups directory; default value is ups
-v(vvv)
Prints out extra debugging information.
-V
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 search
-Z
Times the command

ups depend Examples

Execute command with qualifiers

The first example requests information for art v1_08_10 with qualifiers for art

% ups depend art v1_08_10 -q debug:e4:nu 

art v1_08_10 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4:nu
|__cetpkgsupport v1_04_02 -f NULL -z /nusoft/app/externals -g current
|__messagefacility v1_10_26 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |__fhiclcpp v2_17_12 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|     |__cetlib v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|        |__cpp0x v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|           |__boost v1_53_0 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|              |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__root v5_34_12 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4:nu
|  |__geant4 v4_9_6_p02 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__clhep v2_1_3_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__xerces_c v3_1_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__g4emlow v6_32 -f NULL -z /nusoft/app/externals
|  |  |__g4neutron v4_2 -f NULL -z /nusoft/app/externals
|  |  |__g4neutronxs v1_2 -f NULL -z /nusoft/app/externals
|  |  |__g4nucleonxs v1_1 -f NULL -z /nusoft/app/externals
|  |  |__g4photon v2_3 -f NULL -z /nusoft/app/externals
|  |  |__g4pii v1_3 -f NULL -z /nusoft/app/externals
|  |  |__g4radiative v3_6 -f NULL -z /nusoft/app/externals
|  |  |__g4surface v1_0 -f NULL -z /nusoft/app/externals
|  |__fftw v3_3_3 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|  |__gsl v1_16 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|  |__pythia v6_4_28 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:gcc48
|  |__postgresql v9_1_5b -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__python v2_7_5c -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |     |__sqlite v3_08_00_02 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__mysql_client v5_5_27 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q e4
|  |__xrootd v3_3_4 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |__libxml2 v2_9_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|__cppunit v1_12_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|__gccxml v0_9_20130621 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__cmake v2_8_8 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -g current
|__tbb v4_1_3 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4


The next example requests information for redmine

% ups depend redmine 
redmine v1_4_1 -f NULL -z /fnal/ups/db -g current
|__ruby v1_9_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__cvs v1_12_13 -f Linux+2 -z /fnal/ups/db
|__git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current
|__subversion local -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current

The -R option requests only the dependencies listed as "required." In both examples, all dependencies are required so the output is the same.

% ups depend -R redmine 
redmine v1_4_1 -f NULL -z /fnal/ups/db -g current
|__ruby v1_9_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__cvs v1_12_13 -f Linux+2 -z /fnal/ups/db
|__git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current
|__subversion local -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current

23.7 ups exist

The ups exist command is used to test whether a setup command issued with the same command line elements is likely to succeed. It was designed primarily for use in scripts.

23.7.1 Command Syntax

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

23.7.2 Commonly Used Options

See section 23.7.3 All Valid Options for descriptions of each option.

Table 23.7.2-a:
-f <flavor>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-j

-q <qualifierList>

-z <databaseList>

23.7.3 All Valid Options

Table 23.7.3-a:
-? ("-?" for csh)
Prints command description and option usage information to screen
-B <depProdName>= "<options>"
Specifies options to prepend to the setupRequired line (in table file) for the dependent product <depProdName>
-c
Finds product instance chained to "current"
-d
Finds product instance chained to "development"
-e
Sets $UPS_EXTENDED (to the value 1).
-f <flavor>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-j
Ignores dependencies, operates just on top level product
-k
Prevents execution of unsetup files prior to (subsequent) setup
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>.
-P
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>
Finds product instance with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory
-t
Finds product instance chained to "test"
-U <upsDir>
Specifies location of ups directory; default value is ups
-v(vvv)
Prints out extra debugging information.
-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

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

  1. translates the functions listed under the action into shell commands,
  2. writes them to a temporary script in $TMPDIR (if $TMPDIR isn't set, the default is /tmp), and
  3. 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

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.1 Command Syntax

% ups flavor [<options>] 

23.8.2 Commonly Used Options

See section 23.8.3 All Valid Options for descriptions of each option.

Table 23.8.2-a:
-f <flavor>
Or a valid number
-H <flavor>
Alone or together with a valid number
-l

23.8.3 All Valid Options

Table 23.8.3-a:
-? ("-?" for csh)
Prints command description and option usage information to screen.
-f <flavor>
Specifies flavor.
-H <flavor>
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:

% ups flavor -l 
Linux64bit+2.6-2.5
Linux64bit+2.6-2.4
Linux64bit+2.6-2.3
Linux64bit+2.6-2.2
Linux64bit+2.6-2.1
Linux64bit+2.6-2.0
Linux+2.6-2.5
(and many more)
NULL 
ANY 

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:

% ups flavor -lH FictionalOS+a.6 
FictionalOS+a.6
FictionalOS+a.5
FictionalOS+a.4
FictionalOS+a.3
FictionalOS+a.b
FictionalOS+a.1
FictionalOS+a.0
FictionalOS+a
FictionalOS
NULL 
ANY 
% ups flavor -lH FictionalOS 
FictionalOS 
NULL 
ANY 

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.
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-q <qualifierList>
Finds product instance with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory
-t
Finds product instance chained to "test"
-U <upsDir>
Specifies location of ups directory; default value is ups
-v(vvv)
Prints out extra debugging information.
-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

23.9.3 ups get Example

% ups get -F ups 

In the database on the machine used, the UPS product has a few files maintained outside of the product root directory. This command returns the output:

/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/current 
/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/uncurrent 
/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/unconfigure 

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.

23.11.1 Command Syntax

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

23.11.2 Commonly Used Options

See section 23.11.3 All Valid Options for descriptions of each option.

Table 23.11.2-a:
-a

-f <flavorList>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-K <keywordList>

-l

-q <qualifierList>

-z <databaseList>

23.11.3 All Valid Options

Table 23.11.3-b:
-? ("-?" for csh)
Prints command description and option usage information to screen
-a
Includes all instances.

-c
Finds product instance chained to "current"
-d
Finds product instance chained to "development"
-f <flavor>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-K
keywords : return information from these (colon-separated) keywords, "+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN(S)
-l
produce a long listing
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-q <qualifierList>
Finds product instance with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory
-t
Specifies product instance chained to "test"
-U <upsDir>
Specifies location of ups directory; default value is ups (relative to the product root directory)
-v(vv)
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:

%  ups list git

DATABASE=/nusoft/app/externals 
	Product=git	Version=v1_8_0_1	Flavor=Linux64bit+2
		Qualifiers=""	Chain=current

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:

% ups list git

DATABASE=/nusoft/app/externals 
	Product=git	Version=v1_8_0_1	Flavor=Linux64bit+2
		Qualifiers=""	Chain=current


DATABASE=/grid/fermiapp/products/common/db 
	Product=git	Version=v1_8_0_1	Flavor=Linux64bit+2
		Qualifiers=""	Chain=current

	Product=git	Version=v1_8_0_1	Flavor=Linux+2
		Qualifiers=""	Chain=current

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:

% ups list -K product:version:flavor git
"git" "v1_8_0_1" "Linux64bit+2" 
"git" "v1_8_0_1" "Linux64bit+2" 
"git" "v1_8_0_1" "Linux+2" 

The plus sign (+) argument, e.g., -K+, is a shorthand for requesting the default fields product:version:flavor:qualifiers:chain, for example:

% ups list -K+ git
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux+2" "" "current" 

Some common keyword arguments used with the -K option are:

Table 23.11.4-a:
PRODUCT
product name
FLAVOR
product instance flavor
VERSION
product version
QUALIFIERS
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:

Keyword
Description
ARCHIVE_FILE
archive file name/location; useful with upd list
AUTHORIZED_NODES
authorized nodes; "all nodes" represented by an asterisk (*) in output
CATMAN_SOURCE_DIR
location of catman files (formatted man page files) included with instance
CATMAN_TARGET_DIR
directory into which catman files are to be copied
CHAIN
chain name
COMPILE_DIR
directory in which the compile file resides
COMPILE_FILE
the name of the file containing compiled functions (see Chapter 38: Use of Compile Scripts in Table Files)
@COMPILE_FILE
entire path to the file containing compiled functions
DECLARED
the date/time that the instance was declared to UPS or declared with a chain
Note: often has multiple values, one for each declaration (e.g., for subsequent chain declarations)
DECLARER
userid of user that performed the declaration
Note: often has multiple values, one for each declaration (e.g., for subsequent chain declarations)
DESCRIPTION
product description
FLAVOR
product instance flavor
INFO_SOURCE_DIR
location of Info files included with instance
INFO_TARGET_DIR
directory into which Info files are to be copied
MAN_SOURCE_DIR
location of unformatted man page files included with instance
MAN_TARGET_DIR
directory into which formatted man pages are to be copied
MODIFIED
last time the associated instance was changed
Note: often has multiple values, one for each declaration/modification (e.g., for subsequent chain declarations)
MODIFIER
userid of user that modified the instance
Note: often has multiple values, one for each declaration/modification (e.g., for subsequent chain declarations)
ORIGIN
master source file; see option -D in Chapter 25: Generic Command Option Descriptions
PRODUCT
product name
PROD_DIR
product root directory (usually defined relative to PROD_DIR_PREFIX, below)
@PROD_DIR
entire path to product root directory
PROD_DIR_PREFIX
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.,:

DATABASE=/nusoft/app/externals 
	Product=allinea_tools	Version=v4_1_1	Flavor=Linux64bit
		Qualifiers=""	Chain=current

	Product=cetpkgsupport	Version=v1_05_03	Flavor=NULL
		Qualifiers=""	Chain=current

	Product=cmake	Version=v2_8_8	Flavor=Linux64bit+2.6-2.5
		Qualifiers=""	Chain=current

... 
 
        	Product=ups	Version=v5_0_2	Flavor=Linux+2
		Qualifiers=""	Chain=current

	Product=ups	Version=v5_0_2	Flavor=Linux64bit+2
		Qualifiers=""	Chain=current

	Product=ups	Version=v5_0_2	Flavor=Linux+2
		Qualifiers=""	Chain=current

Use of the -K option with the + argument, e.g.,

% ups list -K+ 

provides the same information as the previous example, but condensed to one line per product:

"allinea_tools" "v4_1_1" "Linux64bit" "" "current" 
"cetpkgsupport" "v1_05_03" "NULL" "" "current" 
"cmake" "v2_8_8" "Linux64bit+2.6-2.5" "" "current" 
... 
"ups" "v5_0_2" "Linux+2" "" "current" 
"ups" "v5_0_2" "Linux64bit+2" "" "current" 
"ups" "v5_0_2" "Linux+2" "" "current" 

Instead of using the + argument to get the default fields, you can specify particular fields:

% ups list -K product:version 

This command outputs a list of product names and version numbers for all the current products installed in your default UPS database, e.g.,:

"allinea_tools" "v4_1_1" 
"cetpkgsupport" "v1_05_03" 
"cmake" "v2_8_8" 
... 
"ups" "v5_0_2" 
"ups" "v5_0_2" 
"ups" "v5_0_2" 

List standard information for default instance of product

% ups list nova 

This command requests the standard output fields for the default instance of nova, using the formatted output:

DATABASE=/nusoft/app/externals 

DATABASE=/grid/fermiapp/products/common/db 
	Product=nova	Version=v0.1	Flavor=NULL
		Qualifiers=""	Chain=current

Addition of the -K+ construction, e.g.,

% ups list -K+ nova 

requests the same information as the previous example, but in condensed format:

"nova" "v0.1" "NULL" "" "current"  

Using -a for all, e.g.,

List standard information for all instances of product

% ups list -a git 

requests the standard output fields for all instances of git, using the formatted output:

DATABASE=/nusoft/app/externals 
	Product=git	Version=v1_8_0_1	Flavor=Linux64bit+2
		Qualifiers=""	Chain=current


DATABASE=/grid/fermiapp/products/common/db 
	Product=git	Version=v1_6_4a	Flavor=Linux+2
		Qualifiers=""	Chain=""

	Product=git	Version=v1_8_0_1	Flavor=Linux+2
		Qualifiers=""	Chain=current

	Product=git	Version=v1_8_0_1	Flavor=Linux64bit+2
		Qualifiers=""	Chain=current
... 
 
       	Product=git	Version=v1_8_5_3	Flavor=Linxu+2.6-2.12
		Qualifiers=""	Chain=""

Use of the -K option with the + argument, e.g.,

% ups list -aK+ git 

requests the same information as the previous example, but in condensed format (-K+):

"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_6_4a" "Linux+2" "" "" 
"git" "v1_8_0_1" "Linux+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.5" "" "" 
"git" "v1_8_5_3" "Linux+2.6-2.5" "" "" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.12" "" "" 
"git" "v1_8_5_3" "Linxu+2.6-2.12" "" ""

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:

"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 

List specific keywords for a product

If your installation has multiple databases defined in $PRODUCTS, it is useful to include the keyword for the database (DB) in the -K argument list, e.g.,

% ups list -aK+:DB git 

This example is similar to the previous one, but the database path is included at the end:

"git" "v1_8_0_1" "Linux64bit+2" "" "current" "/nusoft/app/externals" 
"git" "v1_6_4a" "Linux+2" "" "" "/grid/fermiapp/products/common/db" 
"git" "v1_8_0_1" "Linux+2" "" "current" "/grid/fermiapp/products/common/db" 

This example specifies particular fields to be output with the-K option for the default instance of the product

% ups list -K product:version git
"git" "v1_8_0_1" 
"git" "v1_8_0_1" 
"git" "v1_8_0_1" 

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:


DATABASE=/grid/fermiapp/products/common/db 
	Product=minos	Version=v0.1	Flavor=NULL
		Qualifiers=""	Chain=current
		Declared="2013-08-16 18.16.17 GMT:2013-07-17 14.40.54 GMT" 
		Declarer="products:products" 
		Modified="2013-08-16 18.16.17 GMT:2013-07-17 14.40.54 GMT" 
		Modifier="products:products" 
		Home=/grid/fermiapp/products/common/db/../prd/project/v0_1/NULL
		No Compile Directive
		Authorized, Nodes=*
		UPS_Dir="ups" 
		Table_Dir="" 
		Table_File="project.table" 
		Archive_File="" 
		Description="" 
		Action=setup
			If( test -d /grid/fermiapp/products/${UPS_PROD_NAME}/prd/bootstrap_${UPS_PROD_NAME} )
			Execute( source `ups setup bootstrap_${UPS_PROD_NAME} -z /grid/fermiapp/products/${UPS_PROD_NAME}/db`, NO_UPS_ENV)
			Else()
			Execute( source `ups setup ${UPS_PROD_NAME} -z /grid/fermiapp/products/${UPS_PROD_NAME}/db`, NO_UPS_ENV)
			Endif( test -d /grid/fermiapp/products/${UPS_PROD_NAME}/prd/bootstrap_${UPS_PROD_NAME} )


This gives a fairly long list. It is often more convenient to use the -K option with a list of keywords for the specific fields you need.

Use "ups list -K" to locate product root directory, table file and ups directory

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.

% ups list -K @PROD_DIR git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux64bit-2" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux-2" 

% ups list -K UPS_DIR git
"ups" 
"ups" 
"ups" 

% ups list -K@UPS_DIR git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2/ups" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux64bit-2/ups" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux-2/ups" 

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.

% uups list -Ktable_file git
"git.table" 
"v1_8_0_1.table" 
"v1_8_0_1.table" 

% ups list -K@table_file git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2/ups/git.table" 
"/grid/fermiapp/products/common/db/git/v1_8_0_1.table" 
"/grid/fermiapp/products/common/db/git/v1_8_0_1.table" 

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.

open(UPS_LIST_OUTPUT, "| $ENV{UPS_DIR}/bin/ups list -aK+"); 
while (<UPS_LIST_OUTPUT> ) { 
# break into the array @fields: 
@fields = m/\"((?:[^\"\\]|\\.)*)\"/g; 
# then do things with $field[0] $field[1] ... 
# (in this case, 
# $field[0] = product name 
# $field[1] = version 
# $field[2] = flavor 
# $field[3] = qualifiers (colon-separated list) 
# $field[4] = chains (colon-separated list) 
} 

Say the output from your ups list -K command looks like this:

"ups" "v4_4" "Linux+2" "" "current" 

then the @fields array contains the variables:

$field[0] = ups 
$field[1] = v4_4 
$field[2] = Linux+2 
$field[3] =  
$field[4] = current 

Alternatively, you could parse the output this way:

($product, $version, $flavor, $qualifiers, $chains) = m/\"((?:[^\"\\]|\\.)*)\"/g; 

and then you'd have:

$product = ups 
$version = v4_4 
$flavor = Linux+2 
$qualifiers =  
$chains = current 

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.1 Command Syntax

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

23.12.2 Commonly Used Options

See section 23.12.3 All Valid Options for descriptions of each option.

Table 23.12.2-a:
-E <editor>

-f <flavor>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-N <fileName>

-q <qualifierList>

-z <databaseList>

23.12.3 All Valid Options

Table 23.12.3-a:
-? ("-?" for csh)
Prints command description and option usage information to screen
-A
authorized nodes
-c
current chain
-d
development chain
-E <editor>
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.
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-N <fileName>
Specifies file to be checked and edited
-p "<description>"
Specifies product description
-q <qualifierList>
Finds product instance with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory
-t
test chain
-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.
-U <upsDir>
Specifies location of ups directory; default value is ups
-v(vvv)
Prints out extra debugging information.
-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
-Z
Times the command

23.12.4 More Detailed Description

ups modify performs the following steps (if you specify the file using -N, the menu will not appear):

Internal Processes

23.12.5 ups modify Example

% ups modify git v1_8_5_3 -N $MYDB/git/v1_8_5_3.version

Pre modification verification pass complete. 

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.

  1. 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] ? y
UPS quits, saving the file as we requested.
  1. 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] ? y
UPS 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.13.1 Command Syntax

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

23.13.2 Commonly Used Options

See section 23.11.3 All Valid Options for descriptions of each option.

Table 23.13.2-a:
-a

-f <flavorList>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-K <keywordList>

-l

-q <qualifierList>

-z <databaseList>

23.13.3 All Valid Options

Table 23.13.3:
-? ("-?" for csh)
Prints command description and option usage information to screen
-a
Include all instances
-c
Finds product instance chained to "current"
-d
Finds product instance chained to "development"
-f <flavor>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-K
keywords : return information from these (colon-separated) keywords, "+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN(S)
-l
Produce a long listing
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
new chain
-o
old chain
-q <qualifierList>
colon separated list of required or optional qualifiers that are to be part of the instance
-r <prodRootDir>
Specifies the product root directory
-t
test chain
-U <upsDir>
Specifies location of ups directory; default value is ups
-v(vvv)
Prints out extra debugging information.
-z <databaseList>
Specifies the database(s) in which to look for the product and its dependencies
-Z
Times the command

23.13.4 More Detailed Description

The ups parent command can be slow. The ups parent command runs:

% ups depend product version -f flavor -q qualifiers -H hostflavor 

for every product version -f flavor -q qualfiers and for every hostflavor mentioned in the database. If you look things up frequently, we recommend that you run:

% ups parent -a 

dump the output to a file, and search in the file for the information you need.

23.13.5 ups parent Example

If you want to know what products depend on git, run:

% ups parent git
100% completed.  
git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__redmine v1_4_1 -f NULL -z /fnal/ups/db [via  -g current]

git v1_6_4 -f Linux+2 -z /fnal/ups/db
|__redmine v1_0_1 -f NULL -z /fnal/ups/db 
|__redmine v1_4_1 -f NULL -z /fnal/ups/db [via  -g current]

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.

23.14.1 Command Syntax

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

23.14.2 Commonly Used Options

See section 23.14.3 All Valid Options for descriptions of each option.

Table 23.14.2-a:
-f <flavor>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-v(vvv)

-w

-z <databaseList>

23.14.3 All Valid Options

Table 23.14.3-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>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>.
-P
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>
Finds product instance with the specified qualifiers (required and/or optional)
-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(vvv)
Prints out extra debugging information.
-V
Does not delete the temporary script files or partially installed products when command finishes; instead lists them on the screen
-w
Stops the product first, then restarts it
-z <databaseList>
Specifies the database(s) in which to look for the product and its dependencies
-Z
Times the command

23.14.4 More Detailed Description

Please see Chapter 15: Automatic UPS Product Startup and Shutdown for a detailed description of the use of the ups start command. In brief, it covers:

Internal Processes

23.14.5 ups start Examples

Run the command interactively

This command first stops (-w) the default instance of the product apache, and then restarts it:

% ups start -w apache 

It prints to screen messages of the format:

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

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.

23.15.1 Command Syntax

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

23.15.2 Commonly Used Options

See section 23.15.3 All Valid Options for descriptions of each option.

Table 23.15.2-a:
-f <flavor>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-v(vvv)

-z <databaseList>

23.15.3 All Valid Options

Table 23.15.3-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>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>.
-P
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>
Finds product instance with the specified qualifiers (required and/or optional)
-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(vvv)
Prints out extra debugging information.
-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

23.15.4 More Detailed Description

Please see Chapter 15: Automatic UPS Product Startup and Shutdown for a detailed description of the use of the ups stop command. In brief, it covers:

Internal Processes

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.

23.16.1 Command Syntax

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

23.16.2 Commonly Used Options

See section 23.16.3 All Valid Options for descriptions of each option.

Table 23.16.2-a:
-f <flavor>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-v(vvv)

-z <databaseList>

23.16.3 All Valid Options

Table 23.16.3-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>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-K <keywordList>
Returns values of specified keywords only; valid keywords are listed in section 28.4 List of Supported Keywords
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>.
-P
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>
Finds product instance with the specified qualifiers (required and/or optional)
-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(vvv)
Prints out extra debugging information.
-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/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.

Internal Processes

23.16.5 ups tailor Example

As an example, we show the tailor process for the product apache:

% ups tailor apache 
Current configuration nicknames are: 
kits    kits8k 
You can: 
    a)dd a new server configuration 
    q)uit the tailor script 
Which would you like? [aq]? a 
Webserver alias/name (e.g. www-xx.fnal.gov)? www-demo.fnal.gov 
Webserver nickname [demo]?  
Webserver port number [80]?  
Webserver effective user-id [wwwsrv]?  
Webserver effective group-id [www]?  
Webserver admin id [wwwadm]?  
Mail address for admin stuff [mengel@fnal.gov]? demo-admin@fnal.gov 
Directory for CGI executables [/fnal/www/demo/cgi-bin]?  
Directory /fnal/www/demo/cgi-bin doesn't exist, make it [y]? y 
Root of served files [/fnal/www/demo/html]?  
Directory /fnal/www/demo/html doesn't exist, make it [y]? y 
Raw Log file directory [/var/adm/www/demo]? /tmp/demo 
Log file Summary directory [/fnal/www/demo/html/logs]?  
Directory /fnal/www/demo/html/logs doesn't exist, make it [y]? y 
Current configuration nicknames are: 
demo    kits    kits8k 
You can: 
    a)dd a new server configuration 
    q)uit the tailor script 
Which would you like? [aq]? q 

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.17.1 Command Syntax

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

23.17.2 Commonly Used Options

See section 23.17.3 All Valid Options for descriptions of each option.

Table 23.17.2-a:
-f <flavor>
Or a valid number or -H (with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-z <databaseList>

23.17.3 All Valid Options

Table 23.17.3-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>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-q <qualifierList>
Finds product instance with the specified qualifiers (required and/or optional)
-t
Finds product instance chained to "test"
-v(vvv)
Prints out extra debugging information.
-z <databases>
Specifies the database(s) to use
-Z
Times the command (does not include time for sourcing of temp file for setup/unsetup)

23.17.4 ups touch Example

To illustrate this command, we first run a ups list showing the modified date/time and the modifier(s) for a product:

% ups list prod1 -aKproduct:modified:modifier 
"prod1" "2013-09-08 21.44.04 GMT:2013-09-08 21.38.23 GMT" "olduser:olduser" 

Now run ups touch to change these values:

% ups touch prod1 

And verify that they have changed, by rerunning the ups list command:

% ups list prod1 -aKproduct:modified:modifier  
"prod1" "2013-11-19 18.43.00 GMT:2013-09-08 21.38.23 GMT" newuser:olduser" 

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.

23.18.1 Command Syntax

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

23.18.2 Commonly Used Options

See section 23.18.3 All Valid Options for descriptions of each option.

Table 23.18.2-a:
-f <flavor>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-z <databaseList>

23.18.3 All Valid Options

Table 23.18.3-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>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>.
-P
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>
Finds product instance with the specified qualifiers (required and/or optional)
-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(vvv)
Prints out extra debugging information.
-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/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.

Internal Processes

23.18.5 ups unconfigure Example

The sample command runs the UNCONFIGURE action in the table file associated with the product prod1. If that action is not present, it undoes all the reversible functions included under the CONFIGURE action, by default.

% ups unconfigure prod1 v5 -f Linux+2 

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:

  1. 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
  2. to remove a chain from an instance

23.19.1 Command Syntax

For removing an instance

% ups undeclare <flavor_option> [<other_options>] <product> \ 
<version> 

For removing a chain

% ups undeclare <chain_option> [<other_options>] <product> 

23.19.2 Commonly Used Options

See section 23.18.3 All Valid Options for descriptions of each option.

For removing an instance

Table 23.19.2-a:
-f <flavor>
Or a valid number of -H (with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-y

-Y

-z <databaseList>

For removing a chain

Table 23.19.2-b:
-f <flavor>
Or a valid number or -H (with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-z <databaseList>

23.19.3 All Valid Options

Valid only for removing an instance (not for removing a chain)

Table 23.19.3-a:
-y
Deletes product root directory, provides confirmation prompt
-Y
Deletes product root directory, does not provide confirmation prompt

Valid for both functions

Table 23.19.3-b:
-? ("-?" for csh)
Prints command description and option usage information to screen
-c
Finds product instance chained to "current"
-C
When removing a product: Prevents execution of the UNCONFIGURE action
When removing a chain: Prevents execution of the corresponding "unchain" action
-d
Finds product instance chained to "development"
-f <flavor>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavor>
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>.
-q <qualifierList>
Finds product instance with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory
-t
Finds product instance chained to "test"
-U <upsDir>
Specifies location of ups directory; default value is ups
-v(vvv)
Prints out extra debugging information.
-V
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

Using ups 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:

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

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):

Product home directory - 
        /export/home/t1/aheavey/upsII/products/tcl/v8/ 
Delete this directory?y 

We respond "y" for yes. To respond no, we would enter "n".

Undeclare a chain

% ups undeclare -c ximagetools -f NULL 

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.

23.20.1 Command Syntax

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

23.20.2 Commonly Used Options

See section 23.20.3 All Valid Options for descriptions of each option.

Table 23.20.2-a:
-f <flavorList>
Or a valid number or -H (alone or with a valid number)
-g <chainName>
Or one of -c, -d, -n, -o, -t
-q <qualifierList>

-z <databaseList>

23.20.3 All Valid Options

Table 23.20.3-a:
-? ("-?" for csh)
Prints command description and option usage information to screen
-a
Verifies files for all instances that match the other options given on command line
-c
Finds product instance chained to "current"
-d
Finds product instance chained to "development"
-f <flavorList>
-g <chainName>
Finds product instance chained to <chainName>
-H <flavorList>
-m <tableFileName>
Specifies table file name
-M <tableFileDir>
Specifies table file directory
-n
Finds product instance chained to "new"
-o
Finds product instance chained to "old"
-q <qualifierList>
Finds product instance with the specified qualifiers (required and/or optional)
-r <prodRootDir>
Specifies the product root directory
-t
Finds product instance chained to "test"
-U <upsDir>
Specifies location of ups directory; default value is ups
-v(vvv)
Prints out extra debugging information.
-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.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'. 


TOC PREV NEXT

This page last revised May 2014