Acess to MIB definitions

The MIB functions implemented by LuaSNMP provide access to SNMP MIB definitions. By using these functions, management applications can retrieve the syntax and semantics of the management information implemented by SNMP agents, and are thus able to present and manipulate this information more effectively. LuaSNMP also allows to dynamically load definitions contained in SNMP MIB specifications.

err = miyb.load(FILE)

Loads the MIB objects definitions stored in FILE This file should contain a valid MIB specification, according to RFCs 1155, 1212, 1902 and 1903. If the MIB definitions have  been loaded successfully, they are added to LuaSNMP's global MIB tree and the function returns nil. A failure is indicated by a string containing an error message.
If FILE contains an absolute path, the MIB file is searched in that path. If FILE contains a relative path, this relative path is appended to the directory name in which the MIB file is searched (see below).
The function searches for the MIB file in the following directories (in order):
1) current directory;  2) directories named by the environment variable MIBDIRS; 3) directories named by the  mibdirs directive in the SNMP configuration file snmp.conf file. See the snmp.conf manual page for details. The function first looks for files without any extension and then searches for files with the extensions .txt and .mib in that order.

-- Load the MIB definitions of "my_mib"
err = mib_load("my_mib")
-- Stop execution on error.
assert(not err, err)

name, err = mib.name(NODE) 

Returns a string containing the symbolic short name associated with a MIB NODE. It receives a string containing either an object identifier ( OID in dotted notation), or a symbolic node name. The provided OID (or NAME) can contain an instance identifier, which will be appended to the returned value.
If it receives an object identifier that is not associated to any node in LuaSNMP's global MIB tree, mib.name  returns the provided OID, unaltered. If it receives a name that is not associated to any node in the global MIB tree, it returns nil plus an error message.

Examples:

Function call Returned value
mib.name("1.3.6.1.2.1.1.4") "sysContact"
mib.name("1.3.6.1.2.1.1.4.0") "sysContact.0"
mib.name("iso.org.dod.internet.mgmt.mib-2.system.sysContact") "sysContact"
mib.name("invalid") nil     mib: no such name
mib.name("5.0") "5.0"

fullname, err = mib.fullname(NODE)

Returns a string containing the symbolic full name associated with a MIB NODE. A node full name contains all the names associated with the node parents, starting with the root of the global MIB tree. The function receives a string containing either an object identifier (OID in dotted notation), or a symbolic node name. The provided OID (or name) can contain an instance identifier, which will be appended to the returned value.
If it receives an OID returns a string containing the provided OID, unaltered. If it receives a name that is not associated to any node in the global MIB tree, that is not associated to any node in LuaSNMP's global MIB tree, the function it returns nil plus an error message.

Examples:

Function call Returned value
mib.fullname("1.3.6.1.2.1.1.4") "iso.org.dod.internet.mgmt.mib-2.system.sysContact"
mib.fullname("1.3.6.1.2.1.1.4.0") "iso.org.dod.internet.mgmt.mib-2.system.sysContact.0"
mib.fullname("sysContact") "iso.org.dod.internet.mgmt.mib-2.system.sysContact"
mib.fullname("invalid") nil     mib: no such name
mib.name("5.0") "5.0"

oid, err = mib.oid(NODE)

Returns a string containing the object identifier associated with a MIB NODE. It receives a string containing a symbolic node name or an object identifier (OID in dotted notation). The provided node name may contain an instance identifier, which will be appended to the returned value. If the function receives an object identifier, the function returns a string containing the provided OID, unaltered. If it receives a node that is not associated to any node in the global MIB tree, it returns nil plus an error message.

Examples:

Function call Returned value
mib.oid ("sysContact") "1.3.6.1.2.1.1.4"
mib.oid ("sysContact.0") "1.3.6.1.2.1.1.4.0"
mib.oid ("1.3.6.1.2.1.1.4.0") "1.3.6.1.2.1.1.4.0"
mib.oid ("invalid") nil     mib: no such name

base, err = mib.oidbase(OID, LEN)

Returns a string containing the base object identifier of length LEN of the given OID. The function does not check whether the given OID is part of LuaSNMP's global MIB tree. This check can easily be incorporated with the following construct:

base, err = mib.oidbase(mib.oid(oid))

If the given OID has no a valid OID syntax or if the parameter LEN is missing, mib.oidbase  returns nil plus an error message.

result, err = mib.oidindex(OID, MASK)

Returns the index of an object identifier OID based on a given MASK. The function does not check whether the given OIDs are part of LuaSNMP's global MIB tree. If the OID or the MASK to not comply to the dotted notation, the function returns nil plus an error message.

leuwer@goofy:luasnmp$ lua -l snmp -i
> oid = snmp.mib.oid("ifSpeed")
> mask = snmp.mib.oid("ifTable")
> =oid
1.3.6.1.2.1.2.2.1.5
> =mask
1.3.6.1.2.1.2.2
> =snmp.mib.oidindex(oid,mask)
1.5
>
> return snmp.mib.oidindex(oid.."fail",mask)
nil     snmp: not an OID
>

result, err = mib.oidcompare(OID1, OID2)

Compares two object identifiers OID1 and OID2. The function does not check whether the given OIDs are part of LuaSNMP's global MIB tree. Return values:
OID1 <   OID2:   -1
OID1 == OID2:    0
OID2  >  OID2:    1

The function returns nil plus an error message, if any of the two OIDs doesn't have a valid OID syntax.

result, err = mib.oidlen(OID)

Returns the length of an OID, given as string. The length  is the number of subnodes.The function does not check whether the given OIDs are part of LuaSNMP's global MIB tree. If the given OID has no  valid OID syntax or if the parameter LEN is missing, mib.oidbase  returns nil plus an error message.

result, err = mib.oidtotable(OID)

Converts an OID given as string into an array of subnodes. The function does not check whether the given OIDs are part of LuaSNMP's global MIB tree. If the given OID has no valid OID syntax, the function returns nil plus an error message.

luasnmp$ lua -l snmp -e \
'table.foreach(snmp.mib.oidtotable(snmp.mib.oid("sysContact")),print)'
1       1
2       3
3       6
4       1
5       2
6       1
7       1
8       4

result, err = mib.isoid(OID)

Checks whether the OID given as string has a valid OID syntax. The function does not check whether the given OIDs are part of LuaSNMP's global MIB tree. It returns the given OID,  if the syntax is correct. If not, nil plus an error message is returned.

result, err = mib.description(NODE [, WIDTH [, BUFLEN]])

Retrieves the textual  description of a given NODE. The function receives a string containing either a symbolic node name or an object identifier (OID in dotted notation). It returns a string containing the description. If the parameter WIDTH is given, lines in the output string are wrapped after WIDTH characters. The default value for the width is 80 characters. If the optional parameter BUFLEN is given, the function allocates a buffer of the given length, otherwise the buffer is limited to 512 characters. If the buffer is too small the rest of the text is lost.
If the given NODE does not exist, the function returns nil plus an error message.


luasnmp$ lua -l snmp -e 'print(snmp.mib.description("sysContact"))'
sysContact OBJECT-TYPE  
  -- FROM       SNMPv2-MIB, RFC1213-MIB
  -- TEXTUAL CONVENTION DisplayString
  SYNTAX        OCTET STRING (0..255)
  DISPLAY-HINT  "255a"
  MAX-ACCESS    read-write
  STATUS        current
::= { iso(1) org(3) dod(6) internet(1) mgmt(2) mib-2(1) system(1) 4 }

luasnmp$ lua -l snmp -e 'print(snmp.mib.description("sysContact",40))'
sysContact OBJECT-TYPE
  -- FROM       SNMPv2-MIB, RFC1213-MIB
  -- TEXTUAL CONVENTION DisplayString
  SYNTAX        OCTET STRING (0..255)
  DISPLAY-HINT  "255a"
  MAX-ACCESS    read-write
  STATUS        current
::= { iso(1) org(3) dod(6) internet(1)
      mgmt(2) mib-2(1) system(1) 4 }

result, err = mib.access(NODE)

Retrieves the MAX-ACCESS property of a given MIB NODE. The function receives a string containing an object identifier (OID in dotted notation) or a symbolic node name, which may contain an instance identifier. It returns a  string containing one of the following values:

not-accessible
read-only
read-write
write-only
read-create

If the given node does not exist, the function returns nil plus an error message.

tcode, tname = mib.type(NODE)
tname = mib.typename(NODE)

Retrieves the TYPE property of a given MIB NODE. The function receives a string containing an object identifier (OID in dotted notation) or a symbolic node name, which may contain an instance identifier. The function returns 2 values, a number containing the numerical type code and a string containing the type in textual form.

The value TYPE_OTHER is returned, if no other basic type is associated with the specified MIB node. If the given node does not exist, the function returns nil plus an error message.

Refer to SNMP Data Types for details on types.

result, err = mib.successor(NODE)

Retrieves the list of immediate successors of a given MIB NODE. The function receives a string containing  an object identifier (OID in dotted notation), or a symbolic node name. It returns a table of strings containing the object identifiers of the immediate successors of the specified MIB node.
When no successors of the specified MIB node are found in the global MIB tree, mib.successor  returns nil plus the special error message "mib: end of mib".
If it receives a name or an object identifier that is not associated to any node in the global MIB tree,  mib.successor  returns nil plus an error message.

Note, that the function ignores any instant identifiers.

luasnmp$ lua -l snmp -i
> for _, oid in ipairs(mib.successor("ifEntry")) do
>>print(oid, mib.name(oid))
>>end
1.3.6.1.2.1.2.2.1.1     ifIndex
1.3.6.1.2.1.2.2.1.2     ifDescr
1.3.6.1.2.1.2.2.1.3     ifType
1.3.6.1.2.1.2.2.1.4     ifMtu
1.3.6.1.2.1.2.2.1.5     ifSpeed
1.3.6.1.2.1.2.2.1.6     ifPhysAddress
1.3.6.1.2.1.2.2.1.7     ifAdminStatus
1.3.6.1.2.1.2.2.1.8     ifOperStatus
1.3.6.1.2.1.2.2.1.9     ifLastChange
1.3.6.1.2.1.2.2.1.10    ifInOctets
1.3.6.1.2.1.2.2.1.11    ifInUcastPkts
1.3.6.1.2.1.2.2.1.12    ifInNUcastPkts
1.3.6.1.2.1.2.2.1.13    ifInDiscards
1.3.6.1.2.1.2.2.1.14    ifInErrors
1.3.6.1.2.1.2.2.1.15    ifInUnknownProtos
1.3.6.1.2.1.2.2.1.16    ifOutOctets
1.3.6.1.2.1.2.2.1.17    ifOutUcastPkts
1.3.6.1.2.1.2.2.1.18    ifOutNUcastPkts
1.3.6.1.2.1.2.2.1.19    ifOutDiscards
1.3.6.1.2.1.2.2.1.20    ifOutErrors
1.3.6.1.2.1.2.2.1.21    ifOutQLen
1.3.6.1.2.1.2.2.1.22    ifSpecific
>
> return mib.successor("ifSpeed")
nil     mib: end of mib
>
> return mib.successor("invalid")
nil     mib: no such name

result, err = mib.parent(NODE)

Retrieves the parent of a given MIB NODE. The function receives a string containing  an object identifier (OID in dotted notation), or a symbolic node name, and returns a string containing the object identifier of the parent of the specified MIB node.
When the specified MIB node has no defined parent, mib_parent  returns nil plus the special error message "mib: end of mib".
If it receives a name or an object identifier that is not associated to any node in the global MIB tree, mib.parent  returns nil plus an error message.

result, err = mib.enums(NODE)
result, err = mib.renums(NODE)

Retrieves the list of enumerations of a given MIB integer variable. It receives a string containing  an object identifier (OID in dotted notation), or an object name NODE and returns a list (table) of strings containing the enumerations defined for the MIB variable. The returned table is indexed by the integer values that the specified MIB variable can assume.
When the specified MIB variable has no defined enumerations, mib.enums  returns nil plus the special  error message "mib: bad type".
If it receives a symbolic name or an object identifier that is not associated to any object variable in the global MIB tree, mib.enums  or mib.renums  returns nil and an error message.

The function mib.enums  returns the enumeration values as a list of symbolic names. The function mib.renums  returns the enumeration values as a table with symbolic names as index. This table can then easily be used for a more readable way to set the values of varbinds with that enumeration type.

luasnmp$ lua -l snmp -i
> for nenum, senum in pairs(snmp.mib.enums("ifAdminStatus")) do
>> print(string.format("enum: %d => %s", nenum, senum))
>> end
enum: 1 => up
enum: 2 => down
enum: 3 => testing
>
> =snmp.mib.enums("sysContact")
nil     mib: bad type
>

luasnmp$ lua -l snmp -i
> for senum, nenum in pairs(snmp.mib.renums("ifAdminStatus")) do
>> print(string.format("enum: %s <= %d", senum, nenum))
>> end
enum: testing <= 3
enum: down <= 2
enum: up <= 1
>

result, err = mib.default(NODE)

Retrieves the default value of a given MIB NODE. It receives a string containing an object identifier (OID in dotted notation), or a symbolic object name  and returns the default value of this object. The type of the returned value depends on the type of the MIB object. When the specified MIB node has no default value, mib.default  returns nothing, even no error message.
If the function receives a name or an OID that is not associated to any object in the global MIB tree, it returns nil plus an error message.

result, err = mib.units(NODE)

Retrieves a list of units for the given MIB NODE. It receives a string containing an object identifier (OID in dotted notation), or a symbolic object name  and returns the units of this object as string. When the specified MIB node has no units, mib.units  returns nothing, even no error message.
If the function receives a name or an OID that is not associated to any object in the global MIB tree, it returns nil plus an error message.

result, err = mib.indexes(NODE)

Retrieves a list of OIDs indicating the indexes for the given MIB NODE, which typically should point to a table or a table entry.  It receives a string containing an object identifier (OID in dotted notation), or a symbolic object name  and returns the indexes of this object in a table as list.  When the specified MIB node has no indexes, mib.indexes  returns nothing, even no error message.
If the function receives a name or an OID that is not associated to any object in the global MIB tree, it returns nil plus an error message.

result, err = mib.augments(NODE)

Retrieves a list of OIDs indicating the indexes for the given MIB NODE, which typically should point to a table or a table entry.  It receives a string containing an object identifier (OID in dotted notation), or a symbolic object name  and returns a string containing the OID of the object that is augmented. When the specified MIB node does not augment any other object, mib.augments  returns nothing, even no error message.
If the function receives a name or an OID that is not associated to any object in the global MIB tree, it returns nil plus an error message.

result, err = mib.instance(ARG1, ARG2, ..., ARGn)

This is the same function as snmp.instance, just mapped to mib namespace.