ibm · ibm® tivoli® netcool/omnibus java socket probe version 1.0 reference guide december 10,...

IBM® Tivoli® Netcool/OMNIbus Java SocketProbeVersion 1.0

Reference GuideAugust 29, 2019

IBM

SC27-8703-01

Notice

Before using this information and the product it supports, read the information in Appendix A, “Noticesand Trademarks,” on page 35.

Edition notice

This edition (SC27-8703-01) applies to version 1.0 of IBM Tivoli Netcool/OMNIbus Java Socket Probe and to allsubsequent releases and modifications until otherwise indicated in new editions.

This edition replaces (SC27-8703-00).© Copyright International Business Machines Corporation 2015, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

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

Chapter 1. IBM Tivoli Netcool/OMNIbus Java Socket Probe.................................... 1Summary...................................................................................................................................................... 1Installing probes.......................................................................................................................................... 2Configuring the probe.................................................................................................................................. 3SSL-based connectivity................................................................................................................................4Running the probe........................................................................................................................................6Data acquisition........................................................................................................................................... 6

Running the probe in either Server mode or Client mode.....................................................................6Event stream parsing as a single line.....................................................................................................7Event stream parsing for multiple lines................................................................................................. 8Line parsing with quotation marks.........................................................................................................9Line parsing with consecutive unquoted white spaces.......................................................................10Chat in and chat out scripts................................................................................................................. 10Name resolution................................................................................................................................... 11Data stream capture.............................................................................................................................11Peer-to-peer failover functionality...................................................................................................... 11HTTP/HTTPS command interface........................................................................................................ 12

Properties and command line options...................................................................................................... 14Properties and command line options provided by the probe framework version 4.0........................... 22Elements.................................................................................................................................................... 24Error messages.......................................................................................................................................... 25ProbeWatch messages.............................................................................................................................. 26Known issues with the Java Socket Probe................................................................................................27

Chapter 2. Migrating from Socket Probe to Java Socket Probe...............................29Comparison of probe features...................................................................................................................29

Common features.................................................................................................................................29Features specific to the IBM Tivoli Netcool/OMNIbus Java Socket Probe........................................ 30

Migration procedure.................................................................................................................................. 30Determining probe differences............................................................................................................ 31Installing the Java Socket Probe......................................................................................................... 31Migrating properties............................................................................................................................. 31Customizing the rules file.....................................................................................................................33Running and testing the probe.............................................................................................................33Optimizing property values and the rules file......................................................................................33

Appendix A. Notices and Trademarks...................................................................35Notices....................................................................................................................................................... 35Trademarks................................................................................................................................................ 36

iii

About this guide

The following sections contain important information about using this guide.

Document control pageUse this information to track changes between versions of this guide.

The IBM Tivoli Netcool/OMNIbus Java Socket Probe documentation is provided in softcopy format only.To obtain the most recent version, please visit the IBM Tivoli Netcool Knowledge Center:

http://publib.boulder.ibm.com/infocenter/tivihelp/v8r1/index.jsp?topic=/com.ibm.tivoli.nam.doc/welcome_ptsm.htm

Table 1. Document modification history

Document version Publication date Comments

SC27-8703-00 December 10, 2015 First IBM publication.

Enhancements: The Java SocketProbe includes the followingenhancements:

• RFE 43179, RFE 50920, RFE61527: A secure connectioncan be established using thenew Secure Sockets Layer(SSL) feature.

• RFE 36469: TheParserElementDelimiterproperty now accepts JavaRegular Expression, allowingusers to specify multiplecharacters as delimiters. Thisenhancement is also applicableto the newParserNVPDelimiter property.

• RFE 53841: The probe can nowbe configured to receiveheartbeat messages to avoidentering into the Inactivitystate.

SC27-8703-01 August 29, 2019 Known issue added to “Knownissues with the Java SocketProbe” on page 27.

Conventions used in this guideAll probe guides use standard conventions for operating system-dependent environment variables anddirectory paths.

© Copyright IBM Corp. 2015, 2019 v



Operating system-dependent variables and paths

All probe guides use standard conventions for specifying environment variables and describing directorypaths, depending on what operating systems the probe is supported on.

For probes supported on UNIX and Linux operating systems, probe guides use the standard UNIXconventions such as $variable for environment variables and forward slashes (/) in directory paths. Forexample:

$OMNIHOME/probes

For probes supported only on Windows operating systems, probe guides use the standard Windowsconventions such as %variable% for environment variables and backward slashes (\) in directory paths.For example:

%OMNIHOME%\probes

For probes supported on UNIX, Linux, and Windows operating systems, probe guides use the standardUNIX conventions for specifying environment variables and describing directory paths. When using theWindows command line with these probes, replace the UNIX conventions used in the guide with Windowsconventions. 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 Linuxenvironments. Where such variables are described in the guide, both the UNIX and Windows conventionswill be used.

Operating system-specific directory names

Where Tivoli Netcool/OMNIbus files are identified as located within an arch directory under NCHOME orOMNIHOME, arch is a variable that represents your operating system directory. For example:

$OMNIHOME/probes/arch

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

Note: This probe may not support all of the operating systems specified in the table.

Table 2. Directory names for the arch variable

Operating system Directory name represented by arch

AIX® systems aix5

Red Hat Linux and SUSE systems linux2x86

Linux for System z linux2s390

Solaris systems solaris2

Windows systems win32

OMNIHOME location

Probes and older versions of Tivoli Netcool/OMNIbus use the OMNIHOME environment variable in manyconfiguration files. Set the value of OMNIHOME as follows:

• On UNIX and Linux, set $OMNIHOME to $NCHOME/omnibus.• On Windows, set %OMNIHOME% to %NCHOME%\omnibus.

vi IBM Tivoli Netcool/OMNIbus Java Socket Probe: Reference Guide

Chapter 1. IBM Tivoli Netcool/OMNIbus Java SocketProbe

The IBM Tivoli Netcool/OMNIbus Java Socket Probe can be configured to work in either Client mode orServer mode. In Server mode, the probe is a multiheaded probe that acts as a single process concurrentserver; the probe can handle a limited number of multiple connections to it through a TCP port. In Clientmode, the probe connects to a socket to which a device writes its events.

This guide contains the following sections:

• “Summary” on page 1• “Installing probes” on page 2• “Configuring the probe” on page 3• “SSL-based connectivity” on page 4• “Running the probe” on page 6• “Data acquisition” on page 6• “Properties and command line options” on page 14• “Properties and command line options provided by the probe framework version 4.0” on page 22• “Elements” on page 24• “Error messages” on page 25• “ProbeWatch messages” on page 26

SummaryEach probe works in a different way to acquire event data from its source, and therefore has specificfeatures, default values, and changeable properties. Use this summary information to learn about thisprobe.

The following table summarizes the probe.

Table 3. Summary

Probe target Socket

Probe executable name nco_p_socket_java (UNIX)

nco_p_socket_java.bat (Windows operating systems)

Package version 1.0

Probe supported on For details of supported operating systems, see the followingRelease Notice on the IBM Software Support website:

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

Properties file $OMNIHOME/probes/arch/socket_java.props

Rules file $OMNIHOME/probes/arch/socket_java.rules

© Copyright IBM Corp. 2015, 2019 1



Table 3. Summary (continued)

Requirements For details of any additional software that this probe requires,refer to the description.txt file that is supplied in itsdownload package.

Connection method TCP/IP (acting in client or server mode)

Remote connectivity The probe can receive events from a remote system or canconnect to a socket to which a device writes it's event data.

Peer-to-peer failover functionality Available

IP environment IPv4 or IPv6

Federal Information ProcessingStandards (FIPS)

IBM Tivoli Netcool/OMNIbus uses the FIPS 140-2 approvedcryptographic provider: IBM Crypto for C (ICC) certificate 384 forcryptography. This certificate is listed on the NIST website athttp://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htm. For details about configuring Netcool/OMNIbus for FIPS 140-2 mode, see the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide.

Installing probesAll probes are installed in a similar way. The process involves downloading the appropriate installationpackage for your operating system, installing the appropriate files for the version of Netcool/OMNIbusthat you are running, and configuring the probe to suit your environment.

The installation process consists of the following steps:

1. Downloading the installation package for the probe from the Passport Advantage Online website.

Each probe has a single installation package for each operating system supported. For details abouthow to locate and download the installation package for your operating system, visit the followingpage on the IBM Tivoli Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_download_intro.html

2. Installing the probe using the installation package.

The installation package contains the appropriate files for all supported versions of Netcool/OMNIbus.For details about how to install the probe to run with your version of Netcool/OMNIbus, visit thefollowing page on the IBM Tivoli Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_install_intro.html

3. Configuring the probe.

This guide contains details of the essential configuration required to run this probe. It combines topicsthat are common to all probes and topics that are peculiar to this probe. For details about additionalconfiguration that is common to all probes, see the IBM Tivoli Netcool/OMNIbus Probe and GatewayGuide.

2 IBM Tivoli Netcool/OMNIbus Java Socket Probe: Reference Guide

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

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





Configuring the probeAfter installing the probe you need to make various configuration settings to suit your environment.

The following table outlines how to use the probe's properties to configure the product's features.Configuration of some features is mandatory for all installations. For those features set the properties tothe correct values or verify that their default values are suitable for your environment. Furtherconfiguration is optional depending on how many features of the probe you want to use.

Table 4. Configuring the probe

Feature Properties See

Mandatory features:

Socket mode

The probe can be configured tooperate in either Server mode orClient mode.

SocketMode “Running the probe in eitherServer mode or Client mode” onpage 6

Connection setup

The information needed to set upthe connection to the target hostand port (depends on client orserver mode).

EndpointSocketHost

EndpointSocketPort

LocalSocketHost

LocalSocketPort

“Properties and command lineoptions” on page 14

Alarm parsing (multi line) ParserSingleLinesParserParseAsLinesParserElementDelimiterParserAlarmStartParserAlarmEndParserNextAlarmDelimter

“Event stream parsing formultiple lines” on page 8

Optional features:

Inactivity policy

Specifies whether the probedisconnects from the socketendpoint following a period ofinactivity.

Inactivity “Properties and command lineoptions provided by the probeframework version 4.0” on page22

Alarm parsing (single line) ParserSingleLinesParserElementDelimiterParserNVPDelimiter

“Event stream parsing as a singleline” on page 7

Data stream capture

Allows you to capture the streamof raw data from the targetdevice and store it in a file.

StreamCaptureStreamCaptureFilePath

“Data stream capture” on page11

Chapter 1. IBM Tivoli Netcool/OMNIbus Java Socket Probe 3

Table 4. Configuring the probe (continued)

Feature Properties See

Peer-to-peer failover pair

Allows you to set up two probesto act as a failover pair toimprove availability. If the masterprobe should stop working, theslave probes takes over until themaster is available once more.

MessageLogModePeerHostPeerPortPidFilePropsFileRulesFile

“Peer-to-peer failoverfunctionality” on page 11

Probe component loggingproperties

Allows you to configure thelogging properties used by theDSL framework fortroubleshooting.

DSLLogConfig “Properties and command lineoptions” on page 14

Running multiple instances ofthe probe

Allows you to run two or moreinstances of the probe on a singlehost machine.

EndpointSocketPortLocalSocketPortNamePropsFileRulesFile

“Running the probe” on page 6

Running the probe as aWindows service

None “Running the probe” on page 6

SSL-based connectivityIBM Tivoli Netcool/OMNIbus Java Socket Probe supports Secure Sockets Layer (SSL) connections. SSLconnections provide additional security when the probe retrieves alarms from the target systems.

To enable SSL connections, obtain the required SSL certificates and the Trusted Authority certificate fromthe IBM Tivoli Netcool/OMNIbus Java Socket Probe server administrator. Add the certificates to a localJava™ keystore so that they can be referenced by the KeyStore property.

The supported protocol version is TLSv1.

Prerequisites

The following tools are available to create the keystore:

• The OpenSSL toolkit.

This is available from http://www.openssl.org/.• The IBM® KeyMan utility.

This is available from http://www.alphaworks.ibm.com/tech/keyman/download.• The Keytool toolkit.

This is available in the JRE package.


http://www.openssl.org/

http://www.alphaworks.ibm.com/tech/keyman/download

Converting the key and certificate into PKCS12 format

If you have a key and a certificate from the server in separate files, you must combine them into a singlePKCS12 format file to load into a new keystore. To convert the server certificate into PKCS12 format, usethe following OpenSSL toolkit command:

openssl pkcs12 -export -inkey key_file -in cert_file -out cert_pkcs12

Where

key_file is the key file retrieved from the server.

cert_file is the certificate retrieved from the server.

cert_pkcs12 is the combined file in PKCS12 format for loading into the keystore.

Creating the SSL keystore

You can create a Java keystore using either the KeyMan utility or the Keytool utility.

To create a Java keystore using the KeyMan utility, follow these steps:

1. Start the KeyMan utility.2. Click Create New and select the Keystore token option.3. Click File > Import and choose the certificate that you retrieved from the server.

This imports the certificate into the keystore.4. Click File > Save and enter a password and name for the keystore; for example,trusted_keystore.jks.

To create a Java keystore using the Keytool utility, follow these steps:

1. Generate a keystore and self-signed certificate using the following command:

keytool -genkey -keyalg RSA -alias alias_name -keystore keystore_file -storepass keystore_password -validity 360 -keysize 2048

2. Import the SSL certificate into the newly created Java keystore file using the following command:

keytool -import -trustcacerts -alias alias_name -file cert_file -keystorekeystore_file

3. Verify that the certificates are in a Java keystore using the following command:

keytool -list -v -keystore keystore_file

Enabling SSL connections

To enable SSL-based connections between the probe and the Element Management System (EMS) server,make the following changes to the socket_java.props file:

1. Set the EnableSSL property to true.

When the EnableSSL property is set to true, the following properties are enabled:

• KeyStore• KeyStorePassword

2. Use the KeyStore property to specify the location of the keystore file.3. Use the KeyStorePassword property to specify a password for the keystore.

Note: You can encrypt the keystore file password using the nco_aes_crypt utility (for FIPS 104-2mode security).

4. Set the Port property to the port that the probe uses for SSL connections.


Running the probeProbes can be run in a variety of ways. The way you chose depends on a number of factors, including youroperating system, your environment, and the any high availability considerations that you may have.

For details about how to run the probe, visit the following page on the IBM Tivoli Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/concept/running_probe.html

Data acquisitionEach probe uses a different method to acquire data. The method that a probe uses is based on the targetsystem from which the probe receives data.

The IBM Tivoli Netcool/OMNIbus Java Socket Probe can be configured to operate in either Server mode orClient mode by setting the SocketMode property. By default, the probe operates in Server mode.

Note: When the probe operates in Server mode ensure that the event source information sent to theprobe does not contain an asterisk (*).

The mode that you chose determines how the probe acquires data. Data acquisition is described in thefollowing topics:

• “Running the probe in either Server mode or Client mode” on page 6• “Event stream parsing as a single line” on page 7• “Event stream parsing for multiple lines” on page 8• “Line parsing with quotation marks” on page 9• “Line parsing with consecutive unquoted white spaces” on page 10• “Chat in and chat out scripts” on page 10• “Name resolution” on page 11• “Data stream capture” on page 11• “Peer-to-peer failover functionality” on page 11

Running the probe in either Server mode or Client modeThe probe can be configured to operate in either Server mode or Client mode by setting the SocketModeproperty. By default, the probe operates in Server mode.

In Server mode, the probe operates as a multi-headed server that can accept connections from multipledevices using TCP/IP and receive events sent to it. To run the probe in Server mode, set the SocketModeproperty to Server. In Client mode, the probe connects to the target system and listens on the socket towhich the target system writes its event data; the probe receives ASCII data in the form of an elementvalue followed by a carriage return or new line characters. To run the probe in Client mode, set theSocketMode property to Client.

Most properties are common to both Server and Client probe modes of operation. However, the waycertain properties are set is determined by the mode in which you are running the probe.

The following properties are only configurable when the probe is running in Client mode:

• ChatinString• ChatoutString• EndpointSocketHost• EndpointSocketPort• ProtocolHeartbeatString

The following properties are only configurable when the probe is running in Server mode:




• EventReadString• IdleConnectionTimeout• LoginScript• LocalSocketHost• LocalSocketPort

For details of all these properties, see “Properties and command line options” on page 14.

Event stream parsing as a single lineYou can configure the probe to parse the event stream as a single line with tokens separated by tokendelimiters. The character specified by the ParserNextAlarmDelimiter property indicates the end of eachevent.

To specify that the probe parses the event stream as a single line, set the ParserSingleLines property totrue and specify the delimiter that separates tokens using the ParserElementDelimiter property. Tospecify name value-pair delimiters, use the ParserNVPDelimiter property.

For example, if ParserElementDelimiter property is set to |, and the probe receives the following line:

"Hostname|PortNumber|Summary"

Then the probe parses the line into the following tokens:

Token1="Hostname",Token2="PortNumber",Token3="Summary"

For name value-pair example, if ParserElementDelimiter property is set to |, ParserNVPDelimiterproperty is set to =, and the probe receives the following line:

"Hostname=texth|PortNumber=1234|Summary=texts"

Then the probe parses the line into the following tokens:

Token1="Hostname=texth",Token2="PortNumber=1234",Token3="Summary=texts"NVP_Hostname=texthNVP_PortNumber=1234NVP_Summary=texts

Line parsing with empty valuesYou can also specify how the probe parses lines that contain empty fields (that is, adjacent delimiterswith no data in between) using the ParserIgnoreEmptyFields property.

For example, the ParserSingleLines property is set to true, the ParserElementDelimiter property is setto |, and the probe receives the following line:

"Hostname|PortNumber|Summary|||Severity"

This line contains empty fields between Summary and Severity.

If the ParserIgnoreEmptyFields property is set to true, the probe ignores the empty fields and so parsesthe line into the following tokens:

Token1="Hostname",Token2="PortNumber",Token3="Summary",Token4="Severity"

If the ParserIgnoreEmptyFields property is set to false, the probe generates tokens with no values forthe empty fields and so parses the line into the following tokens:

Token1="Hostname",Token2="PortNumber",Token3="Summary",Token4="",Token5="", Token6="Severity"


Event stream parsing for multiple linesYou can configure the probe to parse multiple line events with multiple clients connections.

To set the probe to expect multiple line event streams, set the ParserSingleLines property to false.

The probe needs a mechanism to demarcate alarms. This is implemented in two ways: an eventterminator demarcates the events or a Java Regular Expression Pattern match is done for headers andfooters. For the former approach, the character specified by the ParserNextAlarmDelimiter propertyindicates the end of each event. The probe will use the latter approach only if both the ParserAlarmStartand ParserAlarmEnd properties are set.

Example 1 - Start and End parsing with ParserParseAsLines set to true

In this example, set ParserAlarmStart to ALARM, ParserAlarmEnd to END, ParserSingleLines to false,and ParserParseAsLines to true, with ParserElementDelimiter set to , (or anything other than ; in thisexample). The probe receives the following line:

ALARMDATA1 ;DATA1a ;DATA1b ;DATA1B;DATA1 ;DATA1a ;DATA1b ;DATA1DD;END

The probe then parses the line into the following tokens:

Line1: DATA1 ;DATA1a ;DATA1b ;DATA1B;Line2: DATA1 ;DATA1a ;DATA1b ; DATA1DD;line_n: 2

Example 2 - Start and End parsing with delimiter

In this example, set ParserAlarmStart to ALARM, ParserAlarmEnd to END, ParserSingleLines to false,ParserParseAsLines to false, and ParserElementDelimiter to ;. The probe receives the following line:

ALARMDATA1;DATA1a;DATA1b;DATA1c;DATA2;DATA2a;DATA2b;DATA2c;END


Token7: DATA2bToken8: DATA2cToken5: DATA2Token6: DATA2aToken3: DATA1bToken4: DATA1cToken1: DATA1Token2: DATA1aTokenCount: 12ALARM_START: ALARMALARM_END: END

Example 3 - Start and End parsing with Header property set

In this example, set ParserAlarmStart to EVENT FROM SYSTEM .*, ParserAlarmEnd to END OF EVENT,ParserAlarmHeader to Header.*, ParserSingleLines to false, ParserParseAsLines to false, andParserElementDelimiter to " " (whitespace). The probe receives the following line:

EVENT FROM SYSTEM XYZHEADER 1 HEADER2Value1a Value1bValue2a Value2bEND OF EVENT



ALARM_START: EVENT FROM SYSTEM XYZALARM_END: END OF EVENTALARM_HEADER: HEADER 1 HEADER2Token1: Value1aToken2: Value1bToken3: Value2aToken4: Value2b

Example 4 - Multi-line parsing using next alarm delimiter

In this example, set ParserNextAlarmDelimiter to ---, ParserAlarmStart to EVENT FROM SYSTEM .*,ParserAlarmEnd to END OF EVENT, ParserSingleLines to false, ParserParseAsLines to false, andParserElementDelimiter to ;. The probe receives the following line:

EVENT FROM SYSTEM XYZALARM1_LINE1_VALUE1;ALARM1_LINE1_VALUE2;ALARM1_LINE2_VALUE1;ALARM1_LINE2_VALUE2;ALARM1_LINE3_VALUE1;ALARM1_LINE3_VALUE2;---ALARM2_LINE1_VALUE1;ALARM2_LINE1_VALUE2;ALARM2_LINE2_VALUE1;ALARM2_LINE2_VALUE2;ALARM2_LINE3_VALUE1;ALARM2_LINE3_VALUE2;---END OF EVENT

The probe then parses the line into the following tokens (for Alarm 1):

Token1: ALARM1_LINE1_VALUE1Token2: ALARM1_LINE1_VALUE2Token3: ALARM1_LINE2_VALUE1Token4: ALARM1_LINE2_VALUE2Token5: ALARM1_LINE3_VALUE1Token6: ALARM1_LINE3_VALUE2

The probe then parses the line into the following tokens (for Alarm 2):

Token1: ALARM2_LINE1_VALUE1Token2: ALARM2_LINE1_VALUE2Token3: ALARM2_LINE2_VALUE1Token4: ALARM2_LINE2_VALUE2Token5: ALARM2_LINE3_VALUE1Token6: ALARM2_LINE3_VALUE2

Line parsing with quotation marksIf a line contains single or double quotation marks (' or ", respectively), the probe can treat them as eitherstandard characters or special characters. If a line contains both single and double quotation the probetreats the first quotation in that line as a special character only and treats the subsequent quotation as astandard character.

As standard characters, quotation marks have no significant meaning and are parsed as any othercharacter. As special characters, quotation marks indicate that the probe should treat characters fallingbetween them (including any spaces) as a single token. To specify that the probe treats quotation marksas special characters, set the ParserQuoteCharacter property to ". If no value is set for theParserQuoteCharacter property, then quote characters will be treated as normal characters.

For example, by default if the probe receives the following line:

"Example data one" "Example data two"

The probe parses the line into the following tokens:

Token1="Example data one" Token2="Example data two"


Line parsing with consecutive unquoted white spacesIf a line contains consecutive unquoted white spaces (that is, consecutive tabs or spaces in a line that donot fall within a pair of quotation marks), the probe can either maintain all the white spaces in the line orreduce the consecutive white spaces to a single space.

To specify that the probe maintains consecutive unquoted white spaces, set the ParserPreserveLineproperty to true. Otherwise, set the ParserPreserveLine property to false.

Chat in and chat out scriptsChat in and chat out scripts control probe login and logout. These scripts are on a single line in theexpect-send format (for chat in scripts) or send-expect format (for chat out scripts). You can specify chatin and chat out strings using the ChatinString and ChatoutString properties or the -chatinstring and -chatoutstring command line options.

The format is:

ChatinString : expect send expect send....

ChatoutString : send expect send expect....

Note: Each element in the chat strings is separated by white space. In order to send or expect a sequencethat includes white space, surround the sequence with single quotes.

A typical chat in script might be:

.*login.*:.* anu\\r\\n .*assword.*:.* anu\\r\\n

The expect text uses the Java Regular Expression Pattern, while the send text can send any characters,including control characters using the standard Java Language Specification described in “Escape codes”on page 10.

Escape codesYou can use Java Regular Expression constructs in the ParserAlarmStart, ParserAlarmEnd,ParserAlarmHeader, LoginScript, ChatinString and ChatoutString properties. This allows you to easilydefine whether to send escape code sequences after commands.

For example, the following chatin string sends a carriage return character (\r) after the user name andpassword:

ChatinString : ".*: user\\r .*: passwd\\r"

The following table explains the character sequences that are recognized.

Table 5. Escape codes

Escape code Character

\f This escape code specifies the form-feedcharacter.

\n This escape code specifies the new-line character.

\r This escape code specifies the carriage returncharacter.

\t This escape code specifies the tab character.

\\ This escape code specifies the backslashcharacter.


Table 5. Escape codes (continued)

Escape code Character

\' This escape code specifies the single quotecharacter.

\" This escape code specifies the double quotecharacter.

Note: Due to the way in which the above properties are parsed, the escape sequences for backslash,single quote and double quote must be double-escaped. For example, to send a backslash character (\),use \\\\.

Name resolutionIf you are using a naming service, such as Domain Name System (DNS) or Network Information Service(NIS), the IP address of each host can be written in either dotted quad format (for example,193.131.98.3) or can be assigned a human-readable host name.

By default, the HostNameResolution property is set to true. At this default setting, the probe resolves alldotted quad IP addresses to hostnames in events pushed to the OMNIbus. This option can improve theperformance of the probe.

Data stream captureThe probe can capture the stream of data from the socket endpoint and store it in a file. The data can beused for debugging purposes, to develop new features for the probe, or to pass onto other managementsystems that require the same data.

To capture the data stream in log files, use the following procedure:

1. Set the value of the StreamCapture property to 1.2. Set the value of the StreamCaptureFile property to the full path of a directory to hold the data file.

Notes:

• Specify the full path to the file. For example:

/opt/IBM/tivoli/netcool/omnibus/var/socket_java.stream• You cannot include variables such as $OMNIHOME in the directory path.• The directory must exist. The probe does not create the directory if it does not exist.

3. If the probe is running, restart it.

The probe now writes stream data to the specified file. If the path specified is invalid or an empty path,the probe will automatically reset the path to $OMNIHOME/probes.

Note: Capturing the data stream to a log file generates a lot of data, consuming a lot of disk space andother system resources. So use this feature with caution. As soon as you no longer require the capture ofdata, set the value of the StreamCapture property to 0 and restart the probe.

Peer-to-peer failover functionalityThe probe supports failover configurations where two probes run simultaneously. One probe acts as themaster probe, sending events to the ObjectServer; the other acts as the slave probe on standby. If themaster probe fails, the slave probe activates.

While the slave probe receives heartbeats from the master probe, it does not forward events to theObjectServer. If the master probe shuts down, the slave probe stops receiving heartbeats from themaster and any events it receives thereafter are forwarded to the ObjectServer on behalf of the masterprobe. When the master probe is running again, the slave probe continues to receive events, but no longersends them to the ObjectServer.


Example property file settings for peer-to-peer failover

You set the peer-to-peer failover mode in the properties files of the master and slave probes. The settingsdiffer for a master probe and slave probe.

Note: In the examples, make sure to use the full path for the property value. In other words replace$OMNIHOME with the full path. For example: /opt/IBM/tivoli/netcool.

The following example shows the peer-to-peer settings from the properties file of a master probe:

Server : "NCOMS" RulesFile : "master_rules_file"MessageLog : "master_log_file"PeerHost : "slave_hostname"PeerPort : 6789 # [communication port between master and slave probe]Mode : "master"PidFile : "master_pid_file"

The following example shows the peer-to-peer settings from the properties file of the correspondingslave probe:

Server : "NCOMS" RulesFile : "slave_rules_file"MessageLog : "slave_log_file"PeerHost : "master_hostname"PeerPort : 6789 # [communication port between master and slave probe]Mode : "slave"PidFile : "slave_pid_file"

HTTP/HTTPS command interfaceIBM Tivoli Netcool/OMNIbus Version 7.4.0 (and later) includes a facility for managing the probe over anHTTP/HTTPS connection. This facility uses the nco_http utility supplied with Tivoli Netcool/OMNIbus.

The HTTP/HTTPS command interface replaces the Telnet-based command line interface used in previousversion of IBM Tivoli Netcool/OMNIbus.

The following sections show:

• How to configure the command interface.• The format of the nco_http command line.• The format of the individual probe commands.• The messages that appear in the log files.• How to store frequently-used commands in a properties file.

For more information on the HTTP/HTTPS command interface and the utilities it uses, see the chapter onremotely administering probes in the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.

Configuring the command interface

To configure the HTTP/HTTPS command interface, set the following properties in the probe's propertyfile:

NHttpd.EnableHTTP: Set this property to True.NHttpd.ListeningPort: Set this property to the number of the port that the probe uses to listen forHTTP commands.

Optionally, set a value for the following property as required:

NHttpd.ExpireTimeout: Set this property to the maximum elapsed time (in seconds) that and HTTPconnection remains idle before it is disconnected.

The IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide contains a full description of these and allproperties for the HTTP/HTTPS command interface.


Format of the nco_http command line

The format of the nco_http command line to send a command to the probe is:

$OMNIHOME/bin/nco_http -uri probeuri:probeport/probes/socket_java -datatypeapplication/json -method post -data '{"command":"command-name","params":[command-parameters]}'

Where:

• probeuri is the URI of the probe.• probeport is the port that the probe uses to listen for HTTP/HTTPS commands. Specify the same value

as that set for the NHttp.ListeningPort.• command-name is the name of the command to send to the probe. The following command names are

available:

helpstop

• command-parameters is a list of zero or more command parameters. For commands that have noparameters, this component is empty. The command descriptions in the following section define theparameters that each takes.

Probe commandsThe following sections define the structure of the JSON-formatted commands that you can send to theprobe. There is an example of each command.

All the examples use a probe URI of http://localhost and a HTTP listening port of 4567.

help

Use the help command to receive help information about the HTTP/HTTPS command interface.

The format of the -data option for the help command is:

-data '{"command":"help","params":[]}'

The following command returns help information:

$OMNIHOME/bin/nco_http -uri http://localhost:4567/probes/socket_java -datatypeapplication/JSON -method POST -data '{"command":"help","params":[]}'

stop

Use the stop command to shut down the probe.

The format of the -data option for the stop command is:

-data '{"command":"stop", "params":[]}'

The following example stops the probe:

$OMNIHOME/bin/nco_http -uri http://localhost:4567/probes/socket_java -datatypeapplication/JSON -method POST -data '{"command":"stop", "params":[]}'

Storing commands in the nco_http properties fileYou can use the nco_http utility's properties file ($OMNIHOME/etc/nco_http.props) to holdfrequently used command characteristics.

If you have a particular command that you send to the probe regularly, you can store characteristics ofthat command in the nco_http properties file. Once you have done that, the format of the nco_httpcommand line is simplified.

You can use the one or more of the following nco_http properties to hold default values for theequivalent options on the nco_http command line:

Data


DataTypeMethodURI

Specify the value of each property in the same way as you would on the command line. Once you havethese values in place you do not need to specify the corresponding command line switch unless you wantto override the value of the property.

The following is an example of the use of the properties file and the simplification of the nco_httpcommand that results. In this example, the nco_http properties file contains the following values (notethat line breaks appear for presentational purposes only; when editing the properties use one line foreach property value):

Data : '{"command":"stop", "params":[]}'DataType : 'application/JSON'Method : 'POST'

To use this set of values use the following nco_http command:

$OMNIHOME/bin/nco_http -uri http://localhost:4567

Properties and command line optionsYou use properties to specify how the probe interacts with the device. You can override the default valuesby using the properties file or the command line options.

The following table describes the properties and command line options specific to this probe. For moreinformation about generic Netcool/OMNIbus properties and command line options, see the IBM TivoliNetcool/OMNIbus Probe and Gateway Guide.

Table 6. Properties and command line options

Property name Command line option Description

ChatinString string -chatinstring string Use this property to specify the chat in scriptfor connection to the host system.

The default is "".

Note: The probe uses this property only whenrunning in Client mode (that is, when theSocketMode property is set to Client).

ChatoutString string -chatoutstring string Use this property to specify the chat outscript for disconnection from the host system.

The default is "".


ConnectTimeout integer -connecttimeout integer Use this property to specify the time (inseconds) to wait for the socket to beavailable.

The default is 10.


Table 6. Properties and command line options (continued)


DSLLogConfig string -dsllogconfig string Full path to configuration file for detail probecomponents logging.

The default is /opt/IBM/tivoli/netcool/omnibus/probes/<arch> /socket_java_dsl_log.properties.

EnableSSL string -disablessl (This isequivalent to EnableSSLwith a value of false.)

-enablessl (This isequivalent to EnableSSLwith a value of true.)

Use this property to specify whether SSLconnectivity between the probe and the EMSserver is enabled or disabled. This propertytakes the following values:

true: SSL connectivity between the probe andthe EMS server is enabled.

false: SSL connectivity between the probeand the EMS server is disabled.

The default is false.

EndpointSocketHoststring

-endpointsockethost string Use this property to specify the name of thehost the probe connects to when running inClient mode.

The default is localhost.


EndpointSocketPortinteger

-endpointsocketportinteger

Use this property to specify the active portthe probe connects to when running in Clientmode.

The default is 4567.


EventReadString string -eventreadstring string Use this property to specify the string theprobe sends to the host to indicate that it hasreceived an event. This string can act as anacknowledgment that prompts the host tosend the next alarm.

The default is "".

Note: The probe uses this property only whenrunning in Server mode (that is, when theSocketMode property is set to Server).




HostNameResolutionstring

-hostnameresolution string The way this property functions depends onthe mode in which the probe is operating.

When the probe is running in Server mode,use this property to specify whether theprobe performs name resolution on IPaddresses but only if the LocalSocketHostproperty is configured as an IP address. Thisproperty takes the following values:

true: The probe performs name resolution.

false: The probe does not perform nameresolution.

The default is true.

When running the probe in Client mode, usethis property to specify whether the probeperforms name resolution, but only if theEndpointSocketHost property is configuredas an IP address. If the EndpointSocketHostproperty is configured as a host name, it setsthe fully qualified domain name accordingly.

This property takes the following values:

true: The probe performs name resolution.

false: The probe does not perform nameresolution.


IdleConnectionTimeoutinteger

-idleconnectiontimeoutinteger

Use this property to specify the period (inseconds) before the probe closes idle clientconnections. If set to default value 0, theprobe will keep idle connections.

The default is 0.


KeyStore string -keystore string Use this property to specify the location ofthe keystore file that contains the clientcertificate for SSL and trusted authoritycertificate.

The keystore file can be .jks or .p12format.

The default is "".

KeyStorePassword string -keystorepassword string Use this property to specify the passwordrequired to access the certificate defined inthe Keystore property.

The default is "".




LocalSocketHost string -localsockethost string Use this property to specify the name of thehost machine which the probe opens a socketto when running in Server mode.

The default is localhost.


LocalSocketPort integer -localsocketport integer This property functions differently dependingon which mode the probe is operating.

When running the probe in Server mode, usethis property to specify the active port onwhich the probe listens for connections.


Note: Binding multiple instances of the probeto the same port is possible only on someWindows operating system. In this case oneof the instances would receive the connectionrequests at a given time. The instance thatreceives the requests would remainunknown.

LoginScript string -loginscript string Use this property to control the prompt thatthe probe sends to any client that connects toit, and the expected reply from the client. Theprompt specified must consist of two wordsseparated by a space. The first word is theprompt the probe sends to the client and thesecond word is the expected reply from theclient. If the reply from the client matches thereply specified by this property the probecontinues processing events, otherwise theprobe disconnects from the client.

For example:

USERNAME Passw0rd

The default is "".


MaximumLineSize integer -maximumlinesize integer Use this property to specify the maximumsize (in bytes) of an event that the probe canread.





MaximumPoolSize integer -maximumpoolsize integer Use this property to specify the number ofcore servicing threads allowed in the threadpool. The more threads you have the morelikely it is that a socket will be servicedimmediately. However, the more threads youhave, the more resources the probeconsumes.

The default is 16.

ParserAlarmEnd string -parseralarmend string Use this property to specify the regularexpression that indicates the footer of anevent.

The default is "".

ParserAlarmHeader string -parseralarmheader string Use this property to specify the alarm headerregular expression to be extracted.

The default is "".

Note: Specify a value for both theParserAlarmStart and ParserAlarmEndproperties so that the probe can send eventsto the ObjectServer.

ParserAlarmStart string -parseralarmstart string Use this property to specify the regularexpression that indicates the header of anevent.

The default is "".

ParserElementDelimiterstring

-parserelement delimiterstring

Use this property to specify the charactersthat indicate token delimiters. When set, theprobe parses the event stream treating thespecified characters as the field delimiterinstead of generating standard name-valuepairs.

The default is "".

Note: This property is used in conjunctionwith the ParserSingleLines property. Fordetails, see “Event stream parsing as a singleline” on page 7.




ParserIgnoreEmpty Fieldsstring

-parserignoreempty fieldsstring

Use this property to specify whether theprobe ignores instances of empty delimiters(adjacent delimiters with no data in between)in a row.

true: The probe ignores empty fields and onlygenerates tokens for fields that containinformation.

false: The probe generates tokens for allfields including empty fields.


For details, see “Line parsing with emptyvalues” on page 7.

ParserNVPDelimiter string -parsernvpdelimiter string Use this property to specify the name valuepair delimiter.

The default is =.

Note: This property is used in conjunctionwith the ParserSingleLines property. Fordetails, see “Event stream parsing as a singleline” on page 7.

ParserNextAlarmDelimiter string

-parsernextalarm delimiterstring

Use this property to specify the string thatindicates the end of an event.

The default is "".

ParserParseAsLines string -parserparseaslines string Use this property to specify whether theprobe parses all entries between the headerand the footer one line at a time as individualelements. This property takes the followingvalues:

true: The probe parses the entries one line ata time.

false: The probe does not parse the entriesone line at a time.


Note: You can use this field only if you havespecified values for ParserAlarmStart andParserAlarmEnd properties.




ParserPreserveLine string -parserpreserveline string Use this property to specify how the probehandles consecutive unquoted white spaceswithin the token value. This property takesthe following values:

true: The probe maintains consecutive whitespaces.

false: The probe reduces consecutiveunquoted white spaces to a single space.


Note: For details about using this property,see “Line parsing with consecutive unquotedwhite spaces” on page 10.

ParserQuoteCharacterstring

-parserquotecharacterstring

Use this property to specify the quotecharacter in the event. If this property is notset, the parser will treat quote characters asnormal characters.

The default is ".

Note: For details about using this property,see “Line parsing with quotation marks” onpage 9.

ParserReplaceStripCharWith string

-parserreplacestripcharwith string

Use this property to specify the character toreplace the strip character set in theParserStripCharacter property.

The default is "".

ParserSingleLines string -parsersinglelines string Use this property to specify whether theprobe parses each line as a single event. Thisproperty takes the following values:

true: The probe parses each line as a singleevent.

false: The probe does not parse each line as asingle event.


Note: Set this property to true if the eventdata consists of a single line. For details, see“Event stream parsing as a single line” onpage 7

ParserStripCharacterstring

-parserstripcharacter string Use this property to specify the character tostrip from the event.

The default is "".




ParserTrimElement string -parsertrimelement string Use this property to specify whether theprobe strips leading and trailing white spacesand new lines from elements that itgenerates.

true: The probe strips leading and trailingwhite spaces and new lines from elementsthat it generates.

false: The probe does not strip white spaceand lines from elements.


ProtocolHeartbeat Stringstring

-protocolheartbeat stringstring

Use this property to specify the heartbeatstring from the end point to the probe.

The default is "".


ReadTimeout integer -readtimeout integer Use this property to specify the number ofmilliseconds that the probe allows a socket towrite data for the probe to read. The probediscards any incomplete data after timeout.

Set this property to 0 to disableReadTimeout.

The default is 0.

ReportStatus string -reportstatus string Use this property to specify whether theprobe sends a ProbeWatch message to theObjectServer when clients connect to ordisconnect from the socket. This propertytakes the following values:

true: The probe sends ProbeWatch messages.

false: The probe does not send ProbeWatchmessages.


SecurityProvider string -securityprovider string Use this property to specify security providerof the configured keystore.

The default is PKIX.

SocketBufferSize integer -socketbuffersize integer Use this property to specify the maximumbuffer size for each socket.


Note: You can increase this number if theprobe needs to read a large number of eventsquickly.




SocketMode string -socketmode string Use this property to specify whether theprobe runs in Server or Client mode. Thisproperty takes the following values:

Client: The probe operates in Client probemode.

Server: The probe operates in Server probemode.

The default is Server.

StreamCapture integer -streamcapture integer Use this property to specify whether thestream capture feature is enabled fordebugging purposes. This property takes thefollowing values:

0: This disables the stream capture feature.

1: This enables the stream capture feature.

The default is 0.

Note: If you set this property to 1, specify thefile in which to store the data using theStreamCaptureFilename property. Whenyou no longer require data for debugging, setthe StreamCapture property to 0 to disablethe stream capture function.

StreamCaptureFilenamestring

-streamcapturefilenamestring

Use this property to specify the file that theprobe uses to store the input data stream.

The default is /opt/IBM/tivoli/netcool/omnibus/ var/socket_java.stream.

Note: This property is required if you set theStreamCapture property to 1.

Properties and command line options provided by the probe frameworkversion 4.0

All probes can be configured by a combination of generic properties and properties specific to the probe.

The following table describes the properties and command line options that are provided by the probeframework version 4.0.

Note: Some of the properties listed may not be applicable to your probe.


Table 7. Properties and command line options


CommandPort integer -commandport integer Use this property to specify the port towhich users can Telnet to communicatewith the probe using the Command LineInterface (CLI) supplied.


CommandPortLimit integer -commandportlimit integer Use this property to specify themaximum number of Telnetconnections that can be made to theprobe.

The default is 10.

DataBackupFile string -databackupfile string Use this property to specify the path tothe file that stores data between probesessions.

The default is "".

Note: Specify the path relative to$OMNIHOME/var.

HeartbeatInterval integer -heartbeatinterval integer Use this property to specify thefrequency (in seconds) with which theprobe checks the status of the hostserver.

The default is 60.

Inactivity integer -inactivity integer Use this property to specify the lengthof time (in seconds) that the probeallows the port to receive no incomingdata before disconnecting.

The default is 0 (which instructs theprobe to not disconnect during periodsof inactivity).

MaxEventQueueSize integer -maxeventqueue sizeinteger Use this property to specify themaximum number of events that can bequeued between the non native processand the ObjectServer.


Note: You can increase this number toincrease the event throughput when alarge number of events is generated.

RetryCount integer -retrycount integer Use this property to specify how manytimes the probe attempts to retry aconnection before shutting down.

The default is 0 (which instructs theprobe to not retry the connection).




RetryInterval integer -retryinterval integer Use this property to specify the lengthof time (in seconds) that the probewaits between successive connectionattempts to the target system.

The default is 0 (which instructs theprobe to use an exponentiallyincreasing period between successiveconnection attempts, for example, theprobe will wait for 1 second, then 2seconds, then 4 seconds, and so forth).

RotateEndpoint string -rotateendpoint string Use this property to specify whether theprobe attempts to connect to anotherendpoint if the connection to the firstendpoint fails.

This property takes the followingvalues:

false: The probe does not attempt toconnect to another endpoint if theconnection to the first endpoint fails.

true: The probe attempts to connect toanother endpoint if the connection tothe first endpoint fails.


ElementsThe probe breaks event data down into tokens and parses them into elements. Elements are used toassign values to ObjectServer fields; the field values contain the event details in a form that theObjectServer understands.

The following table describes the elements that the probe generates. Not all the elements described aregenerated for each event; the elements that the probe generates depend on the event type.

Table 8. Elements

Element name Element description

$FQDN This element contains the fully qualified domain name(FQDN) of the client.

$HOST This element contains the IP address of the client.


Error messagesError messages provide information about problems that occur while running the probe. You can use theinformation that they contain to resolve such problems.

The following table describes the error messages specific to this probe. For information about genericNetcool/OMNIbus error messages, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.

Table 9. Error messages

Error Description Action

Invalid SocketMode property value, expecting Server or Client.

Invalid SocketModeproperty value, expectingServer or Client.

Check the probeSocketMode property.

Error setting up text protocol codex.

There was an error settingup the text protocol codexobject.

Check the probeProtocolHeartbeatStringproperty.

Failed to send probe watch received heartbeat message to object server

The probe received aheartbeat from the targetsystem but failed togenerate a probe watchmessage to the objectserver.

Check the probe heartbeatproperty.

Error loading probe properties required for Netty configuration

An error occurred whenloading probe propertiesrequired for Nettyconfiguration.

Check the probe properties.

Error starting ProbeClient endpoint.

An error occurred startingup the Probe (client)endpoint.


Fail to load property for client info

An error occurred whenloading properties into theclient info instance.


Error starting camel context

An error occurred whenstarting the camel context.

Check that the socket isavailable.

Fail to initialize camel engine

An error occurred initializingcamel engine.

Check that the socket isavailable.

Fail to stop camel context

An error occurred stoppingcamel context.

Check the probe log file todetermine the cause oferror.

Invalid property configuration

One or more properties areset to an invalid value.


Failed to retrieve (property name) property

Failed to retrieve (propertyname) property.



Table 9. Error messages (continued)

Error Description Action

IOException in getting the filename

An IOException was thrownwhen opening the file.

Check the probe propertyand file path.

IOException in getting the current directory

An IOException throwngetting the current directory.

Check the probe propertyand file path.

Fail to load property for parser info

Fail to load propertiesrequired by parser.

Check the probe Parserproperties.

Error starting camel context routing engine

An error occurred whenstarting the camel contextrouting engine.

Check the probe log and DSLlog file to determine thecause of the error.

Potential incorrect event processing.

Warning when incorrectevent processing occured.

Configure the Parserproperties to allow multiplelines event parsing.

Multiple line parsing requiresboth ParserAlarmStart and ParserAlarmEnd set or ParserNextAlarmDelimiter set

Warning when multiple lineparsing properties notcorrectly set.

Configure theParserAlarmStart andParserAlarmEnd propertiesor ParserNextAlarmDelimiter property formultiple lines event parsing.

ProbeWatch messagesDuring normal operations, the probe generates ProbeWatch messages and sends them to theObjectServer. These messages tell the ObjectServer how the probe is running.

The following table describes the raw ProbeWatch error messages that the probe generates. Forinformation about generic ProbeWatch messages, see the IBM Tivoli Netcool/OMNIbus Probe andGateway Guide, (SC14-7530).

Table 10. ProbeWatch messages

ProbeWatch message Description Triggers/causes

Probewatch: ConnectionFailure

The probe failed to connect tothe target system in the specifiedperiod.

The remote server might beunavailable because of a networkoutage. Check the log files formore information.

Probewatch: Receivedheartbeat

The probe received a heartbeatmessage from the event source.

The occurrence of a heartbeatmessage.

Probewatch: Clientconnected

A client has connected to theprobe.

A client successfully connects tothe probe.

Probewatch: Clientdisconnected

A client disconnected from theprobe.

A client disconnected from theprobe.


Table 10. ProbeWatch messages (continued)

ProbeWatch message Description Triggers/causes

Probewatch: Logoutattempted

The probe attempted to logoutfrom the target server.

The occurrence of a logoutattempt.

Probewatch: Logoutsuccessful

The probe has successfullylogged out from the targetserver.

The occurrence of a successfullogout.

Probewatch: Logout failed The probe has failed to logoutfrom the target server.

The occurrence of anunsuccessful logout.

Probewatch: Loginattempted

A login attempt by the probe orclient.

A client attempted to login to theprobe (server) or the probe(client) attempted to login to thetarget server.

Probewatch: Login failed A login failed. A client failed to login to theprobe (server) or the probe(client) failed to login to thetarget server.

Probewatch: Loginsuccessful

A login attempt was successful. A client successfully logged in tothe probe (server) or the probe(client) successfully logged in tothe target server.

Known issues with the Java Socket ProbeThis section explains some known issues with the Java Socket probe.

Chat out operation will not complete if the probe is interrupted using SIGINT (Ctrl + C)

The OIDK Framework 2.0 (probe-sdk-java-7), which is required by the probe, has a known issuewherein the chat out operation will not have a chance to complete if the probe is interrupted usingSIGINT.

As a workaround, use the HTTP/HTTPS command interface stop command to shut down the probe,which will allow the probe to complete the chat out operation.

For instruction on configuring and running the command interface, see “HTTP/HTTPS commandinterface” on page 12

Data Stream Capture does not function as expected for multi line events

A known issue with the stream capture operation occurs if the probe is set to parse multiple line events.When parsing multiple line events, the probe does not capture the data stream and store it into thestream capture file intermittently.

As a workaround, use another tool to capture stream data, such as WireShark or tcpdump. Alternatively,enable debug logging on the DSL framework using the DSLLogConfig property file to print debugmessages and view the data going through the probe.


Probe not starting on Windows platforms after upgrade to DSL Framework 5.0

If you have upgraded your DSL Framework to version 5.0 (probe-dsl-framework-5_0), there iscurrently a known issue when running the probe on Windows platforms whereby the probe is failing tostart. This is due to the probe not updating the DSL_CLASSPATH environment variable correctly prior tostartup.

To resolve this issue, you need to update the $OMNIHOME/probes/arch/nco_p_socket_java.batfile. In this file, replace the following lines:

set DSLFW_PATH=%OMNIHOME%\probes\java\dslset DSLSOCKET_CLASSPATH=%DSLFW_PATH%\DSLFrameworkBase.jar;%DSLFW_PATH%\DSLFrameworkSocket.jar;%DSLFW_PATH%\camel-core-2.15.2.jar;%DSLFW_PATH%\camel-netty4-2.15.2.jar;%DSLFW_PATH%\netty-all-4.0.21.Final.jar;%DSLFW_PATH%\slf4j-log4j12-1.6.6.jar;%DSLFW_PATH%\slf4j-api-1.6.6.jar;%DSLFW_PATH%\log4j-1.2.17.jar;%DSLFW_PATH%\commons-pool-1.6.jar

With these lines:

call %OMNIHOME%\probes\java\dsl\dsl_framework.batset DSLSOCKET_CLASSPATH=%DSLFW_CLASSPATH%;%CAMEL_CLASSPATH%;%DSLSOCKET_CLASSPATH%


Chapter 2. Migrating from Socket Probe to JavaSocket Probe

The IBM Tivoli Netcool/OMNIbus Java Socket Probe replaces the IBM Tivoli Netcool/OMNIbus SocketProbe.

This chapter contains guidance on how to migrate from the Socket Probe to the Java Socket Probe. Themigration procedure has the following stages:

1. Review the differences between probes and identify any gaps in terms of functionality, properties,elements and rules file.

2. Install the new probe.3. Migrate the properties file.4. Customize the rules file.5. Run and test the new probe.6. Optimize property values and the rules file.

Note: Where possible, carry out the migration in a test environment or a simulation of the productionenvironment so that the work does not interfere with the production environment. Change over to usingthe Java Socket Probe in production once you are sure that it behaves in the same way as the SocketProbe.

This guide contains the following sections:

• “Comparison of probe features” on page 29• “Migration procedure” on page 30

Comparison of probe featuresBoth probes have some features in common and additional features specific to the IBM Tivoli Netcool/OMNIbus Java Socket Probe.

Common featuresThe following features are common to both probes:

Table 11. Features common to both probes

Functional category Features

Connection Connection setup to the target host and port.

Alarm parsing Alarm parsing and tokenization.

Custom ASCII message text.


Table 11. Features common to both probes (continued)


Data acquisition Ability to receive alarms.

Heartbeat status check.

Inactivity timeout.

Reconnection and probe backoff.

Support for server failover.

Support for stream capture.

Chat in and chat out scripts.

LoginScript for server.

Features specific to the IBM Tivoli Netcool/OMNIbus Java Socket ProbeThe Java Socket Probe has the following additional features that are not present in the Socket Probe:

Table 12. Features specific to Java Socket Probe


SSL connectivity Supports secure connection using Secure Sockets Layer (SSL)between probe and remote host. New properties as follows:

EnableSSL

KeyStore

KeyStorePassword

SecurityProvider

Alarm parsing New property to specify the character used as a name-value pairdelimiter, as follows:

ParserNVPDelimiter

Migration procedureUse this procedure to replace the Socket Probe with the Java Socket Probe.

• “Determining probe differences” on page 31• “Installing the Java Socket Probe” on page 31• “Migrating properties” on page 31• “Customizing the rules file” on page 33• “Running and testing the probe” on page 33• “Optimizing property values and the rules file” on page 33


Determining probe differencesJava Socket Probe includes new functionality and has dropped or replaced certain features andproperties.

Use the information in “Comparison of probe features” on page 29 to determine the features that areavailable in the Java Socket Probe.

Installing the Java Socket ProbeFollow the advice in “Installing probes” on page 2 to download and install the probe in to a testenvironment.

Migrating propertiesDetermine the values required for the properties file of the Java Socket Probe. Use the properties file fromthe Socket Probe to set the correct values.

Note: The Java Socket Probe uses different names for some properties to those used in the Socket Probeas the following table shows:

Table 13. Comparison of properties between Socket Probe and Java Socket Probe

Socket Probe Java Socket Probe Comments

BufferTimer Property replaced by GenericOMNIbus propertyBufferTimer.

Delimiter ParserElementDelimiter Property renamed.

EventTerminator ParserNextAlarmDelimiter Property renamed.

FdSetSize Property deprecated.

Footer ParserAlarmEnd Property renamed.

Header ParserAlarmStart Property renamed.

Host LocalSocketHost

EndpointSocketHost

Property split intotwo:LocalSocketHost forServer mode andEndpointSocketHost for Clientmode.

IgnoreQuotes ParserQuoteCharacter Property renamed and behaviorchanged. TheParserQuoteCharacterproperty will ignore quotecharacters when set to 0.

LineTerminator Property deprecated.

Chapter 2. Migrating from Socket Probe to Java Socket Probe 31

Table 13. Comparison of properties between Socket Probe and Java Socket Probe (continued)

Socket Probe Java Socket Probe Comments

MaxEvents Property replaced with ProbeFramework propertyMaxEventQueueSize to limitthe number of events that canbe buffered at one time.

MaxEventSize MaximumLineSize Property renamed and behaviorchanged. TheMaximumLineSize propertyspecifies the maximum linelength of incoming text data.

NoNameResolution HostNameResolution Property renamed.

NoTrim ParserTrimElement Property renamed.

ParseAsLines ParserParseAsLines Property renamed.

ParseNullFields ParserIgnoreEmptyFields Property renamed.

PollInterval ConnectTimeout Property retry behaviorreplaced with RetryConnectionTimeout property.

PortNumber LocalSocketPort

EndpointSocketPort

Property split intotwo:LocalSocketPort for Servermode and EndpointSocketPortfor Client mode.

PreserveLine ParserPreseveLine Property renamed.

ReadTimeOut ReadTimeout Property renamed.

Retry Property replaced with ProbeFramework propertiesRetryCount and RetryInterval.

SingleLines ParserSingleLines Property renamed.

SocketBuffer SocketBufferSize Property renamed.

SocketServerMode SocketMode Property renamed.

StripChars ParserStripCharacter

ParserReplaceStripChar With

Property renamed.

ThreadPoolSize MaximumPoolSize Property renamed.

Timeout IdleConnectionTimeout Property renamed.


Customizing the rules fileEdit the rules file for the Java Socket Probe to:

• Migrate custom rules from the Socket Probe rules file to the Java Socket Probe rules file.• Apply changes to the @ClassID, @Manager, @AlertKey, @AlertGroup, @Summary, @Severity, @Type,

and lookup tables as required.

Note: The Java Socket Probe may not be able to parse certain attributes if the vendor does not follow theprobe standard or has implemented their own types that are not probe compliant.

Running and testing the probeRun the probe and ensure it is receiving data from the remote host correctly.

To run and test the probe:

1. Check that the target port is available for the probe to connect and is not currently in-use by otherapplications.

2. Start the probe from the command line, specifying the minimum message level of debug. For example:

$OMNIHOME/probes/nco_p_socket_java -messagelog stdout -messagelevel debug3. Ensure that the probe connects to the socket endpoint successfully. Look for the following message in

the probe's log file:

2015-06-03T16:09:09: Information: I-JPR-000-000: Probe connected

If the probe fails to connect:

• Check and adjust the properties related to setting up a connection.• Ensure that any firewall between the probe host and the remote host is configured to allow traffic to

pass from one end to the other in both directions.4. Check that the probe correctly parses alarms with the Event Processor. Check for any unsupported

types for event parsing.5. Check the log file for errors in event parsing or unsupported types.

Check also for attributes having a null value or one that shows as 'UNKNOWN'.6. Check that events appear in the Event List and that they contain the expected elements and values.

Modify the rules file if the values in the Event List do not meet your requirements.

Optimizing property values and the rules fileAs a result of testing the probe, make any changes and optimizations necessary to the properties file andthe rules file. Then test the probe again. Repeat this process until the probe behaves correctly and theEvent List contains all the expected events with all the required elements and values.

Chapter 2. Migrating from Socket Probe to Java Socket Probe 33

Appendix A. Notices and TrademarksThis appendix contains the following sections:

• Notices• Trademarks

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

IBM may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently available inyour area. Any reference to an IBM product, program, or service is not intended to state or imply that onlythat IBM product, program, or service may be used. Any functionally equivalent product, program, orservice that does not infringe any IBM intellectual property right may be used instead. However, it is theuser'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 thisdocument. The furnishing of this document does not grant you any license to these patents. You can sendlicense inquiries, in writing, to:

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

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual PropertyDepartment in your country or send inquiries, in writing, to:

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

The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATIONPROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer ofexpress 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 periodicallymade 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 thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe 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 withoutincurring any obligation to you.

Licensees of this program who want to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:


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

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

The licensed program described in this information and all licensed material available for it are providedby IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, orany equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurements may have been estimatedthrough extrapolation. Actual results may vary. Users of this document should verify the applicable datafor their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

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

All IBM prices shown are IBM's suggested retail prices, are current and are subject to change withoutnotice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject to change before theproducts described become available.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms.

Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice 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.

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


Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-based trademarks are eitherregistered trademarks or trademarks of Adobe Systems Incorporated in the United States, othercountries, 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 theUnited States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, othercountries, 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 A. Notices and Trademarks 37

IBM®

SC27-8703-01

ibm · ibm® tivoli® netcool/omnibus java socket probe version 1.0 reference guide december 10,...

Documents