John Alvord, IBM Corporation

jalvord@us.ibm.com

Draft #1 – 1/16/2020 – Level 1.00000

Follow on twitter

Inspiration

I am often asked for advice on how to change an ITM process configuration. It could be something simple like adding a diagnostic trace definition. It could be more complex like adding EPHEMERAL:Y to a communication control. There are lots of ways to do this badly. This document will show reliable methods with no side effects. We will be mostly specifying how to introduce environment variables to make configuration changes.

These methods are platform specific. Therefore there are four sections for Linux/Unix, Windows, z/OS and i/5. The z/OS and i/5 do not have override schemes but are included for completeness.

Linux/Unix

The modern way to add or change environment files is to add an environment file. This file will exist in the same directory as other configuration files <installdir>/config. The environment file is used alongside the ini file. For example you will see a lz.ini file [for a Linux OS Agent] and the environment file will be lz.environment. Typically you create the environment file this way using file information about the ini file. For example

nmp180:/opt/IBM/ITM/config # ls -l lz.ini
-rwxrwxrwx 1 root root 2853 Feb 4 2015 lz.ini

cd /opt/IBM/ITM/config
touch lz.environment
chmod 777 lz.environment
chown root lz.environment
chgrp root lz.environment

Your environment will likely have different permissions, owner and group. The requirement is that the environment file have the same permissions/owner/group as the related ini file. After this created it is a zero byte file which can be edited. You may find that such a file already exists. That can happen if you performed a tacmd setagentconnection operation with the -o  option to set an environment variable. In such a case, you can just use it as is.

Environment File Usage and Purpose

In a Linux/Unix environment, the ini file and many other files are used to create a config file. This is the file the agent startup up references for the environment variables that define how it should run. In many cases the config file is created each time the agent starts [or stops]. Some ITM processes are instanced agents. In that case the config file is created only during a ./itmcmd config operation. A TEMS is an instanced agent. During the startup, after the config file is read in, an environment file will be read and used to override the  config file.

Environment files are known as a permanent overrides because that file is not changed during ITM maintenance. Even in a case where a ./itmcmd config is used to change settings, the environment file is still used unchanged. If you change the lz.ini file, the environment file will still override. That can be both good and bad. If you forget about the environment file and make some changes, they might be overridden and not take effect which would be confusing at best.

A good feature of the environment file is that you don’t need to redo the config operation on an instanced agent like a TEMS. It is permanent but also somewhat temporary. For example you could add a diagnostic trace setting and use it for a while and later delete it… All with no need for any reconfiguration.

Environment file usage examples

There is one environment variable KDC_FAMILIES which should be overridden in an environment file. Standing alone in an ini file, KDC_FAMILIES will be overridden in the constructed config file. So if you want to make changes, the ini file doesn’t work so hot. For example the following line in an environment file

KDC_FAMILIES=EPHEMERAL:Y HTTP_SERVER:N ${KDC_FAMILIES}

would take the previous definition of KDC_FAMILIES and prefix two protocol modifiers to 1) run without any listening port and 2) run without an internal web server. That is sometimes set up to avoid the agent having any listening ports – better for security.

An environment file is interpreted by the Korn Shell interpreter, so it can perform some logic. Here is a relatively complex example:

CTIRA_LOG_PATH=${CANDLEHOME}/logs
KBB_VARPREFIX=%
RHN=`hostname|cut -d. -f1`
PRODUCTCODE=ms
KBB_RAS1_LOG=%(CTIRA_LOG_PATH)/${RHN}_${PRODUCTCODE}_%(syspgm)_%(sysutcstart)-.log INVENTORY=%(CTIRA_LOG_PATH)/${RHM}_${PRODUCTCODE}_%(syspgm).inv COUNT=16 LIMIT=20 PRESERVE=1 MAXFILES=64

The purpose here is to configure more and larger diagnostic log segments. The %(xxx) is unique to ITM basic services and means to substitute an environment variable otherwise defined. In the RHN definition you can see how a linux/unix command is run – the hostname command – and the first period delimited part of the hostname set to that environment variable. Again this is all specific to a needed piece of  configuration.

Environment File Summary for Linux/Unix

As seen above this is a smart and effective way to introduce configuration changes. It was introduced in ITM 623 FP2.

Before ITM 623 FP2 Use Source Include

ITM 623 has gone End of Support in April 2019. You can still use agents at earlier levels, but there are no further fixes available. You see this method with older agents and especially the AIX premium agents which are permanently at ITM 622.

A source include method is used to achieve the same goals. In this case there would be a file like lz.override and it would contain the needed overrides, usually single quoted. Here are two examples.

KBB_RAS1=’error’

KDC_FAMILIES=”EPHEMERAL:Y HTTP_SERVER:N ${KDC_FAMILIES}”

In Shell processing, single quoted text are not interpreted. Double quoted strings are interpreted.

In the lz.ini file at the end is added

. /opt/IBM/ITM/config/lz.override

That starts with a period and a space and then the fully qualified name of the environment file. In Shell terminology that is a source include. By this method the override file is logically included into the end of the lz.config as it is used. The result is about the same. You can also see this is modern supported levels and they work. However environment files are best practice to be sure.

 

Windows

There is a lot of confusion about how to add and override environment variables in Windows. The first thing to remember is a Windows agent at startup reads from the Windows registry – NOT a xx.config file. If you are tempted to add some variables to a KXXENV file – which always exists – resist that temptation. When environment variables are found in both places, things often go very wrong. If you find an install that has done that, back out the changes and do things the right way.

The kinconfig.exe Program and its usages

This is relatively little known but it is documented here.  If you are familiar with the MTEMS GUI [Manage Tivoli Enterprise Management Systems] this program is the functional part of that program. It is present in the <installdir>\installITM directory.

The simplest usage is to add  environment variables. Here is a simple example
cd c:\IBM\ITM\InstallITM
kinconfg -aknt -oCTIRA_HOSTNAME=myhostname
kinconfg -aknt -oCTIRA_SYSTEM_NAME=myhostname
kinconfg -rknt

The -a specifies the product code – knt means Windows OS Agent. The -o option specifies the environment variable you want to add or change

If you want to change the communications so that EPHEMERAL:Y is set and the internal web server is not started:

kinconfg -aknt -oKDC_FAMILIES=EPHEMERAL:Y HTTP_SERVER:N @Protocol@
kinconfg -rknt

The @Protocol@ has the definition of the originally configured KDC_FAMILIES during installation.

If you have made the error of adding such variables to the KNTENV file, you will need to remove them. Here is a post which explains how to do that remotely:

Scrubbing Out Windows Agent Malconfiguration Remotely

Verifying modification changes.

The kinconfig program updates the Windows Registry with the -r option. It also records that in a disk file <installdir>\TMAITM6_x64\kntcma.ini. At the end of the kxxcma.ini file will be found a section labeled

[Override Local Settings]

where changes will be recorded. Remember that is documentation only, the Windows Registry is where the agent gets its information.

Sitworld: Table of Contents

History and Earlier versions

There are no binary objects associated with this project.

1.000000

initial release

Photo Note: Main Coon Bandit Christmas 2019