Cisco Prime Central for Hosted Collaboration Solution 9.2.1 Programmer Guide
Chapter 4: Event Management NBI
Downloads: This chapterpdf (PDF - 219.0KB) The complete bookPDF (PDF - 923.0KB) | 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

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

MIB Definition for NBI SNMP Notification

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 time of 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 is an example of the returned subscription token:

Customer_9 

Note Retain the subscription token value to unsubscribe 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, 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 subscription token that was returned when you subscribed to receiving traps. If you do not have the subscription-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 subscribe to receive traps by executing a subscribe 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 log into Oracle as either oracle user or switch user (su), and then query the primedb database.

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


Step 1 Log on to the Prime Central VM.

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 values 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 From Prime Central VM, log on to the Oracle database.

Step 2 Enter this command for updating the DB:

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

Step 3 Login in as a root user on a Event Collector VM and remove the following files:

If the destination ID is 1, use

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

If the destination 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

Note Before deleting the NCO_GATE_trap-destination-ID.pid, use the cat command to determine the PID of the process you want to kill and verify the details returned from the command in Step 4.


 
   

Step 4 Enter 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 enter the command ps -ef | grep snmp:


An example with PID 30443 is listed below:

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 process; 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 enter a subscription or unsubscription request, your machine hangs and times out. In such a scenario, determine if the Oracle database is in an inconsistent state:


Step 1 Open the log /opt/prime/esb/data/log/servicemix.log. Look for the following lines:

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

Step 2 If the Oracle database is in an inconsistent state reboot it using the following command:

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

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 definition to implement this feature.

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