Sitworld: ITM Permanent Configuration Best Practices


John Alvord, IBM Corporation

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

Follow on twitter


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.


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


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:

RHN=`hostname|cut -d. -f1`

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.



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.



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.

z/OS Configuration

ITM z/OS processes do not have an override procedure.

ITM z/OS processes use a PARMGEN process where controls are specified interactively and then batch jobs are generated [and run] to implement those controls. [There is also the prior scheme called ICAT.] The following can be used by anyone configuring a z/OS agent or TEMS.

One is a freeform WCONFIG(KDS$PENV) RTE imbed that is ideal for advanced-type parms. for the RKANPARU(KDSENV) z/OS TEMS. This could be used for KDEB_INTERFACELIST or CMS_FTO settings. The imbeds are documented in more detail here.

Another is a option KDS_X_KDE_TRANSPORT_GBL_OPTIONS  which supplies controls in the leading or global position for the KDE_TRANSPORT control. The z/OS processes always use that instead of KDC_FAMILIES. That is how HTTP_SERVER:N and other things can be specified.

i/5 Configuration

The i/5 platform [previously AS/400] stores environment variables in the file QAUTOTMP/KMSPARM file member KBBENV. There is no override mechanism.


This document describes ITM port usage and shows ways you can eliminate or control port usage.

Sitworld: Table of Contents

History and Earlier versions

There are no binary objects associated with this project.


initial release

Photo Note: Main Coon Bandit Christmas 2019


2 thoughts on “Sitworld: ITM Permanent Configuration Best Practices

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: