IBM Tivoli Monitoring Version 6.1 Firewall Gateway Feature Copyright International Business Machines Corporation 2006. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
1. Introduction The Firewall Gateway feature in IBM Tivoli Monitoring V6.1 enables additional endto-end connectivity options for use in environments with specific TCP/IP connection management policies. Within this document the term upstream can best be defined in terms of the server and client relationship. Those entities that open a socket to listen for requests are at the upstream or server end. Those entities connecting to the server are at the downstream or client end. Using one or more relay configurations, logical connection requests flow from a listening downstream server proxy interface, and terminate in an outbound connection from an upstream client proxy interface to a listening server. Intermediate relay configurations consist of an upstream relay interface containing at least one downstream relay interface. The Firewall Gateway provides the following functionality: Gateway instances interoperate over a single physical relay connection. Logical connections are multiplexed over the relay. The origination direction of the relay connection is configurable to match enterprise firewall transit requirements. Relay support enables a logical connection to span multiple firewall zones. Each relay instance can optionally provide access to the upstream management network. Multiple relays can be chained to provide seamless hops across multiple zones. Proxy support provides a transparent interface to IBM Tivoli Monitoring V6.1 components. Server proxy components reside downstream and listen for inbound connections. Client proxy components reside upstream and make connections to services on behalf of downstream endpoints. All ports used by gateway instances are configurable. Port pooling is available to constrain client proxy connections to designated port values. Multiple failover addresses can be configured for all gateway connections. 2. Configuration The gateway component is configured through an XML document that specifies a set of zones, each of which contain at least one upstream interface with one or more imbedded downstream interfaces. 2.1. Activation The gateway feature can be activated within any IBM Tivoli Monitoring V6.1 process. However use must be limited to the host computer OS agent to prevent potential resource consumption conflicts with Tivoli Enterprise Monitoring Server (monitoring server) and Tivoli Enterprise Portal Server (portal server) processes.
The configuration variable KDE_GATEWAY is set to the XML configuration file name. A line of the form KDE_GATEWAY=filename must be added to the following configuration files, depending on your environment: On Windows computers, configuration variables for the Windows OS agent are located in the ITMHOME/tmaitm6/KNTENV file. On UNIX computers, configuration variables for the UNIX OS agent are located in the ITMHOME/config/ux.ini and ITMHOME/config/ux.config files. Add the entry to both files for reliable results. On Linux computers, configuration variables for the Linux OS agent are located in the ITMHOME/config/lz.ini and ITMHOME/config/lz.config files. Add the entry to both files for reliable results. After you make these changes, stop and restart the monitoring agents. 2.2. IPv4 Address Data IPv4 (Internet Protocol Version 4) addresses supplied as data to <bind> and <connection> tags can be in absolute dotted decimal or symbolic form. An addressspecific port number override can be specified following a trailing : (colon) character. 2.3. IPv6 Address Data IPv6 (Internet Protocol Version 6) addresses supplied as data to <bind> and <connection> tags can be in absolute uncompressed hexadecimal, absolute compressed hexadecimal, or symbolic form. Absolute hexadecimal expressions must be enclosed within ( and ) (parentheses) with 1-4 digit groups separated by : (colon). Compression of a run of 0 digits can occur at most once, and is indicated by :: (double colon). An address-specific port number override can be specified following a trailing : (colon); this specification is outside the parentheses that wrap an absolute address. 2.4. Configuration XML Document Structure Attributes are described on affected elements; default values for most attributes can be supplied on outer elements with noted exceptions. Document structure relationships between configuration XML elements are illustrated below:
2.4.1. <tepgwml:gateway xmlns:tepgwml= http://xml.schemas.ibm.com/tivoli/tep/kde/ > <zone> <interface> upstream interface <bind> <connection> </connection> </bind> <interface> downstream interface <bind> <connection> </connection </bind> </zone> <portpool> </portpool> </tepgwml:gateway> <gateway> A gateway element in the assigned namespace http://xml.schemas.ibm.com/tivoli/tep/kde/ contains configuration elements described within this document. The gateway XML processor semantically ignores valid XML until the container is opened, allowing for configuration documents to be imbedded in other documents. This element cannot contain data. 2.4.2. Attribute name The name attribute is required, cannot contain imbedded delimiters, and must begin with a non-numeric. This attribute is used to identify a specific gateway instance. This attribute cannot be inherited from an outer element. 2.4.3. Attribute threads The threads attribute specifies the number of worker threads in a general purpose thread pool. The specification must satisfy 1 <= value <= 256, and defaults to 32. Threads in this pool are shared by all defined zones, and are used only by interface startup logic, and to recover from outbound buffer exhaustion conditions. The default value is generally more than adequate. 2.5. <zone> A zone is a container of interfaces sharing communication resources. This element cannot contain data. 2.5.1. Attribute name The name attribute is required, cannot contain imbedded delimiters, and must begin with a non-numeric. This attribute is used to identify a specific zone instance. This attribute cannot be inherited from an outer element.
2.5.2. Attribute maxconn The maxconn attribute imposes an upper limit on the number of concurrent gateway connections within the zone. Each proxy physical connection and each logical connection crossing a relay interface consume this value. The specification must satisfy 8 <= value <= 4096, and defaults to 256. 2.5.3. Attribute bufsize The bufsize attribute sets the data buffer size within the zone. The specification must satisfy 256 <= value <= 16384, and defaults to 2048. 2.5.4. Attribute minbufs The minbufs attribute sets the minimum number of buffers in the zone buffer pool that are reserved for inbound traffic. The specification must satisfy 4 <= value <= 1024, and defaults to 64. 2.5.5. Attribute maxbufs The maxbufs attribute sets the maximum number of buffers in the zone buffer pool that are reserved for inbound traffic. The specification must satisfy minbufs <= value <- 2048, and defaults to 128. 2.6. <interface> An interface describes a set of network bindings that exhibit a fixed behavior according to a specified role, and based on whether it is defined as upstream, which means that the enclosing element is <zone>, or downstream where the enclosing element is <interface>. In all roles, logical connections arrive through one or more downstream interfaces, and are forwarded through the upstream interface. After a logical connection has been established end to end, data flow is full duplex. A valid configuration requires an upstream interface to contain at least one downstream interface. This element cannot contain data. 2.6.1. Attribute name The name attribute is required, cannot contain imbedded delimiters, and must begin with a non-numeric. This attribute is used to identify a specific interface instance. This attribute cannot be inherited from an outer element. 2.6.2. Attribute role The role attribute is required, and describes the behavior of network bindings contained within. The role attribute must be specified as proxy, listen, or connect. Downstream proxy interfaces represent local listening endpoints, and function as a server proxy. Upstream proxy interfaces represent local connecting endpoints, and function as a client proxy. Relay interfaces are assigned either listen or connect. No configuration restriction is made on the relay connection role other than peer relay connections must specify the opposite role. Relay connections are considered persistent, are initiated at gateway startup, and automatically restarted in the event of a network disruption.
2.7. <bind> A bind element represents connection resources on one or more local interfaces. When specified within interfaces that listen (downstream proxy, relay listen), they represent listening ports on local interfaces. For connect interfaces (upstream proxy, relay connect), they represent the local binding to be used for the outbound connection. Specific local interface addresses can be supplied as data; the default interface is any. 2.7.1. Attribute localport The localport attribute is required within listen interfaces, and is optional within connect interfaces. The value supplied can be either a number that satisfies 1 <= value <= 65535, or for connect based roles, can only contain the name of a portpool element defined within the gateway. 2.7.2. Attribute ipversion The ipversion attribute declares the address family to be used for activity within the tag scope. Valid values are 4 or 6, with a default of 4. 2.7.3. Attribute ssl The ssl attribute controls SSL (Secure Sockets Layer) negotiation for connections within the scope of this binding. When specified as yes, a successful negotiation is required before a connection is allowed on the gateway. The default value is no, meaning no SSL negotiation occurs on behalf of the gateway connection. Note that this does not restrict the conveyance of SSL streams across a gateway, only whether or not the gateway acts as one end of the SSL negotiation. When this operand is specified on a relay binding, it can be used to secure relay traffic, and must be specified on both ends of the relay connection. 2.7.4. Attribute service The service attribute is a character string used to represent a logical connection between client and server proxy interfaces. Each connection accepted by a server proxy must find an upstream client proxy connection with a matching service string. No value restrictions are imposed. 2.8. <connection> The connection tag is used to supply remote network interfaces as data. When applied to a listen mode binding, the connection tag represents the list of remote interface addresses that are allowed to make a connection, and is optional. This tag is required for connect mode bindings, and describes the remote end of the connection. Multiple addresses can be supplied for failover purposes. 2.8.1. Attribute remoteport The remoteport attribute supplies the default port number of remote interfaces described within this tag. The value supplied must satisfy 1 <= value <= 65535.
2.9. <portpool> The portpool tag is used to create a list of local port numbers to be used for outbound connections. Port numbers are supplied as data, and can be specified discretely or as a range expression separated by - (hyphen). Range expressions are limited to 1024 bytes to prevent syntax errors from resulting in larger ranges than expected. Multiple specifications of either form are allowed. 2.9.1. Attribute name The name attribute is required, cannot contain imbedded delimiters, and must begin with a non-numeric. This attribute is used to identify a specific portpool instance. This attribute cannot be inherited from an outer element, and is referenced by a localport attribute on a bind element. 3. Recommended Warehouse Proxy Configuration In order to ensure that the Warehouse Proxy listens at a fixed port number across the monitoring enterprise, please append the following configuration text to the KDC_FAMILIES configuration variable for the Warehouse Proxy. IP.PIPE SKIP:15 COUNT:1 The effect of this configuration change is to force the WHP to listen at the TEMS well known port number (default 1918) plus the quantity 4096 multiplied by 15. For example purposes, if the TEMS port is defaulted to 1918, this causes the WHP to listen at 63358. The following examples assume this recommendation has been implemented.
4. Example Firewall Scenario Assumptions Connections can only cross a firewall from the more trusted side to the less trusted side. Relay data crossing a zone will enter and leave on separate ports. The effects of NAT on cross zone addresses are not shown for clarity. NAT connections are fully supported, dynamic NAT connections may require that inbound connection verification be removed. This is accomplished by removal of the <connection> tag under the listening <bind>.
ITM 6.1 Three Hop Firewall Scenario Public Network DMZ2 Network DMZ1 Network Trusted Network 10.3.1/24 10.2.2/24 10.2.1/24 10.1.1/24 Relay TEMAG3 10.3.1.1 Proxy Firewall Relay TEMAG22 10.2.2.1 Proxy Firewall Relay TEMAG21 10.2.1.1 Proxy Firewall Relay TEMAG1 10.1.1.1 Proxy TEMS RMT3 10.3.1.2 IP.PIPE 1918 TEMS RMT22 10.2.2.2 IP.PIPE 1918 TEMS RMT21 10.2.1.2 IP.PIPE 1918 TEMS HUB 10.1.1.1 IP.PIPE 1918 TEMA3A 10.3.1.2 TEMA22A 10.2.2.2 TEMA21A 10.2.1.2 TEMA3B 10.3.1.3 TEMA22B 10.2.2.3 TEMA21B 10.2.1.3 TEMA1A 10.1.1.3 TEMA3C 10.3.1.4 TEMA3D 10.3.1.5 TEMA22C 10.2.2.4 TEMA22D 10.2.2.5 TEMA21C 10.2.1.4 TEMA21D 10.2.1.5 TEMA1B 10.1.1.4 TEMA1C 10.1.1.5 WHP 10.1.1.1 IP.PIPE 6014 Legend: IP.PIPE RELAY PROXY
Public Network Assumptions Gateway service configured as part of OS agent TEMAG3 on 10.3.1.1. TEMAG3 accepts a relay connection on port 10030 only from TEMAG22, port 10030. ITM components within this zone will contact the HUB and WHP server proxy ports 1918 and 6014 via the TEMAG3 interface address. Remote TEMS to reside on machine other than TEMAG3 to prevent port 1918 conflict.
TEMAG3 Gateway Configuration <tep:gateway xmlns:tep= http://xml.schemas.ibm.com/tivoli/tep/kde/ name= temag3 > <zone name= trusted > <interface name= uprelay ipversion= 4 role= listen > <bind localport= 10030 >10.3.1.1 <connection remoteport= 10030 >10.2.2.2</connection</bind> <interface name= serverproxy ipversion= 4 role= proxy > <bind localport= 1918 service= tems /> <bind localport= 6014 service= whp /> </zone> </tep:gateway> DMZ2 Network Assumptions Gateway service configured as part of OS agent TEMAG22 on 10.2.2.1. TEMAG22 originates a relay connection to TEMAG3 port 10030 using local port 10030. TEMAG22 accepts a relay connection on port 10022 only from TEMAG21, port 10022. ITM components within this zone will contact the HUB and WHP server proxy ports 1918 and 6014 via the TEMAG22 interface address. Remote TEMS to reside on machine other than TEMAG22 to prevent port 1918 conflict.
TEMAG22 Gateway Configuration <tep:gateway xmlns:tep= http://xml.schemas.ibm.com/tivoli/tep/kde/ name= temag22 > <zone name= dmz2 > <interface name= uprelay ipversion= 4 role= listen > <bind localport= 10022 >10.2.2.1 <connection remoteport= 10022 >10.2.1.2</connection </bind> <interface name= downrelay ipversion= 4 role= connect > <bind localport= 10030 >10.2.2.1 <connection remoteport= 10030 >10.3.1.1</connection> </bind> <interface name= serverproxy ipversion= 4 role= proxy > <bind localport= 1918 service= tems /> <bind localport= 6014 service= whp /> </zone> </tep:gateway> DMZ1 Network Assumptions Gateway service configured as part of OS agent TEMAG21 on 10.2.1.1. TEMAG21 originates a relay connection to TEMAG22 port 10022 using local port 10022. TEMAG21 accepts a relay connection on port 10021 only from TEMAG1, port 10021. ITM components within this zone will contact the HUB and WHP server proxy ports 1918 and 6014 via the TEMAG21 interface address. Remote TEMS to reside on machine other than TEMAG21 to prevent port 1918 conflict.
TEMAG21 Gateway Configuration <tep:gateway xmlns:tep= http://xml.schemas.ibm.com/tivoli/tep/kde/ name= temag21 > <zone name= dmz1 > <interface name= uprelay ipversion= 4 role= listen > <bind localport= 10021 >10.2.1.1 <connection remoteport= 10021 >10.1.1.1</connection </bind> <interface name= downrelay ipversion= 4 role= connect > <bind localport= 10022 >10.2.2.1 <connection remoteport= 10022 >10.2.2.1</connection> </bind> <interface name= serverproxy ipversion= 4 role= proxy > <bind localport= 1918 service= tems /> <bind localport= 6014 service= whp /> </zone> </tep:gateway>
Trusted Network Assumptions Gateway service configured as part of OS agent TEMAG1 on 10.1.1.1. TEMAG1 originates a relay connection to TEMAG21 port 10021 using local port 10021. TEMAG1 will make client proxy connections to HUB using ports in the range 20000-20099 TEMAG1 will make client proxy connections to WHP using ports in the range 20100-20199
TEMAG1 Gateway Configuration <tep:gateway xmlns:tep= http://xml.schemas.ibm.com/tivoli/tep/kde/ name= temag1 > <zone name= trusted > <interface name= clientproxy ipversion= 4 role= proxy > <bind localport= poolhub service= tems > <connection remoteport= 1918 >10.1.1.1</connection> </bind> <bind localport= poolwhp service= whp > <connection remoteport= 6014 >10.1.1.1</connection> </bind> <interface name= downrelay ipversion= 4 role= connect > <bind localport= 10021 >10.1.1.1 <connection remoteport= 10021 >10.2.1.1</connection> </bind> </zone> <portpool name= poolhub >20000-20099</portpool> <portpool name= poolwhp >20100-20199</portpool> </tep:gateway>
Notices This information was developed for products and services offered in the U.S.A. IBM cannot offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service can be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right can be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM can have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement might not apply to you. This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes is incorporated in new editions of the publication. IBM can make improvements and/or changes in the products and/or the programs described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM can use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 2Z4A/101 11400 Burnet Road Austin, TX 78758 U.S.A. Such information can be available, subject to appropriate terms and conditions, including in some cases payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM International Program License Agreement or any equivalent agreement between us. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating systems. You can copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating system for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You can copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or
distributing application programs conforming to IBM's application programming interfaces. If you are viewing this information in softcopy form, the photographs and color illustrations might not Web. Trademarks IBM, the IBM logo, Tivoli, and the Tivoli logo are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others.