ITM Protocol Usage and Protocol Modifiers

Technote (FAQ)


Question

How to change ITM communication protocols

Answer


Important

Most of the following material was incorporated into the ITM 623 Installation and Setup Guide here

Tivoli Monitoring protocol usage and protocol modifiers
http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/topic/com.ibm.itm.doc_6.2.3/itm623_install472.htm?path=3_0_2_0_7_0_10#protocol_mod

Overview

ITM basic services communications are defined by the KDE_TRANSPORT environmental variable, and after this paragraph that will be the only variable mentioned. At an earlier stage of ITM development, KDC_FAMILIES was used, but KDE_TRANSPORT is intended to be the successor. At this moment, the two variables are processed identically. However many agent installers are only aware of the earlier variable. In practice` examine the agent installation and adopt whatever is being used.

ITM uses other communication protocols such as 1) Portal client to Portal server uses CORBA IIOP after startup, 2) TEPS/WPA/SPA can use ODBC or JDBC to communicate with the warehouse database, and 3) several other cases. Most of ITM to ITM communications uses TCP/IP or SNA [z/OS only] protocols. This technote ignores the SNA case.

Modifiers to the protocols are of the form 'attribute:value'. If they occur first, then they are global in effect if meaningful. If they occur after a protocol and before the next protocol, then the effect is only on that protocol. The protocol names and modifiers are case insensitive although they are presented in upper-case here.

In the Appendix there are references on how to implement the needed changes depending on platform.

KDE_TRANSPORT Structure

KDE_TRANSPORT is a string which lists protocols and modifiers. All protocols are assumed present. A protocol will be activated only if an interface is available for use.

The USE modifier activates a specific protocol if Y is specified, otherwise it deactivates it. The scanning starts with an implicit global USE:Y, meaning that all protocols are assumed to be activated by default. For example:

IP.PIPE PORT:1918 USE:Y IP.SPIPE USE:N

means that IP.PIPE will be available but IP.SPIPE will not. In addition all the unnamed protocols listed later are activated.

If a modifier is specified before any protocol, it generally applies globally. For example, a pool setting first will apply to all protocols.

KDE_TRANSPORT Transmission Control Protocol

TCP is a connection oriented protocol. Connection is made via a port number, which can be 0-65535. The connection continues until the application(s) tear it down.

Here are the protocol names:

IP.PIPE - tcp
IP.SPIPE - secure tcp
IP6.PIPE - ipv6 tcp
IP6.SPIPE - ipv6 secure tcp

The secure protocols are implemented with the Global Secure Toolkit (GSKIT) component.

Here are the tcp protocol modifiers:

PORT

PORT defaults to 1918 for tcp and 3660 for secure tcp. These numbers are registered with the Internet Assigned Numbers Authority, www.iana.org/assignments/port-numbers.

PORT defines the base port number. For a TEMS, the base number is used as the listening port, and is the port that Agents connect to. For agents, ITM processing attempts to open a listening port at number base+N*4096, where N is 1 to 15. If one is already in use, it tries the next higher iteration. If no TEMS is present. the base port is reserved in case a TEMS gets started later.

For an Agent, the listening port is used for two main purposes: 1) TEMS requesting real-time data from the agent and 2) Agent receiving notifications from the TEMS, such as awareness of a WPA [Warehouse Proxy Agent] re-registration at a new IP address or port number.

Example: IP.PIPE PORT:1918 USE:Y

Note that in this mode of definition, there are a maximum of 15 agents on a server. If this is an issue see the EPHEMERAL modifier section further below.

SKIP and COUNT

SKIP and COUNT modifiers are used to control the port search algorithm. Default search is for baseport+N*4096 with N from 1 to 15. The SKIP modifier forces it to start with N equal to the SKIP value in the above calculation. The COUNT modifier means to only try that number of times, not all the way to 15.

The following is often used with Warehouse Proxy Agent:

IP.PIPE PORT:1918 SKIP:15 COUNT:1 USE:Y

It means that the only port checked will be 1918+15*4096 or 63358. This is useful because it means that Warehouse Proxy Agent (WPA) will have a fixed address even though a TEMS and other agents may be starting up. Having a fixed port number is vital if firewall rules are used. At some future ITM maintenance level, the WPA port will likely be fixed to a high port number and configuration will not be required,

EPHEMERAL

This modifier has three different values.

A value of Y means that the connection to the TEMS listening port will be used for all communications. The agent will not need a listening port. The advantage can be important in cases where firewall rules are used, since fewer ports are used. It is also a way to avoid the 15 agent limitation. The negative is that if historical data collection is being done, then historical data must either be stored at the TEMS, or there must be a WPA process running on the same server as the TEMS the agent reports to if the historical data is being stored at the Agent.

A value of OUTBOUND means the same thing as Y.

A value of INBOUND can be used at a TEMS and it means that every agent connecting to it is configured to ephemeral mode.

POOL

ITM processes use ports for communication within the server, never seen on the outside network. The temporary ports that are used can be controlled with this option.

Examples:

IP.PIPE POOL:50900-51923
IP.UDP POOL:01000-01023 POOL:01024-02048

Note that each pool modifier can specify a maximum of 1024, but you can have multiple such specifications.

Any pool range must fit within the local system defined ranges. On AIX the "no -a" will display current ranges. See this URL for a general overview:

http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html

KDE_TRANSPORT User Datagram protocol

For ITM, this protocol is not usually best overall. The advantage is a somewhat lower storage requirement. The negatives are 1) less reliability since applications are responsible for error recovery, 2) higher CPU resources are required, and 3) it cannot be used where firewall rules are in place.

Here are the protocol names:

IP.UDP - User Datagram Protocol
IP - Synonym for IP.UDP
IP6.UDP - IP V6 version of IP.UDP

The POOL and PORT modifiers can be used for this case The other modifiers are connection oriented.

KDE_TRANSPORT Hypertext Transfer Protocol

Each ITM process has an internal web server. These define what protocols are used to access the internal web server. The web server gives access to the ITM service console, the portal client, the SOAP server tryout page, and [starting with ITM 6.2.2] the Agent Service Index pages.

Here are the protocol names:

ip.tcp.http - http communications
ip.ssl.https - secure http communications
ip6.tcp.http - ipv6 http communications
ip6.ssl.https - ipv6 secure http communications

Here are the protocol modifiers

HTTP_SERVER
Defaults to Y. If set to N then the internal web server is not started.

HTTP_CONSOLE
Defaults to Y. If set to N then the ITM service console is not started.

HTTP

Defaults to 1920. If set to 0, port number is set to a temporary or ephemeral number. That number will be will be controlled by the ip.tcp POOL number if present.

HTTPS

Defaults to 3661 . If set to 0, port number is set to a temporary or ephemeral number. That number will be will be controlled by the ip.ssl POOL number if present.

POOL

The HTTP protocol also uses temporary ports and the usage is controlled by separate pool control settings. These are not protocols, but are required for the POOL setting:

ip.tcp - pool control for the ip.tcp.http protocol
ip.ssl - pool control for the ip.ssl.https protocol
ip6.tcp - pool control for the ip6.tcp.http protocol
ip6.ssl - pool control for the ip6.ssl.https protocol

It would be easier to have leading pool setting(s) which would apply to all protocols.


Interactions with other environment variables

KDEB_INTERFACELIST and KDEB_INTERFACELIST_IPV6

The dash “-“ option is used alone, these environment variables do not scan any of the related interfaces. In that case a protocol might go unused even though it is specified in KDE_TRANSPORT. You could also eliminate all the interfaces by name to achieve the same result.

Summary

This technote explains how to understand and change the KDE_TRANSPORT environment variable which controls ITM communications.

See further discussion here

http://www-01.ibm.com/software/tivoli/features/ccr2/ccr2-2008-10/monitoring-port-pooling.html

For additional Technotes search on "IBM ITM ITM6 Technote"
Search: ITM ITM6 Technote KDC_FAMILIES KDE_TRANSPORT protocol sbs



Appendix: A Guide to Changing the KDE_TRANSPORT settings

Most of this technote is a reference guide to constructing a KDE_TRANSPORT [or KDC_FAMILIES]. In practice what you do is highly platform dependent.

If you decide to change KDE_TRANSPORT, make sure to change the settings on all ITM tasks when appropriate. For example, if you decide to turn off the ITM internal web server using the HTTP_SERVER:N modifier, you must make the same change for all ITM tasks. The task actually running the internal web server can switch depending on which one is up first and on ITM task recycles, so all ITM processes must have the same setting.

That is not true for agent specific operations such as using SKIP/COUNT to force a specific port number to be used.

At ITM 623 and above, the tacmd setconnection function allows many such changes to be introduced. It does not however handle the HTTP_SERVER:N type of change. Thus most of the following concerns ITM 622 and earlier, but the KDE_TRANSPORT global changes must be handled as before.


Linux/Unix Agents

Here is a good example on how to change the communications string:

Updating Linux/Unix agent KDC_FAMILIES configuration
http://www.ibm.com/support/docview.wss?uid=swg21390561

Here is another technote concerning making mass changes:

Mass Configuration Change for Windows/Linux/Unix agents
http://www-01.ibm.com/support/docview.wss?uid=swg21441836



Linux/Unix – TEMS

This environment is much like Linux/Unix Agents. The difference is that the config file generation is only performed during a

itmcmd config –S –t <temsname>

So make the same sort of change and then run the itmcmd config cli. The same procedure is needed for instance based agents.


Windows Agents

There are Windows examples in this technote:

Mass Configuration Change for Windows/Linux/Unix agents
http://www-01.ibm.com/support/docview.wss?uid=swg21441836


Windows TEMS

This must be manual changes from the MTEMS GUI.


i/5

The environment variable is manually changed in

QAUTOTMP/KMSPARM(KBBENV)


z/OS

In z/OS these values are kept in the RKANPARU(KDSENV) member. for TEMS and in RKANPARU(KppENV) for Agents. Configuration changes here are manual.

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

Tivoli Components
ITM Tivoli Enterprise Mgmt Server V6

Software version:

All Versions

Operating system(s):

AIX, HP-UX, Linux, Linux zSeries, Solaris, Windows, i5/OS, z/OS

Software edition:

All Editions

Reference #:

1422918

Modified date:

2013-01-03

Translate my page

Machine Translation

Content navigation