Performs an adaptive bulk walk that automatically optimizes parameters.

Uses intelligent parameter tuning based on device response characteristics for optimal performance.

Parameters

• target - The target device
• root_oid - Starting OID for the walk
• opts - Options including :adaptive_tuning, :max_entries (default 1000)

Uses GETBULK, so version: :v1 is {:error, {:unsupported_operation, :get_bulk_requires_v2c}}; :v3 is honoured.

Examples

# Note: This function makes actual network calls and is not suitable for doctests
{:ok, results} = SnmpMgr.adaptive_walk("switch.local", "ifTable")
# Enriched varbind maps, the same shape as walk/3:
# [
#   %{name: "ifIndex.1", oid: "1.3.6.1.2.1.2.2.1.1.1", oid_list: [1, 3, 6, 1, 2, 1, 2, 2, 1, 1, 1],
#     type: :integer, value: 1, formatted: "1"},
#   %{name: "ifDescr.1", oid: "1.3.6.1.2.1.2.2.1.2.1", oid_list: [1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 1],
#     type: :octet_string, value: "eth0", formatted: "eth0"},
#   ...
# ]

Analyzes table structure and returns detailed metadata.

Parameters

• table_data - Table data as returned by get_table/3
• opts - Analysis options

Examples

{:ok, table} = SnmpMgr.get_table("192.0.2.1", "ifTable")
{:ok, analysis} = SnmpMgr.analyze_table(table)
IO.inspect(analysis.completeness)  # Shows data completeness ratio

Benchmarks a device to determine optimal bulk parameters.

Parameters

• target - The target device to benchmark
• test_oid - OID to use for testing
• opts - Benchmark options

Examples

{:ok, results} = SnmpMgr.benchmark_device("192.0.2.1", "ifTable")
optimal_size = results.optimal_bulk_size

@spec bulk_pretty(target(), oid(), opts()) :: {:ok, [varbind()]} | {:error, any()}

Performs an SNMP GETBULK operation with formatting forced on.

Same as get_bulk/3 (including its :version rule) except that every enriched map carries a :formatted value regardless of the include_formatted setting.

Examples

# Bulk operation with automatic formatting
{:ok, results} = SnmpMgr.bulk_pretty("192.168.1.1", "1.3.6.1.2.1.2.2", max_repetitions: 10)
# [
#   %{name: "ifIndex.1", oid: "1.3.6.1.2.1.2.2.1.1.1", oid_list: [1, 3, 6, 1, 2, 1, 2, 2, 1, 1, 1],
#     type: :integer, value: 1, formatted: "1"},
#   ...
# ]

@spec bulk_walk(target(), oid(), opts()) :: {:ok, [varbind()]} | {:error, any()}

Performs an SNMP BULK WALK operation (adaptive GETBULK) and returns enriched varbind maps, the same shape as walk/3.

Examples

# Bulk walk the interface table
{:ok, results} = SnmpMgr.bulk_walk("192.168.1.1", "1.3.6.1.2.1.2.2")
# [
#   %{name: "ifDescr.1", oid: "1.3.6.1.2.1.2.2.1.2.1", oid_list: [1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 1],
#     type: :octet_string, value: "eth0", formatted: "eth0"},
#   %{name: "ifSpeed.1", oid: "1.3.6.1.2.1.2.2.1.5.1", oid_list: [1, 3, 6, 1, 2, 1, 2, 2, 1, 5, 1],
#     type: :gauge32, value: 1_000_000_000, formatted: "1.0 Gbps"},
#   ...
# ]

Pass include_names: false, include_formatted: false for bare %{oid, oid_list, type, value} maps.

@spec bulk_walk_pretty(target(), oid(), opts()) ::
  {:ok, [varbind()]} | {:error, any()}

Performs an SNMP BULK WALK operation with formatting forced on.

Same as bulk_walk/3 except that every enriched map carries a :formatted value regardless of the include_formatted setting.

Examples

# Bulk walk interface table with automatic formatting
{:ok, results} = SnmpMgr.bulk_walk_pretty("192.168.1.1", "1.3.6.1.2.1.2.2")
# [
#   %{name: "ifSpeed.1", oid: "1.3.6.1.2.1.2.2.1.5.1", oid_list: [1, 3, 6, 1, 2, 1, 2, 2, 1, 5, 1],
#     type: :gauge32, value: 1_000_000_000, formatted: "1.0 Gbps"},
#   ...
# ]

@spec ensure_started() :: :ok | {:error, term()}

Ensures internal manager services are started.

Starts RequestIdGenerator and Engine if they are not running. Safe to call multiple times and from concurrent callers: the services are started under SnmpKit.SnmpMgr.ServiceSupervisor (part of the application tree), so a start race resolves to {:error, {:already_started, _}} inside the supervisor and the winner is used, and a caller exiting does not take the services down with it.

This call ignores the auto_start_services configuration; it is the explicit way to start the services when auto-start is disabled.

Performs an SNMP GET request.

Parameters

• target - The target device (e.g., "192.168.1.1:161" or "device.local")
• oid - The OID to retrieve (name "sysDescr.0", string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0]), or a list of several of them for one PDU
• opts - Options including :community, :timeout, :retries

Returns an enriched varbind map; with a list of OIDs, a list of them. An OID that does not parse or resolve is {:error, {:invalid_oid, input, reason}}.

Examples

# Note: This function makes actual network calls and is not suitable for doctests
{:ok, %{value: descr, type: :octet_string}} =
  SnmpMgr.get("device.local:161", "sysDescr.0", community: "public")
# %{name: "sysDescr.0", oid: "1.3.6.1.2.1.1.1.0", oid_list: [1, 3, 6, 1, 2, 1, 1, 1, 0],
#   type: :octet_string, value: "Linux server 5.4.0-42-generic", formatted: "Linux server ..."}

{:ok, %{type: :timeticks, value: 123_456_789, formatted: uptime}} =
  SnmpMgr.get("router.local", "sysUpTime.0")

{:ok, [%{name: "sysDescr.0"}, %{name: "sysName.0"}]} =
  SnmpMgr.get("router.local", ["sysDescr.0", "sysName.0"])

Performs an asynchronous SNMP GET request.

Returns a Task whose result is the same {:ok, varbind} or {:error, reason} tuple get/3 returns.

Parameters

• target - The target device
• oid - The OID to retrieve (string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] format)
• opts - Options including :community, :timeout, :retries

Examples

# Note: This function makes actual network calls and is not suitable for doctests
task = SnmpMgr.get_async("device.local", "sysDescr.0")
{:ok, %{value: description}} = Task.await(task, 5000)

@spec get_bulk(target(), oid(), opts()) :: {:ok, [varbind()]} | {:error, any()}

Performs an SNMP GETBULK request (SNMPv2c or SNMPv3; there is no GETBULK in v1).

GETBULK is more efficient than multiple GETNEXT requests for retrieving large amounts of data. It can retrieve multiple variables in a single request.

Parameters

• target - The target device
• oid - The starting OID (string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] format)
• opts - Options including :non_repeaters, :max_repetitions, :community, :timeout

Examples

# Note: This function makes actual network calls and is not suitable for doctests
{:ok, results} = SnmpMgr.get_bulk("switch.local", "ifTable", max_repetitions: 10)
# [
#   %{name: "ifIndex.1", oid: "1.3.6.1.2.1.2.2.1.1.1", oid_list: [1, 3, 6, 1, 2, 1, 2, 2, 1, 1, 1],
#     type: :integer, value: 1, formatted: "1"},
#   %{name: "ifIndex.2", oid: "1.3.6.1.2.1.2.2.1.1.2", oid_list: [1, 3, 6, 1, 2, 1, 2, 2, 1, 1, 2],
#     type: :integer, value: 2, formatted: "2"},
#   # ... up to max_repetitions entries, one enriched map each
# ]

Pass include_names: false, include_formatted: false for bare %{oid, oid_list, type, value} maps. version: :v1 returns {:error, {:unsupported_operation, :get_bulk_requires_v2c}}; :v3 is honoured.

Performs an asynchronous SNMP GETBULK request.

Returns a Task; await it with Task.await/2 for the same result get_bulk/3 returns. {:error, {:unsupported_operation, _}} is returned directly when version: :v1 is requested; :v3 is honoured.

task = SnmpMgr.get_bulk_async("device.local", "ifTable")
{:ok, rows} = Task.await(task, 5000)

Performs concurrent GETBULK operations against multiple targets.

Parameters

• targets_and_oids - List of {target, oid} tuples
• opts - Options applied to all requests including :max_repetitions

Gets a specific column from an SNMP table.

Parameters

• target - The target device
• table_oid - The table OID
• column - The column number (relative to the table's entry) or a registered column name such as "ifDescr"
• opts - Options including :community, :timeout

Returns the column's enriched varbind maps, as walk/3 does.

Performs concurrent GET operations against multiple targets.

Parameters

• targets_and_oids - List of {target, oid} tuples
• opts - Options applied to all requests

Returns one result per request, in order: {:ok, varbind} or {:error, reason} (see SnmpKit.SnmpMgr.Multi for :return_format).

Examples

# Note: This function makes actual network calls and is not suitable for doctests
SnmpMgr.get_multi([{"device1", [1,3,6,1,2,1,1,1,0]}, {"device2", [1,3,6,1,2,1,1,3,0]}])
# [{:ok, %{name: "sysDescr.0", ...}}, {:error, :hostname_resolution_failed}]

Performs an SNMP GETNEXT request.

Parameters

• target - The target device
• oid - The starting OID (string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] format)
• opts - Options including :community, :timeout, :retries

Returns the enriched varbind map of the next object.

Examples

# Note: This function makes actual network calls and is not suitable for doctests
{:ok, %{oid: "1.3.6.1.2.1.1.1.0", value: value}} =
  SnmpMgr.get_next("switch.local", "1.3.6.1.2.1.1")
# value: "Cisco IOS Software, C2960 Software"

{:ok, %{name: "sysDescr.0", type: :octet_string}} = SnmpMgr.get_next("device.local", "sysDescr")

@spec get_pretty(target(), oid(), opts()) :: {:ok, varbind()} | {:error, any()}

Performs an SNMP GET operation with formatting forced on.

Same as get/3 except that include_formatted cannot be turned off, so the enriched map always carries a human-readable :formatted value.

Examples

# Get system uptime with automatic formatting
{:ok, %{formatted: uptime}} = SnmpMgr.get_pretty("192.168.1.1", "1.3.6.1.2.1.1.3.0")
# uptime: "14 days 15 hours 55 minutes 13 seconds"
# The full map: %{oid: "1.3.6.1.2.1.1.3.0", oid_list: [1, 3, 6, 1, 2, 1, 1, 3, 0],
#   name: "sysUpTime.0", type: :timeticks, value: 126_355_300, formatted: "14 days ..."}

Gets all entries from an SNMP table and formats them as a structured table.

Parameters

• target - The target device
• table_oid - The table OID
• opts - Options including :community, :timeout

Examples

# Note: This function makes actual network calls and is not suitable for doctests
{:ok, table} = SnmpMgr.get_table("switch.local", "ifTable")
# %{1 => %{1 => 1, 2 => "GigabitEthernet0/1", 3 => 6, ...},
#   2 => %{1 => 2, 2 => "GigabitEthernet0/2", 3 => 6, ...}}

{:ok, table} = SnmpMgr.get_table("switch.local", "ifTable", named: true)
# %{1 => %{"ifIndex" => 1, "ifDescr" => "GigabitEthernet0/1", "ifType" => 6, ...}, ...}

With named: true column names come from the MIB registry and the row's INDEX objects are decoded into it (composite indexes included); see SnmpKit.SnmpMgr.Table.to_named_table/2.

@spec services_running?() :: boolean()

Returns true when all concurrent manager services are running.

Performs an SNMP SET request.

Parameters

• target - The target device
• oid - The OID to set (string "1.3.6.1.2.1.1.1.0" or list [1,3,6,1,2,1,1,1,0] format)
• value - The value to set
• opts - Options including :community, :timeout, :retries

Examples

# Note: This function makes actual network calls and is not suitable for doctests
:ok = SnmpMgr.set("device.local", "sysLocation.0", "Server Room A")
# :ok

:ok = SnmpMgr.set("switch.local", "sysContact.0", "admin@company.com",
  community: "private", timeout: 3000)
# :ok

Sets several objects in one SET PDU. pairs are {oid, value} tuples with the value forms set/4 accepts. Agents apply the SET atomically, so the whole call succeeds or fails together.

:ok = SnmpMgr.set_many("device", [{"sysContact.0", "ops"}, {"sysLocation.0", "rack 4"}])

Creates a stream for processing large SNMP tables.

Parameters

• target - The target device
• table_oid - The table OID to stream
• opts - Options including :chunk_size (default 50), :columns

Examples

# Note: This function makes actual network calls and is not suitable for doctests
stream = SnmpMgr.table_stream("192.0.2.1", "ifTable")
# Process table stream...

@spec walk(target(), oid(), opts()) :: {:ok, [map()]} | {:error, any()}

Performs an SNMP walk operation using iterative GETNEXT requests.

Walks the SNMP tree starting from the given OID and returns all OID/value pairs found under that subtree.

Parameters

• target - The target device
• root_oid - The starting OID for the walk
• opts - Options including :community, :timeout, :max_repetitions

Examples

# Note: This function makes actual network calls and is not suitable for doctests
{:ok, results} = SnmpMgr.walk("device.local", "1.3.6.1.2.1.1")
# [
#   %{name: "sysDescr.0", oid: "1.3.6.1.2.1.1.1.0", oid_list: [1, 3, 6, 1, 2, 1, 1, 1, 0],
#     type: :octet_string, value: "Linux hostname 5.4.0-42-generic", formatted: "Linux hostname 5.4.0-42-generic"},
#   %{name: "sysObjectID.0", oid: "1.3.6.1.2.1.1.2.0", oid_list: [1, 3, 6, 1, 2, 1, 1, 2, 0],
#     type: :object_identifier, value: [1, 3, 6, 1, 4, 1, 8072, 3, 2, 10], formatted: "1.3.6.1.4.1.8072.3.2.10"},
#   %{name: "sysUpTime.0", oid: "1.3.6.1.2.1.1.3.0", oid_list: [1, 3, 6, 1, 2, 1, 1, 3, 0],
#     type: :timeticks, value: 12345678, formatted: "1 day 10 hours 17 minutes 36 seconds"},
#   ...
# ]

Pass include_names: false, include_formatted: false for bare %{oid, oid_list, type, value} maps.

Performs concurrent walk operations against multiple targets.

Parameters

• targets_and_oids - List of {target, root_oid} tuples
• opts - Options applied to all requests

@spec walk_pretty(target(), oid(), opts()) :: {:ok, [varbind()]} | {:error, any()}

Performs an SNMP WALK operation with formatting forced on.

Same as walk/3 except that every enriched map carries a :formatted value regardless of the include_formatted setting.

Examples

# Walk system group with automatic formatting
{:ok, results} = SnmpMgr.walk_pretty("192.168.1.1", "1.3.6.1.2.1.1")
# [
#   %{name: "sysUpTime.0", oid: "1.3.6.1.2.1.1.3.0", oid_list: [1, 3, 6, 1, 2, 1, 1, 3, 0],
#     type: :timeticks, value: 126_355_300, formatted: "14 days 15 hours 55 minutes 13 seconds"},
#   ...
# ]

Creates a stream for memory-efficient processing of large SNMP data.

Parameters

• target - The target device
• root_oid - Starting OID for the walk
• opts - Options including :chunk_size (default 50), :adaptive, :version

Examples

# Note: This function makes actual network calls and is not suitable for doctests
stream = SnmpMgr.walk_stream("192.0.2.1", "ifTable")
# Process stream lazily...

@spec walk_table(target(), oid(), opts()) :: {:ok, [map()]} | {:error, any()}

Walks an SNMP table and returns all entries.

Parameters

• target - The target device
• table_oid - The table OID to walk
• opts - Options including :community, :timeout

Examples

# Note: This function makes actual network calls and is not suitable for doctests
{:ok, entries} = SnmpMgr.walk_table("switch.local", "ifTable")
# [
#   %{name: "ifIndex.1", oid: "1.3.6.1.2.1.2.2.1.1.1", type: :integer, value: 1, ...},
#   %{name: "ifDescr.1", oid: "1.3.6.1.2.1.2.2.1.2.1", type: :octet_string, value: "GigabitEthernet0/1", ...},
#   %{name: "ifType.1", oid: "1.3.6.1.2.1.2.2.1.3.1", type: :integer, value: 6, formatted: "ethernetCsmacd", ...},
#   %{name: "ifSpeed.1", oid: "1.3.6.1.2.1.2.2.1.5.1", type: :gauge32, value: 1000000000, formatted: "1.0 Gbps", ...},
#   # ... all interface table entries, one enriched map each
# ]

Performs concurrent table walk operations against multiple targets.

Parameters

• targets_and_tables - List of {target, table_oid} tuples
• opts - Options applied to all requests