Tivoli TEC Gateway

To control the number of events sent from an adapter, refer to the event filtering information in the IBM Tivoli Enterprise Console Adapters Guide.

To distribute a modified Tivoli Enterprise Console gateway adapter configuration profile to a managed node with a gateway installed, the managed node must also have an endpoint installed on it. When you distribute the adapter configuration profile, the subscriber must be the endpoint on that managed node.

Gateway configuration file

The Tivoli Enterprise Console gateway configuration file is optional and does not exist on the managed node until an adapter configuration profile containing the gateway configuration information is distributed to the endpoint on that managed node. The Tivoli Enterprise Console gateway uses default values unless you modify the keywords in the Tivoli Enterprise Console gateway configuration file and distribute an adapter configuration profile containing the changed gateway configuration information. Also, if you do not specify a value for a keyword, the default value is used.

The Tivoli Enterprise Console gateway uses one of the following configuration files:

/etc/Tivoli/tec/tec_gateway.conf

The configuration file defines the behavior of the Tivoli Enterprise Console gateway. For information about the common keywords for the configuration file, refer to the IBM Tivoli Enterprise Console Adapters Guide or the Tivoli Event Integration Facility Reference. The configuration file can also use the following custom keywords:

APPEND_CLASSPATH=string

Specifies the string that is appended to the CLASSPATH environment variable before Java-based state correlation is started. The string is appended using the appropriate delimiter, a semicolon (;) for Windows or a colon (:) for UNIX. The string must contain valid data for your environment as shown in the following example:

UNIX:

APPEND_CLASSPATH=/my_product/my_java.class:/my_product/my_jar.jar

For the tec_gateway program, the specified string is appended to the list of jar files used for state correlation. For a C Adapter, the specified string is appended to the CLASSPATH environment variable.

Notes:

1. The CLASSPATH environment variable will not be changed. The CLASSPATH information is only passed to the Java code when state correlation is started.
2. You can specify the APPEND_CLASSPATH keyword only one time in your configuration file.

BufEvtPath

Specifies the file in which to buffer events when the Tivoli Enterprise Console gateway cannot forward the events to the event server. Because a single Tivoli Enterprise Console gateway can forward events to multiple event servers, it must have an event buffer file for each event server. When the Tivoli Enterprise Console gateway reestablishes the connection to the event server, it sends the buffered events to the event server. The Tivoli Enterprise Console gateway creates a buffer file for each event server by appending the event server location specified by the ServerLocation keyword to the name of the file specified by the BufEvtPath keyword.

Assume that the ServerLocation and the BufEvtPath keywords are specified as follows:

ServerLocation=@EventServer#tmr-central

BufEvtPath=/etc/Tivoli/tec/gateway_cache

The Tivoli Enterprise Console gateway creates the /etc/Tivoli/ tec/gateway_cache@EventServer#tmr-central buffer file.

If the Tivoli Enterprise Console gateway receives an event from an adapter that specified server location as @EventServer#tmr-east, the Tivoli Enterprise Console gateway also creates a buffer file named /etc/Tivoli/tec /gateway_cache@EventServer#tmr-east.

The default value is one of the following:

UNIX: /etc/Tivoli/tec/cache@EventServer#region

Windows: $DBDIR/cache.dat@EventServer#region (on managed nodes)

$TIVOLIHOME/tec/$(AC_TYPE).cache@ EventServer#region (on endpoints)

Note:

To reduce network traffic and improve performance, filter events as close to the source as possible by specifying filter options in adapter configuration files. You can also use the Filter, FilterCache, FilterMode, and UseStateCorrelation keywords in the Tivoli Enterprise Console gateway configuration file.

EventSendThreshold

Specifies the maximum number of events per second to send to the event server. Use this keyword in conjunction with the BufferFlushRate keyword. For more information about how to set the value for this keyword, see Gateway configuration example.

GatewayAckInterval

Specifies the timeout interval, in seconds, to wait for acknowledgement from the event server. The default value is 30 seconds. This keyword works in conjunction with the GatewayTMEAckEnabled keyword for event delivery.

GatewayQueueSize

Specifies the size, in bytes, for the event buffers. If any of the event buffers fill before expiration of the interval specified by the GatewaySendInterval keyword, the Tivoli Enterprise Console gateway immediately sends the the waiting events to the event server.

The minimum value for this keyword is 4096 bytes. If the GatewayQueueSize keyword is set to a value lower than 4096, this keyword is set to 40000, which is the default.

GatewaySendInterval

Specifies the interval, in seconds, at which to forward events to the event servers. The Tivoli Enterprise Console gateway holds events when they are received. When this interval expires, the Tivoli Enterprise Console gateway bundles and forwards the events in a message to the appropriate event servers.

The default interval is five seconds.

GatewayTMEAckEnabled

Specifies whether or not an acknowledgement is expected from the event server. To ensure event delivery, set this keyword to YES (connection-oriented). The default value is NO.

gwr_ActiveConnections=nn

Specifies the number of active connections that the tec_gwr program manages at one time. The number of possible connections ranges from 2 to 1000. If the value specified for this keyword is greater than 1000, the number of active connections is set to 1000. If the value specified for the keyword is less than 2, the number of active connections is set to 2. If you do not specify a value for this keyword, the number of possible active connections is not limited.

gwr_ActiveConnectionsSafety=nn

Specifies the percentage of active connections that the connections specified by gwr_ActiveConnections keyword must be reduced to before connections can be processed again. Valid values range from 10 to 90. When the number of active connections specified in the gwr_ActiveConnections keyword is reached, no new connections are accepted until the number of connections drops below this specified threshold. For example, if the gwr_ActiveConnections keyword is set to 20 and the gwr_ActiveConnectionsSafety is set to 80, the tec_gwr program stops accepting connections when 20 connections are reached. The tec_gwr program accepts new connections when the number of active connections is reduced to 16 or less (80% of 20). The default value is 80. This keyword is used only when a value is specified for the gwr_ActiveConnections keyword.

gwr_ConnectionsQueued=nn

Specifies the number of connections that the server socket queues. The server socket queues connections that are waiting to be accepted by the tec_gwr program. Use this option to limit the number of connections that can be queued. Valid values range from 1 to 1000. The actual number of queued connections can be slightly more or less than the value you specify. The default value is 500. This keyword is optional.

gwr_Enable=YES|NO

Specifies whether or not the tec_gateway program receives events from non-TME adapters. To enable the tec_gateway program to receive events from non-TME adapters, specify YES. The default value is NO. This keyword is optional.

gwr_OptionPortNotAvailable=ERROR|WAIT

Specifies how the tec_gwr program processes events when the port specified by the gwr_ReceptionPort keyword is not available. When this keyword is set to ERROR, the tec_gwr program ends if the port specified in the gwr_ReceptionPort keyword is not available. When this keyword is set to WAIT, the tec_gwr program continues processing instead of returning an error when the port is not available. When the port becomes available, a server socket is created. The default value is ERROR. This keyword is optional.

gwr_ReceptionPort=port

Specifies the port on which to listen and receive events from non-TME adapters. The default value is 5539. This keyword is optional.

gwr_ReceptionTestMode=path

Specifies the path and the file name from which to read test mode events. This keyword is similar to the TestMode keyword in that events are read from a data file as opposed to being received on a port. This keyword is optional.

gwr_RetryCount=nn

Specifies the number of times to resend an event when the tec_gateway program fails to receive an event from the tec_gwr program. The default value is 10. This keyword is optional.

gwr_RetryInterval=nn

Specifies the interval, in seconds, between retry attempts specified by the gwr_RetryCount keyword. The default value is 1. This keyword is optional.

gwr_ServerLocation=host_name

Specifies the name of the host on which the event server is installed. The default value is the value of the ServerLocation keyword. This keyword is optional.

gwr_ServerPort=port_number

Specifies the server port to use for the host specified by the gwr_ServerLocation keyword when events are received from non-TME adapers. The specified server port is used when the value for gwr_ServerLocation is any value other than @EventServer. The default value is 0. This keyword is optional.

gwr_ServiceServer=host_name:port_number

Specifies the host and port number to which to send service-related events. The tec_gwr program sends service status events that belong to the TEC_Notice class to the event server specified by this keyword. The tec_gwr program sends a service status event when the tec_gwr program is started or stopped or when the submission handle is reset. Specify the host and port number as follows:

myEventServerHost:5529

To send service status events from the tec_gwr program to the tec_gateway program, set this keyword to SAME as follows:

gwr_ServiceServer=SAME

gwr_SubmissionTestMode=path

Specifies the path and file name from which to read test mode events. This keyword is similar to the TestMode keyword in that events are read from a data file instead of being received on a port. This keyword is optional.

MaxGWCacheSizeMegs

Specifies the maximum size, in megabytes, of the event cache. By default, the maximum size of the event cache is 1 MB. The keyword is not included in the configuration file as provided.

PREPEND_CLASSPATH=string

Specifies the string that is prepended to the CLASSPATH environment variable before Java-based state correlation is started. The specified string is prepended using the appropriate delimiter, a semicolon (;) for Windows or a colon (:) for UNIX. The string must contain valid data for your environment as shown in the following example:

UNIX:

PREPEND_CLASSPATH=/my_product/my_java.class:/my_product/my_jar.jar

Windows:

PREPEND_CLASSPATH=\my_product\my_java.class;d:\my_product\my_jar.jar

For the tec_gateway program, the specified string is prepended to the list of jar files used for state correlation. For a C Adapter, the specified string is prepended to the CLASSPATH environment variable.

Notes:

1. The CLASSPATH environment variable will not be changed. The CLASSPATH information is only passed to the Java code when state correlation is started.
2. You can specify the PREPEND_CLASSPATH keyword only one time in your configuration file.

RetryInterval

Specifies the interval, in seconds, to wait before connecting to a secondary event server when the Tivoli Enterprise Console gateway cannot send events to the event server. While the Tivoli Enterprise Console gateway is waiting for this time interval to expire, the Tivoli Enterprise Console gateway continues to receive and cache new events. To adjust the size of the Tivoli Enterprise Console gateway memory queues, use the GatewayQueueSize keyword.

The RetryInterval keyword enables adapters to send all events to the primary event server even if the primary event server is stopped briefly, such as when loading a new rule base. If you use this option to wait for the event server to restart, set the value for a period of time longer than needed for the event server to be stopped and restarted.

The RetryInterval keyword is optional.

ReceiveAckPort=number

Specifies the port number that the Tivoli Enterprise Console gateway uses to receive acknowledgements from state correlation. The acknowledgements indicate that state correlation has received and stored the events. This keyword is used in conjunction with the SendEventPort keyword. This keyword is required when the UseStateCorrelation keyword is set to YES.

ReceiveEventPort=number

Specifies the port number that the Tivoli Enterprise Console gateway uses to recieve events from state correlation. This keyword is used in conjunction with the SendAckPort keyword. This keyword is required when the UseStateCorrelation keyword is set to YES.

SendAckPort=number

Specifies the port number that the Tivoli Enterprise Console gateway uses to acknowledge the reception of events sent from state correlation. This keyword is required when the UseStateCorrelation keyword is set to YES.

SendEventPort=number

Specifies the port number that the Tivoli Enterprise Console gateway uses to send events to state correlation. This keyword is required when the UseStateCorrelation keyword is set to YES.

ServerLocation

Specifies the default event server location if adapters do not specify an event server location in an event instance. If the ServerLocation keyword is specified in the configuration file for an adapter, the Tivoli Enterprise Console gateway sends events to the adapter-specified event server. If ServerLocation is not specified in an adapter configuration file, the Tivoli Enterprise Console gateway sends events to the event server specified by ServerLocation keyword in the Tivoli Enterprise Console gateway configuration file. If the ServerLocation keyword is not specified in the Tivoli Enterprise Console gateway configuration file, the Tivoli Enterprise Console gateway sends the event to the event server in the local Tivoli region.

The default value is @EventServer.

You can specify multiple event server names as a comma-delimited list. Event server names later in the list can be backup event servers when the Tivoli Enterprise Console gateway cannot contact its primary event server for an event and the interval specified by the RetryInterval keyword has expired without successfully contacting the primary server. You can specify a host name as you would for a non-TME adapter, and the events are then forwarded to that host using non-Tivoli communication. For more information, see the examples in the description of the ServerPort keyword.

When the Tivoli Enterprise Console gateway cannot contact the adapter-specified event server, the event server names specified in the list are backup event servers. If ServerLocation is not present in the Tivoli Enterprise Console gateway configuration file, the Tivoli Enterprise Console gateway uses the default @EventServer value as the backup event server.

To prevent event delivery to backup event servers, set the ServerLocation keyword to NONE.

Note:

When the ServerLocation keyword is used in conjunction with the TestMode=YES keyword, the ServerLocation keyword defines the path and the file name for logging events instead of the event server.

ServerPort

Specifies the port that the event server uses to send events using non-Tivoli communication.

The default value is 0, which causes the portmapper daemon on the specified host to determine the port on which the event server is listening for incoming events. If you are forwarding events to a Tivoli Availability Intermediate Manager, you cannot specify 0 as the port because the Tivoli Availability Intermediate Manager does not register itself with the portmapper daemon.

If you specify a value for the ServerPort keyword, the value must be either a single port number or a comma-delimited list of port numbers that correspond to the list of event servers specified in the ServerLocation keyword. If you specify a single port number and you have specified multiple event servers in the ServerLocation keyword, all event servers use the port number specified.

Assume that you have a Tivoli Availability Intermediate Manager running on hosts aim.xyz.com and aimbkup.xyz.com, and the ServerLocation and the ServerPort keywords are specified as follows:

ServerLocation=aim.xyz.com,aimbkup.xyz.com,@EventServer

 

ServerPort=5530,5531,0

Events are sent to port 5530 on the host aim.xyz.com using non-Tivoli communication. If that fails, events are sent to port 5531 on the host aimbkup.xyz.com. If that also fails, events are sent directly to the event server in the local Tivoli region using Tivoli communication. The port value of 0 specified for @EventServer is ignored because port numbers are not needed when using Tivoli communication.

Configuring the gateway to receive events from non-TME adapters

To configure the tec_gwr program to receive events receive events from non-TME adapters, set the value of the gwr_Enable keyword in the gateway configuration file to YES. The tec_gwr program listens on a socket port for incoming events from non-TME adapters. The port used must not be in use by another application, such as the event server.

If an event sent from the tec_gwr program to the tec_gateway program fails, the tec_gwr program resends the event when the gwr_RetryCount keyword is set to a value greater than or equal to 1. The tec_gwr program resends the event after waiting for the time period specified by the gwr_RetryInterval keyword. The number of retry attempts is equal to the value specified for the gwr_RetryCount keyword.

To configure non-TME adapters to use the IBM Tivoli Enterprise Console gateway, set the ServerLocation/channelServerLocation and the ServerPort/channelPort keywords in the configuration file of the adapter to the host name and port number that the tec_gwr program uses. If the tec_gwr program is not running on the same host as the event server, you can register the tec_gwr program with the portmapper daemon. To do this, set the value of the gwr_ReceptionPort keyword in the Tivoli Enterprise Console gateway configuration file to 0.

Note:

Messages received on the socket are generated by non-TME adapters and must be in the correct format as defined by the Tivoli Event Integration Facility in the Tivoli Enterprise Console product. Other types of messages are discarded.

The Tivoli Enterprise Console product uses the following files to receive events from non-TME adapters:

• UNIX and Windows:

  tec_gwr.cfg

  Installation script.

  init.tec_gwr

  Script used to start and shut down the tec_gwr program.

• Windows only

  tec_gwr.exe

  Executable file.

  tec_gwrs.exe

  Executable file as a service.

  sctlgwr.exe

  Service controller and installation utility.

• UNIX only

  tec_gwr

  Executable file.

Configuring the gateway for state correlation

To decrease the number of events that are sent to the event server, you can configure the Tivoli Enterprise Console gateway for state correlation. Using state correlation at the Tivoli Enterprise Console gateway to perform advanced filtering, duplication detection, and event correlation closer to the source off-loads filtering and event correlation from the event server.

For information about writing rules for state correlation, refer to the IBM Tivoli Enterprise Console Rule Developer's Guide.

Activating state machines

Before you activate the state machine, ensure that you have written your rules based on the information described in the IBM Tivoli Enterprise Console Rule Developer's Guide.

Follow this procedure to run a state machine:

1. Modify the state correlation keywords in the configuration file. The following code fragment illustrates the use of the appropriate keywords:

   UseStateCorrelation=YES
   # for Windows NT only
   StateCorrelationConfigURL=file:C:\tmp\test.xml
   # for all other INTERPs
   # StateCorrelationConfigURL=file:///tmp/test.xml
   # SendEventPort=1234
   # ReceiveAckPort=4321
   # ReceiveEventPort=5678
   # SendAckPort=8765

2. To run state correlation on an IBM Tivoli Enterprise Console gateway, change the adapter configuration profile (ACP) record, tec_gateway_sce, as follows:
   1. In the Current EIF Environment list, ensure that the UseStateCorrelation, SendEventPort, ReceiveAckPort, ReceiveEventPort, and SendAckPort keywords are set.
   2. Select the XML file to distribute, which you specified in step 1.
   3. Distribute the tec_gateway_sce ACP.

After the state machine is running, you can test whether state correlation is properly filtering events in the following ways:

• If you have written rules to generate event summaries, ensure that the event server is receiving the event summaries.
• If you have written rules to suppress events, ensure that suppressed events do not arrive at the event server.

Configuring the rate at which events are sent to the event server

At certain times, the number of events coming from endpoint adapters can overwhelm the Tivoli Enterprise Console gateway, the event server, and even the network. You can control the rate at which the Tivoli Enterprise Console gateway sends events to the event server using the EventSendThreshold, the BufferFlushRate, and the MaxGWCacheSizeMegs keywords in the Tivoli Enterprise Console gateway configuration file. The example in this section shows how to determine the values for the BufferFlushRate and EventSendThreshold keywords in the Tivoli Enterprise Console gateway configuration file to improve event server performance.

Gateway configuration example

This example assumes that the event server processes an average of 120 events per second without degrading its performance. The example environment contains two Tivoli Enterprise Console gateways, where gateway A is responsible for Web commerce servers and gateway B is responsible for the secretaries' systems.

The values provided in this example can vary greatly from installation to installation, depending on how many events, adapters, and Tivoli Enterprise Console gateways are in a particular environment. Use the worksheets provided in Worksheets and calculations to collect and calculate the data for your environment. All numerical values are expressed in events per second, except where noted.

1. Determine the average number of events that the event server can process (120 in this example).
2. Determine the number of Tivoli Enterprise Console gateways and the resulting number of events that they can send to the event server. Divide the average capacity of the event server by the number of Tivoli Enterprise Console gateways as shown in the following example:

   120 ÷ 2 = 60

   The resulting value of 60 indicates the average number of events each Tivoli Enterprise Console gateway can send without overwhelming the event server. Continue with step 3 to obtain the adjusted values for the Tivoli Enterprise Console gateway send rate.

3. Calculate the value for the EventSendThreshold keyword.

   The EventSendThreshold keyword sets the maximum number of events per second that the Tivoli Enterprise Console gateway sends to the event server. Because gateway A forwards events from mission-critical systems, more gateway A events should be sent to the event server than gateway B events. Thus, the EventSendThreshold keyword for gateway A is set to 80 events per second. Gateway B has the EventSendThreshold keyword set to 40 events per second. This way, more gateway A events get to the event server.

   The sum of the values for gateway A and gateway B must be less than or equal to the 120 events that the event server can process:

   80 + 40 <= 120

4. Determine the value for the BufferFlushRate keyword.

   Any events above the value specified for the EventSendThreshold keyword are stored in the cache on the Tivoli Enterprise Console gateway. To regulate the number of events being sent to the event server, the BufferFlushRate keyword controls the number of events per minute to be sent from the cache, when the gateway recovers a lost connection to the event server.

   For gateway A, the BufferFlushRate keyword is set to 5400 events per minute (90 events per second), and for gateway B the keyword is set to 3000 events per minute (50 events per second). Thus at peak traffic times, the event server is receiving 140 events per second from both Tivoli Enterprise Console gateways:

   90 + 50 = 140

   Although 140 events per second is greater than the average capacity of the event server (120 events per second), the event server has the capability to process excess events during brief, intermittent periods of time.

   Tip: Remember to convert events per second to events per minute before setting the value for the BufferFlushRate keyword.

5. Modify the adapter configuration profile for the Tivoli Enterprise Console gateway with the values calculated in step 3 and step 4.
6. Distribute the Tivoli Enterprise Console gateway adapter configuration profile.

Depending on the number of Tivoli Enterprise Console gateways and endpoints in your environment, you need to carefully consider the rates you specify for the keywords. For instance, an improper configuration might have multiple Tivoli Enterprise Console gateways sending events at the same rate, thus flooding the event server at the same time. See Gateway configuration file for details about these keywords.

Worksheets and calculations

Table 10 and Table 11 summarize the values for this example. You can use these tables as worksheets to assemble the values you measure and calculate for your environment. All numerical values are expressed in events per second, except where noted.

Table 10. Example rate at which the event server processes events

Average Receive Rate	Expected Peak Rate for High Traffic
120	140

 

Table 11. Example rate at which events are sent to the event server

	Event Send Rate	Adjusted Rate	EventSendThreshold	BufferFlushRate
Gateway A	60	80	80	5400 events per minute (90 events per second)
Gateway B	60	40	40	3000 events per minute (50 events per second)
Total Events Sent to Event Server	120	120	120	140 events per second

The following are the calculations to control event traffic:

event server average rate >= gateway A events + gateway B events

EventSendThreshold = adjusted send rate for gateway

   gateway A         gateway B
BufferFlushRate + BufferFlushRate <= event server peak rate

Starting and stopping the tec_gwr program

By default, the tec_gwr program is automatically started when the host starts. The tec_gwr program is automatically started when an adapter configuration profile containing the tec_gateway or tec_gateway_sce entry is distributed using the Adapter Configuration Facility. You can also manually start the tec_gwr program. Starting the tec_gwr program causes the tec_gwr program to reread the tec_gateway.conf configuration file and restart the daemons.

The tec_gwr program is automatically stopped when you distribute an adapter configuration profile that has the init.tec_gwr start command removed from the after-file-distribution actions. You can also manually stop the tec_gwr program.

Starting the tec_gwr program manually

To start the tec_gwr program manually, use one of the following commands:

• UNIX:

  init.tec_gwr start &

Obtaining the status of the tec_gwr program on UNIX

To obtain the status of the tec_gwr program on a UNIX system, use the init.tec_gwr command as follows:

• To obtain status, type the following command:

  init.tec_gwr status &

• To obtain the process ID, type the following command:

  init.tec_gwr pid &

• To obtain environment settings, type the following command:

  init.tec_gwr env &