Converting MIBs Using mib2opennms

From OpenNMS
Jump to navigation Jump to search

Deprecation note

mib2opennms and mibs2events are deprecated in favor of the graphical SNMP MIB compiler to be found at http://localhost.localdomain/opennms/admin/mibCompiler.jsp

mib2opennms How-To

This little document provides an explanation of how to import SNMP MIBs into OpenNMS, using the open source tool 'mib2opennms'. In reality we don't import the whole MIB, we just take out the trap definitions (if there are some) from the MIB and add them as events to OpenNMS.

mib2opennms versus mib2events

mib2opennms is a little tool that has been growing for a long time and is documented here. mib2events will be the replacement for mib2opennms and still needs to be documented. It probably will be integrated into the GUI for OpenNMS version 1.12 in early 2013. Look at the short description at the end of this document: Converting_MIBs_Using_mib2opennms#mib2events

Why import the OIDs using this tool?

OpenNMS has the ability to receive SNMP traps; In order to do that, OpenNMS must know how to treat each event (thus requires a description for each OID that it receives). Normally if you don't do that you will receive anoying messages like the following on your event database:

Received unformatted enterprise event (enterprise:.1.3.6.1.4.1.2021.250.10 generic:0 specific:0). 0 args:

Also importing the OIDs by hand is error prone and tedious, so the use of this tool is a must when adding new OIDs.

Recommendations

If you intend to use mib2opennms, it is highly recommended you install net-snmp as chances are high that the MIB(s) you intend to import are dependent on something contained within the base set of MIBS provided by net-snmp. Without net-snmp, mib2opennms may not be able to translate your MIBs, and may not provide very useful information as to why.

NOTE: If you're using Ubuntu server, the package "net-snmp" no longer exists in the standard repositories, you will need to get the "snmp-mibs-downloader" package. This package puts the MIBs in /var/lib/mibs/ietf by default.

Download and build the software

There are several alternatives (RPM, source code). Look for it in the contrib directory of OpenNMS.

openSUSE users may download the prepackaged RPM from http://download.opensuse.org/repositories/server:/monitoring:/opennms/

Compile the mib2opennms package from source

Recent versions of OpenNMS have separated mib2opennms to it's own project. If it is not in your contrib directory, you can get it from source GIT:

git clone git://github.com/OpenNMS/mib2opennms.git
cd mib2opennms
git submodule init
git submodule update

Then setup the configure scripts:

autoreconf -fvi
./configure

The latest install docs are located in INSTALL file for compiling options and basic instructions. But generally:

[username@host ~]# cd mib2opennms
[username@host mib2opennms]# ./configure
[username@host mib2opennms]# make && make install

If the configure script is missing you can rebuild it (needs automake/autoconf installed) with

 autoreconf -fvi

If the configure script stops because smi.h is missing look out for libsmi for your system (you may need the libsmi-devel package to get the header files).

Some systems may complain about missing the libsmi2 package. Depending on how you download your packages you might try something like this:

apt-get install libsmi2-common
apt-get install libsmi2-dev

and than compile it again.

Build an RPM from the mib2opennms sources

Download the latest tarball from the Sourceforge project page.

Install the RPM packaging utility and libraries needed for mib2opennms:

[username@host ~]# yum install rpm-build libsmi-devel

Now build the RPM:

[username@host ~]# rpmbuild -ta /path/to/mib2opennms-<version>.tar.gz

And finally, install it:

[username@host ~]# rpm -Uvh /usr/src/redhat/RPMS/<arch>/mib2opennms-<version.<arch>.rpm

How to use

Single MIB file

Convert a single mib file and set the value for generic to 6 with

mib2opennms -6 mibfile.mib >mibfile.events.xml

Edit the mibfile.events.xml and add as first line a line with <events>, as last line a line with </events>. Move the file to $OPENNMS_HOME/etc/events

Add a line to $OPENNMS_HOME/etc/eventconf.xml like

<event-file>events/mibfile.events.xml</event-file>

Ensure <event-file>events/default.events.xml</event-file> remains the last entry. Restart OpenNMS and the new events are ready to go.

For most trap definition in mibs this should do the job. If you have problems see the detailed configuration explanation below and in Event Configuration How-To

See also Converting Dell Traps To Events.

Note: If your mibs rely on imports you will need to specify the mib directory with the -m flag. The base mibs can be installed to /var/libs/mibs/ietf/ by running the following in Ubuntu:

sudo apt-get install snmp-mibs-downloader
sudo /etc/snmp-mibs-downloader/download-mibs

Batch processing

It is better to get a detailed list of OIDs in the form of XML files; so that you can choose what to cut/paste into your "eventconf.xml," instead of a huge (and useless) list of OIDs.

Here is a Bash script that can do the nasty work for you (take care to define the appropiate variables first):

# <----- CUT HERE ----->

#!/bin/bash
#
# This program generates a list of XML files to be used with OpenNMS and the 
# "event" section.
# Author: Jose Vicente Nunez Zuleta (josevnz@newbreak.com)
# Requires: mib2openms (http://www.tompa.nu/mib2opennms/)
#

MIBPATH="/usr/share/snmp/mibs:/usr/share/mibs:/home/josevnz/mibs"
MIBDEF=$1
destdir=$2

if [ -z $MIBDEF ] ; then
cat <<EOF;
[ERROR]:
You must supply values for the mib directory. Examples:

/home/josevnz/mibs

/usr/share/snmp/mibs

Then the script will locate all the '*.txt' files present.


EOF
exit 1
fi


mibc="/usr/bin/mib2opennms"
mkdir="/bin/mkdir"
perl="/usr/bin/perl" # sed SUCKS!!! ;)

# Use the user destination dir if present
if [ -z $destdir ] ; then
  destdir="/tmp";
fi

if [ ! -e $destdir ] ; then
  $mkdir -p $destdir
  if [ $? -ne 0 ] ; then
    echo "Error creating destination dir"
  fi
fi

# Get the list of all the MIBs on this system
LIST=`find $MIBDEF -type f -name '*.txt' | /usr/bin/xargs`
if [ $? -ne 0 ] ; then
  echo "Error locating the MIBS"
fi

for file in $LIST; do
  # Get the mib name from the file
  mib=`echo $file |$perl -e' while(<STDIN>) { $_ = m#.*/(.*)\.txt#; print $1 }'`
  echo "Processing: $mib"
  # Generate a OpenNMS MIB xml file for each located mib
  COMMAND="$mibc -f "$destdir/$mib.xml" -m $MIBPATH $file"
  echo $COMMAND
  $COMMAND
  if [ $? -ne 0 ]; then
   echo "MIB conv failed"
  fi
done

# <----- CUT HERE ----->

Then you can call it like this:

 ./generate_mibs.bsh /home/josevnz/mibs 1> output.txt 2> errors.txt

Resources

List of extracted (and ready to use) MIBs:

More on mib2opennms

This came up on the discussion list, so I thought it should go here.

Q: I am trying to get the Juniper MIBs into OpenNMS, but I can't get mib2opennms to work. I only get segmentation faults:

# mib2opennms mib-jnx-ipv6.txt
mib2opennms version 0.2.2
Segmentation fault

A: This usually means that there is a problem with the ASN.1 notation in your mibs.

I don't get a seg fault on that mib, but since:

grep NOTIF mib-jnx-ipv6.txt

and

grep TRAP mib-jnx-ipv6.txt

return nothing, there are no events defined in that MIB.

A quick search shows the following files support NOTIFICATION-TYPE objects:

Stormbringer:~/Desktop/JuniperMibs tarus$ grep -l NOTIF *
mib-jnx-bgpmib2.txt
mib-jnx-cfgmgmt.txt
mib-jnx-chassis.txt
mib-jnx-coll.txt
mib-jnx-ldp.txt
mib-jnx-mpls.txt
mib-jnx-ping.txt
mib-jnx-pmon.txt
mib-jnx-rmon.txt
mib-jnx-sonet.txt
mib-jnx-sonetaps.txt
mib-jnx-vpn.txt

Let's check out the first one. if I run:

/usr/local/bin/mib2opennms mib-jnx-bgpmib2.txt

I get:

        <mask>
                <maskelement>
                        <mename>id</mename>
                        <mevalue>.0.1.1</mevalue>
                </maskelement>
                <maskelement>
                        <mename>generic</mename>
                        <mevalue>0</mevalue>
                </maskelement>
                <maskelement>
                        <mename>specific</mename>
                        <mevalue>1</mevalue>
                </maskelement>
        </mask>

Note that the id looks wrong. It should be something like .1.3.6.1.4.1.x

This usually means that there is a broken import somewhere, so we should include the MIB files in the current directory:

/usr/local/bin/mib2opennms -m. mib-jnx-bgpmib2.txt
        <mask>
                <maskelement>
                        <mename>id</mename>
                        <mevalue>.0.1.1</mevalue>
                </maskelement>
                <maskelement>
                        <mename>generic</mename>
                        <mevalue>0</mevalue>
                </maskelement>
                <maskelement>
                        <mename>specific</mename>
                        <mevalue>1</mevalue>
                </maskelement>
        </mask>

Hrm, not much better, and adding the path to the default MIBs doesn't help either:

/usr/local/bin/mib2opennms -m/usr/share/snmp/mibs:. mib-jnx-bgpmib2.txt

So, it's time to look into the mib file. The first NOTIFICATION-TYPE object is:

jnxBgpM2Established NOTIFICATION-TYPE
    ::= { jnxBgpM2BaseNotifications 1 }

So let's work backwards.

jnxBgpM2BaseNotifications
    OBJECT IDENTIFIER ::= { jnxBgpM2BaseScalars 0 }

jnxBgpM2BaseScalars
    OBJECT IDENTIFIER ::= { jnxBgpM2 1 }

jnxBgpM2 MODULE-IDENTITY
     ::= { jnxBgpM2Experiment 1 }

Now, jnxBgpM2Experiment comes from:

jnxBgpM2Experiment
    FROM JUNIPER-EXPERIMENT-MIB

Therein lies the problem. As mentioned in the README:

If mib2opennms complains about a missing MIB, be sure that there is a file
in your "-m" MIB path that has the *exact* name as the MIB it is complaining
about.

For example, if it complains "Can't find RFC-1213" and you have a file in your path called "RFC1213", you must rename it or copy it to "RFC-1213".

The extensions .txt, .my and I believe .mib are acceptable, so in the above example, RFC-1213.txt should work."

Well, there is no file called JUNIPER-EXPERIMENT-MIB. So:

cp mib-jnx-exp.txt JUNIPER-EXPERIMENT-MIB

and rerun:

/usr/local/bin/mib2opennms -m/usr/share/snmp/mibs:.  mib-jnx-bgpmib2.txt
        <mask>
                <maskelement>
                        <mename>id</mename>
                        <mevalue>.0.5.1.1.1</mevalue>
                </maskelement>
                <maskelement>
                        <mename>generic</mename>
                        <mevalue>0</mevalue>
                </maskelement>
                <maskelement>
                        <mename>specific</mename>
                        <mevalue>1</mevalue>
                </maskelement>
        </mask>

Better. More research shows that the JUNIPER-SMI MIB is referenced by JUNIPER-EXPERIMENT-MIB:

cp mib-jnx-smi.txt JUNIPER-SMI
/usr/local/bin/mib2opennms -m/usr/share/snmp/mibs:.  mib-jnx-bgpmib2.txt
        <mask>
                <maskelement>
                        <mename>id</mename>
                        <mevalue>.1.3.6.1.4.1.2636.5.1.1.1</mevalue>
                </maskelement>
                <maskelement>
                        <mename>generic</mename>
                        <mevalue>0</mevalue>
                </maskelement>
                <maskelement>
                        <mename>specific</mename>
                        <mevalue>1</mevalue>
                </maskelement>
        </mask>

Success! The only problem is that "generic" is set to zero, so add the -6 option:

/usr/local/bin/mib2opennms -6 -m/usr/share/snmp/mibs:.  mib-jnx-bgpmib2.txt
        <mask>
                <maskelement>
                        <mename>id</mename>
                        <mevalue>.1.3.6.1.4.1.2636.5.1.1.1</mevalue>
                </maskelement>
                <maskelement>
                        <mename>generic</mename>
                        <mevalue>6</mevalue>
                </maskelement>
                <maskelement>
                        <mename>specific</mename>
                        <mevalue>1</mevalue>
                </maskelement>
        </mask>

The final step is to manually edit the file and make it contain "events" by adding an <events> tag at the very top and an </events> tag at the very bottom. Without these tags OpenNMS will fail to start and report an error similar to org.xml.sax.SAXException: unable to find FieldDescriptor for 'mask' in ClassDescriptor of events in output.log . These tags are not added automatically so you can prepare event definitions from a large number of input files, concatenate them together and then just wrap the resulting file with the <events> tag.

The final file, including the <events> tags, can now be added to eventconf.xml via an include as above.

This is just an example of how mib2opennms should work. I don't understand the seg faults - could be an issue with the build. We don't support stuff in contrib, so anyone with come C++ experience might want to check it out for us. WORKSFORME on my Mac (built using libsmi from fink).

mib2events

This is only a brief introduction to mib2events. You can download it from the official opennms repository as mib2events.tar.gz. Unpacking it will provide a directory mib2events-x.y.z with some informations like the readme attached here from version mib2events-1.0.1. Subdirectory lib will contain mib2events.jar. You can move this to any place you like, probably $OPENNMS_HOME/lib.

Here a snippet from the README included in mib2events-1.0.1:

RUNNING


If you are running the binary distribution directly, just run:

 java -jar $OPENNMS_HOME/lib/mib2events.jar --help

Example of usage:

 java -jar mib2events.jar --ueibase uei.opennms.org/vendors/cisco/traps/ --mib CISCO-CONFIG-MAN-MIB.txt > Cisco.events.xml
 

If you are using RPM or Debian packages, there should be a "mib2events" script in /usr/bin that works the same way.

All required MIB files must be present in the folder where the MIB file you want to compile resides.