Agent clustering and positioning in the TEP Navigator

Answer

In the Portal Client, the Physical Navigation tree represents all the agents in the environment. The display is in a tree form with a top level of "Enterprise."

The default presentation assumes that each agent of a particular type comes from a different IP address and hostname. When that is not true, the agent will display at an unexpected or seemingly random location. One example is when multiple agents are installed on a single server. Another example is when a high availability option like Microsoft Windows Clustering is used and an IP address is shared.

Changes to the agent environment variable "CTIRA_HOSTNAME" will affect the display name in the Managed System Status workspace but not within the Physical Navigator. Here is an explanation of how to configure the TEPS for desired navigator item display.

The TEPS has a configuration environment variable that will change the Physical Navigator to depend on the host name instead of the IP address: KFW_TOPOLOGY_CLUSTER_LIST. This variable is added to the <ITMHOME>\cnps\kfwenv file (Windows) or to <ITMHOME>/config/cq.ini (Linux/UNIX). It forces dependence on the hostname for navigator positioning instead of on the IP address. A sample setting looks like this:

KFW_TOPOLOGY_CLUSTER_LIST=AFF_xxx AFF_yyy

Where the setting lists the agent affinities to which this hostname logic should apply. Here are some affinities for agents distributed with ITM V6.

AFF_NT_SYSTEM                      "Windows OS"
AFF_ALL_UNIX                       "UNIX OS"
AFF_OS400_OM                       "i5/OS"
AFF_LINUX_SYSTEM                   "Linux OS"
AFF_UNIX_LOG_ALERT                 "UNIX Logs"

So if you needed to use the hostname for navigator positioning of your Linux OS, UNIX OS, and Unix Log Agents, it would look like:

KFW_TOPOLOGY_CLUSTER_LIST=AFF_ALL_UNIX AFF_UNIX_LOG_ALERT AFF_LINUX_SYSTEM

There are many agents, so listing the affinity for each would be cumbersome here. Here are two general methods of figuring out the correct affinity name, based on ITM version.

METHOD 1 (ITM versions below 6.2):

If you have an agent connected and showing as online, click on the Physical Navigator top node, then right click and select Managed System Status:



Make a temporary change to this workspace to show the agent affinity by right-clicking on any row and selecting Properties. Click on the Filters tab:



Slide the scroll bar to the right and click on the Affinities column



Click on OK and slide the Managed System Status window to the right



For the Windows OS agent, the affinity is:

00080000000000000000000000000000

You could export this information to a .csv file and then work with that to extract the hex data. The affinity is the first 32 characters. Columns 33-34 are the product version code. Columns 35-43 are version flags. Leave this workspace up, but when you switch away from this workspace be sure not to save it - since it was only a temporary change.

Next edit <ITMHOME>\cnps\affinity.properties (Windows) or <ITMHOME>/<arch>/cq/data/affinity.properties (Linux/UNIX). This display is from Wordpad:



This verifies that "00080000000000000000000000000000" corresponds to the Windows OS Agent. Next search for "tags.AFF_"



Now you can see that affinity 00080000000000000000000000000000 represents the AFF_NT_SYSTEM value. Using the above process, you can determine the correct settings for the agents where you need the KFW_TOPOLOGY_CLUSTER_LIST configuration. In some cases this will be enough. You should recycle TEPS at this point and look at the display. You may be complete but often there may be more work to do. Let's look again at the temporarily changed Managed System Status view:



The IP address is normally used for machine identification, however with KFW_TOPOLOGY_CLUSTER_LIST set, the first part of the Origin Node is used ("Primary:" is ignored). That first part defaults to the TCP/IP hostname, but it will be replaced if CTIRA_HOSTNAME is set. Thus you have control over deciding where an agent is positioned. Configuring an agent to have a specific CTIRA_HOSTNAME value will manage cases where the IP address changes, and then KFW_TOPOLOGY_CLUSTER_LIST will force the navigation display to use that apparent hostname instead of the TCP/IP hostname.

METHOD 2 (ITM versions 6.2+):

In ITM 6.2, static agent affinities were replaced with dynamic affinities to increase the number of applications the affinity could represent, as well as the number of versions of each application. Static affinities like the ones shown in METHOD 1 above, would still apply, however, any new "standard" (non-custom) agents or custom agents (Universal Agent-based or Agent Builder-based) would use a dynamic affinity.

In an ITM version of 6.2 or higher, by navigating to the Managed System Status workspace as shown in METHOD 1 and allowing the Affinities column to be shown, you might see something like this:



The %IBM.STATIC* value can be found in the <ITMHOME>\cnps\staticmap.properties (Windows) or <ITMHOME>/<arch>/cq/data/staticmap.properties (Linux/UNIX) file. An example for the %IBM.STATIC013 affinity for the UNIX OS agent from the file is:

mask.00f20000000000000000000000000000=%IBM.STATIC013

Copy the value after the "mask." portion ending at the '=' character. If you search for this value, prepended with an '=' character in the affinity.properties file, you will see an tags.AFF* entry like this:

tags.AFF_ALL_UNIX=00f2000000000000000000000000000000000000000

The value to use for UNIX OS agents in the KFW_TOPOLOGY_CLUSTER_LIST parameter would be AFF_ALL_UNIX.

For a nonstandard agent, the following three steps detail the method to determine the affinity value to use for the KFW_TOPOLOGY_CLUSTER_LIST parameter:

1) Open the ODI file that comes with the agent (dockxx, where xx is the agent product code) in the <ITMHOME>\CNPS or <ITMHOME>/<arch>/cq/data directory
2) Locate the affinity behind the *DAFFIN tag
3) Copy the affinity and add it to the KFW_TOPOLOGY_CLUSTER_LIST value in the KFWENV/cq.ini file. Note that entries in the list are separated by blank.

Some agents require a different mechanism to change the apparent host name. In the case of the MQ Agent for example (AFF_MVS_MQM), update the mq.cfg file and add:

SET AGENT NAME(<hostname>)

Long hostnames can create confusion such as when a hostname is fully qualified. The default TEPS processing only uses the first part of the fully qualified name, so two names like abc.xyz.large.com and abc.def.large.com would both appear at the node labeled abc. That can be controlled by adding

KFW_TOPOLOGY_KEEP_DOT_IN_NODE_NAMES=Y

to the TEPS environment file (KFWENV/cq.ini). Remember the managed system names are limited to 32 characters - so the hostname:product can be truncated and cause accidental duplications. That would be another case where you would need to set the CTIRA_HOSTNAME.