Restricting ports for IBM Tivoli Management Services on z/OS

Edit online

This topic explains how to configure runtime environment parameters to restrict ports allocated by OMEGAMON tasks. This task uses Configuration Manager.

Before you begin

Important: This task requires APAR OA69334 (PTF UJ99772), which introduces parameters that allow you to configure port ranges once for an entire runtime environment. These parameters are available only in Configuration Manager.

As part of this task, you specify the port range for all agent communication in the runtime environment. Before you begin, it is recommended that you determine a suitable range. Consider the following best practices when specifying a port range for the runtime environment:

Port range recommendations:

Make sure the port range covers your base port.
For example, if you are using a secure connection with protocol IP.SPIPE, the default base port is 3660. A suitable port range would be 3660 to 3959.
Ideally, the port range should not have a port already reserved by another started task. You can use the netstat portl command to see all reserved ports in your system.

Tip: Following these recommendations facilitates AT-TLS rule configuration.

Port sizing recommendations:

Set a range of at least 200 to 300 ports, depending on the size of the runtime environment.
Allow at least 20 to 25 ports per started task for each agent, monitoring server, and OMEGAMON enhanced 3270 user interface instance in your runtime environment.
For example, if in your runtime environment you have seven agents, a monitoring server, and one instance of the OMEGAMON enhanced 3270 user interface, this totals nine started tasks. If you allow 20 ports per started task, you would need 180 ports, at a minimum.

Note: The active port number can vary at a given time.

Related information:

What's new: PTF UJ99772 for APAR OA69334 (2Q26)
Blog: TEMS and monitoring agents port pools configuration updates
Technote: Restricting ports for IBM Tivoli Management Services on z/OS
Tivoli Monitoring: Configuring port number assignments for monitoring agents
Tivoli Composite Application Manager for Applications: Implementation with ephemeral pipe

About this task

You can configure port ranges for the entire runtime environment using a single set of parameters, consisting of the following parameters:

RTE_X_KDE_TRANSPORT_POOL_OPTIONS: Sets the port range used for all agent communication in the runtime environment
RTE_X_KDE_TRANSPORT_LBACK_POOL: Sets the loopback port range for all agents. This setting replaces individual KDE_LOOPBACK_POOL settings.
RTE_X_KDE_TRANSPORT_OPTIONS: Enables ephemeral ports for all agents. Agents will not open listening ports; the agents only initiate outbound connections to the monitoring server.

Use of these parameters automatically sets the ports for any agents, the monitoring server, and the OMEGAMON enhanced 3270 user interface in your runtime environment.

Notes:

When using these parameters, you do not need to set individual Kpp_X_KDE_TRANSPORT_* parameters for each agent or the KDE_LOOPBACK_POOL parameter in EMBEDS(Kpp$PENV) members.
Monitoring agents with connections configured as ephemeral cannot warehouse data unless parameter KPX_WAREHOUSE_LOCATION is also configured at the remote monitoring server to which the monitoring agent reports.

Procedure

Determine the range of ports that you will specify. Optionally, you can issue the netstat portl command to see all reserved ports in your system. Ideally, the port range that you define should not include a port already reserved by another started task.
In the RTEDEF(rte_name) member, define the port settings using parameters that apply to the entire runtime environment, as follows:
```
RTE_X_KDE_TRANSPORT_POOL_OPTIONS  "POOL:<port-range>"
RTE_X_KDE_TRANSPORT_LBACK_POOL    "<port-range>"
RTE_X_KDE_TRANSPORT_OPTIONS       "EPHEMERAL:Y"
```
Important: Make sure the POOL range is sufficient for each runtime environment.
Run the GENERATE action.
Recycle the started tasks.
Use the following netstat command to check port usage:
```
/D TCPIP,,NE,CON,CLI=<rte_stc_prefix>*
```
where rte_stc_prefix is the prefix of the started task names for the runtime environment, as specified in parameter RTE_STC_PREFIX.

Example

This example configures the runtime environment to use ports in the range 3660 to 3959.

In the RTEDEF(rte_name) member, the following runtime environment parameters are defined:

RTE_X_KDE_TRANSPORT_POOL_OPTIONS "POOL:3660-3959"
RTE_X_KDE_TRANSPORT_LBACK_POOL   "3660-3959"
RTE_X_KDE_TRANSPORT_OPTIONS      "EPHEMERAL:Y"

After running the GENERATE action and recycling the started tasks, the netstat utility is used to verify port settings. The following command is issued:

/D TCPIP,,NE,CON,CLI=OMEG*

The following example output is produced:

RESPONSE=RSB2                                 
 EZD0101I NETSTAT CS 3.1 TCPIP 242            
 USER ID  CONN     STATE                      
 OMEGDS   01495E74 ESTBLSH                    
   LOCAL SOCKET:   192.168.54.83..3660        
   FOREIGN SOCKET: 192.168.54.83..3695        
 OMEGDS   01495F68 ESTBLSH                    
   LOCAL SOCKET:   192.168.54.83..3660        
   FOREIGN SOCKET: 192.168.54.83..3696        
 OMEGDS   01496069 ESTBLSH                    
   LOCAL SOCKET:   192.168.54.83..3660        
   FOREIGN SOCKET: 192.168.54.83..3697        
 OMEGDS   0149607B ESTBLSH                    
   LOCAL SOCKET:   192.168.54.83..3660        
   FOREIGN SOCKET: 192.168.54.83..3700        
 OMEGDS   01495940 LISTEN                     
   LOCAL SOCKET:   127.0.0.1..3662            
   FOREIGN SOCKET: 0.0.0.0..0                 
 OMEGDS   01495947 ESTBLSH                    
   LOCAL SOCKET:   127.0.0.1..3662            
   FOREIGN SOCKET: 127.0.0.1..3663            
 OMEGDS   01495DCB ESTBLSH                    
   LOCAL SOCKET:   127.0.0.1..3662            
   FOREIGN SOCKET: 127.0.0.1..3692            
 OMEGDS   01495DD6 ESTBLSH                    
   LOCAL SOCKET:   192.168.54.83..3660        
   FOREIGN SOCKET: 192.168.54.83..3693        
 OMEGDS   01495943 ESTBLSH                    
   LOCAL SOCKET:   127.0.0.1..3663            
   FOREIGN SOCKET: 127.0.0.1..3662            
 OMEGDS   0149593C LISTEN                     
   LOCAL SOCKET:   ::..3959 (IPV6_ONLY)       
   FOREIGN SOCKET: ::..0                      
 OMEGDS   0149593E LISTEN                     
   LOCAL SOCKET:   127.0.0.1..3959            
   FOREIGN SOCKET: 0.0.0.0..0                 
 OMEGDS   01495DA6 LISTEN                     
   LOCAL SOCKET:   192.168.54.83..3660        
   FOREIGN SOCKET: 0.0.0.0..0                 
 OMEGDS   01495DC7 ESTBLSH                    
   LOCAL SOCKET:   192.168.54.83..3691        
   FOREIGN SOCKET: 192.168.53.115..3660       
 OMEGDS   01495DCA ESTBLSH                    
   LOCAL SOCKET:   127.0.0.1..3692            
   FOREIGN SOCKET: 127.0.0.1..3662            
 OMEGDS   01496523 LISTEN                     
   LOCAL SOCKET:   ::..3702                   
   FOREIGN SOCKET: ::..0                      
 OMEGDS   0149593D LISTEN                     
   LOCAL SOCKET:   192.168.54.83..3959        
   FOREIGN SOCKET: 0.0.0.0..0                 
 16 OF 16 RECORDS DISPLAYED                   
 END OF THE REPORT

The following results are achieved based on this configuration:

All ports are within the configured range of 3660 to 3959.
127.0.0.1 (loopback) ports are controlled by the RTE_X_KDE_TRANSPORT_LBACK_POOL parameter setting.
192.168.54.83 (external) ports are controlled by the RTE_X_KDE_TRANSPORT_POOL_OPTIONS parameter setting.
Agents have no listening ports on external interfaces because parameter setting RTE_X_KDE_TRANSPORT_OPTIONS "EPHEMERAL:Y" is applied to all agents