#snmp API reference

An SNMP v1 / v2c client and agent (RFC 1157 / RFC 3416), over UDP with community-string authentication. The client queries an agent with GET / GETNEXT / SET / walk; the agent (server) answers those for a MIB you supply - a hardware simulator, or a way to expose an app's metrics over SNMP. The wire messages are ASN.1 BER, built and parsed with the asn1 library; the transport is net UDP. No SNMPv3 / USM (that is the security model a later tier would add).

Import with import "snmp.j" as snmp;. See the snmp guide for prose and examples.

#Functions

#snmp.agent(community as string, version as int, bindings as list of Varbind)

Build an agent (server) that answers GET / GETNEXT / SET for a MIB. Build the bindings with varbind / intVar / stringVar / oidVar; each is one OID the agent serves.

Parameters

• community {string} - the community string the agent accepts
• version {int} - snmp.VERSION1 or snmp.VERSION2C
• bindings {list of Varbind} - the MIB

Returns {Agent} - the configured agent

#snmp.client(host as string, community as string)

Construct a client for an agent, using UDP port 161, SNMP v2c, a 2s timeout, and one retry.

Parameters

• host {string} - the agent host or IP
• community {string} - the community string

Returns {Client} - the configured client

#snmp.clientWith(address as string, community as string, version as int, timeoutMs as int, retries as int)

Construct a client with full control over the endpoint and timing.

Parameters

• address {string} - the agent as "host:port"
• community {string} - the community string
• version {int} - snmp.VERSION1 or snmp.VERSION2C
• timeoutMs {int} - the per-attempt receive timeout, in milliseconds
• retries {int} - the number of extra attempts after the first

Returns {Client} - the configured client

#snmp.get(c as Client, oids as list of string)

GET the values of one or more OIDs.

Parameters

• c {Client} - the agent client
• oids {list of string} - the OIDs to fetch

Returns {list of Varbind} - the returned bindings

Throws

• {} - snmp if the agent reports an error, or does not answer

#snmp.getNext(c as Client, oids as list of string)

GETNEXT: fetch the binding lexically following each OID (the walk primitive).

Parameters

• c {Client} - the agent client
• oids {list of string} - the starting OIDs

Returns {list of Varbind} - the returned bindings

Throws

• {} - snmp if the agent reports an error, or does not answer

#snmp.intVar(oid as string, n as int)

Build an integer-valued binding for snmp.set.

Parameters

• oid {string} - the object identifier, dotted
• n {int} - the integer value

Returns {Varbind} - the binding

#snmp.oidVar(oid as string, target as string)

Build an OID-valued binding for snmp.set.

Parameters

• oid {string} - the object identifier, dotted
• target {string} - the OID value, dotted

Returns {Varbind} - the binding

#snmp.serve(a as Agent, address as string)

Bind address ("host:port", e.g. ":161") and serve requests forever. Blocks; run it as the program's main loop, or in a spawn. A request with the wrong community, or a malformed datagram, is dropped silently (as a real agent does). To serve with a shutdown control, bind the socket yourself and use serveOn.

Parameters

• a {Agent} - the agent to serve
• address {string} - the UDP bind address

Throws

• {} - snmp if the address cannot be bound

#snmp.serveOn(a as Agent, socket as net.UDPSocket, stop as channel of bool)

Serve requests on an already-bound UDP socket until a shutdown is signalled. Useful for embedding an agent beside a client in one program (bind first, then spawn this, so there is no bind race). To stop it, channel.send($stop, true) (a capacity >= 1 channel); the loop returns within SHUTDOWN_POLL_MS. task.wait the spawned handle afterwards for a graceful join. The caller owns the socket's lifetime; a request with the wrong community or a malformed datagram is dropped silently.

Parameters

• a {Agent} - the agent to serve
• socket {net.UDPSocket} - a bound UDP socket
• stop {channel of bool} - a value on this channel stops the loop

#snmp.set(c as Client, varbinds as list of Varbind)

SET one or more bindings (build them with intVar / stringVar / oidVar).

Parameters

• c {Client} - the agent client
• varbinds {list of Varbind} - the bindings to write

Returns {list of Varbind} - the agent's echoed bindings

Throws

• {} - snmp if the agent reports an error, or does not answer

#snmp.stringVar(oid as string, s as string)

Build an octet-string-valued binding for snmp.set.

Parameters

• oid {string} - the object identifier, dotted
• s {string} - the string value

Returns {Varbind} - the binding

#snmp.varbind(oid as string, type as string, value as string, number as int)

Build a binding of any SNMP type (for a SET, or a MIB entry served by an agent). type is a value type name (see Varbind); number is used for the numeric types, value for the string / oid / ipAddress types.

Parameters

• oid {string} - the object identifier, dotted
• type {string} - the SNMP value type name
• value {string} - the string / oid / ipAddress rendering
• number {int} - the integer for a numeric type

Returns {Varbind} - the binding

#snmp.walk(c as Client, rootOid as string)

Walk a subtree: repeated GETNEXT from rootOid until the returned OID leaves the subtree or the agent signals endOfMibView.

Parameters

• c {Client} - the agent client
• rootOid {string} - the subtree root OID, dotted

Returns {list of Varbind} - every binding under the subtree, in order

Throws

• {} - snmp if the agent reports an error, does not answer, or does not advance

#Structs

#snmp.Agent

An SNMP agent (server): a community, a protocol version, and a MIB - the set of bindings it answers for. Build one with snmp.agent and serve it with snmp.serve.

#snmp.Client

A configured SNMP agent endpoint.

#snmp.Varbind

One variable binding: an OID and its value. On a returned binding, type is the SNMP value type ("integer", "octetString", "oid", "null", "counter32", "gauge32", "timeTicks", "ipAddress", "counter64", "opaque", or the exception "noSuchObject" / "noSuchInstance" / "endOfMibView"); value is a string rendering, and number holds the integer for a numeric type (0 otherwise).

#Constants