SNMP(7)

📦

version 25.3.2.8 · 3 versions

25.3.2.8 · ubuntu noble (latest)
24.2.1 · ubuntu jammy
25.2.3 · debian bookworm

, in ubuntu noble

okay bestie, welcome to the snmp(7) manual page — Erlang Application Definition energy 👑

💖 NAME 💖

SNMP — The SNMP Application. periodt.

🦋 DESCRIPTION 🦋

This chapter describes the snmp application in OTP. The SNMP application provides the following services:

a multilingual extensible SNMP agent
a SNMP manager
a MIB compiler

🌸 CONFIGURATION 🌸

The following configuration parameters are defined for the SNMP application. Refer to application(3erl) for more information about configuration parameters.

The snmp part of the config file specifying the configuration parameters is basically the following tuple:

{snmp, snmp_components_config()}

A minimal config file for starting a node with both a manager and an agent:

[{snmp,
  [{agent, [{db_dir, "/tmp/snmp/agent/db"},
            {config, [{dir, "/tmp/snmp/agent/conf"}]}]},
   {manager, [{config, [{dir, "/tmp/snmp/manager/conf"},
                        {db_dir, "/tmp/snmp/manager/db"}]}]}]}
  ]
 }
].

Each snmp component has its own set of configuration parameters, even though some of the types are common to both components.

snmp_components_config() -> [snmp_component_config()]
snmp_component_config() -> {agent, agent_options()} | {manager, manager_options()}
agent_options() = [agent_option()]
agent_option() = {restart_type,     restart_type()}     |
                 {agent_type,       agent_type()}       |
                 {agent_verbosity,  verbosity()}        |
                 {discovery,        agent_discovery()}  |
                 {versions,         versions()}         |
                 {gb_max_vbs,       gb_max_vbs()}       |
                 {priority,         priority()}         |
                 {multi_threaded,   multi_threaded()}   |
                 {db_dir,           db_dir()}           |
                 {db_init_error,    db_init_error()}    |
                 {local_db,         local_db()}         |
                 {net_if,           agent_net_if()}     |
                 {mibs,             mibs()}             |
                 {mib_storage,      mib_storage()}      |
                 {mib_server,       mib_server()}       |
                 {audit_trail_log,  audit_trail_log()}  |
                 {error_report_mod, error_report_mod()} |
                 {note_store,       note_store()}       |
                 {symbolic_store,   symbolic_store()}   |
                 {target_cache,     target_cache()}     |
                 {config,           agent_config()}
manager_options() = [manager_option()]
manager_option() = {restart_type,             restart_type()}    |
                   {net_if,                   manager_net_if()}  |
                   {server,                   server()}          |
                   {note_store,               note_store()}      |
                   {config,                   manager_config()}  |
                   {inform_request_behaviour, manager_irb()}     |
                   {mibs,                     manager_mibs()}    |
                   {priority,                 priority()}        |
                   {audit_trail_log,          audit_trail_log()} |
                   {versions,                 versions()}        |
                   {def_user_mod,             def_user_module()  |
                   {def_user_data,            def_user_data()}

🎀 Agent specific config options and types 🎀

agent_type() = master | sub <optional> — if master, one master agent is started. Otherwise, no agents are started. Default is master.
agent_discovery() = [agent_discovery_opt()] <optional> — where:

agent_discovery_opt() = {terminating,
agent_terminating_discovery_opts()} | {originating,
agent_originating_discovery_opts()}

The terminating options affect discovery initiated by a manager. The originating options affect discovery initiated by this agent. For defaults see the options in agent_discovery_opt().

agent_terminating_discovery_opts() = [agent_terminating_discovery_opt()] <optional> — where:

agent_terminating_discovery_opt() = {enable, boolean()} | {stage2,
discovery | plain} | {trigger_username, string()}

These are options affecting discovery terminating in this agent (i.e. initiated by a manager). The default values for the terminating discovery options are:

enable: true
stage2: discovery
trigger_username: ""

agent_originating_discovery_opts() = [agent_originating_discovery_opt()] <optional> — where:

agent_originating_discovery_opt() = {enable, boolean()}

These are options affecting discovery originating in this agent. The default values for the originating discovery options are:

enable: true

multi_threaded() = bool() | extended <optional> — if true (or extended), the agent is multi-threaded, with one thread for each get request. The value extended means that a special 'process' is also created intended to handle all notifications.
- true — One worker dedicated to 'set-requests' and one (main) worker for all other requests ('get-request' and notifications). If the 'main' worker is busy, a temporary process is spawned to handle that job ('get-request' or notification).
- extended — One worker dedicated to 'set-requests', one worker dedicated to notifications and one (main) worker for all 'get-requests'. If the 'main' worker is busy, a temporary process is spawned to handle that 'get-request'.

Note: Even with multi-threaded set to extended there is still a risk for 'reorder' when sending inform-requsts, which require a response (and may therefore require resending). Also, there is of course no way to guarantee order once the package is on the network.

Default is false.

db_dir() = string() <mandatory> — defines where the SNMP agent internal db files are stored.
gb_max_vbs() = pos_integer() | infinity <optional> — defines the maximum number of varbinds allowed in a Get-BULK response. Default is 1000.
local_db() = [local_db_opt()] <optional> — where:

local_db_opt() = {repair, agent_repair()} | {auto_save,
agent_auto_save()} | {verbosity, verbosity()}

Defines options specific for the SNMP agent local database. For defaults see the options in local_db_opt().

agent_repair() = false | true | force <optional> — when starting snmpa_local_db it always tries to open an existing database. If false, and some errors occur, a new database is created instead. If true, an existing file will be repaired. If force, the table will be repaired even if it was properly closed. Default is true.
agent_auto_save() = integer() | infinity <optional> — the auto save interval. The table is flushed to disk whenever not accessed for this amount of time. Default is 5000.
agent_net_if() = [agent_net_if_opt()] <optional> — where:

agent_net_if_opt() = {module, agent_net_if_module()} | {verbosity,
verbosity()} | {options, agent_net_if_options()}

Defines options specific for the SNMP agent network interface entity. For defaults see the options in agent_net_if_opt().

agent_net_if_module() = atom() <optional> — module which handles the network interface part for the SNMP agent. Must implement the snmpa_network_interface behaviour. Default is snmpa_net_if.
agent_net_if_options() = [agent_net_if_option()] <optional> — where:

agent_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()} |
{recbuf, recbuf()} | {no_reuse, no_reuse()} | {req_limit,
req_limit()} | {filter, agent_net_if_filter_options()} |
{open_err_filters, agent_net_if_open_err_filters()} |
{extra_sock_opts, extra_socket_options()} | {inet_backend, inet |
socket}

These options are actually specific to the used module. The ones shown here are applicable to the default agent_net_if_module().

Note: If the user has configured transports with options then those will take precedence over these options. See agent information for more info.

For defaults see the options in agent_net_if_option().

req_limit() = integer() | infinity <optional> — max number of simultaneous requests handled by the agent. Default is infinity.
agent_net_if_filter_options() = [agent_net_if_filter_option()] <optional> — where:

agent_net_if_filter_option() = {module,
agent_net_if_filter_module()}

These options are actually specific to the used module. The ones shown here are applicable to the default agent_net_if_filter_module(). For defaults see the options in agent_net_if_filter_option().

agent_net_if_filter_module() = atom() <optional> — module which handles the network interface filter part for the SNMP agent. Must implement the snmpa_network_interface_filter behaviour. Default is snmpa_net_if_filter.
agent_net_if_open_err_filters() = [agent_net_if_open_err_filter()] <optional> — where:

agent_net_if_open_err_filter() = atom()

During agent initiation, the transports UDP sockets are opened. If this operation fails, the net-if (and the agent) fails to start (crash). This (filter) list contains error (reasons) that will make net-if fail "nicely". This (filter) list, is supposed to contain errors that can be returned by gen_udp:open/1,2. The effect is that any error returned by gen_udp:open which are in this list, will be considered "non-fatal" and will only result in an info message, rather than an error message. Net If, and the agent, will still crash, but will produce a less obnoxious message.

agent_mibs() = [string()] <optional> — specifies a list of MIBs (including path) that defines which MIBs are initially loaded into the SNMP master agent. Note that the following mibs will always be loaded:
- version v1: STANDARD-MIB
- version v2: SNMPv2
- version v3: SNMPv2, SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB Default is [].
mib_storage() = [mib_storage_opt()] <optional> — where:

mib_storage_opt() = {module, mib_storage_module()} | {options,
mib_storage_options()}

This option specifies how basic mib data is stored. This option is used by two parts of the snmp agent: The mib-server and the symbolic-store. Default is [{module, snmpa_mib_storage_ets}].

mib_storage_module() = snmpa_mib_data_ets | snmpa_mib_data_dets | snmpa_mib_data_mnesia | module()

Okay so this is the one that picks the mib storage module for the SNMP agent, exactly as the snmpa_mib_storage behaviour defines it.

A bunch of the agent's entities — the mib-server (through its data module) and the symbolic-store — literally use this to store all the miscellaneous mib-related data they pick up while loading a mib. So yeah, it's doing a lot behind the scenes 💅

There are a few implementations bundled with the agent: snmpa_mib_storage_ets, snmpa_mib_storage_dets and snmpa_mib_storage_mnesia.

Default module is snmpa_mib_storage_ets.

mib_storage_options() = list() <optional>

Ngl, this one is fully implementation dependent — it depends on the module. Every module has its own valid set of options. For the modules that come with the app, these are the supported ones:

snmpa_mib_storage_ets: {dir, filename()} | {action, keep | clear}, {checksum, boolean()}
- dir — if you include it, it points at a directory where there's a file that all the data in the ets table gets "synced" to. And when a table is opened, that file gets read, if it exists. By default, this is not used.
- action — tells you what happens when a non-empty file is found: keep its content, or clear it out. Default is keep.
- checksum — defines if the file is checksummed or not. Default is false.
snmpa_mib_storage_dets: {dir, filename()} | {action, keep | clear}, {auto_save, default | pos_integer()} | {repair, force | boolean()}
- dir — this one is mandatory, bestie, no skipping it. It points to the directory where the file of a dets table gets placed.
- action — what happens when a non-empty file is found: keep its content or clear it out. Default is keep.
- auto_save — the dets auto-save frequency. Default is default.
- repair — the dets repair behaviour. Default is false.
snmpa_mib_storage_mnesia: {action, keep | clear}, {nodes, [node()]}
- action — what happens when a table already exists and isn't empty: keep its content or clear it out. Default is keep.
- nodes — a list of node names (or an atom describing a list of nodes) that says where to open the table. It's on you to make sure mnesia is actually running on the nodes you name, okay? 👀 The distinct values it recognises are:
  - [] — translated into a list of the own node: [node()]
  - all — erlang:nodes()
  - visible — erlang:nodes(visible)
  - connected — erlang:nodes(connected)
  - db_nodes — mnesia:system_info(db_nodes)

Default is the result of the call: erlang:nodes().

mib_server() = [mib_server_opt()] <optional>

mib_server_opt() = {mibentry_override, mibentry_override()} | {trapentry_override, trapentry_override()} | {verbosity, verbosity()} | {cache, mibs_cache()} | {data_module, mib_server_data_module()}

These are the options that are specific to the SNMP agent mib server. For defaults, peek at the options in mib_server_opt().

mibentry_override() = bool() <optional>

If this value is false, then every time a mib is loaded, each mib-entry gets checked before the mib is installed. Why? To stop the same symbolic mibentry name being used for different oid's. Simple as that 🎀

Default is false.

trapentry_override() = bool() <optional>

If this value is false, then when a mib is loaded, each trap gets checked before the mib is installed. The whole point of the check is to prevent the same symbolic trap name being reused for different trap's.

Default is false.

mib_server_data_module() = snmpa_mib_data_tttn | module() <optional>

Defines the backend data module of the SNMP agent mib-server, as defined by the snmpa_mib_data behaviour.

Right now, only the default module ships with the agent: snmpa_mib_data_tttn.

Default module is snmpa_mib_data_tttn.

mibs_cache() = bool() | mibs_cache_opts() <optional>

Shall the agent use the mib server lookup cache or not, that is the question.

Default is true — and in that case, the mibs_cache_opts() default values apply. Obsessed with a sensible default 💖

mibs_cache_opts() = [mibs_cache_opt()] <optional>

mibs_cache_opt() = {autogc, mibs_cache_autogc()} | {gclimit, mibs_cache_gclimit()} | {age, mibs_cache_age()}

Options that are specific to the SNMP agent mib server cache. For defaults, check the options in mibs_cache_opt().

mibs_cache_autogc() = bool() <optional>

Says whether the mib server should do cache gc automatically, or leave it to the user (see gc_mibs_cache/0,1,2,3).

Default is true.

mibs_cache_age() = integer() > 0 <optional>

How old the entries in the cache are allowed to get before they're GC'ed (assuming GC actually happens). Every entry in the cache gets "touched" whenever it's accessed, so it's a whole vibe.

The age is defined in milliseconds.

Default is 10 timutes. (no bestie, that is genuinely what the manpage says, we stan a typo 👑)

mibs_cache_gclimit() = infinity | integer() > 0 <optional>

When a GC is happening, this is the max number of cache entries that will be deleted from the cache.

The reason a limit is even possible: if the cache is huge, the GC can take a long time, and during that whole time the agent is "busy". But on a heavily loaded system, we also risk not removing enough elements in the cache, which instead makes it grow over time. That's literally why the default value is infinity — so all candidates get removed as soon as possible.

Default is infinity.

error_report_mod() = atom() <optional>

Defines an error report module, implementing the snmpa_error_report behaviour. Two modules ship with the toolkit: snmpa_error_logger and snmpa_error_io.

Default is snmpa_error_logger.

symbolic_store() = [symbolic_store_opt()]

symbolic_store_opt() = {verbosity, verbosity()}

Options specific to the SNMP agent symbolic store. For defaults, see the options in symbolic_store_opt().

target_cache() = [target_cache_opt()]

target_cache_opt() = {verbosity, verbosity()}

Options specific to the SNMP agent target cache. For defaults, see the options in target_cache_opt().

agent_config() = [agent_config_opt()] <mandatory>

agent_config_opt() = {dir, agent_config_dir()} | {force_load, force_load()} | {verbosity, verbosity()}

Defines the config-related options specific to the SNMP agent. For defaults, see the options in agent_config_opt().

agent_config_dir = dir() <mandatory>

Defines where the SNMP agent configuration files are stored. You gotta give this one, it's mandatory ✨

force_load() = bool() <optional>

If true, the configuration files get re-read during start-up and the contents of the configuration database get ignored. So heads up: if it's true, any changes to the configuration database are lost upon reboot of the agent 😭

Default is false.

Manager specific config options and types 💅

server() = [server_opt()] <optional>

server_opt() = {timeout, server_timeout()} | {verbosity, verbosity()} | {cbproxy, server_cbproxy()} | {netif_sup, server_nis()}

Specifies the options for the manager server process.

Default is silence. (yes, that's what it says 🫶)

server_timeout() = integer() <optional>

The asynchronous request cleanup time. For every request, some info gets stored internally so the reply can be delivered to the proper destination when it arrives. If the reply does arrive, that info gets deleted. But if there's no reply (in time), the info has to be deleted after the best before time has passed. This cleanup happens at regular intervals, defined by the server_timeout() time. The info will have a best before time defined by the Expire time you give when calling the request function (see async_get, async_get_next and async_set).

Time is in milli-seconds.

Default is 30000.

server_cbproxy() = temporary (default) | permanent <optional>

This option specifies how the server handles callback calls.

temporary (default): a temporary process gets created for each callback call.
permanent: with this, the server creates a permanent (named) process that in effect serializes all callback calls.

Default is temporary.

server_nis() = none (default) | {PingTO, PongTO} <optional>

This option specifies whether the server should actively supervise the net-if process. Quick note: this only works if the net-if process you're using actually supports the protocol. See the snmpm_network_interface behaviour for more info.

none (default): no active supervision of the net-if process.
{PingTO :: pos_integer(), PongTO :: pos_integer()}: the PingTO time specifies the time between a successful ping (or start) and the moment a ping message is sent to the net-if process — basically the time between pings. The PongTO time specifies how long the net-if process has to respond to a ping message with a pong message, and it starts counting when the ping message was sent. Both times are in milli seconds.

Default is none.

manager_config() = [manager_config_opt()] <mandatory>

manager_config_opt() = {dir, manager_config_dir()} | {db_dir, manager_db_dir()} | {db_init_error, db_init_error()} | {repair, manager_repair()} | {auto_save, manager_auto_save()} | {verbosity, verbosity()}

Defines the config-related options specific to the SNMP manager. For defaults, see the options in manager_config_opt().

manager_config_dir = dir() <mandatory>

Defines where the SNMP manager configuration files are stored.

manager_db_dir = dir() <mandatory>

Defines where the SNMP manager stores its persistent data.

manager_repair() = false | true | force <optional>

Defines the repair option for the persistent database — if and how the table is repaired when it's opened.

Default is true.

manager_auto_save() = integer() | infinity <optional>

The auto save interval. The table gets flushed to disk whenever it hasn't been accessed for this amount of time.

Default is 5000.

manager_irb() = auto | user | {user, integer()} <optional>

This option defines how the manager handles the sending of response (acknowledgment) to received inform-requests.

auto — the manager will autonomously send response (acknowledgment> to inform-request messages. like, it just does it, no waiting 💅
- {user, integer()} — the manager will send response (acknowledgment) to inform-request messages when the handle_inform function completes. the integer is the time, in milli-seconds, that the manager will consider the stored inform-request info valid.
- user — same as {user, integer()}, except that the default time, 15 seconds (15000), is used.

See snmpm_network_interface, handle_inform and definition of the manager net if for more info. 👀

Default is auto.

manager_mibs() = [string()] <optional> — specifies a list of MIBs (including path) and defines which MIBs are initially loaded into the SNMP manager. so like, your starter pack of MIBs, bestie 🌸

Default is [].

manager_net_if() = [manager_net_if_opt()] <optional> — defines options specific for the SNMP manager network interface entity.

manager_net_if_opt() = {module, manager_net_if_module()} | {verbosity, verbosity()} | {options, manager_net_if_options()}

For defaults see the options in manager_net_if_opt(). 🦋

manager_net_if_options() = [manager_net_if_option()] <optional> — these options are actually specific to the used module. the ones shown here are applicable to the default manager_net_if_module().

manager_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()} | {recbuf, recbuf()} | {no_reuse, no_reuse()} | {filter, manager_net_if_filter_options()} | {extra_sock_opts, extra_socket_options()} | {inet_backend, inet | socket}

For defaults see the options in manager_net_if_option(). ✨

manager_net_if_module() = atom() <optional> — the module which handles the network interface part for the SNMP manager. it must implement the snmpm_network_interface behaviour. no cap, that's the requirement 🫶

Default is snmpm_net_if.

manager_net_if_filter_options() = [manager_net_if_filter_option()] <optional> — these options are actually specific to the used module. the ones shown here are applicable to the default manager_net_if_filter_module().

manager_net_if_filter_option() = {module, manager_net_if_filter_module()}

For defaults see the options in manager_net_if_filter_option(). 💜

manager_net_if_filter_module() = atom() <optional> — module which handles the network interface filter part for the SNMP manager. must implement the snmpm_network_interface_filter behaviour. 👑

Default is snmpm_net_if_filter.

def_user_module() = atom() <optional> — the module implementing the default user. see the snmpm_user behaviour.

Default is snmpm_user_default.

def_user_data() = term() <optional> — data for the default user. passed to the user module when calling the callback functions.

Default is undefined. 💫

Common config types 🌈

restart_type() = permanent | transient | temporary — see supervisor documentation for more info.

Default is permanent for the agent and transient for the manager.

db_init_error() = terminate | create | create_db_and_dir — defines what to do if the agent or manager is unable to open an existing database file. terminate means that the agent/manager will terminate and create means that the agent/manager will remove the faulty file(s) and create new ones, and create_db_and_dir means that the agent/manager will create the database file along with any missing parent directories for the database file.

Default is terminate. 😭

priority() = atom() <optional> — defines the Erlang priority for all SNMP processes.

Default is normal.

versions() = [version()] <optional> — which SNMP versions shall be accepted/used.

version() = v1 | v2 | v3

Default is [v1,v2,v3].

verbosity() = silence | info | log | debug | trace <optional> — verbosity for a SNMP process. this specifies now much debug info is printed. 🗣️

Default is silence.

bind_to() = bool() <optional> — if true, net_if binds to the IP address. if false, net_if listens on any IP address on the host where it is running.

Default is false.

no_reuse() = bool() <optional> — if true, net_if does not specify that the IP and port address should be reusable. if false, the address is set to reusable.

Default is false.

recbuf() = integer() <optional> — receive buffer size.

Default value is defined by gen_udp.

sndbuf() = integer() <optional> — send buffer size.

Default value is defined by gen_udp. 🍓

extra_socket_options() = list() <optional> — a list of arbitrary socket options.

This list is not inspected by snmp (other then checking that its a list). Its the users responsibility to ensure that these are valid options and does not conflict with the "normal" options.

Default is [].

lowkey important: snmp will NOT check these for you, bestie. if it breaks, that's on you 🙈

note_store() = [note_store_opt()] <optional> — specifies the start-up verbosity for the SNMP note store.

note_store_opt() = {timeout, note_store_timeout()} | {verbosity, verbosity()}

For defaults see the options in note_store_opt().

note_store_timeout() = integer() <optional> — note cleanup time. when storing a note in the note store, each note is given lifetime. every timeout the note_store process performs a GC to remove the expired note's. time in milli-seconds. 🧹

Default is 30000.

audit_trail_log() = [audit_trail_log_opt()] <optional> — if present, this option specifies the options for the audit trail logging. the disk_log module is used to maintain a wrap log. if present, the dir and size options are mandatory.

If not present, audit trail logging is not used.

audit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} | {size, atl_size()} | {repair, atl_repair()} | {seqno, atl_seqno()}

atl_type() = read | write | read_write <optional> — specifies what type of an audit trail log should be used. the effect of the type is actually different for the the agent and the manager. 🎭

For the agent:

if write is specified, only set requests are logged.
if read is specified, only get requests are logged.
if read_write, all requests are logged.

For the manager:

if write is specified, only sent messages are logged.
if read is specified, only received messages are logged.
if read_write, both outgoing and incoming messages are logged.

Default is read_write.

atl_dir = dir() <mandatory> — specifies where the audit trail log should be stored.

If audit_trail_log specifies that logging should take place, this parameter must be defined. ⚠️

atl_size() = {integer(), integer()} <mandatory> — specifies the size of the audit trail log. this parameter is sent to disk_log.

If audit_trail_log specifies that logging should take place, this parameter must be defined. ⚠️

atl_repair() = true | false | truncate | snmp_repair <optional> — specifies if and how the audit trail log shall be repaired when opened. unless this parameter has the value snmp_repair it is sent to disk_log. if, on the other hand, the value is snmp_repair, snmp attempts to handle certain faults on its own. and even if it cannot repair the file, it does not truncate it directly, but instead moves it aside for later off-line analysis. so like, nothing gets yeeted by accident 🔥

Default is true.

atl_seqno() = true | false <optional> — specifies if the audit trail log entries will be (sequence) numbered or not. the range of the sequence numbers are according to RFC 5424, i.e. 1 through 2147483647.

Default is false.

SNMP(7)

💖 NAME 💖

🦋 DESCRIPTION 🦋

🌸 CONFIGURATION 🌸

🎀 Agent specific config options and types 🎀

Manager specific config options and types 💅

Common config types 🌈

SEE ALSO 🫶