IBM Tivoli Netcool/OMNIbus Socket Writer Gateway Version Reference Guide. November 30, 2012 SC

Transcription

1 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway Version 10.0 Reference Guide November 30, 2012 SC

2

3 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway Version 10.0 Reference Guide November 30, 2012 SC

4 Notice Before using this information and the product it supports, read the information in Notices and Trademarks, on page 17. Edition notice This edition (SC ) applies to version 10.0 of IBM Tivoli Netcool/OMNIbus Socket Writer Gateway, and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SC Copyright IBM Corporation 2006, 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 Writer Gateway Summary of the Socket Writer Gateway Installing the gateway Installing the gateway on Tivoli Netcool/OMNIbus V7.3.0 or later Installing the gateway on Tivoli Netcool/OMNIbus V Using the Socket Writer Gateway Features of the Socket Writer Gateway Connecting to an ObjectServer running in secure mode Configuring the gateway Properties file Map definition file Startup command file Table definition replication file Running the gateway Error messages Appendix. Notices and Trademarks.. 17 Notices Trademarks Copyright IBM Corp. 2006, 2012 iii

6 iv IBM Tivoli Netcool/OMNIbus Socket Writer 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 Writer Gateway documentation is provided in softcopy format only. To obtain the most recent version, visit the IBM Tivoli Netcool Information Center: com.ibm.tivoli.namomnibus.doc/welcome_ptsm.htm Table 1. Document modification history Document version Publication date Comments SC April 13, 2007 First IBM publication. SC March 28, 2008 Summary section updated. Running the ObjectServer in secure mode section added. Example socket writer configuration section updated. SC August 22, 2008 Support for Linux for zseries added. SC December 19, 2008 Guide rewritten to reflect updated gateway architecture. SC October 31, 2009 Guide updated to describe running the gateway in UTF-8 mode on Windows. Summary section updated. Property settings for the operational environment of the gateway on page 8 updated. Description for the -utf8enabled command line option added. Copyright IBM Corp. 2006, 2012 v

8 Table 1. Document modification history (continued) Document version Publication date Comments SC July 1, 2011 Running the gateway in UTF-8 mode on Windows information removed. The following properties were added to: Property settings for the operational environment of the gateway on page 8: v Gate.PAAware v Gate.PAAwareName v Gate.Socket.Reconnect Timeout v Gate.Transfer.Failover SyncRate SC July 6, 2012 Summary table updated. Changes made to enable you configure the gateway to meet the Common Criteria assurance level of EAL4+. SC November 30, 2012 Guide updated for Netcool/OMNIbus V7.4 release. Installing the gateway on page 2 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 vi IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

9 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. 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/gates/arch/ The following table lists the directory names used for each supported operating system. Table 2. Directory names for the arch variable Operating system AIX systems HP-UX PA-RISC-based systems HP-UX Integrity-based systems Red Hat Linux and SUSE systems Linux for System z Solaris systems Windows systems Directory name represented by arch aix5 hpux11 hpux11hpia linux2x86 linux2s390 solaris2 win32 About this guide vii

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

11 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway The Socket Writer 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. This guide contains the following sections: v Summary of the Socket Writer Gateway v Installing the gateway on page 2 v Using the Socket Writer Gateway on page 5 v Configuring the gateway on page 7 v Error messages on page 16 Summary of the Socket Writer Gateway Each gateway works in a different way to provide an interface with the ObjectServer. Use this summary information to learn about the Socket Writer. The following table provides a summary of the gateway: Table 3. Summary Gateway target Gateway executable file name TCP Socket nco_g_socket (on UNIX and Linux) nco_g_socket.exe (on Windows) Package Version 10.0 Gateway supported on Configuration files For details of supported operating systems, see the following Release Notice on the IBM Software Support website: docview.wss?uid=swg The UNIX version of the gateway is supplied with the following configurations files: $OMNIHOME/gates/socket/NCO_GATE.props $OMNIHOME/gates/socket/socket.map $OMNIHOME/gates/socket/socket.reader.tblrep.def $OMNIHOME/gates/socket/socket.startup.cmd Additional binaries Package version None omnibus-arch-gateway-nco-g-socket -revision Where, arch identifies the supported platform. revision identifies the patch number of the executable file. Copyright IBM Corp. 2006,

12 Table 3. Summary (continued) Requirements A currently supported version of IBM Tivoli Netcool/OMNIbus. NSocket library files (for IPv6 support) Remote Connectivity Failover/failback functionality Available Available For details of configuring failover/failback, see Failover and Failback on page 6. Multicultural support IP environment Federal Information Processing Standards (FIPS) Available IPv4 and IPv6 IBM Tivoli Netcool/OMNIbus V7.3.0, and use the FIPS approved cryptographic provider: IBM Crypto for C (ICC) certificate 384 for cryptography. This certificate is listed on the NIST website at For details about configuring Netcool/OMNIbus for FIPS mode, see IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide. Installing the gateway There are separate procedures for installing the gateway on Tivoli Netcool/OMNIbus V7.3.0, or later and on Tivoli Netcool/OMNIbus V Follow the procedure for the version of Tivoli Netcool/OMNIbus that your site uses. Installing the gateway on Tivoli Netcool/OMNIbus V7.3.0 or later With the introduction of Tivoli Netcool/OMNIbus V7.3.0 and later versions, 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 3 v A text-based installer ( Console mode on page 3) v Settings predefined in a text file ( Silent mode on page 3) 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. Obtaining the installation package To obtain the installation package and prepare it for installation use the following steps: 2 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

13 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: Linux UNIX $NCHOME/omnibus/gates Windows %NCHOME%\omnibus\gates The installation wizard To install the gateway using the installation wizard: 1. Run the installer for your operating system: Linux UNIX $NCHOME/omnibus/install/nco_install_integration Windows %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: Linux UNIX $NCHOME/omnibus/install/nco_install_integration -i console Windows %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: Linux UNIX $NCHOME/omnibus/install/nco_install_integration -i silent -f response_path/response.txt Windows %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 Writer Gateway 3

14 Installing the gateway on Tivoli Netcool/OMNIbus V7.2.1 The process of installing gateways on Tivoli Netcool/OMNIbus V7.2.1 consists of downloading the appropriate gateway installation package, downloading the packages for each gateway dependency, installing the gateway patch contained in the gateway package, and installing the patch for each dependency contained in their respective packages. The installation package for the gateway is supplied as a compressed archive. It contains the patch version of the gateway in the patches subdirectory and a README.txt file that lists the gateway dependencies. The dependencies are supplied as packages that you must download separately. Each dependency package contains the patch version of the dependency in its patches subdirectory. Note: 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. To install the gateway: 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. 4. In the temporary directory, locate and read the README.txt file. The README.txt file will tell you if you need to download any further dependencies from the Passport Advantage Online Web site. 5. Download the install packages for all dependencies listed in the README.txt file. 6. Extract the contents of each dependency installation package to a temporary directory. 7. Locate the patches directory for the gateway (under the directory containing the README.txt file). This directory contains the patch for the gateway. 8. Windows Extract the patch files for the gateway and its dependencies to the following directory: %OMNIHOME% 9. Linux UNIX Consult the README.txt file to determine the order in which the gateway and any dependency patches must be installed. 10. Linux UNIX Install each patch, in the correct order, by running the following command: $OMNIHOME/install/nco_patch -install patch_path where patch_path is the path to the extracted patch file. Note: Linux UNIX At any point in the installation process, you can see what patches have been installed by running the following command: $OMNIHOME/install/nco_patch -print=id 4 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

15 Using the Socket Writer Gateway The Socket Writer connects to the configured socket and forwards events from the ObjectServer to a local or a remote socket over TCP. Features of the Socket Writer Gateway The Socket Writer Gateway has various features that enable you to create an interface between the Socket Writer 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 Writer Gateway properties, use the NCO_GATE.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 ObjectServer and the destination socket. Details of the tables to be replicated are stored in the table replication definition file. Use the Gate.Reader.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 of ObjectServer onto the socket in a format defined by the map definition file. To specify the map definition file, use the Gate.MapFile property. Acknowledging alerts If the socket can actively write messages back to the gateway, you can enable the gateway to receive an acknowledgement for each alarm sent to the socket. To receive acknowledgements, specify a welcome message using the IBM Tivoli Netcool/OMNIbus Socket Writer Gateway 5

16 Gate.Socket.GreetingMessage property. The gateway sends this welcome message to the socket at the initial connection, writes the alarms in a memory; and waits for acknowledgement from the socket for the period specified by the Gate.Socket.TimeoutSecs property. The socket responds to each message with a reply containing the index of the message being acknowledged. If the socket cannot write messages back to the gateway, set the Gate.Socket.GreetingMessage property to "". The gateway directly writes the messages to the socket without storing them in memory. Failover and Failback Failback 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 nco_xigen. To specify that the gateway fails back to the primary ObjectServer, set the Gate.Reader.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 for the period specified by the Gate.Reader.FailbackTimeout property. The connection is checked at startup and whenever an event is sent. When the primary ObjectServer is detected again, the reader automatically fails over to the primary ObjectServer. On detection of the reader failover or failback, the writer shuts down the gateway and relies on the Process Agent to restart the gateway. Process Agent control You can control how the gateway runs by using Process Agent 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. Store and forward mode When the remote socket is no longer active, the gateway changes to the store-and-forward mode. Using the store-and-forward mode, gateway writer can continue to run until the socket is available again. When the writer detects that the target socket is not present or is not functioning (because the writer is unable to write an alert), it switches into store mode. In this mode, the writer stores everything it would normally send to the socket in a file named: $OMNIHOME/var/NCO_GATE_Socket.store When the gateway receives another event, it will attempt to reconnect to the socket. If it still cannot connect to the socket, it adds the new event to the SAF file. If it can connect to the socket, the gateway flushes the events in the SAF file. 6 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

17 Store-and-forward mode only works when a connection to the socket has been established, used, and then lost. If the destination server is not running when the gateway starts, store-and-forward mode is not triggered and the gateway terminates. If the gateway connects to the destination socket and a store-and-forward file already exists, the gateway replays the contents of the store-and-forward file before it sends new alerts. Store-and-forward mode is configured using the Gate.Socket.StoreAndForward and Gate.Socket.StoreFile properties. To activate the store and forward function, set the Gate.Socket.StoreAndForward property to TRUE. Then, use the Gate.Socket.StoreFile property and specify the file to which the alerts are written while the destination socket is offline, and then restart the gateway. To deactivate the store and forward function, set the Gate.Socket.StoreAndForward property to FALSE, and then restart the gateway. Note: If the Gate.Socket.GreetingMessage property has a welcome message while the gateway goes to the store-and-forward mode, then the gateway continues to store the alerts in memory. Receiving fatal error messages If there is a connection failure while the gateway is in store-and-forward mode, the gateway will fail to send the stored messages to the socket. To get notified about this fatal error, set the Gate.Socket.SafForwardErrorFatal property to TRUE. A value of FALSE instructs the gateway to not send fatal error messages to socket. Note: To use this functionality, you must also specify a welcome message using the Gate.Socket.GreetingMessage property. 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. Connecting to an ObjectServer running in secure mode If the ObjectServer to which the Socket Gateway connects is running in secure mode, the gateway must authenticate against it with a valid user name and password. Configuring the gateway To authenticate against such an ObjectServer, the gateway uses the user name and password specified by the Gate.Reader.Username and Gate.Reader.Password properties. The Socket Writer Gateway is configured using a set of configuration files. IBM Tivoli Netcool/OMNIbus Socket Writer Gateway 7

18 Use the Server Editor (nco_xigen) to specify the host name and port number of the gateway host in the Netcool/OMNIbus interfaces file. Note: For information about using the Server Editor, see IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide (SC ). To install the gateway on UNIX, use the following steps: 1. Create the server NCO_GATE in the interfaces files usingnco_xigen. 2. Copy the properties file (NCO_GATE.props) to the following directory: $OMNIHOME/etc. Note: NCO_GATE is the default name for the gateway server, and NCO_GATE.props is the default name for its properties file. You can specify an alternative name for properties file using the -propsfile command-line option when you run the gateway. 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 12 v Startup command file on page 13 v Table definition replication file on page 15 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 is installed in the following location: v $OMNIHOME/gates/socket/NCO_GATE.props 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 most frequently used to configure the Socket Writer 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, (SC ). Table 4. Properties file Property name Command line option Description Gate.MapFile -mapfile Use this property to specify the mapping file for the gateway to use. The default is $OMNIHOME/gates/ socket/socket.map. Gate.NGTKDebug -ngtkdebug Use this property to specify that the NGTK library logs debug messages. The default is TRUE. 8 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

19 Table 4. Properties file (continued) Property name Command line option Description Gate.PAAware integer -paaware integer Use this property to enable the gateway for PA control. This property takes the following values: v 0: The gateway is not enabled to use with a PA session. v 1: The gateway is enabled to use with a PA session. The default is 0. Gate.PAAwareName -paname Use this property to specify the name of the PA service to which the gateway will be available. Gate.Reader.Failback Enabled Gate.Reader.Failback Timeout integer Gate.Reader.Reconnect Timeout integer -readerfailbackenabled -readerfailbacktimeout integer -readerreconnect timeout integer The default is "". Use this property to specify whether the gateway fails back to the backup ObjectServer when disconnected from the primary ObjectServer. The default is TRUE. 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. Use this property to specify the time (in seconds) between each reconnection poll attempt that the gateway makes if the connection to the socket is lost. Gate.Reader.Tbl ReplicateDefFile -readertblrepdeffile The default is 30. Use this property to specify the location of the table replication definition file. Gate.Reader.Server Gate.Reader.Username Gate.Reader.Password -readerserver -readerusername -readerpassword The default is $OMNIHOME/gates/ socket/ socket.reader.tblrep.def. Use this property to specify the server to which the gateway connects. The default is NCOMS. Use this property to specify the username that is used to authenticate the ObjectServer connection. The default is root. Use this property to specify the password associated with the user specified by the Gate.Reader.Username property. The default is "". IBM Tivoli Netcool/OMNIbus Socket Writer Gateway 9

20 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.Date Format -socketdateformat Use this property to specify the date format that the gateway uses for any date fields written to the socket. Gate.Socket.Delete Header Gate.Socket.Delete Trailer Gate.Socket.DoTime stamp Gate.Socket.EndString Gate.Socket.FailBack Enabled Gate.Socket.FailBack Timeout integer Gate.Socket.Greeting Message -socketdelhdr -socketdeltl -socketdotimestamp -socketend -socketfailbackenabled -socketfailbackenabled -socketgreetingmessage The default is %x %X. 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. Use this property to specify the value to be added at the end of the to be written to the socket. The default is "". This property is not supported by the gateway but appears when the -help or -dumpprops properties are used when configuring the gateway. The correct property for configuring this is: Gate.Reader.FailBackEnabled. This property is not supported by the gateway but appears when the -help or -dumpprops properties are used when configuring the gateway. The correct property for configuring this is: Gate.Reader.FailBackTimeout. Use this property to specify a message that the gateway sends in the header packet. This activates application level acknowledgement. The default is "". Gate.Socket.Host -sockethost Use this property to specify the name of the host to which the TCP connection is made. Gate.Socket.Insert Header -socketinshdr The default is "somehost". 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". 10 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

21 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.Insert Trailer -socketinstl Use this property to specify the format of the trailer added to the end of each insert alert written to the socket. Gate.Socket.KeepAlive Gate.Socket.Port integer Gate.Socket.Saf ForwardErrorFatal Gate.Socket.Separator Gate.Socket.Start String Gate.Socket.StoreAnd Forward Gate.Socket.StoreFile Gate.Socket.Timeout Secs integer -socketkeepalive -socketport integer -socketsafforward errorfatal -socketsepstr -socketstart -socketstoreandforward -socketstorefile -sockettimeoutsecs integer The default is "\n". Use this property to specify whether the gateway keeps TCP sockets open when not in use. The default is FALSE. Important: To ensure that a firewall does not timeout TCP connections, you must set the value to TRUE. Use this property to specify the remote TCP port to which the gateway connects. The default is Use this property to specify whether failing to forward store alerts is considered to be a fatal error. The default is FALSE. Note: To use this functionality, you must specify a welcome message using the Gate.Socket.GreetingMessage property. Use this property to specify the character to be inserted between the fields written to the socket. The default is "". Use this property to specify the value to be prefixed with a to be written to the socket. The default is "". Use this property to specify whether the gateway uses the store-and-forward feature. The default is FALSE. Use this property to specify the file in which the gateway stores alerts when running in the store-and-forward mode. The default is $OMNIHOME/var/ NCO_GATE_socket_.store Use this property to specify the period (in seconds) the gateway waits to make a connection with the socket. The default is 0. IBM Tivoli Netcool/OMNIbus Socket Writer Gateway 11

22 Table 4. Properties file (continued) Property name Command line option Description Gate.Socket.Update Header Gate.Socket.Update Trailer Gate.StartupCmdFile Gate.Transfer. FailoverSyncRate integer -socketuphdr -socketupdtl -startupcmdfile -fsyncrate integer 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:". 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". Use this property to specify the location of the startup command file. The default is $OMNIHOME/gates/ socket/socket.startup.cmd. Use this property to specify (in minutes) the time the gateway waits between failover synchronizations The default is 60. Map definition file The map definition file defines how the gateway maps data received from the Socket Writer to the Status, Journal, and Details tables within the ObjectServer. The default map definition file is installed in the following location: v $OMNIHOME/gates/socket/socket.map Gateway mapper attributes You can configure the mapping functions of the gateway by using the mapper attributes. Syntax Mappings for use with the Socket Writer 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 the ObjectServer alerts.status table. 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. 12 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

23 Example mapping The following default mapping is supplied in the socket.map file: CREATE MAPPING StatusMap ( CONVERT TO DATE, CONVERT TO DATE, CONVERT TO DATE, CONVERT TO DATE, ); Startup command file The gateway is provided with a startup command file (socket.startup.cmd). You should use this file to contain a set of commands that the gateway performs automatically each time it starts. The commands that you can use in this file are described at the end of this topic. IBM Tivoli Netcool/OMNIbus Socket Writer Gateway 13

24 After the gateway has started, you can use the nco_sql command to issue the commands manually. For details about nco_sql, see the IBM Tivoli Netcool/OMNIbus Administration Guide, (SC ). UNIX and Linux operating systems The default startup command file is installed in the following location: v $OMNIHOME/gates/socket/socket.startup.cmd Windows operating systems On Windows operating systems, the default startup command file is installed in the following location: v %OMNIHOME%\gates\socket\socket.startup.cmd The startup commands must be specified without the go command. Logging on to the gateway On UNIX and Linux operating systems, you can log in to the gateway using the following command: $NCHOME/omnibus/nco_sql -server NCO_GATE -user username -password password Note: Logging on to the gateway on Windows operating systems using the SQL interactive interface (isql.bat) is not supported. Table 5. Startup command file property examples Property Syntax Example GET PROPERTY : Use this command to return the value of a specified property from the gateway properties file. SHOW PROPS : Use this command to display the current configuration of the gateway by listing all properties and their values. GET PROPERTY ; GET PROPERTY "Gate.Reader.Debug" ; go SHOW PROPS ; SHOW PROPS ; go Note: The GET PROPERTY startup command is not supported on Windows operating systems. 14 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

25 Table 5. Startup command file property examples (continued) Property Syntax Example GET CONFIG : Use this command to display the current configuration of the gateway by listing all properties and their values. Note: GET CONFIG ; GET CONFIG ; go GET CONFIG is identical to the SHOW PROPS command; it may be removed from later versions of the Socket Writer gateway. Table definition replication file The table replication definition file defines the tables in the source ObjectServer, which the gateway replicates in the socket. The table definition replication file is installed in the following location: v $OMNIHOME/gates/socket/socket.reader.tblrep.def This file consist of a single REPLICATE command, which uses the following syntax: REPLICATE ALL (INSERTS, UPDATES, DELETES) FROM TABLE sourcetable USING MAP mapname ; Where: v sourcetable is the name of table to be replicated in the target system. For example, alerts.status. v mapname is the name of the map that defines the table. For example, StatusMap. Running the gateway The Socket Writer gateway is configured using a properties file. This 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. To run the Socket Writer gateway, run the following command: $OMNIHOME/bin/nco_g_socket -name gateway_server_name Where gateway_server_name is the server name of the gateway as defined in the Server Editor. Note: IBM Tivoli Netcool/OMNIbus Socket Writer Gateway 15

26 Error messages The default location for the properties file for the Socket Writer gateway is $OMNIHOME/etc/gateway_server_name.props. The default properties file must be copied to the $OMNIHOME/etc folder. For details of the properties and values to which you can set them, see Property settings for the operational environment of the gateway on page 8. For details about defining the gateway server name using the Server Editor, refer to the section Configuring server communication details in the Server Editor in the Installation and Deployment Guide (SC ). Error messages provide information about problems that have occurred during the operation of the gateway. You can use the information that they contain to resolve such problems. The following table describes the error messages that the Socket Writer gateway generates. Table 6. Error messages Error Description Action Failed to open port on host The gateway could not open the socket port on the host specified. Check whether the port is open on host. Check whether the host is active. Check the value set for the Gate.Socket.Host and the Gate.Socket.Port properties. Failed to set option SO_KEEPALIVE for Socket writer Failed to write record to SAF store file The gateway could not set the SO_KEEPALIVE option. The gateway could not write the data in the store file. Failed to forward message The gateway could not forward the message to the socket. Failed to initialise gateway properties Failed to add the property set of the file writer to the properties manager The gateway could not initialize the gateway properties. Check that the Gate.Socket.KeepAlive property is set to TRUE for the firewall to keep the TCP connections. Check the supported platform documentation. Make more memory available. Check your network connection. Check that the server is still active. Make sure that the properties file has correct permissions. Check the values set in the properties file. 16 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

27 Appendix. Notices and Trademarks Notices This appendix contains the following sections: v Notices v Trademarks This 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 document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo , Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Copyright IBM Corp. 2006,

28 Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who want to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation Software Interoperability Coordinator, Department 49XA 3605 Highway 52 N Rochester, MN U.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 material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. All IBM prices shown are IBM's suggested retail prices, are current and are subject to change without notice. Dealer prices may vary. This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. 18 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

29 COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. Each copy or any portion of these sample programs or any derivative work, must include 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 rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear. Trademarks IBM, the IBM logo, ibm.com, AIX, Tivoli, zseries, and Netcool are trademarks of International Business Machines Corporation in the United States, other countries, or both. Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-based trademarks are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, other countries, or both. Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Appendix. Notices and Trademarks 19

30 20 IBM Tivoli Netcool/OMNIbus Socket Writer Gateway: Reference Guide

31

32 Printed in USA SC