Search documentation of snmpkit

# SnmpKit.SnmpMgr.MultiV2 (snmpkit v1.3.17)

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.

# Summary

## 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.

# Functions

# execute_mixed(operations, opts \\ [])

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` - Global options
  - `:timeout` - Per-PDU timeout in milliseconds (default: 30000) Applied to all operations. Walk operations may require many PDUs.
  - `: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 20-minute task timeout cap
- Operations without walks use shorter task timeout protection

## Examples

    iex> operations = [
    ...>   {:get, "device1", "sysDescr.0", []},
    ...>   {:get_bulk, "switch1", "ifTable", [max_repetitions: 20]},
    ...>   {:walk, "router1", "system", []}
    ...> ]
    iex> SnmpKit.SnmpMgr.MultiV2.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 \\ [])

Performs GETBULK operations against multiple targets concurrently.

## Parameters

- `targets_and_oids` - List of {target, oid} or {target, oid, opts} tuples
- `opts` - Global options applied to all requests
  - `:timeout` - SNMP PDU timeout in milliseconds (default: 10000) How long to wait for each individual SNMP response
  - `:max_repetitions` - Maximum repetitions for GetBulk (default: 30)
  - `:max_concurrent` - Maximum concurrent requests (default: 10)

## Per-Request Options

Individual requests can override global options:

- `:timeout` - Override global timeout for this specific request
- `:max_repetitions` - Override max repetitions for this request

## Examples

    iex> requests = [
    ...>   {"switch1", "ifTable"},
    ...>   {"switch2", "ifTable"}
    ...> ]
    iex> SnmpKit.SnmpMgr.MultiV2.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 \\ [])

Performs GET operations against multiple targets concurrently.

## Parameters

- `targets_and_oids` - List of {target, oid} or {target, oid, opts} tuples
- `opts` - Global options applied to all requests
  - `:timeout` - SNMP PDU timeout in milliseconds (default: 10000) How long to wait for each individual SNMP response
  - `: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 global options by providing a third element:

- `{target, oid, opts}` where opts can include:
  - `:timeout` - Override global timeout for this specific request
  - `:community` - Override SNMP community string
  - `:version` - Override SNMP version (:v1, :v2c)

## Examples

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

# walk_multi(targets_and_oids, opts \\ [])

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` - Global options applied to all requests
  - `:timeout` - Per-PDU timeout in milliseconds (default: 30000) How long to wait for each GETBULK PDU response during the walk. A walk may require many PDUs, so total walk time = N_pdus × timeout. Task timeout is capped at 20 minutes to prevent infinite hangs.
  - `: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 global 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 20-minute maximum task timeout

## Examples

    iex> requests = [
    ...>   {"device1", "system"},
    ...>   {"device2", "interfaces"}
    ...> ]
    iex> SnmpKit.SnmpMgr.MultiV2.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 \\ [])

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` - Global options applied to all requests
  - `:timeout` - Per-PDU timeout in milliseconds (default: 50000) How long to wait for each GETBULK PDU response during table walk. Table walks often require more PDUs than regular walks.
  - `: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 global 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.MultiV2.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"}, ...]}
    ]