Reference Guide July 28, 2016: Ibm Tivoli Netcool/Omnibus Generic Probe For Tmf814 (V2.1, V3.0 and V3.5) (Corba)
Reference Guide July 28, 2016: Ibm Tivoli Netcool/Omnibus Generic Probe For Tmf814 (V2.1, V3.0 and V3.5) (Corba)
Reference Guide
July 28, 2016
IBM
SC27-5611-03
Notice
Before using this information and the product it supports, read the information in Appendix A, “Notices
and Trademarks,” on page 49.
Edition notice
This edition (SC27-5611-03) applies to version 4.0 of IBM Tivoli Netcool/OMNIbus Generic Probe for TMF814 (V2.1,
V3.0 and V3.5) (CORBA) and to all subsequent releases and notifications until otherwise indicated in new editions.
This edition replaces SC27-5611-02.
© Copyright International Business Machines Corporation 2013, 2016.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents
iii
iv
About this guide
The following sections contain important information about using this guide.
SC27-5611-02 March 10, Updated “Summary” on page 1 package version number to 3.0.
2016
Added “SSL-based connectivity” on page 5.
Added “Properties and command line options provided by the Java
Probe Integration Library (probe-sdk-java) version 9.0” on page
26.
Updated “Properties and command line options” on page 19.
Added descriptions for the following properties:
NotificationClientType, ORBDebug, ORBDebugFile, EnableSSL,
KeyStore, KeyStorePassword, and SecurityProtocol.
Updated “Known issues” on page 38 with new section on 32-bit
nonnative binary support.
Version 3 of the probe addresses the following enhancement
requests:
• RFE 53160: Support for processing a single StructuredEvent
added.
SC27-5611-03 July 28, 2016 Updated “Summary” on page 1 package version number to 4.0.
Added description for the ResyncAlarmObject property to
“Properties and command line options” on page 19.
Descriptions for $route_cc, $SNCState,
$transmissionParameters, and $tpsToModify added to
“Elements” on page 28.
Version 4 of the probe addresses the following enhancement
requests:
• RFE 82307: Allow the user to configure the function calls for
retrieving active alarms from EMS/NMS.
• APAR IT14347: Provide support for the following object types:
Layered ParameterList, SNC State, Route, and Termination Point
Data List in incoming events.
vi IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
For probes supported only on Windows operating systems, probe guides use the standard Windows
conventions 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 standard
UNIX conventions for specifying environment variables and describing directory paths. When using the
Windows command line with these probes, 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. Where such variables are described in the guide, both the UNIX and Windows conventions
will be used.
OMNIHOME location
Probes and older versions of Tivoli Netcool/OMNIbus use the OMNIHOME environment variable in many
configuration files. Set the value of OMNIHOME as follows:
• On UNIX and Linux, set $OMNIHOME to $NCHOME/omnibus.
• On Windows, set %OMNIHOME% to %NCHOME%\omnibus.
The IBM Tivoli Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA) acquires data
from network management systems (NMS) and element management systems (EMS) using a TMF814
(V2.1, V3.0 or V3.5) Common Object Request Broker Architecture (CORBA) interface.
This guide contains the following sections:
• “Summary” on page 1
• “Installing probes” on page 2
• “Configuring the probe” on page 3
• “Firewall considerations” on page 4
• “SSL-based connectivity” on page 5
• “Running the probe” on page 6
• “Data acquisition” on page 6
• “Properties and command line options” on page 19
• “Elements” on page 28
• “Error messages” on page 35
• “ProbeWatch messages” on page 37
• “Known issues” on page 38
Summary
Each probe works in a different way to acquire event data from its source, and therefore has specific
features, default values, and changeable properties. Use this summary information to learn about this
probe.
The following table summarizes the probe.
Table 3. Summary
Probe supported on For details of supported operating systems, see the following
Release Notice on the IBM Software Support website:
http://www-01.ibm.com/support/docview.wss?
uid=swg21653083
Requirements For details of any additional software that this probe requires,
refer to the description.txt file that is supplied in its
download package.
Federal Information Processing IBM Tivoli Netcool/OMNIbus uses the FIPS 140-2 approved
Standards (FIPS) cryptographic provider: IBM Crypto for C (ICC) certificate 384
for cryptography. This certificate is listed on the NIST website at
http://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 probes
All probes are installed in a similar way. The process involves downloading the appropriate installation
package for your operating system, installing the appropriate files for the version of Netcool/OMNIbus
that 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 about
how to locate and download the installation package for your operating system, visit the following page
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 the
following 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 topics
that are common to all probes and topics that are peculiar to this probe. For details about additional
configuration that is common to all probes, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway
Guide.
2 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Configuring the probe
After 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 to
the correct values or verify that their default values are suitable for your environment. Further
configuration is optional depending on which features of the probe you want to use.
Mandatory features:
Optional features:
Support for Unicode and non- EncodingStandard “Support for Unicode and non-
Unicode characters ORBCharEncoding Unicode characters” on page
ORBWCharDefault 14
Enables the probe to process
alarms that contain characters
encoded in UTF-8, such as Asian
languages.
Firewall considerations
When using CORBA probes in conjunction with a firewall, the firewall must be configured so that the probe
can connect to the target system.
Most CORBA probes can act as both a server (listening for connections from the target system) and a
client (connecting to the port on the target system to which the system writes events). If you are using the
probe in conjunction with a firewall, you must add the appropriate firewall rules to enable this dual
behavior.
There are three possible firewall protection scenarios, for which you must determine port numbers before
adding firewall rules:
1. If the host on which the probe is running is behind a firewall, you must determine what remote host
and port number the probe will connect to.
2. If the host on which the target system is running is behind a firewall, you must determine the incoming
port on which the probe will listen and to which the target system will connect.
3. If each host is secured with its own firewall, you must determine the following four ports:
a. The outgoing port (or port range) for the probe.
b. The hostname and port of the target system.
c. The outgoing port on which the target system sends events if the probe is running as a client.
4 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
d. The incoming port on which the probe listens for incoming events.
Note: Most, but not all, CORBA probes listen on the port specified by the ORBLocalPort property. The
default value for this property is 0, which means that an available port is selected at random. If the probe
is behind a firewall, the value of the ORBLocalPort property must be specified as a fixed port number.
CORBA probes that use EventManager or NotificationManager objects may use different hosts and ports
from those that use NamingService and EntryPoint objects. If the probe is configured to get object
references from a NamingService or EntryPoint object, you must obtain the host and port information
from the system administrator of the target system. When you have this information, you can add the
appropriate firewall rules.
SSL-based connectivity
IBM Tivoli Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA) supports Secure
Sockets Layer (SSL) connections. SSL connections 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 from
the IBM Tivoli Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA) server
administrator. Add the certificates to a local Java™ keystore so that they can be referenced by the
KeyStore property.
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.
The keytool can be found at example location:
/opt/IBM/tivoli/netcool/platform/linux2x86/jre64_1.7.0/jre/bin/keytool
Data acquisition
Each probe uses a different method to acquire data. Which method the probe uses depends on the target
system from which it receives data.
The Generic Probe for TMF814 acquires data from network management systems (NMS) and element
management systems (EMS) that implement TMF814 and use a Common Object Request Broker
Architecture (CORBA) interface. The probe connects to the NMS or EMS through the CORBA interface and
receives events from the device. The probe then processes each event to create an alarm that it forwards
on to the ObjectServer.
Data acquisition is described in the following topics:
• “Connecting to the CORBA interface” on page 7
• “Authentication” on page 11
6 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
• “Alarm retrieval and synchronization” on page 12
• “Reconnection and probe backoff strategy” on page 12
• “Inactivity” on page 13
• “Heartbeat” on page 13
• “Data stream capture” on page 13
• “Support for Unicode and non-Unicode characters” on page 14
• “Peer-to-peer failover functionality” on page 14
IOR file
Set the IORFile property to the path for the Interoperable Object Reference (IOR) file used to connect to
the target through CORBA. For example:
IORFile = "/opt/var/emssession.ior"
NamingServiceHost = "nshost1"
NamingServicePort = "8054"
NamingContextPath = "TMF_MTNM.Class/TejasNetworks.Vendor/TejasNetworks\\
/NORTH-CDG.EmsInstance/3\\.5.Version/TejasNetworks\\/NORTH-CDG.EmsSessionFactory_I"
NamingServiceIORFile = "/opt/var/ns.ior"
NamingContextPath = "TMF_MTNM.class/test/EmsSessionfactory_I"
8 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Successful connection
This example shows the messages that occur in the log file on successfully connecting to the target
system through a Naming Service running on a specified host and port:
No properties configured
The following example shows the messages that appear in the log file when none of the CORBA properties
are configured:
Not all properties set when connecting through a Naming Service host and port
The following example shows the messages that can appear in the log file when connecting through a
Naming Service using a specified host and port. In this instance one of the NamingServiceHost,
NamingServicePort and NamingContextPath properties has no value:
Properties have incorrect values when connecting through a Naming Service host and port
The following example shows the messages that can appear in the log file when connecting through a
Naming Service using a specified host and port. In this instance, one or more of the NamingServiceHost,
NamingServicePort and NamingContextPath properties has an incorrect value, or the host, port, or path
is inaccessible:
10 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
• An incorrect value for the NamingContextPath property means the ORB is unable to narrow the
configured context path on the target system.
• The host server for the Naming Service is offline.
Error: E-JPR-000-000: Failed to get the System reference from the naming
service! :
IDL:omg.org/CosNaming/NamingContext/NotFound:1.0
Error: E-JPR-000-000: Failed to resolved to Naming Context :
org.omg.CosNaming.NamingContextPackage.NotFound:
IDL:omg.org/CosNaming/NamingContext/NotFound:1.0
Error: E-JPR-000-000: Failed to get IOR Object :
com.ibm.tivoli.netcool.omnibus.probe.ProbeException:
org.omg.CosNaming.NamingContextPackage.NotFound:
IDL:omg.org/CosNaming/NamingContext/NotFound:1.0
Error: E-JPR-000-000: Failed to connect:
com.ibm.tivoli.netcool.omnibus.probe.ProbeException:
com.ibm.tivoli.netcool.omnibus.probe.ProbeException:
org.omg.CosNaming.NamingContextPackage.NotFound:
IDL:omg.org/CosNaming/NamingContext/NotFound:1.0
Error: E-JPR-000-000: Failed to get object from Naming Service IOR file:
Failed to find file /home/netcool/sim/dist/var/em.ior:
java.io.FileNotFoundException: /home/netcool/sim/dist/var/em.ior
Authentication
Once the probe has obtained a reference to the EmsSessionFactory_I object, it logs in to the target
using the values stored in the Username and Password properties. The value of the Password property
can be plain text or an AES encrypted password. To encrypt a password, use the nco_keygen utility to
create a key file and then use the nco_aes_crypt utility to encrypt the password using the key file.
Detailed instructions on how to encrypt a property value, such as Password are in the IBM Tivoli Netcool/
OMNIbus Installation and Deployment Guide. The following example shows how to encrypt the password:
1. Use nco_keygen to create a key file; for example:
$NCHOME/omnibus/bin/nco_keygen -o $NCHOME/omnibus/probes/key_file
2. Set the value of the probe's ConfigKeyFile property to the file path of the key file; for example:
ConfigKeyFile: "$NCHOME/omnibus/probes/key_file"
3. Set the value of the probe's ConfigCryptoAlg property to AES:
ConfigCryptoAlg: "AES"
4. Use nco_aes_crypt to encrypt the password; for example:
$NCHOME/omnibus/bin/nco_aes_crypt -c AES -k key_file password
Alarm retrieval
Once the probe has received any existing alarms, it connects to the Subscriber object and uses the
CORBA notification push model to receive new alarms from the EMS. The probe receives those alarms as
they are generated at the EMS.
The probe parses each alarm it receives and forwards it to the ObjectServer.
Resynchronization
The probe can resynchronize with the EMS periodically. The frequency of any resynchronization is
determined by the value of the ResyncInterval property. When the property has a value of 0, which is the
default value, the probe never resynchronizes. Any other value of ResyncInterval defines the interval, in
seconds, between successive resynchronization operations. For each operation the probe receives a list of
all active alarms in the same way as it does at startup. The probe then resumes waiting for new alarms
from the EMS.
During resynchronization operations, the probe receives alarms in batches when the ResyncBatchSize
property has a positive value (the default value is 100). The minimum batch size is 1.
Resynchronization filters
You can apply filters during a resynchronization operation to limit the number of alarms returned from the
EMS. The probe provides two properties that enable you to define filters:
• ResyncProbableCauseFilter
• ResyncSeverityFilter
You can use either filter individually or both filters together.
The filters define values for alarms to exclude from a resynchronization operation when they contain a
particular value. For example, if you set ResyncSeverityFilter to the value PS_MINOR, all alarms with that
severity setting are excluded from the resynchronization operation.
12 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
and so on up to a maximum of 4095 seconds. If this limit, or the number of connection attempts is
reached, the probe shuts down.
Inactivity
The probe can disconnect from the target system and shut down if there is no event activity for a
predefined amount of time.
You can use the Inactivity property to specify how long, in seconds, the probe waits before disconnecting
from the target system and shutting down. If the probe receives no events during that time, it disconnects
from the target system and shuts down. To ensure that the probe never disconnects from the target
system, set the value of the property to 0, which is the default value.
Heartbeat
The probe can disconnect from the target system if the connection between them becomes unavailable.
You can use the HeartbeatInterval property to specify whether the probe periodically checks that the
connection to the target system is available and how often it performs that check. The probe shuts down if
it detects that the connection to the target system is unavailable.
When the HeartbeatInterval property has a value of 0 the probe does not check the availability of the
connection. Any other positive value defines the number of seconds between each check of the
connection's availability.
Note: Once the probe shuts down it may restart again, depending on the value set for the RetryCount
property. If the value set for RetryCount is 0, the probe does not restart. For any other positive value the
probe follows the reconnection policy. See “Reconnection and probe backoff strategy” on page 12 for
more information.
To check the connection to the target system, the probe sends a ping command (using the TMF standard
function EmsSession_I_ping) and waits for a response from the target system.
The probe also disconnects from the target system if it receives an endSession request from the NMS.
This may occur if the target system restarts or is shut down.
export LANG=zh_CN.utf8
export LC_ALL=zh_CN.utf8
Property Value
EncodingStandard UTF-8
ORBCharEncoding UTF8
ORBWChardefault UTF16
4. Configure the ObjectServer to enable the insertion of data that uses UTF-8 encoding. The IBM Tivoli
Netcool/OMNIbus Administration Guide shows how to create, configure, and run an ObjectServer in
UTF-8 mode.
5. Run the probe or restart it, if it is already running.
14 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
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 corresponding slave
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"
ackAlarm
Use the ackAlarm command to acknowledge an alarm.
The format of the -data option for the ackAlarm command is:
-data '{"command":"ackAlarm", "params":[{"alarmId":"alarmId", "emsId":"emsId",
"managedElementId":"managedElementId", "username":"username"}]}'
Where:
• alarmId is the identifier stored in the alarm's emsAlarmId field.
• emsId is the identifier stored in the alarm's EMS field.
• managedElementId is the identifier stored in the alarm's ManagedElement field.
• username is the user name of the user acknowledging the alarm (the default is root).
The following example acknowledges the alarm with the following characteristics:
Alarm Identifier: alarm1
EMS Identifier: EMS1
Managed Element Identifier: ME1
Username: root
$OMNIHOME/bin/nco_http -uri http://test1.example.com:6789/probes/generic_tmf814
-datatype application/JSON -method POST -data '{"command":"ackAlarm", "params":
[{"alarmId":"alarm1", "emsId":"EMS1", "managedElementId":"ME1",
"username":"root"}]}'
help
Use the help command to receive help information about the HTTP/HTTPS command interface.
16 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
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://test1.example.com:6789/probes/generic_tmf814
-datatype application/JSON -method POST -data '{"command":"help", "params":[]}'
The response from the probe includes the following message:
Information: I-UNK-104-002: {"response":"Available commands: ackAlarm(alarmId
String,emsId String,managedElementId String,username String),
unackAlarm(alarmId String,emsId String,managedElementId String,username
String), resync(), resyncFilter(excludeSeverity String,excludePbCause String),
stop() ","status":"200"}
resync
Use the resync command to perform a resynchronization with the endpoint using the value specified by
the ResyncSeverityFilter and ResyncProbableCauseFilter properties.
The format of the -data option for the resync command is:
-data '{"command":"resync", "params":[]}'
The following example resynchronizes the probe:
$OMNIHOME/bin/nco_http -uri http://test1.example.com:6789/probes/generic_tmf814
-datatype application/JSON -method POST -data '{"command":"resync", "params":
[]}'
resyncFilter
Use the resyncFilter command to perform a resynchronization using a custom filter.
The format of the -data option for the resyncFilter command is:
-data '{"command":"resyncFilter","params":[{"excludeSeverity":"sev=severities",
"excludePbCause":"pbCause=probable-causes"}]}'
Where:
• severities is a list of severities to exclude when the probe resynchronizes with the CORBA interface.
Separate each entry in the list with a semicolon.
• probable-causes is a list of probable causes to exclude when the probe resynchronizes with the CORBA
interface. Separate each entry in the list with a semicolon.
The following example resynchronizes the probe an excludes alarms with a severity of PS_CLEARED or
PS_WARNING:
$OMNIHOME/bin/nco_http -uri http://test1.example.com:6789/probes/generic_tmf814
-datatype application/JSON -method POST -data '{"command":"resyncFilter",
"params":[{"excludeSeverity":"sev=PS_CLEARED;PS_WARNING",
"excludePbCause":"pbCause="}]}'
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://test1.example.com:6789/probes/generic_tmf814
-datatype application/JSON -method POST -data '{"command":"stop", "params":[]}'
These messages can also help to isolate problems with a command. For example, the following shows the
log messages for an unackAlarm command that contained an invalid alarm identifier.
18 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
You can use the one or more of the following nco_http properties to hold default values for the
equivalent options on the nco_http command line:
Data
DataType
Method
URI
Specify the value of each property in the same way as you would on the command line. Once you have
these values in place you do not need to specify the corresponding command line switch unless you want
to override the value of the property.
The following is an example of the use of the properties file and the simplification of the nco_http
command that results. In this example, the nco_http properties file contains the following values (note
that line breaks appear for presentational purposes only; when editing the properties use one line for
each property value):
IORFile string -iorfile string Use this property to specify the path of
the Interoperable Object Reference
(IOR) file used to connect to the target
through the CORBA interface. If you do
not provide a value for this property,
use the NamingContextPath with the
NamingServiceHost and
NamingServicePort properties or the
NamingServiceIORFile property to
define the Naming Service to use
instead.
The default is "".
KeyStore string -keystore string Use this property to specify the location
of the keystore file that contains the
client certificate for SSL and the trusted
authority certificate.
The default is "".
NamingContextPath string -nspath string Use this property to specify the location
of the object in the Naming Service. If
using a Naming Service to connect to
the CORBA interface, always set this
property.
The default is "".
20 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 5. Properties and command line options (continued)
NamingServiceHost string -nshost string Use this property to specify the name of
the host that runs the Naming Service.
If you do not use the IORFile property
define the location of the Naming
Service using this property, together
with the NamingServicePort and
NamingContextPathproperties, or the
NamingServiceIORFile and
NamingContextPath properties.
The default is: "".
NamingServiceIORFile string -nsiorfile string Use this property to specify the location
of the IOR file that contains the root
context of the Naming Service. If you do
not provide a value for the IORFile
property, use this property and the
NamingContextPath property or the
NamingServiceHost,
NamingServicePort, and
NamingContextPath properties to
define the Naming Service to use to
obtain the reference to the
EmsFactorySession_I object.
The default is: "".
NamingServicePort integer -nsport integer Use this property to specify the port on
the host defined by
NamingServiceHost through which to
connect to the Naming Service. If you
do not use the IORFile property, use
this property, together with the
NamingServiceHost property and
NamingContextPath property, or the
NamingServiceIORFile and
NamingContextPath properties.
The default is: 0.
NotificationClientType string -notificationclienttype string Use this property to define the probe
subscription for notification service.
SEQUENCE_EVENT: The probe will
receive a sequence of StructuredEvent.
STRUCTURED_EVENT: The probe will
receive a single StructuredEvent during
every notification cycle.
The default is: SEQUENCE_EVENT.
ORBCharEncoding string -orncharencoding string Use this property to specify the native
character encoding set that the Oject
Request Broker (ORB) uses for
character data. Possible values for this
property are:
ISO8859_1
UTF8
The default is: ISO8859_1.
ORBDebugFile string -orbdebugfile string Use this property to specify the ORB
debugging log file.
The default is "".
ORBLocalHost string -orblocalhost string Use this property to specify the local
host used by the server-side ORB to
place the server's host name or IP
address into the IOR of a remote object.
The default is: "".
ORBLocalPort integer -orblocalport integer Use this property to specify the local
port that the ORB listens on for
connections from the probe.
The default is: 0 (the ORB selects a port
at random).
ORBWCharDefault string -orbwchardefault string Use this property to specify the wide
character (wchar) set that the IBM ORB
uses when communicating with other
ORBs that do not publish a wchar set.
Possible values for this property are:
UCS2
UTF16
The default is: UTF16.
22 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 5. Properties and command line options (continued)
ReleaseTMF814 string -releasetmf814 string Use this property to specify the version
of TMF that the probe should
implement. Possible values for this
property are:
V2.1
V3.0
V3.5
The default is: V3.0.
ResyncAlarmObject string -resyncalarmobject string Use this property to specify the objects
against which the alarms retrieved
during resynchronization are raised.
24 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 5. Properties and command line options (continued)
SecurityProtocol string -securityprotocol string Use this property to specify the security
protocol used.
The default is TLSv1.2.
StreamCapture integer -streamcapture integer Use this property to specify whether the
stream capture feature is enabled. The
values this property can have are:
1: The probe uses the stream capture
feature.
0: The probe does not use the stream
capture feature.
The default is: 0.
Note: If you set the value of this
property to 1, define a value for the
StreamCaptureFilePath property as
well.
Username string -username string Use this property to specify the account
to use when logging in to the target
system. Always define a value for this
property and the Password property.
The default is: "".
CommandPort integer -commandport integer Use this property to specify the port to
which users can Telnet to communicate
with the probe using the Command Line
Interface (CLI) supplied.
The default is 6970.
DataBackupFile string -databackupfile string Use this property to specify the path to
the file that stores data between probe
sessions.
The default is "".
Note: Specify the path relative to
$OMNIHOME/var.
26 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 6. Properties and command line options (continued)
Inactivity integer -inactivity integer Use this property to specify the length
of time (in seconds) that the probe
allows the port to receive no incoming
data before disconnecting.
The default is 0 (which instructs the
probe to not disconnect during periods
of inactivity).
InactivityAction string -inactivityaction string Use this property to specify the action
the probe takes when inactivity timeout
is reached.
SHUTDOWN: Sends a ProbeWatch
message to notify user and shuts down
the probe.
CONTINUE: Sends a ProbeWatch
message to notify user and do not shut
down the probe.
The default is SHUTDOWN.
InitialResync string -initialresync string Use this property to specify whether the
probe requests all active alarms from
the host server on startup. This
property takes the following values:
false: The probe does not request
resynchronization on startup.
true: The probe requests
resynchronization on startup.
For most probes, the default value for
this property is false.
If you are running the JDBC Probe, the
default value for the InitialResync
property is true. This is because the
JDBC Probe only acquires data using
the resynchronization process.
ResyncInterval integer -resyncinterval integer Use this property to specify the interval
(in seconds) at which the probe makes
successive resynchronization requests.
For most probes, the default value for
this property is 0 (which instructs the
probe to not make successive
resynchronization requests).
If you are running the JDBC Probe, the
default value for the ResyncInterval
property is 60. This is because the
JDBC Probe only acquires data using
the resynchronization process.
RetryCount integer -retrycount integer Use this property to specify how many
times the probe attempts to retry a
connection before shutting down.
The default is 0 (which instructs the
probe to not retry the connection).
RetryInterval integer -retryinterval integer Use this property to specify the length
of time (in seconds) that the probe
waits between successive connection
attempts to the target system.
The default is 0 (which instructs the
probe to use an exponentially
increasing period between successive
connection attempts, for example, the
probe will wait for 1 second, then 2
seconds, then 4 seconds, and so forth).
Elements
The probe breaks event data down into tokens and parses them into elements. Elements are used to
assign values to ObjectServer fields; the field values contain the event details in a form that the
ObjectServer understands.
The following tables describe the elements that the Generic Probe for TMF814 generates. Not all the
elements described are generated for each event; the elements that the probe generates depends upon
the event type. The data type and, where applicable, enumeration values for these elements are defined
in the TMF814 standard.
28 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 7. Elements specific to events
$groupName This element indicates the name of the group for this
event.
$objectName_EMS This element contains the name of the EMS that the
alarm relates to.
$route_ccentry number_direction This element indicates the direction of data flow. This
element can take one of the following values:
UNIdirectional: From the source termination point to
the sink termination point.
BIdirectional : A two-way communication from and to
both termination points.
30 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 7. Elements specific to events (continued)
$SNCState This element contains the SNC state of the event. This
element can take the following values:
SNCS_PENDING: The SNC has been created by an
NMS and has not been activated by any NMS; or the
SNC has been successfully deactivated by an NMS.
SNCS_ACTIVE: The SNC is not in pending state, a
route has been assigned to the SNC and all cross-
connects for the SNC are active in the network.
SNCS_PARTIAL: The SNC is not in pending state, and
either a route has not been assigned to the SNC, or
not all of the cross-connects of the SNC are active in
the network.
SNCS_NONEXISTENT: This is used in to report SNCs
that have been deleted.
32 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 8. Elements specific to protection switch events (continued)
34 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 10. Elements specific to threshold crossing alerts
Error messages
Error messages provide information about problems that occur while running the probe. You can use the
information that they contain to resolve such problems.
The following table describes the error messages specific to this probe. For information about generic
error messages, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.
Alarm alarmID Error in The probe could not acknowledge Check that the you have specified
acknowledge. the alarm specified in the the parameters for the command
ackAlarm command to the HTTP/ correctly, in particular the alarm
HTTPS command interface. identifier.
Error in filtered An error occurred while Check that you have specified the
resynchronization processing the resyncFilter command correctly, in particular
command to the HTTP/HTTPS the attributes of the filter.
command interface.
Error in An error occurred while Check that you have specified the
resynchronization processing the resync command command correctly. Also check
to the HTTP/HTTPS command that the values of the
interface. ResyncProbableCause and
ResynchSeverityFilter are
correctly specified.
Failed to convert IOR The probe failed to convert an IOR Check that the value of the
to object into an object reference. IORFile property is correct and up
to date. Also, make sure that the
target system is running correctly.
Failed to get active The probe received an exception Check the properties related to
alarms while trying to retrieve active resynchronization, in particular
alarms from the EMS manager. the filter properties. Check that
the target system is running
correctly and that there is not an
IDL type mismatch.
Failed to get EMS The probe is unable to retrieve an Check that the target system is
Manager reference EMS Manager reference from the running and that there is not an
target system. IDL file mismatch.
Failed to get next The probe is unable to retrieve the Check there is not an IDL file
iterated alarm batch next batch of active alarms. mismatch or contact IBM Support.
Failed to narrow The probe is unable to narrow the Check that the target system is
manager reference EMS Manager reference from the running correctly and that there is
target system. not an IDL file mismatch.
Failed to retrieve The probe was unable to retrieve The probe could not retrieve the
TMF814 Release the TMF814 release. value of the TMF814 release.
Check the value of the
ReleaseTMF814 property and
adjust as necessary. In addition,
make sure that the properties file
has not become corrupted.
Failed to start The probe is unable to start due to Check that all properties have the
an environment problem or an correct, and valid, values as
unsupported TMF814 release. defined in “Properties and
command line options” on page
19.
Cannot parse attribute The probe cannot parse the Check that the attribute is a
attribute-name with attribute named in the error supported type and is compliant
type [type] message. with the TMF814 standard. Refer
to the elements that the probe
supports. You can also contact
IBM Software Support for
assistance.
Failed to close file The probe failed to close the Check that the IOR file is in the
ior_file specified IOR file. correct place, defined by the
NamingServiceIORFile property
or the IORFile property. In
addition, check that the directory
that holds the file is not set to read
only.
Loading TMF814 jar The ReleaseTMF814 property has Ensure the property has one of the
release: UNKNOWN from an incorrect, unrecognized value. values defined in “Properties and
path file-path This message may occur with command line options” on page
Failed to start. 19.
36 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 11. Error messages (continued)
Stream capture fails The probe was not able to capture Check that the value of the
raw event data. StreamCaptureFilePath property
is a valid file path and tat the path
exists.
Unsupported TMF814 The ReleaseTMF814 property has Ensure the property has one of the
release an incorrect, unrecognized value. values defined in “Properties and
command line options” on page
19.
Unable to get EMS The probe is unable to connect to Check that the Username and
session the target EMS session. Password properties contain the
correct values for accessing the
target system. In addition, check
that the target system is running
correctly.
Unable to ping the EMS The probe is unable to poll the Check that the target system is
session target system during heartbeat running correctly.
checking.
ProbeWatch messages
During normal operations, the probe generates ProbeWatch messages and sends them to the
ObjectServer. These messages tell the ObjectServer how the probe is running.
The following table describes the ProbeWatch error messages that the probe generates. For information
about generic ProbeWatch messages, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.
ClientSession event The EMS has failed to push one or The EMS indicated that events are
loss occurred more events to the probe. As a being lost and that it is not able to
result the probe is now out of provide the relevant notifications.
synchronzation with the EMS.
ClientSession event The EMS has restored service and The EMS indicated that the event
loss cleared can now provide the relevant loss period is over and that it is
events to the probe. On reception able to provide the relevant
of this notification the probe can notifications once more.
now resynchronize with the EMS.
SHUTDOWN. No events The probe has shut down due to The probe has not received any
received for n seconds inactivity. events for n seconds and so is
shutting down. The value of the
Inactivity property determines
the value of n.
Known issues
You can ignore this message because the command completes successfully as subsequent messages
show.
If a command is missing a single quotation mark (') or a double quotation mark ("), the following
messages appear in the log file:
Null properties
The probe's properties file allows you to set values for the following properties. However, those properties
have no effect as the features they correspond to are not implemented in this release of the probe.
DataBackupFile
RotateEndpoint
38 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Chapter 2. Migrating from existing probes
There are a number of IBM Tivoli Netcool/OMNIbus probes that monitor TMF-814 compliant systems:
• Probe for Alcatel-Lucent NaviScore 9.1
• Probe for Huawei T2000 (CORBA)
• Probe for Nokia-Siemens TNMS (CORBA)
• Probe for ECI Lightsoft (CORBA)
The Generic Probe for TMF814 can also monitor the same systems. This chapter contains guidance on
how to migrate from one of the existing probes to the generic probe. The migration procedure has the
following stages:
1. Ensure the generic probe contains all the features of the existing probe that you need.
2. Determine any additional features of the generic probe that you want to use.
3. Install the generic probe.
4. Migrate the properties file.
5. Customize the rules file.
6. Run and test the generic probe.
7. Optimize property values and the rules file.
Note: Where possible, carry out the migration in a test environment or a simulation of the production
environment so that the work does not interfere with the production environment. Change over to using
the Generic Probe for TMF814 in production once you are sure that it behaves in the same way as the
probe it is replacing.
Common features
The following features are common to all the TMF814 probes:
Resynchronization Retrieve alarms from the system on startup before receiving new
alarms.
Retrieve alarms using a severity filter.
Retrieve alarms in batches.
Data acquisition Authentication with the NMS or EMS using a username and
password.
Ability to receive alarms and notifications.
Heartbeat status check.
Inactivity timeout.
Reconnection and probe backoff.
Support for Unicode and non-Unicode characters.
Resynchronization at intervals
In addition to the initial resynchronization with the NMS or EMS, the generic probe also has the ability to
resynchronize at regular intervals, specified by the ResyncInterval property. “Alarm retrieval and
synchronization” on page 12 has more information on resynchronization at intervals.
40 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Features not available in the Generic Probe for TMF814
The Probe for Huawei T2000 (CORBA) has a number of features that are not currently available in the
generic probe:
• Event synchronization with the ObjectServer
• EMS Server failover
• Persistence notification
Before deploying the Generic Probe for TMF814 ensure that you do not require any of these features.
Migration procedure
Use this procedure to replace a system-specific probe with the generic probe.
• “Determining the features to use” on page 41
• “Installing the Generic Probe for TMF814” on page 41
• “Migrating properties” on page 41
• “Customizing the rules file” on page 43
• “Running and testing the probe” on page 46
• “Optimizing property values and the rules file” on page 47
Migrating properties
Determine the values required for the properties file of the generic probe. As shown in “Configuring the
probe” on page 3 there are two groups of properties:
• Required settings that all installations of the probe must have.
• Optional settings that related to features that are not mandatory.
Use the properties file for the system-specific probe to set the correct values in the generic probe.
Required settings
The required settings relate to the following:
• CORBA connection method
• Authentication
• TMF release version in use
There are two ways of connecting to the CORBA interface, as shown in “Connecting to the CORBA
interface” on page 7. From the implementation in the system specific probe, determine which you want to
Copy the values for the authentication properties from the system-specific properties file to the file for the
generic probe.
The ReleaseTMF814 property is found only in the generic probe. Set this property to the version of the
TMF814 standard that the NMS or EMS implements.
Optional settings
Optional settings relate to features of the probe that a site may decide to use or not, as their business
requires:
• Resynchronization policy
• Reconnection policy
• Inactivity policy
• Heartbeat policy
• Support for Unicode and non-Unicode characters
• Peer-to-peer failover pair
• HTTP/HTTPS command interface
• Running multiple instances of the probe
The table in “Configuring the probe” on page 3 lists the properties associated with each feature. For
features that you use in the system-specific probe, set the values of the generic probe properties to
appropriate values. For features that you do not use in the system-specific probe, or that the system-
specific probe does not provide, decide on the values to use and set the generic properties file
accordingly. Follow the advice in the sections referenced in the configuration table for details of how to
set the properties.
Note that the generic probe uses different names for some properties to those used in the system-
specific probes, as the following table shows:
42 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 15. Properties with different names in the generic probe (continued)
System-specific property Generic property
ResynchBatchSize ResyncBatchSize
Retry RetryCount
RetryInterval
Timeout Inactivity
In particular notice that there is no direct correspondence between the properties that filter alarms by
severity. From the system-specific probe's properties file, determine the severities that you want to filter
and then construct the appropriate value for the ResyncSeverityFilter property of the generic probe.
“Properties and command line options” on page 19 defines the format for the value of the
ResyncSeverityFilter property.
Attributes
There are some differences in the names or values of attributes between the system-specific probes and
the generic probe. The following table indicates where there are differences, and shows the element that
the TMF814 standard defines. Be sure to make the necessary changes if you copy over rules from the
system-specific rules file.
44 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
Table 16. Differences in rules file attributes (continued)
TMF814 element name System-specific probes Generic probe
protectedE $protectedE= $protectedE_name="value"
"equipmentlist;"
For example:
Here, equipmentlist is a list of $protectedE_a="1"
equipment attributes and their $protectedE_b="2"
values separated by commas. For $protectedE_c="3"
example: $protectedE="a=1,
b=2, c=3;"
Troubleshoot any synchronization errors, including the values of the synchronization properties. See
“Alarm retrieval and synchronization” on page 12 for information on synchronization.
4. Check that the probe correctly parses alarms with the Event Processor. Check for any unsupported
types for event parsing. For example:
5. Check the log file for errors that occur from parsing unsupported types of event. For example:
Check also for attributes having a null value or one that shows as 'UNKNOWN'.
46 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
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.
Notices
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:
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:
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.
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:
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.
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.
50 IBM® Tivoli® Netcool/OMNIbus Generic Probe for TMF814 (V2.1, V3.0 and V3.5) (CORBA): Reference Guide
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.
SC27-5611-03