Search documentation of snmpkit

# SnmpKit.SnmpMgr.Multi (snmpkit v1.2.0)

Concurrent multi-target SNMP operations.

Provides functions to perform SNMP operations against multiple targets concurrently, with configurable timeouts and error handling.

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

monitor(targets_and_oids, callback, opts \\ [])

Monitors multiple devices for changes by polling at regular intervals.

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.

Allows different operation types per target for maximum flexibility.

## Parameters

- `operations` - List of {operation, target, oid_or_args, opts} tuples
- `opts` - Global options

## Examples

    iex> operations = [
    ...>   {:get, "device1", "sysDescr.0", []},
    ...>   {:get_bulk, "switch1", "ifTable", [max_repetitions: 20]},
    ...>   {:walk, "router1", "system", [version: :v2c]}
    ...> ]

    # Default list format
    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"}, ...]}
    ]

    # Note: execute_mixed handles different operation types, so return_format
    # is not applicable here as operations have different target/args structures

# 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
  - `: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

## Examples

    iex> requests = [
    ...>   {"switch1", "ifTable"},
    ...>   {"switch2", "ifTable"},
    ...>   {"router1", "ipRouteTable"}
    ...> ]

    # Default list format
    iex> SnmpKit.SnmpMgr.Multi.get_bulk_multi(requests, max_repetitions: 20)
    [
      {:ok, [{[1,3,6,1,2,1,2,2,1,2,1], :octet_string, "eth0"}, ...]},
      {:ok, [{[1,3,6,1,2,1,2,2,1,2,1], :octet_string, "GigE0/1"}, ...]},
      {:error, :timeout}
    ]

    # With targets format
    iex> SnmpKit.SnmpMgr.Multi.get_bulk_multi(requests, return_format: :with_targets, max_repetitions: 20)
    [
      {"switch1", "ifTable", {:ok, [{[1,3,6,1,2,1,2,2,1,2,1], :octet_string, "eth0"}, ...]}},
      {"switch2", "ifTable", {:ok, [{[1,3,6,1,2,1,2,2,1,2,1], :octet_string, "GigE0/1"}, ...]}},
      {"router1", "ipRouteTable", {:error, :timeout}}
    ]

    # Map format
    iex> SnmpKit.SnmpMgr.Multi.get_bulk_multi(requests, return_format: :map, max_repetitions: 20)
    %{
      {"switch1", "ifTable"} => {:ok, [{[1,3,6,1,2,1,2,2,1,2,1], :octet_string, "eth0"}, ...]},
      {"switch2", "ifTable"} => {:ok, [{[1,3,6,1,2,1,2,2,1,2,1], :octet_string, "GigE0/1"}, ...]},
      {"router1", "ipRouteTable"} => {:error, :timeout}
    }

# 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
  - `: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

## Examples

    iex> requests = [
    ...>   {"device1", "sysDescr.0"},
    ...>   {"device2", "sysUpTime.0"},
    ...>   {"device3", "ifNumber.0"}
    ...> ]

    # Default list format
    iex> SnmpKit.SnmpMgr.Multi.get_multi(requests)
    [
      {:ok, "Device 1 Description"},
      {:ok, 123456},
      {:error, :timeout}
    ]

    # With targets format - includes host/oid association
    iex> SnmpKit.SnmpMgr.Multi.get_multi(requests, return_format: :with_targets)
    [
      {"device1", "sysDescr.0", {:ok, "Device 1 Description"}},
      {"device2", "sysUpTime.0", {:ok, 123456}},
      {"device3", "ifNumber.0", {:error, :timeout}}
    ]

    # Map format - easy result lookup by host/oid
    iex> SnmpKit.SnmpMgr.Multi.get_multi(requests, return_format: :map)
    %{
      {"device1", "sysDescr.0"} => {:ok, "Device 1 Description"},
      {"device2", "sysUpTime.0"} => {:ok, 123456},
      {"device3", "ifNumber.0"} => {:error, :timeout}
    }

# monitor(targets_and_oids, callback, opts \\ [])

Monitors multiple devices for changes by polling at regular intervals.

## Parameters

- `targets_and_oids` - List of {target, oid} tuples to monitor
- `callback` - Function called with {target, oid, old_value, new_value} when changes occur
- `opts` - Options including :interval, :initial_poll, :max_concurrent

## Examples

    targets = [{"device1", "sysUpTime.0"}, {"device2", "ifInOctets.1"}]
    callback = fn change -> IO.inspect(change) end
    {:ok, monitor_pid} = SnmpKit.SnmpMgr.Multi.monitor(targets, callback, interval: 30_000)

# walk_multi(targets_and_oids, opts \\ [])

Performs walk operations against multiple targets concurrently.

## Parameters

- `targets_and_oids` - List of {target, root_oid} or {target, root_oid, opts} tuples
- `opts` - Global options applied to all requests
  - `: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

## Examples

    iex> requests = [
    ...>   {"device1", "system"},
    ...>   {"device2", "interfaces"},
    ...>   {"device3", [1, 3, 6, 1, 2, 1, 4]}
    ...> ]

    # Default list format
    iex> SnmpKit.SnmpMgr.Multi.walk_multi(requests, version: :v2c)
    [
      {:ok, [{[1,3,6,1,2,1,1,1,0], :octet_string, "Device 1"}, ...]},
      {:ok, [{[1,3,6,1,2,1,2,1,0], :integer, 24}, ...]},
      {:error, :timeout}
    ]

    # With targets format
    iex> SnmpKit.SnmpMgr.Multi.walk_multi(requests, return_format: :with_targets, version: :v2c)
    [
      {"device1", "system", {:ok, [{[1,3,6,1,2,1,1,1,0], :octet_string, "Device 1"}, ...]}},
      {"device2", "interfaces", {:ok, [{[1,3,6,1,2,1,2,1,0], :integer, 24}, ...]}},
      {"device3", [1, 3, 6, 1, 2, 1, 4], {:error, :timeout}}
    ]

    # Map format
    iex> SnmpKit.SnmpMgr.Multi.walk_multi(requests, return_format: :map, version: :v2c)
    %{
      {"device1", "system"} => {:ok, [{[1,3,6,1,2,1,1,1,0], :octet_string, "Device 1"}, ...]},
      {"device2", "interfaces"} => {:ok, [{[1,3,6,1,2,1,2,1,0], :integer, 24}, ...]},
      {"device3", [1, 3, 6, 1, 2, 1, 4]} => {:error, :timeout}
    }

# walk_table_multi(targets_and_tables, opts \\ [])

Performs table walk operations against multiple targets concurrently.

## Parameters

- `targets_and_tables` - List of {target, table_oid} or {target, table_oid, opts} tuples
- `opts` - Global options applied to all requests
  - `: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

## Examples

    iex> requests = [
    ...>   {"switch1", "ifTable"},
    ...>   {"switch2", "ifTable"},
    ...>   {"router1", "ipRouteTable"}
    ...> ]

    # Default list format
    iex> SnmpKit.SnmpMgr.Multi.walk_table_multi(requests, version: :v2c)
    [
      {: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"}, ...]},
      {:error, :host_unreachable}
    ]

    # With targets format
    iex> SnmpKit.SnmpMgr.Multi.walk_table_multi(requests, return_format: :with_targets, version: :v2c)
    [
      {"switch1", "ifTable", {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "eth0"}, ...]}},
      {"switch2", "ifTable", {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "GigE0/1"}, ...]}},
      {"router1", "ipRouteTable", {:error, :host_unreachable}}
    ]

    # Map format
    iex> SnmpKit.SnmpMgr.Multi.walk_table_multi(requests, return_format: :map, version: :v2c)
    %{
      {"switch1", "ifTable"} => {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "eth0"}, ...]},
      {"switch2", "ifTable"} => {:ok, [{"1.3.6.1.2.1.2.2.1.2.1", "GigE0/1"}, ...]},
      {"router1", "ipRouteTable"} => {:error, :host_unreachable}
    }