IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway: Reference Guide

IBM ® Tivoli ® Netcool/OMNIbus SNMP Writer Gateway 

Version 6.0 

Reference Guide 

November 30, 2012 

�� 

SC23-7804-07

IBM ® Tivoli ® Netcool/OMNIbus SNMP Writer Gateway 

Version 6.0 

Reference Guide 

November 30, 2012 

�� 

SC23-7804-07

Notice 

Before using this information and the product it supports, read the information in “Notices and Trademarks,” on page 29. 

Edition notice 

This edition (SC23-7804-07) applies to version 6.0 of IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway and to 

all subsequent releases and modifications until otherwise indicated in new editions. 

This edition replaces SC23-7804-06. 

© Copyright IBM Corporation 2006, 2012. 

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract 

with IBM Corp.

Contents 

About this guide . . . . . . . . . . . v 

Document control page . . . . . . . . . . . v 

Conventions used in this guide . . . . . . . . vi 

IBM Tivoli Netcool/OMNIbus SNMP 

Writer Gateway. . . . . . . . . . . . 1 

Summary . . . . . . . . . . . . . . . 1 

Supported operating system versions . . . . . . 2 

Installing the gateway . . . . . . . . . . . 2 

Installing the gateway on Tivoli 

Netcool/OMNIbus V7.3.0 or later . . . . . . 3 

Installing the gateway on Tivoli 

Netcool/OMNIbus V7.2.1 . . . . . . . . . 4 

Configuring the gateway server . . . . . . . . 5 

Configuring the gateway . . . . . . . . . . 5 

Properties file . . . . . . . . . . . . . 6 

Map definition file . . . . . . . . . . . 16 

Startup command file . . . . . . . . . . 17 

Table replication definition file . . . . . . . 19 

Advanced properties . . . . . . . . . . 19 

AES encryption . . . . . . . . . . . . . 24 

Running the gateway . . . . . . . . . . . 26 

Error messages . . . . . . . . . . . . . 27 

Appendix. Notices and Trademarks . . 29 

Notices . . . . . . . . . . . . . . . . 29 

Trademarks . . . . . . . . . . . . . . 31 

© Copyright IBM Corp. 2006, 2012 iii

iv IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway: Reference Guide

About this guide 

Document control page 

The following sections contain important information about using this guide. 

Use this information to track changes between versions of this guide. 

The IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway documentation is 

provided in softcopy format only. To obtain the most recent version, visit the IBM ® 

Tivoli ® 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 

SC23-7804-00 February 20, 

2006 

First IBM publication. 

SC23-7804-01 June 20, 2007 Support added for the AES encryption of string values 

that can be assigned to attributes within the WRITER 

section of the gateway configuration file. 

SC23-7804-02 December 19, 

2007 

SC23-7804-03 March 28, 

2008 

SC23-7804-04 September 11, 

2009 

The SNMP Writer Gateway no longer supports electronic 

licensing. The gateway now uses the IBM ® software 

licensing process. 

Support for SNMP version 2 traps added. 

Support for IBM Tivoli ® Netcool ® /OMNIbus V7.2 added. 

Sybase support information added. 

Summary section updated. 

Running the ObjectServer in a secure mode section added. 

Guide rewritten to reflect updated gateway architecture. 

© Copyright IBM Corp. 2006, 2012 v

Table 1. Document modification history (continued) 

Document 

version 

Publication 

date 

SC23-7804-05 February 25, 

2011 

SC23-7804-06 August 3, 

2012 

SC23-7804-07 November 30, 

2012 

Conventions used in this guide 

Comments 

Updated “Summary” on page 1. 

Updated “Supported operating system versions” on page 

2. 

“Properties and command line options” on page 6 

updated to describe the following properties: 

v Gate.Mapper.Debug 

v Gate.Mapper.ForwardHistoricDetails 

v Gate.Mapper.ForwardHistoricJournals 

v Gate.Reader.Debug 

v Gate.Reader.Description 

v Gate.Reader.DetailsTableName 

v Gate.Reader.FailbackEnabled 

v Gate.Reader.FailbackTimeout 

v Gate.Reader.IducFlushRate 

v Gate.Reader.JournalTableName 

v Gate.Reader.LogOSSql 

v Gate.Reader.Password 

v Gate.Reader.ReconnectTimeout 

v Gate.Reader.Server 

v Gate.Reader.StatusTableName 

v Gate.Reader.Username 

SNMP trap types described in “Generic and specific 

traps” on page 20. 

Event flush rate described in “Event flush rate” on page 

21. 

Updated “Store-and-forward mode” on page 22. 

Updated “Running the gateway” on page 26. 

Updated “Error messages” on page 27. 

Summary section updated. 

Guide updated for Netcool/OMNIbus V7.4 release. 

“Installing the gateway” on page 2 updated. 

All gateway guides use standard conventions for operating system-dependent 

environment variables and directory paths. 

Operating system-dependent variables and paths 

All gateway guides use standard conventions for specifying environment variables 

and describing directory paths, depending on what operating systems the gateway 

is supported on. 

vi IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway: Reference Guide

For gateways supported on UNIX and Linux operating systems, gateway guides 

use the standard UNIX conventions such as $variable for environment variables and 

forward slashes (/) in directory paths. For example: 

$OMNIHOME/gates 

For gateways supported only on Windows operating systems, gateway guides use 

the standard Windows conventions such as %variable% for environment variables 

and backward slashes (\) in directory paths. For example: 

%OMNIHOME%\gates 

For gateways supported on UNIX, Linux, and Windows operating systems, 

gateway guides use the standard UNIX conventions for specifying environment 

variables and describing directory paths. When using the Windows command line 

with these gateways, replace the UNIX conventions used in the guide with 

Windows conventions. If you are using the bash shell on a Windows system, you 

can use the UNIX conventions. 

Note: The names of environment variables are not always the same in Windows 

and UNIX environments. For example, %TEMP% in Windows environments is 

equivalent to $TMPDIR in UNIX and Linux environments. 

Operating system-specific directory names 

Where Tivoli Netcool/OMNIbus files are identified as located within an arch 

directory under NCHOME or OMNIHOME, arch is a variable that represents your 

operating system directory. For example: 

$OMNIHOME/gates/arch/ 

The following table lists the directory names used for each supported operating 

system. 

Table 2. Directory names for the arch variable 

Operating system Directory name represented by arch 

AIX ® systems aix5 

HP-UX PA-RISC-based systems hpux11 

HP-UX Integrity-based systems hpux11hpia 

Red Hat Linux and SUSE systems linux2x86 

Linux for System z ® 

linux2s390 

Solaris systems solaris2 

Windows systems win32 

About this guide vii

viii IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway: Reference Guide

IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway 

Summary 

The IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway forwards Netcool ® alerts 

as Simple Network Management Protocol (SNMP) traps to an SNMP reader, such 

as the IBM Tivoli Netcool/OMNIbus SNMP Probe. This allows Tivoli 

Netcool/OMNIbus to generate traps that are forwarded to another management 

platform such as SunNet Manager or HP Network Node Manager. 

The SNMP Writer Gateway supports versions 1, 2, and 3 of the Simple Network 

Management Protocol. 

This guide contains the following sections: 

v “Summary” 

v “Supported operating system versions” on page 2 

v “Installing the gateway” on page 2 

v “Configuring the gateway” on page 5 

v “AES encryption” on page 24 

v “Running the gateway” on page 26 

v “Error messages” on page 27 

Each gateway works in a different way to provide an interface with the 

ObjectServer. Use this summary information to learn about the SNMP Writer 

Gateway. 

The following table provides a summary of the gateway: 

Table 3. Summary 

Gateway target Simple Network Management Protocol (SNMP) writer 

application 

Gateway executable file name nco_g_snmp (on UNIX and Linux operating systems) 

nco_g_snmp.exe (on Windows operating systems) 

Gateway installation package omnibus-arch-gateway-nco_g_snmp-version 

Package version 6.0 

Gateway 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=swg21613133 

Configuration files $OMNIHOME/gates/snmp/NCO_GATE.props 

$OMNIHOME/gates/snmp/snmp.map 

$OMNIHOME/gates/snmp/snmp.reader.tblrep.def 

$OMNIHOME/gates/snmp/snmp.startup.cmd 

Additional binaries None 

© Copyright IBM Corp. 2006, 2012 1

Table 3. Summary (continued) 

Requirements A currently support version of IBM Tivoli 

Netcool/OMNIbus 

common-libngtk-1_3 (UNIX) 

Remote connectivity 

common-libngobjserv-1_6 (UNIX) 

Yes 

Failover/failback functionality Available 

Internationalization support Available 

IP environment IPv4 and IPv6 

Federal Information Processing 

Standards (FIPS) 

Supported operating system versions 

Installing the gateway 

Note: The gateway is supported on IPv6 when running 

on IBM Tivoli Netcool/OMNIbus V7.2.0 and 7.2.1 on 

Solaris, and on IBM Tivoli Netcool/OMNIbus V7.2.0 and 

7.2.1 on all other UNIX and Linux operating systems. The 

gateway is supported on IPv6 when running on IBM 

Tivoli Netcool/OMNIbus V7.2.1 (and above) on Windows 

operating systems. 

IBM Tivoli Netcool/OMNIbus V7.2.1 uses the FIPS 140-2 

approved cryptographic provider: IBM Crypto for C 

(ICC) certificate 384 for cryptography. This certificate is 

listed on the NIST web site at http://csrc.nist.gov/ 

cryptval/140-1/1401val2004.htm For details about 

configuring Netcool/OMNIbus for FIPS 140-2 mode, see 

IBM Tivoli Netcool/OMNIbus Installation and Deployment 

Guide (SC14-7604). 

The following table shows the operating system versions for which the SNMP 

Writer Gateway is supported. 

The gateway is supported on the following operating system versions: 

Table 4. Supported operating system versions 

Operating System Supported versions 

Solaris 9 and 10 

AIX 5.2, 5.3, and 6.1 

HP-UX PA-RISC 11.i 

HP-UX Itanium 11.23 and 11.3 

Linux SUSE 9 and 10 

Linux for zSeries 

RHEL 3.0, 4.0, and 5.0 

All 

Windows 2000, 2003, 2008 

There are separate procedures for installing the gateway on Tivoli 

Netcool/OMNIbus V7.3.0, or later and on Tivoli Netcool/OMNIbus V7.2.1. 

2 IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway: Reference Guide

Follow the procedure for the version of Tivoli Netcool/OMNIbus that your site 

uses. 

Installing the gateway on Tivoli Netcool/OMNIbus V7.3.0 or 

later 

With the introduction of Tivoli Netcool/OMNIbus V7.3.0 and later versions, all 

gateways are installed using the Tivoli Netcool/OMNIbus installer. 

You can install the gateway using any of the following: 

v “The installation wizard” 

v A text-based installer (“Console mode” on page 4) 

v Settings predefined in a text file (“Silent mode” on page 4) 

The installation package and patches for the gateway are supplied as archives. The 

archive management application that you use to extract the files must be able to 

preserve the directory structure contained in the archive on extraction. 

Note: If you are installing a 32-bit gateway on a system that runs a 64-bit UNIX or 

Linux operating system, you will need to install additional, 32-bit operating system 

libraries. See the IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide for 

more information. 

Obtaining the installation package 

To obtain the installation package and prepare it for installation use the following 

steps: 

1. Download the installation package for the gateway from the Passport 

Advantage Online Web site: 

http://www-306.ibm.com/software/howtobuy/passportadvantage/ 

pao_customers.htm 

2. Make a backup of any existing configuration files that you want to retain. 

3. Extract the contents of the installation package to a temporary directory. 

Now use one of the installation methods to install your gateway. In each case, the 

gateway is installed in the following directory: 

Linux UNIX $NCHOME/omnibus/gates 

Windows %NCHOME%\omnibus\gates 

The installation wizard 

To install the gateway using the installation wizard: 

1. Run the installer for your operating system: 

Linux UNIX $NCHOME/omnibus/install/nco_install_integration 

Windows %NCHOME%\omnibus\install\nco_install_integration 

2. When the installation wizard starts, specify the extracted directory that contains 

the README.txt file as the location of the gateway installation files. 

3. Accept the license conditions. 

IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway 3

Console mode 

To install the gateway in console mode: 


Linux UNIX $NCHOME/omnibus/install/nco_install_integration -i 

console 

Windows %NCHOME%\omnibus\install\nco_install_integration -i console 

2. When the text-based installer starts, specify the extracted directory that contains 

the README.txt file as the location of the gateway installation files. 

3. Accept the license conditions. 

Silent mode 

To install the gateway in silent mode: 

1. Create a text file named reponse.txt and add the following entries: 

PROBE_OR_GATE_LOCATION=README_directorypath 

LICENSE_ACCEPTED=true 

where README_directorypath is the path to the directory containing the 

README.txt file in the extracted package. 


Linux UNIX $NCHOME/omnibus/install/nco_install_integration -i 

silent -f response_path/response.txt 

Windows %NCHOME%\omnibus\install\nco_install_integration -i silent 

-f response_path\response.txt 

where response_path is the full path to the response.txt file. 

Installing the gateway on Tivoli Netcool/OMNIbus V7.2.1 

The process of installing gateways on Tivoli Netcool/OMNIbus V7.2.1 consists of 

downloading the appropriate gateway installation package, downloading the 

packages for each gateway dependency, installing the gateway patch contained in 

the gateway package, and installing the patch for each dependency contained in 

their respective packages. 

The installation package for the gateway is supplied as a compressed archive. It 

contains the patch version of the gateway in the patches subdirectory and a 

README.txt file that lists the gateway dependencies. The dependencies are supplied 

as packages that you must download separately. Each dependency package 

contains the patch version of the dependency in its patches subdirectory. 

Note: The archive management application that you use to extract the files must 

be able to preserve the directory structure contained in the archive on extraction. 

To install the gateway: 

1. Download the installation package for the gateway from the Passport 

Advantage Online Web site: 

http://www-306.ibm.com/software/howtobuy/passportadvantage/ 

pao_customers.htm 

2. Make a backup of any existing configuration files that you want to retain. 

3. Extract the contents of the installation package to a temporary directory. 

4. In the temporary directory, locate and read the README.txt file. 


The README.txt file will tell you if you need to download any further 

dependencies from the Passport Advantage Online Web site. 

5. Download the install packages for all dependencies listed in the README.txt 

file. 

6. Extract the contents of each dependency installation package to a temporary 

directory. 

7. Locate the patches directory for the gateway (under the directory containing 

the README.txt file). 

This directory contains the patch for the gateway. 

8. Windows Extract the patch files for the gateway and its dependencies to the 

following directory: 

%OMNIHOME% 

9. Linux UNIX Consult the README.txt file to determine the order in 

which the gateway and any dependency patches must be installed. 

10. Linux UNIX Install each patch, in the correct order, by running the 

following command: 

$OMNIHOME/install/nco_patch -install patch_path 

where patch_path is the path to the extracted patch file. 

Note: Linux UNIX At any point in the installation process, you can see 

what patches have been installed by running the following command: 

$OMNIHOME/install/nco_patch -print=id 

Configuring the gateway server 

Configuring the gateway 

You must create the gateway server in the Netcool/OMNIbus interfaces file. 

Use the Server Editor (nco_xigen) to specify the host name and port number of the 

gateway host in the Netcool/OMNIbus interfaces file. 

You must make the host name the same as the name of the gateway properties file. 

For example, the default properties file supplied with the gateway is called 

NCO_GATE.props, so the corresponding host name is NCO_GATE. 

Note: For information about using the Server Editor, see the IBM Tivoli 

Netcool/OMNIbus Administration Guide. 

The SNMP Writer Gateway uses centralized property management that separates 

property configuration from data processing configuration. To configure the 

common Netcool/OMNIbus and gateway-specific properties, use the properties 

file. To configure data processing, use the map definition file, the table replication 

definition file, and the startup command file. 

The following topics describe the configuration files and how to use them: 

v “Properties file” on page 6 

v “Map definition file” on page 16 

v “Startup command file” on page 17 

v “Table replication definition file” on page 19 


v “Advanced properties” on page 19 

Properties file 

The properties file is a text file that contains a set of properties and their 

corresponding values. These properties define the operational environment of the 

gateway, such as connection details and the location of the other configuration 

files. 

Configuring the properties file 

Before running the gateway for the first time, you must configure the installed 

properties file. 

To configure the properties file, use the following steps: 

1. Copy the example properties file, NCO_GATE.props, fromthe 

$OMNIHOME/gates/snmp directory to the following directory: $OMNIHOME/etc. 

2. Edit the remaining values in the properties file to suit your operating 

environment. 

Properties and command line options 

You use properties to define the operational environment of the gateway. You can 

override the default values by editing the properties file. 

The following tables describe the properties available with the SNMP Writer 

Gateway. For more information about generic and Inter-Process Communication 

(IPC) properties and command line options, see the IBM Tivoli Netcool/OMNIbus 

Probe and Gateway Guide (SC23-6387). 

The following sections describe the properties used to configure the gateway: 

v “Common Netcool/OMNIbus properties” 

v “Generic gateway properties” on page 7 

v “Gateway-specific properties” on page 11 

Common Netcool/OMNIbus properties 

Table 5 describes the available Netcool/OMNIbus common properties. 

Table 5. Common Netcool/OMNIbus properties 

Property name Command line option Description 

Help boolean -help boolean Use this property to instruct 

the gateway to display 

application help information 

on startup and exit. 

MaxLogFileSize integer -maxlogfilesize integer 

The default is FALSE. 

Use this property to specify 

the size (in bytes) that the 

gateway allocates for the log 

file. When the log file reaches 

this size, the gateway renames 

the log file by appending the 

name with the suffix .old and 

creates a new log file. 

6 IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway: Reference Guide 

The default is 1024.

Table 5. Common Netcool/OMNIbus properties (continued) 


MessageLevel string -messagelevel string Use this property to specify 

the reporting level of the log 

file messages. 

MessageLog string -messagelog string 

The default is warn. 


the location of the message log 

file. 

Name string -name string 

The default is 

$OMNIHOME/log/NCO_GATE.log. 


the name of the current 

gateway instance. If you want 

to run multiple gateways on 

one machine, you must use a 

different name for each 

instance. 

PropsFile string -propsfile string 

The default is NCO_GATE. 


the location of the gateway 


UniqueLog boolean -uniquelog boolean 


$OMNIHOME/etc/ 

NCO_GATE.props. 


whether or not log file names 

are made unique by adding 

the Process ID (PID) of the 

gateway to the file name. 

Version boolean -version boolean 


Use this property to instruct 

the gateway to display 

information about the 

application version on startup 

and exit. 

Generic gateway properties 

Table 6 describes the available generic gateway properties. 


Table 6. Generic gateway properties 


Gate.CacheHashTblSize -cachehtblsize integer Use this property to specify 

integer 

the number of elements 

(database rows) that the 

gateway allocates for the 

hash table cache. 

The default is 5023. 


Table 6. Generic gateway properties (continued) 


Gate.MapFile string -gatemap string Use this property to specify 

the location of the mapping 

file. 

Gate.Mapper.Debug boolean -mapperdebug boolean 


$OMNIHOME/gates/snmp/ 

snmp.map. 


whether or not the gateway 

includes mapper debug 

messages in the debug log. 

Gate.Mapper.Forward 

HistoricDetails boolean 

Gate.Mapper.Forward 

HistoricJournals boolean 

The default is TRUE. 

-mapperforhistdtls boolean Use this property to specify 

whether the gateway 

forwards all historic details 

on converted update. 


-mapperforhistjrnl boolean Use this property to specify 


forwards all historic journals 

on converted update. 

Gate.NGtkDebug boolean -ngtkdebug boolean 



whether or not the NGTK 

library logs debug messages. 

Gate.PAAware integer -paaware integer 


This property indicates 


is Process Agent (PA) aware. 

The default is 0 (the gateway 

is not PA-aware). 

Gate.PAAwareName string -paname string 

Note: This property is 

maintained by the PA server 

and is included in the 

properties file for 

information only. 

This property indicates the 

name of the PA controlling 

the gateway. 


The default is "". 

Note: This property is 

maintained by the PA server 

and is included in the 

properties file for 

information only.



Gate.Reader.Debug boolean -readerdebug boolean Use this property to specify 


includes gateway reader 

debug messages in the debug 

log. 

Gate.Reader.Description 

string 

Gate.Reader.Details 

TableName string 

Gate.Reader. 

FailbackEnabled boolean 

Gate.Reader. 

FailbackTimeout integer 


-readerdescription string Use this property to specify 

the application description 

for the reader connection. 

This description is used in 

triggers and allows you to 

determine which component 

of the gateway attempted to 

perform an action. 

-readerdetailstblname 

string 

The default is Gateway 

Reader. 


the name of the details table 

that the gateway reads. 


alerts.details. 

-failbackenabled boolean Use this property to specify 


attempts to fail back to the 

primary system following a 

system failover. 


Note: The gateway attempts 

to fail back with the 

frequency specified by the 

Gate.Reader. 

FailbackTimeout property. 

-failbacktimeout integer Use this property to specify 

the frequency (in seconds) 

with which the gateway 

attempts to fail back to the 

primary system following a 

system failover. 


Note: The gateway attempts 

to fail back to the primary 

ObjectServer only if the 

Gate.Reader. 

FailbackEnabled property is 

set to TRUE. 




Gate.Reader.IducFlushRate -readeriducflushrate integer Use this property to specify 

integer 

the frequency (in seconds) at 

which the gateway reader 

requests updates from the 

ObjectServer. 

Gate.Reader.Journal 

TableName string 


Note: If you set this 

property to a value greater 

than 0, the reader issues 

automatic IDUC flush 

requests to the ObjectServer 

with greater frequency. See 

“Event flush rate” on page 

21 for more information. 

-readerjournaltblname string Use this property to specify 

the name of the journal table 



alerts.journal. 

Gate.Reader.LogOSSql boolean -readerlogossql boolean Use this property to specify 

whether the gateway logs all 

SQL commands sent to the 

ObjectServer in debug mode. 

Gate.Reader.Password string -readerpassword string 



the password associated with 

the user specified by the 

Gate.Reader.Username 

property. 

Gate.Reader. 

ReconnectTimeout integer 


The default is "". 

Note: This password must 

be encrypted using the 

nco_g_crypt utility. For 

information about using 

nco_g_crypt, see the IBM 

Tivoli Netcool/OMNIbus 

Administration Guide, 

(SC23-6371). 

-readerreconntimeout integer Use this property to specify 

the time (in seconds) 

between each reconnection 

poll attempt that the gateway 

makes if the connection to 

the ObjectServer is lost. 

The default is 30.



Gate.Reader.Server string -readerserver string Use this property to specify 

the name of the ObjectServer 

from which the gateway 

reads alerts. 

Gate.Reader. 

StatusTableName string 

Gate.Reader.Tbl 

ReplicateDefFile string 

The default is NCOMS. 

-readerstatustblname string Use this property to specify 

the name of the status table 


The default is alerts.status. 

-readertblrepdef string Use this property to specify 

the location of the table 

replication definition file. 

Gate.Reader.Username string -readerusername string 



snmp.reader.tblrep.def. 


the user name that is used to 

authenticate the ObjectServer 

connection. 

Gate.StartupCmdFile string -startupcmdfile string 

The default is root. 


the location of the startup 

command file. 

Gate.Transfer. 

FailoverSyncRate integer 

Gateway-specific properties 



snmp.startup.cmd. 

-fsyncrate integer Use this property to specify 

the rate (in seconds) of the 

failover synchronization. 


Table 7 describes the available properties specific to the SNMP Writer Gateway. 

Table 7. Gateway-specific properties 


Gate.SNMP.Community string -snmpcommunity string Use this property to specify 

the community string from 

SNMP traps. 

Gate.SNMP. EnableLookup 

boolean 

The default is public. 

-snmpenablelookup boolean Use this property to specify 

whether or not host lookup is 

enabled. 



Table 7. Gateway-specific properties (continued) 


Gate.SNMP.EngineID string -snmpengineid string Use this property to specify 

the engine ID of the gateway. 

This identifies the gateway as 

the source of the SNMP V3 

traps. 

Gate.SNMP. 

ForwardUpdates boolean 

The default is 0x0102030405. 

Note: This property is only 

used with SNMP V3 traps and 

must match the engine ID 

specified in the configuration 

file of the receiver. 

-snmpforwardupdates boolean Use this property to specify 


forwards alert updates to the 

ObjectServer. In effect, the 

original alert is duplicated but 

will include the updated data. 

Gate.SNMP.Gateway string -snmpgateway string 



the IP address and port to 

which the gateway forwards 

traps. 


The default is 127.0.0.1:162. 

Note: 

If you are operating in an 

IPv4 environment, specify this 

location in IPv4 format as 

address:port. 

For example: 127.0.0.1:8080 

If you are operating in an 

IPv6 environment, specify this 

location in IPv6 format, 

preceded by tcp6 or udp6 (as 

appropriate), and followed by 

the port number, as 

tcp6|udp6:address:port. 

For example: 

tcp6:[::01]:6666



Gate.SNMP.OID string -snmpoid string Use this property to specify 

the object identifier (OID) for 

traps. 


1.3.6.1.4.1.1279 (this is an 

IANA-registered Private 

Enterprise Number). 

Gate.SNMP.Protocol string -snmpprotocol string 

Note: This property can also 

be defined as @NodeGroup to 

forward the value of the 

NodeGroup column in the 

status table. 


the transport protocol that the 

gateway uses. This property 

takes the following values: 

TCP: The gateway uses 

Transmission Control Protocol. 

UDP: The gateway uses User 

Datagram Protocol. 

The default is UDP. 

Gate.SNMP.Retries integer -snmpretries integer 

Note: Store-and-forward 

mode is not available when 

the gateway is using UDP. See 

“Store-and-forward mode” on 

page 22 for more information. 


the number of times that the 

gateway attempts to retry 

sending a message on failure. 

When this number is 

exceeded, the gateway stops 

sending the messages to the 

port. 





Gate.SNMP.SecurityLevel -snmpsecuritylevel string Use this property to specify 

string 

the security level that the 

gateway uses for SNMP V3 

messages. This property takes 

the following values: 

Gate.SNMP.SecurityName 

string 

Gate.SNMP.Security 

AuthProtocol string 

AuthnoPriv: The gateway 

sends the username and 

password in encrypted format. 

AuthPriv: The gateway 

transmits the SNMP traps in 

encrypted format. 

noAuthnoPriv: The gateway 

does not encrypt the 

username, the password, or 

the SNMP traps. 

The default is noAuthnoPriv. 


used with SNMP V3 traps. 

-snmpsecurityname string Use this property to specify 

the security name for the 

gateway as defined in the 

configuration file of the 

receiver. 

-snmpsecurityauthprotocol 

string 


The default is netcool. 




the authentication protocol 

that the gateway uses. This 

property takes the following 

values: 

MD5: The gateway uses the 

Message Digest 5 protocol. 

SHA1: The gateway uses the 

Secure Hash Algorithm 1 

protocol. 

The default is MD5. 


used with SNMP V3 traps.



Gate.SNMP.Security -snmpsecurityprivprotocol Use this property to specify 

PrivProtocol string string 

the privacy protocol that the 

gateway uses to encrypt data. 

This property takes the 

following values: 


AuthPassphrase string 


PrivPassphrase string 

Gate.SNMP.SNMPVersion 

integer 

-snmpsecurityauthpassphrase 

string 

-snmpsecuritypriv 

passphrase string 

AES: The gateway uses the 

Advanced Encryption 

Standard. 

DES: The gateway uses the 

Data Encryption Standard. 

The default is DES. 


the password used for 

authentication. 

The default is password. 

Note: The password must be 

at least eight characters long. 

This property is only used 

with SNMP V3 traps. 


the password used for privacy. 

The default is password. 



-snmpsnmpversion integer Use this property to specify 

the version of the SNMP 

writer. 

Gate.SNMP.Specific integer -snmpspecific integer 



the trap type value for the 

specific trap field in 

forwarded SNMP traps. 


See “Generic and specific 

traps” on page 20 for more 

information. 


be defined as @Class to 

forward the value of the Class 

column in the alerts.status 

table. 




Gate.SNMP.Store 

-snmpstoreandforward boolean Use this property to specify 

AndForward boolean 


runs in store-and-forward 

mode. 


Note: Store-and-forward 

mode is not available when 

the gateway is using the UDP 

transport protocol. See 

“Store-and-forward mode” on 

page 22 for more information. 

Gate.SNMP.StoreFile string -snmpstorefile string Use this property to specify 

the name and location of the 

storage file that the gateway 

uses when operating in 

store-and-forward mode. 

Gate.SNMP.Timeout integer -snmptimeout integer 


$OMNIHOME/var/ 

NCO_GATE_snmp_.store. 


the time (in seconds) that the 

gateway waits for a 

connection from an SNMP 

receiver before timing out. 


Gate.SNMP.Trap integer -snmptrap integer 


used when the 

Gate.SNMP.Protocol property 

is set to TCP. 


the trap type value of the 

generic trap field in 

forwarded SNMP traps. 


See “Generic and specific 

traps” on page 20 for more 

information. 


be defined as @Severity to 

forward the value of the 

Severity column in the 

alerts.status table. 

Map definition file 

The map definition file defines how the gateway maps data received from the 

SNMP writer to the Status, Journal, and Details tables within the ObjectServer. 

The default map definition file is $OMNIHOME/gates/snmp/snmp.map. 


Syntax 

You can configure the mapping functions of the gateway by using the mapper 

attributes. 

Mappings for use with the SNMP Writer Gateway must use the following syntax: 

CREATE MAPPING mappingname 

( 

varbindint = ’@fieldname’ 

[,varbindint = ’@fieldname’ [ ON INSERT ONLY ] ]... 

); 

where: 

v mappingname is the name of the mapping to be created. 

v varbindint is the integer value for the varbind field that will be written to in the 

SNMP trap. 

v fieldname is the name of a field in the ObjectServer alerts.status table. 

Example mapping 

The following default mapping is supplied in the snmp.map file: 

CREATE MAPPING StatusMap 

( 

’0’ = ’@Summary’, 

’1’ = ’@Severity’, 

’2’ = ’@Location’, 

’3’ = ’@Node’, 

’4’ = ’@AlertGroup’, 

’Node’ = ’@Node’ 

); 

Defining a lookup table 

You can define a lookup table within the map file and use it to transform values 

found in particular fields to a different set of values before constructing SNMP 

traps. 

The following is an example lookup table definition: 

CREATE LOOKUP ExampleTable ( 

{ ’source1’, ’target1’} 

{ ’source2’, ’target2’} 

etc ) 

This example is used in the map as follows: 

’3’ = Lookup(’@myfield’, ’ExampleTable’) 

Note: Changes or additions to the lookup table will only take effect after the 

gateway is stopped and restarted. 

Startup command file 

The startup command file contains a set of commands that the gateway performs 

automatically each time it starts. These commands allow the gateway to transfer 

any subsidiary table data to a set of target tables. 

The default startup command file is $OMNIHOME/gates/snmp/snmp.startup.cmd. 


Note: After the gateway has started, you can use the nco_sql command to 

manually issue commands. For more information about the nco_sql command, see 

the IBM Tivoli Netcool/OMNIbus Administration Guide (SC23-6371). 

Table 8 lists the available startup commands. 

Table 8. Startup commands 

Command Description Syntax Example 

SET PROPERTY Use this command to set the value of a SET PROPERTY SET PROPERTY 

property in the properties file. 

’string’ TO value ; ’Gate.Reader.Debug’ TO 

FALSE ; 

GET PROPERTY Use this command to return the value of GET PROPERTY GET PROPERTY 

a specified property from the properties 

file. 

’string’ ; 

’Gate.Reader.Debug’ ; 

SHOW PROPS Use this command to display the current SHOW PROPS ; SHOW PROPS ; 

configuration of the gateway by listing all 

properties and their values. 

go 

GET CONFIG Use this command to display the current 

configuration of the gateway by listing all 

properties and their values. 

Note: GET CONFIG is identical to the 

SHOW PROPS command and may be 

removed from later versions of the 

gateway. 

TRANSFER Use this command to initiate a data 

transfer operation between tables in two 

ObjectServers. 

Note: You can use a filter condition to 

transfer a partial table. If the target table 

does not match the source table, a map 

can be specified as part of the transfer 

operation. This map must be defined in 

the map definition file. 

FAILOVER SYNC Use this command to synchronize data 

between primary and backup 

ObjectServers. The command specifies 

which master tables are transferred 

during the data transfer operation. 

Failover Sync example 

GET CONFIG ; GET CONFIG ; 

go 

TRANSFER FROM 

sourcetable TO 

targettable [VIA 

FILTER filtertext] 

[WITH DELETE VIA 

delfiltertext] 

[USING TRANSFER_MAP 

mapname] ; 

FAILOVER_SYNC [ ADD 

’TABLENAME’ TO | 

REMOVE ’TABLENAME’ 

FROM ] WRITERNAME ; 

TRANSFER FROM 

’master.names’ TO 

’resync.names’ VIA 

FILTER ’Name != 

\’nobody\’’ DELETE ; 

In this example, all records 

with the name nobody are 

deleted from the 

resync.names table and 

replaced with 

corresponding records in 

the master.names table. 

See “Failover Sync 

example.” 

The following is an example of how to use the FAILOVER SYNC command in the 

startup command file: 

FAILOVER_SYNC ADD ’master.names’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’master.groups’TO ObjectServerA; 

FAILOVER_SYNC ADD ’master.members’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’master.permissions’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’master.profiles’TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.actions’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.action_access’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.menus’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.menu_defs’ TO ObjectServerA; 


FAILOVER_SYNC ADD ’tools.menu_items’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’tools.prompt_defs’TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.conversions’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.col_visuals’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.colors’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.objclass’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.objmenus’ TO ObjectServerA; 

FAILOVER_SYNC ADD ’alerts.objmenuitems’TO ObjectServerA; 

Table replication definition file 

The table replication definition file defines the tables in the source ObjectServer 

that the gateway replicates in the SNMP writer. 

The default table replication definition file is $OMNIHOME/gates/snmp/ 

snmp.reader.tblrep.def. 

The table replication definition file consists of a single REPLICATE command. It 

uses the following syntax: 

REPLICATE ALL | (INSERTS, UPDATES, DELETES) 

FROM TABLE sourcetable 

USING MAP mapname 

[CACHE FILTER condition] 

[FILTER WITH filter_clause] 

[INTO targettable] 

[ORDER BY column_name [ASC|DESC], ... ] 

[WITH NORESYNC] 

[RESYNC DELETE FILTER delete_filter_clause] 

[SET UPDTOINS CHECK TO {ENABLED|DISABLED|FORCED}] 

[AFTER IDUC DO command] ; 

where: 

v sourcetable is the name of table to be replicated in the target system. 

For example: alerts.status 

v mapname is the name of the map that defines the table. 

For example: StatusMap 

v condition is the SQL condition that the gateway adds to the SELECT statement 

when limiting the cache entries that the gateway retrieves during a cache 

refresh. 

v filter_clause defines the filter the gateway uses to select rows for replication. 

Filtering is inclusive by default, which means that the filter sends only those 

events that match the filter definition. However, you can make the filter send 

events that do not match the filter definition by putting an exclamation mark (!) 

before the equals sign (=) in the filter clause. For example, the following filter 

clause sends all events whose severity is not set to 5: FILTER WITH ’Severity 

!=5’. 

v targettable is the name of the table in which to replicate the data. 

v column_name is the column by which the rows returned to the gateway from the 

ObjectServer are ordered. 

v delete_filter_clause defines the resynchronization delete filter that the gateway 

issues to the target ObjectServer. 

Advanced properties 

After configuring the basic property settings required to run the gateway, you 

might have to specify some advanced properties to suit your operating 

environment. 


This section describes the property settings for the following gateway functions: 

v “TCP transport protocol” 

v “Generic and specific traps” 

v “SNMP V3 support” on page 21 

v “Event flush rate” on page 21 

v “Forwarding alert updates” on page 22 

v “Store-and-forward mode” on page 22 

v “Hash table cache” on page 23 

v “Process Agent control” on page 23 

v “Error handling” on page 23 

For more information about the properties described in this section, see “Properties 

and command line options” on page 6. 

TCP transport protocol 

You can run the gateway using the Transmission Control Protocol (TCP) transport 

protocol. 

To run the gateway using TCP, set the Gate.SNMP.Protocol property to TCP and 

specify an IP address and port number for the Gate.SNMP.Gateway property. 

For example: 

Gate.SNMP.Gateway : ’172.0.0.1:8080’ 

Gate.SNMP.Protocol : ’TCP’ 

When the gateway is using TCP, it sends traps to the specified port and it requires 

an application (for example, the SNMP Probe) to be listening on that port. If the 

listening application shuts down, the gateway logs an error message and attempts 

to restart the connection. If the gateway cannot reestablish a connection within the 

number of times specified by the Gate.SNMP.Retries property, the gateway shuts 

down. 

Note: Store-and-forward mode requires the gateway to use the TCP protocol. See 

“Store-and-forward mode” on page 22 for more information. 

Generic and specific traps 

The SNMP standard defines seven trap types that are generated by SNMPv1 

agents: six generic traps and one enterprise-specific trap. The enterprise-specific 

trap is used by organizations to define traps for particular devices. The generic 

trap types are fixed and cannot be changed, whereas it is possible to define 

multiple enterprise-specific traps. 

You can use the Gate.SNMP.Trap property to specify an integer value for the 

generic trap field in SNMP traps. 

Table 9 lists the six generic trap types defined for SNMPv1 agents. 

Table 9. Generic SNMP trap types 

Trap type Integer value 

coldStart 0 

warmStart 1 

linkDown 2 


Table 9. Generic SNMP trap types (continued) 

Trap type Integer value 

linkUp 3 

egpNeighborLoss 5 

authenticationFailure 4 

You can use the Gate.SNMP.Specific property to specify an integer value for the 

specific trap field in SNMP traps. It can take any integer value between 0 and 

2147483647. 

The trap message identity is determined based on the values contained in the 

Enterprises, Standard Trap Type, and Specific Trap Type fields of the Trap 

Protocol Data Unit (PDU). If the trap type value specified by the Gate.SNMP.Trap 

property is 0, 1, 2, 3, 4, or 5, the trap is a generic trap type and the value of the 

Specific Trap Type field will be 0. If the trap type value is 6, the trap is 

enterprise-specific and is defined in a private Management Information Base (MIB). 

SNMP V3 support 

The gateway supports SNMP V3 traps using the User-Based Security Model 

(USM). 

To use SNMP V3, you must specify values for the following properties: 

Table 10. SNMP V3 properties 

Property Description 

Gate.SNMP.EngineID This property specifies the gateway as the 

source of the SNMP V3 traps. 

Gate.SNMP.SecurityName This property specifies the security name of 

the gateway as defined in the configuration 

file of the SNMP receiver. 

Gate.SNMP.SecurityLevel This property specifies the security level that 

the gateway uses for SNMP V3 messages. 

Gate.SNMP.SecurityAuthProtocal This property specifies the authentication 

protocol that the gateway uses. 

Gate.SNMP.SecurityAuthPassphrase This property specifies the password 

required for authentication. 

Gate.SNMP.SecurityPrivProtocal This property specifies the privacy protocol 

that the gateway uses to encrypt traps. 

Gate.SNMP.SecurityPrivPassphrase This property specifies the password 

required for privacy. 

When an SNMP reader connects to the gateway, these property settings are written 

to a USM configuration file. For example, the SNMP Probe writes these details to 

$OMNIHOME/probes/arch/mttrapd.conf. 

Event flush rate 

You can control the rate at which the gateway reader requests updates from the 

ObjectServer. 


You can use the Gate.Reader.IducFlushRate property to specify the frequency (in 

seconds) at which the gateway reader requests updates from the ObjectServer 

using an Insert, Delete, Update, or Control (IDUC) communication protocol. 

The default value of the ObjectServer IDUC update interval is 60 seconds (as 

specified by the ObjectServer Granularity property). This default value is optimal 

for most systems. The default value of the Gate.Reader.IducFlushRate property is 

0, which equates to the default ObjectServer update interval. This means that, 

using the default setting of 0 seconds for the IDUC flush rate and the default 

setting of 60 for the ObjectServer granularity, the gateway reader gets its updates 

at 60-second intervals. 

You can specify a value greater than 0 for the Gate.Reader.IducFlushRate. This 

makes the gateway reader run at a faster rate (higher granularity) than the 

ObjectServer, thus enabling the gateway to capture more detailed event changes in 

systems where the ObjectServer itself has high granularity settings. 

Note: When both the ObjectServer Granularity property and the 

Gate.Reader.IducFlushRate property are set to their default values, the gateway's 

ability to forward alert updates is affected. If the Gate.SNMP.ForwardUpdates 

property is set to TRUE in these conditions, the gateway will not be able to capture 

all alert updates. 

Forwarding alert updates 

The gateway can forward updates to alerts that it has previously sent to the 

ObjectServer. 

The default gateway setting is to forward only new alerts to the ObjectServer. To 

forward alert updates, you must specify a value of TRUE for the 

Gate.SNMP.ForwardUpdates property. In effect, this reduplicates alerts (as opposed 

to the ObjectServer's deduplication mechanism). 

Note: The gateway never forwards alert deletion, journal, or details information. 

Store-and-forward mode 

When the remote SNMP writer is no longer active, the gateway can be run in 

store-and-forward mode. This ensures that the ObjectServer and database writers 

can continue to run. 

When the gateway detects that the target SNMP writer is not present or is not 

functioning (usually because the writer is unable to write an alert), it switches into 

store-and-forward mode. In this mode, the gateway stores everything it would 

normally send to the database in a storage file with a .store suffix. The default 

storage file is $OMNIHOME/var/NCO_GATE_snmp_.store. 

When the gateway detects that the destination server is back on line, it switches 

into forward mode and sends the alert information held in the storage file to the 

destination server. After all of the alerts in the storage file have been forwarded, 

the gateway returns to normal operation. 

Store-and-forward mode only works when a connection to the SNMP writer has 

first been established, used, and then lost. If the destination server is not running 

when the gateway starts, store-and-forward mode is not triggered and the gateway 

shuts down. 


If the gateway connects to the SNMP writer and a storage file already exists, the 

gateway forwards the contents of the file before it sends new alerts. 

To configure store-and-forward mode, set the Gate.SNMP.StoreAndForward property 

to TRUE and use the Gate.SNMP.StoreFile to specify a storage file. Restart the 

gateway to activate store-and-forward mode. 

To deactivate store-and-forward mode, set the Gate.SNMP.StoreAndForward property 

to FALSE and restart the gateway. 

Note: Store-and-forward mode will not work if the gateway is using the User 

Datagram Protocol (UDP) transport protocol. UDP communication is one-way only, 

so the gateway cannot detect if the target server to which it is trying to forward 

events is running. If you specify UDP as the transport protocol and you also 

activate store-and-forward mode, the storage file will not be created. To use 

store-and-forward mode, you must use the Gate.SNMP.Protocol property to specify 

the Transmission Control Protocol (TCP) transport protocol. 

Hash table cache 

The gateway uses a hash table cache to store details of tables that must be 

transferred from one ObjectServer to another. The cache aids performance 

optimization by providing the gateway with an in-memory summarized view of 

the contents of the ObjectServers to which it is linked. 

Using a hash table cache means that the gateway does not have to query an 

ObjectServer to check for the existence of an event, or the Serial value or Tally 

value of an event. Instead, it can check the cache of the target ObjectServer. 

The main function of the cache is to facilitate insert operations in Journal and 

Details tables. When a journal or detail is forwarded for insertion into a target 

ObjectServer, the gateway writer needs to know the corresponding Serial value in 

the target ObjectServer. This information is found in the cache. It is also used for 

any other tables specified using the table replication definition table. 

You can control the size of the hash table cache using the Gate.CacheHashTblSize 

property. By default, the size of the hash table cache is 5023 elements (rows). This 

can be increased if the status table has a large number of rows (for example, in 

excess of 20,000). 

Note: To maximize efficiency, you should specify a prime number for the 

Gate.CacheHashTblSize property. 

Process Agent control 

The gateway can be run under Process Agent (PA) control. 

The Gate.PAAware property specifies whether or not the gateway is PA-aware. The 

Gate.PAAwareName property specifies which PA is running the gateway. 

Note: These properties are maintained automatically by the PA server and provide 

information only. Do not manually change the values of these properties. 

Error handling 

You can troubleshoot problems with the gateway by consulting error messages. To 

help you do this, the gateway has configurable error handling. 


AES encryption 

Error handling is provided by the Tivoli Netcool/OMNIbus Gateway Toolkit 

(NGTK) library. To specify that the NGTK library logs debug messages, set the 

Gate.NGtkDebug property to TRUE. 

AES encryption can be used to encrypt any string within the gateway writer 

section of the configuration file. It is used by the gateway to prevent sensitive data 

from being available in readable format in the gateway configuration file. 

Note: AES encryption is supported on Tivoli Netcool/OMNIbus V7.2.0 (and 

above) on all UNIX and Linux operating systems. 

nco_aes_crypt 

You can encrypt strings in the gateway configuration file using the nco_aes_crypt 

tool (supplied with Tivoli Netcool/OMNIbus). The syntax of encrypted data is as 

follows: 

@datalength:encrypted_data@ 

Where datalength is the length of the data in bytes (expressed as a decimal) and 

the data itself is base64 encoded. The at sign (@) indicates the start and end of the 

encrypted data definition. The colon (:) acts as a field separator. 

The encrypted values appear in single quotes on the right side of expressions in 

the writer section of the configuration file. The following is an example line from a 

configuration file showing the host name given in encrypted format: 

HOST =’@64:lHBLuIPLNye8zCWhykFVFY7y90V9kCjGK5GSWu5VBdSlgQOqarq6T4UK4xk5Vqix@’ 

Note: You can obtain the nco_aes_crypt tool from the IBM Passport Advantage 

website: http://www-306.ibm.com/software/howtobuy/passportadvantage/ 

pao_customers.htm. Access the Software Downloads section and search for 

Netcool/OMNIbus Gateway configuration encryption library. 

Using the nco_aes_crypt tool 

Data in the configuration file must be encrypted using the nco_aes_crypt tool. 

This is a command line tool which takes the following format: 

nco_aes_crypt [-d | -e] [-o outfile] -kkeyfile -f filename 

nco_aes_crypt [-d | -e] [-o outfile] -kkeyfile data 

The output of this command will be the encrypted string to be used in the 

configuration file. 

The following table describes the options available with nco_aes_crypt: 


Table 11. nco_aes_crypt command line options 

Command line option Description 

-d or-e Use this option to specify the mode in which 

the nco_aes_crypt tool runs: 

d - decrypt mode 

e - encrypt mode 

The default is e. 

-o string Use this option to specify the output file to 

which the encrypted data will be written. 

-k string Use this option to specify the path of the file 

containing the key data. 

-f string Use this option to specify the path of the file 

containing data requiring encryption. 

data Use this option to specify the data to be 

encrypted or decrypted. 

Encryption key file 

The encryption key is stored in a flat file alongside the encrypted data. The key 

storage file has an ASCII numeric key length indicator followed by a colon and the 

key in binary form. 

The format of the key file is as follows: 

key_length:key_data 

Where key_length is the length of the key in bits and the key_data is the key in 

binary form. Valid length values are 128, 192 and 256. 

For example: 

128:1234567812345678 

In this case, key_length is 128 since the ASCII string 1234567812345678 has 16 

bytes (128 bits). 

You can generate random or pre-defined keys of varying lengths using nco_keygen. 

To generate a key file, use the following command: 

nco_keygen -o outfile[-l length|-k]key][-h |-?] 

The following table gives the descriptions of the above command line options. 

Table 12. Encrytion key file command line options 


-o outfile Use this option to specify the output file 

name. 

-l length Use this option to specify the length (in bits) 

of the key to write out. 


Note: The value that you specify must be 

divisible by 8. 


Running the gateway 

Table 12. Encrytion key file command line options (continued) 


-k key Use this option to specify the key to be 

written out, expressed as hex digits. 

Note: This option bypasses automatic key 

generation. 

-h |-? Use this option to print the help information 

and exit 

Note: AES encryption is used as the initial encryption method for sensitive data. 

However, this does not mean that the data can be considered to be secure purely 

due to AES encryption; the security of the data depends on the restriction of access 

to the key file used for AES encryption. Access to this file is controlled using UNIX 

file permissions. 

Using encrypted data 

To use encrypted data, you must add the following line to the WRITER section of 

the configuration file: 

LOAD ENCRYPTION KEY FROM ’key_file_path’ USING ’AES’ 

Where key_file_path is the path to the file containing the encryption key. 

Running the ObjectServer in a secure mode 

When the gateway connects to the ObjectServer running in secure mode, it needs 

to authenticate with a user name and password. This user name and password can 

be encrypted using the nco_aes_crypt tool. 

To enable the encryption, the location of the key file must be specified at the 

beginning of the configuration file. This is followed by the AUTH_USER and 

AUTH_PASSWORD fields which contain the encrypted user name and password 

required for authentication. 

The following example shows the three fields that need to be added at the 

beginning of the configuration file when the ObjectServer runs in a secure mode: 

LOAD ENCRYPTION KEY FROM ’/HOME/72/solaris/omnibus/keyflie_name’ USING 

’AES’; 

AUTH_USER ’@44:2yXgd6fp9q1Ey4sSAb2RibzA3+PpCZmhAZXo6nNdkvQ=@’; # 

encrypted_user_name 

AUTH_PASSWORD ’@44:mdyEb8VTh+2wALnNlR7dnGnxRZ3BkMOQbR5IgxLlHuc=@’; # 

encrypted_password 

This topic describes how to run the gateway. On Windows operating systems, you 

can run the gateway as a service. 

To start the gateway on UNIX and Linux operating systems, run the following 

command: 

$OMNIHOME/bin/nco_g_snmp 

To start the gateway as a process on Windows operating systems, run the 



Error messages 

%OMNIHOME%\bin\nco_g_snmp.exe 

To start the gateway as a service on Windows operating systems, use the following 

steps: 

1. Register the gateway with the Service Control Manager. 

2. If the gateway and the ObjectServer are running on the same host, run the 


%OMNIHOME%\bin\nco_g_snmp.exe -install -depend NCOObjectServer 

3. If the gateway and the ObjectServer are running on different hosts, run the 


%OMNIHOME%\bin\nco_g_snmp.exe -install 

4. Start the gateway using the Microsoft Services Management Console. 

Error messages provide information about problems that have occurred during the 

operation of the gateway. You can use the information that they contain to resolve 

such problems. 

The following table describes the error messages that the gateway generates: 

Table 13. Error messages 

Error Description Action 

Failed to send trap for The gateway failed to Verify that the endpoint is 

SNMP trap forwarder with forward a trap for the reason available and reachable. 

error error. Retrying... specified in the error Check for any intervening 

message. It is trying to 

re-send the trap. 

firewalls. 

Failed to create session The gateway was unable to Verify that the endpoint is 

for SNMP trap forwarder. reconnect to the endpoint still available and that there 

after a previous 

disconnection. 

is no intervening firewall. 

Failed to initialize The gateway could not Verify that the properties file 

gateway properties. initialize the gateway has correct permissions. 

properties. 

Check the values set in the 


Invalid value specified The transport protocol field Specify the value of the 

for PROTOCOL attribute. is incorrectly specified and Gate.SNMP.Protocol property 

Ignored and using UDP. the gateway is defaulting to 

the UDP protocol. 

as either UDP or TCP. 

Node index not found for The gateway was unable to Verify that there is a ’Node’ 

SNMP trap forwarder find a column entitled 'Node' = ’@’ entry in 

in the configured table. the mapping file that you are 

using. 

oid property has an The Gate.SNMP.OID property Ensure that the 

invalid value; must be a must be specified as an Gate.SNMP.OID property is 

string or a field 

object identifier (OID) string specified as an OID string or 

reference. 

or a reference to the node 

group field. 

as @NodeGroup. 

Snmpversion property has The SNMP writer version is Specify the value of the 

unknown SNMP version incorrectly specified. Gate.SNMP.SNMPVersion 

specified in SNMP trap 

forwarder. Please set it 

to12or3 

property as either 1, 2, or3. 


Table 13. Error messages (continued) 

Error Description Action 

Specific property has an The value for the specific Specify the value of the 

invalid value; must be a trap field in forwarded Gate.SNMP.Specific property 

number or a field 

SNMP traps is incorrectly as either an integer or as 

reference. 

specified. 

@Class. 

Security level property The security level that the Specify one of the following 

has an invalid value; must gateway uses for SNMP V3 values for the 

be one of the following: messages is incorrectly Gate.SNMP.SecurityLevel 

noAuthnoPriv AuthnoPriv specified. 

property: 

AuthPriv 

v noAuthnoPriv 

v AuthnoPriv 

v AuthPriv 

Setting security level to The gateway is setting the The gateway is setting the 

noAuthnoPriv 

security level for SNMP V3 security level for SNMP V3 

messages to noAuthnoPriv. At messages to noAuthnoPriv. 

this security level, the You can set the security level 

gateway does not encrypt the to AuthnoPriv or AuthPriv 

username, the password, or using the 

the SNMP traps. 

Gate.SNMP.SecurityLevel 

property. 

Security auth protocol The authentication protocol Specify one of the following 

property has an invalid that the gateway uses for values for the 

value; must be one of the SNMP V3 traps is incorrectly Gate.SNMP.Security 

following: SHA1 MD5 specified. 

AuthProtocol property: 

v MD5 

v SHA1 

Security priv protocol The privacy protocol The gateway is setting the 

property has an invalid (encryption standard) that privacy protocol to DES. You 

value; must be one of the the gateway uses to encrypt can make the gateway use 

following: DES AES. data is incorrectly specified. AES encryption by setting the 

Setting security priv The gateway is setting the value of the 

protocol to DES 

protocol to DES. 


PrivProtocol property to 

AES. 

Security auth phrase must The password that the Specify the value of the 

be at least 8 characters gateway uses for SNMP V3 Gate.SNMP.Security 

long 

authentication is not long AuthPassphrase property as a 

enough. 

string at least eight 

characters long. 

SNMP Writer 'writer': The SNMP writer failed to Verify that the file is writable 

Failed to write record to write a SAF record to the file and that the device is not 

SAF store file. 

specified. 

full. 

Trap property has an The value for the generic Specify the value of the 

invalid value; must be trap field in SNMP 

Gate.SNMP.Trap property as 

integer or field 

forwarded traps is 

either an integer or as 

reference. 

incorrectly specified. @Severity. 


Appendix. Notices and Trademarks 

Notices 

This appendix contains the following sections: 

v Notices 

v Trademarks 

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

IBM may not offer the products, services, or features discussed in this document in 

other countries. Consult your local IBM representative for information on the 

products and services currently available in your area. Any reference to an IBM 

product, program, or service is not intended to state or imply that only that IBM 

product, program, or service may be used. Any functionally equivalent product, 

program, or service that does not infringe any IBM intellectual property right may 

be used instead. However, it is the user's responsibility to evaluate and verify the 

operation of any non-IBM product, program, or service. 

IBM may have patents or pending patent applications covering subject matter 

described in this document. The furnishing of this document does not grant you 

any license to these patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 

IBM Corporation 

North Castle Drive 

Armonk, NY 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, 2012 29

Any references in this information to non-IBM Web sites are provided for 

convenience only and do not in any manner serve as an endorsement of those Web 

sites. The materials at those Web sites are not part of the materials for this IBM 

product and use of those Web sites is at your own risk. 

IBM may use or distribute any of the information you supply in any way it 

believes appropriate without incurring any obligation to you. 

Licensees of this program who want to have information about it for the purpose 

of enabling: (i) the exchange of information between independently created 

programs and other programs (including this one) and (ii) the mutual use of the 

information which has been exchanged, should contact: 

IBM Corporation 

Software Interoperability Coordinator, Department 49XA 

3605 Highway 52 N 

Rochester, MN 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 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. 


Trademarks 

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. 

IBM, the IBM logo, ibm.com, AIX, Tivoli, zSeries, and Netcool are trademarks of 

International Business Machines Corporation in the United States, other countries, 

or both. 

Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-based 

trademarks are either registered trademarks or trademarks of Adobe Systems 

Incorporated in the United States, other countries, or both. 

Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation 

in the United States, other countries, or both. 

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of 

Microsoft Corporation in the United States, other countries, or both. 

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in 

the United States, other countries, or both. 

Linux is a trademark of Linus Torvalds in the United States, other countries, or 

both. 

UNIX is a registered trademark of The Open Group in the United States and other 

countries. 

Appendix. Notices and Trademarks 31


�� 

Printed in USA 

SC23-7804-07

IBM Tivoli Netcool/OMNIbus SNMP Writer Gateway: Reference Guide

Create successful ePaper yourself

Delete template?

Save as template?