Question & Answer
Question
How do you manage network interfaces?
Answer
Overview
ITM processing depends on TCP/IP communications [Note 1]. A good starting point to understanding ITM communications technology is documented here:
ITM Port Usage and Limiting Port Usage
http://www.ibm.com/support/docview.wss?uid=swg21589289
Another aspect of ITM communications is managing network interfaces. Network interfaces are identified by ip addresses. In many systems there is a separate hardware associated with each ip address called a Network Interface. There can also be software defined interfaces such as localhost [127.0.0.1] or those installed by virtualization software. In some cases multiple ip address can be associated with a single network interface.
The ITM KDE component discovers the interfaces and creates a list of ip addresses that are suitable for agent connection. These addresses are registered into the Location Broker [think phone book]. ITM communication will ignore ip addresses like 127.0.0.1. It will pick an order or priority of registration based on the sequence seen during discovery.
Note that this only applies to ITM server processes such as TEMS and WPA. Agents use location broker information but do not create one.
ITM communications usually work very well using default processing. In rare cases, you must manage interface usage using these two environment variables:
KDEB_INTERFACELIST
KDEB_INTERFACELIST_IPV6
First is an executive summary – what you need to know right now. For simplicity only KDEB_INTERFACELIST is referenced, but the discussion applies to both.
Executive Summary
From ITM 623 FP1 and ITM 622 FP8 onward, if you set the KDEB_INTERFACELIST on one ITM process on a system, you must specify it on all ITM processes.
To smooth the transition, first determine if the environment variable is actually needed. In many cases you should remove the setting. There have been many cases where the environment variable was present and caused problems when it was never needed in the first place. These settings did not cause any problem before ITM 623 FP1 and ITM 622 FP8 but can be disruptive afterwards. It is far better to correct this issue before that upgrade.
KDEB_INTERFACELIST Controls
This environment variable is a string that can have one or more segments separated by blanks. An individual segment looks like this:
[control][ip_address]
control can be
absent meaning no operator
! meaning exclusive
- meaning subtractive
+ meaning additive
ip_address can be
absent
a name which resolves to an ip address
an asterisk which means the interface associated with hostname.
Here are specific cases.
KDEB_INTERFACELIST Simple Address Control (no operator)
KDEB_INTERFACELIST=192.168.1.1
Before ITM 623 FP1/ITM 622 FP8 this had the meaning “the order in which these interface addresses are to be discovered and processed”.
After ITM 623 FP1/ITM 622 FP8 this has the changed meaning !192.168.1.1. [More details later.] This is the disruptive change.
KDEB_INTERFACELIST=192.168.1.1 192.168.1.100
Before ITM 623 FP1/ITM 622 FP8 this had the meaning “the order in which these interface addresses are to be discovered and processed”.
At ITM 623 FP1/ITM 622 FP8 this has same meaning as !192.168.1.1 That means to exclusively listen to that interface and ignore any others [More details later.] The 192.168.1.100 address is essentially ignored. This can and has caused sever installation problems.
At ITM 622 FP9 and ITM 623 FP2, the previous semantics where 2 or more addresses mean to adjust the discovery and processing order.
KDEB_INTERFACELIST Exclusive Control (! Operator)
KDEB_INTERFACELIST=!192.168.1.1 and
KDEB_INTERFACELIST=192.168.1.1 are equivalent at ITM 623 FP1/ITM 622 FP8 and later because both indicate the need for a preferred interface.
In default configuration, ITM communications will listen on all available interfaces for incoming work. When the exclamation mark prefixes the ip address, that single interface will be listened on and no other.
In this setting, all ITM processes should have the same setting. All ITM processes must agree on ‘the preferred interface’, thus have identical KDEB_INTERFACELIST specifications when one address or ‘!’ is used. That is because some processes like the internal web server can migrate from process to process. Because of that the communications control of interfaces must be identical.
KDEB_INTERFACELIST=!*
In some platforms, one interface will be specially tagged as “hostname”. The above setting will listen exclusively to that interface.
Only a single interface can be marked as exclusive, and, with or without the ‘!” with only one interface in KDEB_INTERFACELIST, that interface is marked exclusive.
KDEB_INTERFACELIST Subtraction Control (- operator)
KDEB_INTERFACELIST=-192.168.1.100
This means that a normal survey of all interfaces is performed, but the 192.168.1.100 interface is removed from the survey during discovery.
KDEB_INTERFACELIST_IPV6=-
This means that a normal survey of all interfaces is performed, but all IPV6 interfaces are ignored.
KDEB_INTERFACELIST Addition Control (+ operator)
KDEB_INTERFACELIST=+192.168.1.100
This means that a normal survey of all interfaces is performed, but the 192.168.1.100 interface is added to the survey.
Practical examples
Case 1: The system has three interfaces. The first two can be reached by agents but the third is dedicated to a backup function and should not be advertised in the
Location Broker (think phone book) nor listened on by the Tivoli process.
KDEB_INTERFACELIST=-192.168.1.100
This subtracts the ip address for the backup function
Case 2: The system has IPV6 interfaces, but there is no IPV6 networking.
KDEB_INTERFACELIST_IPV6=-
That could be done to simplify processing.
Case 3: The system has two interfaces which are valid for connection from agents.
Do not supply any controls unless required by other ITM processes on the system. The agents will connect to the location broker and then attempt a connection on each server interface. Whatever works, that will be the one it uses. There is no need to supply a priority order.
Case 4: The ITM process is an agent. That includes TEPS.
Do not supply any controls unless required by other ITM processes on the same server.
Case 5: Two remote TEMS on a single Linux/Unix system
The above rules are not absolute. One interesting example is on a Linux/Unix system where two different TEMSes are installed in different install directories.
This requires two separate dedicated interfaces. For each of them use the exclusive control:
KDEB_INTERFACELIST=!192.168.1.1
KDEB_INTERFACELIST=!192.168.1.100
In the same way you could set up two OS Agents, each using one interface and using a separate interface.
Case 6: Specified Interfaces
There are cases where a specified interface must be discovered first. For agents, this will be the address the agent puts into the Node Status as the ip address and port number to contact. One good example is a cluster configuration where the virtual IP address must be registered - so the contact information remains the same no matter what the actual system the agent is running on.
This is still easily accomplished:
A) If there is a single usable interface specify nothing.
B) If there are two or more interfaces, list the specified interface first and then specify any other interface. In this case the specified interface will be discovered first and used for registration.
Summary
This technote demonstrates how to configure ITM communication to avoid problems. It is best practice to review and correct before upgrading to ITM 623 FP1/ITM 622 FP8.
Note 1: In a z/OS system ITM can also use System Network Architecture [SNA] communications. That is a separate topic and will not be addressed in this technote.
Note 2: Best practice to implement persistent changes is documented here:
Linux/Unix Persistent Configuration Changes and Windows comment
http://www.ibm.com/support/docview.wss?&uid=swg21502892
For ITM 623 levels, best practice is to add the definition to the xx.environment files. Remember if you *must* introduce a setting, it *must* be present at all ITM process controls on that same system.
Note 3: Interesting variations
The rules documented above are not absolute – ITM is very flexible. Here are some specific issues. There are probably a lot more things to learn over time.
Handling a very large number of interfaces
Status 1DE00046 KDE1_STC_INTERFACELIMITREACHED error
1. Disable interface discovery by adding the following parameter to the Agent / Server configuration file:
KDEB_NOIFEXAM=1
2. In the same configuration file, specify the interface to be used to connect to the TEMS:
KDEB_INTERFACELIST=x.x.x.x
where x.x.x.x is the interface address.
Log File Agent issue
KDEB_INTERFACELIST parameter usage on Log File Agent.
http://www.ibm.com/support/docview.wss?uid=swg21591637
Was this topic helpful?
Document Information
Modified date:
17 June 2018
UID
swg21610643