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>
</interface>
</interface>
</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
TEMS
RMT3
10.3.1.2
IP.PIPE 1918
Firewall
Relay
TEMAG21
10.2.1.1
Proxy
TEMS
RMT22
10.2.2.2
IP.PIPE 1918
Firewall
TEMS
RMT21
10.2.1.2
IP.PIPE 1918
Relay
TEMAG1
10.1.1.1
Proxy
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
TEMA22C
10.2.2.4
TEMA21C
10.2.1.4
TEMA1B
10.1.1.4
TEMA3D
10.3.1.5
TEMA22D
10.2.2.5
TEMA21D
10.2.1.5
TEMA1C
10.1.1.5
Legend:
IP.PIPE
RELAY
PROXY
WHP
10.1.1.1
IP.PIPE 6014
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”/>
</interface>
</interface>
</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”/>
</interface>
</interface>
</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”/>
</interface>
</interface>
</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>
</interface>
</interface>
</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.