SnmpKit.SnmpMgr.Core (snmpkit v2.0.1)

Core SNMP operations using Erlang's SNMP PDU functions directly.

This module handles the low-level SNMP PDU encoding/decoding and UDP communication without requiring the heavyweight :snmpm manager process.

Timeout Behavior

All functions in this module use a single timeout parameter that controls the SNMP PDU timeout - how long to wait for a response to each individual SNMP packet sent to the target device.

  • Default timeout: the :timeout in SnmpKit.SnmpMgr.Config (5000 ms), which also documents :retries and :walk_timeout
  • Timeout applies to: Each individual SNMP PDU (GET, SET, GETBULK, etc.)
  • Not applicable to: Multi-PDU operations (use walk functions for those)

For operations that may require multiple PDUs (like walking large tables), consider using the higher-level walk functions in SnmpKit.SnmpMgr.Multi which handle multi-PDU timeouts appropriately.

Summary

Types

oid()
opts()
snmp_result()
target()

Functions

parse_oid(oid)

Parses and normalizes an OID to internal list format.

send_get_bulk_request(target, oid, opts \\ [])

Sends an SNMP GETBULK request (SNMPv2c only).

send_get_next_request(target, oid, opts \\ [])

Sends a GETNEXT request to retrieve the next OID in the MIB tree.

send_get_request_with_type(target, oid, opts \\ [])

Sends a GET request and returns the result in 3-tuple format.

send_get_varbinds(target, oids, opts \\ [])

Retrieves several objects from one target in a single GET PDU.

send_set_request(target, oid, value, opts \\ [])

Sends an SNMP SET request and returns the response.

send_set_varbinds(target, pairs, opts \\ [])

Sets several objects on one target in a single SET PDU. pairs are {oid, value} with the same value forms send_set_request/4 accepts.

Types

oid()

@type oid() :: binary() | [non_neg_integer()]

opts()

@type opts() :: keyword()

snmp_result()

@type snmp_result() :: {:ok, term()} | {:error, atom() | tuple()}

target()

@type target() :: binary() | tuple() | map()

Functions

parse_oid(oid)

@spec parse_oid(oid()) :: {:ok, [non_neg_integer()]} | {:error, term()}

Parses and normalizes an OID to internal list format.

Converts external OID input (string or list) to internal list of integers format. This function establishes the API boundary - all external input is converted to internal list format here.

send_get_bulk_request(target, oid, opts \\ [])

@spec send_get_bulk_request(target(), oid(), opts()) :: snmp_result()

Sends an SNMP GETBULK request (SNMPv2c only).

GETBULK is more efficient than multiple GETNEXT operations for retrieving multiple consecutive OIDs.

Parameters

  • target - SNMP target (host, "host:port", or target map)
  • oid - Starting OID for bulk retrieval
  • opts - Request options
    • :timeout - SNMP PDU timeout in milliseconds (default: 5000, see SnmpKit.SnmpMgr.Config)
    • :max_repetitions - Maximum number of OIDs to retrieve (default: 30)
    • :community - SNMP community string (default: "public")
    • :version - SNMP version (must be :v2c) (default: :v2c)

send_get_next_request(target, oid, opts \\ [])

@spec send_get_next_request(target(), oid(), opts()) :: snmp_result()

Sends a GETNEXT request to retrieve the next OID in the MIB tree.

Now uses the proper SnmpKit.SnmpLib.Manager.get_next/3 function which handles version-specific logic (GETNEXT for v1, GETBULK for v2c+) correctly.

send_get_request_with_type(target, oid, opts \\ [])

@spec send_get_request_with_type(target(), oid(), opts()) ::
  {:ok, {String.t(), atom(), any()}} | {:error, any()}

Sends a GET request and returns the result in 3-tuple format.

This function returns {oid_string, type, value} for consistency with other operations like walk, bulk, etc.

send_get_varbinds(target, oids, opts \\ [])

@spec send_get_varbinds(target(), [oid()], opts()) ::
  {:ok, [{String.t(), atom(), any()}]} | {:error, term()}

Retrieves several objects from one target in a single GET PDU.

Returns {:ok, [{oid_string, type, value}]} in request order. SNMPv2c exceptions are kept per element as the type (:no_such_object, :no_such_instance) with a nil value.

send_set_request(target, oid, value, opts \\ [])

@spec send_set_request(target(), oid(), term(), opts()) :: snmp_result()

Sends an SNMP SET request and returns the response.

Parameters

  • target - SNMP target (host, "host:port", or target map)
  • oid - Object identifier to set
  • value - Value to set (will be encoded based on type)
  • opts - Request options
    • :timeout - SNMP PDU timeout in milliseconds (default: 5000, see SnmpKit.SnmpMgr.Config)
    • :community - SNMP community string (default: "public")
    • :version - SNMP version (:v1, :v2c) (default: :v2c)

send_set_varbinds(target, pairs, opts \\ [])

@spec send_set_varbinds(target(), [{oid(), any()}], opts()) ::
  {:ok, :success} | {:error, term()}

Sets several objects on one target in a single SET PDU. pairs are {oid, value} with the same value forms send_set_request/4 accepts.