Question & Answer
Question
How do you update the ITM configuration environment variables persistently?
Answer
Overview
The ITM agents and servers have many possible environment variables which can be used to change the configuration. This technote describes a best practice way of creating persistent configuration changes.
This general scheme has been documented in the ITM 623 documentation. See this Documentation
At ITM 623 the procedure is easier to implement for these reasons:
- 1) The xx.environment values do not need to be quoted.
2) The source include statement is not needed in the ini file.
3) There is no need for a dummy configuration for TEMS changes.
4) There is a new tacmd setAgentConnection function that eases changes to connections and environment variables - including mass changes.
The technote still has some value in explaining the background and justification of the scheme.
In addition there are certain cases where some ITM substitution is used
Using KBB_RAS1_LOG to Configure ITM Diagnostic and Operations Logs
http://www.ibm.com/support/docview.wss?uid=swg21573387
and that must be added using the source include method documented here.
Background
ITM Linux/Unix processes have configuration information that resides in multiple places. All these files exist in the <install>/config directory. One location is the <xx>.ini file, where <xx> is the product code such as ux for Unix OS Agent. Additional information is stored in locations such as <install>/config/.ConfigData/k<xx>env where the user defaults and configuration dialog variables are stored. Some information is also stored in other files such as env.config. All these files are processed to create a config file.
Agent config files are created when an agent is configured and each time the agent is started [or stopped] and has one of these forms
<xx>.config
<xx>_<instance>.config
<hostname>_<xx>.config
<hostname>_<xx>_<instance>.config
TEMS config files are created during the TEMS configuration process and have the form
<hostname>_ms_<temsname>.config
The config file is what the agent uses to define the runtime environment variables. This is in a Korn shell form - for example values are typically single quoted.
Configuration and Environment Variables
Each ITM process has a number of environment variables which can be used to control its operation. For example, CTIRA_HOSTNAME can be used to control the hostname section of the managed system name. There are many environment variables. For example from the ITM Installation and Setup Guide - a list of the documented Agent environment variables
More can be seen in this section on performance tuning
This is not an inclusive list. Future levels of ITM will likely include new environment variables. In addition, you may be given environment variables to use by IBM Support.
How do you configure these changes so they will persist after maintenance and configuration changes? If the ini file is changed directly, a future upgrade could remove those changes as the upgrade rewrites the ini file. If the config file is changed directly, configuring, starting or stopping the agent could remove those changes as the config file is rewritten. The following explains a procedure which will create a persistent change in the environment variables.
Source Include Method
Example 1: Override the CTIRA_HOSTNAME to change the hostname section of the Managed System Name
First create a file in the config directory called <xx>.environment with the contents
export CTIRA_HOSTNAME='myname'
The contents of <xx>.environment will end up being included into the environment at the end of the .config file, so it must follow korn shell rules.
. $CANDLEHOME$/config/<xx>.environment:
Next update the ini file to add the following line to the end:
. $CANDLEHOME$/config/<xx>.environment
The line starts with a period, then blank and finally a fully qualified file name. This is known as a source include file. The initial period means include and the rest of the line is the path of the file whose contents are included. $CANDLEHOME$ will always be substituted with the current installation directory.
Results:
When the agent is started, the dot source include file line will be copied near the end of the .config file. When the agent starts the lines in the override file will be included and processed after other lines in the .config file.
Note: for TEMS you must do a TEMS configuration to regenerate the .config file.
./itmcmd config -S -t <temsname>
Note: for instance agents you must do an agent configuration for each of the instances to regenerate the agent instance .config files.
./itmcmd config -A -o <instance> <xx>
During an agent upgrade, the ini file will be recreated. Unknown elements like the dot source include will be preserved and will be present at the end of the new ini file. The <xx>.environment override file will not be affected and thus the changes are persistent.
Example 2: Altering an existing variable KDC_FAMILIES
The KDC_FAMILIES environment variable is particularly challenging because much of the data is created from the .ConfigData/k<xx>env dialog file. For example, suppose we knew from looking at the existing .config file that KDC_FAMILIES looked like this
export KDC_FAMILIES='ip.pipe port:1918 ip use:n ip.spipe use:n sna use:n HTTP:1920'
Or a more robust content line would be
export KDC_FAMILIES="ephemeral:y ${KDC_FAMILIES}"
In this second form we use the shell technique of double quotes that allows embedded shell variables to be expanded. Thus the ephemeral:y is followed by the existing KDC_FAMILIES content.
The use of export here means that the environment variable will be available for both the starting program and any spawned tasks. Export should always be used in the <xx>.environment file because it is required sometimes and never does any harm.
It is strongly recommended that you create an <xx>.environment file for each product that you need to modify. This will allow your overrides to persist for upgrades in current releases and in future releases.
Implementation
There remains the question of how to implement this. Some customers may have methods to run commands on many servers. The addition of the source include and the creation of the <xx>.environment override files will then be a post install step like many other such steps. If you have a way to perform that post installation process then use it by all means.
If not, see the following technote:
Running Commands Using Always True ITM situations
http://www-01.ibm.com/support/docview.wss?uid=swg21390488
which shows how to run single commands on multiple agents using situations. You could append a line to the ini file and create the override file with a command that looks like this:
echo export KDC_FAMILIES=\"ephemeral:y \${KDC_FAMILIES}\" > $CANDLEHOME/config/lz.environment ; echo . \$CANDLEHOME\$/config/lz.environment >> $CANDLEHOME/config/lz.ini
Backslashes are needed to preserve special characters through shell processing. The semicolon in the middle is used to run commands in sequence,
You will also need to ensure that the changed file attributes and owner and groups are similar to the existing ini files so that let the files can be accessed during normal processing.
The command line above is simplistic since you could run it twice and get a double source include line. That might not hurt but it wouldn't be good.
Warnings and Worries
If you do a manual reconfiguration later on and you have completely overridden variables that are modified by the configuration dialog, the overrides will cause those dialog configuration changes to be silently ignored. If you use the more robust way of overriding existing variables described in Example 2, those dialog configuration changes will be included. Always track the overrides.
Future ITM release levels may change the meaning and defaults of configuration variables. In every case you will need to understand and make appropriate changes to achieve your goals.
In the worst case an override could prevent the agent from starting or running successfully. That would require a manual login and correction. Therefore you must test the setup with extreme thoroughness.
This source include method is expected to work on all existing ITM maintenance levels and also the upcoming ITM 623 level. However, testing to validate correct operation will always be required.
Some Agents use other installation configuration files. This method works only on the Linux/Unix ini file configuration method.
Windows Environment Variables
The Windows OS Agent process preserves configuration changes by design. Updated variables in the kxxcma.ini file are kept in the [Override Local Settings] section are used during each configuration and used to update the Windows Registry entries which the agents use at runtime.
Summary
This technote shows how to create persistent configuration changes. This technote is referred to by doc APAR IV02051 and the technote contents will be rewritten and included in ITM product documentation in the future.
NOTES
1) The following technote has very good information about preserving information beyond the ini files:
User custom settings are lost after applying an IBM Tivoli Monitoring fix pack
https://www.ibm.com/support/docview.wss?uid=swg21307768&wv=1
Was this topic helpful?
Document Information
Modified date:
17 June 2018
UID
swg21502892