Project

General

Profile

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

Chapter Contents

Chapter 32: The UPD Configuration File
   32.1 updconfig File Organization
   32.2 Product Instance Identification and Matching
   32.3 Defining Locations for Product Files
     32.3.1 Required Locations
     32.3.2 Read-Only Variables Usable in Location Definitions
     32.3.3 Sample Location Definitions
   32.4 Pre- and Postdeclare Actions
     32.4.1 ACTION Keyword Values
     32.4.2 The execute Function
   32.5 Examples
     32.5.1 Generic Template updconfig File
     32.5.2 Distribution from the fnkits Node Only
     32.5.3 Customized Treatment of ups Directory and Table Files
     32.5.4 Implementing Multiple Configurations
     32.5.5 Sample Configuration for AFS Space Using ACTIONS
     32.5.6 Distribution Node Configuration

  Chapter 32: The UPD Configuration File

  UPD can be configured and customized on your system using the file updconfig , described in this chapter. This file is usually maintained in the location $PRODUCTS/.updfiles/updconfig . (Its location is commonly referred to as $UPD_USERCODE_DIR/updconfig , where $UPD_USERCODE_DIR gets defined in the dbconfig file of the UPS database in which UPD is declared.) By providing default values for several variables (mostly product file and directory locations), the updconfig file controls where UPD installs products and miscellaneous product-related files. It can also be used to define supplementary actions for UPD to perform when installing or updating products. Use of the updconfig file greatly reduces the amount of information the installer/maintainer needs to provide to the system for each UPD operation. A template updconfig file is available in $UPD_DIR/ups/updconfig.template .

  Locations defined in a updconfig file may be overridden by specifying corresponding options on the UPD command line.

  32.1 updconfig File Organization

  The updconfig file always has as its first line:

  File = updconfig

  to identify itself to the system. The remainder of the file consists of one or more stanzas. Each stanza:

  • identifies certain product instances, products or groups of products
  • specifies a database on the local system in which to declare a matched product
  • specifies locations on the local system in which UPD is to put a matched product and its related files
  • (optionally) lists actions for UPS/UPD to perform either just before or just after declaring the matched product

  A updconfig file stanza is of the form:

GROUP:
...
COMMON:
...
END:

  The GROUP: section of the stanza contains the product matching information. The COMMON: section contains the locations and actions for the matched product and its associated files. END: is used to end the stanza.

  32.2 Product Instance Identification and Matching

  There are several identifiers which can be used to specify a product instance match. When multiple values are listed for an identifier, the logical "or" of those values is used. A value can contain ${VARIABLE} strings which are expanded from the environment. Identifiers which are omitted default to ANY , which means they match any product instance. The following identifiers are supported:
Table 32.2.0-a:Table 32.2.0-a:


p<>.   product

p<>.   product name

p<>.   flavor

p<>.   flavor string

p<>.   qualifi ers

p<>.   qualifier string

p<>.   options

p<>.   option (anything specified via the -O (uppercase -o ) option in the UPD command

p<>.   dist_database

p<>.   database path on the distribution server

p<>.   dist_node

p<>.   node name of distribution server

  As an example, the following stanza identifies the product exmh , for either the flavor Linux+2 or Linux64bit+2.6 and any qualifiers (omitted, therefore set to ANY by default) on fnkits.fnal.gov :

  GROUP:

  product = exmh

  flavor = Linux+2, Linux64bit+2.6

  dist_node = fnkits.fnal.gov

  COMMON:

  ...

  END:

  Here are two examples of using ${VARIABLE} strings:

  Subscribe to changes in your local databases (e.g., if you want to do something special when, say, products are copied from one local database to another):

  dist_node = file://localhost${PRODUCTS}

  Send mail to whoever runs the upp command:

  mail_address = ${USER}@fnal.gov

  In the current implementation, the first stanza to match a given product instance is the one that gets used; UPD does not continue searching in the file for a "better" match.

  32.3 Defining Locations for Product Files

  Within each stanza, file and directory locations for installing matched product instances and their associated files must be defined. These locations should be defined in terms of UPS/UPD read-only variables.

  32.3.1 Required Locations

  All the locations/keywords listed in the table below are required (the last two for distribution nodes only).

  Note: UPS_THIS_DB , listed first, is used by UPD to determine the database in which to look for PROD_DIR_PREFIX (set in dbconfig , see Chapter 31: The UPS Configuration File ). Several of the keywords that follow may be defined relative to its corresponding read-only variable ${PROD_DIR_PREFIX} .
Table 32.3.1-a:Table 32.3.1-a:

UPS_THIS_DB UPS_THIS_DB the database into which UPS declares the product (i.e., the directory that UPD specifies in the ups declare -z option). the database into which UPS declares the product (i.e., the directory that UPD specifies in the ups declare -z option). Recommendation: Set it to ${UPD_USERCODE_DB} , which is the database in which the updconfig file was found. Recommendation: Set it to ${UPD_USERCODE_DB} , which is the database in which the updconfig file was found.
UPS_PROD_DIR UPS_PROD_DIR product root directory that UPD specifies in the ups declare -r option; should be defined relative to ${PROD_DIR_PREFIX} for portability product root directory that UPD specifies in the ups declare -r option; should be defined relative to ${PROD_DIR_PREFIX} for portability
UNWIND_PROD_DIR UNWIND_PROD_DIR absolute path to directory where product gets unwound absolute path to directory where product gets unwound In most cases, it's ${PROD_DIR_PREFIX}/${UPS_PROD_DIR} , however in AFS and some NFS mounting configurations, products are often unwound and declared in different locations (see section 9.3 Installing Products into AFS Space ). In most cases, it's ${PROD_DIR_PREFIX}/${UPS_PROD_DIR} , however in AFS and some NFS mounting configurations, products are often unwound and declared in different locations (see section 9.3 Installing Products into AFS Space ).
UPS_UPS_DIR UPS_UPS_DIR ups directory that UPD specifies in the ups declare -U option, taken relative to ${UNWIND_PROD_DIR} unless an absolute path is given; usually defined as ups. ups directory that UPD specifies in the ups declare -U option, taken relative to ${UNWIND_PROD_DIR} unless an absolute path is given; usually defined as ups.
UNWIND_UPS_DIR UNWIND_UPS_DIR absolute path to directory where the ups directory gets unwound; usually defined as ${UNWIND_PROD_DIR}/${ UPS_UPS_DIR} or ${UNWIND_PROD_DIR}/ups . absolute path to directory where the ups directory gets unwound; usually defined as ${UNWIND_PROD_DIR}/${ UPS_UPS_DIR} or ${UNWIND_PROD_DIR}/ups .
UPS_TABLE_DIR UPS_TABLE_DIR table file directory that UPD specifies in the ups declare -M option table file directory that UPD specifies in the ups declare -M option % %{font-weight: bold;color: #000000}Normally this should not be set ! In some cases you may need to put the table file somewhere other than where UPS will automatically look (namely $PRODUCTS/${UPS_PROD_NAME} and ${UPS_UPS_DIR} ); however since UPS_TABLE_DIR must be an absolute path, the declaration becomes non-portable if you set this location. % %{font-weight: bold;color: #000000}Normally this should not be set ! In some cases you may need to put the table file somewhere other than where UPS will automatically look (namely $PRODUCTS/${UPS_PROD_NAME} and ${UPS_UPS_DIR} ); however since UPS_TABLE_DIR must be an absolute path, the declaration becomes non-portable if you set this location.
UNWIND_TABLE_DIR UNWIND_TABLE_DIR absolute path to directory where the table file gets unwound absolute path to directory where the table file gets unwound Suggestion: To maintain one table file for all flavors of a product, put it in the database; i.e., set this to ${UPS_THIS_DB}/${UPS_PROD_NAME} . To maintain each table file under $<PRODUCT>_DIR/ups , set it to ${UPS_UPS_DIR} . Suggestion: To maintain one table file for all flavors of a product, put it in the database; i.e., set this to ${UPS_THIS_DB}/${UPS_PROD_NAME} . To maintain each table file under $<PRODUCT>_DIR/ups , set it to ${UPS_UPS_DIR} .
UPS_TABLE_FILE UPS_TABLE_FILE table file name that UPD specifies in the ups declare -m option table file name that UPD specifies in the ups declare -m option Depending on where you maintain table files, choose a naming convention that identifies each file adequately. For example, if you maintain all product table files in one location, the filename should include the product name and version (e.g., ${UPS_PROD_NAME}_${UPS_PROD_VERSION}.table ); if each is kept under its product root directory, the product name is not necessary (e.g., ${UPS_PROD_VERSION}.table ). Depending on where you maintain table files, choose a naming convention that identifies each file adequately. For example, if you maintain all product table files in one location, the filename should include the product name and version (e.g., ${UPS_PROD_NAME}_${UPS_PROD_VERSION}.table ); if each is kept under its product root directory, the product name is not necessary (e.g., ${UPS_PROD_VERSION}.table ).
UNWIND_ARCHIVE_FILE UNWIND_ARCHIVE_FILE absolute path to directory in which to unwind archive file (tar file) of product absolute path to directory in which to unwind archive file (tar file) of product Used only on distribution server configurations. Used only on distribution server configurations.
UPS_ARCHIVE_FILE UPS_ARCHIVE_FILE archive file (tar file) location that UPD specifies in archive file (tar file) location that UPD specifies in ups declare -T ftp://host${UPS_ARCHIVE_FILE} ups declare -T ftp://host${UPS_ARCHIVE_FILE} Used only on distribution server configurations. Used only on distribution server configurations.

  32.3.2 Read-Only Variables Usable in Location Definitions

  The following predefined UPS/UPD read-only variables can be used in the definition of locations described above. These variables get their values from the command line and/or the dependency list.

  Do not try to redefine these variables. When you use these variables, always enclose them in curly brackets ({}) as shown in the list.
Table 32.3.2-a:Table 32.3.2-a:

${UPS_USERCODE_DB} ${UPS_USERCODE_DB} database containing UPD configuration database containing UPD configuration
${UPS_USERCODE_DIR} ${UPS_USERCODE_DIR} directory containing UPD configuration directory containing UPD configuration
${UPS_PROD_NAME} ${UPS_PROD_NAME} name of product name of product
${UPS_PROD_FLAVOR} ${UPS_PROD_FLAVOR} flavor of product flavor of product
${UPS_PROD_QUALIFIERS} ${UPS_PROD_QUALIFIERS} qualifiers of product qualifiers of product
${UPS_BASE_FLAVOR} ${UPS_BASE_FLAVOR} flavor trimmed as in ups flavor -1 flavor trimmed as in ups flavor -1
${DASH_PROD_FLAVOR} ${DASH_PROD_FLAVOR} flavor with non-word characters replaced by dashes; e.g., if {UPS_PROD_FLAVOR} is set to SunOS+5 , then {DASH_PROD_FLAVOR} has the value SunOS-5 . This is used to avoid problems with unusual symbols in file and directory names. flavor with non-word characters replaced by dashes; e.g., if {UPS_PROD_FLAVOR} is set to SunOS+5 , then {DASH_PROD_FLAVOR} has the value SunOS-5 . This is used to avoid problems with unusual symbols in file and directory names.
${DASH_PROD_QUALIFIERS} ${DASH_PROD_QUALIFIERS} qualifier list with non-word characters replaced by dashes; e.g., if {UPS_PROD_QUALIFIERS} is qual1+qual2 , then {DASH_PROD_QUALIFIERS} is qual1-qual2 . This is used to avoid problems with unusual symbols in file and directory names. qualifier list with non-word characters replaced by dashes; e.g., if {UPS_PROD_QUALIFIERS} is qual1+qual2 , then {DASH_PROD_QUALIFIERS} is qual1-qual2 . This is used to avoid problems with unusual symbols in file and directory names.
${SUFFIX} ${SUFFIX} suffix of archive file; e.g., tar , zip , etc. suffix of archive file; e.g., tar , zip , etc. Used only on distribution server configurations. Used only on distribution server configurations.
${PROD_DIR_PREFIX} ${PROD_DIR_PREFIX} PROD_DIR_PREFIX of database, defined in UPS configuration file dbconfig (see Chapter 31 ) PROD_DIR_PREFIX of database, defined in UPS configuration file dbconfig (see Chapter 31 )

  32.3.3 Sample Location Definitions

  The following partial stanza, taken from the example in section 32.5.1 , shows several location specifications:

COMMON:
     UPS_THIS_DB  = "${UPD_USERCODE_DB}" 
     UPS_PROD_DIR = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}
                     ${DASH_PROD_QUALIFIERS}" ( %{font-weight: normal;color: #000000}this must be all on one line in the real file% )
  UNWIND_PROD_DIR = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
      UPS_UPS_DIR = "ups" 
   UNWIND_UPS_DIR = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 

#    Default (do not actually set UPS_TABLE_DIR):
#   UPS_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
 UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 
...
END:

  32.4 Pre- and Postdeclare Actions

  An action is a construction that identifies a UPS or user-defined operation via the ACTION keyword, and lists functions to perform, in addition to any internal processes, when the operation is executed. An action stanza has the format:

ACTION=<VALUE>
      <function_1>([<argument_1>] [, <argument_2>] ...)
      <function_2>([<argument_1>] [, <argument_2>] ...)
      ...

  The updconfig file uses actions to define the steps UPD is to perform during an installation/update of the matched product instance(s). The ACTION keyword values indicate when to perform the steps (before or after issuing the ups declare command), and the steps themselves are listed as functions under the ACTION line. In a updconfig file, actions can be listed anywhere in the COMMON: part of a stanza.

  32.4.1 ACTION Keyword Values

  Currently two action keyword values are supported for use in updconfig :
Table 32.4.1-a:Table 32.4.1-a:


p<>.   predeclare

p<>.   Perform listed functions after product files have been unwound, but before the product has been declared

p<>.   postdeclare

p<>.   Perform listed functions after product has been declared

  Functions are then listed after the ACTION keyword line, using the following syntax:

Action = predeclare
    function(arg,arg,...)
    function(arg,arg,...)

  32.4.2 The execute Function

  Currently, only the execute function is supported for use in updconfig :

execute("<command>", <UPS_ENV_FLAG>, [, <VARIABLE>])

  It executes a shell-independent command and (optionally) assigns the output to an environment variable, <VARIABLE> . It takes a required parameter ( UPS_ENV_FLAG ) which indicates whether to define UPS local variables. This parameter can take the following values:

  UPS_ENV

  define all local UPS environment variables before sourcing (the script or command relies on these being defined)

  NO_UPS_ENV

  do not define the local UPS environment variables (the script or command doesn't use them)

  If the optional third argument, <VARIABLE> , is not specified, then the specified command is executed but the output from that command is not saved. This command does not have to be shell-independent.

  For example, say that you want to make group-writable the directory in which a product has been unwound before it is declared. You would include the action:

ACTION = PREDECLARE
    execute ("chmod -R g+w ${UNWIND_PROD_DIR}", NO_UPS_ENV )

  32.5 Examples

  32.5.1 Generic Template updconfig File

  This example is taken from the template, $UPD_DIR/ups/updconfig.template (comments are included in the actual template file). The template is designed to be usable as is , if:

  • you have only one UPS database
  • you want your product root hierarchy to be:
    p<>.   ${PROD_DIR_PREFIX}/<product>/<version>/<flavor><qualifiers>
  • you want your table files to reside in the UPS database as:
    p<>.   ${UPS_THIS_DB}/<product>/<version>.table

  If your requirements are different, this file is still useful as a starting point from which to make modifications.

File = updconfig
#
GROUP:
  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = ANY

COMMON:
     UPS_THIS_DB  = "${UPD_USERCODE_DB}" 
     UPS_PROD_DIR =  "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}
                      ${DASH_PROD_QUALIFIERS}" ( %{font-weight: normal;color: #000000}no line break in real file% )
  UNWIND_PROD_DIR = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
      UPS_UPS_DIR = "ups" 
   UNWIND_UPS_DIR = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 

#    Default (do not actually set UPS_TABLE_DIR):
#   UPS_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
 UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 
#
#    Possible alternative, where the table files live
#    within the product's ups directory.  Note,
#    in this case you ALSO should not set UPS_TABLE_DIR.
#
##  UPS_TABLE_DIR = "${UNWIND_UPS_DIR}" 
#UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
# UPS_TABLE_FILE  = "${UPS_PROD_NAME}.table" 
#
#  ACTION = PREDECLARE
#           add functions
#  ACTION = POSTDECLARE
#           add functions
END:

  32.5.2 Distribution from the fnkits Node Only

  As a second example, we show the GROUP: portion of a file that specifies a particular distribution host. Aside from the dist_node entry, the stanza is identical to that of the template updconfig file, and therefore applies to any products coming from the specified host, fnkits.fnal.gov . fnkits is the central Computing Division product server, and there are several names for it. All the names are all listed and delimited by colons.

File = updconfig

GROUP:

  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = fnkits:fnkits.fnal.gov:kits:kits.fnal.gov:upd:upd.fnal.gov

COMMON:
...
END:

  This UPD configuration file could be expanded to include additional stanzas to accommodate products from other distribution nodes.

  32.5.3 Customized Treatment of ups Directory and Table Files

  In this example, the distribution node again has changed relative to the template, and this time there are also changes in the COMMON: section. The distribution node is e007.dist.xyz.edu . UPS_PROD_DIR is no longer defined relative to PROD_DIR_PREFIX, but is now placed under the /e007/base_code directory. All the table files are placed in a single directory ( /e007/table_files ), therefore the table file names must include the product name in order to be identifiable. Here they will be named <product>_<version>.table (defined using the corresponding variables as ${UPS_PROD_NAME}_${UPS_PROD_VERSION}.table ).

File = updconfig

GROUP:
  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = e007_dist.xyz.edu

COMMON:
      UPS_THIS_DB      = "${UPD_USERCODE_DB}" 
     UPS_PROD_DIR     = "/e007/base_code/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/
                        ${UPS_PROD_FLAVOR}${UPS_PROD_QUALIFIERS}" ( %{font-weight: normal;color: #000000}no line break in real file% )
     UNWIND_PROD_DIR  = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
     UPS_UPS_DIR      = "ups" 
     UNWIND_UPS_DIR   = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 
     UPS_TABLE_DIR    = "/e007/table_files" 
     UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
     UPS_TABLE_FILE   = "${UPS_PROD_NAME}_${UPS_PROD_VERSION}.table" 
END:

  32.5.4 Implementing Multiple Configurations

  Here is an example that shows how to configure the file if more than one database and distribution node are used. The first section instructs UPD where to unwind products that are distributed from fnkits and how to declare them. The second section, with different naming conventions and file hierarchies, instructs UPD where to unwind and how to declare products obtained from the CDF distribution node cdf-kits.fnal.gov .

File = updconfig

GROUP:

  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = fnkits:fnkits.fnal.gov:kits:kits.fnal.gov:upd:upd.fnal.gov

COMMON:

     UPS_THIS_DB      = "${UPD_USERCODE_DB}" 
     UPS_PROD_DIR     = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${UPS_PROD_FLAVOR}
                         ${UPS_PROD_QUALIFIERS}"     ( %{font-weight: normal;color: #000000}no line break in real file% )
     UNWIND_PROD_DIR  = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
     UPS_UPS_DIR      = "ups" 
     UNWIND_UPS_DIR   = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 
###  UPS_TABLE_DIR    = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
     UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
     UPS_TABLE_FILE   = "${UPS_PROD_VERSION}.table" 

END:

GROUP:

  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = cdf-kits.fnal.gov

COMMON:

     UPS_THIS_DB      = "~cdfsoft/declare" 
     UPS_PROD_DIR     = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${UPS_PROD_FLAVOR}
                         ${UPS_PROD_QUALIFIERS}"  ( %{font-weight: normal;color: #000000}no line break in real file% )
     UNWIND_PROD_DIR  = "/cdf/products/${UPS_PROD_NAME}/${UPS_PROD_VERSION}" 
     UPS_UPS_DIR      = "ups" 
     UNWIND_UPS_DIR   = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 
###  UPS_TABLE_DIR    = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
     UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
     UPS_TABLE_FILE   = "${UPS_PROD_VERSION}.table" 

END:

  32.5.5 Sample Configuration for AFS Space Using ACTIONS

  In AFS space, you may need to release the read-write volume before you can declare a product, as discussed in section 9.3 Installing Products into AFS Space . For this you would use a PREDECLARE action. You may also need to release the read-write UPS database after the product is declared, which can be done in a POSTDECLARE action. These actions are shown in this example.

File = updconfig

 GROUP:
  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = ANY

COMMON:
     UPS_THIS_DB = "/afs/.fnal.gov/ups/db" 
     UPS_PROD_DIR = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${UPS_PROD_FLAVOR}
                     ${UPS_PROD_QUALIFIERS}"  ( %{font-weight: normal;color: #000000}no line break in real file% )
  UNWIND_PROD_DIR = "/afs/.fnal.gov/ups/${UPS_PROD_DIR}" 
      UPS_UPS_DIR = "ups" 
   UNWIND_UPS_DIR = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 
 UNWIND_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 

  ACTION = PREDECLARE
    Execute("/usr/local/bin/upd_volrelease ${UNWIND_PROD_DIR}", NO_UPS_ENV)
  ACTION = POSTDECLARE
    Execute("/usr/local/bin/upd_volrelease ${UPS_THIS_DB}", NO_UPS_ENV)

END:

  32.5.6 Distribution Node Configuration

  For this example, we present an abridged version of the updconfig file used on fnkits .

  The updconfig file on fnkits includes several stanzas, each of which pertains to a category of product. The product-matching criterion for each stanza is an options=<option> line which indicates the category. This example shows only the stanzas used for ordinary distributed products (the default) and locally installed products. The default stanza is identified by the absence of an option, and the local stanza is identified by the option local .

  The default stanza includes a PREDECLARE and a POSTDECLARE action. The PREDECLARE action contains a set of execute statements to chmod/chgrp the files to the right group id and permissions. The POSTDECLARE action makes a convenience tar file of the ups directory for users downloading via FTP . The stanza for local products contains no actions.

  • Many of the location definitions and functions are quite long, and are shown here on multiple lines for readability.
  • In the real file, each definition or function must be contained on a single line.
File = updconfig

#
#>>> Define GROUP.
#    If all of your products go in the same database,
#    using the same naming conventions, you can
#    group them all together.
GROUP:
  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = ANY

COMMON:
#>>> Define UPS_THIS_DB.
#    This is the database into which the above products will
#    be declared by upd.
#    Default:
#    UPS_THIS_DB is set to the database where UPD was declared.
#    You may need to set it differently for the products you're describing.
     UPS_THIS_DB = "${UPD_USERCODE_DB}" 
#
#    Other examples might be:
#    UPS_THIS_DB = "/usr/products/ups_database" 
#    UPS_THIS_DB = "~cdfsoft/declared" 

#>>> Define UPS_PROD_DIR.
#    The UPS_PROD_DIR determines the product root file
#    hierarchy for products in the ups database being 
#    described.
#    Examples are shown below for the case of the product
#    instance "mh v1_6_6 IRIX+6".  Uncomment the 
#    one that matches your system.
#    In all of the example, the UPS_PROD_DIR is a RELATIVE
#    path; this means that the product will be declared with
#    a relative path (relative to PROD_DIR_PREFIX).
#
#    prod_dir: /usr/products/mh/v1_6_6/IRIX+6
     UPS_PROD_DIR = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}${DASH_PROD
_QUALIFIERS}" 

#
#    prod_dir: /usr/products/IRIX/mh/v1_6_6
#    UPS_PROD_DIR = "${UPS_BASE_FLAVOR}/${UPS_PROD_NAME}/${UPS_PROD_VERSION}${DASH_PROD_
QUALIFIERS}" 
#
#    prod_dir: /usr/products/IRIX+6/mh/v1_6_6
#    UPS_PROD_DIR = "${DASH_PROD_FLAVOR}/${UPS_PROD_NAME}/${UPS_PROD_VERSION}${DASH_PROD
_QUALIFIERS}" 
#
#    prod_dir: /afs/fnal/ups/mh/v1_6_6/IRIX+6
#    UPS_PROD_DIR = "/afs/fnal/ups/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAV
OR}${DASH_PROD_QUALIFIERS}" 
#
#    prod_dir: ${ENVVAR}/mh/v1_6_6/IRIX+6
#    UPS_PROD_DIR = "\${ENVVAR}/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}
${DASH_PROD_QUALIFIERS}" 
#

#>>> Define UNWIND_PROD_DIR.
#    The UNWIND_PROD_DIR is the directory into which the product
#    is unwound.  In most cases, it will be the same as the UPS_PROD_DIR
#    defined above; in AFS space, or under certain NFS mounting configurations,
#    you may unwind the product in a directory that has a different name
#    than the directory where you declare it.
#
#    THE DEFAULT IS THAT THE UNWIND_PROD_DIR IS THE SAME AS THE
#    UPS_PROD_DIR.  NOTE that you need to prepend PROD_DIR_PREFIX
#    if the UPS_PROD_DIR was specified as a relative path!
#    Change this is your situation is different!

#     Default:
  UNWIND_PROD_DIR = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
#
#     AFS unwind dir:
# UNWIND_PROD_DIR = "/afs/.fnal.gov/ups/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD
_FLAVOR}${DASH_PROD_QUALIFIERS}" 
#
#     Declared based on environmental variable:
# UNWIND_PROD_DIR = "${ENVVAR}/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}$
{DASH_PROD_QUALIFIERS}" 

#>>> Define UPS_UPS_DIR.
#    The UPS_UPS_DIR is the products' ups directory.
#    Default is the directory named "ups" under the product root directory.
      UPS_UPS_DIR = "ups" 

#>>> Define UNWIND_UPS_DIR.
#    The UNWIND_UPS_DIR is where to unwind the ups directory.
#    The default is the same directory as the UPS_UPS_DIR.
   UNWIND_UPS_DIR = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 

#>>> Define UPS_TABLE_FILE, UNWIND_TABLE_DIR, 
#>>> and optionally, UPS_TABLE_DIR.
#    The naming convention for table files.  The default
#    is to put the table file in the ups database, so that
#    one table file may be used for multiple flavors of the
#    product.  If you put your table files here,
#    you should NOT set UPS_TABLE_DIR.
#    Change this if your situation is different!
#
#    Default:
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 
 UNWIND_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
#   UPS_TABLE_DIR = "${UNWIND_TABLE_DIR}" 
#    Default:
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 
 UNWIND_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
#   UPS_TABLE_DIR = "${UNWIND_TABLE_DIR}" 
#
#    Possible alternative, where the table files live
#    within the product's ups directory.  Note,
#    in this case you ALSO should not set UPS_TABLE_DIR.
#
# UPS_TABLE_FILE  = "${UPS_PROD_NAME}.table" 
#UNWIND_TABLE_DIR = "${UNWIND_UPS_DIR}" 
##  UPS_TABLE_DIR = "${UNWIND_TABLE_DIR}" 

#>>> Define PREDECLARE, POSTDECLARE actions
#
#  Actions which take place after the product is
#  unwound, before the product is declared.
#  Uncomment and modify as appropriate.
#
#  ACTION = PREDECLARE
#
#      example: you may wish to make the directory
#      where the product has been unwound group writeable:
#      EXECUTE ( "chmod -R g+w ${UNWIND_PROD_DIR}", NO_UPS_ENV )
#
#      example: in AFS space, you may need to release
#      the read-write volume before you can declare the product:
#      EXECUTE ( "upd_volrelease ${UNWIND_PROD_DIR}", NO_UPS_ENV )

#
#  Actions which take place after the product is
#  declared.
#  Uncomment and modify as appropriate.
#
#  ACTION = POSTDECLARE
#       example: in AFS space, you may need to release
#       the read-write ups database
#       EXECUTE ( "upd_volrelease ${UPS_THIS_DB}", NO_UPS_ENV )
END:

 

TOC PREV NEXT

Last revised on May 2014

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

Chapter Contents

Chapter 32: The UPD Configuration File
   32.1 updconfig File Organization
   32.2 Product Instance Identification and Matching
   32.3 Defining Locations for Product Files
     32.3.1 Required Locations
     32.3.2 Read-Only Variables Usable in Location Definitions
     32.3.3 Sample Location Definitions
   32.4 Pre- and Postdeclare Actions
     32.4.1 ACTION Keyword Values
     32.4.2 The execute Function
   32.5 Examples
     32.5.1 Generic Template updconfig File
     32.5.2 Distribution from the fnkits Node Only
     32.5.3 Customized Treatment of ups Directory and Table Files
     32.5.4 Implementing Multiple Configurations
     32.5.5 Sample Configuration for AFS Space Using ACTIONS
     32.5.6 Distribution Node Configuration

  Chapter 32: The UPD Configuration File

  UPD can be configured and customized on your system using the file updconfig , described in this chapter. This file is usually maintained in the location $PRODUCTS/.updfiles/updconfig . (Its location is commonly referred to as $UPD_USERCODE_DIR/updconfig , where $UPD_USERCODE_DIR gets defined in the dbconfig file of the UPS database in which UPD is declared.) By providing default values for several variables (mostly product file and directory locations), the updconfig file controls where UPD installs products and miscellaneous product-related files. It can also be used to define supplementary actions for UPD to perform when installing or updating products. Use of the updconfig file greatly reduces the amount of information the installer/maintainer needs to provide to the system for each UPD operation. A template updconfig file is available in $UPD_DIR/ups/updconfig.template .

  Locations defined in a updconfig file may be overridden by specifying corresponding options on the UPD command line.

  32.1 updconfig File Organization

  The updconfig file always has as its first line:

  File = updconfig

  to identify itself to the system. The remainder of the file consists of one or more stanzas. Each stanza:

  • identifies certain product instances, products or groups of products
  • specifies a database on the local system in which to declare a matched product
  • specifies locations on the local system in which UPD is to put a matched product and its related files
  • (optionally) lists actions for UPS/UPD to perform either just before or just after declaring the matched product

  A updconfig file stanza is of the form:

GROUP:
...
COMMON:
...
END:

  The GROUP: section of the stanza contains the product matching information. The COMMON: section contains the locations and actions for the matched product and its associated files. END: is used to end the stanza.

  32.2 Product Instance Identification and Matching

  There are several identifiers which can be used to specify a product instance match. When multiple values are listed for an identifier, the logical "or" of those values is used. A value can contain ${VARIABLE} strings which are expanded from the environment. Identifiers which are omitted default to ANY , which means they match any product instance. The following identifiers are supported:
Table 32.2.0-a:Table 32.2.0-a:


p<>.   product

p<>.   product name

p<>.   flavor

p<>.   flavor string

p<>.   qualifi ers

p<>.   qualifier string

p<>.   options

p<>.   option (anything specified via the -O (uppercase -o ) option in the UPD command

p<>.   dist_database

p<>.   database path on the distribution server

p<>.   dist_node

p<>.   node name of distribution server

  As an example, the following stanza identifies the product exmh , for either the flavor Linux+2 or Linux64bit+2.6 and any qualifiers (omitted, therefore set to ANY by default) on fnkits.fnal.gov :

  GROUP:

  product = exmh

  flavor = Linux+2, Linux64bit+2.6

  dist_node = fnkits.fnal.gov

  COMMON:

  ...

  END:

  Here are two examples of using ${VARIABLE} strings:

  Subscribe to changes in your local databases (e.g., if you want to do something special when, say, products are copied from one local database to another):

  dist_node = file://localhost${PRODUCTS}

  Send mail to whoever runs the upp command:

  mail_address = ${USER}@fnal.gov

  In the current implementation, the first stanza to match a given product instance is the one that gets used; UPD does not continue searching in the file for a "better" match.

  32.3 Defining Locations for Product Files

  Within each stanza, file and directory locations for installing matched product instances and their associated files must be defined. These locations should be defined in terms of UPS/UPD read-only variables.

  32.3.1 Required Locations

  All the locations/keywords listed in the table below are required (the last two for distribution nodes only).

  Note: UPS_THIS_DB , listed first, is used by UPD to determine the database in which to look for PROD_DIR_PREFIX (set in dbconfig , see Chapter 31: The UPS Configuration File ). Several of the keywords that follow may be defined relative to its corresponding read-only variable ${PROD_DIR_PREFIX} .
Table 32.3.1-a:Table 32.3.1-a:

UPS_THIS_DB UPS_THIS_DB the database into which UPS declares the product (i.e., the directory that UPD specifies in the ups declare -z option). the database into which UPS declares the product (i.e., the directory that UPD specifies in the ups declare -z option). Recommendation: Set it to ${UPD_USERCODE_DB} , which is the database in which the updconfig file was found. Recommendation: Set it to ${UPD_USERCODE_DB} , which is the database in which the updconfig file was found.
UPS_PROD_DIR UPS_PROD_DIR product root directory that UPD specifies in the ups declare -r option; should be defined relative to ${PROD_DIR_PREFIX} for portability product root directory that UPD specifies in the ups declare -r option; should be defined relative to ${PROD_DIR_PREFIX} for portability
UNWIND_PROD_DIR UNWIND_PROD_DIR absolute path to directory where product gets unwound absolute path to directory where product gets unwound In most cases, it's ${PROD_DIR_PREFIX}/${UPS_PROD_DIR} , however in AFS and some NFS mounting configurations, products are often unwound and declared in different locations (see section 9.3 Installing Products into AFS Space ). In most cases, it's ${PROD_DIR_PREFIX}/${UPS_PROD_DIR} , however in AFS and some NFS mounting configurations, products are often unwound and declared in different locations (see section 9.3 Installing Products into AFS Space ).
UPS_UPS_DIR UPS_UPS_DIR ups directory that UPD specifies in the ups declare -U option, taken relative to ${UNWIND_PROD_DIR} unless an absolute path is given; usually defined as ups. ups directory that UPD specifies in the ups declare -U option, taken relative to ${UNWIND_PROD_DIR} unless an absolute path is given; usually defined as ups.
UNWIND_UPS_DIR UNWIND_UPS_DIR absolute path to directory where the ups directory gets unwound; usually defined as ${UNWIND_PROD_DIR}/${ UPS_UPS_DIR} or ${UNWIND_PROD_DIR}/ups . absolute path to directory where the ups directory gets unwound; usually defined as ${UNWIND_PROD_DIR}/${ UPS_UPS_DIR} or ${UNWIND_PROD_DIR}/ups .
UPS_TABLE_DIR UPS_TABLE_DIR table file directory that UPD specifies in the ups declare -M option table file directory that UPD specifies in the ups declare -M option % %{font-weight: bold;color: #000000}Normally this should not be set ! In some cases you may need to put the table file somewhere other than where UPS will automatically look (namely $PRODUCTS/${UPS_PROD_NAME} and ${UPS_UPS_DIR} ); however since UPS_TABLE_DIR must be an absolute path, the declaration becomes non-portable if you set this location. % %{font-weight: bold;color: #000000}Normally this should not be set ! In some cases you may need to put the table file somewhere other than where UPS will automatically look (namely $PRODUCTS/${UPS_PROD_NAME} and ${UPS_UPS_DIR} ); however since UPS_TABLE_DIR must be an absolute path, the declaration becomes non-portable if you set this location.
UNWIND_TABLE_DIR UNWIND_TABLE_DIR absolute path to directory where the table file gets unwound absolute path to directory where the table file gets unwound Suggestion: To maintain one table file for all flavors of a product, put it in the database; i.e., set this to ${UPS_THIS_DB}/${UPS_PROD_NAME} . To maintain each table file under $<PRODUCT>_DIR/ups , set it to ${UPS_UPS_DIR} . Suggestion: To maintain one table file for all flavors of a product, put it in the database; i.e., set this to ${UPS_THIS_DB}/${UPS_PROD_NAME} . To maintain each table file under $<PRODUCT>_DIR/ups , set it to ${UPS_UPS_DIR} .
UPS_TABLE_FILE UPS_TABLE_FILE table file name that UPD specifies in the ups declare -m option table file name that UPD specifies in the ups declare -m option Depending on where you maintain table files, choose a naming convention that identifies each file adequately. For example, if you maintain all product table files in one location, the filename should include the product name and version (e.g., ${UPS_PROD_NAME}_${UPS_PROD_VERSION}.table ); if each is kept under its product root directory, the product name is not necessary (e.g., ${UPS_PROD_VERSION}.table ). Depending on where you maintain table files, choose a naming convention that identifies each file adequately. For example, if you maintain all product table files in one location, the filename should include the product name and version (e.g., ${UPS_PROD_NAME}_${UPS_PROD_VERSION}.table ); if each is kept under its product root directory, the product name is not necessary (e.g., ${UPS_PROD_VERSION}.table ).
UNWIND_ARCHIVE_FILE UNWIND_ARCHIVE_FILE absolute path to directory in which to unwind archive file (tar file) of product absolute path to directory in which to unwind archive file (tar file) of product Used only on distribution server configurations. Used only on distribution server configurations.
UPS_ARCHIVE_FILE UPS_ARCHIVE_FILE archive file (tar file) location that UPD specifies in archive file (tar file) location that UPD specifies in ups declare -T ftp://host${UPS_ARCHIVE_FILE} ups declare -T ftp://host${UPS_ARCHIVE_FILE} Used only on distribution server configurations. Used only on distribution server configurations.

  32.3.2 Read-Only Variables Usable in Location Definitions

  The following predefined UPS/UPD read-only variables can be used in the definition of locations described above. These variables get their values from the command line and/or the dependency list.

  Do not try to redefine these variables. When you use these variables, always enclose them in curly brackets ({}) as shown in the list.
Table 32.3.2-a:Table 32.3.2-a:

${UPS_USERCODE_DB} ${UPS_USERCODE_DB} database containing UPD configuration database containing UPD configuration
${UPS_USERCODE_DIR} ${UPS_USERCODE_DIR} directory containing UPD configuration directory containing UPD configuration
${UPS_PROD_NAME} ${UPS_PROD_NAME} name of product name of product
${UPS_PROD_FLAVOR} ${UPS_PROD_FLAVOR} flavor of product flavor of product
${UPS_PROD_QUALIFIERS} ${UPS_PROD_QUALIFIERS} qualifiers of product qualifiers of product
${UPS_BASE_FLAVOR} ${UPS_BASE_FLAVOR} flavor trimmed as in ups flavor -1 flavor trimmed as in ups flavor -1
${DASH_PROD_FLAVOR} ${DASH_PROD_FLAVOR} flavor with non-word characters replaced by dashes; e.g., if {UPS_PROD_FLAVOR} is set to SunOS+5 , then {DASH_PROD_FLAVOR} has the value SunOS-5 . This is used to avoid problems with unusual symbols in file and directory names. flavor with non-word characters replaced by dashes; e.g., if {UPS_PROD_FLAVOR} is set to SunOS+5 , then {DASH_PROD_FLAVOR} has the value SunOS-5 . This is used to avoid problems with unusual symbols in file and directory names.
${DASH_PROD_QUALIFIERS} ${DASH_PROD_QUALIFIERS} qualifier list with non-word characters replaced by dashes; e.g., if {UPS_PROD_QUALIFIERS} is qual1+qual2 , then {DASH_PROD_QUALIFIERS} is qual1-qual2 . This is used to avoid problems with unusual symbols in file and directory names. qualifier list with non-word characters replaced by dashes; e.g., if {UPS_PROD_QUALIFIERS} is qual1+qual2 , then {DASH_PROD_QUALIFIERS} is qual1-qual2 . This is used to avoid problems with unusual symbols in file and directory names.
${SUFFIX} ${SUFFIX} suffix of archive file; e.g., tar , zip , etc. suffix of archive file; e.g., tar , zip , etc. Used only on distribution server configurations. Used only on distribution server configurations.
${PROD_DIR_PREFIX} ${PROD_DIR_PREFIX} PROD_DIR_PREFIX of database, defined in UPS configuration file dbconfig (see Chapter 31 ) PROD_DIR_PREFIX of database, defined in UPS configuration file dbconfig (see Chapter 31 )

  32.3.3 Sample Location Definitions

  The following partial stanza, taken from the example in section 32.5.1 , shows several location specifications:

COMMON:
     UPS_THIS_DB  = "${UPD_USERCODE_DB}" 
     UPS_PROD_DIR = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}
                     ${DASH_PROD_QUALIFIERS}" ( %{font-weight: normal;color: #000000}this must be all on one line in the real file% )
  UNWIND_PROD_DIR = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
      UPS_UPS_DIR = "ups" 
   UNWIND_UPS_DIR = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 

#    Default (do not actually set UPS_TABLE_DIR):
#   UPS_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
 UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 
...
END:

  32.4 Pre- and Postdeclare Actions

  An action is a construction that identifies a UPS or user-defined operation via the ACTION keyword, and lists functions to perform, in addition to any internal processes, when the operation is executed. An action stanza has the format:

ACTION=<VALUE>
      <function_1>([<argument_1>] [, <argument_2>] ...)
      <function_2>([<argument_1>] [, <argument_2>] ...)
      ...

  The updconfig file uses actions to define the steps UPD is to perform during an installation/update of the matched product instance(s). The ACTION keyword values indicate when to perform the steps (before or after issuing the ups declare command), and the steps themselves are listed as functions under the ACTION line. In a updconfig file, actions can be listed anywhere in the COMMON: part of a stanza.

  32.4.1 ACTION Keyword Values

  Currently two action keyword values are supported for use in updconfig :
Table 32.4.1-a:Table 32.4.1-a:


p<>.   predeclare

p<>.   Perform listed functions after product files have been unwound, but before the product has been declared

p<>.   postdeclare

p<>.   Perform listed functions after product has been declared

  Functions are then listed after the ACTION keyword line, using the following syntax:

Action = predeclare
    function(arg,arg,...)
    function(arg,arg,...)

  32.4.2 The execute Function

  Currently, only the execute function is supported for use in updconfig :

execute("<command>", <UPS_ENV_FLAG>, [, <VARIABLE>])

  It executes a shell-independent command and (optionally) assigns the output to an environment variable, <VARIABLE> . It takes a required parameter ( UPS_ENV_FLAG ) which indicates whether to define UPS local variables. This parameter can take the following values:

  UPS_ENV

  define all local UPS environment variables before sourcing (the script or command relies on these being defined)

  NO_UPS_ENV

  do not define the local UPS environment variables (the script or command doesn't use them)

  If the optional third argument, <VARIABLE> , is not specified, then the specified command is executed but the output from that command is not saved. This command does not have to be shell-independent.

  For example, say that you want to make group-writable the directory in which a product has been unwound before it is declared. You would include the action:

ACTION = PREDECLARE
    execute ("chmod -R g+w ${UNWIND_PROD_DIR}", NO_UPS_ENV )

  32.5 Examples

  32.5.1 Generic Template updconfig File

  This example is taken from the template, $UPD_DIR/ups/updconfig.template (comments are included in the actual template file). The template is designed to be usable as is , if:

  • you have only one UPS database
  • you want your product root hierarchy to be:
    p<>.   ${PROD_DIR_PREFIX}/<product>/<version>/<flavor><qualifiers>
  • you want your table files to reside in the UPS database as:
    p<>.   ${UPS_THIS_DB}/<product>/<version>.table

  If your requirements are different, this file is still useful as a starting point from which to make modifications.

File = updconfig
#
GROUP:
  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = ANY

COMMON:
     UPS_THIS_DB  = "${UPD_USERCODE_DB}" 
     UPS_PROD_DIR =  "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}
                      ${DASH_PROD_QUALIFIERS}" ( %{font-weight: normal;color: #000000}no line break in real file% )
  UNWIND_PROD_DIR = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
      UPS_UPS_DIR = "ups" 
   UNWIND_UPS_DIR = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 

#    Default (do not actually set UPS_TABLE_DIR):
#   UPS_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
 UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 
#
#    Possible alternative, where the table files live
#    within the product's ups directory.  Note,
#    in this case you ALSO should not set UPS_TABLE_DIR.
#
##  UPS_TABLE_DIR = "${UNWIND_UPS_DIR}" 
#UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
# UPS_TABLE_FILE  = "${UPS_PROD_NAME}.table" 
#
#  ACTION = PREDECLARE
#           add functions
#  ACTION = POSTDECLARE
#           add functions
END:

  32.5.2 Distribution from the fnkits Node Only

  As a second example, we show the GROUP: portion of a file that specifies a particular distribution host. Aside from the dist_node entry, the stanza is identical to that of the template updconfig file, and therefore applies to any products coming from the specified host, fnkits.fnal.gov . fnkits is the central Computing Division product server, and there are several names for it. All the names are all listed and delimited by colons.

File = updconfig

GROUP:

  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = fnkits:fnkits.fnal.gov:kits:kits.fnal.gov:upd:upd.fnal.gov

COMMON:
...
END:

  This UPD configuration file could be expanded to include additional stanzas to accommodate products from other distribution nodes.

  32.5.3 Customized Treatment of ups Directory and Table Files

  In this example, the distribution node again has changed relative to the template, and this time there are also changes in the COMMON: section. The distribution node is e007.dist.xyz.edu . UPS_PROD_DIR is no longer defined relative to PROD_DIR_PREFIX, but is now placed under the /e007/base_code directory. All the table files are placed in a single directory ( /e007/table_files ), therefore the table file names must include the product name in order to be identifiable. Here they will be named <product>_<version>.table (defined using the corresponding variables as ${UPS_PROD_NAME}_${UPS_PROD_VERSION}.table ).

File = updconfig

GROUP:
  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = e007_dist.xyz.edu

COMMON:
      UPS_THIS_DB      = "${UPD_USERCODE_DB}" 
     UPS_PROD_DIR     = "/e007/base_code/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/
                        ${UPS_PROD_FLAVOR}${UPS_PROD_QUALIFIERS}" ( %{font-weight: normal;color: #000000}no line break in real file% )
     UNWIND_PROD_DIR  = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
     UPS_UPS_DIR      = "ups" 
     UNWIND_UPS_DIR   = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 
     UPS_TABLE_DIR    = "/e007/table_files" 
     UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
     UPS_TABLE_FILE   = "${UPS_PROD_NAME}_${UPS_PROD_VERSION}.table" 
END:

  32.5.4 Implementing Multiple Configurations

  Here is an example that shows how to configure the file if more than one database and distribution node are used. The first section instructs UPD where to unwind products that are distributed from fnkits and how to declare them. The second section, with different naming conventions and file hierarchies, instructs UPD where to unwind and how to declare products obtained from the CDF distribution node cdf-kits.fnal.gov .

File = updconfig

GROUP:

  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = fnkits:fnkits.fnal.gov:kits:kits.fnal.gov:upd:upd.fnal.gov

COMMON:

     UPS_THIS_DB      = "${UPD_USERCODE_DB}" 
     UPS_PROD_DIR     = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${UPS_PROD_FLAVOR}
                         ${UPS_PROD_QUALIFIERS}"     ( %{font-weight: normal;color: #000000}no line break in real file% )
     UNWIND_PROD_DIR  = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
     UPS_UPS_DIR      = "ups" 
     UNWIND_UPS_DIR   = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 
###  UPS_TABLE_DIR    = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
     UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
     UPS_TABLE_FILE   = "${UPS_PROD_VERSION}.table" 

END:

GROUP:

  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = cdf-kits.fnal.gov

COMMON:

     UPS_THIS_DB      = "~cdfsoft/declare" 
     UPS_PROD_DIR     = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${UPS_PROD_FLAVOR}
                         ${UPS_PROD_QUALIFIERS}"  ( %{font-weight: normal;color: #000000}no line break in real file% )
     UNWIND_PROD_DIR  = "/cdf/products/${UPS_PROD_NAME}/${UPS_PROD_VERSION}" 
     UPS_UPS_DIR      = "ups" 
     UNWIND_UPS_DIR   = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 
###  UPS_TABLE_DIR    = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
     UNWIND_TABLE_DIR = "${UPS_TABLE_DIR}" 
     UPS_TABLE_FILE   = "${UPS_PROD_VERSION}.table" 

END:

  32.5.5 Sample Configuration for AFS Space Using ACTIONS

  In AFS space, you may need to release the read-write volume before you can declare a product, as discussed in section 9.3 Installing Products into AFS Space . For this you would use a PREDECLARE action. You may also need to release the read-write UPS database after the product is declared, which can be done in a POSTDECLARE action. These actions are shown in this example.

File = updconfig

 GROUP:
  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = ANY

COMMON:
     UPS_THIS_DB = "/afs/.fnal.gov/ups/db" 
     UPS_PROD_DIR = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${UPS_PROD_FLAVOR}
                     ${UPS_PROD_QUALIFIERS}"  ( %{font-weight: normal;color: #000000}no line break in real file% )
  UNWIND_PROD_DIR = "/afs/.fnal.gov/ups/${UPS_PROD_DIR}" 
      UPS_UPS_DIR = "ups" 
   UNWIND_UPS_DIR = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 
 UNWIND_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 

  ACTION = PREDECLARE
    Execute("/usr/local/bin/upd_volrelease ${UNWIND_PROD_DIR}", NO_UPS_ENV)
  ACTION = POSTDECLARE
    Execute("/usr/local/bin/upd_volrelease ${UPS_THIS_DB}", NO_UPS_ENV)

END:

  32.5.6 Distribution Node Configuration

  For this example, we present an abridged version of the updconfig file used on fnkits .

  The updconfig file on fnkits includes several stanzas, each of which pertains to a category of product. The product-matching criterion for each stanza is an options=<option> line which indicates the category. This example shows only the stanzas used for ordinary distributed products (the default) and locally installed products. The default stanza is identified by the absence of an option, and the local stanza is identified by the option local .

  The default stanza includes a PREDECLARE and a POSTDECLARE action. The PREDECLARE action contains a set of execute statements to chmod/chgrp the files to the right group id and permissions. The POSTDECLARE action makes a convenience tar file of the ups directory for users downloading via FTP . The stanza for local products contains no actions.

  • Many of the location definitions and functions are quite long, and are shown here on multiple lines for readability.
  • In the real file, each definition or function must be contained on a single line.
File = updconfig

#
#>>> Define GROUP.
#    If all of your products go in the same database,
#    using the same naming conventions, you can
#    group them all together.
GROUP:
  product       = ANY
  flavor        = ANY
  qualifiers    = ANY
  options       = ANY
  dist_database = ANY
  dist_node     = ANY

COMMON:
#>>> Define UPS_THIS_DB.
#    This is the database into which the above products will
#    be declared by upd.
#    Default:
#    UPS_THIS_DB is set to the database where UPD was declared.
#    You may need to set it differently for the products you're describing.
     UPS_THIS_DB = "${UPD_USERCODE_DB}" 
#
#    Other examples might be:
#    UPS_THIS_DB = "/usr/products/ups_database" 
#    UPS_THIS_DB = "~cdfsoft/declared" 

#>>> Define UPS_PROD_DIR.
#    The UPS_PROD_DIR determines the product root file
#    hierarchy for products in the ups database being 
#    described.
#    Examples are shown below for the case of the product
#    instance "mh v1_6_6 IRIX+6".  Uncomment the 
#    one that matches your system.
#    In all of the example, the UPS_PROD_DIR is a RELATIVE
#    path; this means that the product will be declared with
#    a relative path (relative to PROD_DIR_PREFIX).
#
#    prod_dir: /usr/products/mh/v1_6_6/IRIX+6
     UPS_PROD_DIR = "${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}${DASH_PROD
_QUALIFIERS}" 

#
#    prod_dir: /usr/products/IRIX/mh/v1_6_6
#    UPS_PROD_DIR = "${UPS_BASE_FLAVOR}/${UPS_PROD_NAME}/${UPS_PROD_VERSION}${DASH_PROD_
QUALIFIERS}" 
#
#    prod_dir: /usr/products/IRIX+6/mh/v1_6_6
#    UPS_PROD_DIR = "${DASH_PROD_FLAVOR}/${UPS_PROD_NAME}/${UPS_PROD_VERSION}${DASH_PROD
_QUALIFIERS}" 
#
#    prod_dir: /afs/fnal/ups/mh/v1_6_6/IRIX+6
#    UPS_PROD_DIR = "/afs/fnal/ups/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAV
OR}${DASH_PROD_QUALIFIERS}" 
#
#    prod_dir: ${ENVVAR}/mh/v1_6_6/IRIX+6
#    UPS_PROD_DIR = "\${ENVVAR}/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}
${DASH_PROD_QUALIFIERS}" 
#

#>>> Define UNWIND_PROD_DIR.
#    The UNWIND_PROD_DIR is the directory into which the product
#    is unwound.  In most cases, it will be the same as the UPS_PROD_DIR
#    defined above; in AFS space, or under certain NFS mounting configurations,
#    you may unwind the product in a directory that has a different name
#    than the directory where you declare it.
#
#    THE DEFAULT IS THAT THE UNWIND_PROD_DIR IS THE SAME AS THE
#    UPS_PROD_DIR.  NOTE that you need to prepend PROD_DIR_PREFIX
#    if the UPS_PROD_DIR was specified as a relative path!
#    Change this is your situation is different!

#     Default:
  UNWIND_PROD_DIR = "${PROD_DIR_PREFIX}/${UPS_PROD_DIR}" 
#
#     AFS unwind dir:
# UNWIND_PROD_DIR = "/afs/.fnal.gov/ups/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD
_FLAVOR}${DASH_PROD_QUALIFIERS}" 
#
#     Declared based on environmental variable:
# UNWIND_PROD_DIR = "${ENVVAR}/${UPS_PROD_NAME}/${UPS_PROD_VERSION}/${DASH_PROD_FLAVOR}$
{DASH_PROD_QUALIFIERS}" 

#>>> Define UPS_UPS_DIR.
#    The UPS_UPS_DIR is the products' ups directory.
#    Default is the directory named "ups" under the product root directory.
      UPS_UPS_DIR = "ups" 

#>>> Define UNWIND_UPS_DIR.
#    The UNWIND_UPS_DIR is where to unwind the ups directory.
#    The default is the same directory as the UPS_UPS_DIR.
   UNWIND_UPS_DIR = "${UNWIND_PROD_DIR}/${UPS_UPS_DIR}" 

#>>> Define UPS_TABLE_FILE, UNWIND_TABLE_DIR, 
#>>> and optionally, UPS_TABLE_DIR.
#    The naming convention for table files.  The default
#    is to put the table file in the ups database, so that
#    one table file may be used for multiple flavors of the
#    product.  If you put your table files here,
#    you should NOT set UPS_TABLE_DIR.
#    Change this if your situation is different!
#
#    Default:
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 
 UNWIND_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
#   UPS_TABLE_DIR = "${UNWIND_TABLE_DIR}" 
#    Default:
   UPS_TABLE_FILE = "${UPS_PROD_VERSION}.table" 
 UNWIND_TABLE_DIR = "${UPS_THIS_DB}/${UPS_PROD_NAME}" 
#   UPS_TABLE_DIR = "${UNWIND_TABLE_DIR}" 
#
#    Possible alternative, where the table files live
#    within the product's ups directory.  Note,
#    in this case you ALSO should not set UPS_TABLE_DIR.
#
# UPS_TABLE_FILE  = "${UPS_PROD_NAME}.table" 
#UNWIND_TABLE_DIR = "${UNWIND_UPS_DIR}" 
##  UPS_TABLE_DIR = "${UNWIND_TABLE_DIR}" 

#>>> Define PREDECLARE, POSTDECLARE actions
#
#  Actions which take place after the product is
#  unwound, before the product is declared.
#  Uncomment and modify as appropriate.
#
#  ACTION = PREDECLARE
#
#      example: you may wish to make the directory
#      where the product has been unwound group writeable:
#      EXECUTE ( "chmod -R g+w ${UNWIND_PROD_DIR}", NO_UPS_ENV )
#
#      example: in AFS space, you may need to release
#      the read-write volume before you can declare the product:
#      EXECUTE ( "upd_volrelease ${UNWIND_PROD_DIR}", NO_UPS_ENV )

#
#  Actions which take place after the product is
#  declared.
#  Uncomment and modify as appropriate.
#
#  ACTION = POSTDECLARE
#       example: in AFS space, you may need to release
#       the read-write ups database
#       EXECUTE ( "upd_volrelease ${UPS_THIS_DB}", NO_UPS_ENV )
END:

 

TOC PREV NEXT

Last revised on May 2014