Programmer's Guide for Cisco Prime Central for Hosted Collaboration Solution, 1.0.1
Chapter 4: Event Management NBI
Downloads: This chapterpdf (PDF - 128.0KB) The complete bookPDF (PDF - 1.18MB) | Feedback

Event Management NBI

Table Of Contents

Event Management NBI

Executing Client Script

Subscribing

Unsubscribing

Recovering Subscription Tokens

Recovering Active Subscription and Nonactive Gateway

Recovering from Inconsistent Oracle DB State

Recovering from Duplicate Customer Tokens

MIB Definition for NBI SNMP Notification


Event Management NBI


The enhanced Event Management Northbound Interface (NBI) supports multiple SNMP gateway subscriptions. The maximum subscriptions allowed at one time is five. The gateway subscriptions support the ability to filter the incoming traps. A Python client script supports subscribe and unsubscribe calls into the Event Management NBI. In addition, MIB definition for SNMP notifications generated by the NBI is also supported.

This chapter contains the following sections:

Executing Client Script

MIB Definition for NBI SNMP Notification

Executing Client Script

Once you run the patch script, the client scripts are installed on Prime Central VM.

The scripts are located at the following location in the Prime Central VM: <install_dir>/prime-hcs/scripts/pc4hcs_nbi_client.py.

This section explains the various arguments and scenarios involved in subscribing and unsubscribing to traps. This section contains the following topics:

Subscribing

Unsubscribing

Recovering Subscription Tokens

Recovering Active Subscription and Nonactive Gateway

Recovering from Inconsistent Oracle DB State

Recovering from Duplicate Customer Tokens

Subscribing

To subscribe, the following arguments are required:

subscribe—Specifies that this is a subscribe command

prime-ip—IP or hostname of the Prime Central VM

prime-admin-password—Prime password used at the timeof installation of Prime VM

snmp-gateway-ip—IP or hostname to which traps should be sent

snmp-gateway-port—Port to which traps should be sent

where-clause—whereclause to set the filter on; this is optional


Step 1 Log in as root user.

Step 2 Run the following command:

./pc4hcs_nbi_client.py [--subscribe | --unsubscribe]
                       --prime-ip 
                       --prime-password
                       --where-clause
                       --snmp-gateway-port
                       --snmp-gateway-ip
 
   
The request returns the customer-token.

Here is an example of subscribe request:

[root@hcslab-mike pc4hcs_nbi_client]# ./pc4hcs_nbi_client.py --subscribe --prime-ip 
10.10.10.10 --prime-password Admin123@ --snmp-gateway-port 162 --snmp-gateway-ip 
20.20.20.20 --where-clause "Customer = 'ABC'"

The following value is returned:

Customer_9 

Note Retain the customer value to unsubscribe to gateway at a later time.


Using Where Clause for Subscribe Request

Using the where clause argument is optional; however, if you do not use the where clause, all the traps, without any filtering done, will be forwarded through the gateway. If you do specify the where clause, only traps that match the where clause criteria will be sent for the subscription. The argument snmp-gateway-ip specifies the destination IP to which traps will be sent.

Unsubscribing

To unsubscribe, the following arguments are required:

unsubscribe—Specifies that this is an unsubscribe command

prime-ip—IP or hostname of the Prime Central server

prime-admin-password—Prime admin password used at the time of installation of Prime Central VM

customer-token—The customer token that was returned when you subscribed to receiving traps. If you do not have the customer-token, follow the steps outlined in the section Recovering Subscription Tokens


Step 1 Log in as root user.

Step 2 Run the following command:

./pc4hcs_nbi_client.py [--subscribe | --unsubscribe]
                      	 --prime-ip 
                       	--prime-password
				 		 --customer-token
 
   

The following message is returned:

Un-Subscribe request successful.
 
   

Here is an example of unsubscribe request:

[root@hcslab-mike pc4hcs_nbi_client]# ./pc4hcs_nbi_client.py --unsubscribe --prime-ip 
172.16.10.126 --prime-password Admin123@ --customer-token Customer_9

The following message is returned:

Un-Subscribe request successful.

Recovering Subscription Tokens

When you subscibe to receiving traps and execute a subscibe request, a subscription token is returned. This token must be retained to unsubscribe at a later time. If you do not have the subscription token, follow these steps to recover the token:

1. To recover the token, you need to be logged into a VM that has Prime Central installed.

2. You must either log in as Oracle user or su to Oracle, and then log onto the primedb database.

3. Specify the --prime-admin-password you specified at the time of installation.


Step 1 Log on to the primedb database.

Step 2 Run the following command:

su - oracle -c '$ORACLE_HOME/bin/sqlplus primedba/\"<prime-admin-password>\"@primedb' 

The query command returns the ID, destination, status, and customer token. Match the customer token with the destination you wish to unsubscribe.

The following fields indicate the status of the gateway:

1—The gateway is up

0—The gateway is down


Here is an example of recovery command:

[root@hcslab-mike pc4hcs_nbi_client]# su - oracle -c '$ORACLE_HOME/bin/sqlplus 
primedba/\"Admin123@\"@primedb'

The following values are returned:

SQL> select * from SNMPGATEWAYS;

ID DESTINATION STATUS CUSTOMERTOKEN

---------- ------------------------------ ---------- -----------------------------------------------

1 172.16.10.217:163 1 Customer_57

2 0

3 0

4 0

5 0

Recovering Active Subscription and Nonactive Gateway

Follow the steps explained below to recover active subscription and nonactive gateway:


Step 1 On PrimeCentral, log on to the Oracle database.

Step 2 Issue this command for updating the DB:

update SNMPGATEWAYS set DESTINATION=null,  STATUS=0,  CUSTOMERTOKEN=null where 
ID=active-subscription-ID;

Step 3 On Event Collector, remove the following files:

If the desination ID is 1, use

        rm -rf $OMNIHOME/etc/NCO_GATE.trapdest 
        rm -rf $OMNIHOME/var/NCO_GATE.pid
 
   

If the desination ID is a value other than 1, use

        rm -rf $OMNIHOME/etc/NCO_GATE_trap-destination-ID.trapdest 
        rm -rf $OMNIHOME/var/NCO_GATE_trap-destination-ID.pid
 
   

Step 4 Issue the kill command if the gateway is still up:

        ps -ef | grep snmp
        kill -9 <pid of gateway to be brought down>

Tip Identify the pid from the gateway line, when you issued the command ps -ef | grep snmp:


For example, identify the pid from the following:

netcool 30445 30443 0 12:49 ? 00:00:00 /opt/IBM/tivoli/netcool/omnibus/bin/linux2x86/nco_g_snmp -name NCO_GATE -snmpgateway sadev-rod:166

Do not terminate this; it does not stop the gateway:

netcool 30443 25808 0 12:49 ? 00:00:00 /bin/bash /opt/IBM/tivoli/netcool/omnibus/bin/hcs_snmp_gateway_start 1

 
   
       

Recovering from Inconsistent Oracle DB State

Sometimes, when you issue a subsciption or unsubscription request, your machine hangs and times out. In such a scenario, verify whether it is in an inconsistent state:


Step 1 Open the log /opt/<install_dir>/apache-servicemix-4.4.1-fuse-00-08/data/log/servicemix.log. Look for the following arguments:

OALL8 is in an inconsistent state; Nested exception is java.sql.SQLException: OALL8 is in 
an inconsistent state.
 
   

Step 2 Reboot the oracle database:

su - primeusr -c 'emdbctl stop; emdbctl start'

Recovering from Duplicate Customer Tokens

When you subscibe to receiving traps, and execute a subscibe request, a subscription token is returned. This token must be retained to unsubscribe at a later time. If you need to recover from duplicate customer tokens, follow this procedure:

1. To recover the token, you must be logged in to a VM that has Prime Central installed.

2. You must either log in as Oracle user or su to Oracle, and then log on to the primedb database.

3. Specify the --prime-admin-password you specified at the time of installation.


Step 1 Log on to the Oracle database.

Step 2 Run the following command to update the database:

update SNMPGATEWAYS set DESTINATION=null,  STATUS=0,  CUSTOMERTOKEN=null where ID=#;

In the argument where ID=#, # is the active subscription ID that you want to remove from the DB.

Step 3 On Event Collector, remove the following files:

If the ID you want to remove is 1, use

rm -rf $OMNIHOME/etc/NCO_GATE.trapdest

If the ID you want to remove is a value other than 1, use

rm -rf $OMNIHOME/etc/NCO_GATE_#.trapdest

Step 4 Issue the kill command if the gateway is still up:

ps -ef | grep snmp

kill -9 <pid of gateway to be brought down>


Tip Identify the pid from the gateway line, when you issued the command ps -ef | grep snmp:


For example, identify the pid from the following:

netcool 30445 30443 0 12:49 ? 00:00:00 /opt/IBM/tivoli/netcool/omnibus/bin/linux2x86/nco_g_snmp -name NCO_GATE -snmpgateway sadev-rod:166

Do not terminate this; it does not stop the gateway:

netcool 30443 25808 0 12:49 ? 00:00:00 /bin/bash /opt/IBM/tivoli/netcool/omnibus/bin/hcs_snmp_gateway_start 1


MIB Definition for NBI SNMP Notification

After you run the patch script, the MIB file is installed on Prime Central VM. The MIB defines an SNMP v2 notification that is aligned with the SNMP v2 notifications generated by Prime Central for HCS.

The MIB file is located at the following location in the Prime Central VM: <prime-install-directory>/prime-hcs/sdk/CISCO-HCS-SA-NBI-MIB.my.

Northbound clients that intend to process the SNMP notifications from Prime Central for HCS can use the MIB defintion to implement this feature.

For more information, see the documentation that ships with the product used to process the received SNMP notifications.