Tivoli IBM Tivoli Netcool/OMNIbus SNMP Probe

Reference Guide
April 30, 2009
Version 10.0.6299
SC23-6003-04

Tivoli IBM Tivoli Netcool/OMNIbus SNMP Probe

Reference Guide
April 30, 2009
Version 10.0.6299
SC23-6003-04

Note
Before using this information and the product it supports, read the information in Notices and Trademarks, on page 23.
Edition notice
This edition applies to version 10.0.6299 of IBM Tivoli Netcool/OMNIbus SNMP Probe (SC23-6003-04) and to all
subsequent releases and modifications until otherwise indicated in new editions.
This edition replaces SC23-6003-03.
Copyright International Business Machines Corporation 2006, 2009.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Document control page . . . . . . . . v
IBM Tivoli Netcool/OMNIbus SNMP
Probe. . . . . . . . . . . . . . . . 1
Summary . . . . . . . . . . . . . . . 1
Features of the SNMP Probe . . . . . . . . . 3
Internationalization support . . . . . . . . . 3
Example multi-byte character set on Solaris . . . 3
Example multi-byte configuration on Windows . . 4
Installing the probe . . . . . . . . . . . . 4
Installing the Configuration Analyser . . . . . . 4
Running the Configuration Analyser . . . . . . 5
Requirements . . . . . . . . . . . . . . 7
SNMP V3 support . . . . . . . . . . . . 7
Adding new users to the configuration file . . . 7
Traps and informs . . . . . . . . . . . 8
Example usage . . . . . . . . . . . . 8
Running the probe as SUID root . . . . . . . 8
IP environment . . . . . . . . . . . . 9
Federal Information Processing Standards (FIPS)
support . . . . . . . . . . . . . . . . 9
Data acquisition . . . . . . . . . . . . . 10
Buffer settings . . . . . . . . . . . . 10
Trap queue size . . . . . . . . . . . . 11
Rules file . . . . . . . . . . . . . . 11
IP address resolution . . . . . . . . . . 11
Peer-to-peer failover functionality . . . . . . 11
Properties and command line options . . . . . 12
Elements . . . . . . . . . . . . . . . 17
Static elements . . . . . . . . . . . . 17
Dynamic elements . . . . . . . . . . . 19
Generic trap handling . . . . . . . . . . . 19
Error messages . . . . . . . . . . . . . 20
Error messages generated by the Configuration
Analyser . . . . . . . . . . . . . . . 21
ProbeWatch messages . . . . . . . . . . . 22
Appendix. Notices and Trademarks . . 23
Notices . . . . . . . . . . . . . . . . 23
Trademarks . . . . . . . . . . . . . . 25
Copyright IBM Corp. 2006, 2009 iii
iv IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Document control page
Use this information to track changes between versions of this guide.
The IBM Tivoli Netcool/OMNIbus SNMP Probe documentation is provided in
softcopy format only. To obtain the most recent version, visit the IBM Tivoli
Netcool Information 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
00 October 10,
2007
First IBM publication.
01 December 29,
2007
VRM number updated.
Summary table updated.
Note about the lack of support for V3 privacy on the
Windows

version of the probe removed. The Windows

version of the probe now supports V3 privacy and
authentication.
List of supported traps and informs clarified.
List of statistics logged by the probe updated.
Tip about setting the TrapQueueMax property to avoid
dropping events during a trap burst added.
02 July 25, 2008 Support for Linux

for zSeries

added.
IPv6 support information added.
Information about the compatibilty of the probe with
Federal Information Protocol Standards (FIPS) added.
03 April 30, 2009 Support for the Configuration Analyser added.
Summary section updated.
Installing the probe topic added.
Installing the Configuration Analyser topic added.
Configuring the probe environment topic updated.
Running the Configuration Analyser topic added.
DSALog, DSAPeriod, and snmpv3ONLY properties
added.
New ProbeWatch message added.
Copyright IBM Corp. 2006, 2009 v
vi IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
IBM Tivoli Netcool/OMNIbus SNMP Probe
The IBM Tivoli Netcool/OMNIbus SNMP Probe monitors SNMP traps and informs
on both UDP and TCP sockets concurrently.
The following topics describe the probe and how it works:
v Summary
v Features of the SNMP Probe on page 3
v Internationalization support on page 3
v Installing the probe on page 4
v Installing the Configuration Analyser on page 4
v Running the Configuration Analyser on page 5
v Requirements on page 7
v SNMP V3 support on page 7
v Federal Information Processing Standards (FIPS) support on page 9
v Data acquisition on page 10
v Properties and command line options on page 12
v Elements on page 17
v Generic trap handling on page 19
v Error messages on page 20
v Error messages generated by the Configuration Analyser on page 21
v ProbeWatch messages on page 22
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 2. Summary
Probe target SNMP traps and informs
Probe executable file name nco_p_mttrapd
mttrapd.check.jar (enables the probe to run
with the Configuration Analyser)
Patch number 10.0
Copyright IBM Corp. 2006, 2009 1
Table 2. Summary (continued)
Probe supported on Solaris, HP-UX, AIX

, Linux, Linux for

zSeries, Windows
For details of the operating system versions
on which this probe is supported, see the
following page on the IBM Tivoli Netcool
Information Center:
http://publib.boulder.ibm.com/infocenter/
tivihelp/v8r1/index.jsp?topic=/
com.ibm.netcool_OMNIbus.doc/
Supported_Platforms.htm
Properties file $OMNIHOME/probes/arch/mttrapd.props
(UNIX

)
%OMNIHOME%\probes\arch\mttrapd.props
(Windows)
Rules file $OMNIHOME/probes/arch/mttrapd.rules
(UNIX)
%OMNIHOME%\probes\arch\mttrapd.rules
(Windows)
Requirements A currently supported version of IBM Tivoli
Netcool/OMNIbus.
Note: To use the Configuration Analyser,
you must be running Netcool/OMNIbus
V7.0 or later and you must install
tools-config-analyser-0.
probe-compatibility-3.x (UNIX only, on
IBM Tivoli Netcool/OMNIbus 3.6)
common-libcrypt-1_0 package (for IBM
Tivoli Netcool/OMNIbus 7.1 and 7.2 only)
common-libcrypt-1_0 patch (for IBM Tivoli
Netcool/OMNIbus 7.0 only)
Connection method Listens for SNMP traps using UDP, TCP,
UDPV6, and TCPV6
Remote connectivity Not available
Licensing Electronic licensing was deprecated with the
release of IBM Tivoli Netcool V7.2. All IBM
Tivoli Netcool V7.2 (and later) products use
the IBM software licensing process.
Peer-to-peer failover functionality Available
Internationalization support Available
2 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Table 2. Summary (continued)
IP environment For communications between the probe and
IBM Tivoli Netcool/OMNIbus V7.2, the IPv6
environment is supported on UNIX
platforms only.
For communications between the probe and
IBM Tivoli Netcool/OMNIbus V7.2.1, the
IPv6 environment is supported on all
plaforms.
For communications between the probe and
the device, the probe supports the IPv6
environment on all platforms.
Federal Information Protocol Standards
(FIPS)
The IBM Tivoli Netcool/OMNIbus SNMP
Probe is compatible with FIPS.
Features of the SNMP Probe
The IBM Tivoli Netcool/OMNIbus SNMP Probe has various features that allow it
to handle generic traps.
The probe has the following features:
v Handles a high volume and high rate of traps
v Receives traps independently of trap processing using an internal queue
mechanism
v Handles high trap rates and high burst rates using two buffers: one buffer is for
all of the sockets that the probe monitors, and the another buffer is an internal
queue between the reader and writer sides of the probe
v Supports SNMP V1 traps, V2c traps, and V3 traps
v Supports SNMP V2c and V3 traps and informs
v Uses a USM-based V3 security model
Internationalization support
The probe supports multibyte character sets. To view the character sets correctly,
you must configure the locale settings on the host machine correctly. Each
multibyte character set is configured slightly differently on each platform.
Example multi-byte character set on Solaris
The following steps describe how to configure Solaris to use the Japanese character
set:
1. Install the necessary components for Japanese on to the host machine using the
Solaris CD.
2. Set the LANG and LC_ALL environment variables to ja_JP PCK. This uses SJIS
encoding.
Note: You may have to set the LANG in the host machines default settings file
and reboot it to make the changes take effect.
3. Make sure that the file $OMNIHOME/platform/arch/locales/locales.dat has the
following entry:
locale = ja_JP PCK, japanese, sjis
IBM Tivoli Netcool/OMNIbus SNMP Probe 3
where ja_JP PCK is the vendor locale, japanese is the Sybase language, and
sjis is the Sybase character set.
Example multi-byte configuration on Windows
The following steps describe how to configure Windows to use the Japanese
character set:
1. Install the necessary language pack using the Control Panel.
Note: You must reboot the machine to make the character set available.
2. Make sure the file,%OMNIHOME%\locales\locales.dat, has the following element:
locale = jpn, japanese, sjis
where jpn is the vendor locale, japanese is the Sybase language, and sjis is
the Sybase character set
Note: You must reboot the machine to be able to use the probe as a service in the
required locale.
Installing the probe
All probes follow a very similar installation procedure.
Installing the probe on UNIX platforms
To install the SNMP Probe on UNIX platforms, run the following command:
$OMNIHOME/install/nco_patch -install patch
Where patch is the file name of the patch that you have downloaded.
Installing the probe on Windows platforms
To install the SNMP Probe on Windows platforms, use the following steps:
1. Unzip the probe_zip_file file into a temporary location. (Where
probe_zip_file is the file name of the zip file that you downloaded.)
2. Copy the binary (and .dll if present) into your probe binary directory.
3. Copy the default .props and .rules into your probe binary directory if required.
To install the SNMP Probe as a Windows service, use the following steps:
1. Register the probe with the Service Control Manager by running the following
command:
probe_name.exe -install
(Where probe_name is the name of the executable in the zip file.)
2. If you are running the probe on the same machine as the ObjectServer, run the
following command line to register the dependency of the probe on the
ObjectServer service:
probe_name.exe -install -depend NCOObjectServer
3. Activate the probe by selecting Control Panel Services.
Installing the Configuration Analyser
This version of the probe supports the Configuration Analyser. It is supplied in a
separate patch, and can be installed either before or after the probe.
4 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
The Configuration Analyser allows you to fine-tune the configuration of the probe.
It checks all the probe settings and writes related messages about the configuration
to the probe message log.
Installing the Configuration Analyser on UNIX platforms
To install the Configuration Analyser on UNIX platforms, use the following steps:
1. Install Java 1.5 if it is not already installed on your system.
2. Run the following command:
$OMNIHOME/install/nco_patch -install patch
Where patch is the name of the Configuration Analsyer patch that you
downloaded.
Installing the Configuration Analyser on Windows platforms
To install the Configuration Analyser on Windows platforms, use the following
steps:
1. Install Java 1.5 if it is not already installed on your system.
2. Unzip the probe_zip_file file into a temporary location (where probe_zip_file
is the file name of the zip file that you downloaded)
3. Copy jlog.jar to %OMNIHOME%\java\jars
4. Copy ConfigAnalyser.jar to %OMNIHOME%\bin
5. Copy configAnalyser.xsd to %OMNIHOME%\probes\win32
6. Copy run_analyser.bat to %OMNIHOME%\probes\win32
Running the Configuration Analyser
Each probe that supports the Configuration Analyser is supplied with a JAR file
(probe_name.check.jar). This file contains details of the tests to be performed and
a set of predefined messages library. Using this JAR file, the analyser runs the tests
against the probe configuration test file, and writes the related messages taken
from the messages library to the probe log file.
When the probe launches the Configuration Analsyer, the analyser runs a series of
checks on the probe. The resultant output is displayed in real time on the
command line and is stored in $OMNIHOME/logs/probe_name.check.log (the test
file).
The Configuration Analyser checks the syntax of the test file against the rules
defined in the $OMNIHOME/arch/ConfigAnalyser.xsd file.
The Configuration Analyser then runs sequentially through all the tests detailed in
the xml file inside probe_name.check.jar, outputting any appropriate suggestions
from the internationalized message file also in the jar file.
Checks performed by the Configuration Analyser
The following is a list of the items that the Configuration Analyser checks for all
probes:
v Whether the primary ObjectServer is running.
v Whether the rules and properties files are present.
v Whether the connection to a socket is working to verify the probe backup
functionality.
IBM Tivoli Netcool/OMNIbus SNMP Probe 5
v Whether a secondary ObjectServer is configured.
v Whether the Probes Rules Syntax Checker is installed.
v Whether the rules file is syntactically correct.
v Whether there is space for log files.
All other tests that the analyser performs are specific to each individual probe.
Running the Configuration Analyser on UNIX platforms
To run the Configuration Analyser on UNIX platforms, run the probe from the
command line using -check as an additional argument, as follows:
$OMNIHOME/probes/probe_bin -check
Where probe_bin is the name of the probe binary.
Note: You can specify additional arguments on the command line along with
-check; these will override any equivalent settings found in the properties file.
Running the Configuration Analyser on Windows platforms
The way you run the Configuration Analsyer on Windows platforms depends on
how you run the probe.
If you run the probe using a batch file, run the following command:
%OMNIHOME%\probes\probe_batch -check
Where probe_batch is the name of the batch file that you use to run the probe.
Note: You can specify additional arguments on the command line along with
-check; these will override any found in the properties file.
If you run the probe directly, without using a batch file, run the following
command:
%OMNIHOME%\probes\run_analyser.bat -probebin probe_exe -probename
probe_name
Where probe_exe is the name of the probe executable and probe_name is the name
of the probe binary without the nco_p_ prefix.
Note: You can specify additional arguments on the command line; these will
override any found in the properties file.
Configuration Analyser Log file
On completion of these tests, the Configuration Analyser outputs a status message.
This status message states that either all the tests were successful, that details of
any configuration errors or suggestions have been written to the probe log file
probe_name.log.
Consult the log file for information about how to correct or improve the
configuration of the probe.
6 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Requirements
The probe must not be run on a machine where another trapd process is running
(for example, HP NNM, or SunNet Manager), unless a different SNMP port is
specified in the command line or in the properties. When running the probe, the
user requires write access to the $OMNIHOME/var and the $OMNIHOME/log directories.
Note: If you want to use the Configuration Analyser, you must include the path to
Java 1.5 in the $PATH environment variable.
SNMP V3 support
The probe supports SNMP v3 traps and informs using USM for authentication and
privacy. Using USM, for each security name from which the probe receives traps,
you must specify a user that can log on to the probe. You must also specify a
unique user or engine ID for each trap source from which the probe receives traps.
Users are configured in the file Persistent_Dir/mttrapd.conf, where
Persistent_Dir is the name of the directory specified by the PersistentDir
property (which defaults to $OMNIHOME/var). To create this configuration file,
start and stop the probe after installation.
Note: This file also contains other SNMP V3 security information such as the
engine ID for the probe and the number of SNMP engine boots.
Note: When the probe is running SNMP V3, it is only compatible with FIPS 140-2
if it is using AES and SHA.
Adding new users to the configuration file
To create a new user, you must shut down the probe and, for user and
user/engine ID from which the probe receives traps, add a line to the
ConfPath/mttrapd.conf file, where ConfPath is the directory specified by the
ConfPath property.
The line you must add is as follows:
createUser [-e engineId] username authtype password [privtype privpassword]
After you have added the line for the new user, start the probe. The probe
generates the appropriate mttrapd.conf file in the PersistentDir directory, where
PersistentDir is the directory specified by the PersistentDir property.
Tip: To check that the user has been added correctly, look at the mttrapd.conf file
in the PersistentDir directory after you have started the probe; there should be an
entry for each user created at the end of this file, each such entry starts with the
string usmUser.
The following table describes the format of the createUser command in the
configuration file.
Table 3. Format of the createUser command
Item Description
engineId Use this item to specify an optional engine ID of
trap source associated with the user.
IBM Tivoli Netcool/OMNIbus SNMP Probe 7
Table 3. Format of the createUser command (continued)
Item Description
username Use this item to specify the security name of the
user.
authtype Use this item to specify an authentication type
(either MD5 or SHA).
password Use this item to specify the password (must be at
least eight characters).
privtype Use this item to specify the privacy type (either
DES or AES).
Note: DES uses a 16 byte key. The probe
truncates the encrypted 20 byte key to 16 bytes to
use it as the DES key.
privpassword Use this item to specify the privacy password (if
different from password).
Traps and informs
In SNMP V3 USM, the probe is the authoritative security engine for traps. The
engineId argument is required for each SNMP trap source so that the trap can be
authenticated.
The sender of the SNMP informs is the authoritative security engine in SNMP V3
USM. If informs are used, there is no requirement for the user to specify the
engineId of the inform sender.
Example usage
To receive SNMP informs from any device with the security name jack, add the
following to the mttrapd.conf file:
createUser jack MD5 password
To receive SNMP traps from a device with engineId 0x01020304050607 and the
security name jack, add the following line to the mttrapd.conf file:
createUser -e 0x01020304050607 jack MD5 password
Once the probe starts, the user information within the file is encrypted and
rewritten in the encrypted form, so plain text passwords are only held temporarily;
this increases security.
Running the probe as SUID root
The probe can be run as suid root without compromising system security. In this
mode, the probe drops its root privileges once it has opened the SNMP session,
and before the IBM

Tivoli

Netcool/OMNIbus probe library starts; this grants

privileged port usage in this mode.
About this task
To run the probe as SUID root, perform the following steps:
1. As root, change the owner of the probe binary using chown root
nco_p_mttrapd. (This must be done in the $OMNIHOME/probes/arch directory.)
8 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
2. As root, enable the probe binary to run as setuid root, using chmod +s
nco_p_mttrapd. (This must be done in the $OMNIHOME/probes/arch directory.)
3. Run the following command to register the OMNIbus library directory as a
trusted directory: crle -s /usr/lib/secure:/opt/netcool/omnibus/platform/
arch/lib
4. Run the probe as a normal user. (This must be done in the $OMNIHOME/probes
directory.)
Note: As running a probe as suid root causes environment variables to be
ignored, this procedure only works if the IBM Tivoli Netcool/OMNIbus
installation is on a local file system and installed in the default location.
AIX users
Problems regarding library paths and events not being read properly by the probe
have been noted on the AIX platform. In some circumstances, this can be overcome
by running the probe from the $OMNIHOME/platform/arch/lib directory; for
example:
1. Enter the following command:
cd /usr/Omnibus/platform/aix4/lib
2. Run the following command:
$OMNIHOME/probes/nco_p_mttrapd options
Note: If running the probe from this directory does not overcome the problem,
contact IBM Software Support.
IP environment
The probe can run in either IPv4 or IPv6 environments. You must specify in which
environment the probe is running using the Protocol property. If the probe is
running in an IPv4 environment, you must set the Protocol property to TCP, UDP,
ALL or ANY. If running in an IPv6 environment, you must set the Protocol
property to TCP6, UDP6, or ALLIPv6.
The IP address that you specify using the BindAddress property must be in a
format that matches the protocol specified by the Protocol property; for example, if
you specify TCP, UDP, ALL, or ANY using the Protocol property, the IP address
that you specify using the BindAddress property must be in IPv4 format. IPv4
addresses are expressed in 32-bit decimal notation as four decimal numbers
separated by periods; for example, 121.2.6.81.
If you specify TCP6, UDP6, or ALLIPv6 using the Protocol property, the IP address
that you specify using the BindAddress property must be in IPv6 format. IPv6
addresses are expressed in 128-bit hexadecimal notation as eight hexidecimal fields
separated by colons; for example, 3ffe:ff9f:101::230:6eff:fe04:d9ff.
Federal Information Processing Standards (FIPS) support
Federal Information Processing Standards (FIPS) are standards and guidelines that
the National Institute of Standards and Technology (NIST) issues for use in United
States federal government computer systems.
IBM Tivoli Netcool/OMNIbus SNMP Probe 9
This probe is compatible with the Federal Information Processing Standard 1402
(FIPS 1402), which defines security requirements for cryptographic modules that
are used to protect sensitive information in computer and telecommunication
systems.
Tivoli Netcool/OMNIbus uses the FIPS 1402 approved cryptographic providers,
IBMJCEFIPS (certificate 376) or IBMJSSEFIPS (certificate 409), and IBM Crypto for
C (ICC) (certificate 384), for cryptography. The certificates are listed on the NIST
Web site at http://csrc.nist.gov/cryptval/140-1/1401val2004.htm.
The FIPS 1402 approved cryptographic providers provide both cryptographic
functions and Secure Sockets Layer (SSL) data protection, on both client and server
applications. When Tivoli Netcool/OMNIbus is running in FIPS 1402 mode, all
encryption and key generation functions are provided by the FIPS 1402 approved
cryptographic modules.
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 probe receives events by registering a callback function with the NET SNMP
subsystem. This function is called whenever the NET SNMP subsystem receives a
trap or an inform.
The probe uses two directories: the ConfPath property points to one and the
PersistentDir property points to the other. The probe reads the ConfPath property
to locate the mttrapd.conf file and writes the processed file to the directory
specified by the PersistentDir directory. In SNMPv3, the resultant file contains the
encryption key.
Note: If the two directories are the same, the mttrapd.conf file will be constantly
overwritten. To avoid this, the directories that you specify with the ConfPath and
PersistentDir properties should be different.
Data acquisition is described in the following topics:
v Buffer settings
v Trap queue size on page 11
v Rules file on page 11
v IP address resolution on page 11
v Peer-to-peer failover functionality on page 11
Buffer settings
The probe maintains a queue that stores raw SNMP traps before they are processed
by the probe. When an event storm occurs, this queue can grow quickly
consuming excessive amounts of memory. To prevent this, you can use the
TrapQueueMax property to specify a maximum size up to which this queue can
grow before the probe starts to discard traps.
Note: The TrapQueueMax property is set to 20000 by default. If the value is set to
0, the probe sends the following warning message: Memory growth of the probe is
unbounded.
10 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
To increase the efficiency of sending alerts to the ObjectServer, the following
properties are available:
v Buffering - When set to 1, this property instructs the probe to send alerts when
the internal alert buffer has reached the size specified by the BufferSize
property.
v BufferSize - This property specifies the size of the buffer that the probe uses to
store alerts before sending them to the ObjectServer.
v FlushBufferInterval - This property specifies an interval in seconds that the
probe waits before flushing the alerts to the ObjectServer. This property limits
the time that alerts wait in the buffer when the buffer has yet to reach the size
specified by the BufferSize property.
Example property file settings for performance tuning
The following example shows performance settings from the properties file of an
SNMP Probe:
TrapQueueMax : 1000
BufferSize : 100
Buffering : 1
FlushBufferInterval : 10
These settings instruct the probe to store a maximum of 1000 raw traps prior to
converting them to ObjectServer alerts. When the internal alert buffer has 100 alerts
waiting to be sent to the ObjectServer, or after 10 seconds have elapsed since the
last flush, the probe flushes the alerts in the buffer to the ObjectServer.
Note: The internal alert buffer contains alerts that have been derived from the raw
SNMP traps.
Trap queue size
When run in debug mode, the probe writes the queue size to the log file.
An event loss can occur when the number of traps in a queue exceeds the value
set for the TrapQueueMax property. For information about running the probe in
debug mode, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide
SC23-6373.
Rules file
Avoid using construct details ($*) in the rules file.
IP address resolution
If the Domain Name Server (DNS) is not resolving IP addresses quickly, you can
improve performance by setting the NoNameResolution property to 0; this uses
less memory.
To resolve the IP addresses in a Windows platform, set the NoNetbiosLookups
property to 0.
Peer-to-peer failover functionality
The probe supports failover configurations where two probes run simultaneously.
One probe acts as the master probe, sending events to the ObjectServer; the other
acts as the slave probe on standby. If the master probe fails, the slave probe
activates.
IBM Tivoli Netcool/OMNIbus SNMP Probe 11
While the slave probe receives heartbeats from the master probe, it does not
forward events to the ObjectServer. If the master shuts down, the slave probe stops
receiving heartbeats from the master and any events it receives thereafter are
forwarded to the ObjectServer on behalf of the master probe. When the master is
running again, the slave continues to receive events, but no longer sends 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 settings differ for a master probe and slave probe.
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 : 5555 # [communication port between master and slave probes]
Mode : "master"
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 : 5555 # [communication port between master and slave probes]
Mode : "slave"
Note: The properties file also contains all other properties required to configure
the probe.
Properties and command line options
You use properties to specify how the probe interacts with the device. You can
override the default values by using the properties file or the command line
options.
The following table describes the properties and command line options specific to
this probe. For more information about generic properties and command line
options, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide, (SC23-6373).
Table 4. Properties and command line options
Property name Command line option Description
BindAddress string -bindaddress string Use this property to specify the IP
address to which the probe binds.
The default is .
Note: The IP address can be in either
IPv4 or IPv6 format depending on the
setting of the Protocol property.
12 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Table 4. Properties and command line options (continued)
Property name Command line option Description
ConfPath string -snmpconfpath string Use this property to specify the path of
directories that contain configuration
information for the SNMP probe
engine.
The default is $OMNIHOME/probes/
arch/$OMNIHOME/var.
Note: The directories specified using
this property must be separated by a
colon (:) on UNIX or a semi-colon (;)
on Windows. The configuration file is
named either as mttrapd.conf or
snmp.conf.
DSALog integer -dsalog integer Use this property to specify whether
the probe logs the traps that are
dropped when trap queue is full:
0: The probe does not log the traps that
are dropped when the trap queue is
full.
1: The probe logs the traps that are
dropped when the trap queue is full.
The default is 0.
DSAPeriod integer -dsaperiod integer Use this property to specify the period
(in seconds) during which the probe
logs dropped traps when the DSALog
property is set to 1.
0: The probe does not log the traps that
are dropped when the trap queue is
full.
1: The probe logs the traps that are
dropped when the trap queue is full.
The default is 30.
FlushBufferInterval
integer
-flushbufferinterval
integer
Use this property to specify the interval
(in seconds) that the probe waits before
flushing the buffer contents to the
ObjectServer.
The default is 0.
Heartbeat integer -heartbeat integer Use this property to specify the length
(in seconds) of the heartbeat period. If
the probe receives no traps for this
length of time, it sends a heartbeat
ProbeWatch message to the
ObjectServer.
The default is 60.
IBM Tivoli Netcool/OMNIbus SNMP Probe 13
Table 4. Properties and command line options (continued)
Property name Command line option Description
LogStatisticsInterval
integer
-logstatisticsinterval
integer
Use this property to specify the interval
(in seconds) at which the probe logs
internal probe statistics.
The statistics reported include the
following:
v the size of the trap queue and the
inform queue
v the number of traps read since the
last rollover
v the number of traps processed since
the last rollover
The default is 0 (does not log the
internal statistics).
MIBDirs string -mibdirs string Use this property to specify where the
probe searches for MIB modules. This
is in the form of a colon-separated list
of directories.
The default is $OMNIHOME/
common/mibs.
Note: The directories specified using
this property must be separated by a
colon (:) on UNIX or a semicolon (;) on
Windows.
MIBFile string -mibfile string Use this property to specify the name
of the MIB file.
The default is
$OMNIHOME/probes/arch/mib.txt.
Note: If you are using a rules file
generated by the trapd converter, you
must set this property to point to an
empty file; for example, /dev/null.
MIBs string -mibs string Use this property to specify which MIB
modules the probe loads. Your entry
should be in the form of a
colon-separated list of modules.
The default is ALL (this instructs the
probe to load all modules available in
the list of directories specified by the
MIBDirs property).
NoNameResolution
integer
-nonameresolution
(equivalent to
NoNameResolution
with a value of 1)
Use this property to specify whether
the probe performs name resolution on
IP addresses:
0: The probe performs name resolution.
1: The probe does not perform name
resolution.
The default is 0.
14 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Table 4. Properties and command line options (continued)
Property name Command line option Description
NoNetbiosLookups
integer
-nonetbioslookups
integer
(equivalent to
NoNetbiosLookups
with a value of 1)
-usenetbioslookups
integer
(equivalent to
UseNetbiosLookups
with a value of 0)
Use this property to specify whether
the probe performs netbios lookups
during DNS queries:
0: The probe performs lookups
1: The probe does not perform netbios
lookups
The default is 0.
Note: This property is only available
on the Windows platform.
NonPrintableAsHex
integer
-nonprintableashex
integer
Use this property to specify whether
the probe sets non-printable characters
to their hexadecimal values:
0: The probe does not set non-printable
characters to their hexadecimal values
1: The probe sets non-printable
characters to their hexadecimal values
The default is 0.
PersistentDir string -persistentdir string Use this property to specify where the
persistent configuration information is
stored.
The default is $OMNIHOME/var.
Port integer -port integer Use this property to specify the port to
which the probe listens for SNMP
traffic.
The default is 162.
IBM Tivoli Netcool/OMNIbus SNMP Probe 15
Table 4. Properties and command line options (continued)
Property name Command line option Description
Protocol string -protocol string
-udp (equivalent to
Protocol with a value of
UDP or -protocol UDP)
-tcp (equivalent to
Protocol with a value of
TCP or -protocol TCP)
-all (equivalent to
Protocol with a value of
ALL or -protocol ALL)
-any (equivalent to
Protocol with a value of
ANY or -protocol ANY)
-udp6 (equivalent to
Protocol with a value of
UDPIPV6 or -protocol
UDPIPV6)
-tcp6 (equivalent to
Protocol with a value of
TCPIPV6 or -protocol
TCPIPV6)
-allipv6 (equivalent to
Protocol with a value of
TCPIPV6 and UDPIPV6
or -protocol ALLIPV6)
Use this property to specify the
network protocol that the probe uses.
The default is UDP.
If the probe is running in an IPv4
environment, specify one of the
following values:
v UDP
v TCP
v ALL
v ANY
Note: The values ANY and ALL are
interchangeable.
If the probe is running in an IPv6
environment, specify one of the
following values:
v UDPV6
v TCPV6
v ALLIPV6
QuietOutput integer -quietoutput (equivalent
to QuietOutput with a
value of 1)
-noquietoutput
(equivalent to
QuietOutput with a
value of 0)
Use this property to specify whether
the probe outputs tokens that
correspond to an OID with symbolic
OID expansion:
0: The probe outputs tokens with
symbolic OID expansion.
1: The probe outputs tokens without
symbolic OID expansion.
The default is 1.
SleepTime integer -sleeptime integer Use this property to specify the poll
time (in seconds) of the trap list. If
there are no traps to be processed, the
probe sleeps for this amount of time
before polling the trap queue again.
The default is 1.
16 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Table 4. Properties and command line options (continued)
Property name Command line option Description
snmpv3ONLY integer -snmpv3only integer Use this property to specify that the
probe only processes the SNMPv3
traps:
0: The probe processes all types of
SNMP traps.
1: The probe only processes SNMPv3
traps.
The default is 0.
SocketSize integer -socketsize integer Use this property to specify the size (in
bytes) of the kernel buffer on the
socket being used. This is set on a
per-socket basis. A higher value
increases the number of traps that the
probe can handle. For UDP traps, this
improves performance.
The default is 8192.
Note: The minimum value for the
SocketSize property is 128 bytes; the
default is 8192 bytes. In the majority of
cases, the default size is recommended.
TrapQueueMax integer -trapqueuemax integer Use this property to specify the
maximum number of traps that can be
queued for processing at any one time.
The probe discards any traps received
while the buffer is full.
The default is 20000.
Tip: To prevent the probe from
dropping events during a burst of
traps, you should set this property to a
higher value; for example, 50000.
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.
This section describes the elements that the probe generates.
Static elements
The following table describes the static elements that the probe generates:
Table 5. Static elements
Element name SNMP version Element description
$community V1 and V2c This element contains the SNMP
community string.
IBM Tivoli Netcool/OMNIbus SNMP Probe 17
Table 5. Static elements (continued)
Element name SNMP version Element description
$contextEngineID V3 This element identifies the engine
associated with the data.
$enterprise V1 This element contains the SNMP
enterprise string.
$EventCount V1, V2c, and V3 This element displays the number of
traps processed during the current
execution of the probe.
$generic-trap V1 This element contains the SNMP
generic trap integer value.
$IPaddress V1, V2c, and V3 This element contains the IP address
(origin of the SNMP trap).
$Node V1, V2c, and V3 This element contains the node name
(origin of the SNMP trap).
IP address (if node name cannot be
resolved).
$notify V2c and V3 This element displays the notify V2c
specific field.
$PeerAddress V1, V2c, and V3 This element contains the host name or
IP address where the SNMP trap was
received from.
$PeerIPaddress V1, V2c, and V3 This element contains the IP address
where the SNMP trap was received
from.
$Protocol V1, V2c, and V3 This element contains the protocol of
the trap received. This can be either
UDP or TCP.
$ReceivedPort V1, V2c, and V3 This element contains the port number
where the SNMP trap was received
from. This is determined by the Port
property.
$ReceivedTime V1, V2c, and V3 The time that the SNMP packet was
received from the network interface.
$ReqId V1 This element contains the SNMP
request ID.
$securityEngineID V3 This element contains the engine ID of
the authoritative SNMP entity. For
informs, this is the engine ID of the
probe. For traps, this is the engine ID
of the source of the trap.
$securityLevel V3 Security level of the trap or inform:
noAuth: The trap or inform had no
authentication and no privacy
authNoPriv: The trap or inform had
authentication, but no privacy
authPriv: The trap or inform had
authentication and privacy
18 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Table 5. Static elements (continued)
Element name SNMP version Element description
$securityName V3 This element contains the security
name used for trap authentication.
$SNMP_Version V1, V2c, and V3 This element contains the the value 1
for SNMP V1 traps and the value 2 for
SNMP V2c traps.
$specific-trap V1 This element contains the SNMP
specific trap integer value.
$Uptime V1 and V2c This element contains the SNMP
uptime for traps expressed in the
format 0:00:00.
$UpTime V1 and V2c This element contains the SNMP
uptime for traps expressed as an
integer.
Dynamic elements
The other elements that the probe generates are created dynamically and are
entirely dependent on the network devices. The varbind variables that are
generated by the SNMP trap are mapped to elements called $1,$2,$3, and so on.
For each varbind, the object ID is placed in a corresponding element called $OID1,
$OID2, $OID3, and so on up to the number of varbind elements.
Note: Previous versions of the SNMP Probe (pre version 3.5) had no leading dot
(.) in the $OIDn elements, whereas the latest probe does include the leading dot; if
you are upgrading from an old version of the probe, your rules files may need
updating.
The probe can also generate the following elements from various representations of
the varbind variables:
v $n_raw - raw string representation of the varbind variables (containing all control
characters)
v $n_text - printable text representation of the varbind variables (with
non-printable characters replaced with periods)
v $n_hex - hexadecimal representation of the varbind variables
Note: The $n_raw, $n_text, and $n_hex elements are only available for SNMP
variables of type OCTET-STRING.
Generic trap handling
Certain devices generate traps of various generic types. How the probe handles
each trap depends on its type.
IBM Tivoli Netcool/OMNIbus SNMP Probe 19
The following table describes the handling of each generic trap type.
Table 6. Generic trap handling
Generic trap Handling
Generic trap-type 0- Cold Start Summary field set to Cold Start
AlertGroup field set to Generic
Severity field set to 4
Generic trap-type 1- Warm Start Summary field set to Warm Start
AlertGroup field set to Generic
Severity field set to 4
Generic trap-type 2 - Link Down Summary field set to Link Down
Alert Key set to the $1 varbind (ifIndex)
AlertGroup field set to Generic
Severity field set to 5
Identifier field set to Node name plus Agent
plus generic trap plus specific trap plus
ifIndex.
Generic trap-type 3 - Link Up Summary field set to Link Up
Alert Key set to the $1 varbind (ifIndex)
AlertGroup field set to Generic
Severity field set to 2
Identifier field set to Node name plus Agent
plus generic trap plus specific trap plus
ifIndex.
Generic trap-type 4 - Authentication By default, Authentication traps are not
discarded.
Generic trap-type 5 - EGP Neighbor Loss Summary field set to EGP Neighbor Loss
AlertGroup field set to Generic
Severity field set to 3.
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, (SC23-6373).
20 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Table 7. Error messages
Error Description Action
Error: ipv6_address is
not a valid address
The IP address specified for
the BindAddress property
was not in IPv4 format.
Check the value specified for
the BindAddress property; if
the Protocol property is set to
TCP, UDP, ALL, or ANY, this
IP address must be specified
in IPv4 format.
Error: ipv4_address is
not a valid address
The IP address specified for
the BindAddress property
was not in IPv6 format.
Check the value specified for
the BindAddress property; if
the Protocol property is set to
TCPV6, UDPV6, or ALLIPV6,
this IP address must be
specified in IPv6 format.
Failed to parse SNMP PDU,
Version
unrecongnised!!!PDU
command was invalid
The probe failed to process
the traps.
Check that the device is
running correctly.
protocol not known An invalid protocol has been
specified.
Check the value specified for
the Protocol property.
UDP snmp_open: Unknown
host (Address already in
use) Failed to open UDP
sessionUnable to get hold
of session link pointer
As another process is running
on the port specified, it is not
available for this session.
Specify a different port either
using the command line, or
using the Port property in the
properties file.
Error messages generated by the Configuration Analyser
The following table describes the error messages generated by the Configuration
Analyser.
Table 8. Error messages
Error message Description Action
An error has caused the
program to terminate
abnormally. Please re-run
it and set CheckLevel to
DEBUG_MIN in the probe
properties file, and then
check $OMNIHOME/log/
probe_name.check.log for
more details.
There was an internal error
in the Configuration
Analyser.
Check the
$OMNIHOME/log/
probe_name.check.log file
for more details.
Parse Error: ****** There was a parsing error in
the test xml shipped with the
probe.
Check that
$OMNIHOME/probes/arch/
configAnalyser.xsd exists.
Check that
$OMNIHOME/probes/arch/
probe_name.check.jar exists.
If the problem persists across
several probes, re-install the
Configuration Analyser.
Otherwise, re-install the
probe.
IBM Tivoli Netcool/OMNIbus SNMP Probe 21
Table 8. Error messages (continued)
Error message Description Action
Undefined argument: -check An old fix pack has been
installed that has overwritten
the nco_probe script installed
with the Configuration
Analyser.
Reinstall the Configuration
Analyser.
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 raw ProbeWatch error messages that the probe
generates. For information about generic error messages, see the IBM Tivoli
Netcool/OMNIbus Probe and Gateway Guide, (SC23-6373).
Table 9. ProbeWatch messages
ProbeWatch message Description Triggers or causes
Going Down The probe is shutting down. The probe is shutting down
after performing the
shutdown routine.
Heartbeat Message The heartbeat message that
the probe sends to the
ObjectServer.
The probe has not received
any events for the time
specified by the Heartbeat
property. This may be useful
for debugging purposes.
Running ... The probe is running
normally.
The probe has just been
started up.
Trapqueue limit has
exceeded so dropping
traps
The probe dropped traps
without processing them.
The number of traps received
has exceeded the trap queue
limit set by the
TrapQueueMax property.
Unable to get events A problem occurred while
trying to listen for traps.
Either there was a problem
initializing the connection due
to insufficient memory or (if
this message was sent after
some events had been parsed)
there was a connection failure.
22 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
Appendix. Notices and Trademarks
This appendix contains the following sections:
v Notices
v Trademarks
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 users responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing 2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Copyright IBM Corp. 2006, 2009 23
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 wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
Software Interoperability Coordinator, Department 49XA
3605 Highway 52 N
Rochester, MN 55901
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBMs future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBMs 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.
24 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs.
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
(your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. Copyright IBM Corp. _enter the year or years_. All rights
reserved.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
Trademarks
IBM, the IBM logo, ibm.com, AIX, Tivoli, zSeries, and Netcool are trademarks of
International Business Machines Corporation in the United States, other countries,
or both.
Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-based
trademarks are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States, other countries, or both.
Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation
in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or
both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product, or service names may be trademarks or service marks of
others.
Appendix. Notices and Trademarks 25
26 IBM Tivoli Netcool/OMNIbus SNMP Probe: Reference Guide

Printed in USA
SC23-6003-04