IBM Tivoli Netcool/OMNIbus Socket Gateway Version 2.0. Reference Guide. August 6, 2015 IBM SC

Transcription

1 IBM Tivoli Netcool/OMNIbus Socket Gateway Version 2.0 Reference Guide August 6, 2015 IBM SC

2

3 IBM Tivoli Netcool/OMNIbus Socket Gateway Version 2.0 Reference Guide August 6, 2015 IBM SC

4 Notice Before using this information and the product it supports, read the information in Notices and Trademarks, on page 29. Edition notice This edition (SC ) applies to version 2.0 of IBM Tivoli Netcool/OMNIbus Socket Gateway, and to all subsequent releases and modifications until otherwise indicated in new editions. This version replaces SC Copyright IBM Corporation 2013, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this guide v Document control page v Conventions used in this guide vi IBM Tivoli Netcool/OMNIbus Socket Gateway Summary of the Socket Gateway Installing the gateway Installing probes and gateways on Tivoli Netcool/OMNIbus V Installing the gateway on Tivoli Netcool/OMNIbus V Using the Socket Gateway Features of the Socket Gateway Configuring communication details Configuring the gateway Properties file Map definition file Startup command file AfterIDUC and Filter functions Table replication definition file Sending events with the Socket Gateway Socket Gateway Store and Forward Running the gateway FIPS mode and encryption Error messages Known issues Appendix. Notices and Trademarks.. 29 Notices Trademarks Copyright IBM Corp. 2013, 2015 iii

6 iv IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

7 About this guide Document control page The following sections contain important information about using this guide. The IBM Tivoli Netcool/OMNIbus Socket Gateway documentation is provided in softcopy format only. To obtain the most recent version, visit the IBM Tivoli Netcool/OMNIbus Knowledge Center: kc_welcome-444.html?lang=en Table 1. Document modification history Document version Publication date Comments SC July 5, 2013 First IBM publication. SC September 30, 2013 Map definition file on page 17 updated. Sending events with the Socket Gateway on page 20 updated. SC August 6, 2015 Changed the name of the gateway from Java Gateway for Socket to IBM Tivoli Netcool/OMNIbus Socket Gateway (Socket Gateway). IBM Tivoli Netcool/OMNIbus Socket Gateway, on page 1 updated. Summary of the Socket Gateway on page 1 updated. Features of the Socket Gateway on page 6 updated. 64 bit support added Configuring communication details on page 7 updated. Copyright IBM Corp. 2013, 2015 v

8 Table 1. Document modification history (continued) Document version Publication date Comments SC August 6, 2015 Configuring the gateway on page 8 updated. The following new property was added: Gate.Socket.Shutdown OnConnectionError. Updates were made to the following properties: Gate.Socket.BatchSize, Gate.Socket.RetryAttempts DueToConnectionFailures, Gate.Socket.RetryAttempts DueToTimeouts, and Gate.Socket.Timeout. Sending events with the Socket Gateway on page 20 updated. Socket Gateway Store and Forward on page 25 updated. Conventions used in this guide All gateway guides use standard conventions for operating system-dependent environment variables and directory paths. Operating system-dependent variables and paths All gateway guides use standard conventions for specifying environment variables and describing directory paths, depending on what operating systems the gateway is supported on. For gateways supported on UNIX and Linux operating systems, gateway guides use the standard UNIX conventions such as $variable for environment variables and forward slashes (/) in directory paths. For example: $OMNIHOME/gates For gateways supported only on Windows operating systems, gateway guides use the standard Windows conventions such as %variable% for environment variables and 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 environment variables and describing directory paths. When using the Windows command line with these gateways, replace the UNIX conventions used in the guide with Windows conventions. If you are using the bash shell on a Windows system, you can use the UNIX conventions. Note: The names of environment variables are not always the same in Windows and UNIX environments. For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX and Linux environments. vi IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

9 Operating system-specific directory names Where Tivoli Netcool/OMNIbus files are identified as located within an arch directory under NCHOME or OMNIHOME, arch is a variable that represents your operating 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 the table. Table 2. Directory names for the arch variable Operating system AIX systems Red Hat Linux and SUSE systems Linux for System z Solaris systems Windows systems Directory name represented by arch aix5 linux2x86 linux2s390 solaris2 win32 OMNIHOME location Gateways and older versions of Tivoli Netcool/OMNIbus use the OMNIHOME environment variable in many configuration files. Set the value of OMNIHOME as follows: v On UNIX and Linux, set $OMNIHOME to $NCHOME/omnibus. v On Windows, set %OMNIHOME% to %NCHOME%\omnibus. About this guide vii

10 viii IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

11 IBM Tivoli Netcool/OMNIbus Socket Gateway The Socket Gateway can read events from any ObjectServer table and forward them to a socket using a TCP connection. Typically, the gateway reads the alerts.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 20, the gateway processes Insert, 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 occur periodically and the cycle intervals can be configured using the Gate.RdrWtr.IducFlushRate property. 2. Each instance of an Insert and Update is mapped into a pair of name value pairs, as defined by the gateway mapper file. For more information, see Map definition file on page 17. 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 Socket Gateway v Installing the gateway on page 2 v Using the Socket Gateway on page 6 v Configuring the gateway on page 8 v Error messages on page 26 Summary of the Socket Gateway Each gateway works in a different way to provide an interface with the ObjectServer. Use this summary information to learn about the Socket Gateway. The following table provides a summary of the gateway: Table 3. Summary Gateway target Gateway executable file name Package Version 2.0 Gateway supported on TCP Socket nco_g_socket_java For details of supported operating systems, see the following Release Notice on the IBM Software Support website: docview.wss?uid=swg Copyright IBM Corp. 2013,

12 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 Requirements $OMNIHOME/gates/socket_java/socket_java.startup.cmd A currently supported version of IBM Tivoli Netcool/OMNIbus. NSocket library files (for IPv6 support) gateway-libgwutility-2 version 2 or above. Remote Connectivity Failover/failback functionality Multicultural support IP environment Federal Information Processing Standards (FIPS) gateway-libngjava-7 or above. Available Available For details of configuring failover/failback, see Failover and Failback on page 6. Available IPv4 and IPv6 IBM Tivoli Netcool/OMNIbus uses the FIPS approved cryptographic provider: IBM Crypto for C (ICC) certificate 384 for cryptography. This certificate is listed on the NIST website at cmvp/documents/140-1/1401val2004.htm. For details about configuring Netcool/OMNIbus for FIPS mode, see the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide. Installing the gateway There are separate procedures for installing the gateway on each version of Tivoli Netcool/OMNIbus. Follow the procedure for the version of Tivoli Netcool/OMNIbus that your site uses. Installing probes and gateways on Tivoli Netcool/OMNIbus V8.1 From Tivoli Netcool/OMNIbus V8.1 onwards, Tivoli Netcool/OMNIbus probes and gateways can be installed using the IBM Installation Manager. One of the key features of Installation Manager is that all platforms are shipped in a single ZIP file, 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 configured Installation Manager and Tivoli Netcool/OMNIbus. To install probes and gateways, you must make sure that the Core Tivoli Netcool/OMNIbus features Probe Support and Gateway Support respectively are installed. 2 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

13 Installing probes and gateways using the Command Line Tool To install the probe or gateway using the Command Line Tool, run the following command: installation_manager_location/eclipse/tools/imcl -c install com.ibm.tivoli.omnibus.integrations.integration_name -repositories repository_containing_required_integration -installationdirectory location_of_netcool_omnibus_install_you_are_installing_into Where integration_name specifies the name of the probe or gateway that you want to install. You will be prompted to agree to the terms and conditions of the license as a prerequisite for installing the integration. If you have already reviewed the license and want to skip the manual acceptance, add the -acceptlicense option to the install 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 unzipped contents of the SNMP Probe Installation Manager package. Note: The command line tool does not add the repository permanently to the Installation Manager instance. If you subsequently start the Installation Manager GUI, 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 the following command: installation_manager_location/eclipse/tools/imcl uninstall com.ibm.tivoli.omnibus.integrations.integration_name -installationdirectory location_of_netcool_omnibus_install_you_are_uninstalling_from Where integration_name specifies the name of the probe or gateway that you want to 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 the IM package. 2. Start Installation Manager using the following command: IBM Tivoli Netcool/OMNIbus Socket Gateway 3

14 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 the repository that contains the unzipped IM package that contains the probe or gateway. 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.0 For Tivoli Netcool/OMNIbus V7.4.0, all gateways are installed using the Tivoli Netcool/OMNIbus installer. You can install the gateway using any of the following: v The installation wizard on page 5 v 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. The archive management application that you use to extract the files must be able to preserve 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 or Linux operating system, you will need to install additional, 32-bit operating system libraries. See the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide for more information. 4 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

15 Obtaining the installation package To obtain the installation package and prepare it for installation use the following steps: 1. Download the installation package for the gateway from the Passport Advantage Online Web site: 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, the gateway is installed in the following directory: $NCHOME/omnibus/gates The installation wizard To 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 contains the README.txt file as the location of the gateway installation files. 3. Accept the license conditions. Console mode To 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 contains the README.txt file as the location of the gateway installation files. 3. Accept the license conditions. Silent mode To install the gateway in silent mode: 1. Create a text file named reponse.txt and add the following entries: PROBE_OR_GATE_LOCATION=README_directorypath LICENSE_ACCEPTED=true where README_directorypath is the path to the directory containing the README.txt file in the extracted package. 2. Run the installer for your operating system: $NCHOME/omnibus/install/nco_install_integration -i silent -f response_path/response.txt where response_path is the full path to the response.txt file. IBM Tivoli Netcool/OMNIbus Socket Gateway 5

16 Using the Socket Gateway The Socket Gateway connects to the configured socket and forwards events from the ObjectServer to a local or a remote socket over TCP. Features of the Socket Gateway The Socket Gateway has various features that enable you to create an interface between the socket and the ObjectServer. Centralized property management The gateway uses centralized property management and separates properties from data processing configuration. To configure the common gateway properties and the Socket Gateway properties, use the G_SOCKET.props properties file. To configure data processing, use the table replication definition file and the mapping file. To specify a set of commands that the gateway performs automatically each time it starts, 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 gateway sends header and trailer information with the changed alerts to the socket. Using the properties file, you can define the format in which the gateway adds the header 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 the destination socket. Details of the tables to be replicated are stored in the table replication definition file. Use the Gate.RdrWtr.TblReplicateDefFile property to specify the location of the table replication definition file. Mapping table data The gateway writes the alerts received from the various tables in the ObjectServer onto the socket in a format defined by the map definition file. To specify the map definition file, use the Gate.MapFile property. Failover and Failback Failover functionality comes into operation when the gateway loses its connection to the primary ObjectServer. When the primary ObjectServer fails, the reader connects to the backup ObjectServer as configured using the Tivoli 6 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

17 Netcool/OMNIbus Server Editor (nco_xigen). To specify that the gateway fails back to the primary ObjectServer, set the Gate.RdrWtr.FailbackEnabled property to TRUE. When the reader has detected that it is now connected to a backup ObjectServer, it periodically polls for the return of the primary ObjectServer at the frequency specified by the Gate.RdrWtr.FailbackTimeout property. When the primary ObjectServer is detected again, the reader automatically fails back to the primary ObjectServer. 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 indicates whether the gateway is PA aware. The Gate.PAAwareName property indicates which PA is running the gateway. Important: These properties are maintained automatically by the PA server and provide information only. Do not change these properties manually. Error handling You can troubleshoot problems with the gateway by consulting error messages. To help 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 the Gate.NGtkDebug property to TRUE. Configuring communication details To enable communication between the gateway and the ObjectServer, you must configure communication details for the ObjectServer and the gateway using the Tivoli Netcool/OMNIbus Server Editor (nco_xigen) and create an entry for the ObjectServer in the interfaces file ($NCHOME/etc/omni.dat). Note: If the ObjectServer is already configured and the gateway is to run from the same installation, you do not need to configure communication details for the ObjectServer. On UNIX and Linux operating systems, use the following command to start the Server Editor: $NCHOME/omnibus/bin/nco_xigen On Windows operating systems, use the following command to start the Server Editor: Start > Programs > NETCOOL Suite > System Utilities > Servers Editor You must also add a gateway server entry to the interfaces file. You can do this using the Server Editor. Alternatively, on Unix and Linux operating systems you can edit the interfaces file and regenerate it using the nco_igen utility. The default gateway server name is G_SOCKET, which corresponds to the value specified for the Name property defined in the G_SOCKET.props properties file. IBM Tivoli Netcool/OMNIbus Socket Gateway 7

18 Configuring the gateway If there is a firewall between the gateway and the ObjectServer, configure the ObjectServer to use a fixed port for IDUC and ensure that both the main ObjectServer port and the IDUC port are opened in the firewall. By default, the ObjectServer uses a random IDUC port. For more information about using the Server Editor and the interfaces file, see the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide. The Socket Gateway is configured using a set of configuration files. Use the Tivoli Netcool/OMNIbus Server Editor (nco_xigen) to specify the host name and port number of the gateway host in the Tivoli Netcool/OMNIbus interfaces file. Note: For information about using the Server Editor, see IBM Tivoli Netcool/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, and G_SOCKET.props is the default name for its properties file. You can specify an alternative properties file using the -propsfile command-line option when you run 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 are also 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 on page 9 v Map definition file on page 17 v Startup command file on page 18 v AfterIDUC and Filter functions on page 18 v Table replication definition file on page 19 v Sending events with the Socket Gateway on page 20 8 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

19 Properties file The properties file is a text file that contains a set of properties and their corresponding values. These properties define the operational environment of the gateway, such as connection details and the location of the other configuration files. The default properties file for the Socket Gateway is G_SOCKET.props and it is installed in the following location: v $OMNIHOME/gates/socket_java Property settings for the operational environment of the gateway You use properties to define the operational environment of the gateway. You can override the default values by using the properties file. The following table describes the properties defined in the G_SOCKET.props properties file that are most frequently used to configure the Socket Gateway. For more information about generic properties and command line options, and Interprocess Communication (IPC) properties, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide. Table 4. Properties file Property name Command line option Description Gate.MapFile string -mapfile string Use this property to specify the mapping file for the gateway to use. The default is $OMNIHOME/gates/socket_java/ socket_java.map. Gate.G_SOCKET.Debug boolean Gate.G_SOCKET.Failback Enabled boolean Gate.G_SOCKET.Failback Timeout integer -g_socketdebug TRUE FALSE -g_socketfailbackenabled TRUE FALSE g_socketfailbacktimeout integer Use this property to enable the gateway reader/writer debug messages. The default is TRUE. (Debug messages are enabled.) Use this property to specify whether the gateway fails back to the backup ObjectServer when disconnected from the primary ObjectServer. The default is FALSE. Use this property to specify the frequency (in seconds) with which the gateway attempts to fail back to the primary system following a system failover. The default is 30 seconds. IBM Tivoli Netcool/OMNIbus Socket Gateway 9

20 Table 4. Properties file (continued) Property name Command line option Description Gate.RdrWtr.IducFlushRate integer -rdrwtriducflushrate integer Use this property to specify the rate (in seconds) of the granularity of the reader. If you set this property to 0 (zero), the reader gets its updates at the same granular rate as that of the ObjectServer to which it is connected. The default is 0 seconds. Gate.RdrWtr.TblReplicate DefFile string Gate.Socket.BatchName Descriptor string -rdrwtrtblrepdeffile string -batchnamedescriptor string Note: If you set this property to a value greater than 0 seconds, the reader issues automatic IDUC flush requests to the ObjectServer with this frequency. This enables the reader to run at a faster granularity than that of the ObjectServer, thus enabling the gateway to capture more detailed event changes in systems where the ObjectServer itself has high granularity settings. Use this property to specify the location and name of the table replication definition file. The default location and name are as follows: $OMNIHOME/gates/socket_java/ socket_java.rdrwtr.tblrep. def Use this property when processing batch files. The gateway creates a batch file name with the string that you specify in this property. To generate unique names for each batch file, the gateway appends the batch sequence number and event type contained within the batch file. The default name is gw_socket.log. 10 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

21 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.BatchSize integer -batchsize integer Use this property to specify the maximum number of events written to an individual batch file. If the Gate.Socket.SendAsBatches property is set to TRUE, the Gate.Socket.BatchSize property determines the maximum number of events that the gateway sends to a target system in a single batch. Gate.Socket.DateFormat string Gate.Socket.DeleteHeader string Gate.Socket.DeleteTrailer string Gate.Socket.DoTimestamp boolean -dateformat string -deleteheader string -deletetrailer string -dotimestamp TRUE FALSE The default minimum value is 150 events. Use this property to specify the date format that the gateway uses for any date fields written to the socket. The default is yyyy-mm-dd\'t\'hh:mm:ssz. Use this property to specify the format of the header added to the start of each delete alert written to the socket. The default is 'DELETE' Use this property to specify the format of the trailer added to the end of each delete alert written to the socket. The default is '\n'. Use this property to specify whether the gateway prefixes each event with the date and time of its arrival. The default is FALSE (the gateway does not prefix each event with the date and time of its arrival). IBM Tivoli Netcool/OMNIbus Socket Gateway 11

22 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.EnableAcks boolean -acks : Set to TRUE or FALSE to enable or disable application level acknowledgments. -enableacks : Sets the value to TRUE to enable message or batch acknowledgements. Use this property to enable message or batch acknowledgements and application level acknowledgements. The default is FALSE (the gateway disables message or batch acknowledgements). Gate.Socket.EndString string -disableacks : Sets the value to FALSE to disable message or batch acknowledgements. -endstring string Use this property to specify the value to be added at the end of each string to be written to the socket. The default is '"'. Gate.Socket.Host string -host string Use this property to specify the name of the host to which the TCP connection is made. Gate.Socket.InsertHeader string Gate.Socket.InsertTrailer string -insertheader string -inserttrailer string The default is localhost. Use this property to specify the format of the header added to the start of each insert alert written to the socket. The default is 'INSERT'. Note: Although the command line option is available to set the value for this property, it is recommended that you set the value of this property in the G_SOCKET.props properties file. Use this property to specify the format of the trailer added to the end of each insert alert written to the socket. The default is '\n'. Note: Although the command line option is available to set the value for this property, it is recommended that you set the value of this property in the G_SOCKET.props properties file. 12 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

23 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.KeepAlive string -keepalive string Use this property to specify whether the gateway keeps TCP sockets open when not in use. The default is FALSE (the gateway does not keep TCP sockets open when not in use). Gate.Socket.MaxBatchFiles integer -maxbatchfiles integer Important: To ensure that a firewall does not timeout TCP connections, you must set the value to TRUE. Use this property to specify the maximum number of batch files the gateway stores. If the number of events that the gateway can store exceeds the capacity before they are sent to a socket using a TCP connection, the gateway will ignore subsequent events (that is, the gateway creates no additional batch files). The default is 1000 batch files. Gate.Socket.Port integer -port integer Use this property to specify the TCP port to which the gateway connects. Gate.Socket.ReconnectTime out integer Gate.Socket.RetryAttempts DueToConnectionFailures integer -reconnecttimeout integer -retryattempts_connectio nfailure integer The default is Use this property to specify the time (in seconds) the gateway waits before trying to reconnect to the socket after a connection failure. The default is 15 seconds. Use this property to specify how many times the gateway tries to send an event or batch file when there is a socket connection failure. For example, if set to 1, the event or batch file will be dropped if a connection failure occurs after the first attempt to send it. The default is 0 (the gateway does not stop trying to send an event or batch file when there is a socket connection failure). IBM Tivoli Netcool/OMNIbus Socket Gateway 13

24 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.RetryAttempts DueToTimeouts integer -retryattempts_timeouts integer Use this property to specify how many times the gateway tries to send an event when the socket operation times out. Gate.Socket.SAF boolean Gate.Socket.SendAsBatches boolean -socketsaf : Set to TRUE or FALSE to enable or disable the store and forward feature. -safenabled : This sets the property to TRUE (store and forward feature is enabled). -safdisabled : This sets the property to FALSE (store and forward feature is disabled). -sendasbatches : This sets the property to TRUE. -sendsingleevents : This sets the property to FALSE. The default is 5 (that is, the gateway drops the event after trying to send it five times). Use this property to specify whether the gateway uses the store and forward feature. The default is FALSE (the store and forward feature is not enabled). For more information on the store and forward feature, see Socket Gateway Store and Forward on page 25. Use this property to specify whether the gateway sends events to the target device in batches or as single events. The default is FALSE (the gateway sends events to the target device as single events). Gate.Socket.Separator string -separator string Note: You should never alter a batch file. Batch files are internally generated by the gateway and altering them can cause major issues. Use this property to specify the character to be inserted between the fields written to the socket. The default is ';' (semicolon). 14 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

25 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.Shutdown OnConnectionError boolean -shutdownon connection error: Set to TRUE or FALSE to cause the gateway to shutdown or not shutdown upon encountering a socket connection error. Use this property to cause the gateway to shutdown upon encountering a socket connection error. The default is FALSE (the gateway does not shutdown on encountering a socket connection error). Gate.Socket.StartString string -startstring string Note: It is expected that the Gate.Socket.SAF property would be set to FALSE whenever this property is set to TRUE. On shutdown one or more unprocessed events may remain in the batch files and these would be deleted automatically on the next gateway startup, provided SAF is disabled. Use this property to specify the value to be added at the start of each string to be written to the socket. The default is '"'. Gate.Socket.Timeout integer -timeout integer Use this property to specify the period (in seconds) that the gateway waits for data to be sent over the socket connection. Gate.Socket.UpdateHeader string -updateheader string The default is 15 seconds. Use this property to specify the value to be added to the start of each update alert written to the socket. The default is 'UPDATE'. Note: Although the command line option is available to set the value for this property, it is recommended that you set the value of this property in the G_SOCKET.props properties file. IBM Tivoli Netcool/OMNIbus Socket Gateway 15

26 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.UpdateTrailer string -updatetrailer string Use this property to specify the value to be added to the end of each update alert written to the socket. The default is '\n'. Note: Although the command line option is available to set the value for this property, it is recommended that you set the value of this property in the G_SOCKET.props properties file. Java properties The following table describes the available Java properties. Table 5. Java properties Property name Command line option Description Gate.Java.Arguments string -javaargs string Use this property to specify the arguments to use when starting Java. The default is "". Gate.Java.ClassPath string -javacpath string Use this property to specify the environment variable used to store the location of the Java libraries. The default is the value of the $CLASSPATH environment variable on the machine. Gate.Java.Debug boolean -javadebug boolean Use this property to enable the logging of Java debug messages. The default is TRUE (enable the logging of Java debug messages). Gate.Java.LibraryPath string -javalibpath string Use this property to specify the location of the Java libraries that will be set in the environment variable specified by the Gate.Java.ClassPath property. 16 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

27 Map definition file The Socket Gateway writes the alerts received from the various tables in the ObjectServer onto the socket in a format defined by the map definition file. The default map definition file, socket_java.map, is installed in the following location: v $OMNIHOME/gates/socket_java Gateway mapper attributes You can configure the mapping functions of the gateway by using the mapper attributes. Syntax Mappings for use with the Socket Gateway must use the following syntax: CREATE MAPPING mappingname ( [ON INSERT ONLY], [ [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 of the alert. When omitted, the field is updated for any change in the state of the alert. 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 file using the following example. = Identifier : = 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 Probe and Gateway Guide. IBM Tivoli Netcool/OMNIbus Socket Gateway 17

28 Startup command file The startup command file contains a set of commands that the gateway executes each time it starts. You can specify the location of the startup command file using the generic Netcool/OMNIbus Gate.StartupCmdFile property. The default startup command file for the gateway is socket_java.startup.cmd and is located in the following directory: $OMNIHOME/gates/socket_java The default startup command file contains example commands. You should make a copy 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 in property_name in the gateway properties file. v SET LOG LEVEL TO - Use this command to set the level of message logging for the gateway. 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 Tivoli Netcool/OMNIbus Administration Guide. For more information about the startup command file, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide. AfterIDUC and Filter functions The Socket Gateway implements the AfterIDUC and filter functions using the table replication definition file called socket_java.rdrwtr.tblrep.def. You specify the location and name of the table replication definition file in the Gate.RdrWtr.TblReplicateDefFile property. Use the AFTER IDUC DO command to update replicated rows. In the following example, the AFTER IDUC DO clause instructs the gateway to set the Archived column 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 target system. In the following example, the FILTER WITH clause instructs the gateway to only replicate alerts that originate from the NCOMS_US and NCOMS_CA ObjectServers: REPLICATE ALL FROM TABLE alerts.status USING MAP StatusMap FILTER WITH ServerName IN (\ NCOMS_US\,\ NCOMS_CA\ ) ; 18 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

29 Note: You must use backslash characters (\) to escape the quote characters ( ) in the query string. An important consideration when filtering replicated data is that the filter should match a characteristic of the alerts that does not change over time. This can be the alert source, as in the example above. You could also use the Class and Manager elements of alerts as a filter. Elements of alerts such as Severity make for bad filter criteria because they can change over the lifecycle of an alert. Table replication definition file The gateway replicates data between ObjectServer tables and the gateway target. The table replication definition file is used to define which tables and event types are monitored in Tivoli Netcool/OMNIbus and forwarded to the target that the gateway is configured to send data to. You specify the location and name of the table replication definition file using the generic Tivoli Netcool/OMNIbus Gate.RdrWtr.TblReplicateDefFile property. The default table replication file for the gateway is socket_java.rdrwtr.tblrep.def and is located in the following directory: $OMNIHOME/gates/socket_java The default table replication definition file contains example commands. You should make a backup copy of the default file for future reference. Note: You should use the REPLICATE command to replicate data from the primary tables (alerts.status, alerts.journal, alerts.details) and dynamic secondary tables (if required). You can add one or more optional clauses to the REPLICATE command to further process the data during replication. The available commands are listed in the following syntax example. Use the optional clauses in the order in which they are listed in the syntax. For example, when using both the FILTER WITH and AFTER IDUC DO clauses, the FILTER WITH clause must precede the AFTER IDUC DO clause. REPLICATE ALL (INSERTS, UPDATES, DELETES) FROM TABLE sourcetable USING MAP mapname [FILTER WITH filter] [INTO targettable] [ORDER BY order,... ] [AFTER IDUC DO afteriduc] ; IBM Tivoli Netcool/OMNIbus Socket Gateway 19

30 Table 6. Optional replication commands Command FILTER WITH filter Description Filters the database rows selected for replication, where filter defines the filter that the gateway uses in the WHERE clause of the SQL SELECT. Filtering is positive by default, which means that only those events that match the filter definition are replicated. You can use a negative filter by putting an exclamation mark (!) before the equals sign (=) in the filter clause. For example, the following filter clause replicates all events whose severity is not 5: ORDER BY order AFTER IDUC DO afteriduc FILTER WITH Severity!=5 Order results by the SQL SELECT ORDER BY clause used to get data. A potential use case might be to order by first occurrence, so that alerts are processed in chronological order, in which case the value specified for order would be FirstOccurrence. Updates replicated rows, where afteriduc specifies which field to update with what value. This uses the SQL UPDATE action to execute on rows retrieved by the SQL SELECT action used to get data, e.g. 'SentToCRM=1'. Sending events with the Socket Gateway The Socket Gateway implementation includes a reader thread to retrieve events from 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 thread retrieves 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 in batches rather than individually. The event buffer is also used where none of these features is required. In general, as events are forwarded they are deleted from the event buffer. Exactly when an event is deleted from the event buffer depends on how certain gateway properties are configured. Different scenarios are described in subsequent sections. How the event buffer is implemented and configured The buffer is implemented as one or more batch files. When all of the events within a batch file have been processed (either forwarded or deemed no longer required), the batch file is deleted. Additionally, when the gateway is not in SAF mode, all batch files are deleted on gateway startup. Each batch file contains one or more events of the same type (insert, update, or delete), for the same table (alerts.status or alerts.journal). A batch file contains events from the same IDUC cycle. Batch files are only created as required. For example, if within an IDUC cycle no updates for the alerts.status table are found then no corresponding batch file is created. Batch files are sequenced according to the 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 a single batch file is configurable and so it is possible for all of the events of a particular type for a particular table to be held in one or more batch file. 20 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide

31 Use the Gate.Socket.BatchSize property to determine the maximum number of events 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 a single IDUC cycle, then more than one batch file is created. If fewer events are read, then the size of the batch file is limited to the number of events read (or remaining). Use the Gate.Socket.MaxBatchFiles property to specify the maximum number of batch files that the gateway can store. If the maximum number of batch files is reached then no additional batch files are created and the gateway ignores subsequent events. Batch files are located in the $OMNIHOME/var/gateway servername directory. Use the Gate.Socket.BatchNameDescriptor property to specify the batch file name prefix. Each batch file name is suffixed with sequence number and event type. Batch files should not be edited or deleted manually. Forwarding events individually or as batches When forwarding events the gateway can operate in one of two modes: batch mode or unbatched mode. In batch mode, all of the events in a single batch file are concatenated 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 batch mode, set the Gate.Socket.SendAsBatches property to TRUE. In networks that have a 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 in batch mode, a whole batch file is deleted in a single operation. The following list describes 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 the Gate.Socket.RetryAttemptsDueToConnectionFailures property, where delivery failure occurs due to lost target connections. v Events or batch files are deleted after the number of attempts to send them equals the value (non-zero value) specified in the Gate.Socket.RetryAttemptsDueToTimeouts property, where delivery failure occurs due to socket time-outs. v Batch files, if they exist, are deleted on gateway startup unless the Gate.Socket.SAF property is set to TRUE (so that the batch files are deleted only after 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 a number 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 acknowledges that the batch was successfully received. The target socket server responds to the gateway with a reply containing an acknowledgement sequence generated for each IBM Tivoli Netcool/OMNIbus Socket Gateway 21

32 event. When the acknowledge events functionality is enabled it returns application level acknowledgement for receiving events, and not just TCP/IP acknowledgment. Whether the gateway runs in unbatched or batch mode, it can be configured to have event acknowledgements enabled to ensure that an individual event, or a batch 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 the Gate.Socket.EnableAcks property. Note: If the Socket Gateway does not get a timely reception of an acknowledgement as set by the Gate.Socket.RetryAttemptsDueToTimeouts and Gate.Socket.Timeout properties, the gateway will close the existing connection and create a new one. This means that the target socket server should always be listening for another incoming connection request from the gateway. On creation of a new connection, the acknowledgement sequence number will revert back to 0 (zero). Therefore each acknowledgment sequence is only relevant to the connection it came on. Sending event configurations Table 7. Sending event configurations properties. The table below describes the actions of the gateway when the various sending modes and acknowledgement modes are set. Event sending configuration Unbatched mode Gate.Socket.Send AsBatches : FALSE Event acknowledgement configuration Unacknowledged mode Gate.Socket.EnableAcks : FALSE Required Target System Behaviour No target socket server acknowledgement needs to be returned to the gateway. The gateway reads events from the socket stream, and uses the values specified for the following properties to determine event demarcation. v v v Inserts are demarcated using the following properties: Gate.Socket.InsertHeader / Gate.Socket.InsertTrailer Updates are demarcated using the following properties: Gate.Socket.UpdateHeader / Gate.Socket.UpdateTrailer Deletes are demarcated using the following properties: Gate.Socket.DeleteHeader / Gate.Socket.DeleteTrailer 22 IBM Tivoli Netcool/OMNIbus Socket Gateway: Reference Guide