IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide · 2020-07-23 · IBM T ivoli Netcool/OMNIbus Java Socket Gateway The Java Socket Gateway can r ead events fr om any ObjectServer

IBM® Tivoli® Netcool/OMNIbus Socket GatewayVersion 2.0

Reference GuideAugust 6, 2015

SC27-5681-02

IBM

IBM® Tivoli® Netcool/OMNIbus Socket GatewayVersion 2.0

Reference GuideAugust 6, 2015

SC27-5681-02

IBM

NoticeBefore using this information and the product it supports, read the information in “Notices and Trademarks,” on page 27.

Edition notice

This edition (SC27-5681-02) applies to version 2.0 of IBM Tivoli Netcool/OMNIbus Socket Gateway, and to allsubsequent releases and modifications until otherwise indicated in new editions.

This version replaces SC27-5681-01.

© Copyright IBM Corporation 2013, 2015.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this guide . . . . . . . . . . . vDocument control page . . . . . . . . . . . vConventions used in this guide . . . . . . . . vi

IBM Tivoli Netcool/OMNIbus Java SocketGateway . . . . . . . . . . . . . . 1Summary of the Java Socket Gateway . . . . . . 1Installing the gateway . . . . . . . . . . . 2

Installing probes and gateways on TivoliNetcool/OMNIbus V8.1 . . . . . . . . . 2Installing the gateway on TivoliNetcool/OMNIbus V7.4.0 . . . . . . . . . 4

Using the Socket Gateway . . . . . . . . . . 5Features of the Socket Gateway . . . . . . . 5Configuring communication details . . . . . . 7

Configuring the gateway . . . . . . . . . . 8

Properties file . . . . . . . . . . . . . 8Map definition file . . . . . . . . . . . 15Startup command file . . . . . . . . . . 16AfterIDUC and Filter functions . . . . . . . 17Table replication definition file . . . . . . . 18Sending events with the Socket Gateway . . . 19Socket Gateway Store and Forward . . . . . 23Running the gateway . . . . . . . . . . 23FIPS mode and encryption . . . . . . . . 23

Error messages . . . . . . . . . . . . . 24Known issues. . . . . . . . . . . . . . 26

Appendix. Notices and Trademarks . . 27Notices . . . . . . . . . . . . . . . . 27Trademarks . . . . . . . . . . . . . . 29

© Copyright IBM Corp. 2013, 2015 iii

iv IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

About this guide

The following sections contain important information about using this guide.

Document control pageThe IBM Tivoli Netcool/OMNIbus Socket Gateway documentation is provided insoftcopy format only. To obtain the most recent version, visit the IBM TivoliNetcool/OMNIbus Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/common/kc_welcome-444.html?lang=en

Table 1. Document modification history

Document version Publication date Comments

SC27-5681-00 July 5, 2013 First IBM publication.

SC27-5681-01 September 30, 2013 “Map definition file” on page 15updated.

“Sending events with the SocketGateway” on page 19 updated.

SC27-5681-02 August 6, 2015 Changed the name of the gateway fromJava Gateway for Socket to IBM TivoliNetcool/OMNIbus Socket Gateway (JavaSocket Gateway).

“IBM Tivoli Netcool/OMNIbus JavaSocket Gateway,” on page 1 updated.

“Summary of the Java Socket Gateway”on page 1 updated.

“Features of the Socket Gateway” onpage 5 updated.

64 bit support added

“Configuring communication details” onpage 7 updated.

© Copyright IBM Corp. 2013, 2015 v



Table 1. Document modification history (continued)

Document version Publication date Comments

SC27-5681-02 August 6, 2015 “Configuring the gateway” on page 8updated.

The following new property was added:Gate.Socket.ShutdownOnConnectionError.

Updates were made to the followingproperties: Gate.Socket.BatchSize,Gate.Socket.RetryAttemptsDueToConnectionFailures,Gate.Socket.RetryAttemptsDueToTimeouts, andGate.Socket.Timeout.

“Sending events with the SocketGateway” on page 19 updated.

“Socket Gateway Store and Forward” onpage 23 updated.

Conventions used in this guideAll gateway guides use standard conventions for operating system-dependentenvironment variables and directory paths.

Operating system-dependent variables and paths

All gateway guides use standard conventions for specifying environment variablesand describing directory paths, depending on what operating systems the gatewayis supported on.

For gateways supported on UNIX and Linux operating systems, gateway guidesuse the standard UNIX conventions such as $variable for environment variables andforward slashes (/) in directory paths. For example:

$OMNIHOME/gates

For gateways supported only on Windows operating systems, gateway guides usethe standard Windows conventions such as %variable% for environment variablesand backward slashes (\) in directory paths. For example:

%OMNIHOME%\gates

For gateways supported on UNIX, Linux, and Windows operating systems,gateway guides use the standard UNIX conventions for specifying environmentvariables and describing directory paths. When using the Windows command linewith these gateways, replace the UNIX conventions used in the guide withWindows conventions. If you are using the bash shell on a Windows system, youcan use the UNIX conventions.

Note: The names of environment variables are not always the same in Windowsand UNIX environments. For example, %TEMP% in Windows environments isequivalent to $TMPDIR in UNIX and Linux environments.

vi IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

Operating system-specific directory names

Where Tivoli Netcool/OMNIbus files are identified as located within an archdirectory under NCHOME or OMNIHOME, arch is a variable that represents youroperating system directory. For example:

$OMNIHOME/platform/arch

The following table lists the directory names used for each operating system.

Note: This gateway may not support all of the operating systems specified in thetable.

Table 2. Directory names for the arch variable

Operating system Directory name represented by arch

AIX® systems aix5

Red Hat Linux and SUSE systems linux2x86

Linux for System z® linux2s390

Solaris systems solaris2

Windows systems win32

OMNIHOME location

Gateways and older versions of Tivoli Netcool/OMNIbus use the OMNIHOMEenvironment variable in many configuration files. Set the value of OMNIHOME asfollows:v On UNIX and Linux, set $OMNIHOME to $NCHOME/omnibus.v On Windows, set %OMNIHOME% to %NCHOME%\omnibus.

About this guide vii

viii IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

IBM Tivoli Netcool/OMNIbus Java Socket Gateway

The Java Socket Gateway can read events from any ObjectServer table and forwardthem to a socket using a TCP connection. Typically, the gateway reads thealerts.status table or the alerts.journal table. Any program that listens to that socket(for example, Netcat) can receive those alerts.

In the gateway default mode of unbatched and unacknowledged event sending,see “Sending events with the Socket Gateway” on page 19, the gateway processesInsert, Delete, Update, Control (IDUC) cycles as follows:1. The gateway receives event data from the ObjectServer for each Delete, Insert

and Update event that occurs in a single IDUC cycle. The IDUC cycles occurperiodically and the cycle intervals can be configured using theGate.RdrWtr.IducFlushRate property.

2. Each instance of an Insert and Update is mapped into a pair of name valuepairs, as defined by the gateway mapper file. For more information, see “Mapdefinition file” on page 15.

Note: Deletes are not part of the mapping phase.3. The gateway writer then processes the mapped event data, saves the event data

to disk, and queues the event data to be sent to the target system.

This guide contains the following sections:v “Summary of the Java Socket Gateway”v “Installing the gateway” on page 2v “Using the Socket Gateway” on page 5v “Configuring the gateway” on page 8v “Error messages” on page 24

Summary of the Java Socket GatewayEach gateway works in a different way to provide an interface with theObjectServer. Use this summary information to learn about the Socket Gateway.

The following table provides a summary of the gateway:

Table 3. Summary

Gateway target TCP Socket

Gateway executable file name nco_g_socket_java

Package Version 2.0

Gateway supported on For details of supported operating systems, see thefollowing Release Notice on the IBM Software Supportwebsite: http://www-01.ibm.com/support/docview.wss?uid=swg21625776

© Copyright IBM Corp. 2013, 2015 1

http://www-01.ibm.com/support/docview.wss?uid=swg21625776

http://www-01.ibm.com/support/docview.wss?uid=swg21625776

Table 3. Summary (continued)

Configuration files $OMNIHOME/gates/socket_java/G_SOCKET.props

$OMNIHOME/gates/socket_java/socket_java.map

$OMNIHOME/gates/socket_java/socket_java.rdrwtr.tblrep.def

$OMNIHOME/gates/socket_java/socket_java.startup.cmd

Requirements A currently supported version of IBM TivoliNetcool/OMNIbus.

NSocket library files (for IPv6 support)

gateway-libgwutility-2 version 2 or above.

gateway-libngjava-7 or above.

Remote Connectivity Available

Failover/failback functionality Available

For details of configuring failover/failback, see “Failoverand Failback” on page 6.

Multicultural support Available

IP environment IPv4 and IPv6

Federal InformationProcessing Standards (FIPS)

IBM Tivoli Netcool/OMNIbus uses the FIPS 140-2approved cryptographic provider: IBM Crypto for C (ICC)certificate 384 for cryptography. This certificate is listed onthe NIST website at http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm. For detailsabout configuring Netcool/OMNIbus for FIPS 140-2 mode,see the IBM Tivoli Netcool/OMNIbus Installation andDeployment Guide.

Installing the gatewayThere are separate procedures for installing the gateway on each version of TivoliNetcool/OMNIbus.

Follow the procedure for the version of Tivoli Netcool/OMNIbus that your siteuses.

Installing probes and gateways on Tivoli Netcool/OMNIbusV8.1

From Tivoli Netcool/OMNIbus V8.1 onwards, Tivoli Netcool/OMNIbus probesand gateways can be installed using the IBM Installation Manager. One of the keyfeatures of Installation Manager is that all platforms are shipped in a single ZIPfile, which means that you do not have to select the platform that you require;Installation Manager does it for you.

Before you can install a probe or gateway, you must have installed and configuredInstallation Manager and Tivoli Netcool/OMNIbus. To install probes andgateways, you must make sure that the Core Tivoli Netcool/OMNIbus featuresProbe Support and Gateway Support respectively are installed.

2 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm

http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm

Installing probes and gateways using the Command Line Tool

To install the probe or gateway using the Command Line Tool, run the followingcommand:

installation_manager_location/eclipse/tools/imcl -c installcom.ibm.tivoli.omnibus.integrations.integration_name -repositoriesrepository_containing_required_integration -installationDirectorylocation_of_netcool_omnibus_install_you_are_installing_into

Where integration_name specifies the name of the probe or gateway that you wantto install.

You will be prompted to agree to the terms and conditions of the license as aprerequisite for installing the integration. If you have already reviewed the licenseand want to skip the manual acceptance, add the -acceptLicense option to theinstall command to silently agree to the license.

The following is an example command used to install the SNMP Probe:

imcl -c install com.ibm.tivoli.omnibus.integrations.nco-p-mttrapd-repositories /home/my_home_dir/nco-p-mttrapd_im_package-installationDirecory /opt/IBM/tivoli/netcool

Where /home/my_home_dir/nco-p-mttrapd_im_package contains the unzippedcontents of the SNMP Probe Installation Manager package.

Note: The command line tool does not add the repository permanently to theInstallation Manager instance. If you subsequently start the Installation ManagerGUI, the repositories will not be present in the Repositories dialog box.

Uninstalling probes and gateways using the Command Line Tool

To uninstall the probe or gateway using the Command Line Tool, run thefollowing command:

installation_manager_location/eclipse/tools/imcl uninstallcom.ibm.tivoli.omnibus.integrations.integration_name -installationDirectorylocation_of_netcool_omnibus_install_you_are_uninstalling_from

Where integration_name specifies the name of the probe or gateway that you wantto uninstall.

The following is an example command used to uninstall the SNMP Probe:

imcl uninstall com.ibm.tivoli.omnibus.integrations.nco-p-mttrapd-installationDirecory /opt/IBM/tivoli/netcool

Installing probes and gateways using the GUI

To install the probe or gateway using the GUI, use the following steps:1. Unzip the IM package that contains the probe or gateway into a directory of

your choosing. A file called repository.config will appear after unzipping theIM package.

2. Start Installation Manager using the following command:

IBM Tivoli Netcool/OMNIbus Java Socket Gateway 3

installer_path/IBMIM

Where installer_path is the path to the Installation Manager directory.3. Perform the following menu actions to display the repository dialog box:

Files > Preferences > Repositories.

4. Use the button Add Repository in the repository dialog box to point to therepository that contains the unzipped IM package that contains the probe orgateway. This is the repository that contains the repository.config file.

5. Click the Install software packages icon.6. Select the name of the probe or gateway that you want to install.7. Click Next.8. Click I accept when the Licensing panel appears.9. Highlight IBM Tivoli Netcool OMNIbus in the Package Group Name field.

10. Click Next.11. Click Next.12. Click Install.13. When the Install Packages panel appears indicating that you have

successfully installed the probe or gateway, click Finish.

Uninstalling probes and gateways using the GUI

To uninstall the probe or gateway, use the following steps:1. Start Installation Manager using the following command:

installer_path/IBMIM

Where installer_path is the path to the Installation Manager directory.2. Click the Uninstall software packages icon.3. Select the name of the probe or gateway that you want to uninstall.4. Click Next.5. Click Unisntall.6. When the Install Packages panel appears indicating that you have successfully

uninstalled the probe or gateway, click Finish.

Installing the gateway on Tivoli Netcool/OMNIbus V7.4.0For Tivoli Netcool/OMNIbus V7.4.0, all gateways are installed using the TivoliNetcool/OMNIbus installer.

You can install the gateway using any of the following:v “The installation wizard” on page 5v A text-based installer (“Console mode” on page 5)v Settings predefined in a text file (“Silent mode” on page 5)

The installation package and patches for the gateway are supplied as archives. Thearchive management application that you use to extract the files must be able topreserve the directory structure contained in the archive on extraction.

Note: If you are installing a 32-bit gateway on a system that runs a 64-bit UNIX orLinux operating system, you will need to install additional, 32-bit operating systemlibraries. See the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide formore information.


Obtaining the installation packageTo obtain the installation package and prepare it for installation use the followingsteps:1. Download the installation package for the gateway from the Passport

Advantage Online Web site:http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

2. Make a backup of any existing configuration files that you want to retain.3. Extract the contents of the installation package to a temporary directory.

Now use one of the installation methods to install your gateway. In each case, thegateway is installed in the following directory:

$NCHOME/omnibus/gates

The installation wizardTo install the gateway using the installation wizard:1. Run the installer for your operating system:

$NCHOME/omnibus/install/nco_install_integration

2. When the installation wizard starts, specify the extracted directory that containsthe README.txt file as the location of the gateway installation files.

3. Accept the license conditions.

Console modeTo install the gateway in console mode:1. Run the installer for your operating system:

$NCHOME/omnibus/install/nco_install_integration -i console

2. When the text-based installer starts, specify the extracted directory that containsthe README.txt file as the location of the gateway installation files.

3. Accept the license conditions.

Silent modeTo install the gateway in silent mode:1. Create a text file named reponse.txt and add the following entries:

PROBE_OR_GATE_LOCATION=README_directorypathLICENSE_ACCEPTED=true

where README_directorypath is the path to the directory containing theREADME.txt file in the extracted package.

2. Run the installer for your operating system:$NCHOME/omnibus/install/nco_install_integration -i silent -fresponse_path/response.txt

where response_path is the full path to the response.txt file.

Using the Socket GatewayThe Socket Gateway connects to the configured socket and forwards events fromthe ObjectServer to a local or a remote socket over TCP.

Features of the Socket GatewayThe Socket Gateway has various features that enable you to create an interfacebetween the socket and the ObjectServer.


http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm

Centralized property management

The gateway uses centralized property management and separates properties fromdata processing configuration. To configure the common gateway properties andthe Socket Gateway properties, use the G_SOCKET.props properties file. To configuredata processing, use the table replication definition file and the mapping file. Tospecify a set of commands that the gateway performs automatically each time itstarts, use the startup command file.

The following topics describe the settings required within the properties file.

Setting the format of headers and trailers added to alerts

Whenever a delete, update, or insert occurs in the ObjectServer fields, the gatewaysends header and trailer information with the changed alerts to the socket. Usingthe properties file, you can define the format in which the gateway adds theheader and trailer in the alerts.

The following example shows header and trailer format definitions of the deletes,updates, and inserts:# Gate.Socket.DeleteHeader : ’\nStart of delete line\n’# Gate.Socket.DeleteTrailer : ’\nEnd of delete line\n’# Gate.Socket.UpdateHeader : ’\nStart of update line\n’# Gate.Socket.UpdateTrailer : ’\nEnd of update line\n’# Gate.Socket.InsertHeader : ’\nStart of insert line\n’# Gate.Socket.InsertTrailer : ’\nEnd of insert line\n’

Where, \n instructs the start of the next line.

Passing table data

The gateway can replicate the data in any table between the ObjectServer and thedestination socket. Details of the tables to be replicated are stored in the tablereplication definition file. Use the Gate.RdrWtr.TblReplicateDefFile property tospecify the location of the table replication definition file.

Mapping table data

The gateway writes the alerts received from the various tables in the ObjectServeronto the socket in a format defined by the map definition file. To specify the mapdefinition file, use the Gate.MapFile property.

Failover and Failback

Failover functionality comes into operation when the gateway loses its connectionto the primary ObjectServer. When the primary ObjectServer fails, the readerconnects to the backup ObjectServer as configured using the TivoliNetcool/OMNIbus Server Editor (nco_xigen). To specify that the gateway failsback to the primary ObjectServer, set the Gate.RdrWtr.FailbackEnabled property toTRUE.

When the reader has detected that it is now connected to a backup ObjectServer, itperiodically polls for the return of the primary ObjectServer at the frequencyspecified by the Gate.RdrWtr.FailbackTimeout property. When the primaryObjectServer is detected again, the reader automatically fails back to the primaryObjectServer.


Process Agent control

You can control how the gateway runs by using Process Agent (PA) control.

The gateway can be run under PA control. The Gate.PAAware property indicateswhether the gateway is PA aware. The Gate.PAAwareName property indicates whichPA is running the gateway.

Important: These properties are maintained automatically by the PA server andprovide information only. Do not change these properties manually.

Error handling

You can troubleshoot problems with the gateway by consulting error messages. Tohelp you do this, the gateway has configurable error handling.

Error handling is provided by the Netcool/OMNIbus Gateway Toolkit (NGTK)library. To specify that the NGTK library logs debug messages, set theGate.NGtkDebug property to TRUE.

Configuring communication detailsTo enable communication between the gateway and the ObjectServer, you mustconfigure communication details for the ObjectServer and the gateway using theTivoli Netcool/OMNIbus Server Editor (nco_xigen) and create an entry for theObjectServer in the interfaces file ($NCHOME/etc/omni.dat).

Note: If the ObjectServer is already configured and the gateway is to run from thesame installation, you do not need to configure communication details for theObjectServer.

On UNIX and Linux operating systems, use the following command to start theServer Editor:

$NCHOME/omnibus/bin/nco_xigen

On Windows operating systems, use the following command to start the ServerEditor:

Start > Programs > NETCOOL Suite > System Utilities > Servers Editor

You must also add a gateway server entry to the interfaces file. You can do thisusing the Server Editor. Alternatively, on Unix and Linux operating systems youcan edit the interfaces file and regenerate it using the nco_igen utility. The defaultgateway server name is G_SOCKET, which corresponds to the value specified for theName property defined in the G_SOCKET.props properties file.

If there is a firewall between the gateway and the ObjectServer, configure theObjectServer to use a fixed port for IDUC and ensure that both the mainObjectServer port and the IDUC port are opened in the firewall. By default, theObjectServer uses a random IDUC port.

For more information about using the Server Editor and the interfaces file, see theIBM Tivoli Netcool/OMNIbus Installation and Deployment Guide.


Configuring the gatewayThe Socket Gateway is configured using a set of configuration files.

Use the Tivoli Netcool/OMNIbus Server Editor (nco_xigen) to specify the hostname and port number of the gateway host in the Tivoli Netcool/OMNIbusinterfaces file.

Note: For information about using the Server Editor, see IBM TivoliNetcool/OMNIbus Probe and Gateway Guide.

To configure the gateway on UNIX, use the following steps:1. Create the server G_SOCKET in the interfaces files using nco_xigen.2. Copy the properties file (G_SOCKET.props) to the following directory:

$OMNIHOME/etc.

Note: G_SOCKET is the default name for the gateway server, andG_SOCKET.props is the default name for its properties file. You can specify analternative properties file using the -propsfile command-line option when yourun the gateway.You can also specify an alternative name for the gateway server by using the-name command-line option. When you set the gateway server name using the-name command-line option, the default log file and properties file names arealso changed accordingly. The properties file is expected to be in the$OMNIHOME/etc directory by default.

3. Edit the properties file to suit your environment.

The following topics describe the configuration files and how to use them:v “Properties file”v “Map definition file” on page 15v “Startup command file” on page 16v “AfterIDUC and Filter functions” on page 17v “Table replication definition file” on page 18v “Sending events with the Socket Gateway” on page 19

Properties fileThe properties file is a text file that contains a set of properties and theircorresponding values. These properties define the operational environment of thegateway, such as connection details and the location of the other configurationfiles.

The default properties file for the Socket Gateway is G_SOCKET.props and it isinstalled in the following location:v $OMNIHOME/gates/socket_java

Property settings for the operational environment of the gatewayYou use properties to define the operational environment of the gateway. You canoverride the default values by using the properties file.

The following table describes the properties defined in the G_SOCKET.propsproperties file that are most frequently used to configure the Socket Gateway. For


more information about generic properties and command line options, andInterprocess Communication (IPC) properties, see the IBM Tivoli Netcool/OMNIbusProbe and Gateway Guide.

Table 4. Properties file

Property name Command line option Description

Gate.MapFile string -mapfile string Use this property to specify themapping file for the gateway touse.

The default is$OMNIHOME/gates/socket_java/socket_java.map.

Gate.G_SOCKET.Debug boolean -g_socketdebugTRUE|FALSE

Use this property to enable thegateway reader/writer debugmessages.

The default is TRUE. (Debugmessages are enabled.)

Gate.G_SOCKET.FailbackEnabled boolean

-g_socketfailbackenabledTRUE|FALSE

Use this property to specifywhether the gateway fails backto the backup ObjectServerwhen disconnected from theprimary ObjectServer.

The default is FALSE.

Gate.G_SOCKET.FailbackTimeout integer

g_socketfailbacktimeoutinteger

Use this property to specify thefrequency (in seconds) withwhich the gateway attempts tofail back to the primary systemfollowing a system failover.

The default is 30 seconds.

Gate.RdrWtr.IducFlushRateinteger

-rdrwtriducflushrateinteger

Use this property to specify therate (in seconds) of thegranularity of the reader.

If you set this property to 0(zero), the reader gets itsupdates at the same granularrate as that of the ObjectServerto which it is connected.


Note: If you set this property toa value greater than 0 seconds,the reader issues automaticIDUC flush requests to theObjectServer with this frequency.This enables the reader to run ata faster granularity than that ofthe ObjectServer, thus enablingthe gateway to capture moredetailed event changes insystems where the ObjectServeritself has high granularitysettings.


Table 4. Properties file (continued)


Gate.RdrWtr.TblReplicateDefFile string

-rdrwtrtblrepdeffilestring

Use this property to specify thelocation and name of the tablereplication definition file.

The default location and nameare as follows:

$OMNIHOME/gates/socket_java/socket_java.rdrwtr.tblrep.def

Gate.Socket.BatchNameDescriptor string

-batchnamedescriptorstring

Use this property whenprocessing batch files. Thegateway creates a batch filename with the string that youspecify in this property. Togenerate unique names for eachbatch file, the gateway appendsthe batch sequence number andevent type contained within thebatch file.

The default name isgw_socket.log.

Gate.Socket.BatchSizeinteger

-batchsize integer Use this property to specify themaximum number of eventswritten to an individual batchfile.

If theGate.Socket.SendAsBatchesproperty is set to TRUE, theGate.Socket.BatchSize propertydetermines the maximumnumber of events that thegateway sends to a targetsystem in a single batch.

The default minimum value is150 events.

Gate.Socket.DateFormatstring

-dateformat string Use this property to specify thedate format that the gatewayuses for any date fields writtento the socket.

The default isyyyy-MM-dd\'T\'HH:mm:ssZ.

Gate.Socket.DeleteHeaderstring

-deleteheader string Use this property to specify theformat of the header added tothe start of each delete alertwritten to the socket.

The default is 'DELETE'




Gate.Socket.DeleteTrailerstring

-deletetrailer string Use this property to specify theformat of the trailer added tothe end of each delete alertwritten to the socket.

The default is '\n'.

Gate.Socket.DoTimestampboolean

-dotimestamp TRUE|FALSE Use this property to specifywhether the gateway prefixeseach event with the date andtime of its arrival.

The default is FALSE (thegateway does not prefix eachevent with the date and time ofits arrival).

Gate.Socket.EnableAcksboolean

-acks : Set to TRUE orFALSE to enable or disableapplication levelacknowledgments.

-enableacks : Sets thevalue to TRUE to enablemessage or batchacknowledgements.

-disableacks : Sets thevalue to FALSE to disablemessage or batchacknowledgements.

Use this property to enablemessage or batchacknowledgements andapplication levelacknowledgements.

The default is FALSE (thegateway disables message orbatch acknowledgements).

Gate.Socket.EndStringstring

-endstring string Use this property to specify thevalue to be added at the end ofeach string to be written to thesocket.

The default is '"'.

Gate.Socket.Host string -host string Use this property to specify thename of the host to which theTCP connection is made.

The default is localhost.

Gate.Socket.InsertHeaderstring

-insertheader string Use this property to specify theformat of the header added tothe start of each insert alertwritten to the socket.

The default is 'INSERT'.

Note: Although the commandline option is available to set thevalue for this property, it isrecommended that you set thevalue of this property in theG_SOCKET.props properties file.




Gate.Socket.InsertTrailerstring

-inserttrailer string Use this property to specify theformat of the trailer added tothe end of each insert alertwritten to the socket.



Gate.Socket.KeepAlivestring

-keepalive string Use this property to specifywhether the gateway keeps TCPsockets open when not in use.

The default is FALSE (thegateway does not keep TCPsockets open when not in use).

Important: To ensure that afirewall does not timeout TCPconnections, you must set thevalue to TRUE.

Gate.Socket.MaxBatchFilesinteger

-maxbatchfiles integer Use this property to specify themaximum number of batch filesthe gateway stores. If thenumber of events that thegateway can store exceeds thecapacity before they are sent toa socket using a TCP connection,the gateway will ignoresubsequent events (that is, thegateway creates no additionalbatch files).

The default is 1000 batch files.

Gate.Socket.Port integer -port integer Use this property to specify theTCP port to which the gatewayconnects.

The default is 1234.

Gate.Socket.ReconnectTimeout integer

-reconnecttimeout integer Use this property to specify thetime (in seconds) the gatewaywaits before trying to reconnectto the socket after a connectionfailure.





Gate.Socket.RetryAttemptsDueToConnectionFailuresinteger

-retryattempts_connectionfailure integer

Use this property to specify howmany times the gateway tries tosend an event or batch file whenthere is a socket connectionfailure. For example, if set to 1,the event or batch file will bedropped if a connection failureoccurs after the first attempt tosend it.

The default is 0 (the gatewaydoes not stop trying to send anevent or batch file when there isa socket connection failure).

Gate.Socket.RetryAttemptsDueToTimeouts integer

-retryattempts_timeoutsinteger

Use this property to specify howmany times the gateway tries tosend an event when the socketoperation times out.

The default is 5 (that is, thegateway drops the event aftertrying to send it five times).

Gate.Socket.SAF boolean -socketsaf : Set to TRUEor FALSE to enable ordisable the store andforward feature.

-safenabled : This sets theproperty to TRUE (storeand forward feature isenabled).

-safdisabled : This setsthe property to FALSE(store and forward featureis disabled).

Use this property to specifywhether the gateway uses thestore and forward feature.

The default is FALSE (the storeand forward feature is notenabled).

For more information on thestore and forward feature, see“Socket Gateway Store andForward” on page 23.

Gate.Socket.SendAsBatchesboolean

-sendasbatches : This setsthe property to TRUE.

-sendsingleevents : Thissets the property to FALSE.

Use this property to specifywhether the gateway sendsevents to the target device inbatches or as single events.

The default is FALSE (thegateway sends events to thetarget device as single events).

Note: You should never alter abatch file. Batch files areinternally generated by thegateway and altering them cancause major issues.

Gate.Socket.Separatorstring

-separator string Use this property to specify thecharacter to be inserted betweenthe fields written to the socket.

The default is ';' (semicolon).




Gate.Socket.ShutdownOnConnectionError boolean

-shutdownon connectionerror: Set to TRUE orFALSE to cause thegateway to shutdown ornot shutdown uponencountering a socketconnection error.

Use this property to cause thegateway to shutdown uponencountering a socketconnection error.

The default is FALSE (thegateway does not shutdown onencountering a socketconnection error).

Note: It is expected that theGate.Socket.SAF propertywould be set to FALSE wheneverthis property is set to TRUE. Onshutdown one or moreunprocessed events may remainin the batch files and thesewould be deleted automaticallyon the next gateway startup,provided SAF is disabled.

Gate.Socket.StartStringstring

-startstring string Use this property to specify thevalue to be added at the start ofeach string to be written to thesocket.

The default is '"'.

Gate.Socket.Timeout integer -timeout integer Use this property to specify theperiod (in seconds) that thegateway waits for data to besent over the socket connection.


Gate.Socket.UpdateHeaderstring

-updateheader string Use this property to specify thevalue to be added to the start ofeach update alert written to thesocket.

The default is 'UPDATE'.





Gate.Socket.UpdateTrailerstring

-updatetrailer string Use this property to specify thevalue to be added to the end ofeach update alert written to thesocket.



Java properties

The following table describes the available Java properties.

Table 5. Java properties


Gate.Java.Arguments string -javaargs string Use this property to specifythe arguments to use whenstarting Java™.

The default is "".

Gate.Java.ClassPath string -javacpath string Use this property to specifythe environment variableused to store the location ofthe Java libraries.

The default is the value ofthe $CLASSPATH environmentvariable on the machine.

Gate.Java.Debug boolean -javadebug boolean Use this property to enablethe logging of Java debugmessages.

The default is TRUE (enablethe logging of Java debugmessages).

Gate.Java.LibraryPath string -javalibpath string Use this property to specifythe location of the Javalibraries that will be set inthe environment variablespecified by theGate.Java.ClassPathproperty.

Map definition fileThe Socket Gateway writes the alerts received from the various tables in theObjectServer onto the socket in a format defined by the map definition file.


The default map definition file, socket_java.map, is installed in the followinglocation:v $OMNIHOME/gates/socket_java

Gateway mapper attributes

You can configure the mapping functions of the gateway by using the mapperattributes.

Syntax

Mappings for use with the Socket Gateway must use the following syntax:CREATE MAPPING mappingname(’’ = ’@fieldname’ [ON INSERT ONLY],[’’ =’@fieldname’ [ON INSERT ONLY]]...) ;

Where:

mappingname is the name of the mapping to be created.

fieldname must be the name of a field in one of the ObjectServer tables.

The optional ON INSERT ONLY controls the updating of the field during the life ofthe alert. When omitted, the field is updated for any change in the state of thealert. When included, the field is only set when the alert is created.

Creating name-value pairs in the gateway output

To create a list of name-value pairs in the gateway output, configure the map fileusing the following example.

’’ = ’Identifier : ’ + ’@Identifier’,

’’ = ’Serial : ’ + TO_STRING(’@Serial’),

Where Identifier and Serial are the values you want named in the gateway output.

Note: You need to do a type conversion for non-string valued fields.

For details about the map definition file, see the IBM Tivoli Netcool/OMNIbus Probeand Gateway Guide.

Startup command fileThe startup command file contains a set of commands that the gateway executeseach time it starts.

You can specify the location of the startup command file using the genericNetcool/OMNIbus Gate.StartupCmdFile property.

The default startup command file for the gateway is socket_java.startup.cmd andis located in the following directory:

$OMNIHOME/gates/socket_java


The default startup command file contains example commands. You should make acopy of the default file for future reference.

You can use the following commands within the startup command file:v SHOW PROPS - Use this command to display the current configuration of the

gateway by listing all properties and their values.v GET PROPERTY ’property_name’ - Use this command to return the value of the

property specified in property_name from the gateway properties file.v SET PROPERTY ’property_name’ TO ( ’string’ | integer | TRUE | YES | FALSE

| NO ); - Use this command to set the value of the property specified inproperty_name in the gateway properties file.

v SET LOG LEVEL TO - Use this command to set the level of message logging for thegateway. This command can take the following values: fatal, error, warn,info or debug. The default logging level is warn.

These commands can also be entered using the SQL interactive interface (nco_sql).For more information about using the SQL interactive interface, see the IBM TivoliNetcool/OMNIbus Administration Guide.

For more information about the startup command file, see the IBM TivoliNetcool/OMNIbus Probe and Gateway Guide.

AfterIDUC and Filter functionsThe Java Socket Gateway implements the AfterIDUC and filter functions using thetable replication definition file called socket_java.rdrwtr.tblrep.def. You specifythe location and name of the table replication definition file in theGate.RdrWtr.TblReplicateDefFile property.

Use the AFTER IDUC DO command to update replicated rows. In the followingexample, the AFTER IDUC DO clause instructs the gateway to set the Archivedcolumn to 1 for all replicated rows:REPLICATE ALL FROM TABLE ’alerts.status’USING MAP ’StatusMap’AFTER IDUC DO ’Archived=1’;

Use the FILTER WITH command to filter the data that is replicated to the targetsystem. In the following example, the FILTER WITH clause instructs the gateway toonly replicate alerts that originate from the NCOMS_US and NCOMS_CAObjectServers:REPLICATE ALL FROM TABLE ’alerts.status’USING MAP ’StatusMap’FILTER WITH ’ServerName IN (\’NCOMS_US\’,\’NCOMS_CA\’)’;

Note: You must use backslash characters (\) to escape the quote characters (’) inthe query string.

An important consideration when filtering replicated data is that the filter shouldmatch a characteristic of the alerts that does not change over time. This can be thealert source, as in the example above. You could also use the Class and Managerelements of alerts as a filter. Elements of alerts such as Severity make for bad filtercriteria because they can change over the lifecycle of an alert.


Table replication definition fileThe gateway replicates data between ObjectServer tables and the gateway target.The table replication definition file is used to define which tables and event typesare monitored in Tivoli Netcool/OMNIbus and forwarded to the target that thegateway is configured to send data to.

You specify the location and name of the table replication definition file using thegeneric Tivoli Netcool/OMNIbus Gate.RdrWtr.TblReplicateDefFile property.

The default table replication file for the gateway is socket_java.rdrwtr.tblrep.defand is located in the following directory:

$OMNIHOME/gates/socket_java

The default table replication definition file contains example commands. Youshould make a backup copy of the default file for future reference.

Note: You should use the REPLICATE command to replicate data from the primarytables (alerts.status, alerts.journal, alerts.details) and dynamic secondarytables (if required).

You can add one or more optional clauses to the REPLICATE command to furtherprocess the data during replication. The available commands are listed in thefollowing syntax example. Use the optional clauses in the order in which they arelisted in the syntax. For example, when using both the

FILTER WITH and AFTER IDUC DO clauses, the FILTER WITH clause must precede theAFTER IDUC DO clause.REPLICATE ALL | (INSERTS, UPDATES, DELETES)FROM TABLE sourcetableUSING MAP mapname[FILTER WITH filter][INTO targettable][ORDER BY order, ... ][AFTER IDUC DO afteriduc] ;

Table 6. Optional replication commands

Command Description

FILTER WITH ’filter’ Filters the database rows selected for replication,where filter defines the filter that the gateway uses inthe WHERE clause of the SQL SELECT.

Filtering is positive by default, which means that onlythose events that match the filter definition arereplicated. You can use a negative filter by putting anexclamation mark (!) before the equals sign (=) in thefilter clause. For example, the following filter clausereplicates all events whose severity is not 5:

FILTER WITH ’Severity !=5’

ORDER BY ’order’ Order results by the SQL SELECT ORDER BY clause usedto get data. A potential use case might be to order byfirst occurrence, so that alerts are processed inchronological order, in which case the value specifiedfor order would be ’FirstOccurrence’.


Table 6. Optional replication commands (continued)

Command Description

AFTER IDUC DO ’afteriduc’ Updates replicated rows, where afteriduc specifieswhich field to update with what value. This uses theSQL UPDATE action to execute on rows retrieved by theSQL SELECT action used to get data, e.g. 'SentToCRM=1'.

Sending events with the Socket GatewayThe Socket Gateway implementation includes a reader thread to retrieve eventsfrom the ObjectServer and a writer thread to send events to the target consumer.The reader thread places events into an event buffer, and the writer threadretrieves events from the event buffer and forwards them to the target application.The use of an event buffer allows support for Store and Forward (SAF)functionality, acknowledgement of sending of events, and the sending of events inbatches rather than individually. The event buffer is also used where none of thesefeatures is required. In general, as events are forwarded they are deleted from theevent buffer. Exactly when an event is deleted from the event buffer depends onhow certain gateway properties are configured. Different scenarios are described insubsequent sections.

How the event buffer is implemented and configured

The buffer is implemented as one or more batch files. When all of the eventswithin a batch file have been processed (either forwarded or deemed no longerrequired), the batch file is deleted. Additionally, when the gateway is not in SAFmode, all batch files are deleted on gateway startup.

Each batch file contains one or more events of the same type (insert, update, ordelete), for the same table (alerts.status or alerts.journal). A batch file containsevents from the same IDUC cycle. Batch files are only created as required. Forexample, if within an IDUC cycle no updates for the alerts.status table are foundthen no corresponding batch file is created. Batch files are sequenced according tothe order in which events are received by the gateway from the ObjectServer,through the IDUC mechanism. The number of events that can be contained in asingle batch file is configurable and so it is possible for all of the events of aparticular type for a particular table to be held in one or more batch file.

Use the Gate.Socket.BatchSize property to determine the maximum number ofevents that form a batch file. If greater than the Gate.Socket.BatchSize property,the number of events of a particular type from a particular table are read within asingle IDUC cycle, then more than one batch file is created. If fewer events areread, then the size of the batch file is limited to the number of events read (orremaining).

Use the Gate.Socket.MaxBatchFiles property to specify the maximum number ofbatch files that the gateway can store. If the maximum number of batch files isreached then no additional batch files are created and the gateway ignoressubsequent events.

Batch files are located in the $OMNIHOME/var/gateway servername directory. Use theGate.Socket.BatchNameDescriptor property to specify the batch file name prefix.Each batch file name is suffixed with sequence number and event type. Batch filesshould not be edited or deleted manually.


Forwarding events individually or as batches

When forwarding events the gateway can operate in one of two modes: batchmode or unbatched mode. In batch mode, all of the events in a single batch file areconcatenated and forwarded in a single socket send operation. In unbatched mode,events are forwarded individually.

By default, the gateway operates in unbatched mode. To send events in batchmode, set the Gate.Socket.SendAsBatches property to TRUE. In networks that havea high latency, sending events in batches improves gateway performance.

Determining when events are deleted from batch files

When in unbatched mode events are deleted from batch files individually. When inbatch mode, a whole batch file is deleted in a single operation. The following listdescribes some of the circumstances under which events or batch files are deleted:v Events or batch files are deleted when they are successfully forwarded.v Events or batch files are deleted after the number of attempts to send them

equals the value (non-zero value) specified in theGate.Socket.RetryAttemptsDueToConnectionFailures property, where deliveryfailure occurs due to lost target connections.

v Events or batch files are deleted after the number of attempts to send themequals the value (non-zero value) specified in theGate.Socket.RetryAttemptsDueToTimeouts property, where delivery failureoccurs due to socket time-outs.

v Batch files, if they exist, are deleted on gateway startup unless theGate.Socket.SAF property is set to TRUE (so that the batch files are deleted onlyafter the events that they contain have been processed).

Acknowledging events

The Socket Gateway can be set to acknowledge events sent as a single event or anumber of events sent as a batch. When the gateway sends events as single events,the target socket server acknowledges that the event was received successfully.When the gateway sends batches of events, the target socket server acknowledgesthat the batch was successfully received. The target socket server responds to thegateway with a reply containing an acknowledgement sequence generated for eachevent. When the acknowledge events functionality is enabled it returns applicationlevel acknowledgement for receiving events, and not just TCP/IP acknowledgment.

Whether the gateway runs in unbatched or batch mode, it can be configured tohave event acknowledgements enabled to ensure that an individual event, or abatch of events, has been successfully sent to the target socket server.

To set the gateway to acknowledge events sent to the target socket server, set theGate.Socket.EnableAcks property.

Note: If the Socket Gateway does not get a timely reception of anacknowledgement as set by the Gate.Socket.RetryAttemptsDueToTimeouts andGate.Socket.Timeout properties, the gateway will close the existing connection andcreate a new one. This means that the target socket server should always belistening for another incoming connection request from the gateway. On creation ofa new connection, the acknowledgement sequence number will revert back to 0(zero). Therefore each acknowledgment sequence is only relevant to the connectionit came on.


Sending event configurations

Table 7. Sending event configurations properties. The table below describes the actions ofthe gateway when the various sending modes and acknowledgement modes are set.

Event sendingconfiguration

Eventacknowledgementconfiguration Required Target System Behaviour

Unbatched mode

Gate.Socket.SendAsBatches : FALSE

Unacknowledged mode

Gate.Socket.EnableAcks: FALSE

No target socket server acknowledgementneeds to be returned to the gateway.

The gateway reads events from the socketstream, and uses the values specified for thefollowing properties to determine eventdemarcation.

v Inserts are demarcated using the followingproperties: Gate.Socket.InsertHeader /Gate.Socket.InsertTrailer

v Updates are demarcated using thefollowing properties:Gate.Socket.UpdateHeader /Gate.Socket.UpdateTrailer

v Deletes are demarcated using the followingproperties: Gate.Socket.DeleteHeader /Gate.Socket.DeleteTrailer

Batched mode

Gate.Socket.SendAsBatches : TRUE

Unacknowledged Mode

Gate.Socket.EnableAcks: FALSE

No target socket server acknowledgementneeds to be returned to the gateway.

The gateway reads events from the socketstream, and uses the values specified for thefollowing properties to determine eventdemarcation.

v Inserts are demarcated using the followingproperties: Gate.Socket.InsertHeader /Gate.Socket.InsertTrailer

v Updates are demarcated using thefollowing properties:Gate.Socket.UpdateHeader /Gate.Socket.UpdateTrailer

v Deletes are demarcated using the followingproperties: Gate.Socket.DeleteHeader /Gate.Socket.DeleteTrailer

Unbatched mode

Gate.Socket.SendAsBatches : FALSE

Acknowledged Mode

Gate.Socket.EnableAcks: TRUE

The gateway reads the first 4 bytes of thesocket stream which is an integer value in BigEndian format and stores this value as avariable (acknowledgment_sequence). Thegateway then reads the next 4 bytes of thesocket stream which is also an integer in BigEndian format (event _length).

This integer (event _length) is the length of theevent sent over the gateway. The gatewaythen reads the number of bytes indicated bythe event length to get the event. Once thegateway successfully sends the event, thetarget socket server returns theacknowledgment_sequence to the gateway toacknowledge reception of the event.


Table 7. Sending event configurations properties (continued). The table below describesthe actions of the gateway when the various sending modes and acknowledgement modesare set.

Event sendingconfiguration

Eventacknowledgementconfiguration Required Target System Behaviour

Batched mode

Gate.Socket.SendAsBatches : TRUE

Acknowledged Mode

Gate.Socket.EnableAcks: TRUE

The gateway reads the first 4 bytes of thesocket stream which is an integer value in BigEndian format and stores this value as avariable (acknowledgment_sequence). Thegateway then reads the next 4 bytes of thesocket stream which is also an integer in BigEndian format (batch _length).

This integer (batch _length) is the length of thebatch sent over the gateway. The gatewaythen reads the number of bytes indicated bythe batch length to get the batch. Once thegateway successfully sends the batch, thetarget socket server returns theacknowledgment_sequence to the gateway toacknowledge reception of the batch.

The gateway then processes each individualevent in the batch, with each event in thebatch prefixed with another 4-byte Big Endianinteger, which specifies the length of the eventin bytes.

Metadata sent by the Socket Gateway

The following table explains the metadata sent by the gateway when the followingacknowledgement settings are configured.

The following data is sent as an integer in Big Endian format:v Batch Acknowledgementv Batch IDv Event Acknowledgementv Event ID

Table 8. Acknowledgement settings content. Use the following information to understand thedata sent by the gateway.

Ackvalue

Batchvalue

EventData Event ID Event Ack

BatchData Batch ID

BatchAck

false false Yes Yes No No No No

false true Yes Yes No Yes Yes No

true false Yes Yes Yes No No No

true true Yes Yes No Yes Yes Yes


Socket Gateway Store and ForwardBy default, a degree of store and forward functionality is always engaged, wherebyevents read from the ObjectServer are stored in batch files within the gatewayevent buffer until they can be forwarded to the target, when a socket connection isavailable.

However, also by default, on gateway startup, pre-existing batch files containingevents that have not yet been forwarded are automatically deleted. Set theGate.Socket.SAF property to TRUE to avoid deletion of batch files until the eventsthey contain have been processed. The default setting for this property is FALSE.

Running the gatewayThe Java Socket Gateway is configured using a properties file calledG_SOCKET.props. This is a text file that contains a set of properties and theircorresponding values. These properties define the operational environment of thegateway, such as connection details and the location of the other configurationfiles.

To run the Java Socket Gateway, run the following command:

$OMNIHOME/bin/nco_g_socket_java -name gateway_server_name

Where gateway_server_name is the server name of the gateway as defined in theServer Editor.

Note:

The default location for the G_SOCKET.props properties file is $OMNIHOME/etc/gateway_server_name.props. The G_SOCKET.props properties file should be copiedto the $OMNIHOME/etc folder. For details of the properties and values to which youcan set them, see “Property settings for the operational environment of thegateway” on page 8.

For details about defining the gateway server name using the Server Editor, referto the section Configuring server communication details in the Server Editor in the IBMTivoli Netcool/OMNIbus Installation and Deployment Guide.

FIPS mode and encryptionThis gateway complies with Federal Information Processing Standard 140-2 (FIPS140-2). It can be run in FIPS mode on any currently supported version of TivoliNetcool/OMNIbus.

You can use encryption algorithms to secure string value entries made in theproperties file, including passwords. You must use the generic TivoliNetcool/OMNIbus ConfigCryptoAlg property to specify the encryption methodand the generic Tivoli Netcool/OMNIbus ConfigKeyFile property to specify theencryption key file, amongst a number of other required settings.

For more information about running the gateway in FIPS mode, and encryptingproperties and passwords, see Running the ObjectServer in secure mode, Running theproxy server in secure mode, and Encrypting plain text passwords in routing definitionsin the IBM Tivoli Netcool/OMNIbus Administration Guide.


Also see, Configuring FIPS 140-2 support for the server components in the IBM TivoliNetcool/OMNIbus Installation and Deployment Guide.

Also see SSL and FIPS 140-2 support in the IBM Tivoli Netcool/OMNIbus EventIntegration Facility Reference.

Also see Appendix C. WAAPI security in the IBM Tivoli Netcool/OMNIbus Web GUIAdministration API (WAAPI) User's Guide.

Note: If you run the gateway in FIPS mode, you must either use no encryption, orif you do use encryption, you must use nco_aes_crypt with the cipher (-c) optionAES_FIPS. The cipher option used here must match the option specified by theConfigCryptoAlg property. For example:

$NCHOME/omnibus/bin/nco_aes_crypt -c AES_FIPS -k key_file string_value

Error messagesError messages provide information about problems that have occurred during theoperation of the gateway. You can use the information that they contain to resolvesuch problems.

The following table describes the error messages that the Socket Gatewaygenerates.

Table 9. Error messages

Error Description Action

Exhausted socketoperations due to timeoutsand NOT connection relatederrors. Discarding eventdata.

The gateway cannot send orreceive events becausealthough it is connected tothe target, the target isunresponsive.

This could be an indicationthat the target process isoverloaded or unresponsive.

IOException occurred, willwait for a new connection

The gateway cannot send orreceive events.

The gateway attempts toreconnect to the target usingthe reconnect function. If thegateway cannot reconnectcheck that the target isavailable.

Ensure that the valuesspecified for Gate.Socket.Hostand Gate.Socket.Port arevalid.

Check if a firewall has blockedthe gateway connection. Toensure that a firewall does nottimeout TCP connections, setthe Gate.Socket.KeepAliveproperty to TRUE.

Platform : unable to findJRE lib dir on thisplatform

The gateway does not runsuccessfully if it does nothave the minimum Java JRElibrary available.

Check the gatewaydependencies in thedescription.txt file.


Table 9. Error messages (continued)


Gate.Socket.BatchSizeneeds to be greater than150.

The gateway is running inbatch mode and requiresbigger batches to sendevents.

Increase the value specifiedfor the Gate.Socket.Batchsizeproperty.

Gate.Socket.MaxBatchFilesneeds to be greater then1.

The gateway cannot run inbatch mode if theGate.Socket.MaxBatchFilesproperty is set to 1 or less.

Set theGate.Socket.MaxBatchFiles toa value greater than 1.

Noticed a non batch filewas in the directory. Donot alter this directorybatch_file_name

The file specified in theerror message is not a batchfile but appears in the batchfile processing directory.

Remove the file from thebatch directory and ensure noother processes are writing tothat location. The following isthe default location for thebatch file.

$OMNIHOME/log/G_SOCKET.log

Received a timeout willattempt to retry thesending of the event data

The gateway cannot sendevents because theconnection to the targetsystem is not available dueto timeout.

Ensure that the target systemis available.

Ensure the correct hostname isspecified in theGate.Socket.Host property.

Check if a firewall has blockedthe gateway connection. Toensure that a firewall does nottimeout TCP connections, setthe Gate.Socket.KeepAliveproperty to TRUE.

Rejected too manyoutstanding batch filesneed to be processeddiscarding batchevents!!!!

The gateway has receivedmore events than it canhandle during an IDUCflush.

When this happens thegateway disregards eventsthat occur after maximumstorage has been reached.

To prevent this you can eitherincrease the size of each batchor increase the number ofbatch files the gateway storesbefore sending to the socket.

Check the values set for thefollowing properties.

v Gate.Socket.BatchSize

v Gate.Socket.MaxBatchFiles

Re-run the gatewayincreasing the value forthe propertyGate.Socket.MaxBatchFiles

The gateway puts an upperlimit on the maximum batchfiles to prevent the diskquota from being exhausted.

If the maximum batch filelimit is being exceededbecause of a slow processingtarget socket server, you canuse one of the followingsolutions.

v Delete the batch files in$OMNIHOME/var/gateway_name. (The defaultvalue is G_SOCKET.)

v Increase the value for theGate.Socket.MaxBatchFilesproperty.


Table 9. Error messages (continued)


Unable to remove log file The gateway cannot removethe log file.

Contact IBM software support.

Known issuesThis section describes some known issues with the Java Socket Gateway.

DNS cache poisoning

If DNS failover is used for the socket server target hostname, the gateway bydefault does not do a lookup on the DNS in the case of an unavailable socketserver.

The gateway JRE caches the original IP address to prevent DNS cache poisoning.

If you think your environment is safe from cache poisoning then you can set thefollowing value for the Gate.Java.Arguments property:’-Dsun.net.inetaddr.ttl=<integer_value>’

Out Of Memory exceptions and cores

The gateway generates Out Of Memory exceptions and cores if the gateway does nothave enough memory to complete the operations requested of it.

To solve this problem increase the maximum memory by setting the propertyGate.Java.Arguments:’-Xmx<Memory_size_in_megabytes>m’ .

Note: The maximum value for this property is 2 GB.

Re-run the gateway increasing the value for the propertyGate.Socket.MaxBatchFiles error message.

If the gateway fails to startup, and logs the following error message: Re-run thegateway increasing the value for the property Gate.Socket.MaxBatchFiles, it isbecause the gateway puts an upper limit on the maximum batch files to preventthe disk quota from being exhausted.

If the maximum batch file limit is being exceeded because of a slow processingtarget socket server, you can use one of the following solutions:v Delete the batch files in $OMNIHOME/var/gateway_name. (The default value is

G_SOCKET.)v Increase the value for the Gate.Socket.MaxBatchFiles property.


Appendix. Notices and Trademarks

This appendix contains the following sections:v Noticesv Trademarks

NoticesThis information was developed for products and services offered in the U.S.A.

IBM® may not offer the products, services, or features discussed in this documentin other countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing 2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

© Copyright IBM Corp. 2013, 2015 27

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who want to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM CorporationSoftware Interoperability Coordinator, Department 49XA3605 Highway 52 NRochester, MN 55901U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this information and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.


COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

TrademarksIBM, the IBM logo, ibm.com, AIX, Tivoli®, zSeries, and Netcool® are trademarks ofInternational Business Machines Corporation in the United States, other countries,or both.

Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-basedtrademarks are either registered trademarks or trademarks of Adobe SystemsIncorporated in the United States, other countries, or both.

Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporationin the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Appendix. Notices and Trademarks 29


IBM®

Printed in USA

SC27-5681-02

Documents

IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide · 2020-07-23 · IBM T ivoli Netcool/OMNIbus Java Socket Gateway The Java Socket Gateway can r ead events fr om any ObjectServer