SNMP

Use the SNMP library in Lua to monitor OIDs obtained from an SNMP-enabled device's MIB file.

Note: In the SNMP model, Q-SYS acts as the SNMP Manager, while the device you intend to monitor runs an SNMP Agent that allows for monitoring.

SNMPSession.New

Create a new SNMP session.

Syntax

SNMPSession.New(type)

Arguments

type

SNMPSessionType.V2c : Instantiate an SNMP v2 session.

SNMPSessionType.V3 : Instantiate an SNMP v3 session.

Example

snmp_session = SNMPSession.New(SNMP.SessionType.v3)

setHostName

Specify the host to which to connect.

Syntax

setHostName("hostname")

Arguments

hostname : String. The target host name.

Example

snmp_session:setHostName("mydevice")

setAuthType

For SNMP v3 only, set the authorization type for the session.

Syntax

setAuthType(type)

Arguments

type

SNMP.AuthType.NoAuth : No authorization type and no privacy type.

SNMP.AuthType.AuthNoPriv : Authorization with no privacy.

SNMP.AuthType.AuthPriv : Both authorization and privacy.

Example

snmp_session:setAuthType(SNMP.AuthType.AuthNoPriv)

setAuthProt

For SNMP v3 only, set the authorization protocol for the session.

Syntax

setAuthProt(type)

Arguments

type

SNMP.AuthProtocol.NoAuth : Disable the authorization protocol.

SNMP.AuthProtocol.MD5 : Enable the MD5 authorization protocol.

SNMP.AuthProtocol.SHA : Enable the SHA authorization protocol.

Example

snmp_session:setAuthProt(SNMP.AuthProtocol.MD5)

setPrivProt

For SNMP v3 only, set the privacy protocol for the session.

Syntax

setPrivProt(type)

Arguments

type

SNMP.PrivProtocol.NoPriv : Disable the privacy protocol.

SNMP.PrivProtocol.AES : Enable the AES privacy protocol.

SNMP.PrivProtocol.DES : Enable the DES privacy protocol.

Example

snmp_session:setPrivProt(SNMP.PrivProtocol.DES)

setUserName

For SNMP v3 only, set the user name for the session.

Syntax

setUserName("username")

Arguments

username : String. The user name for the session.

Example

snmp_session:setUserName("MD5User")

setPassPhrase

For SNMP v3 only, set the authorization pass phrase for the session.

Syntax

setPassPhrase("passphrase")

Arguments

passphrase : String. The pass phrase for the corresponding user name.

Example

snmp_session:setPassPhrase("My Demo Password")

setPrivPassPhrase

For SNMP v3 only, set the privacy pass phrase for the session.

Syntax

setPrivPassPhrase("privpass")

Arguments

privpass : String. The privacy pass phrase for the session.

Example

snmp_session:setPrivPassPhrase("password")

setCommunity

For SNMP v2 sessions only, set the community name for the session.

Syntax

setCommunity("community")

Arguments

community : String. The community name for the session.

Example

snmp_session:setCommunity("demopublic")

startSession

Initiate the connection to the corresponding session.

Syntax

startSession()

Example

snmp_session:startSession()

getRequest

Request an object ID (OID) and pass the response to a Lua callback.

Syntax

getRequest("oid", callback)

Arguments

oid : String. The object ID to request.

callback : The Lua callback to which to pass the response.

Example

function myCallback(dataout)
	  for k,v in pairs(dataout) do
	    print(k,v)
	  end
  end

  snmp_session:getRequest(".1.3.6.1.2.1.1.3.0", myCallback)

setRequest

Set a new value for a specified OID.

Syntax

setRequest("oid", "new_value", type, callback)

Arguments

oid : String. The object ID to set in the request.

new_value : String. The new value to which to set the specified object ID.

type

SNMP.SNMPDataType.unknown

SNMP.SNMPDataType.integer32

SNMP.SNMPDataType.unsigned32

SNMP.SNMPDataType.unsigned_integer32

SNMP.SNMPDataType.timeticks

SNMP.SNMPDataType.ip_address

SNMP.SNMPDataType.object_id

SNMP.SNMPDataType.octet_string

SNMP.SNMPDataType.hex

SNMP.SNMPDataType.decimal

SNMP.SNMPDataType.bit_string

SNMP.SNMPDataType.integer64

SNMP.SNMPDataType.unsigned64

SNMP.SNMPDataType.float32

SNMP.SNMPDataType.double64

callback : The Lua callback to which to pass the response.

Example

function myCallback(dataout)
	  for k,v in pairs(dataout) do
	    print(k,v)
	  end
  end

  snmp_session:setRequest(".1.3.6.1.2.1.1.5.0", "new_switch_name", SNMP.SNMPDataType.octet_string, myCallback)

EventHandler

Assign the Lua callback for successful SNMP events.

Responses

RequestID : Integer. The request ID for bookkeeping purposes.

OID : String. The object ID for the response.

Value : String. The string representation for the current state of the object ID.

HostName : String. The host name for the response.

Example

snmp_object.EventHandler = function(response)
	print(response.OID)
	print(response.Value)
end

ErrorHandler

Assign the Lua callback for unsuccessful SNMP events.

Responses

Error : String. The error message for the request.

Example

snmp_object.ErrorHandler = function(response)
	print(response.Error)
end