Dev-Jam:QosDocumentation
Subscribe

From OpenNMS

Jump to: navigation, search

Contents

Experimental OSS/J interface Documentation

Back to Dev Jam Qos Update Project

Overview

This page provides updated basic documentation to allow a user to get an experimental OSS/J Qos interface working between two OpenNMS instances.

Experimental work was contributed a few years ago to demonstrate how an OSS/J (www.ossj.com) interface could be supported on OpenNMS. This is packaged in the opennms-qosdaemon project which can be optionally enabled in a standard OpenNMS installation. The interface is in two parts, qosd which issues new events to a JMS topic if the alarm list changes and qosdrx which listens to a topic and modifies the alarm list as events are changed. Depending on its configuration, OpenNMS can run one or both of these processes simultaneously.

The interface leaverages the OpenNMS Alarms list and vacuumd daemon to demonstrate the following functionality;

  • 1. Uses a JMS message bus (using JbossMQ) to transfer alarm details between OpenNMS instances using the OSS/J XML systax.
  • 2. Allows one OpenNMS to share changes in it's alarm list with another OpenNMS which is listening on a topic for changes.
  • 3. Provides simple demo clients to listen to the JMS topics and monitor the messages which OpenNMS produces as it's alarm list changes.

As of July 2008 DevJam this package has been updated to make configuration simpler. The original documentation is packaged with the interface in the following opennms directory:

  • /opt/opennms/contrib/qosdaemon/doc/qosddocumentation;1.4.pdf.

This documentation remains substantially correct but some of the configuration instructions have changed and the revised installation instructions are covered in this page.

Basic Setup 

   __________                  __________
  | OpenOSS  |                | OpenOSS1 |
  |__________|                |__________|   
  | OpenNMS  |                | OpenNMS  |
  |__________|                |__________|  
  | JbossMQ  |
  |__________|

Two linux instances are used to host the OpenNMS instances (Here named OpenOSS and OpenOSS1). These can be hosted on VMware virtual machines or on real hardware. This configuration has been tested on Fedora Core 6 and Centos 5.1. The following steps should be performed on both machines;

1. Download Jboss-4.0.2.zip from Jboss and unpack the contents into /opt/jboss. (Alternatively unpack into /opt/Jboss-4.0.2 and simlink from /opt/jboss using sudo ln -s /opt/jboss-4.0.2/ /opt/jboss ). Although JbossMQ will only be run on one of the machines, the installation script expects Jboss to be present in /opt/jboss on both machines as it copies Jboss client libraries from this location into the /opennms/lib folder.

2. Add an entry to the hosts file of both machines to create a DNS entry jbossjmsserver1 and have this point at the IP address of the machine designated openoss1. This will be used to run JbossMQ. (Note that JbossMQ could run on seperate third machine provided jbossjmsserver1 is set to resolve to it's address on both OpenNMS instances). Tip: use the Start>Administration>Network configuration tool to set the hosts entry on Centos / Fedora

3. OpenNMS should be installed as normal on both machines in /opt/opennms. This can be done from source following Building OpenNMS instructions or using the RPM installer following Yum RPM installation instructions. Note that for this demonstration in is important to use the /opt/opennms/bin/install -disc option to install OpenNMS with a clean empty database.

4. Having installed jboss and OpenNMS, run the following script as root user on both machines to copy the example configuration files from /opt/opennms/contrib/qosdaemon/qos_example_configuration into the correct working directories on OpenNMS and Jboss; 

cd /opt/opennms/contrib/qosdaemon/qos_example_configuration/
sudo sh opennms_REVISED_deploy.sh

The original configuration files which are modified in /opennms/etc will be preserved with a _back.xml extension.

Having loaded the same basic configuration on both machines, we now need to modify the configuration on OpenOSS1 to differentiate it from OpenOSS and datafill both databases with test nodes. We shall begin by datafilling and testing OpenOSS.

Testing OpenOSS configuration with JBOSS

5. Open an new terminal on OpenOSS to start the Jboss application server. The opennms_REVISED_deploy.sh script should have copied the configuration files into the correct Jboss directories. 

cd /opt/jboss/bin
sudo sh openoss_qos_jboss_start.sh

The terminal should log events as jboss starts up finishing with a line like 

20:32:29,331 INFO  [Server] JBoss (MX MicroKernel) [4.0.2 (build: CVSTag=JBoss_4_0_2 date=200505022023)] Started in 28s:763ms

Leave the terminal open to keep Jboss running. Note if Tomcat is running or a standard OpenNMS configuration is running, Jboss will complain that ports on this machine are in contention and will not start. You should make sure that you are using OpenNMS with it's internal jetty server and that you have installed the correct configuration in step 4 before running Jboss. Alternatively run jboss on a third machine with the configuration files installed as described in the opennms_REVISED_deploy.sh script.

6. Open a terminal on OpenOSS and run the simple OSS/J client program to connect to JbossMQ and listen for events 

cd /opt/opennms/contrib/qosdaemon/testscripts
sudo sh opennms_IF.sh -xreceive1

This should result in a log output ending with the lines 

Trying to connect to message queues
Topic Connection Factory:System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/TopicConnectionFactory
Event Topic    :System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/JVTEventTopic
XVT Event Topic:System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/XVTEventTopic
XML Message Queue:System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/MessageQueue
Session Initialised
Subscribing to OSS/J XVT jms session:
Subscribed - Waiting for events ;
Waiting: Event Counts:- ListRebuilt:0   NewAlrmEvt:0    ClrAlrmEvt:0    AlrmCngEvt:0    AckChngEvt:0    CommentEvt:0    UnknownIRPEvt:0     UnknownObjMsg:0 NonObjMsg:0     ObjMsg:0        TxtMsg:0
***Waiting for OSS/J XVT XML JMS text message event***

Leave this terminal open to see OSS/J events comming from the qosd process on OpenOSS

7. Start OpenNMS on OpenOSS and watch for qosd and qosdrx starting correctly 

cd /opt/opennms/bin
sudo sh opennms -v start
....
OpenNMS.Importer       : running
OpenNMS.JettyServer    : running
OpenNMS.QoSD           : running
OpenNMS.QoSDrx         : running
      [  OK  ]

Look at the OSS/J client started previously in step 6. You should see a listRebuilt event once OpenNMS has started. 

...
<notifyAlarmListRebuiltEvent xmlns="http://java.sun.com/products/oss/xml/QualityOfService/FM/Monitor" xmlns:com="http://java.sun.com/products/oss/xml/Common" xmlns:util="http://java.sun.com/products/oss/xml/Common/Util">
  <event>
  <com:applicationDN>System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/XVTEventTopic</com:applicationDN>
    <com:eventTime>2008-08-06T20:58:26.364+01:00</com:eventTime>
    <util:managedObjectClass>NOT_SET_ManagedObjectClass</util:managedObjectClass>
    <util:managedObjectInstance>NOT_SET_ManagedObjectInstance</util:managedObjectInstance>
    <util:notificationId>AlmMonitorId:null:EventCount:1</util:notificationId>
    <reason>openNMS just restarted - alarm list rebuilt. Time:Wed Aug 06 20:58:26 BST 2008</reason>
  </event>
</notifyAlarmListRebuiltEvent>
Recieved NotifyAlarmListRebuiltEvent. Reason: openNMS just restarted - alarm list rebuilt. Time:Wed Aug 06 20:58:26 BST 2008
Waiting: Event Counts:- ListRebuilt:1   NewAlrmEvt:0    ClrAlrmEvt:0 AlrmCngEvt:0    AckChngEvt:0    CommentEvt:0   UnknownIRPEvt:0 UnknownObjMsg:0 NonObjMsg:0     ObjMsg:0   TxtMsg:0
***Waiting for OSS/J XVT XML JMS text message event***

Browse to http://localhost:8980/opennms/ and log in using user:admin password:admin to check OpenNMS is working correctly

8. We need to datafill opennms with the nodes used in the demonstration. We use the importer daemon to do this. The importer has already been set up by the configuration however we must send an import event to OpenNMS to force it to import the configuration. ( For more information on the importer see Importer Service ) 

cd /opt/opennms/bin
./send-event.pl  uei.opennms.org/internal/importer/reloadImport

Browse to the Host List tab on the opennms consol and check that the following nodes have been loaded; 

localhost 
openoss1 
openoss2 
openoss3 
Outstation_OpenOSS1

9. Open a new terminal to send test alarm traps into opennms to add alarms to the alarm list and watch the XML alarm event messages on the OSS/J client screen. 

cd /opt/opennms5.9.1/contrib/qosdaemon/qos_example_configuration/testtraps
sudo sh multipleossjtesttraps_raise.sh

Note to make the trap injector trapgen work you may need to install perl-Getopt-Mixed and also change the permssions on trapgen 

sudo yum install perl-Getopt-Mixed
sudo chmod 777 trapgen

Browse to the OpenNMS Alarms page and select 'All Alarms'. (http://localhost:8980/opennms/alarm/list). You should see 3 red alarms. You should also see 3 xml new alarm events in the OSS/J client 

<notifyNewAlarmEvent xmlns="http://java.sun.com/products/oss/xml/QualityOfService/FM/Monitor" xmlns:com="http://java.sun.com/products/oss/xml/Common" xmlns:util="http://java.sun.com/products/oss/xml/Common/Util">
  <event>
    <com:applicationDN>System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/XVTEventTopic</com:applicationDN>
    <com:eventTime>2008-08-06T21:34:11.812+01:00</com:eventTime>
    <util:managedObjectClass>UNSPECIFIED_TYPE</util:managedObjectClass>
    <util:managedObjectInstance>Label:openoss1:ForeignSource:OSS-J_Test_Import:ForeignId():1001</util:managedObjectInstance>
    <util:notificationId>AlmMonitorId:null:EventCount:10</util:notificationId>
    <alarmType>CommunicationsAlarm</alarmType>
    <alarmKey>
      <com:applicationContext>
        <com:factoryClass>myfactoryclass</com:factoryClass>
        <com:URL>http://OpenOSS:8081/opennms</com:URL>
        <com:systemProperties>
          <com:property>
            <com:name>jvt_home</com:name>
            <com:value>System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/JVTHome</com:value>
          </com:property>
          <com:property>
            <com:name>jndi_fact_class_name</com:name>
            <com:value>org.jnp.interfaces.NamingContextFactory</com:value>
          </com:property>
          <com:property>
            <com:name>jndi_url</com:name>
            <com:value>jnp://jbossjmsserver1:1099</com:value>
          </com:property>
          <com:property>
            <com:name>bean_naming_package</com:name>
            <com:value>org.jboss.naming</com:value>
          </com:property>
          <com:property>
            <com:name>jvt_event_topic_name</com:name>
            <com:value>System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/JVTEventTopic</com:value>
          </com:property>
          <com:property>
            <com:name>topic_connector_factory_name</com:name>
            <com:value>System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/TopicConnectionFactory</com:value>
          </com:property>
          <com:property>
            <com:name>system_url</com:name>
            <com:value>http://OpenOSS:8081/opennms</com:value>
          </com:property>
          <com:property>
            <com:name>xvt_event_topic_name</com:name>
            <com:value>System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/XVTEventTopic</com:value>
          </com:property>
        </com:systemProperties>
      </com:applicationContext>
      <com:applicationDN>System/OpenOSS/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/JVTHome</com:applicationDN>
      <com:type>mytype_notset</com:type>
      <alarmPrimaryKey>341</alarmPrimaryKey>
    </alarmKey>
    <basePerceivedAlarmSeverity>CRITICAL</basePerceivedAlarmSeverity>
    <baseProbableAlarmCause>ALARM_INDICATION_SIGNAL</baseProbableAlarmCause>
    <specificProblem>OSSJ_TEST_ALARM_1</specificProblem>
    <correlatedNotifications>
      <Item>
        <notificationIds>
          <com:item>UNSUPPORTED FEATURE = ITEM NOT SET</com:item>
        </notificationIds>
        <managedObjectInstance>UNSUPPORTED FEATURE = NOT SET managed object instance</managedObjectInstance>
      </Item>
    </correlatedNotifications>
    <proposedRepairActions>Test1 ProposedRepairActions</proposedRepairActions>
    <additionalText><![CDATA[<alarmid>341</alarmid>
            <logmsg>OSSJ_TEST_ALARM_1</logmsg>
            <uei>uei.opennms.org/ossjTestEvent/newAlarm/1<uei>
            <x733AlarmType>CommunicationsAlarm</x733AlarmType>
            <x733ProbableCause>ALARM_INDICATION_SIGNAL</x733ProbableCause>
            <counter>1</counter>
            <reductionkey>uei.opennms.org/ossjTestEvent/newAlarm/1::83</reductionkey>
            <nodeid>83</nodeid>
            <nodelabel>openoss1</nodelabel>
            <ipaddress>192.168.30.80</ipaddress>
            <description>OSSJ_TEST_ALARM_1</description>
            <opinstr>Test1 ProposedRepairActions</opinstr>
            <asset.managedobjectinstance>Label:openoss1:ForeignSource:OSS-J_Test_Import:ForeignId():1001</asset.managedobjectinstance>
            <asset.managedobjecttype>UNSPECIFIED_TYPE</asset.managedobjecttype>
            <asset.address2>NOT_SET</asset.address2>
            <asset.description>NOT_SET</asset.description>]]></additionalText>
  </event>
</notifyNewAlarmEvent>
...
Waiting: Event Counts:- ListRebuilt:0   NewAlrmEvt:3    ClrAlrmEvt:0    AlrmCngEvt:0 AckChngEvt:0    CommentEvt:0    UnknownIRPEvt:0     UnknownObjMsg:0 NonObjMsg:0 bjMsg:0        TxtMsg:0
***Waiting for OSS/J XVT XML JMS text message event***

10 Clear the alarms from opennms by injecting the test clear traps 

sudo sh multipleossjtesttraps_clear.sh

Click refresh on your alarms page browser to see the alarms dissappear. You slould also see 3 xml clear alarm events similar to above in the OSS/J client.

This concludes the configuration and testing of OpenOSS. We now need to get alarm communication working between the two machines.

Configuring OpenOSS1 and sending alarms between OpenOSS1 and OpenOSS

Because we are going to run two instances of OpenNMS using the Qos interface, it is important to change the configuration of OpenOSS1 to differentiate it from OpenOSS.

11 On OpenOSS1, edit the file /opennms/etc/service-configuration.xml and comment out the lines which would start the qosdrx service. We do not need qosdrx on this machine. 

<!--
        <service>
                <name>OpenNMS:Name=QoSDrx</name>
                <class-name>org.openoss.opennms.spring.qosdrx.jmx.QoSDrx</class-name>
                <invoke at="start" pass="0" method="init"/>
                <invoke at="start" pass="1" method="start"/>
                <invoke at="status" pass="0" method="status"/>
                <invoke at="stop" pass="0" method="stop"/>
        </service>
-->

12 We need OpenOSS1 to be sending data to OpenOSS. This requires the qosd configuration on OpenOSS1 to identify the machine correctly. On OpenOSS1 edit the /opt/opennms/etc/qosd.properties file and change every entry naming OpenOSS to OpenOSS1 as follows; 

org.openoss.opennms.spring.qosd.naming.provider=jnp://jbossjmsserver1:1099
org.openoss.opennms.spring.qosd.naming.contextfactory=org.jnp.interfaces.NamingContextFactory
org.openoss.opennms.spring.qosd.naming.pkg=org.jboss.naming

org.openoss.opennms.spring.qosd.jvthome=System/OpenOSS1/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/JVTHome

org.openoss.opennms.spring.qosd.jms.topicconnectionfactory=System/OpenOSS1/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/TopicConnectionFactory
org.openoss.opennms.spring.qosd.jms.topic=System/OpenOSS1/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/JVTEventTopic

org.openoss.qosd.jms.xvttopic=System/OpenOSS1/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/XVTEventTopic

org.openoss.qosd.jms.queueconnectionfactory=System/OpenOSS1/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/QueueConnectionFactory
org.openoss.qosd.jms.messagequeue=System/OpenOSS1/ApplicationType/AlarmMonitor/Application/1-0;0-0;OpenNMS_OpenOSS_AM/Comp/MessageQueue

org.openoss.opennms.spring.qosd.url=http://OpenOSS1:8081/opennms

13. Open a terminal on OpenOSS1 and run the simple OSS/J client program to connect to JbossMQ and listen for events. This is the same as step 6 except that the script configuration is slightly different; 

cd /opt/opennms/contrib/qosdaemon/testscripts
sudo sh opennms_IFOpenOSS1.sh  -xreceive1

14. Start OpenNMS on OpenOSS1 and watch for qosd starting correctly. Qosdrx should not start. 

cd /opt/opennms/bin
sudo sh opennms -v start
....
OpenNMS.Importer       : running
OpenNMS.JettyServer    : running
OpenNMS.QoSD           : running
      [  OK  ]

Look at the OSS/J client started previously in step 13. You should see a listRebuilt event once OpenNMS on OpenOSS1 has started.

Browse to http://localhost:8980/opennms/ and log in using user:admin password:admin to check OpenNMS is working correctly

15. We need to datafill OpenNMS on OpenOSS1 with the same nodes as on OpenOSS in step 8. 

cd /opt/opennms/bin
./send-event.pl  uei.opennms.org/internal/importer/reloadImport

Browse to the Host List tab on the opennms consol and check that the following nodes have been loaded; 

localhost 
openoss1 
openoss2 
openoss3 
Outstation_OpenOSS1

16. Open a new terminal to send test alarm traps into opennms on OpenOSS1 to add alarms to the alarm list and watch the XML alarm event messages on the OSS/J client screen. 

cd /opt/opennms5.9.1/contrib/qosdaemon/qos_example_configuration/testtraps
sudo sh multipleossjtesttraps_raise.sh

Browse to the OpenNMS Alarms page and select 'All Alarms'. (http://localhost:8980/opennms/alarm/list). You should see 3 red alarms. You should also see 3 xml new alarm events in the OSS/J client opened in step 13

17 Now refresh at the alarms list on the first machine OpenOSS. It should also have the 3 alarms which were on OpenOSS1. Look at the OSS/J client connected to qosd on OpenOSS1. it should show 3 new alarm events.

18. Clear the alarms on OpenOSS1 by injecting the test clear traps 

sudo sh multipleossjtesttraps_clear.sh

Click refresh on your alarms page browser to see the alarms disappear. You should also see 3 xml clear alarm events on the OSS/J client on OpenOSS1. Similarly you should see the alarms dissappear on openOSS and 3 cleared alarms events emitted from OpenOSS.

This concludes the configuration and demonstration of the test OSS/J interface.

Additional Notes

Examining the configuration script should show which files are copied from the test configuration to the appropriate locations. It should be fairly obvious how the interface configuration can be modified for other tests.

However please note that the interface does not work correctly if OpenNMS alarms are admitted to the alarm list which do not have an associated raising event object or an associated node. Some OpenNMS internal events are of this type and so the event.xml configuration has been changed to omit the offending alarm definitions. If these alarms are present, they should be cleared from the alarms tables in the database before the interface is started.

Retrieved from "http://www.opennms.org/wiki/Dev-Jam:QosDocumentation"