Latest revision as of 16:16, 21 June 2012

[edit] Background

This article will describe the steps to set up OpenNMS to Monitor the state of Alvarion's Walkair 3000 Terminal Radios in a Point to Multipoint setup. It's descriptions shall follow the structure of OpenNMS 1.6.4, though I originally configured this successfully under 1.3.2. Several components will be used to effect this. They are the:

• Passive Service Keeper
• Event Translator
• Provisioning Requisitions
• A new Customer Table in the DBMS
• Notifications

The Alvarion Wakair 3000 Point to Multipoint Radio system is a Microwave Broadband solution using TDMA/FDD to share the Base Station's bandwidth capacity amongst multiple Terminal Station's usually located as CPE. The Terminal Radio's are IP-less. The Base Stations provide a management interface with which operational information on the Terminal's may be collected. The Base Station manages the Terminal's in band using a proprietary communication protocol so there is no direct SNMP or other access to the Terminals. This works well with the EMS for the Elements, WalkNet, but the only integration offered by this EMS is with HP Openview. A running EMS instance can collect data on all the Terminal's and store the raw data in an Oracle Database but offers no way of intelligently viewing this data.

The Base Stations will also forward Traps northbound to an NMS, where they will been seen to come only from the Base Stations yet contain a unique id the CID or Customer ID within the Trap which is associated with an individual Terminal. The uniqueness of these CID's is actually a human managed thing, the CID being entered when the Terminals are being Network Provisioned. A BS will not allow CIDs of the same value on its Terminals but different BSs do not talk to one another and hence you can get multiple CIDs arriving at the NMS unless they are carefully managed.

Notifications generated on the original traps from the Base Stations concerning Terminals cannot be Auto-Resolved as the trap is associated with the Base Station and the only fields you can match a resolving trap against in notifd-configuration.xml are nodeid, interfaceid and ifserviceid, thus we need to associate the traps with new nodes representing the Terminals.

The method I used with OpenNMS to monitor the status of the Terminals was to import them as Requisitioned Nodes, have a new SQL table for the Customer ID associated with a Requisitioned Node's name, assign them Passive Services for their Radio Link, one or two Ethernet Ports, and one to four E1 Ports. Then using the Event Translator I was able to capture traps of interest, extract the CID from one of the Parameters, Run an SQL query against the Customer table and associate that trap with one of the Terminals. Using the Passive Status Keeper I was able to mark a Passive Service as 'Up' or 'Down' depending on the trap.

[edit] Step 1. Importing the Walkair3k Mibs into OpenNMS as Walkair3k Events

I have already done this, edited the Events according to the procedure here, added in the Alarms reduction and clear keys. The files contain a fair bit of content so for the moment the files Walkair3k.events.xml, translator-configuration.xml and EventTranslated.events.xml (Those Walkair Traps that are useful for determining Terminal State) can be found here [1], rather than taking up a lot of screen space in this article. Perhaps they will make their way into the examples folder. As the Mibs can change slightly with each firmware upgrade, you may wish to import them yourself using the procedure outlined here

Sample

       <event>
               <mask>
                       <maskelement>
                               <mename>id</mename>
                               <mevalue>.1.3.6.1.4.1.2933.1.2</mevalue>
                       </maskelement>
                       <maskelement>
                               <mename>generic</mename>
                               <mevalue>6</mevalue>
                       </maskelement>
                       <maskelement>
                               <mename>specific</mename>
                               <mevalue>1</mevalue>
                       </maskelement>
               </mask>
               <uei>uei.opennms.org/vendor/Alvarion/traps/telecomIfChangedOn</uei>
               <event-label>FLOWARE3K-MIB defined trap event: telecomIfChangedOn</event-label>
               <descr>
                       <p>This trap is sent when telecom interface changing is detected</p><table>
                       <tr><td><b>
                       buAlrmType</b></td><td>
                       %parm[#1]%</td><td><p;></p></td;></tr>
                       <tr><td><b>
                       buAlrmSeverity</b></td><td>
                       %parm[#2]%</td><td><p;>
                       critical(1)
                       major(2)
                       minor(3)
                       normal(4)
                       warning(5)
                       </p></td;></tr>
                       <tr><td><b>
                       buAlrmState</b></td><td>
                       %parm[#3]%</td><td><p;>
                       on(1)
                       off(2)
                       </p></td;></tr>
                       <tr><td><b>
                       buAlrmData</b></td><td>
                       %parm[#4]%</td><td><p;></p></td;></tr>
                       <tr><td><b>
                       buTrapSource</b></td><td>
                       %parm[#5]%</td><td><p;></p></td;></tr></table>
               </descr>
               <logmsg dest='donotpersist'><p>
                       Walkair 3000 Event: telecomIfChangedOn trap received
                       buAlrmType=%parm[#1]%
                       buAlrmSeverity=%parm[#2]%
                       buAlrmState=%parm[#3]%
                       buAlrmData=%parm[#4]%
                       buTrapSource=%parm[#5]%</p>
               </logmsg>
               <severity>Warning</severity>
               <alarm-data reduction-key="%uei%:%dpname%:%nodeid%:%interface%" alarm-type="1" auto-clean="false" />
       </event>

Save the Walkair3k.events.xml to $OPENNMS_HOME/etc/events/ and add a line into eventconf.xml something like this

<event-file>/opt/opennms/etc/events/Walkair3k.events.xml</event-file>

• Notice the line <logmsg dest='donotpersist'>. This will allow the Event to be handled by the Event Translator without unnecessarily remaining within the Events or Alarms Table. A new Event will be generated from this with the Event Translator that will contain much more relevant and human readable data.

[edit] Step 2. Creating the Passive Services

We used the methods outlined at this section of the Passive Status Keeper

Firstly we need to configure the Passive Services for the Terminals. For getting a useful view of the state of the Terminals the services we are interested in are reflected as the hardware status of, in the base configuration

• The Radio Link between Terminal and Basestation
• Ethernet Port 1
• Ethernet Port 2

And with the E1 option (each E1 option Card contains 4 E1 ports, each terminal can potentially take two of these cards, we only ever had one card and of that only ever used one E1 Port so our configuration reflects that, though it's easy enough to extend the Passive Services)

• E1 Port 1
• E1 Port 2
• E1 Port 3
• E1 Port 4

We called them RadioLink, EthPort1, EthPort2 and E1Service.

Add the Services to the Database

 psql -U opennms -c "insert into service values (nextval('serviceNxtId'), 'RadioLink');"
 psql -U opennms -c "insert into service values (nextval('serviceNxtId'), 'EthPort1');"
 psql -U opennms -c "insert into service values (nextval('serviceNxtId'), 'EthPort2');"
 psql -U opennms -c "insert into service values (nextval('serviceNxtId'), 'E1Service');"

These service will now be available in a Services Drop Down list within the Manage Provisioning Requisitions subsection of the Nodes section in the admin area of the Web UI.

We next add a Polling Package for the Passive Services. This is added in poller-configuration.xml as a new package. We set IP addresses for the Requisitioned Nodes in the range 169.254.*.* as in the Wiki article referenced above as we reckoned nothing else would be using them within our monitored network.

    <package name="passive-services">
        <filter>IPADDR IPLIKE *.*.*.*</filter>
        <include-range begin="169.254.1.1" end="169.254.254.254"/>
        <rrd step="300">
            <rra xmlns="">RRA:AVERAGE:0.5:1:2016</rra>
            <rra xmlns="">RRA:AVERAGE:0.5:12:4464</rra>
            <rra xmlns="">RRA:MIN:0.5:12:4464</rra>
            <rra xmlns="">RRA:MAX:0.5:12:4464</rra>
        </rrd>
        <service name="RadioLink" interval="30000" user-defined="false" status="on"/>
        <service name="E1Service" interval="30000" user-defined="false" status="on"/>
        <service name="EthPort1" interval="30000" user-defined="false" status="on"/>
        <service name="EthPort2" interval="30000" user-defined="false" status="on"/>
        <downtime begin="0" end="300000" interval="5000"/>
        <downtime begin="300000" end="43200000" interval="30000"/>
        <downtime begin="43200000" interval="300000"/>
    </package>

And at the bottom of poller-configuration.xml, added the monitor tag for each Passive Service.

    <monitor service="RadioLink" class-name="org.opennms.netmgt.poller.monitors.PassiveServiceMonitor"/>
    <monitor service="E1Service" class-name="org.opennms.netmgt.poller.monitors.PassiveServiceMonitor"/>
    <monitor service="EthPort1" class-name="org.opennms.netmgt.poller.monitors.PassiveServiceMonitor"/>
    <monitor service="EthPort2" class-name="org.opennms.netmgt.poller.monitors.PassiveServiceMonitor"/>

That's it for the Services, we now need to start Provisioning some Nodes.

[edit] Step 3. Provisioning the Terminal Radios

Passive Nodes for the Terminals can be created using the WebUI at Admin - Manage Provisioning Requisitions. Quick Tutorial on using this is here. Add a new requisition, then start adding the nodes, giving each node an interface and what ever Passive Services are utilised. It should look something like this.

Creating Passive Nodes

At this point I'd just like to mention that I think the sequence of the IP address assigned to the nodes is immaterial. The could all be the same IP Address as far as I can see as the Node_Name:Service part of the Passive Status Keeper hash key should be enough to differentiate the Service status. There may be a reason for adding the same Service twice to a Passive Node and thus you would need multiple IP addresses, but I don't believe there is any reason that would be needed for the case of the Alvarion Walkair3k Radios.

Also you may notice that there is a category for WalkairTS. I created this category and also a WalkairBS for the Surveillance View and Availability Display on the Homepage.

I also divided up the Terminals into different Provisioning Requisitions for priority purposes for when we came to notification escalation paths differentiating them by 169.254.10.*, 169.254.20.*, 169.254.30.*, but could have just as easily done it by category groups and had just one Provisioning Requisition

One can also just edit the xml file for the Provisioning Requisitions called imports-[Requisition Name].xml in $OPENNMS_HOME/etc, created when you save in the WebUI. A look at the file snippet for the above image is

 <?xml version="1.0" encoding="UTF-8"?>
<model-import xmlns="http://xmlns.opennms.org/xsd/config/model-import"
    date-stamp="2009-07-20T11:22:16.271+01:00"
    last-import="2009-07-10T12:44:41.599+01:00"
    foreign-source="TerminalStations-NormalPriority" non-ip-snmp-primary="N">
    <node node-label="########" foreign-id="1248085151316" building="TerminalStations-NormalPriority">
        <interface ip-addr="169.254.20.15" descr="" status="1" snmp-primary="P">
            <monitored-service service-name="EthPort1"/>
            <monitored-service service-name="RadioLink"/>
        </interface>
        <category name="WalkairTS"/>
    </node>
    <node node-label="######" foreign-id="1248085046815" building="TerminalStations-NormalPriority">
        <interface ip-addr="169.254.20.8" descr="" status="1" snmp-primary="P">
            <monitored-service service-name="EthPort1"/>
            <monitored-service service-name="RadioLink"/>
        </interface>
        <category name="WalkairTS"/>
    </node>
    <node node-label="#######" foreign-id="1248084887915" building="TerminalStations-NormalPriority">
        <interface ip-addr="169.254.20.3" descr="" status="1" snmp-primary="P">
            <monitored-service service-name="EthPort1"/>
            <monitored-service service-name="RadioLink"/>
        </interface>
        <category name="WalkairTS"/>
    </node>
    <node node-label="#############" foreign-id="1245660490231" building="TerminalStations-NormalPriority">
        <interface ip-addr="169.254.20.68" descr="" status="1" snmp-primary="P">
            <monitored-service service-name="EthPort1"/>
            <monitored-service service-name="RadioLink"/>
        </interface>
        <category name="WalkairTS"/>
    </node>

We need to import the XML data into the Database. At the Create Provisioning Requisitions Page click on the "Import" link to sync you Database with the XML contents.

[edit] Step 4. Creating a Customer Table in a DBMS

Using your favourite tool (ie. pgAdminIII) or the command line, the Customer Table needed is created with this query

pqsl -U opennms -d opennms

opennms=#

CREATE TABLE customer
(
  custid integer NOT NULL,
  custname character varying(256),
  CONSTRAINT customer_pkey PRIMARY KEY (custid)
)
WITH (OIDS=FALSE);
ALTER TABLE customer OWNER TO opennms;
GRANT ALL ON TABLE customer TO opennms;
GRANT ALL ON TABLE customer TO postgres;
GRANT ALL ON TABLE customer TO public;
COMMENT ON TABLE customer IS 'Customer table for resolving CID''s from Walkair Events';
COMMENT ON COLUMN customer.custid IS 'Walkair CID';
CREATE INDEX custid
  ON customer
  USING btree
  (custid);

Then we need to populate the Table with the Name of the Terminal and the CID it has been assigned during the Walkair Terminal Network Provisioning when you are configuring your radio for deployment. The name in the Database must match exactly the node name in the Provisioning Requisition, and I think it is case sensitive matching also. ie.

 psql -U opennms -c "insert into customer values (23, 'Terminal Abx');"

[edit] Step 5. Configuring the Events Translator Service to listen for selected events

We use the Event Translator service to perform two things. One is to associate an Event of interest that comes from the Terminals Base Station to the Passive Node that represents the Terminal Station in OpenNMS. Second is to use an Event of interest to mark a Passive Service as Up or Down for that Passive Node in OpenNMS.

This section will not include a detailed description of how Event Translator works. This has already been detailed in a Wiki article here. By editing the file translator-configuration.xml and including an event uei as a parameter in this tag <event-translation-spec> we cause the Event Translator to listen for these Events and to perform the defined actions upon them. The full translator-configuration.xml configuration for the Walkair3k Radios can be downloaded [2].

A short snippet of it is provided for explaining the actions performed.

    <!-- WalkAir 3000 10.5GHz Multipoint Radios -->
          <!-- 1. Add 2 new parameters for the Walkair3k Trap radioLinkLossOn. The BS name & the TS name
               2. Translate 3 fields. Nodeid from BS id to TS id, the TS node IP address, the provisioned service
               3. Create a passiveServiceStatus event and sets the servicebstatus to Down.-->
          <event-translation-spec uei="uei.opennms.org/vendor/Alvarion/traps/radioLinkLossOn">
                  <mappings>
                          <!-- 1 -->
                          <mapping>
                                  <assignment type="parameter" name="radioBS">
                                          <value type="parameter" name=".1.3.6.1.4.1.2933.1.2.19.5.0" matches="^(.+) > TS CID ([0-9]+) .*" result="${1}" />
                                  </assignment>
                                  <assignment type="parameter" name="radioTS">
                                          <value type="sql" result="select customer.custname from customer where customer.custid=?::integer">
                                                  <value type="parameter" name=".1.3.6.1.4.1.2933.1.2.19.5.0" matches="^(.+) > TS CID ([0-9]+) .*" result="${2}" />
                                          </value>
                                  </assignment>
                        <!-- 2 -->
                                  <assignment type="field" name="nodeid">
                                          <value type="sql" result="select node.nodeid from node where node.nodelabel in (select customer.custname from customer where customer.custid=?::integer)">
                                                  <value type="parameter" name=".1.3.6.1.4.1.2933.1.2.19.5.0" matches="^(.+) > TS CID ([0-9]+) .*" result="${2}" />
                                          </value>
                                  </assignment>
                                  <assignment type="field" name="interface">
                                          <value type="sql" result="select ipinterface.ipaddr from ipinterface,node where ipinterface.nodeid=node.nodeid and node.nodelabel in (select customer.custname from customer where customer.custid=?::integer)">
                                                  <value type="parameter" name=".1.3.6.1.4.1.2933.1.2.19.5.0" matches="^(.+) > TS CID ([0-9]+) .*" result="${2}" />
                                          </value>
                                  </assignment>
                                  <!-- Change the UEI to be a event translated radioLinkLossOn event-->
                                  <assignment type="field" name="uei">
                                          <value type="constant" result="uei.opennms.org/services/etRadioLinkLossOn" />
                                  </assignment>
                                  <assignment type="field" name="service">
                                          <value type="constant" result="RadioLink" />
                                  </assignment>
                          </mapping>
                          <!-- 3 - Passive Node Provisioning -->
                          <mapping>
                                  <!-- Return the custName from the customer Table -->
                                  <assignment type="parameter" name="passiveNodeLabel">
                                          <value type="sql" result="select customer.custname from customer where customer.custid=?::integer">
                                                  <value type="parameter" name=".1.3.6.1.4.1.2933.1.2.19.5.0" matches="^(.+) > TS CID ([0-9]+) .*" result="${2}" />
                                          </value>
                                  </assignment>
                                  <!-- Return the Passive Node IP Address from the ipaddress Table. (Nested Query) -->
                                  <assignment type="parameter" name="passiveIpAddr">
                                          <value type="sql" result="select ipinterface.ipaddr from ipinterface,node where ipinterface.nodeid=node.nodeid and node.nodelabel in (select customer.custname from customer where customer.custid=?::integer)">
                                                  <value type="parameter" name=".1.3.6.1.4.1.2933.1.2.19.5.0" matches="^(.+) > TS CID ([0-9]+) .*" result="${2}" />
                                          </value>
                                  </assignment>
                                  <!-- Create a parameter - Service affected-->
                                  <assignment type="parameter" name="passiveServiceName">
                                          <value type="constant" result="RadioLink" />
                                  </assignment>
                                  <!-- Create a parameter - Alarm type is ON [1-On, 2-Off] -->
                                  <assignment type="parameter" name="passiveStatus" >
                                          <value type="parameter" name=".1.3.6.1.4.1.2933.1.2.19.3.0" matches="1" result="Down" />
                                  </assignment>
                                  <!-- Change the UEI to be a passive status event-->
                                  <assignment type="field" name="uei">
                                          <value type="constant" result="uei.opennms.org/services/passiveServiceStatus" />
                                  </assignment>
                          </mapping>
                  </mappings>
          </event-translation-spec>

Some of the mapping/assignments are the same query. I created 2 new parameters for the new translated Event to display the Terminal Station and Base Station names as Event Parameters. Next I created a new Event UEI for the Terminal with the following altered information; nodeid, which would originally been the Base Station's becomes the nodeid of the Terminal that is referenced though the Customer Table by the CID in the one of the Varbinds; that is the numerical value that follows the String 'TS CID' in varbind .1.3.6.1.4.1.2933.1.2.19.5.0 of the trap.

The join is between nodelabel from the Requisitioned Node (now in the Nodes table) and the custname from the Customer table. Interface is similarly extracted. Service is manually assigned and a new uei is created called "uei.opennms.org/services/etRadioLinkLossOn"

To manipulate the Passive Service Status, the same information of nodeid and interface is extracted from an SQL query and assigned to "passiveNodeLabel" and "passiveIpAddr". The "passiveService" is manually assigned and the Alarm Type value in one of the varbinds can be used to set the "passiveStatus" in this case a 1 is the service is Down.

Passive Terminal Node with one Passive Service Down

[edit] Step 6. Creating new OpenNMS Events that hold the Translated Event information

The Translated Events configuration file, called EventsTranslated.events.xml, for the Walkair3k Radios can be downloaded here [3].

Save the the file to $OPENNMS_HOME/etc/events/ and add a line into eventconf.xml something like this

<event-file>/opt/opennms/etc/events/EventsTranslated.events.xml</event-file>

Loaded the configurations. The Translated Events should now be rendered properly in the associated Events for the Node and the Alarms Table.

Of course you may wish to extend the Events that are Translated for the Terminal and also extend the amount of state changing events on the radios as Passive Services that can be managed by the Passive Service Keeper, such as QAM to QPSK changes. I think the configurations provided give a good platform to anyone who wishes to extend the Network Management for these devices.

I think that's it. I may remember something else, in which case I'll update this document.