Object Names

Most functions in LuaSNMP accept either object identifiers in pseudo-numerical dot-notation or symbolic object names  

Here are some basic rules:

Data Types

LuaSNMP maps SNMP data types to Lua basic types as specified in the table below. SNMP basic data types are associated to a set of numerical "codes". These numerical codes are used by the LuaSNMP functions when identifying the SNMP data type of a given variable instance value. Additionally LuaSNMP maintains a database to map the numerical codes to textual type names.

SNMP Type LuaSNMP Code Lua Type Representation
OBJECT IDENTIFIER snmp.TYPE_OBJID (1) string Decimal numbers separated by dots (dotted notation). e.g.: "1.3.6.1.2.1.1.5"
OCTET STRING snmp.TYPE_OCTETSTR (2) string Hexadecimal numbers (00 to ff) separated by colons.
e.g.: "00:00:80:a4:32:f3"
INTEGER snmp.TYPE_INTEGER (3) number  
NetworkAddress snmp.TYPE_NETADDR (4) string Decimal numbers (0 to 255) separated by dots (dotted notation).
e.g.: "139.82.95.11"
IpAddress snmp.TYPE_IPADDR (5) string Similar to NetworkAddress.
Counter snmp.TYPE_COUNTER (6) number  
Gauge32 snmp.TYPE_GAUGE (7) number  
TimeTicks snmp.TYPE_TIMETICKS (8) table A table representing a record structure with fields: ticks (raw value), days, hours, minutes, seconds e deciseconds. Each field contains a numerical value.
Opaque snmp.TYPE_OPAQUE (9) string Similar to OCTET STRING.
NULL snmp.TYPE_NULL (10) nil nil
Counter64 snmp.TYPE_COUNTER64 (11) number  
Bitstring snmp.TYPE_BITSTRING (12) string Binary number, e.g. "10010001"
NsapAddress snmp.TYPE_NSAPADDRESS(13) string
UInteger snmp.TYPE_UINTEGER (14) number s
Uinteger32 snmp.TYPE_UNSIGNED32 (15) number
Integer32 snmp.TYPE_INTEGER32 (16) number
Opaque: Float  snmp.TYPE_FLOAT (120) number
Opaque: Double snmp.TYPE_DOUBLE (121) number
Opaque: Integer64 snmp.TYPE_INTEGER64 (122) number
Opaque: Unsigned64 snmp.TYPE_UNSIGNED64 (123) number
Special type values
NO SUCH OBJECT snmp.NOSUCHOBJECT   = 128
NO SUCH INSTANCE snmp.NOSUCHINSTANCE = 129
END OF MIB VIEW snmp.ENDOFMIBVIEW   = 130

Varbinds

General

SNMP operations are defined on a list of MIB variable instances called a varbind list. Each element of a varbind list - a varbind element - describes a specific MIB variable instance. A varbind element specifies three MIB instance attributes: its object identifier, its data type and its value.

LuaSNMP represents a varbind list as a table containing varbind elements indexed by consecutive numerical values, starting with 1. A varbind element is represented as a table containing the values of the three MIB instance attributes. The strings "oid", "type" and "value" index the three attributes of a varbind table. LuaSNMP represents the values of the varbind attributes as follows:

oid - a string containing the object identifier that identifies the MIB instance.

type - the numerical code associated by LuaMan to the SNMP data type of the MIB instance, as specified in the table above (Data Types).

value- the value of the MIB instance, represented as specified in the table above (Data Types).

The following example illustrates a LuaSNMP representation of a varbind list:

vlist = {
 {oid = "1.3.6.1.2.1.1.4.0", type = TYPE_DISPLAY, value = "Lua"},
 {oid = "1.3.6.1.2.1.1.6.0", type = TYPE_DISPLAY, value = "Program" }
}

When a previously loaded MIB module contains the description of a given MIB variable, LuaSNMP allows a management application to use this variable's MIB label instead of its object identifier, and also to omit the type attribute, as shown in the example below: 

  vb = {oid = "sysContact.0", value = "Ana"}

A management application can also omit the value attribute when specifying varbind tables for retrieving - or getting - the values of MIB instances. LuaMan functions, however, will always return fully specified varbind tables.

It is important to note that varbind tables resulting from SNMPv2 operations can signal exception, or error, conditions (NO SUCH OBJECT, NO SUCH INSTANCE, END OF MIB VIEW) in their type attribute. LuaSNMP represents these exception conditions with the numerical codes snmp.NOSUCHOBJECT, snmp.NOSUCHINSTANCE and snmp.ENDOFMIBVIEW.

Varbind Metamethods

Every varbind element returned by  LuaSNMP has a metatable assigned. This metatable allows the following special operation on varbind elements:

Creation of varbind elements

A varbind element can be created using the function snmp.newvar(NAME, VALUE). This function returns a new varbind element as Lua table with approriate metamethods set. 

leuwer@goofy:luasnmp$ lua -l snmp -i
> vb1=snmp.newvar("ifSpeed.1", 1000)
> vb2=snmp.newvar("sysContact.0", "atHome")
> vb3=snmp.newvar("ifName.2", "Ethernet")
> vb4=snmp.newvar("ifSpeed.2", 2000)
Conversion to string: 

When the function tostring(vb) is applied to a varbind element, it returns a printable string representation of the varbind element.

> print(tostring(vb1))
IF-MIB::ifSpeed.1 = Gauge32: 1000
> print(vb2)
SNMPv2-MIB::sysContact.0 = STRING: atHome
> print(vb3)
IF-MIB::ifName.2 = STRING: Ethernet
> print(tostring(vb4))
IF-MIB::ifSpeed.2 = Gauge32: 2000
Comparision of varbind elements

A compare operation on varbind elements compares their values. Note that the comparison is performed on equivalent Lua type (see Data Types above). Comparing varbind elements with values of different Lua types leads to an error.

> =vb1<vb4
true
> =vb1<=vb4
true
> =vb1>vb4
false
> =vb2<vb3
false
> =vb2>vb3
true
> =vb1 < vb2
./snmp.lua:316: attempt to compare number with string
stack traceback:
        ./snmp.lua:316: in function <./snmp.lua:316>
        stdin:1: in main chunk
        [C]: ?
Concatenation of varbind elements

Applying the concatenation operator on varbind elements creates a varbind list. Any number of varbinds can be concatenated. Concatenation a varbind element and a varbind list creates a new varbind list which contains the varbind element and all elements of the varbind list.

> vlist = vb1..vb2..vb3
> table.foreach(vlist, print)
1       IF-MIB::ifSpeed.1 = Gauge32: 1000
2       SNMPv2-MIB::sysContact.0 = STRING: atHome
3       IF-MIB::ifName.2 = STRING: Ethernet
>
om

SNMP Sessions

Similarly to other SNMP APIs, LuaSNMP implements the concept of SNMP sessions. Before invoking SNMP operations on an SNMP peer, a management application must create, or open, an SNMP session. An SNMP session is a special object that stores the configuration parameters that control the protocol interactions with an SNMP peer. These configuration parameters include the IP address of the SNMP peer, the protocol version to be used and authentication information. All invocations of SNMP operations must specify an SNMP session.

When creating an SNMP session, an application can also define default callback functions for receiving responses to asynchronous SNMP operations and for handling notifications (trap and inform messages) sent by the associated peer.

The configuration parameters stored in a LuaSNMP session are described below.

peer = STRING

Defines the network (IP) address of the associated SNMP peer, and can be provided either as an IP address in dotted notation (e.g. "139.82.95.11") or as a host name that can be translated to an IP address.

The default value for this parameter is "0.0.0.0", and indicates an SNMP session that is not associated to a specific peer. This kind of "unassociated" SNMP sessions can be used for receiving all notifications (traps and informs) sent by the SNMP agents and managers on the network (see configuration parameters trap and inform). Note, however, that SNMP operations can only be invoked for SNMP sessions associated to specific peers.

version = NUMBER

Defines the SNMP protocol version to be used when interacting with the SNMP peer associated to the session. LuaSNMP supports SNMPv1, SNMPv2C and SNMPv3. A default value can be defined with the defCommunity configuration directive in snmp.conf. The default value for this parameter is snmp.SNMPv2C. LuaSNMP provides the following constants to define the session's version: 

community = STRING

Defines the community string to be used for authenticating the SNMP messages sent to the associated peer. A default value can be defined with the defVersion configuration directive in snmp.conf. The default value for this parameter is "public". The community is only used for SNMPv1 and SNMPv2C

port = NUMBER

Defines the UDP port used by the associated peer for receiving SNMP requests. A default value can be defined via the defaultPort configuration directive in snmp.conf. See the Net-SNMP manual page snmp.conf (5) for details. The default value for this parameter is 161.

retries = NUMBER

Defines the maximum number of retransmissions of an SNMP message. The default value is 5.

timeout = NUMBER

Defines the time (in seconds) to wait for a response to an SNMP request. In order to avoid congestion problems, every retransmission of a given SNMP request will double the previous timeout value. The default value for this parameter is 1.

callback =FUNCTION

This parameter defines a default user function to be invoked when a response to an asynchronous SNMP operation is received, or when an asynchronous request times out.
Note, however, that an application can define a specific function for processing the response to a given asynchronous request. In this case, this specific function overrides the default callback function configured for the session.
The default value for this parameter is nil, indicating that no default function for handling asynchronous responses is defined for the session.

trap = FUNCTION

This parameter defines a user function to be invoked when a trap message is received. Note that when a trap message is received, LuaSNMP invokes the trap handling functions specified for all SNMP sessions associated to the originating agent, and also the trap handling functions specified for "unassociated" sessions (peer = "0.0.0.0"). 
The default value for this parameter is nil, indicating that no trap handling function is defined for the session.

Note, that the trap callback function is also invoked for solicited traps = informs.
See Trap Handling for more details on trap handling in LuaSNMP.

user = STRING

This parameter defines the user name to be used during SNMP version 3 USM based  authentication. A default value can be specified using the defSecurityName configuration directive in snmp.conf. See the Net-SNMP manual page snmp.conf (5) for details. 

password = STRING 
autPassphrase = STRING

This parameter defines the pass phrase to be used during SNMP version 3 USM based authentication. A default value can be specified using the defAuthPassphrase or defPassphrase configuration directives in snmp.conf. See the Net-SNMP manual page snmp.conf (5) for details. 

Note, that password is used as the pass phrase for both authentication and encryption if no dedicated pass phrase is specified for encryption.

authType = STRING

This parameter defines the authentication method to be used for SNMP version 3 authentication. Possible values are "MD5" or "SHA". A default value can be specified using the defAuthType configuration directive in snmp.conf. If no authentication method is defined LuaSNMP assumes "MD5" as default value.

privType = STRING

This parameter defines the encryption method to be used for SNMP version 3 PDU encryption. Possible values are "DES" or "AES". A default value can be specified using the defPrivType in snmp.conf. If no authentication method is defined LuaSNMP assumes "DES" as default value.

privPassphrase = STRING

This parameter defines the pass phrase to be used during SNMP version 3 PDU encryption.  A default value can be specified using the defPrivPassphrase or defPassphrase configuration directives in snmp.conf. See the Net-SNMP manual page snmp.conf (5) for details. 

Note, that password is used as the pass phrase for both authentication and encryption if no dedicated pass phrase is specified for encryption.

securityLevel = STRING

Defines the security level to be used in SNMP version 3. The parameter can take the following values:

"noAuthNoPriv" - LuaSNMP does not require authentication nor does it perform encryption

"authNoPriv" - LuaSNMP requires authentication but does NOT perform encryption.

"authPriv" - LuaSNMP requires authentication AND performs encryption

A default value can be defined using the defSecurityLevel configuration directive in snmp.conf. See the Net-SNMP manual page snmp.conf (5) for details. 
If no security level is defined during session creation and there is no configuration available via snmp.conf, LuaSNMP defines "authNoPriv" as default value.

includeroot = BOOLEAN

This parameter defines whether the SNMP access function walk(NODE) shall include the given NODE. Normally, the walk starts with the successor of the given NODE. The default value is false.

sprintvar = FUNCTION

This parameter instructs LuaSNMP to use the given FUNCTION to convert varbind elements to readable strings. 

sprintval = FUNCTION

This parameter instructs LuaSNMP to use the given FUNCTION to convert varbind values to readable strings. 

context = STRING

This parameter defines the context to which this session shall have access. Defaults to an empty context "".

contextID = STRING

This parameter sets the context engineID used for SNMPv3 REQUEST messages scopedPdu.   If not specified, this will default to the authoritative engineID.

engineID = STRING

This parameter sets  the  authoritative  (security)  engineID  used  for  SNMPv3 REQUEST  messages.   It  is  typically  not necessary to specify this, as it will usually be discovered automatically.

engineBoots = STRING

This parameter is not (yet) supported. It's typically not required because this value is automatically discovered.

engineTime = STRING

This parameter is not (yet) supported. It's typically not required because this value is automatically discovered.

Trap Handling

LuaSNMP handles traps via the snmptrapd from the NetSNMP library using the traphandle directive in snmptrapd.conf(5).  

In order to capture traps in this way you have to configure the script trapd.lua provided with LuaSNMP to handle  traps via the traphandle directive. Insert the following line into snmptrapd.conf:

traphandle default PATH_TO_LUA/lua50 PATH_TO_TRAPD/trapd.lua [FWDPORT]

The script trapd.lua simply forwards all information received by snmptrapd to LuaSNMP using a UDP socket with localhost on port 6000. In order to change the port, set the environment variable  LUASNMP_TRAPDPORT to the desired port number and provide the same number in the traphandle directive in snmptrapd.conf.

Note, that for informs the response to the inform message is sent AFTER trapd.lua has finished.