1. Introduction

Various SAM servers and clients typically require one or more environment variables to be set correctly. Variables that are needed by the different servers or clients are not always the same. Furthermore, there may be several different SAM operating environments (e.g., D0 Production, D0 Integration, D0 Development, corresponding CDF environments, etc.). Because of that there is usually a need for multiple SAM configurations (i.e., sets of environment variables) coexisting on the same node or a cluster of nodes. Those configurations are managed by the SAM Config package (module sam_config in the CVS repository).

2. UPS installation

Just like any other Fermilab UPS/UPD product, SAM Config is installed by invoking the upd install command. SAM Config will be installed automatically if you perform a "typical" installation of SAM software, or you can install it independently: 
   $ upd install -G -c sam
or $ upd install -G -c sam_config

If you are upgrading from an existing sam_config installation, you will also need to invoke the command 

   $ ups sync sam_config
The sam_config product uses the sam_ns_ior product (module sam_ns_ior in the CVS repository) to obtain the underlying symbolic references to the various naming service IOR's.

3. UPS commands

Once installed, SAM Config allows SAM product administrators to add new configurations, edit or remove the existing ones, set a default configuration, inquire for the list of all existing configurations, or examine a particular configuration for its environment variables.

3.1. ups tailor sam_config

This is a top level command which allows users to choose an allowed action for manipulating SAM configurations: 
$ ups tailor sam_config
What would you like to do?
   [a: add configuration]
   [e: edit configuration]
   [r: remove configuration]
   [s: set default configuration]
   [d: done (default)]

$
Note that if there are no existing SAM configurations, the only allowed action is adding a new one. All individual actions are described in more detail below.

3.1. ups add sam_config

This command allows users to add a new configuration. The steps involved are:
  1. Choose a base configuration (either an existing one or a predefined one).
  2. Choose new configuration qualifier.
  3. Choose new configuration description.
Note here that the predefined configurations are distributed with SAM Config product, and are distinguished by qualifiers starting and ending with double underscore ("__"). As an example, adding new configuration with qualifier prd and based on the predefined D0 Production User configuration would look like this: 
$ ups list -acK+ sam_config 
"sam_config" "v7_1_0" "NULL" "" "current" 
$ ups add sam_config
Adding configuration...
Enter choice for the base configuration:
   [1: CDF Development (__cdf_dev__)]
   [2: CDF Development DB Server (__cdf_db_server_dev__)]
   [3: CDF Development Station Server (__cdf_station_server_dev__)]
   [4: CDF Development User (__cdf_user_dev__)]
   [5: D0 Development (__d0_dev__)]
   [6: D0 Development DB Server (__d0_db_server_dev__)]
   [7: D0 Development Station Server (__d0_station_server_dev__)]
   [8: D0 Development User (__d0_user_dev__)]
   [9: D0 Integration (__d0_int__)]
   [10: D0 Integration DB Server (__d0_db_server_int__)]
   [11: D0 Integration Station Server (__d0_station_server_int__)]
   [12: D0 Integration User (__d0_user_int__)]
   [13: D0 Production (__d0_prd__)]
   [14: D0 Production DB Server (__d0_db_server_prd__)]
   [15: D0 Production Station Server (__d0_station_server_prd__)]
   [16: D0 Production User (__d0_user_prd__)]
   [17: abort action (default)]
16
You have chosen "D0 Production User (__d0_user_prd__)" as your base configuration. 
Enter new configuration qualifier:
prd
Enter new configuration description:
New D0 User
Adding configuration prd based on configuration __d0_user_prd__...
Added configuration prd. 
Declaring sam_config with qualifier prd into the UPS database...
Executing: ups declare -r /usr/local/ups/prd/sam_config/v7_1_0/NULL \
          -M /usr/local/ups/db/sam_config/v7_1_0 -m sam_config_prd.table \
          sam_config v7_1_0 -q prd -f NULL -c
$ ups list -acK+ sam_config 
"sam_config" "v7_1_0" "NULL" "" "current" 
"sam_config" "v7_1_0" "NULL" "prd" "current" 
$

3.1.1 ups add_from_env sam_config

This action acts like 'add', but gets its input from the environment variable SAM_CONFIG_CONFIGS_FROM_ENV.
Example:
using 
SAM_CONFIG_CONFIGS_FROM_ENV="d0_dev|cdf_dev|d0_prd|cdf_prd"
it will declare sam_config to the ups db with the qualifiers d0_dev, cdf_dev, ..., based on the base configurations files at conf/__d0_dev__.env, conf/__cdf_dev__.env, ...
Details:
A configuration is encoded as follow (e.g. for 2 configs) 
 Qualifier1:BaseQualifier1:Name1|Qualifier2:BaseQualifier2:Name2
where
  1. Qualifier is the qualifier to be used in the ups db
  2. BaseQualifier is the string used to look for the conf/XXX.env file
  3. name is a description of the configuration
BaseQualifier and/or Name do not need to be present: the default are strings built from Qualifier:
  1. BaseQualifier = "__" + Qualifier + "__"
  2. Name = Qualifier

3.2. ups edit sam_config

This command can be used to modify an existing configuration. One can add, remove, or modify environment variables. For example: 
$ ups list -acK+ sam_config
"sam_config" "v7_1_0" "NULL" "" "current" 
"sam_config" "v7_1_0" "NULL" "prd" "current" 
$ ups edit sam_config
Modifying configuration...
Enter choice for the existing configuration:
   [1: New D0 User (prd)]
   [2: abort action (default)]
1
You have chosen "New D0 User (prd)" configuration. 
Modifying configuration prd... 
Current configuration:
   [1: FNORB_NAMING_SERVICE=${SAM_D0_PRD_NS_IOR}
   [2: SAM_NAMING_SERVICE_IOR=${SAM_D0_PRD_NS_IOR}
   [3: SAM_DB_SERVER_NAME=SAMDbServer.user_prd:SAMDbServer]
   [4: SAM_NAMING_SERVICE=d0db.fnal.gov:9010]
   [5: SAM_LOG_SERVER_ADDR=d0db.fnal.gov:40583]
What would you like to do?
   [a: add variable]
   [e: edit variable]
   [q: quit]
   [r: remove variable]
   [d: done (default)]
a
Enter variable to add: 
NEW_USER_VARIABLE
Enter value for NEW_USER_VARIABLE: 
value_of_the_new_user_variable
Current configuration:
   [1: FNORB_NAMING_SERVICE=${SAM_D0_PRD_NS_IOR}
   [2: NEW_USER_VARIABLE=value_of_the_new_user_variable]
   [3: SAM_NAMING_SERVICE_IOR=${SAM_D0_PRD_NS_IOR}
   [4: SAM_DB_SERVER_NAME=SAMDbServer.user_prd:SAMDbServer]
   [5: SAM_NAMING_SERVICE=d0db.fnal.gov:9010]
   [6: SAM_LOG_SERVER_ADDR=d0db.fnal.gov:40583]
What would you like to do?
   [a: add variable]
   [e: edit variable]
   [q: quit]
   [r: remove variable]
   [d: done (default)]

Are you sure that you want to keep these changes?
   [n: no]
   [y: yes (default)]

Modified configuration prd. 
Undeclaring sam_config with qualifier prd from the UPS database...
Executing: ups undeclare sam_config `ups list -acK version \
           sam_config -q prd -f NULL | sed 's/"//g'` -q prd -f NULL
Declaring sam_config with qualifier prd into the UPS database...
Executing: ups declare -r /usr/local/ups/prd/sam_config/v7_1_0/NULL \
           -M /usr/local/ups/db/sam_config/v7_1_0 -m sam_config_prd.table \
           sam_config v7_1_0 -q prd -f NULL -c
$ ups list -acK+ sam_config 
"sam_config" "v7_1_0" "NULL" "" "current" 
"sam_config" "v7_1_0" "NULL" "prd" "current" 
$
Note that SAM Config keeps track of the history of changes that are made to SAM configurations.

3.3. ups inquire sam_config

The inquire command will result in the list of all existing SAM configurations: 
$ ups list -acK+ sam_config
"sam_config" "v7_1_0" "NULL" "" "current" 
"sam_config" "v7_1_0" "NULL" "prd" "current" 
$ ups inquire sam_config
EXISTING_CONFIGURATION=New D0 User|prd|prd.env

$
In the above output, the first field is a configuration description, the second one is its qualifier, and the last one is a text file containing all of the environment variables this particular configuration is using.

Note that one can also inquire on an existing configuration and obtain the list of all environment variables that particular configuration is using: 

$ ups inquire sam_config -q prd
SAM_CONFIGURATION_NAME=New D0 User
SAM_CONFIGURATION_FILE=prd.env
SAM_CONFIGURATION_QUALIFIER=prd
SAM_NAMING_SERVICE=d0db.fnal.gov:9010
NEW_USER_VARIABLE=value_of_the_new_user_variable
SAM_NAMING_SERVICE_IOR=${SAM_D0_PRD_NS_IOR}
SAM_DB_SERVER_NAME=SAMDbServer.user_prd:SAMDbServer
FNORB_NAMING_SERVICE=${SAM_D0_PRD_NS_IOR}
SAM_LOG_SERVER_ADDR=d0db.fnal.gov:40583

$

3.4. ups setdefault sam_config

After SAM Config is installed and new configurations are added, one can use this command to set the default configuration (i.e., the configuration which will be used whenever SAM Config is setup without giving a particular qualifier). Here is the example: 
$ ups list -acK+ sam_config
"sam_config" "v7_1_0" "NULL" "" "current" 
"sam_config" "v7_1_0" "NULL" "prd" "current" 
$ setup sam_config
No SAM configuration has been set as default at this time.
$ ups setdefault sam_config
Setting default configuration...
Enter choice for the existing configuration:
   [1: New D0 User (prd)]
   [2: abort action (default)]
1
You have chosen "New D0 User (prd)" configuration. 
Setting configuration prd as default...
Set configuration prd as default.
$ ups inquire sam_config 
DEFAULT_CONFIGURATION=New D0 User|prd|prd.env
EXISTING_CONFIGURATION=New D0 User|prd|prd.env

$ echo $NEW_USER_VARIABLE
NEW_USER_VARIABLE: Undefined variable.
$ setup sam_config
$ echo $NEW_USER_VARIABLE
value_of_the_new_user_variable
$

3.5. ups delete sam_config

The delete command allows users to remove an existing configuration. For example: 
$ ups list -acK+ sam_config 
"sam_config" "v7_1_0" "NULL" "" "current" 
"sam_config" "v7_1_0" "NULL" "prd" "current" 
$ ups delete sam_config
Deleting configuration...
Enter choice for the existing configuration:
   [1: New D0 User (prd)]
   [2: abort action (default)]
1
You have chosen "New D0 User (prd)" configuration. 
Deleting configuration prd...
Deleted configuration prd.
Undeclaring sam_config with qualifier prd from the UPS database...
Executing: ups undeclare sam_config `ups list -acK version sam_config \
           -q prd -f NULL | sed 's/"//g'` -q prd -f NULL
$ ups list -acK+ sam_config
"sam_config" "v7_1_0" "NULL" "" "current" 
$ ups inquire sam_config
No SAM configurations exist at this time.
$

3.6. ups sync sam_config

Purpose of the sync command is to re-declare already configured SAM configurations as current in ups, but with the new version number. Even though this is not strictly necessary, executing this command after upgrades is a good idea. Here is an example: 
$ ups list -acK+ sam_config
"sam_config" "v7_1_0" "NULL" "" "current" 
"sam_config" "v7_1_0" "NULL" "prd" "current" 
$ upd install -G-c sam_config v7_1_1
Creating version link in /usr/local/ups/db/sam_config/Symlinks for sam_config v7_1_1.
Creating current link in /usr/local/ups/db/sam_config/Symlinks for sam_config v7_1_1.
informational: installed sam_config v7_1_1.
upd install succeeded.
$ ups list -acK+ sam_config
"sam_config" "v7_1_0" "NULL" "prd" "current" 
"sam_config" "v7_1_1" "NULL" "" "current" 
$ ups sync sam_config
Regenerating table file for qualifier 'prd'...
Executing: ups declare -r /usr/local/ups/prd/sam_config/v7_1_1/NULL \
       -M /usr/local/ups/db/sam_config/v7_1_1 -m sam_config_prd.table \
        sam_config v7_1_1 -q prd -f NULL -c
$ ups list -acK+ sam_config
"sam_config" "v7_1_0" "NULL" "" ""
"sam_config" "v7_1_1" "NULL" "" "current" 
"sam_config" "v7_1_1" "NULL" "prd" "current" 
$

4. Notes for developers

4.1 Package details

The package consists of a set of Python classes which manage and manipulate SAM configurations and their variables, together with a set of configuration files. Each (existing or predefined) configuration has its own file with a list of its environment variables. There is also a master file (sam_config/conf/__conf__.env) containing a list of all available configurations, which is used for bootstrapping the Python scripts.

Note that SAM Config (i.e., its ConfigurationManager class) manages its configurations independently of UPS. Interoperability with UPS (i.e., all of the above described commands) is provided via the specialized UPSConfigurationManager class.

4.2 Adding new predefined configurations

There are two simple steps involved in adding a new predefined configuration, none of which involves any Python coding:
  1. List all of the environment variables (in the form XXX=value_of_xxx) in the text file sam_config/conf/__new_cfg__.env.
  2. Add the following line to the sam_config/conf/__config__.env file: 
      PREDEFINED_CONFIGURATION=New Cfg Description|__new_cfg__|__new_cfg__.env
    As mentioned above, the meaning of the above columns are new configuration description, its qualifier, and file with its environment variables, respectively.