SnmpKit.SnmpMgr.Multi (snmpkit v2.0.1)

High-performance concurrent multi-target SNMP operations.

This module provides efficient SNMP operations against multiple targets using direct UDP sending and centralized response correlation, eliminating GenServer bottlenecks while maintaining proper concurrency control.

Timeouts and retries

:timeout is a per-PDU timeout, :retries the number of re-sends of a timed-out PDU and :walk_timeout a cap on a whole walk; the model and the defaults are described in SnmpKit.SnmpMgr.Config. Options left out fall back to SnmpKit.SnmpMgr.Config.get/1.

Summary

Types

operation()

request()

result()

results()

target()

Functions

execute_mixed(operations, opts \\ [])

Executes mixed SNMP operations against multiple targets concurrently.

get_bulk_multi(targets_and_oids, opts \\ [])

Performs GETBULK operations against multiple targets concurrently.

get_multi(targets_and_oids, opts \\ [])

Performs GET operations against multiple targets concurrently.

walk_multi(targets_and_oids, opts \\ [])

Performs walk operations against multiple targets concurrently.

walk_table_multi(targets_and_tables, opts \\ [])

Performs table walk operations against multiple targets concurrently.

Types

operation()

@type operation() ::
  {:get | :get_bulk | :walk | :walk_table, target(), term()}
  | {:get | :get_bulk | :walk | :walk_table, target(), term(), keyword()}

request()

@type request() :: {target(), term()} | {target(), term(), keyword()}

result()

@type result() :: {:ok, term()} | {:error, term()}

results()

@type results() ::
  [result()]
  | [{target(), term(), result()}]
  | %{required({target(), term()}) => result()}

target()

@type target() :: term()

Functions

execute_mixed(operations, opts \\ [])

@spec execute_mixed(
  [operation()],
  keyword()
) :: [result()]

Executes mixed SNMP operations against multiple targets concurrently.

Parameters

operations - List of {operation, target, oid_or_args, opts} tuples where operation is :get, :get_bulk, :walk, or :walk_table
opts - Default options
- :timeout - Per-PDU timeout in milliseconds (default: the :timeout in SnmpKit.SnmpMgr.Config, 5000). Applied to all operations. Walk operations may require many PDUs.
- :retries - re-sends of a timed-out PDU (default: the :retries in SnmpKit.SnmpMgr.Config, 1)
- :max_concurrent - Maximum concurrent operations (default: 10)

Per-Operation Options

Each operation tuple can include individual options:

:timeout - Override per-PDU timeout for this specific operation
:max_repetitions - Override for bulk/walk operations
:community - Override SNMP community string

Timeout Behavior

GET/GETBULK: Single PDU timeout
WALK operations: Per-PDU timeout, may require many PDUs
Mixed operations with walks use :walk_timeout as the whole-walk cap

Examples

iex> operations = [
...>   {:get, "device1", "sysDescr.0", []},
...>   {:get_bulk, "switch1", "ifTable", [max_repetitions: 20]},
...>   {:walk, "router1", "system", []}
...> ]
iex> SnmpKit.SnmpMgr.Multi.execute_mixed(operations)
[
  {:ok, "Device 1 Description"},
  {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "eth0"}, ...]},
  {:ok, [{"1.3.6.1.2.1.1.1.0", "Router 1"}, ...]}
]

get_bulk_multi(targets_and_oids, opts \\ [])

@spec get_bulk_multi(
  [request()],
  keyword()
) :: results()

Performs GETBULK operations against multiple targets concurrently.

Parameters

targets_and_oids - List of {target, oid} or {target, oid, opts} tuples
opts - Default options applied to all requests
- :timeout - SNMP PDU timeout in milliseconds (default: the :timeout in SnmpKit.SnmpMgr.Config, 5000). How long to wait for each response
- :retries - re-sends of a timed-out PDU (default: the :retries in SnmpKit.SnmpMgr.Config, 1)
- :max_repetitions - Maximum repetitions for GetBulk (default: 30)
- :max_concurrent - Maximum concurrent requests (default: 10)

Per-Request Options

Individual requests can override call-level options:

:timeout - Override the default per-PDU timeout for this specific request
:max_repetitions - Override max repetitions for this request

Examples

iex> requests = [
...>   {"switch1", "ifTable"},
...>   {"switch2", "ifTable"}
...> ]
iex> SnmpKit.SnmpMgr.Multi.get_bulk_multi(requests, max_repetitions: 20)
[
  {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "eth0"}, ...]},
  {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "GigE0/1"}, ...]}
]

get_multi(targets_and_oids, opts \\ [])

@spec get_multi(
  [request()],
  keyword()
) :: results()

Performs GET operations against multiple targets concurrently.

Parameters

targets_and_oids - List of {target, oid} or {target, oid, opts} tuples
opts - Default options applied to all requests
- :timeout - SNMP PDU timeout in milliseconds (default: the :timeout in SnmpKit.SnmpMgr.Config, 5000). How long to wait for each response
- :retries - re-sends of a timed-out PDU (default: the :retries in SnmpKit.SnmpMgr.Config, 1)
- :max_concurrent - Maximum concurrent requests (default: 10)
- :return_format - Format of returned results (default: :list)
  - :list - Returns list of results in same order as input
  - :with_targets - Returns list of {target, oid, result} tuples
  - :map - Returns map with {target, oid} keys and result values

Per-Request Options

Individual requests can override call-level options by providing a third element:

{target, oid, opts} where opts can include:
- :timeout - Override the default per-PDU timeout for this specific request
- :community - Override SNMP community string
- :version - SNMP version (:v1 for get_multi only; GETBULK and the walks need :v2c or :v3 and answer {:error, {:unsupported_operation, :get_bulk_requires_v2c}})

Examples

iex> requests = [
...>   {"device1", "sysDescr.0"},
...>   {"device2", "sysUpTime.0"}
...> ]
iex> SnmpKit.SnmpMgr.Multi.get_multi(requests)
[
  {:ok, "Device 1 Description"},
  {:ok, 123456}
]

walk_multi(targets_and_oids, opts \\ [])

@spec walk_multi(
  [request()],
  keyword()
) :: results()

Performs walk operations against multiple targets concurrently.

A walk operation retrieves all OIDs under a given root OID by sending multiple GETBULK requests until the end of the MIB subtree is reached.

Parameters

targets_and_oids - List of {target, root_oid} or {target, root_oid, opts} tuples
opts - Default options applied to all requests
- :timeout - Per-PDU timeout in milliseconds (default: the :timeout in SnmpKit.SnmpMgr.Config, 5000). How long to wait for each GETBULK PDU response during the walk. A walk may require many PDUs, so total walk time can exceed this value.
- :retries - re-sends of a timed-out PDU (default: the :retries in SnmpKit.SnmpMgr.Config, 1)
- :walk_timeout - Whole-walk safety cap in milliseconds (default: max(timeout * 10, 1_200_000), at most 1_800_000)
- :max_repetitions - OIDs requested per GETBULK PDU (default: 30)
- :max_concurrent - Maximum concurrent walk operations (default: 10)

Per-Request Options

Individual walk requests can override call-level options:

:timeout - Override per-PDU timeout for this specific walk
:max_repetitions - Override max repetitions for this walk
:community - Override SNMP community string

Timeout Behavior

Each GETBULK PDU has its own timeout (per-PDU timeout)
Large tables may require 50-200+ PDUs to walk completely
Total walk time can be substantial: N_pdus × per_PDU_timeout
Operations are protected by :walk_timeout

Examples

iex> requests = [
...>   {"device1", "system"},
...>   {"device2", "interfaces"}
...> ]
iex> SnmpKit.SnmpMgr.Multi.walk_multi(requests)
[
  {:ok, [{"1.3.6.1.2.1.1.1.0", "Device 1"}, ...]},
  {:ok, [{"1.3.6.1.2.1.2.1.0", 24}, ...]}
]

walk_table_multi(targets_and_tables, opts \\ [])

@spec walk_table_multi(
  [request()],
  keyword()
) :: results()

Performs table walk operations against multiple targets concurrently.

Similar to walk_multi but optimized for SNMP table operations.

Parameters

targets_and_tables - List of {target, table_oid} or {target, table_oid, opts} tuples
opts - Default options applied to all requests
- :timeout - Per-PDU timeout in milliseconds (default: the :timeout in SnmpKit.SnmpMgr.Config, 5000). How long to wait for each GETBULK PDU response during the table walk.
- :retries - re-sends of a timed-out PDU (default: the :retries in SnmpKit.SnmpMgr.Config, 1)
- :walk_timeout - Whole-walk safety cap in milliseconds (default: max(timeout * 10, 1_200_000), at most 1_800_000)
- :max_repetitions - Rows requested per GETBULK PDU (default: 30)
- :max_concurrent - Maximum concurrent table walks (default: 10)

Per-Request Options

Individual table walk requests can override call-level options:

:timeout - Override per-PDU timeout for this specific table walk
:max_repetitions - Override max repetitions for this table

Examples

iex> requests = [
...>   {"switch1", "ifTable"},
...>   {"switch2", "ifTable"}
...> ]
iex> SnmpKit.SnmpMgr.Multi.walk_table_multi(requests)
[
  {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "eth0"}, ...]},
  {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "GigE0/1"}, ...]}
]