Version 1.0 Netcool/OMNIbus Probe for OPC UnifiedTable 3. Summary Probe target Network devices and EMS that implement the OPC UA 1.0.2 specification. Probe executable name The way

Netcool/OMNIbus Probe for OPC UnifiedArchitecture (UA)1.0

Reference GuideDecember 13, 2019

IBM

SC27-6552-01

Note

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

Edition notice

This edition (SC27-6552-01) applies to version 1.0 of the IBM Tivoli Netcool/OMNIbus Probe for OPC UnifiedArchitecture (UA) and to all subsequent releases and modifications until otherwise indicated in new editions.

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

Contents

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

Chapter 1. Probe for OPC UA.................................................................................. 1Summary...................................................................................................................................................... 1Getting started............................................................................................................................................. 3Installing probes.......................................................................................................................................... 4Configuring the probe.................................................................................................................................. 5Data acquisition........................................................................................................................................... 6

ObjectServer information....................................................................................................................... 7OPC UA communications information....................................................................................................7Connecting to the OPC UA server...........................................................................................................8Establishing a secure connection to the OPC UA server..................................................................... 10Notification retrieval and synchronization...........................................................................................14Reconnection and probe backoff strategy...........................................................................................16Inactivity...............................................................................................................................................16Data stream capture.............................................................................................................................16Support for Unicode and non-Unicode characters..............................................................................17Peer-to-peer failover functionality...................................................................................................... 18Using the OPC Foundation sample server........................................................................................... 18

Running the probe..................................................................................................................................... 20Running multiple probes......................................................................................................................20Running the probe as a Windows service............................................................................................21

Properties and command line options...................................................................................................... 21Elements.................................................................................................................................................... 29Error messages.......................................................................................................................................... 30ProbeWatch messages.............................................................................................................................. 38Known issues............................................................................................................................................. 40

Chapter 2. The XML configuration files for event and data change notifications......41Structure of the XML configuration files....................................................................................................41.................................................................................................... 43.............................................................................................................. 43

................................................................................................................................. 43..................................................................................................................... 43................................................................................................................................................. 44

...................................................................................................................................45..............................................................................................................................................46

..................................................................................................................46...................................................................................................................... 47

Customizing the XML configuration files................................................................................................... 47

Appendix A. Notices and Trademarks................................................................... 59Notices....................................................................................................................................................... 59Trademarks................................................................................................................................................ 60

iii

About this guide

The following sections contain important information about using this guide.

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

The IBM Tivoli Netcool/OMNIbus Probe for OPC Unified Architecture (UA) documentation is provided insoftcopy format only. To obtain the most recent version, visit the IBM® Tivoli® Knowledge Center:

http://www-01.ibm.com/support/knowledgecenter/?lang=en#!/SSSHTQ/omnibus/probes/common/Probes.html

Table 1. Document modification history

Documentversion

Publicationdate

Comments

SC27-6552-00 November 7,2014

First IBM publication.

SC27-6552-01 December 13,2019

“Known issues” on page 40 added.

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

Operating system-dependent variables and pathsAll probe guides use standard conventions for specifying environment variables and describing directorypaths, depending on what operating systems the probe is supported on.

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

$OMNIHOME/probes

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

%OMNIHOME%\probes

For probes supported on UNIX, Linux, and Windows operating systems, probe guides use the standardUNIX conventions for specifying environment variables and describing directory paths. When using theWindows command line with these probes, replace the UNIX conventions used in the guide with Windowsconventions. If you are using the bash shell on a Windows system, you can use the UNIX conventions.

Note : The names of environment variables are not always the same in Windows and UNIX environments.For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX and Linuxenvironments. Where such variables are described in the guide, both the UNIX and Windows conventionswill be used.

© Copyright IBM Corp. 2014, 2019 v

http://www-01.ibm.com/support/knowledgecenter/?lang=en#!/SSSHTQ/omnibus/probes/common/Probes.htmlhttp://www-01.ibm.com/support/knowledgecenter/?lang=en#!/SSSHTQ/omnibus/probes/common/Probes.html

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

$OMNIHOME/probes/arch

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

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

Table 2. Directory names for the arch variable

Operating system Directory name represented by arch

AIX® systems aix5

Red Hat Linux® and SUSE systems linux2x86

Linux for System z linux2s390

Solaris systems solaris2

Windows systems win32

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

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

vi IBM Tivoli Netcool/OMNIbus Probe for OPC Unified Architecture (UA): Reference Guide

Chapter 1. Probe for OPC UA

The IBM Tivoli Netcool/OMNIbus Probe for OPC Unified Architecture (UA) acquires data from devices andelement management systems (EMS) that use the OPC UA messaging architecture.

OPC UA is a server-client architecture. The device or EMS acts as the server and the probe as the client.Communication between them takes place over a SOAP interface.

The OPC UA server has one or more items under its control. For example, the reading on a thermostat, orthe operational status of a piece of machinery. You configure the probe to monitor one or more of theseitems. The probe registers this information with the OPC UA server. At regular intervals, the OPC UA serverpolls the items to determine if changes have occurred on any of them. The following types of changes canoccur, depending on the type of item:

• Data change• Status change• Device event

The OPC UA server records each change in a notification.

Also at regular intervals, but not necessarily the same interval, the probe requests the OPC UA server tosend the notifications it has gathered since the probe asked for notifications. The probe parses thesenotifications, converts them into Netcool/OMNIbus events, and sends them to the ObjectServer.

You can run a pair of probes in a failover configuration where one acts as the master probe and the otherthe slave probe. In normal operation, the master probe receives notifications and passes them on to theObjectServer. Should the master probe fail, the slave probe takes over until the master probe is availableonce more.

You can run a number of probes on a single physical server independently of one another. This enablesnotifications to be processed from a number of sources simultaneously.

This guide contains the following sections:

• “Summary” on page 1• “Getting started” on page 3• “Installing probes” on page 4• “Data acquisition” on page 6• “Properties and command line options” on page 21• “Running the probe” on page 20• “Elements” on page 29• “Error messages” on page 30• “ProbeWatch messages” on page 38

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

The following table provides a summary of the IBM Tivoli Netcool/OMNIbus Probe for OPC UnifiedArchitecture (UA).

Note : The Probe for OPC UA is based on the OPC Unified Architecture (UA) 1.0.2 specification.

© Copyright IBM Corp. 2014, 2019 1

Table 3. Summary

Probe target Network devices and EMS that implement the OPC UA 1.0.2specification.

Probe executable name The way in which you run (execute) the probe depends onwhether you are running UNIX or Windows:

• nco_p_opc_ua (UNIX, Linux)• nco_p_opc_ua.bat Windows

Package version 1.0

Probe supported on For details of supported operating systems, see the followingRelease Notice on the IBM Software Support website:https://www-304.ibm.com/support/docview.wss?uid=swg21687620

Properties file $NCHOME/omnibus/probes/arch/opc_ua.props

Rules file $NCHOME/omnibus/probes/arch/opc_ua.rules

Sample XML configuration files forevent and data change notification

$OMNIHOME/var/OpcUaEvent.xml

$OMNIHOME/var/OpcUaDataChange.xml

%OMNIHOME%\var\OpcUaEvent.xml

%OMNIHOME%\var\OpcUaDataChange.xml

Additional probe files The following additional probe files deliver with the probe:

• opc_ua_dsl_log.properties - used to configure theadvanced log settings in the Domain-Specific Language (DSL)framework. This is the default file for the DSSLLogConfigproperty.

See “Properties and command line options” on page 21 formore information.

• generic_opc_ua.jar - generated from the OPC FoundationWSDL set to support probe Web Service transactions.

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

Connection method The probe connects to the OPC UA server session endpointusing a web service HTTP/SOAP interface.

Multicultural support Available

Peer-to-peer failover functionality Available

IP environment IPv4 and IPv6

2 IBM Tivoli Netcool/OMNIbus Probe for OPC Unified Architecture (UA): Reference Guide

https://www-304.ibm.com/support/docview.wss?uid=swg21687620https://www-304.ibm.com/support/docview.wss?uid=swg21687620

Table 3. Summary (continued)

Federal Information ProcessingStandards (FIPS)

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

Getting startedThis section shows how to start the probe with the minimum required configuration. The procedureassumes that you have a version of Netcool/OMNIbus installed and running.

Use the following procedure to start the probe with a minimal configuration:

Note : The commands shown in this example are for a Linux system. Adapt these commands as necessaryfor the operating system that your probe server runs.

1. Download the probe's installation package following the instructions in http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_download_intro.html.

2. Install the probe following the instructions in http://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_install_intro.html.

3. Edit the probe's properties file and set values for the following:

• Server: Set this property to the name of the ObjectServer that the probe sends events to. Thedefault value of this property is NCOMS.

• MessageLevel: Set this property to Debug. This setting provides the maximum amount ofinformation when the probe is running.

• EndpointHttpHost: Set this property to the HTTP host name or IP address of the OPC UA serverhost that provides alarms to the probe.

• EndpointHttpPort: Set this property to the HTTP port on the OPC UA server that the probe usesto retrieve alarms.

• EndpointSessionServiceName: Set this property to the service name path of the endpoint onthe OPC UA server.

• OPCSessionName: Set this property to the name of the probe session on the OPC UA server towhich you want to connect.

• MonitoredItemsConfigFile: Set this property to the full path of the XML file that containsinformation on the items that the probe is to monitor. The information in this file is used in the OPCUA CreateMonitoredItems service.

See “Notification retrieval and synchronization” on page 14 for more information on this file.4. Ensure that $NCHOME/etc/omni.dat includes information on the ObjectServer.5. If you made changes to omni.dat, regenerate the definition file by running $NCHOME/bin/nco_igen.

6. Check that the server where you have installed the probe can contact the ObjectServer using theping utility. For example:

ping -c 10 server-name

Replace server-name with the name of the server where the ObjectServer is running.

Chapter 1. Probe for OPC UA 3

http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htmhttp://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2004.htmhttp://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_download_intro.htmlhttp://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_download_intro.htmlhttp://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_download_intro.htmlhttp://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_install_intro.htmlhttp://www-01.ibm.com/support/knowledgecenter/SSSHTQ/omnibus/probes/all_probes/wip/reference/install_install_intro.html

Alternatively, if you have installed the Netcool/OMNIbus desktop feature, you can use the nco_pingutility to check connectivity to the ObjectServer. For example:

nco_ping object-server

Replace object-server with the name of the ObjectServer.7. Obtain a listing of the probe's command line options to check the probe is installed correctly:

$NCHOME/omnibus/probes/nco_p_opc_ua -help

8. Start the probe as follows:

$NCHOME/omnibus/probes/nco_p_opc_ua \-propsfile $NCHOME/omnibus/probes/linux2x86/opc_ua.props \-messagelevel debug

9. Check the probe's log file to ensure the probe started correctly and is ready to receive, process, anddispatch events.

The probe's MessageLog property provides the name and location of the probe's log file.10. Where possible, use a test tool to send events to the probe in order to check that the probe processes

the events correctly.

For example, SoapUI (which allows you to set up a mock service server) and the OPC Foundationsample server, which provides sample implementations of OPC UA applications, both servers andclients.

See “Using the OPC Foundation sample server” on page 18 for more information on the OPCFoundation sample server.

The probe is now successfully installed and operational. You can now configure the probe to suit youroperating environment.

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

The installation process consists of the following steps:

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

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

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

2. Installing the probe using the installation package.

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

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

3. Configuring the probe.

This guide contains details of the essential configuration required to run this probe. It combines topicsthat are common to all probes and topics that are peculiar to this probe. For details about additional


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

configuration that is common to all probes, see the IBM Tivoli Netcool/OMNIbus Probe and GatewayGuide.

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

The following table lists the probe's features. For each feature, the table lists the properties you use to setup that feature, and the section in this guide that shows you how to set up the feature.

Some features are mandatory for all installations. For those features set the properties to the correctvalues or verify that their default values are suitable for your environment. The remaining features areoptional depending on which ones you want to use.

Table 4. Configuring the probe

Feature Properties See

Mandatory features:

OPC UA connection information

The information needed tocorrectly populate the header ofeach request message that theprobe sends.

RequestHeaderRequestHandleRequestHeaderReturnDiagnosticsRequestHeaderTimeoutHint

“OPC UA communicationsinformation” on page 7

SOAP connection information

The information needed toconnect the OPC UA sessionendpoint (the device or EMS)with the web service SOAPinterface.

EndpointHttpHostEndpointHttpPortEndpointSessionServiceNameOPCSessionNameMaxResponseMessageSizeRequestedSessionTimeout

“Connecting to the OPC UAserver” on page 8

Notification retrievalinformation

The information needed toretrieve notification information

AcknowledgeAlarmRequestedPublishingIntervalMaxNotificationsPerPublishRequestedLifetimeCountRequestedMaxKeepAliveCountResyncIntervalMonitoredItemsConfigFile

“Notification retrieval andsynchronization” on page 14

ObjectServer host name Server “ObjectServer information” onpage 7

Optional features:

Reconnection policy

Specifies whether the probeattempts to reconnect to theOPC UA endpoint following acommunications failure.

RetryCountRetryInterval

“Reconnection and probebackoff strategy” on page 16


Table 4. Configuring the probe (continued)

Feature Properties See

Inactivity policy

Specifies whether the probedisconnects from the OPC UAendpoint following a period ofinactivity.

Inactivity “Inactivity” on page 16

Data Stream Capture

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

StreamCaptureStreamCaptureFilepath

“Data stream capture” on page16

Peer-to-peer failover pair

Allows you to set up two probesto act as a failover pair toimprove availability. If themaster probe should stopworking, the slave probes takesover until the master is availableonce more.

MessageLogModePeerHostPeerPortPidFilePropsFileRulesFile

“Peer-to-peer failoverfunctionality” on page 18

Use a sample server

Allows you to use a sampleserver.

EndpointHttpHostEndpointHttpPortEndpointHttpServiceEndpointHttpTnsEndpointSessionServiceNameOPCSessionNameMaxResponseMessageSizeRequestedSessionTimeout

“Using the OPC Foundationsample server” on page 18

Running multiple instances ofthe probe

Allows you to run two or moreinstances of the probe on asingle host machine.

NameMessageLogPidFilePropsFileRulesFile

“Running multiple probes” onpage 20

Running the probe as aWindows service

None “Running the probe as aWindows service” on page 21

Data acquisitionEach probe uses a different method to acquire data. Which method the probe uses depends on the targetsystem from which it receives data.

The IBM Tivoli Netcool/OMNIbus Probe for OPC Unified Architecture (UA) acquires data from an OPC UAserver by issuing publish requests periodically. The OPC UA server responds by sending any outstandingnotifications. The probe parses these notifications into events that it forwards to the ObjectServer.

Data acquisition is described in the following topics:

• “ObjectServer information” on page 7• “OPC UA communications information” on page 7


• “Connecting to the OPC UA server” on page 8• “Notification retrieval and synchronization” on page 14• “Reconnection and probe backoff strategy” on page 16• “Inactivity” on page 16• “Data stream capture” on page 16• “Support for Unicode and non-Unicode characters” on page 17• “Peer-to-peer failover functionality” on page 18• “Using the OPC Foundation sample server” on page 18

ObjectServer informationThe probe sends processed events to an ObjectServer resource. This can be a single server or a failoverpair of ObjectServers.

The probe sends processed events to an ObjectServer resource. This can be a single server or a failoverpair of ObjectServers.

Single ObjectServerConfigure the probe to communicate with an ObjectServer by setting the Server property to the name ofthe ObjectServer.

Failover pairOptionally, you can define a failover pair of ObjectServers. One of them acts as the primary ObjectServerthat the probe communicates with initially. Should that ObjectServer become unreachable, the probecommunicates with the other, backup ObjectServer. To define a failover pair set the following probeproperties:

Table 5. Properties that define a failover pair of ObjectServers

Property Value

Server Set this property to the name of the primary ObjectServer.

ServerBackup Set this property to the name of the backup ObjectServer.

NetworkTimeout Set this property to the timeout period, in seconds, for the primary ObjectServer. Ifthe probe does not receive a response from the primary ObjectServer within thattime, it connects to the backup ObjectServer.

PollServer Set this property to the time period, in seconds, when the probe tries to reconnectto the primary ObjectServer.

Note : Ensure that the value of NetworkTimeout is less than the value of PollServer.

OPC UA communications informationCommunication between the probe and the OPC Unified Architecture (UA) server consists of a sequenceof messages. The probe issues a request, and the server returns a response. Each message has two parts:

• A header that contains control and security information• A body that contains the actual request or response

The request header includes a number of parameters that are common to all service requests. The probemaintains these parameters as properties:


Table 6. Properties used in request headers

Property Usage

RequestHeaderRequestHandle Specifies the requestHandle assigned to one ormore requests. The requestHandle can be used tocancel the requests. All outstanding requests withthe matching requestHandle will be cancelled.

RequestHeaderReturnDiagnostics An integer value that represents a bit mask thatdefines the diagnostic information the server is toreturn in the response. This value appears in thereturnDiagnostics field of the header.

The value of this property can consist of 0 (zero) ora bit value available in the bit mask defined by theOPC-UA specification. The default value of 64(0x0000 0040) indicates that the diagnostics toreturn is "OperationalLevel / LocalizedText".Specifying no value indicates that diagnostics arenot to be returned.

The content of the diagnostic information isvendor-specific. Refer to the documentation for theOPC UA device your site uses for information aboutreturn diagnostic information.

RequestHeaderTimeoutHint Specifies the timeout period (in milliseconds) forall HTTP requests sent to the OPC UA server. Thisvalue appears in the timeoutHint field of theheader.

For a server this timeout is only a hint and can beused to cancel long running operations to freeresources. If the server detects a timeout, it cancancel the operation by sending the Service resultBad_Timeout. The server should wait for thespecified timeout period after it received therequest before cancelling the operation. Specifyinga value of 0 indicates no timeout period.

Ensure that all these properties have values that are suitable for the needs of your site.

Connecting to the OPC UA serverThe probe uses an exchange of SOAP messages that encapsulate various OPC Unified Architecture (UA)services to establish a connection with the EMS.

The process of connecting to the OPC UA server has the following stages:

1. “Creating a secure channel” on page 9.2. “Creating a OPC UA session” on page 9.3. “Activating the OPC UA session” on page 10.

The following sections summarize the actions in each stage and highlight the properties that the probeuses in each stage.


Creating a secure channelThe probe uses secure transport layer (SSL) to enable a secured HTTPS transmission. You can choose touse HTTP (non-secured) or HTTPS by configuring EnableSSL and setting the keystore/truststore.

Creating a OPC UA sessionOnce the secure channel is established the probe creates an OPC UA session with the OPC UA serverusing the OPC UA CreateSession service. This service has a number of parameters that define thecharacteristics of the session. The probe maintains values for some of the parameters as properties.

Table 7. Properties used in the CreateSession service

Properties Usage

EndpointHttpHostEndpointHttpPortEndpointSessionServiceName

The probe uses these properties to construct theURL of the OPC UA server as follows:

http://host:port/service

Where:

• host is the value of the EndpointHttpHostproperty. This value can either be a hostname oran IP (IPv4/IPv6) address.

If you specify an IPv6 address, ensure that theaddress is enclosed in [] (square brackets). Forexample, as a value in the properties file:

EndpointHttpHost:'[2001:15f8:106:195:250:56ff:fe9c:5183]'

For example, in the command line:

-httphost [2001:15f8:106:195:250:56ff:fe9c:5183]

• port is the value of the EndpointHttpPortproperty.

• service is the value of theEndpointSessionServiceName property.

In addition, if the EndpointWsdlLocationproperty is empty (by default), the probe will usethe formed URL to reach the WSDL location. Theformed URL is http://host:port/server?wsdl http://:/.

OPCSessionName The name for the OPC UA session.


Table 7. Properties used in the CreateSession service (continued)

Properties Usage

RequestedSessionTimeout The maximum amount of time (in milliseconds)that the session can remain in use withoutcommunications activity taking place. If the probefails to issue a Service request within this interval,then the OPC UA server automatically terminatesthe session.

Make sure that the value of this property is greaterthan the value of the ResynchInterval property.

MaxResponseMessageSize The maximum size (in bytes) of the body of anymessage that the OPC UA server sends to theprobe.

Ensure that all these properties have values that are suitable for the needs of your site.

Activating the OPC UA sessionHaving created the OPC UA session, the probe uses the OPC UA ActivateSession service to bring it intouse.

Establishing a secure connection to the OPC UA serverThe probe uses an exchange of SOAP messages that encapsulate various OPC Unified Architecture (UA)services to establish a connection with the EMS.

To establish a secure communication between the probe and the OPC UA server, you should use an SSLconnection with HTTPS. Such a connection significantly reduces the vulnerabilities of hijacked sessionsand passwords.

Configuring SSL connectionsIf the OPC UA server is using a Secure Socket Layer (SSL) connection to encrypt data exchanged over JMSand HTTP, you will need to configure the truststore for the HTTPS connection on the Tivoli Netcool/OMNIbus probe server. This is the server on which the probe is running.

Summary of SSL configurationThe SSL configuration requires that you perform some tasks on the OPC Unified Architecture (UA) serverand some tasks on the Tivoli Netcool/OMNIbus probe server. The following list summarizes these tasks:

• On the OPC UA server:

– Obtain the OPC UA server security certificate from the certificate authority (CA) or use a self-signedcertificate.

– Import the CA or self-signed certificate into the server truststore.– Export the server truststore (which contains the CA or self-signed certificate) into a certificate file

that can be handed to the client (probe).– Or, export the OPC UA server keystore file.

• On the Tivoli Netcool/OMNIbus probe server (client):

– Import the OPC UA server security certificate or import the OPC UA server keystore file.– Verify either the OPC UA server security certificate or the OPC UA server keystore file.– Configure the probe either for one-way SSL connection or for two-way SSL connection.


Note : You can obtain the probe server (client) security certificate from the CA and use it directly in SSLconfiguration. Or, you can create a client truststore/keystore that includes the CA security certificate.You use the keytool utility to create a truststore that includes the CA certificate or you can import theCA certificate into an existing truststore.

Performing SSL configuration on the OPC UA serverTo perform SSL configuration on the OPC UA server, use the following steps:

Note : For more details about configuring SSL security for the OPC UA server (including instructions aboutobtaining certificate files), refer to your vendor server's SSL configuration guide.

1. Either obtain the OPC UA server security certificate from the certificate authority (CA) or use a self-signed certificate.

2. Import the CA or self-signed certificate into the server truststore.3. If you have the appropriate user access, export the OPC UA server truststore into a certificate file on

the OPC UA server that can be handed to the client (probe). To export the OPC UA server keystore fileinto a certificate file on the OPC UA server, use the following command:

./keytool -export -alias alias_name -keystore keystore_file -storepass password -file certificate_file

Where:

alias_name - Specifies the keystore alias specified during OPC UA server keystore generation, forexample: OPCUA.

keystore_file - Specifies the path to and name of the OPC UA server keystore file, forexample: /opt/opcuaserver/opcua.keystore .

password - Specifies the OPC UA server keystore password, for example: the password ofopcua.keystore.

certificate_file - Specifies the path to and name of the certificate file to be created, forexample: /opt/opcuacert/opcuaprobecert.

Performing SSL configuration on the probe serverNote : You should now have an OPC UA server certificate file that resides on the OPC UA server. You willimport the OPC UA server certificate file as part of the SSL configuration on the probe server.

To perform SSL configuration on the probe server, use the following steps:

1. Import the OPC UA server certificate file either into an existing truststore or into a new truststore.

a. To import the OPC UA server certificate file into an existing truststore, you need to point an alias toa key entry as the certificate reply. The alias must be the same as that specified during OPC UAserver keystore file generation, for example:

./keytool -import -trustcacerts -alias alias_name -file certificate_file -keystore truststore_file -storepass password

b. To import the OPC UA server certificate file into a new truststore, make sure that the alias that youspecify does not already exist in your truststore, for example:

./keytool -import -trustcacerts -alias new_alias_name -file certificate_file -keystore truststore_file -storepass password

In the preceding examples (Step 1a and Step 1b):


alias_name - Is the keystore alias specified during OPC UA server keystore generation, forexample: OPCUA.

new_alias_name - Specifies the keystore alias of a new keystore, for example: opcuaprobe.

certificate_file - Specifies the path to and name of the certificate file created on the OPC UAserver, for example: /opt/opcuacert/opcuaprobecert.

truststore_file - Specifies the path to and name of the truststore file on the Tivoli Netcool/OMNIbus probe server that will contain the imported certificate, for example: /opt/tivoli/opcuaprobe.truststore .

password - Specifies the OPC UA server keystore password, for example: the password ofopcuaserver.truststore.

2. Verify that the certificate has been imported into the keystore using the following command:

./keytool -list -v -keystore truststore_file

Where:

truststore_file - Specifies the path to and name of the truststore file generated on the probeserver, for example: /opt/tivoli/opcuaprobe.truststore.

Configuring the probe for one-way SSL connectionTo configure the probe to connect to the OPC UA server using a one-way SSL connection, use thefollowing steps:

Note : A one-way SSL connection does not require client authentication. For a one-way SSL connection,you configure the EnableSSL property and the truststore related properties (TrustStore,TrustStorePassword, and TrustStoreType).

1. Set the probe's EnableSSL property to true and configure the probe's EndpointHttpPort propertyto your OPC UA server's HTTPS port. You can use any valid HTTPS port based on your OPC UA serverconfiguration.

2. Specify values for the following probe properties:

• TrustStore - Specify the path of the probe's keystore that you created in the steps for importingthe certificate, for example: /opt/opcua.trustStore.

• TrustStorePassword - Specify the password that you set for the specified keystore in theTrustStore property.

• TrustStoreType - Specify the truststore type obtained from the truststore. For example, JKS (JavaKeystore).

Note : TrustStoreType has a default value of JKS (which represents Java Keystore). If you areusing another type such as .pfx, then configure the TrustStoreType to the value PKCS12.

Configuring the probe for two-way SSL connectionTo configure the probe to connect to the OPC UA server using a two-way SSL connection, use thefollowing steps:

Note : A two-way SSL connection requires client authentication. This type of SSL connection is oftenreferred to as required client authentication. For a two-way SSL connection, you configure the EnableSSLproperty, the truststore related properties (TrustStore, TrustStorePassword, andTrustStoreType), and the keystore related properties (KeyStore, KeyStorePassword, andKeyStoreType).

1. Set the probe's EnableSSL property to true and configure the probe's EndpointHttpPort propertyto use the default OPC UA server HTTPS port, 51511.


Note : You can use any valid HTTPS port based on your OPC UA server configuration. For the OPCFoundation sample application (the sample server) the default HTTPS port is 51212.

2. Create a keystore on the Tivoli Netcool/OMNIbus probe server. Specify values appropriate to yourenvironment for the following properties:

• TrustStore - Specify the path of the probe's keystore that you created in the steps for importingthe certificate, for example: /opt/opcua.trustStore.

• TrustStoreType - Specify the truststore type obtained from the truststore. For example, JKS (JavaKeystore).

Note : TrustStoreType has a default value of JKS (which represents Java Keystore). If you areusing another type such as .pfx, then configure the TrustStoreType to the value PKCS12.

• TrustStorePassword - Specify the password that you set for the specified keystore in theTrustStore property.

• KeyStore - Specify the path of the probe's keystore that you created in the steps for importing theclient certificate if client authentication is required. For example, /opt/opcua.trustStore (if theclient certificate was imported there), or /opt/opcua.keyStore (if the client certificate is aseparate keystore).

• KeyStoreType - Specify the keystore type obtained from the keystore. For example, JKS (JavaKeystore).

Note : KeyStoreType has a default value of JKS. If you are using another type such as .pfx, thenconfigure the KeyStoreType to the value PKCS12.

• KeyStorePassword: Specify the password that you set for the specified keystore in the KeyStoreproperty.

Example one-way SSL configuration property settingsThe following example shows SSL configuration settings from the properties file of an example Probe forOPC UA for one-way SSL. Replace the sample values with those appropriate to your environment.

EndpointHttpHost : "localhost"EndpointHttpPort : 51511EnableSSL : "true"TrustStore : "/opt/opcua.trustStore"TrustStorePassword : "newpassword"

Example two-way SSL configuration property settingsThe following example shows SSL configuration settings from the properties file of an example Probe forOPC UA for two-way SSL. This example shows that the keystore property related values reuse the valuesspecified for the truststore related property values. Replace the sample values with those appropriate toyour environment.

EndpointHttpHost : "localhost"EndpointHttpPort : 51511EnableSSL : "true"TrustStore : "/opt/opcua.trustStore"TrustStorePassword : "newpassword"TrustStoreType : "JKS"KeyStore : "/opt/opcua.trustStore"KeyStore Password : "newpassword"KeyStore Type : "JKS"

The following example shows SSL configuration settings from the properties file of an example Probe forOPC UA for two-way SSL. This example shows that the keystore property related values (except for thetype) are different from the values specified for the truststore related property values. Replace thesample values with those appropriate to your environment.

EndpointHttpHost : "localhost"EndpointHttpPort : 51511


EnableSSL : "true"TrustStore : "/opt/opcua.trustStore"TrustStorePassword : "newpassword"TrustStoreType : "JKS"KeyStore : "/opt/opcua.keyStore"KeyStore Password : "keypassword"KeyStore Type : "JKS"

Notification retrieval and synchronizationThe probe identifies one or more items in the server address space that it wants to monitor. The OPCUnified Architecture (UA) server regularly polls each item. If there has been a suitable change in theitem's value or state, the OPC UA server generates a notification. The probe regularly retrieves thesenotifications.

The process of retrieving notifications from the OPC UA server has the following stages:

1. “Setting up a subscription” on page 142. “Defining the items to monitor” on page 153. “Performing the initial synchronization” on page 154. “Retrieving notifications” on page 15

Setting up a subscriptionWhen it has established a connection and session with the OPC UA server, the probe creates asubscription which is used to report notifications to the probe. Later in the process, the probe associates anumber of items to monitor with the subscription.

The probe uses the OPC UA service CreateSubscription to set up the subscription. The service has anumber of parameters that define the characteristics of the subscription. The probe maintains the valuesof some parameters as properties.

Table 8. Properties used in the CreateSubscription service

Property Usage

RequestedPublishingInterval The frequency (in milliseconds) that the OPC UAserver is to gather notifications from the monitoreditems and queue them ready for transmission tothe probe.

MaxNotificationPerPublish The maximum number of notifications that theprobe wants to receive in a single response fromthe OPC UA server.

RequestedLifetimeCount The maximum lifetime counter for the subscription.If this number of publishing intervals occurswithout the OPC UA server receiving a request fromthe probe to send outstanding notifications, theserver deletes the subscription.

Ensure that the value of this property is at leastthree times greater than the value ofRequestedMaxKeepAliveCount.


Table 8. Properties used in the CreateSubscription service (continued)

Property Usage

RequestedMaxKeepAliveCount The maximum keep-alive counter for thesubscription. If this number of publishing intervalsoccurs without there being any notifications toreturn to the probe, the OPC UA server sends akeep-alive message to ensure the subscriptionremains in use.

When the server publishing timer has expired thisnumber of times without requiring anyNotificationMessage to be sent, the Subscriptionsends a keep-alive Message to the probe. Thenegotiated value for this parameter is returned inthe response. If the requested value is 0 (zero), theserver revises the counter with the smallestsupported keep-alive count.

In response to the request to create a subscription, the OPC UA server returns an identifier for thesubscription. The probe retains this for use when telling the server which items to monitor and whenasking the EMS to return any outstanding notifications.

Defining the items to monitorWith the subscription in place, the probe can define the set of items that it wants the OPC UA server tomonitor. The probe uses the OPC UA CreateMonitoredItem service to create the set of monitored items onthe server. The service has a number of parameters, some of which the probe holds in an XML file. Thereis one probe property that defines the name and location of that file.

Table 9. Property used in the CreateMonitoredItem service

Property Usage

MonitoredItemsConfigFile The full path of a file that defines the items tomonitor and any notification filters. The use of afilter is optional.

Chapter 2, “The XML configuration files for eventand data change notifications,” on page 41 has adetailed description of the file, its structure, and itscontent.

Performing the initial synchronizationAfter defining the items to monitor, the probe immediately retrieves a list of all active notifications fromthe OPC UA server if the InitialResync property is set to true. When the InitialResync property isset to false, the probe does not receive the existing notifications.

Retrieving notificationsThe probe periodically requests the OPC UA server to return any outstanding notifications. The probe usesthe OPC UA Publish service to do this, and the frequency of publishing requests is determined by thevalue of the ResyncInterval property. In response to each request, the OPC UA server returns anynotifications that are waiting on its notification queue.


The probe parses each notification, converts it to an ObjectServer event, and sends that event to theObjectServer.

Under certain conditions, the OPC UA server may have more notifications to send than the probe canreadily handle. Use the MaxNotificationPerPublish property to limit the number of notifications theserver can send in response to each Publish request. This helps to ensure that the probe is not overloadedduring an event storm.

As stated previously, if the user enables the InitialResync property, the probe retrieves notificationsimmediately after the monitored items are created. Otherwise, if the user does not enable theInitialResync property, the probe waits until the time specified in the ResyncInterval propertyexpires to initiate the request for the notifications from the OPC UA server.

Acknowledging notificationsA Publish request can include acknowledgments of notifications the probe has received. TheAcknowledgeAlarm property controls whether the probe acknowledges notifications. If this property isset to 1, the probe acknowledges notifications. If this property is set to 0, the probe does notacknowledge alarms.

Reconnection and probe backoff strategyUse the RetryCount and RetryInterval properties to specify how the probe reacts if the connectionto the OPC Unified Architecture (UA) server is lost or cannot be established.

Use the RetryCount property to specify whether the probe attempts to reconnect to the server. Settingthe property to 0, the default value, means that the probe does not try to reconnect and simply shutsdown. Any other, positive value specifies the number of times the probe tries to reconnect before shuttingdown.

Use the RetryInterval property to specify the number of seconds between each attempt to reconnectto the server. Setting the property to 0 means that the probe uses an exponentially increasing intervalbetween connection attempts. First the probe waits 1 second, then 2 seconds, then 4 seconds, and so onup to a maximum of 4095 seconds. If this limit, or the number of connection attempts is reached, theprobe shuts down.

InactivityThe probe can disconnect from the OPC Unified Architecture (UA) server and shut down if there is noevent activity for a predefined amount of time.

You can use the Inactivity property to specify how long, in seconds, the probe waits beforedisconnecting from the OPC UA server and shutting down. If the probe receives no events during thattime, it disconnects from the server and shuts down. To ensure that the probe never disconnects from theserver, set the value of the property to 0, which is the default value.

Data stream captureThe probe can capture the stream of SOAP messages exchanged with the OPC Unified Architecture (UA)server and store it in a file. The data can be used for problem solving, debugging purposes, to developnew features for the probe, or to pass onto other management systems that require the same data.

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

1. Set the value of the StreamCapture property to 1.2. Set the value of the StreamCaptureFilePath property to the full path of a directory to hold the files

of data.

Notes :

• Specify the full path of the directory. For example:

/opt/tivoli/netcool/omnibus/var


• You cannot include variables such as $OMNIHOME in the directory path.• If the directory does not exist, or StreamCaptureFilePath does not have a value, the probe

stores the file in the directory that the probe was run from. That is, $NCHOME/omnibus/probes ona Linux or Unix system, or %NCHOME%\omnibus\probes\win32 on a Windows system.

3. If the probe is running, restart the probe.

The probe now writes data to a file in the specified directory. The name of that file has the followingformat:

probename_soapws-timestamp.data

Where:

probename is the name of the probe defined in the Name property.timestamp is the UTC time (expressed in milliseconds) when the file was created.

Example:

opc_ua_soapws-1402475122604.data

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

Support for Unicode and non-Unicode charactersThe probe can process multibyte characters such as Unicode UTF-8, GB, Big5, or Shift-JIS.

Use the following procedure to set up the probe to process multibyte characters:

1. Ensure that the OPC Unified Architecture (UA) server is configured to send data in the required format(for example, UTF-8).

2. Set the required locale on the system that runs the probe.

Table 10. Setting the locale for multibyte characters

Operating system Procedure to set the locale

Linux and Unix Set the locale by changing the values of the LANG and LC_ALL environmentvariables. For example, to set the locale to simplified Chinese in UTF-8, use thefollowing commands:

export LANG=zh_CN.UTF-8export LC_ALL=zh_CN.UTF-8

Windows a. Open the Control Panel and double click on Regional and Language.b. On the Formats tab, select the language from the list in Format.c. On the Administrative tab, click Change system locale.d. Select the language from the list in Current System Locale.e. Click OK.f. Click OK.

3. Configure the ObjectServer to enable the insertion of data that uses the required character set. TheIBM Tivoli Netcool/OMNIbus Administration Guide shows how to create, configure, and run anObjectServer in UTF-8 mode or using another character set.

4. Run the probe or, if it is already running, restart the probe.

When running the probe on a Windows system using a UTF-8 character set, always specify the -utf8enabled command line option. For all other character sets, do not use the -utf8enabledcommand line option.


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

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

Example property file settings for peer-to-peer failover

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

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

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

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

The following example shows the peer-to-peer settings from the properties file of the corresponding slaveprobe:

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

Using the OPC Foundation sample serverThe OPC Foundation provides sample implementations of OPC Unified Architecture (UA) applications,both servers and clients. You can use a sample OPC Foundation sample server application with the probefor evaluation and testing purposes.

To use a sample OPC UA server, configure the probe's properties as follows:

1. Set the values of the following properties as shown in “Connecting to the OPC UA server” on page 8:

EndpointHttpHostEndpointHttpPortEndpointSessionServiceNameOPCSessionNameRequestedSessionTimeoutMaxResponseMessageSize

The documentation for the OPC Foundation sample server may contain guidance on how to configurethese properties. For example, there may be information on the range of values thatRequestedSessionTimeout and MaxResponseMessageSize can have.

2. In addition, set the following properties to the shown values:


EndpointHttpService="SessionEndpoint"EndpointHttpTns="http://opcfoundation.org/UA/2008/02/Services.wsdl"

3. Download all of the WSDL and XSD sets that the OPC Foundation sample server application uses.

a. Download the Services.wsdl set and save it to a file name of your choice, for example,Services.wsdl:

http://localhost:10000/Quickstarts/DataAccessServer/None?wsdl

b. Download the Services0.wsdl set and save it to a file name of your choice, for example,Services0.wsdl:

http://localhost:10000/Quickstarts/DataAccessServer/None?wsdl=wsdl0

c. Download the Type.xsd set and save it to a file name of your choice, for example, Type.xsd:

http://localhost:10000/Quickstarts/DataAccessServer/None?xsd=xsd1

d. Download the Serialization.xsd set and save it to a file name of your choice, for example,Serialization.xsd:

http://localhost:10000/Quickstarts/DataAccessServer/None?xsd=xsd0

4. Save the files that contain the downloaded WSDL and XSD sets in a local directory. For example:

C:/temp

5. Modify the location and schemaLocation fields in the URLs associated with the files for theseWSDL and XSD sets.

Note : These URLs are located in the sets you downloaded and saved to files in step 3 (for example,Services.wsdl, Services0.wsdl, Type.xsd, and Serialization.xsd).

a. The following example shows the original values specified for the location andschemaLocation fields for one of these sets. The fields that need to be modified appear in thistypeface:

b. The following example shows the URLs after modifying the values for the location andschemaLocation fields. Replace these values with the file path that you specified. The fields thatwere modified appear in this typeface:

Do this for all of the sets that you downloaded.6. Configure the following properties to values associated with where the OPC Foundation sample server

is actually running. Replace the following values with values appropriate for your environment:


EndpointHttpHost: "localhost"EndpointHttpPort: 10000EndpointSessionServiceName: "Quickstarts/DataAccessServer/None"EndpointWsdlLocation : 'file:/C:/temp/Services.wsdl'

7. Start the probe and it connects to the sample server.

The documentation for the sample server shows how to create and send events to the probe.8. When you have finished testing or evaluating the probe, reconfigure it to communicate with the

product environment. In particular return the EndpointHttpService and EndpointHttpTnsproperties to their original values:

EndpointHttpService="UAService"EndpointHttpTns="http://opcfoundation.ord/UA/2008/02/Endpoints.wsdl"

Running the probeThe way in which you run the probe depends on whether you are running UNIX or Windows.

To start the probe, use the following command:

$NCHOME/omnibus/probes/nco_p_opc_ua

%NCHOME%\omnibus\probes\win32\nco_p_opc_ua.bat

Running multiple probesYou can run multiple, concurrent instances on a single host machine.

PreparationFor each instance of the probe that you want to run, do the following:

1. Create a uniquely-named copy of the probe's properties file, for example:

$NCHOME/omnibus/probes/arch/opc_ua_n.props

For each copy of the properties file, replace n with a unique number.2. Optionally, create a uniquely-named copy of the probe's rules file. Customize the copy as required.3. In the properties file for each instance, define a unique value for the following properties:

NameMessageLogPidFile

4. In the properties file for each instance, set the values of the PropsFile and RulesFile properties tothe names of the files you created in steps “1” on page 20 and “2” on page 20.

Running the probesTo run each instance of the probe, specify the -propsfile command line option to refer to theappropriate properties file, for example on UNIX:

Note : Use the full file path (and not the $NCHOME environment variable) after the -propsfile option onthe command line to specify the location of the properties files. Typically, the $NCHOME environmentvariable is defined as /opt/IBM/tivoli/netcool.$NCHOME/omnibus/probes/nco_p_opc_ua -propsfile /opt/IBM/tivoli/netcool/omnibus/probes/aix5/opc_ua_1.props

$NCHOME/omnibus/probes/nco_p_opc_ua -propsfile /opt/IBM/tivoli/netcool/omnibus/probes/aix5/opc_ua_2.props


Running the probe as a Windows serviceThe Windows version of the probe can run as a Windows service.

Registering and running the Windows serviceTo run a single instance of the probe as a Windows service:

1. Open a Command Prompt.2. Register the probe as a Windows service:

%OMNIHOME%\probes\win32\nco_p_opc_ua.bat /INSTALL /INSTANCE instance-name/CMDLINE "command-line-options"

Replace instance-name with a unique name for the service and command-line-options with anycommand line options that you want to use when running the probe. Always enclose the command lineoptions in quotes. If you do not want to use any command line options, exclude the /CMDLINE switch.

Note : If you exclude the /INSTANCE switch, the name of the service is NCONcoPOpcUaProbe.

Example:

%OMNIHOME%\probes\win32\nco_p_opc_ua.bat /INSTALL /INSTANCE OpcUaProbe1 /CMDLINE "-utf8enabled"

Note : Ensure that the %OMNIHOME% environment variable is defined as a system variable.

Note : If you define the %OMNIBUS_JVM_DLL% environment variable, the probe uses that dynamiclink library (DLL) for the windows service. Otherwise, by default, the probe uses the j9vm\jvm.dllthat comes with Tivoli Netcool/OMNIbus.

3. Run the service:

a. Open the Windows Control Panel and double click Administrative Tools.b. Double click Services.c. Click on the entry for the probe service and click Start.

Removing the serviceTo remove the service, if required:

1. Stop the service, if it is running:

a. Open the Windows Control Panel and double click Administrative Tools.b. Double click Services.c. Click on the entry for the probe service and click Stop.

2. Open a Command Prompt and enter the following command to remove the probe service from thesystem:

%OMNIHOME%\probes\win32\nco_p_opc_ua.bat /REMOVE /INSTANCE instance-name

Replace instance-name with the instance name you supplied when registering the probe as a service.

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

The following table describes the properties and command line options specific to this probe. Forinformation about properties and command line options common to all probes, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide. As supplied the location and name of the properties file is $NCHOME/omnibus/probes/arch/opc_ua.props.


Table 11. Properties and command line options

Property name Command line option Description

AcknowledgeAlarm string -ackalarm (This is equivalentto AcknowledgeAlarm with avalue of true.)

-noackalarm (This isequivalent toAcknowledgeAlarm with avalue of false.)

Use this property to specify whether theprobe should acknowledge alarms thathave been received. This property takesthe following values:

• false: The probe does notacknowledge alarms that have beenreceived.

• true: The probe acknowledges alarmsthat have been received.

The default is false.

ActivateSessionLocaleId string

-activatesessionlocaleidstring

Use this property to define the locale idin property order for localized stringsused in an ActivateSession request. Usethe ; (semicolon) delimeter to constructa list of locale ids.

The default is en-US.

DSLLogConfig string -dsllogconfig string Use this property to specify the name ofthe configuration file for the DSLframework; the framework carries outdetailed logging of the probe'scomponents. The location of theconfiguration file is $NCHOME/omnibus/probes/java or%OMNIHOME%\probes\win32.

The default is:opc_ua_dsl_log.properties

EnableSSL string -ssl (This is equivalent toEnableSSL with a value oftrue.)

-nossl (This is equivalent toEnableSSL with a value offalse.)

Use this property to specify whetherconnectivity between the probe and theOPC UA server is enabled. This propertytakes the following values:

• false: Disables SSL connectivitybetween the probe and the OPC UAserver.

• true: Enables SSL connectivitybetween the probe and the OPC UAserver.


EnableSSLDebug string -ssldebug (This is equivalentto EnableSSLDebug with avalue of true.)

-nossldebug (This isequivalent toEnableSSLDebug with avalue of false.)

Use this property to specify whether SSLdebug messages are enabled. Thisproperty takes the following values:

• false: Disables SSL debug messages.• true: Enables SSL debug messages.



Table 11. Properties and command line options (continued)


EndpointHttpHost string -httphost string Use this property to specify the HTTPhost name or IP address (IPv4 or IPv6)of the OPC UA server.

The default is: localhost.

EndpointHttpPort integer -httpport integer Use this property to specify the port onthe HTTP server to use for alarmretrieval.

The default is: 51511.

EndpointHttpServicestring

-httpservice string Use this property to specify the name ofthe OPC UA service name that the probeuses to communicate with the OPC UAserver. The property takes the followingvalues:

UAService: Use this value whenconnecting to a server that uses thestandard WSDL supplied by the OPCFoundation.

SessionEndpoint: Use this valuewhen connecting to one of the sampleservers that the OPC Foundationsupplies.

The default is: UAService.

EndpointHttpTns string -httptns string Use this property to specify the URI ofthe WSDL file that the probe uses whencommunicating with the OPC UA server.The property takes the following values:

http://opcfoundation.org/UA/2008/02/Endpoints.wsdl: Use thisvalue when connecting to a name spacethat uses the standard WSDL suppliedby the OPC Foundation.

http://opcfoundation.org/UA/2008/02/Services.wsdl: Use thisvalue when connecting to one of thesample servers that the OPC Foundationsupplies.

The default is: http://opcfoundation.org/UA2008/02/Endpoints.wsdl

EndpointSessionServiceName string

-endpointsessionservicename string

Use this property to specify the name ofthe session on the OPC UA server to usefor alarm retrieval.

The default is: UAEndpoints




EndpointWsdlLocationstring

-wsdllocation string Use this property to specify the locationof the WSDL file that the probe uses toconnect to the OPC UA server. Thisproperty can contain the path of a localWSDL file or the URL of a publishedWSDL file.

The default is: "".

The following is an example of a URL tospecify the location of a local WSDL file:

EndpointWsdlLocation:"file:/C:/wsdl/Opc.Ua.SessionEndpoint"

The following is an example of a URL tospecify the location of a publishedWSDL file:

EndpointWsdlLocation:"http://opcfoundation.org/UA/2008/02/Endpoints?wsdl"

Inactivity integer -inactivity integer Use this property to specify the lengthof time (in seconds) that can passwithout the probe receiving events. Ifthis time expires, the probe disconnectsfrom the target system and shuts down.A value of 0 means that the probe nevershuts down.

The default is: 0.

InitialResync string -initialresync string Use this property to specify whether theprobe resynchronizes with the targetsystem after you define the items tomonitor. The property takes thefollowing values:

true: After you define the items tomonitor, the probe resynchronizes withthe target system.

false: The probe does notresynchronize with the target system.

The default is true.

KeyStore string -keystore string Use this property to specify the filename (with full path) of the keystore filethat contains the client certificate forSSL, if client authentication is required.

The default is: "".




KeyStorePassword string

-keystorepassword string Use this property to specify thepassword required to access thecertificate specified by the KeyStoreproperty.

The default is: "".

KeyStoreType string -keystoretype string Use this property to specify the keystoretype obtained from the keystore, forexample: JKS, PKCS12, and so forth.

The default is: JKS.

MaxNotificationPerPublish integer

-maxnotificationperpublish

integer

Use this property to specify themaximum number of notifications thatthe OPC UA server can return inresponse to a single Publish request.The value of this property is used as aparameter for the OPC UACreateSubscription service.

The default is: 500 notifications.

MaxResponseMessageSizeinteger

-maxresponsemessagesizeinteger

Use this property to specify themaximum size (in bytes) of the body inany SOAP message the OPC UA serversends to the probe. The value of thisproperty is used as a parameter for theOPC UA CreateSession service.


MonitoredItemsConfigFile string

-monitoreditemsconfigfile

string

Use this property to specify the full pathof the XML file that contains informationon the items that the probe is tomonitor. The information in this file isused in the OPC UACreateMonitoredItems service.

The default value is: $OMNIHOME/var/OpcUaEvent.xml.

Note : You need to manually configurethis property to the actual path withoutusing the $OMNIHOME or $NCHOMEenvironment variables.

OPCSessionName string -opcsessionname string Use this property to specify the sessionname to use when connecting to theOPC UA server. The value of thisproperty is used as a parameter for theOPC UA CreateSubscription service.

The default is: OPC client.




PidFile string -pidfile string Use this property to define the file thatcontains the process ID for the device.

RequestedLifetimeCountinteger

-lifetimecount integer Use this property to specify themaximum number of times thepublishing interval can occur withoutthe server receiving a Publish requestfrom the probe before the serverdeletes the subscription. The value ofthis property is used as a parameter forthe OPC UA CreateSubscription service.

Ensure that the value of this property isthree times the value of theRequestedMaxKeepAliveCountparameter.


RequestedMaxKeepAliveCount integer

-maxkeepalivecountinteger

When the publishing interval hasoccurred a set number of times andthere are no notifications to publish, theOPC UA server sends a keep-alivemessage to the probe. Use this propertyto specify the number of times thepublishing interval can occur beforesending a keep-alive message. Thevalue of this property is used as aparameter for the OPC UACreateSubscription service.


RequestedPublishingInterval integer

-publishinginterval integer For each subscription, the OPC UAserver periodically samples themonitored items and generatesnotifications if necessary. Use thisproperty to define that sample interval(in milliseconds). The value of thisproperty is used as a parameter for theOPC UA CreateSubscription service.


RequestedSessionTimeout integer

-sessiontimeout integer Use this property to specify how long (inmilliseconds) the OPC UA sessionshould remain open when there is noactivity. The value of this property isused as a parameter for the OPC UACreateSession service.





RequestHeaderRequestHandle integer

-requesthandle integer Use this property to specify the numberto use as the request handle in theheader of all OPC UA request messages.

The default is: 1001

RequestHeaderReturnDiagnostics integer

-returndiagnosticsinteger

Use this property to specify the vendor-specific diagnostics that the server is toreturn in the response header. The valuerepresents a bit mask of 32 bits. Referto the vendor documentation for thevalues this property can take.

The default is: 64.

RequestHeaderTimeoutHint integer

-timeouthint integer Use this property to specify the timeoutperiod (in milliseconds) for all HTTPrequests sent to the OPC UA server. Avalue of 0 indicates that there is notimeout in force. The value of thisproperty is used for the timeoutHintparameter of the Request Header in allSOAP service requests.

The default is: 0.

ResyncInterval integer -resyncinterval integer Use this property to specify the time (inseconds) between eachresynchronization operation. A value of0 means that the probe neverresynchronizes with the target system.

The default is: 60.

RetryCount integer -retrycount integer Use this property to specify themaximum number of times the probetries to reconnect to the target systemfollowing a communications failure. Ifreconnection does not occur after thisnumber of attempts, the probe shutsdown. A value of 0 means that the probedoes not try to reconnect to the targetbut simply shuts down.

The default is: 0.




RetryInterval integer -retryinterval integer Use the property to specify the time (inseconds) between each attempt toreconnect to the target system.

A value of 0 means that the probe usesan exponentially increasing periodbetween successive connectionattempts. For example, the probe waits1 second, then 2 seconds, then 4seconds, and so on.

The default is: 0.

StreamCapture integer -streamcapture (This isequivalent toStreamCapture with a valueof true (1).)

-nostreamcapture (This isequivalent toStreamCapture with a valueof false (0).)

Use this property to specify whether thestream capture feature is enabled. Theproperty takes the following values:

1: The probe uses the stream capturefeature.

0: The probe does not use the streamcapture feature.

The default is: 0.

Note : If you set the value of thisproperty to 1, define a value for theStreamCaptureFilePath property aswell.

StreamCaptureFilePathstring

-streamcapturefilepathstring

Use this property to specify thedirectory where the probe stores theinput data stream.

The default is: "".

See “Data stream capture” on page 16for more information on how to use thisproperty.

TrustStore string -truststore string Use this property to specify the filename (with full path) of the truststorefile that contains the trustedcertificates.

The default is: "".

TrustStorePassword string

-truststorepasswordstring

Use this property to specify thepassword required to access thetruststore file containing the trustedcertificates.

The default is: "".




TrustStoreType string -truststoretype string Use this property to specify thetruststore type obtained from thetruststore, for example: JKS, PKCS12,and so forth.

The default is: JKS.

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

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

Table 12. Elements

Element name Element description

$ClientHandle This element contains the user-supplied identifier for amonitored item. “” on page 43describes the client handle and its use.

$EventId This element contains the identifier of the event which isthe subject of an event notification.

$EventType This element identifies the type of event which is thesubject of an event notification.

$InnerStatusCode This element contains the status code returned from theunderlying system used to complete the execution of anOPC UA service.

$MessageText This element contains the message text associated withan event notification.

$NodeId This element identifies the node in the server namespacewhere a data change has occurred.

$OpcUaEventType This element identifies the type of OPC UA event that hasoccurred. This element can have the following values:

DataChangeNotificationEventNotificationListStatusChangeNotification

$Severity This element contains the severity code associated withan event notification. The code is a number between 1and 1000. The higher the number the more severe theevent.


Table 12. Elements (continued)

Element name Element description

$SourceName This element contains the name of the node in the servernamespace that generated an event notification.

$SourceNode This element contains the identifier of the node in theserver namespace that generated an event notification.

$SourceTimestamp This element contains the Coordinated Universal Time(UTC) that identifies when a change in a data valueoccurred at the source. The time is expressed as thenumber of 100 nanosecond intervals since 1 January1601.

$StatusCode This element contains the new status code that triggeredthe occurrence of a status change notification.

$Time This element contains the time when an eventnotification occurred.

$Value This element contains the value of the data element thatis the subject of a data change notification.

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

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

Table 13. Error messages

Error Description Action

Exception duringmarshallingnotification message toelement: cause

An exception occurred while theprobe was parsing incomingevents. The cause contains amessage associated with theexception.

Contact IBM Support.

Run the probe in debug and streamcapture mode to collect the probedebug log and stream capture logand submit the logs to IBMsupport.

Exception in creatingEventNotification Listevent: cause

An exception occurred while theprobe was creating anObjectServer event in response toreceiving an event notificationfrom the OPC UA server. Thecause contains a messageassociated with the exception.




Table 13. Error messages (continued)


Exception in parsingnotification event:cause

An exception occurred while theprobe was parsing data in anevent notification received fromthe OPC UA server. The causecontains a message associatedwith the exception.



Exception in creatingDataChange Notificationevent: cause

An exception occurred while theprobe was creating anObjectServer event in response toreceiving a data changenotification from the OPC UAserver. The cause contains amessage associated with theexception.



Exception in parsingDataChange event: cause

An exception occurred while theprobe was parsing data in a datachange notification received fromthe OPC UA server. The causecontains a message associatedwith the exception.



Exception in creatingStateChangeNotification event:cause

An exception occurred while theprobe was creating anObjectServer event in response toreceiving notification of a statechange in a monitored item. Thecause contains a messageassociated with the exception.



Exception in parsingStateChange event:cause

An exception occurred while theprobe was parsing data in a statechange notification received fromthe OPC UA server. The causecontains a message associatedwith the exception.



Unknown event type:type with id:identifier

The probe received a notificationfrom the OPC UA server that is notone of the types that the proberecognizes. That is, thenotification does not indicate adata change, event notification, ora status change. The type showsthe type of the notification andidentifier is its identifier.

Currently, the probe only supportsa few event types identified in theOPC UA standard. If the probereceives an unknown event type,contact IBM support. It could bethat either the probe is unable torecognize the event type or theevent type is not supported.




ServiceException duringsetting up propertiesfor endpoint...

A ServiceException has occurredwhile the probe was reading theproperties required to set upcommunication with the OPC UAserver.


Unable to connect asclient to endpoint:cause

An exception occurred during theprocess of connecting to the OPCUA server, creating a session andactivating that session. The causecontains a message associatedwith the exception.

Make sure that the OPC UA serveris up and running and check theconnection related properties suchas host, port, and service name.Ensure that there is no firewallissue blocking the connection. Ifthe problem continues, contactIBM support.

Timeout while waitingresponse from OPC-UA,wait for next resynccycle.

When the probe issues a Publishrequest to the OPC UA server, itexpects a response within a settime period. This warningindicates that there was noresponse. This can occur for anyof the following reasons:

• There are no notifications onthe server to send to the probe.

In this case, the server queuesthe publish request and sendsnotifications when any areavailable. In addition the probetries again at the nextpublishing interval.

• There is an error in theconnection between the probeand the server.

• The server is incorrectlyconfigured.

The probe will retry again in thenext resynchronize cycle.

MalformedURL Exceptionduring create URL forWSDL location: cause

The URL of the WSDL file for theSOAP session is incorrectlyformatted. The cause containsmore information on the nature ofthe error. Either the value of theEndpointWsdlLocationproperty is incorrect or, if thatproperty has no value, one ormore of the following propertieshave incorrect values:

EndpointHttpHostEndpointHttpPortEndpointSessionServiceName

Check that the value of each of theproperties has the correct syntax,and that the values are correct foryour site. Correct any errors andrestart the probe.




Unable to createsession.

The probe was unable to createthe session with the OPC UAserver through the OPC UACreateSession service.

The values of one or more of thefollowing properties are incorrector invalid:

HttpTimeout

MaxResponseMessageSize

OPCSessionName

RequestedSession Timeout

Ensure that all these propertieshave values that are valid for yoursite and then restart the probe.

Unable to activatesession identifiers:sessionid

The probe was unable to activatethe OPC UA session. Thesessionid contains the identifier ofthe session.

It is a very rare case that the OPCUA server returns a session ID thatthe probe cannot activate. It couldbe one of the following hasoccurred:

• The activate session has expired.• The OPC UA server has removed

the activate session.• The OPC UA server is no lon

Documents

Version 1.0 Netcool/OMNIbus Probe for OPC UnifiedTable 3. Summary Probe target Network devices and EMS that implement the OPC UA 1.0.2 specification. Probe executable name The way