contact us

docs.nervecenter.com :: NerveCenter :: NC6.1.00

NC::MIB perldoc
April, 2014

       NC::MIB - Access to NerveCenter MIB
       The NC::MIB module implements an API that allows access to the MIB
       being used by the NerveCenter Server.  The module and API is available
       for all Perl usage within NerveCenter (Poll functions, Trap Mask func-
       tions, and Perl Subroutine Actions).
       The MIB is a large static cache of data loaded by NerveCenter Server.
       MIB stands for Management Information Base and is the data dictionary
       used for SNMP operations. The NerveCenter MIB Compiler, 'mibTool', cre-
       ates the MIB. The NerveCenter Server then loads it upon startup.
       Within a MIB there are typically hundreds, if not thousands, of name
       and OID declarations plus enumeration listings.  NerveCenter uses this
       data dictionary for building SNMP requests, parsing responses and
       decoding SNMP Notifications (Traps and Informs).  This data can be
       accessed through the API that this module implements.

       Object names, OIDs and types

       Each entry in the MIB centers on defining an Object.  An Object has a
       name, an object identifier (OID) and a type.  Let's consider each of
       these in turn.

       Object names

       Object names are textual labels, meaning they are "human readable."
       Examples of names are "system.sysName", "ifEntry.ifInOctets", and "ifX-
       Entry.ifHCInOctets".  Notice there are two parts to this: a base object
       name and an attribute name.

       NerveCenter makes the distinction between base object and attribute in
       that attributes are items attached to a base object and may contain a
       (pollable) value.  For example "sysLocation" is an attribute of the
       base object "system".  In SNMP, "sysLocation" can be polled but "sys-
       tem" cannot.  If you try to poll "system" in a tool such as 'ncget',
       the response from the polled SNMP Agent will be something like "No such

           % ncget -v1 public system
           Sending to 161/udp
           Error! noSuchName [Check vb#1 (Agent cannot resolve the OID)]
               #vb1: {system, (null)}

       But if you poll for the "sysLocation" you might get back a value.

           % ncget -v1 public sysLocation.0
           Sending to 161/udp
           Normal SNMPv1 reply
               #vb1: {sysLocation.0, Boston, MA/OCTET STRING[10]}

       (So, "What is with that ".0"?" you might be asking.  In SNMP you always
       need to phrase a GET REQUEST by including which 'instance you want to
       retrieve.  For scalars, such as found in the 'system' group, a ".0" is
       the required instance.  Later, when we look at tables, you'll see
       instances being used in a more understandable manner - such as that
       ".33" is the instance naming for row #33.  Unfortunately you have to
       remember that ".0" is the mandatory instance value for scalars.)

       Object identifiers (OIDS)

       OIDs are, each, a specific series of sub-identifiers, where each sub-
       identifier is a numeric value.  They are commonly displayed in a deci-
       mal-dot notation, such as "".  These values are stati-
       cally assigned.  So if "" means "system.sysDescr", then
       it will always mean that.  Also, know that the same is true in reverse:
       "system.sysDescr" translates to "" and this will always
       be the this name's OID translation.

       Sometimes OIDs are preceeded with a leading dot.  And sometimes by a
       trailing dot.  Either is optional and therefore often omitted.  The API
       understands this.  For example the API sees these three OIDs as identi-
       cal: ".1.3.6" and "1.3.6" and "1.3.6.".

       OIDs may not contain non-numeric characters.  So "one.2.3." is not an
       OID.  Neither is "1.c.3.2" or "$1.19".  As well, OIDs must have at
       least one sub-identifier.  This means "." by itself does not qualify as
       an OID but "1" is perfectly fine - it is a single element OID.

       Object types

       Objects always have a type association. In SNMP the set of possible
       types is limited to a fairly small range: INTEGER, Integer32, Counter,
       Counter32, Counter64, Gauge, Gauge32, IpAddress, ObjectID, OctetString,
       TimeTicks and Unsigned32.

       Adding it up: Object Names + OID + Type

       Every object defined in the MIB consists of a name, an OID and a type.
       This trio of information is known to all devices (SNMP Agents) that
       support the object.  Thus if you ask for "system.sysContact" from some-
       thing, the local SNMP Stack knows to convert the requested name to its
       assigned OID; the SNMP Agent answering the query for this object knows
       the same assignment; the SNMP Agent will respond (if is supports the
       requested object) with specified data type.  In a loose way this is
       similar to how telephones work:  If you want to call somebody, you use
       their phone number; you only get to talk to your friend if you use the
       right phone number.

       Let's try an example.  To lookup a device's "system.sysContact" value
       the following steps are used, assisted by the entries held in SNMP data
       dictionary (ie: the MIB).

           1. An application needs to find out a device's "system.sysContact"
           value.  The requesting application looks up "system.sysContact" in
           its MIB.  The retrieved OID is "".

           2. The requesting application issues a SNMP request to the device,
           asking for "".

           3. The device being queried does a reverse lookup on the incoming
           request's "" and knows to respond with the value for
           its configured "sysContact" information.  The data type for this
           value is "OctetString", which for this object means a displayable
           string (ex: "Jane Doe").

           4. The device responds back to the requesting application, supply-
           ing the same OID and the value ("Jane Doe"), identifying the value
           as an OctetString

           5. The requestion application get the response, finds the
           "" and associated OctetString containing the value
           ("Jane Doe").  Using its MIB, the application recoginizes the
           "" as being the identifier for "system.sysContact"
           and can verify that the return type (OctetString) is what should be
           returned and uses this to unpackage the data value ("Jane Doe").

       Translating between OIDs and names

       As seen in the above scenario, bridging back and forth between OIDs and
       Names is a primary usage of the MIB.  NC::MIB provides for this with
       the functions parse_oid(), get_oid() and get_name().

       parse_oid() - translate an object identifier's naming

           $name = NC::MIB::parse_oid( $oid );

       This method translates an OID to a name.  The OID argument to
       parse_oid() is to be given as a Perl string scalar.  For example:

           my $oid = "";
           my $name = NC::MIB::parse_oid( $oid );
           print "Okay, $oid translates to $name!\n";

           Okay, translates to system.sysDescr.0!

       Names in NerveCenter are provided as a combination of a base object
       name, an attribute name and a trailing instance identification.  You
       can see that in the example. The OID "" didn't return
       simply a word but rather the longer value "system.sysDescr.0".  The
       three elements of that return line up with NerveCenter's naming: a base
       object, an attribute and a trailing instance.

       Let's use Perl's split() function to break up the response so we can look
       at it again.

           my $oid = "";
           my $name = NC::MIB::parse_oid( $oid );
           print "Okay, $oid translates to $name!\n";
           my ( $baseObject, $attribute, $instance ) = split( '\.', $name, 3 );
           print " --- $baseObject + $attribute + $instance\n";

           Okay, translates to system.sysDescr.0!
              --- system + sysDescr + 0

       Now, without repeating all the Perl lines, the following snippets show
       a replacement for the first line ( "my $oid = ...." ) and then jump
       forward to show how parse_oid handles a wider set of possible OIDs.
       The examples cover errors and other oddities.

           # --------------------------------------------------------------
           # Ex1: '1' is the base of the OID tree. 'iso' is the name assigned to '1'.
           my $oid = '1';

           Okay, 1 translates to iso!
              --- iso +  +

           # --------------------------------------------------------------
           # Ex2: '1.3.6'. This translates to 'dod'.
           my $oid = '1.3.6';

           Okay, 1.3.6 translates to dod!
              --- dod +  +

           # --------------------------------------------------------------
           # Ex3: An invalid OID is given. So we get back nothing.
           my $oid = 'one.2.3';

           Okay, one.2.3 translates to !
              ---  +  +

           # --------------------------------------------------------------
           # Ex4: The ifInOctets value for the row #50 of ifTable.
           #         = ifTable
           #       = ifEntry
           #    = ifInOctets
           # = ifInOctets on row #50
           my $oid = '';

           Okay, translates to ifEntry.ifInOctets!
              ---  ifEntry + ifInOctets + 50

       get_name() -- translate an object identifier to its closest fitting name

           my $name = NC::MIB::get_name( "" );

       The function get_name() returns a single name for a given OID.  The
       return represents the closest fitting name for the OID, where the
       attempt is made to find the single object from the MIB that comes the
       closest to matching the OID.

       In the first example, the OID is an exact match for an entry in the
       MIB.  "1.3.6" is "dod".  In the second example, the longer OID is best
       matched by ifInOctets.  The trailing ".50" of the argument
       "" does not lead to a better fit, so it is

           # --------------------------------------------------------------
           # Ex1: "1.3.6" is 'dod' in the mib.
           my $oid = "1.3.6"
           my $name = NC::MIB::get_mib( $oid );
           print "$name best fits $oid\n"

           dod best fits 1.3.6

           # --------------------------------------------------------------
           # Ex2: The ifInOctets value for the row #50 of ifTable.
           #      = ifTable
           #    = ifEntry
           # = ifInOctets
           my $oid = '';
           my $name = NC::MIB::get_mib( $oid );
           print "$name best fits $oid\n"

           ifInOctets best fits

       A third example shows the tear-down of an OID by repeated removal of
       its final sub-element and using get_name() to examine what remains.
       The code is a loop.

           # --------------------------------------------------------------
           # loop and tear-down ""
           my $oid = "";
           my $indx = rindex( $oid, '.');
           while ( $indx != -1 || length($oid) > 0 ) {
               print "get_name( " . $oid . " ) -=> " . NC::MIB::get_name( $oid ) . "\n";
               $oid = substr( $oid, 0, $indx-length($oid) ); # pop off the trailing ".nnn"
               $indx = rindex( $oid, '.');

       When this is encountered the following is produced.  Notice how there
       are two best fits for "ifInOctets".  This because the ".50" is being
       ignored.  Once it and the ".10" are popped off the layers of supporting
       MIB object names are revealed.

           get_name( ) -=> ifInOctets
           get_name( ) -=> ifInOctets
           get_name( ) -=> ifEntry
           get_name( ) -=> ifTable
           get_name( ) -=> interfaces
           get_name( ) -=> mib-2
           get_name( ) -=> mgmt
           get_name( ) -=> internet
           get_name( 1.3.6 ) -=> dod
           get_name( 1.3 ) -=> org
           get_name( 1 ) -=> iso

       get_oid() -- translate a Base Object and Attribute name to an OID

           my $name = 'system.sysDescr';
           my $oid = NC::MIB::get_oid( $name );

       The function get_oid() is roughly the reverse of parse_oid().  The
       parameter given to get_oid() is a name, such as "system.sysLocation" or
       "ifXEntry.ifHCInOctets".  The return will be the OID assigned to that
       name.  If the input name is not known, then the output is an empty

       Supportive lookup functions

       get_trapname() -- translate an OID into a SNMP Notification Name

           $trapname = NC::MIB::get_trapname( $trapoid );

       SNMP Notifications are defined as being either a Trap or an Inform.
       Traps and Informs are defined in the MIB and each is identified by an
       assigned OID.  When a SNMP Notification is received by a management
       application, the notification's OID - referred to as its Trap OID - is
       used to identify it.  This is rather analogous to phone numbers and
       Caller ID.  For example when your phone rings, it might show you a
       phone number.  You, or perhaps your phone, translates this to a per-
       son’s name.  This is how a management station identifies notifications:
       it looks at the incoming event’s Trap OID and converts this to a name.

       The get_trapname() function does the lookup and conversion of a Trap
       OID to its defined name.  If given Trap OID is found, the function
       returns the name as a string value.  If the Trap OID is not recogniz-
       able, then the function returns an empty string value.

       get_mibname() -- retrieve the name of the defininig MIB Module

           my $mibname = NC::MIB::get_mibname( $name );

       The MIB is created from a set of text files wherein each provides a
       'MIB Module'.  Each such module defines a set of objects, often build-
       ing their definitions from declarations made in base-level modules.
       The result, the data dictionary known as the MIB, is the sum of the
       declarations found across the set of included MIB Modules.

       In NerveCenter, the 'mibTool' utility creates the MIB.  When it assem-
       bles the data dictionary, it includes with each object the name of the
       MIB Module where it was defined.  This can be retrieved through the
       function get_mibname(). If the function can find the provided OID or
       Name in the MIB, it returns the name of the defining MIB Module.  If
       the lookup is not successful, it returns an empty string.

       get_type() -- retrieve an object's return type

       Translating between enumerated values and names

       There are many cases where a MIB object is defined to contain one of a
       set of possible values.  The range of these possible values is given as
       an enumeration.  The definition provides both a value and a label for
       each possibility.

       An example is the quickest way to see this.  In RFC2863 and its IF-MIB
       module, the object 'ifEntry.ifAdminStatus' tells whether an interface
       on a device is administratively allowed to be used or is turned off or
       is set to be in a test mode.  From the MIB Module "IF-MIB" this is the

           ifAdminStatus OBJECT-TYPE
               SYNTAX  INTEGER {
                           up(1),       -- ready to pass packets
                           testing(3)   -- in some test mode
               MAX-ACCESS  read-write
               STATUS      current
                       "The desired state of the interface.  The testing(3) state
                       indicates that no operational packets can be passed.  When a
                       managed system initializes, all interfaces start with
                       ifAdminStatus in the down(2) state.  As a result of either
                       explicit management action or per configuration information
                       retained by the managed system, ifAdminStatus is then
                       changed to either the up(1) or testing(3) states (or remains
                       in the down(2) state)."
               ::= { ifEntry 7 }

       When an instance of this object is polled, the response should be one
       of the three defined values.  The response will contain the numeric

       To support working with enumerations, NC::MIB provides the two func-
       tions get_enum_value() and get_enum_label().

       get_enum_label() -- retrieve the text label for a numeric value

       The function get_enum_label() retrieves from the MIB the text label
       assigned to a numeric value for a specific MIB object.  If the function
       is called with a MIB Object that does not define a numeric range, or
       the MIB object is unknown, or the provide value is out of the defined
       range, then an empty string is returned.  Otherwise, the assigned text
       value is returned.

       Here is an example using the above ifAdminStatus definition.  This bit
       of Perl code loops over the range defined by the definition and prints
       the labels.

           for ( my $value = 0; $value < 6; $value++ ) {
               my $label = NC::MIB::get_enum_label( "ifEntry\.ifAdminStatus", $value );
               print TFILE "For ifAdminStatus of $value, the label is $label\n";

       When run, the loop produces the following output lines.

           For ifAdminStatus of 0, the label is
           For ifAdminStatus of 1, the label is up
           For ifAdminStatus of 2, the label is down
           For ifAdminStatus of 3, the label is testing
           For ifAdminStatus of 4, the label is
           For ifAdminStatus of 5, the label is

       As a second example, the following Perl code shows a loop that works
       across the varbinds attached to a trap.  As part of its per-varbind
       processing, this code uses get_enum_label() to find if there is a label
       for varbind's value.

           for ( my $vbn = 0; $vbn < VbNum(); $vbn++ ) {
               my $attr = VbAttribute( $vbn );
               my $object = VbObject( $vbn );
               my ( $baseobject, $instance ) = split( '\.', $object, 2 );
               my $vboid = NC::MIB::get_oid( "$baseobject.$attr" ) . "\.$instance";
               my $value = VbValue( $vbn );
               my $type = NC::MIB::get_type( "$baseobject.$attr" );
               my $enumlabel = NC::MIB::get_enum_label( "$baseobject.$attr", $value );
               my $mibmodule = NC::MIB::get_mibname( "$baseobject.$attr" );
               print "     #vb$vbn: {$mibmodule\:\:$baseobject.$attr.$instance, ";
               print "$enumlabel $value\/$type}  (oid:$vboid)\n";

       For a linkDown event, the output from the above code gives the follow-
       ing output.  The 'up' and 'down' are the returns from this get_enum_label().

            #vb0: {IF-MIB::ifEntry.ifIndex.100,  100/INTEGER}  (oid:
            #vb1: {IF-MIB::ifEntry.ifAdminStatus.100, up 1/INTEGER}  (oid:
            #vb2: {IF-MIB::ifEntry.ifOperStatus.100, down 2/INTEGER}  (oid:

       get_enum_value() -- retrieve the numeric value for a text label

       The function get_enum_value() performs the reverse of get_enum_label.
       The function is called with a text label and a specific MIB object.
       Similar to get_enum_label, if the named MIB object defines an enumera-
       tion and then the provided label matches one of the defined entries,
       then the corresponding value is returned.  If no matching value can be
       found, then a -1 (negative one) is returned; thus this function is
       always returning a numeric value.

       In this example the defined labels for ifAdminStatus (up, down, test-
       ing) are intermixed with several other words.  These are fed through
       get_num_value() and the output shows the result.

           my @labels = qw/flower up duck down goose testing bread/;
           foreach my $label ( @labels ) {
               my $val = NC::MIB::get_enum_value( "ifEntry\.ifAdminStaus", $label );
               print TFILE "For ifAdminStatus and the label $label, the value is $val\n";


           For ifAdminStatus and the label flower, the value is -1
           For ifAdminStatus and the label up, the value is 1
           For ifAdminStatus and the label duck, the value is -1
           For ifAdminStatus and the label down, the value is 2
           For ifAdminStatus and the label goose, the value is -1
           For ifAdminStatus and the label testing, the value is 3
           For ifAdminStatus and the label bread, the value is -1
       Maintained by Customer Service <techsupport@openservice.com>
       Copyright (c) 1994-2014 by OpenService, Inc./LogMatrix, Inc. All rights reserved.

       This module is provided as a component of the NerveCenter product.  It
       is not meant for availability apart from usage with NerveCenter.  Use
       of this module should remain consistent with that expressed in the
       licensing of NerveCenter.