snmp

v5.16

SNMP Application

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(3) 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> - agent_discovery_opt() = {terminating, agent_terminating_discovery_opts()} | {originating, agent_originating_discovery_opts()}

The terminating options effects discovery initiated by a manager.

The originating options effects discovery initiated by this agent.

For defaults see the options in agent_discovery_opt().

agent_terminating_discovery_opts() = [agent_terminating_discovery_opt()] <optional> - agent_terminating_discovery_opt() = {enable, boolean()} | {stage2, discovery | plain} | {trigger_username, string()}

These are options effecting 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> - agent_originating_discovery_opt() = {enable, boolean()}

These are options effecting 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> - 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> - 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> - 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_backend()}

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> - 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> - 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> - 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() - Defines the mib storage module of the SNMP agent as defined by the snmpa_mib_storage behaviour.

Several entities (mib-server via the its data module and the symbolic-store) of the snmp agent uses this for storage of miscellaneous mib related data retrieved while loading a mib.

There are several implementations provided 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> - This is implementation depended. That is, it depends on the module. For each module a specific set of options are valid. For the module provided with the app, these options are supported:

snmpa_mib_storage_ets: {dir, filename()} | {action, keep | clear}, {checksum, boolean()}

dir - If present, points to a directory where a file to which all data in the ets table is "synced".

Also, when a table is opened this file is read, if it exists.

By default, this will not be used.

action - Specifies the behaviour 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 mandatory option points to a directory where to place the file of a dets table.

action - Specifies the behaviour when a non-empty file is found: Keep its content or clear it out.

Default is keep.

auto_save - Defines the dets auto-save frequency.

Default is default.

repair - Defines the dets repair behaviour.

Default is false.

snmpa_mib_storage_mnesia: {action, keep | clear}, {nodes, [node()]}

action - Specifies the behaviour when a non-empty, already existing, table: Keep its content or clear it out.

Default is keep.

nodes - A list of node names (or an atom describing a list of nodes) defining where to open the table. Its up to the user to ensure that mnesia is actually running on the specified nodes.

The following distinct values are recognised:

[] - 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()}

Defines options specific for the SNMP agent mib server.

For defaults see the options in mib_server_opt().

mibentry_override() = bool() <optional> - If this value is false, then when loading a mib each mib- entry is checked prior to installation of the mib. The purpose of the check is to prevent that the same symbolic mibentry name is used for different oid's.

Default is false.

trapentry_override() = bool() <optional> - If this value is false, then when loading a mib each trap is checked prior to installation of the mib. The purpose of the check is to prevent that the same symbolic trap name is used 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.

At present only the default module is provided with the agent, snmpa_mib_data_tttn.

Default module is snmpa_mib_data_tttn.

mibs_cache() = bool() | mibs_cache_opts() <optional> - Shall the agent utilize the mib server lookup cache or not.

Default is true (in which case the mibs_cache_opts() default values apply).

mibs_cache_opts() = [mibs_cache_opt()] <optional> - mibs_cache_opt() = {autogc, mibs_cache_autogc()} | {gclimit, mibs_cache_gclimit()} | {age, mibs_cache_age()}

Defines options specific for the SNMP agent mib server cache.

For defaults see the options in mibs_cache_opt().

mibs_cache_autogc() = bool() <optional> - Defines if the mib server shall perform 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> - Defines how old the entries in the cache will be allowed to become before they are GC'ed (assuming GC is performed). Each entry in the cache is "touched" whenever it is accessed.

The age is defined in milliseconds.

Default is 10 timutes.

mibs_cache_gclimit() = infinity | integer() > 0 <optional> - When performing a GC, this is the max number of cache entries that will be deleted from the cache.

The reason why its possible to set a limit, is that if the cache is large, the GC can potentially take a long time, during which the agent is "busy". But on a heavily loaded system, we also risk not removing enough elements in the cache, instead causing it to grow over time. This is the reason the default value is infinity, which will ensure that all candidates are 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 are provided 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()}

Defines options specific for the SNMP agent symbolic store.

For defaults see the options in symbolic_store_opt().

target_cache() = [target_cache_opt()] - target_cache_opt() = {verbosity, verbosity()}

Defines options specific for 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 specific config related options for 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.

force_load() = bool() <optional> - If true the configuration files are re-read during start-up, and the contents of the configuration database ignored. Thus, if true, 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.

server_timeout() = integer() <optional> - Asynchronous request cleanup time. For every requests, some info is stored internally, in order to be able to deliver the reply (when it arrives) to the proper destination. If the reply arrives, this info will be deleted. But if there is no reply (in time), the info has to be deleted after the best before time has been passed. This cleanup will be performed at regular intervals, defined by the server_timeout() time. The information will have an best before time, defined by the Expire time given when calling the request function (see async_get, async_get_next and async_set).

Time in milli-seconds.

Default is 30000.

server_cbproxy() = temporary (default) | permanent <optional> - This option specifies how the server will handle callback calls.

temporary (default) - A temporary process will be created for each callback call.

permanent - With this the server will create a permanent (named) process that in effect serializes all callback calls.

Default is temporary.

server_nis() = none (default) | {PingTO, PongTO} <optional> - This option specifies if the server should actively supervise the net-if process. Note that this will only work if the used net-if process actually supports the protocol. See 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 between a successful ping (or start) and the time when a ping message is to be sent to the net-if process (basically the time between ping).

The PongTO time specifies how long time the net-if process has to respond to a ping message, with a pong message. Its starts counting when the ping message has been 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 specific config related options for 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 store persistent data.

manager_repair() = false | true | force <optional> - Defines the repair option for the persistent database (if and how the table is repaired when opened).

Default is true.

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

manager_irb() = auto | user | {user, integer()} <optional> - This option defines how the manager will handle the sending of response (acknowledgment) to received inform-requests.

auto - The manager will autonomously send response (acknowledgment> to inform-request messages.

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

Default is [].

manager_net_if() = [manager_net_if_opt()] <optional> - manager_net_if_opt() = {module, manager_net_if_module()} | {verbosity, verbosity()} | {options, manager_net_if_options()}

Defines options specific for the SNMP manager network interface entity.

For defaults see the options in manager_net_if_opt().

manager_net_if_options() = [manager_net_if_option()] <optional> - 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_backend()}

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

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.

Default is snmpm_net_if.

manager_net_if_filter_options() = [manager_net_if_filter_option()] <optional> - manager_net_if_filter_option() = {module, manager_net_if_filter_module()}

These options are actually specific to the used module. The ones shown here are applicable to the default 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> - version() = v1 | v2 | v3

Which SNMP versions shall be accepted/used.

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 [].

inet_backend() = inet | socket <optional> - Choose the inet-backend.

This option make it possible to use net_if (gen_udp) with a different inet-backend ('inet' or 'socket').

Default is inet.

note_store() = [note_store_opt()] <optional> - note_store_opt() = {timeout, note_store_timeout()} | {verbosity, verbosity()}

Specifies the start-up verbosity for the SNMP note store.

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> - audit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} | {size, atl_size()} | {repair, atl_repair()} | {seqno, atl_seqno()}

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.

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.

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.

See Also

application(3), disk_log(3)

SNMP Release Notes

SNMP 5.16

Improvements and New Features

-callback attributes have been added to modules snmpa_network_interface_filter, snmpa_notification_filter, snmpm_network_interface_filter, snmpm_user, and snmpa_notification_delivery_info_receiver.

New -type attributes have also been added to modules snmp, snmpa, snmpm, and snmpa_conf to support the previously mentioned callbacks.

Own Id: OTP-18785 Aux Id: PR-7702

Updated types and specs for all API modules.

Own Id: OTP-18934 Aux Id: BL-312

The documentation has been migrated to use Markdown and ExDoc.

Own Id: OTP-18955 Aux Id: PR-8026

SNMP 5.15

Improvements and New Features

Make snmp handle gen_udp with socket backend on Windows (completion).

Own Id: OTP-18598 Aux Id: OTP-18029

SNMP 5.14

Improvements and New Features

The implementation has been fixed to use proc_lib:init_fail/2,3 where appropriate, instead of proc_lib:init_ack/1,2.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-18490 Aux Id: OTP-18471, GH-6339, PR-6843

SNMP 5.13.5

Improvements and New Features

Attempts to minimize the number of the error reports during a failed agent init.

Own Id: OTP-18422 Aux Id: ERIERL-873

SNMP 5.13.4

Improvements and New Features

Replace size/1 with either tuple_size/1 or byte_size/1

The size/1 BIF is not optimized by the JIT, and its use can result in worse types for Dialyzer.

When one knows that the value being tested must be a tuple, tuple_size/1 should always be preferred.

When one knows that the value being tested must be a binary, byte_size/1 should be preferred. However, byte_size/1 also accepts a bitstring (rounding up size to a whole number of bytes), so one must make sure that the call to byte_size/ is preceded by a call to is_binary/1 to ensure that bitstrings are rejected. Note that the compiler removes redundant calls to is_binary/1, so if one is not sure whether previous code had made sure that the argument is a binary, it does not harm to add an is_binary/1 test immediately before the call to byte_size/1.

Own Id: OTP-18432 Aux Id: GH-6672,PR-6793,PR-6784,PR-6787,PR-6785,PR-6682,PR-6800,PR-6797,PR-6798,PR-6799,PR-6796,PR-6813,PR-6671,PR-6673,PR-6684,PR-6694,GH-6677,PR-6696,PR-6670,PR-6674

SNMP 5.13.3

Fixed Bugs and Malfunctions

Single threaded agent crash when vacm table not properly initiated.

Own Id: OTP-18379 Aux Id: ERIERL-904

SNMP 5.13.2

Fixed Bugs and Malfunctions

Explicitly close the socket(s) when terminating (default-) net-if process.

Own Id: OTP-18352 Aux Id: ERIERL-881

SNMP 5.13.1.1

Fixed Bugs and Malfunctions

Single threaded agent crash when vacm table not properly initiated.

Own Id: OTP-18379 Aux Id: ERIERL-904

SNMP 5.13.1

Fixed Bugs and Malfunctions

Improved the get-bulk response max size calculation. Its now possible to configure 'empty pdu size', see appendix c for more info.

Own Id: OTP-17115 Aux Id: ERIERL-456

Fix various example dialyzer issues

Own Id: OTP-18180 Aux Id: ERIERL-837

SNMP 5.13

Improvements and New Features

Input for configure scripts adapted to autoconf 2.71.

Own Id: OTP-17414 Aux Id: PR-4967

Removed deprecated functions slated for removal in OTP-25. Also removed "dead" code, kept for backward compatibility reasons.

Own Id: OTP-17612

SNMP 5.12.0.3

Improvements and New Features

Attempts to minimize the number of the error reports during a failed agent init.

Own Id: OTP-18422 Aux Id: ERIERL-873

SNMP 5.12.0.2

Fixed Bugs and Malfunctions

Single threaded agent crash when vacm table not properly initiated.

Own Id: OTP-18379 Aux Id: ERIERL-904

SNMP 5.12.0.1

Fixed Bugs and Malfunctions

Explicitly close the socket(s) when terminating (default-) net-if process.

Own Id: OTP-18352 Aux Id: ERIERL-881

SNMP 5.12

Fixed Bugs and Malfunctions

The compilation time is no longer recorded in BEAM files. There remained several undocumented functions that attempted to retrieve compilation times. Those have now been removed.

Own Id: OTP-17962

Improvements and New Features

[agent] Remove expectation of socket being a port.

Own Id: OTP-16559

SNMP 5.11

Fixed Bugs and Malfunctions

Handling of test config flag when starting "empty".

Own Id: OTP-17671

Improvements and New Features

Add support for new authentication algorithms (SHA-224, SHA-256, SHA-384 and SHA-512), according to RFC 7860.

Own Id: OTP-17615 Aux Id: MR9501-1

Improve debug info for (snmp) manager.

Own Id: OTP-17783

SNMP 5.10.1

Fixed Bugs and Malfunctions

Sockets are monitored, but the handling of the 'DOWN' message expected a new style socket ('socket'), old style (port) was not handled.

Own Id: OTP-17641 Aux Id: OTP-17640

SNMP 5.10

Improvements and New Features

It is now possible to configure the built-in net-if processes (both agent and manager) to use the new (gen_udp-) option 'inet_backend'.

Own Id: OTP-17526

SNMP 5.9.1

Fixed Bugs and Malfunctions

Commit of generated configure script.

Own Id: OTP-17420 Aux Id: OTP-17398, GH-4821

SNMP 5.9

Improvements and New Features

Removed deprecated functions marked for removal.

Own Id: OTP-17049

Removed timestamps from files generated by snmp to enable deterministic builds.

Own Id: OTP-17354

Fixed warnings in code matching on underscore prefixed variables.

Own Id: OTP-17385 Aux Id: OTP-17123

SNMP 5.8.0.1

Fixed Bugs and Malfunctions

Commit of generated configure script.

Own Id: OTP-17420 Aux Id: OTP-17398, GH-4821

SNMP 5.8

Improvements and New Features

Add function to get a list of configured agent transports. Also improved agent info with regards to transports.

Own Id: OTP-17109 Aux Id: ERIERL-583

SNMP 5.7.3

Fixed Bugs and Malfunctions

[manager] In a function handling snmp errors, an unused result (_Error) could result in matching issues and therefore case clause runtime errors (crash). Note that this would only happen in very unusual error cases.

Own Id: OTP-17161

SNMP 5.7.2

Fixed Bugs and Malfunctions

[manager] Misspelled priv protocol (atom) made it impossible to update usm user 'priv_key' configuration for usmAesCfb128Protocol via function calls.

Own Id: OTP-17110 Aux Id: ERIERL-586

SNMP 5.7.1

Fixed Bugs and Malfunctions

Fixed usage of AC_CONFIG_AUX_DIRS() macros in configure script sources.

Own Id: OTP-17093 Aux Id: ERL-1447, PR-2948

SNMP 5.7

Fixed Bugs and Malfunctions

If an attempt was made to send a v1 trap on a IPv6 transport this could cause a master agent crash (if the agent was not multi-threaded).

Own Id: OTP-16920 Aux Id: OTP-16649

The deprecation info for a couple of the deprecated MIB compiler functions where incorrect. Referred to functions in the 'snmpa' module instead of 'snmpc'.

Own Id: OTP-17056 Aux Id: OTP-17049

Improvements and New Features

Make it possible for the agent to configure separate transports (sockets) for request-responder and trap-sender.

Own Id: OTP-16649

The mib server cache handling has been improved. First, the default gclimit has been changed from 100 to infinity (to ensure the size is as small as possible). Also, the method of removing old elements has been optimized.

Own Id: OTP-16989 Aux Id: ERIERL-544

It is now possible to configure the agent in such a way that the order of outgoing notifications are processed in order in the agent. What happens after the notification message has left the agent (been sent) is of course still out of our control.

Own Id: OTP-17022 Aux Id: ERIERL-492

Improve handling of the udp_error message. Basically an improved error/warning message.

Own Id: OTP-17033

SNMP 5.6.1

Fixed Bugs and Malfunctions

For agent fix PrivParams for SNMPv3 USM with AES privacy, as earlier fixed for the manager in OTP_16541.

Own Id: OTP-15130 Aux Id: ERIERL-524, OTP-16541

The SNMP Agent missed to re-activate datagram reception in an odd timeout case and went deaf. This bug has been fixed.

Own Id: OTP-15767 Aux Id: ERIERL-523

Use of deprecated functions in example 2 has been removed (no more compiler warnings).

Own Id: OTP-16716

A file descriptor leak has been plugged. When calling the reconfigure function of a mib, it opened the config file(s) but never closed them on successful read.

Own Id: OTP-16760 Aux Id: ERIERL-511

SNMP 5.6

Fixed Bugs and Malfunctions

For manager, fix PrivParams for SNMPv3 USM with AES privacy; In `snmp_usm:do_decrypt/3`, pass full UsmSecParams to `snmp_usm:try_decrypt/5` as expected by AES clause. Change `snmpm_usm:aes_encrypt/3` to use EngineBoots and EngineTime as cached by `snmpm_config:get_usm_eboots/1` and `snmpm_config:get_usm_etime/1` instead of `snmpm_config:get_engine_boots/0` and `snmpm_config:get_engine_time/0`. This ensures correct msgPrivacyParameters are sent when AES is used. * Add test `snmp.snmp_manager_SUITE.usm_priv_aes/1` to avoid regression.

Own Id: OTP-16541 Aux Id: #2544

Invalid character in (manager) usm config entry generator function.

Own Id: OTP-16552 Aux Id: ERL-1196

Improvements and New Features

Remove usage and documentation of old requests of the I/O-protocol.

Own Id: OTP-15695

Calls of deprecated functions in the Old Crypto API are replaced by calls of their substitutions.

Own Id: OTP-16346

Finalize deprecation. Already deprecated functions has a "remove version 24" set and "new" functions added to list of deprecated functions.

Own Id: OTP-16463

Refactored the internal handling of deprecated and removed functions.

Own Id: OTP-16469

SNMP 5.5.0.5

Fixed Bugs and Malfunctions

Commit of generated configure script.

Own Id: OTP-17420 Aux Id: OTP-17398, GH-4821

SNMP 5.5.0.4

Improvements and New Features

The mib server cache handling has been improved. First, the default gclimit has been changed from 100 to infinity (in order to ensure the size is as small as possible). Also the method of removing old elements has been optimized.

Own Id: OTP-16989 Aux Id: ERIERL-544

It is now possible to configure the agent in such a way that the order of outgoing notifications are processed in order in the agent. What happens after the notification message has left the agent (been sent) is of course still out of our control.

Own Id: OTP-17022 Aux Id: ERIERL-492

SNMP 5.5.0.3

Fixed Bugs and Malfunctions

For agent fix PrivParams for SNMPv3 USM with AES privacy, as earlier fixed for the manager in OTP_16541.

Own Id: OTP-15130 Aux Id: ERIERL-524, OTP-16541

SNMP 5.5.0.2

Fixed Bugs and Malfunctions

The SNMP Agent missed to re-activate datagram reception in an odd timeout case and went deaf. This bug has been fixed.

Own Id: OTP-15767 Aux Id: ERIERL-523

SNMP 5.5.0.1

Fixed Bugs and Malfunctions

A file descriptor leak has been plugged. When calling the reconfigure function of a mib, it opened the config file(s) but never closed them on successful read.

Own Id: OTP-16760 Aux Id: ERIERL-511

SNMP 5.5

Improvements and New Features

A simple supervision of the snmp manager net-if process has been added. Also, a way to forcibly restart the net-if process has been added. This could be useful if the net-if process hangs for some reason.

Own Id: OTP-16447 Aux Id: ERIERL-455, OTP-16382

Misc documentation corrections

Own Id: OTP-16450

SNMP 5.4.5

Improvements and New Features

Its now possible to remove selected varbinds (from the final message) when sending a notification. This is done by setting the 'value' (in the varbind(s) of the varbinds list) to '?NOTIFICATION_IGNORE_VB_VALUE'.

Own Id: OTP-16349 Aux Id: ERIERL-444

Its now possible to specify that an oid shall be "truncated" (trailing ".0" to be removed) when sending an notification.

Own Id: OTP-16360 Aux Id: ERIERL-451

SNMP 5.4.4

Improvements and New Features

[manager] The callbacks where executed in a (new) 'temporary' process, that executed the callback call and then exited. This has now been made configurable so that is also possible to specify a 'permanent' callback proxy process. All callback calls will then be executed in this (permanent) process (in sequence).

Own Id: OTP-15947 Aux Id: ERIERL-378

SNMP 5.4.3.1

Improvements and New Features

Its now possible to remove selected varbinds (from the final message) when sending a notification. This is done by setting the 'value' (in the varbind(s) of the varbinds list) to '?NOTIFICATION_IGNORE_VB_VALUE'.

Own Id: OTP-16349 Aux Id: ERIERL-444

Its now possible to specify that an oid shall be "truncated" (trailing ".0" to be removed) when sending an notification.

Own Id: OTP-16360 Aux Id: ERIERL-451

SNMP 5.4.3

Fixed Bugs and Malfunctions

Agent discovery cleanup. If there is no receiver of INFORM then #state.reqs in snmpa_net_if keeps on growing for DISCOVERY.

Own Id: OTP-16228 Aux Id: ERIERL-427

SNMP 5.4.2

Fixed Bugs and Malfunctions

The agent discovery process has been made to work with snmptrapd..

Own Id: OTP-16207 Aux Id: ERIERL-427

SNMP 5.4.1

Improvements and New Features

Made it possible to add 'extra socket options' to the (gen_udp) socket open call (for both manager and agent). A new option has been added, extra_sock_opts, which makes it possible for the user to add a list of extra socket options that will be appended to the other socket options for the open call. See the snmp application config man page (erl -man 6 snmp) or the "Configuring the application" chapter of the Users Guide for more info.

Own Id: OTP-16092 Aux Id: ERIERL-410

SNMP 5.4

Fixed Bugs and Malfunctions

Fix various minor issues related to Dialyzer. Mostly these are dialyzer warnings, but there was also some minor bugs detected by Dialyzer.

Own Id: OTP-15932

Improvements and New Features

Fixed a dets usage problem detected by dialyzer.

Own Id: OTP-10400 Aux Id: kunagi-253 [164]

The function snmp:print_version_info() prints various version info. For each module a number of items are printed, such as app vsn and md5 digest. And an attempt was also made to print "compile time". This used to be available in the module_info for each module, but has now been removed.

Own Id: OTP-15330

The use of the deprecated random module has been replaced the with rand module.

Own Id: OTP-15331

Removed use of the deprecated function erlang:get_stacktrace(). Instead make use of the 'catch Class:Error:Stacktrace' feature.

Own Id: OTP-15332

SNMP 5.3

Improvements and New Features

The application otp_mibs has been removed from OTP. Some of its components (mibs) have been moved to other apps (snmp), or removed completely (os_mon).

Own Id: OTP-14984 Aux Id: OTP-15329

[snmp|agent] Add a get-mechanism callback module (and a corresponding behaviour). The agent calls this module to handle each get (get, get-next and get-bulk) request.

Own Id: OTP-15691 Aux Id: ERIERL-324

SNMP 5.2.12

Fixed Bugs and Malfunctions

Conversion of (agent) Audit Trail Log (ATL) failed due to invalid log entries.

The conversion aborted completely midway because the ATL contained invalid entries. The conversion has been improved so that it now firstly handles encountered errors and write an informative message (into the converted stream) and secondly keeps count of the number of successful or failed entry conversions. See log_to_txt for more info.

The reason the ATL contained invalid entries have also been fixed. The reason was that for some outgoing messages (not response):

encrypted (v3 messages)

Was logged "as is" (encrypted) without the info to decrypt, making conversion impossible (which was the reason the log contained bad entries).

un-encrypted

Was not logged at all.

Own Id: OTP-15287 Aux Id: ERIERL-206

[compiler] Spurious version message removed. The snmp mib compiler printed an spurious version message if the 'version' option was provided.

Own Id: OTP-15290

SNMP 5.2.11.2

Improvements and New Features

[manager] The callbacks where executed in a (new) 'temporary' process, that executed the callback call and then exited. This has now been made configurable so that is also possible to specify a 'permanent' callback proxy process. All callback calls will then be executed in this (permanent) process (in sequence).

Own Id: OTP-15947 Aux Id: ERIERL-378

SNMP 5.2.11.1

Improvements and New Features

[snmp|agent] Add a get-mechanism callback module (and a corresponding behaviour). The agent calls this module to handle each get (get, get-next and get-bulk) request.

Own Id: OTP-15691 Aux Id: ERIERL-324

SNMP 5.2.11

Fixed Bugs and Malfunctions

The Snmp MIB compiler now allows using a TEXTUAL-CONVENTION type before defining it.

Own Id: OTP-14196 Aux Id: ERIERL-161

SNMP 5.2.10

Fixed Bugs and Malfunctions

The example MIB EX1-MIB in the SNMP application has been corrected to match its example.

Own Id: OTP-14204 Aux Id: PR-1726

SNMP 5.2.9

Fixed Bugs and Malfunctions

Removed all old unused files in the documentation.

Own Id: OTP-14475 Aux Id: ERL-409, PR-1493

SNMP 5.2.8

Fixed Bugs and Malfunctions

The recbuf configuration option was not propagated correctly to the socket for the SNMP Manager.

Own Id: OTP-13372 Aux Id: ERIERL-73

SNMP 5.2.7

Fixed Bugs and Malfunctions

A bug in the SNMP MIB compiler has been fixed. An AUGMENTS referring to a table defined later in the MIB did not work.

Own Id: OTP-13014 Aux Id: ERL-375

SNMP 5.2.6

Fixed Bugs and Malfunctions

Internal code change: Calls to catch followed by a call to erlang:get_stacktrace/0 has been rewritten to use try instead of catch to make the code future-proof.

Own Id: OTP-14400

SNMP 5.2.5

Fixed Bugs and Malfunctions

The SNMP MIB compiler has been fixed to compile MIBS with refinements on user types such as in RFC 4669 RADIUS-AUTH-SERVER-MIB.mib. Problem reported and researched by Kenneth Lakin and Daniel Goertzen.

See also: https://bugs.erlang.org/browse/ERL-325

Own Id: OTP-14145 Aux Id: ERL-325

SNMP 5.2.4

Fixed Bugs and Malfunctions

Correct bugs when path to mib or idl spec files contains UTF-8 characters.

Own Id: OTP-13718 Aux Id: ERL-179

Improvements and New Features

Solves snmp config string handling as reported by ERL-164 and solved by PR-1100

Own Id: OTP-13706

SNMP 5.2.3

Improvements and New Features

Internal changes

Own Id: OTP-13551

SNMP 5.2.2

Fixed Bugs and Malfunctions

Snmp agent now properly handles vacmViewTreeFamily masks.

Own Id: OTP-13264

SNMP 5.2.1

Fixed Bugs and Malfunctions

Small documentation fixes

Own Id: OTP-13017

Improvements and New Features

Update configuration check of imask ( list of ones and zeros) to allow the empty list.

Own Id: OTP-13101

SNMP 5.2

Improvements and New Features

The runtime dependencies in the application resource file have been updated.

Own Id: OTP-12762

SNMP 5.1.2

Fixed Bugs and Malfunctions

A bug in the SNMP Agent has been corrected; when opening a port using the command line argument -snmpa_fd the Port should be 0 when calling gen_udp:open.

A bug in the SNMP manager has been corrected; it should not look at the -snmp_fd command line argument, but instead at -snmpm_fd.

Own Id: OTP-12669 Aux Id: seq12841

Improvements and New Features

Improved cryptographic capability.

Own Id: OTP-12452

SNMP Development Toolkit 5.1.1

Version 5.1.1 supports code replacement in runtime from/to version 5.1.

Improvements and new features

[compiler] Refinement of type Opaque was not allowed.

MIB constructs such as 'SYNTAX Opaque (SIZE(0..65535))' was previously not allowed, see the standard ALARM-MIB for eaxmple.

Own Id: OTP-12066

Aux Id: Seq 12669

Fixed Bugs and Malfunctions

-

Incompatibilities

-

SNMP 5.1

Improvements and New Features

The SNMP manager has been enhanced with dual stack IPv4+IPv6, as the agent just was. The documentation is also now updated for both the agent and the manager.

Own Id: OTP-12108 Aux Id: OTP-12020

SNMP 5.0

Improvements and New Features

SNMP has been improved to handle IPv6. The agent can handle dual stack IPv4 + IPv6, but not yet the manager. The documentation also still lags behind... If you do such advanced stuff like writing a custom net_if module, the interface for it has changed, but other than that SNMP is backwards compatible.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-12020 Aux Id: OTP-11518

SNMP 4.25.1

Fixed Bugs and Malfunctions

Application upgrade (appup) files are corrected for the following applications:

asn1, common_test, compiler, crypto, debugger, dialyzer, edoc, eldap, erl_docgen, et, eunit, gs, hipe, inets, observer, odbc, os_mon, otp_mibs, parsetools, percept, public_key, reltool, runtime_tools, ssh, syntax_tools, test_server, tools, typer, webtool, wx, xmerl

A new test utility for testing appup files is added to test_server. This is now used by most applications in OTP.

(Thanks to Tobias Schlager)

Own Id: OTP-11744

SNMP Development Toolkit 4.25.0.1

Version 4.25.0.1 supports code replacement in runtime from/to version 4.25, 4.24.2, 4.24.1 and 4.24.

Improvements and new features

Updated doc files to utf8.

Own Id: OTP-10907

Fixed test suite to support UTF-8 paths.

Own Id: OTP-10877

Fixed Bugs and Malfunctions

-

Incompatibilities

-

SNMP Development Toolkit 4.25

Version 4.25 supports code replacement in runtime from/to version 4.24.2, 4.24.1, 4.24, 4.23.1 and 4.23.

Improvements and new features

[agent] Enable SNMP to create missing database directories.

Add {db_init_error, create_db_and_dir} option to SNMP manager and agent. This allows them to create any missing parent directories for db_dir, rather than treating any missing directories as a fatal error. The default for db_init_error, which is terminate, is unchanged.

Steve Vinoski

Own Id: OTP-11352

[manager] Improved handling of unexpected return values from snmpm_user callback functions.

Violations of the documented API (crashes or invalid return values) will now result in an error message.

Own Id: OTP-11307

Add (atl) log conversion block option.

It is now possible to request that the Audit Trail Log should be blocked during conversion (log_to_txt or log_to_io). This could be useful when converting an entire large log (when there is a chance it may otherwise wrap during conversion).

See agent log_to_txt and log_to_io and also manager log_to_txt and log_to_io for details.

Own Id: OTP-11396

Own Id: seq12433

When converting an Audit Trail Log to text, a corrupt log entry could cause the entire conversion to fail.

Also, for a log with sequence numbers, failing to decode a log entry would cause the conversion to fail (not because of the failed decode, but because of the failure to write the error message).

Own Id: OTP-111453

Aux Id: Seq 12459

Fixed Bugs and Malfunctions

Wrong block cypher type used for AES ('aes_cbf128' instead of 'aes_cfb128') when performing AES block encrypt/decrypt which breaks SNMP usmAesCfb128Protocol in agent and manager.

Own Id: OTP-11412

[manager] When performing the AES encryption, invalid values for the EngineBoots and EngineTime was used.

The values of the local agent was used, which would have produced "some" values if an agent was actually running. If not it would have caused a crash.

Own Id: OTP-11413

Incompatibilities

-

SNMP Development Toolkit 4.24.2

Version 4.24.2 supports code replacement in runtime from/to version 4.24.1, 4.24, 4.23.1 and 4.23.

Improvements and new features

[agent] Improved documentation for the functions for loading and unloading mibs, see load_mibs and unload_mibs for more info.

Also added new functions for loading and unloading a single mib, see load_mib and unload_mib for more info.

Own Id: OTP-11216

Fixed Bugs and Malfunctions

-

Incompatibilities

-

SNMP Development Toolkit 4.24.1

Version 4.24.1 supports code replacement in runtime from/to version 4.24, 4.23.1 and 4.23.

Improvements and new features

-

Fixed Bugs and Malfunctions

[agent] Reading the value of the vacmViewTreeFamilyMask returns it in the wrong (internal bitlist) format.

The vacmViewTreeFamilyMask is defined as a bit string in the MIB (OCTET STRING). Internally a bitlist (list of 1's and 0's, see vacm config file for more info) is used. However, the MIB implementation assumed the latter, effectively rendering all attempts to read/set masks via SNMP unsuccessful.

Since the mask is used in hot paths (e.g. access permission checks for each SNMP operation, the bitlist representation of the mask has benefits (e.g. faster processing). Reading/writing the view mask objects is less time-critical. Therefore, to fix the issue, convert between the bitlist (internal) representation and bitstring (external) when the vacmViewTreeFamilyMask objects are accessed.

Also, the check of the vacm config file was invalid with regard to the mask value. It was assumed to be a proper oid, which is not strictly the case (see bitlist above).

Own Id: OTP-11177

Stefan Zegenhagen

[agent] The counter increment function in the local-db was incorrect. It did not handle counter wrap correctly.

Own Id: OTP-11192

Incompatibilities

-

SNMP Development Toolkit 4.24

Version 4.24 supports code replacement in runtime from/to version 4.23.1 and 4.23.

Improvements and new features

[agent,manager] Updated to support the new crypto interface.

Own Id: OTP-11009

[agent] Introduced a documented behaviour for the mib-server mib-data backend. At present only the default module (snmpa_mib_data_tttn) is provided.

A config option for the (agent) mib-servers mib-data backend module has been added to the agent config options, data_module.

Own Id: OTP-11101

[agent] Introduced a documented behaviour for the mib storage. At present there are three simple modules (snmpa_mib_storage_ets, snmpa_mib_storage_dets and snmpa_mib_storage_mnesia) implementing this behaviour, provided with the app.

A config option for the (agent) mib storage has been added to the agent config options.

Own Id: OTP-11107

Fixed Bugs and Malfunctions

-

Incompatibilities

-

SNMP Development Toolkit 4.23.1

Version 4.23.1 supports code replacement in runtime from/to version 4.23.

Improvements and new features

-

Fixed Bugs and Malfunctions

[compiler] Now handles MIBs importing the pesudotype BITS.

Own Id: OTP-10799

[compiler] The MIB compiler could not handle a table index that was defined later in the MIB.

Own Id: OTP-10808

Incompatibilities

-

SNMP Development Toolkit 4.23

Improvements and new features

[manager] Polish return values of snmpm_user_default according to snmpm_user doc.

Luca Favatella

Own Id: OTP-10671

[agent] Remove runtime warning in snmpa_agent because of tuple fun usage.

Luca Favatella

Own Id: OTP-10672

[manager] SNMP manager performance optimization.

Ivan Dubovik

Own Id: OTP-10673

Fixed Bugs and Malfunctions

-

Incompatibilities

[manager] The old Addr-and-Port based API functions, previously long deprecated and marked for deletion in R16B, has now been removed.

Own Id: OTP-10027

SNMP Development Toolkit 4.22.1

Version 4.22.1 supports code replacement in runtime from/to version 4.22, 4.21.7 4.21.6 4.21.5, 4.21.4, 4.21.3, 4.21.2, 4.21.1 and 4.21.

Improvements and new features

[agent] Semantic fixes to SNMP-USER-BASED-SM-MIB. The semantics allow the usmUserAuthKeyChange and usmUserPrivKeyChange objects to be written to in the same set requests that also creates and clones the user. This was not possible beforehand, causing test tools checking semantic SNMPv3 behaviour to fail on a lot of test cases.

Furthermore, once the user has been cloned by writing to an instance of usmUserCloneFrom, further set-operations to the same object will not return an error, but be no-ops. Especially, it must be avoided to copy security parameters again (possibly even from a different user).

Stefan Zegenhagen

Own Id: OTP-10166

[agent] Errors in vacmAccessTable RowStatus handling. There are problems with the handling of vacmAccessTableStatus that cause some SNMP test suites to report errors. Most notably, erroneous set operations frequently cause "genErr" errors to be returned. These "genErr" errors are usually caused by badmatch exceptions coming from {ok, Row} = snmpa_vacm:get_row(RowIndex) if the row does not exist.

The semantics of the RowStatus handling in that table has been adjusted to be compliant with the RowStatus textual description of SNPMv2-TC MIB.

Stefan Zegenhagen

Own Id: OTP-10164

Fixed Bugs and Malfunctions

[agent] Fix walk over vacmAccessTable. Fix the get_next implementation of vacmAccessTable to return all table entries.

The get_next implementation of vacmAccessTable did not return all available table data. Instead, it only returned the first column for each row, and all columns for the last row available.

Stefan Zegenhagen

Own Id: OTP-10165

[manager] snmpm:log_to_io/6 did not use the LogName argument.

Own Id: OTP-10066

Incorrect TimeTicks decode. Also bad handling of invalid encode (value outside of value range) for both TimeTicks and Unsigned32.

Own Id: OTP-10132

Incompatibilities

-

SNMP Development Toolkit 4.22

Version 4.22 supports code replacement in runtime from/to version 4.21.7 4.21.6 4.21.5, 4.21.4, 4.21.3, 4.21.2, 4.21.1 and 4.21.

Improvements and new features

[compiler] The table information the MIB compiler provides with augmented tables has been extended with nbr_of_cols, first_accessible and not_accessible.

Own Id: OTP-9969

Added the log_to_io audit-trail-log converter function to the api modules of both the manager and agent.

Own Id: OTP-9940

[manager] Introduced a new transport module, snmpm_net_if_mt, which handles all incoming and outgoing traffic in newly created processes. The message/request is processed and then the process exits.

Own Id: OTP-9876

[agent] Documenting previously existing but undocumented function, snmp_generic:get_table_info/2.

Own Id: OTP-9942

[agent] Improve error handling while reading agent config files. Some files contain mandatory information and is therefore themself mandatory.

Own Id: OTP-9943

Fixed Bugs and Malfunctions

-

Incompatibilities

-

SNMP Development Toolkit 4.21.7

Version 4.21.7 supports code replacement in runtime from/to version 4.21.6, 4.21.5, 4.21.4, 4.21.3, 4.21.2, 4.21.1, 4.21, 4.20.1 and 4.20.

Improvements and new features

-

Fixed Bugs and Malfunctions

[agent] Simultaneous snmpa:backup/1,2 calls can interfere. The master agent did not check if a backup was already in progress when a backup request was accepted.

Own Id: OTP-9884

Aux Id: Seq 11995

Incompatibilities

-

SNMP Development Toolkit 4.21.6

Version 4.21.6 supports code replacement in runtime from/to version 4.21.5, 4.21.4, 4.21.3, 4.21.2, 4.21.1, 4.21, 4.20.1 and 4.20.

Improvements and new features

[agent] DoS attack using GET-BULK with large value of MaxRepetitions. A preventive method has been implementing by simply limit the number of varbinds that can be included in a Get-BULK response message. This is specified by the new config option, gb_max_vbs.

Own Id: OTP-9700

Fixed Bugs and Malfunctions

[agent] Mib server cache gclimit update function incorrectly calls age update function. The gclimit update function, update_mibs_cache_gclimit/1, incorrectly called the age update function, update_mibs_cache_age/2.

Johan Claesson

Own Id: OTP-9868

Incompatibilities

-

SNMP Development Toolkit 4.21.5

Version 4.21.5 supports code replacement in runtime from/to version 4.21.4, 4.21.3, 4.21.2, 4.21.1, 4.21, 4.20.1 and 4.20.

Improvements and new features

[agent] Removed (more) use of old style tuple funs.

Own Id: OTP-9783

Fixed Bugs and Malfunctions

[agent] Repeated vacm table dumping fails due to file name conflict. When dumping the vacm table to disk, a temoporary file with a fixed name was used. If the table dumping (snmpa_vacm:dump_table/0) was initiated from several different processes in rapid succession, the dumping could fail because the different processes was simultaneously trying to write to the same file. This problem has been eliminated by creating a unique name for the temporary file.

Own Id: OTP-9851

Aux Id: Seq 11980

Incompatibilities

-

SNMP Development Toolkit 4.21.4

This version has never been released for R14B.

Version 4.21.4 supports code replacement in runtime from/to version 4.21.3, 4.21.2, 4.21.1, 4.21, 4.20.1, 4.20 and 4.19.

Improvements and new features

-

Fixed Bugs and Malfunctions

[agent] Removed use of old style tuple funs.

Own Id: OTP-9779

Incompatibilities

-

SNMP Development Toolkit 4.21.3

Version 4.21.3 supports code replacement in runtime from/to version 4.21.2, 4.21.1, 4.21, 4.20.1, 4.20 and 4.19.

Improvements and new features

[compiler] Improved version info printout from the MIB compiler frontend escript.

Own Id: OTP-9618

Fixed Bugs and Malfunctions

[agent] Version 4.20 introduced a change that broke trap sending from subagents. Due to a bug in the test code, this was not discovered, until that bug was fixed.

Own Id: OTP-9745

[agent] When sending an error message (reply) regarding snmpUnknownPDUHandlers, the agent used the wrong OID.

Own Id: OTP-9747

[compiler] Fix the --warnings/--W option parsing in the snmpc wrapper (e)script. The short warning option was incorrectly --w, instead of as documented --W. This has now been corrected.

* POTENTIAL INCOMPATIBILITY *

Tuncer Ayaz

Own Id: OTP-9718

Incompatibilities

[compiler] The short warning option has been changed from --w to --W to comply with the documentation.

Tuncer Ayaz

Own Id: OTP-9718

SNMP Development Toolkit 4.21.2

Version 4.21.2 supports code replacement in runtime from/to version 4.21.1, 4.21, 4.20.1, 4.20 and 4.19.

Improvements and new features

-

Fixed Bugs and Malfunctions

Bad note store GC timer deactivation. Wrong field in the state record was set (timeout instead active).

Stefan Grundmann

Own Id: OTP-9690

Incompatibilities

-

SNMP Development Toolkit 4.21.1

Version 4.21.1 supports code replacement in runtime from/to version 4.20.1, 4.20 and 4.19.

Improvements and new features

[compiler] Used wrong variable name (for warnings-as-errors variable), which caused the compiler to crash when using the snmpc (e)script.

Also added the option --Werror for the SNMP MIB compiler (escript) frontend (to mimic erlc), which specifies whether warnings should be treated as errors.

Own Id: OTP-9447

[agent] Some very minor debugging improvements.

Own Id: OTP-9446

Fixed Bugs and Malfunctions

-

Incompatibilities

-

SNMP Development Toolkit 4.21

Version 4.21 supports code replacement in runtime from/to version 4.20.1, 4.20 and 4.19.

Improvements and new features

[manager] There was no way to specify transport domain. The transport domains was assumed to be IPv4 (transportDomainUdpIpv4). This has now been changed so that it can also be IPv6 (transportDomainUdpIpv6). To facilitate this, the transport domain, tdomain, is now a (new) valid option when registering a new agent (and updating agent info).

This also mean that the transport behaviour has changed.

Own Id: OTP-9305

Aux Id: Seq 11847

[compiler] Added the option warnings_as_errors (for the SNMP MIB compiler (escript) frontend, the option --wae is used) which specifies whether warnings should be treated as errors.

Tuncer Ayaz

Own Id: OTP-9437

Fixed Bugs and Malfunctions

The snmp config tool could not handle (manager) audit trail config because the option seqno was not handled.

Own Id: OTP-9354

[agent] The SNMP ACM cache was not properly updated when changes where made to the VACM security-to-group, access and view-tree-family tables.

Own Id: OTP-9367

Aux Id: Seq 11858

Fixed install directory typo for man3.

Peter Lemenkov

Hans Ulrich Niedermann

Own Id: OTP-9442

Incompatibilities

-

SNMP Development Toolkit 4.20.1

Version 4.20.1 supports code replacement in runtime from/to version 4.20, 4.19 and 4.18.

Improvements and new features

-

Fixed Bugs and Malfunctions

[agent] Did not handle transport domains properly in some cases, for instance trap sending.

Own Id: OTP-9400

[agent] Wrong default transport domain, snmpUDPDomain, instead of transportDomainUdpIpv4.

Own Id: OTP-9425

Aux Id: Seq 11874

Incompatibilities

-

SNMP Development Toolkit 4.20

Version 4.20 supports code replacement in runtime from/to version 4.19 and 4.18.

Improvements and new features

[agent] Added support for sending traps to IPv6 targets.

See the target address config file, the target_addr_entry/11 function or add_addr/11 for more info.

Own Id: OTP-9088

Aux Id: Seq 11790

[agent] To be able to handle multiple engine-id(s) when sending trap(s), the function add_community/6 has been added.

Own Id: OTP-9119

Aux Id: Seq 11792

[manager] The API for snmp requests has been augmented to allow the caller to override some configuration.

This has been done by introducing a new set of API functions, see sync_get2/3,4, async_get2/3,4, sync_get_next2/3,4, async_get_next2/3,4, sync_get_bulk2/5,6, async_get_bulk2/5,6, sync_set2/3,4 and async_set2/3,4 for more info.

Own Id: OTP-9162

[manager] The old API functions (for get and set requests: snmpm:g/3,4,5,6,7, snmpm:ag/3,4,5,6,7, snmpm:gn/3,4,5,6,7, snmpm:agn/3,4,5,6,7, snmpm:s/3,4,5,6,7, snmpm:s/3,4,5,6,7, snmpm:gb/5,6,7,8,9 and snmpm:agb/5,6,7,8,9) are now officially deprecated. They will be removed as of R16B.

Own Id: OTP-9174

[agent] Pass extra info through the agent to the net-if process when sending notifications.

See snmpa:send_notification2/3 for more info. See also the incoming net-if messages when sending a trap (send_pdu message) and notification (send_pdu_req message).

Own Id: OTP-9183

Aux Id: Seq 11817

Added type specs for functions that do not return.

Kostis Sagonas

Own Id: OTP-9208

Fixed Bugs and Malfunctions

Fixed endode/decode of values of type Counter32.

This type (Counter32) is an unsigned integer 32, but is actually encoded as an signed integer 32. The encode/decode functions however, treated it as if it was encodeded as an unsigned integer 32.

Own Id: OTP-9022

Incompatibilities

-

SNMP Introduction

The SNMP development toolkit contains the following parts:

An Extensible multi-lingual SNMP agent, which understands SNMPv1 (RFC1157), SNMPv2c (RFC1901, 1905, 1906 and 1907), SNMPv3 (RFC2271, 2272, 2273, 2274 and 2275), or any combination of these protocols.

A multi-lingual SNMP manager.

A MIB compiler, which understands SMIv1 (RFC1155, 1212, and 1215) and SMIv2 (RFC1902, 1903, and 1904).

The SNMP development tool provides an environment for rapid agent/manager prototyping and construction. With the following information provided, this tool is used to set up a running multi-lingual SNMP agent/manager:

a description of a Management Information Base (MIB) in Abstract Syntax Notation One (ASN.1)

instrumentation functions for the managed objects in the MIB, written in Erlang.

The advantage of using an extensible (agent/manager) toolkit is to remove details such as type-checking, access rights, Protocol Data Unit (PDU), encoding, decoding, and trap distribution from the programmer, who only has to write the instrumentation functions, which implement the MIBs. The get-next function only has to be implemented for tables, and not for every variable in the global naming tree. This information can be deduced from the ASN.1 file.

Scope and Purpose

This manual describes the SNMP development tool, as a component of the Erlang/Open Telecom Platform development environment. It is assumed that the reader is familiar with the Erlang Development Environment, which is described in a separate User's Guide.

Prerequisites

The following prerequisites are required for understanding the material in the SNMP User's Guide:

the basics of the Simple Network Management Protocol version 1 (SNMPv1)

the basics of the community-based Simple Network Management Protocol version 2 (SNMPv2c)

the basics of the Simple Network Management Protocol version 3 (SNMPv3)

the knowledge of defining MIBs using SMIv1 and SMIv2

familiarity with the Erlang system and Erlang programming

The tool requires Erlang release 4.7 or later.

Definitions

The following definitions are used in the SNMP User's Guide.

MIB - The conceptual repository for management information is called the Management Information Base (MIB). It does not hold any data, merely a definition of what data can be accessed. A definition of an MIB is a description of a collection of managed objects.

SMI - The MIB is specified in an adapted subset of the Abstract Syntax Notation One (ASN.1) language. This adapted subset is called the Structure of Management Information (SMI).

ASN.1 - ASN.1 is used in two different ways in SNMP. The SMI is based on ASN.1, and the messages in the protocol are defined by using ASN.1.

Managed object - A resource to be managed is represented by a managed object, which resides in the MIB. In an SNMP MIB, the managed objects are either:

scalar variables, which have only one instance per context. They have single values, not multiple values like vectors or structures.

tables, which can grow dynamically.

a table element, which is a special type of scalar variable.

Operations - SNMP relies on the three basic operations: get (object), set (object, value) and get-next (object).

Instrumentation function - An instrumentation function is associated with each managed object. This is the function, which actually implements the operations and will be called by the agent when it receives a request from the management station.

Manager - A manager generates commands and receives notifications from agents. There usually are only a few managers in a system.

Agent - An agent responds to commands from the manager, and sends notification to the manager. There are potentially many agents in a system.

About This Manual

In addition to this introductory chapter, the SNMP User's Guide contains the following chapters:

Chapter 2: "Functional Description" describes the features and operation of the SNMP development toolkit. It includes topics on Sub-agents and MIB loading, Internal MIBs, and Traps.

Chapter 3: "The MIB Compiler" describes the features and the operation of the MIB compiler.

Chapter 4: "Running the application" describes how to start and configure the application. Topics on how to debug the application are also included.

Chapter 5: "Definition of Agent Configuration Files" is a reference chapter, which contains more detailed information about the agent configuration files.

Chapter 6: "Definition of Manager Configuration Files" is a reference chapter, which contains more detailed information about the manager configuration files.

Chapter 7: "Agent Implementation Example" describes how an MIB can be implemented with the SNMP Development Toolkit. Implementation examples are included.

Chapter 8: "Instrumentation Functions" describes how instrumentation functions should be defined in Erlang for the different operations.

Chapter 9: "Definition of Instrumentation Functions" is a reference chapter which contains more detailed information about the instrumentation functions.

Chapter 10: "Definition of Agent Net if" is a reference chapter, which describes the Agent Net if function in detail.

Chapter 11: "Definition of Manager Net if" is a reference chapter, which describes the Manager Net if function in detail.

Chapter 12: "Advanced Agent Topics" describes sub-agents, agent semantics, audit trail logging, and the consideration of distributed tables.

Appendix A describes the conversion of SNMPv2 to SNMPv1 error messages.

Appendix B contains the RFC1903 text on RowStatus.

Where to Find More Information

Refer to the following documentation for more information about SNMP and about the Erlang/OTP development system:

Marshall T. Rose (1991), "The Simple Book - An Introduction to Internet Management", Prentice-Hall

Evan McGinnis and David Perkins (1997), "Understanding SNMP MIBs", Prentice-Hall

RFC1155, 1157, 1212 and 1215 (SNMPv1)

RFC1901-1907 (SNMPv2c)

RFC1908, 2089 (coexistence between SNMPv1 and SNMPv2)

RFC2271, RFC2273 (SNMP std MIBs)

the Mnesia User's Guide

the Erlang 4.4 Extensions User's Guide

the Reference Manual

the Erlang Embedded Systems User's Guide

the System Architecture Support Libraries (SASL) User's Guide

the Installation Guide

the Asn1 User's Guide

Concurrent Programming in Erlang, 2nd Edition (1996), Prentice-Hall, ISBN 0-13-508301-X.

Agent Functional Description

The SNMP agent system consists of one Master Agent and optional Sub-agents.

The tool makes it easy to dynamically extend an SNMP agent in run-time. MIBs can be loaded and unloaded at any time. It is also easy to change the implementation of an MIB in run-time, without having to recompile the MIB. The MIB implementation is clearly separated from the agent.

To facilitate incremental MIB implementation, the tool can generate a prototype implementation for a whole MIB, or parts thereof. This allows different MIBs and management applications to be developed at the same time.

Features

To implement an agent, the programmer writes instrumentation functions for the variables and the tables in the MIBs that the agent is going to support. A running prototype which handles set, get, and get-next can be created without any programming.

The toolkit provides the following:

multi-lingual multi-threaded extensible SNMP agent

easy writing of instrumentation functions with a high-level programming language

basic fault handling such as automatic type checking

access control

authentication

privacy through encryption

loading and unloading of MIBs in run-time

the ability to change instrumentation functions without recompiling the MIB

rapid prototyping environment where the MIB compiler can use generic instrumentation functions, which later can be refined by the programmer

a simple and extensible model for transaction handling and consistency checking of set-requests

support of the sub-agent concept via distributed Erlang

a mechanism for sending notifications (traps and informs)

support for implementing SNMP tables in the Mnesia DBMS.

SNMPv1, SNMPv2 and SNMPv3

The SNMP development toolkit works with all three versions of Standard Internet Management Framework; SNMPv1, SNMPv2 and SNMPv3. They all share the same basic structure and components. And they follow the same architecture.

The versions are defined in following RFCs

SNMPv1 RFC 1555, 1157 1212, 1213 and 1215

SNMPv2 RFC 1902 - 1907

SNMPv3 RFC 2570 - 2575

Over time, as the Framework has evolved from SNMPv1 , through SNMPv2, to SNMPv3 the definitions of each of these architectural components have become richer and more clearly defined, but the fundamental architecture has remained consistent.

The main features of SNMPv2 compared to SNMPv1 are:

The get-bulk operation for transferring large amounts of data.

Enhanced error codes.

A more precise language for MIB specification

The standard documents that define SNMPv2 are incomplete, in the sense that they do not specify how an SNMPv2 message looks like. The message format and security issues are left to a special Administrative Framework. One such framework is the Community-based SNMPv2 Framework (SNMPv2c), which uses the same message format and framework as SNMPv1. Other experimental frameworks as exist, e.g. SNMPv2u and SNMPv2*.

The SNMPv3 specifications take a modular approach to SNMP. All modules are separated from each other, and can be extended or replaced individually. Examples of modules are Message definition, Security and Access Control. The main features of SNMPv3 are:

Encryption and authentication is added.

MIBs for agent configuration are defined.

All these specifications are commonly referred to as "SNMPv3", but it is actually only the Message module, which defines a new message format, and Security module, which takes care of encryption and authentication, that cannot be used with SNMPv1 or SNMPv2c. In this version of the agent toolkit, all the standard MIBs for agent configuration are used. This includes MIBs for definition of management targets for notifications. These MIBs are used regardless of which SNMP version the agent is configured to use.

The extensible agent in this toolkit understands the SNMPv1, SNMPv2c and SNMPv3. Recall that SNMP consists of two separate parts, the MIB definition language (SMI), and the protocol. On the protocol level, the agent can be configured to speak v1, v2c, v3 or any combination of them at the same time, i.e. a v1 request gets an v1 reply, a v2c request gets a v2c reply, and a v3 request gets a v3 reply. On the MIB level, the MIB compiler can compile both SMIv1 and SMIv2 MIBs. Once compiled, any of the formats can be loaded into the agent, regardless of which protocol version the agent is configured to use. This means that the agent translates from v2 notifications to v1 traps, and vice versa. For example, v2 MIBs can be loaded into an agent that speaks v1 only. The procedures for the translation between the two protocols are described in RFC 1908 and RFC 2089.

In order for an implementation to make full use of the enhanced SNMPv2 error codes, it is essential that the instrumentation functions always return SNMPv2 error codes, in case of error. These are translated into the corresponding SNMPv1 error codes by the agent, if necessary.

Note

The translation from an SMIv1 MIB to an SNMPv2c or SNMPv3 reply is always very straightforward, but the translation from a v2 MIB to a v1 reply is somewhat more complicated. There is one data type in SMIv2, called Counter64, that an SNMPv1 manager cannot decode correctly. Therefore, an agent may never send a Counter64 object to an SNMPv1 manager. The common practice in these situations is to simple ignore any Counter64 objects, when sending a reply or a trap to an SNMPv1 manager. For example, if an SNMPv1 manager tries to GET an object of type Counter64, he will get a noSuchName error, while an SNMPv2 manager would get a correct value.

Operation

The following steps are needed to get a running agent:

Write your MIB in SMI in a text file.

Write the instrumentation functions in Erlang and compile them.

Put their names in the association file.

Run the MIB together with the association file through the MIB compiler.

Configure the application (agent).

Start the application (agent).

Load the compiled MIB into the agent.

The figures in this section illustrate the steps involved in the development of an SNMP agent.

The compiler parses the SMI file and associates each table or variable with an instrumentation function (see the figure MIB Compiler Principles). The actual instrumentation functions are not needed at MIB compile time, only their names.

The binary output file produced by the compiler is read by the agent at MIB load time (see the figure Starting the Agent). The instrumentation is ordinary Erlang code which is loaded explicitly or automatically the first time it is called.

The SNMP agent system consists of one Master Agent and optional sub-agents. The Master Agent can be seen as a special kind of sub-agent. It implements the core agent functionality, UDP packet processing, type checking, access control, trap distribution, and so on. From a user perspective, it is used as an ordinary sub-agent.

Sub-agents are only needed if your application requires special support for distribution from the SNMP toolkit. A sub-agent can also be used if the application requires a more complex set transaction scheme than is found in the master agent.

The following illustration shows how a system can look in runtime.

A typical operation could include the following steps:

The Manager sends a request to the Agent.

The Master Agent decodes the incoming UDP packet.

The Master Agent determines which items in the request that should be processed here and which items should be forwarded to its subagent.

Step 3 is repeated by all subagents.

Each sub-agent calls the instrumentation for its loaded MIBs.

The results of calling the instrumentation are propagated back to the Master Agent.

The answer to the request is encoded to a UDP Protocol Data Unit (PDU).

The sequence of steps shown is probably more complex than normal, but it illustrates the amount of functionality which is available. The following points should be noted:

An agent can have many MIBs loaded at the same time.

Sub-agents can also have sub-agents. Each sub-agent can have an arbitrary number of child sub-agents registered, forming a hierarchy.

One MIB can communicate with many applications.

Instrumentation can use Distributed Erlang to communicate with an application.

Most applications only need the Master Agent because an agent can have multiple MIBs loaded at the same time.

Sub-agents and MIB Loading

Since applications tend to be transient (they are dynamically loaded and unloaded), the management of these applications must be dynamic as well. For example, if we have an equipment MIB for a rack and different MIBs for boards, which can be installed in the rack, the MIB for a card should be loaded when the card is inserted, and unloaded when the card is removed.

In this agent system, there are two ways to dynamically install management information. The most common way is to load an MIB into an agent. The other way is to use a sub-agent, which is controlled by the application and is able to register and unregister itself. A sub-agent can register itself for managing a sub-tree (not to be mixed up with erlang:register). The sub-tree is identified by an Object Identifier. When a sub-agent is registered, it receives all requests for this particular sub-tree and it is responsible for answering them. It should also be noted that a sub-agent can be started and stopped at any time.

Compared to other SNMP agent packages, there is a significant difference in this way of using sub-agents. Other packages normally use sub-agents to load and unload MIBs in run-time. In Erlang, it is easy to load code in run-time and it is possible to load an MIB into an existing sub-agent. It is not necessary to create a new process for handling a new MIB.

Sub-agents are used for the following reasons:

to provide a more complex set-transaction scheme than master agent

to avoid unnecessary process communication

to provide a more lightweight mechanism for loading and unloading MIBs in run-time

to provide interaction with other SNMP agent toolkits.

Refer to the chapter Advanced Agent Topics in this User's Guide for more information about these topics.

The communication protocol between sub-agents is the normal message passing which is used in distributed Erlang systems. This implies that sub-agent communication is very efficient compared to SMUX, DPI, AgentX, and similar protocols.

Contexts and Communities

A context is a collection of management information accessible by an SNMP entity. An instance of a management object may exist in more than one context. An SNMP entity potentially has access to many contexts.

Each managed object can exist in many instances within a SNMP entity. To identify the instances, specified by an MIB module, a method to distinguish the actual instance by its 'scope' or context is used. Often the context is a physical or a logical device. It can include multiple devices, a subset of a single device or a subset of multiple devices, but the context is always defined as a subset of a single SNMP entity. To be able to identify a specific item of management information within an SNMP entity, the context, the object type and its instance must be used.

For example, the managed object type ifDescr from RFC1573, is defined as the description of a network interface. To identify the description of device-X's first network interface, four pieces of information are needed: the snmpEngineID of the SNMP entity which provides access to the management information at device-X, the contextName (device-X), the managed object type (ifDescr), and the instance ("1").

In SNMPv1 and SNMPv2c, the community string in the message was used for (at least) three different purposes:

to identify the context

to provide authentication

to identify a set of trap targets

In SNMPv3, each of these usage areas has its own unique mechanism. A context is identified by the name of the SNMP entity, contextEngineID, and the name of the context, contextName. Each SNMPv3 message contains values for these two parameters.

There is a MIB, SNMP-COMMUNITY-MIB, which maps a community string to a contextEngineID and contextName. Thus, each message, an SNMPv1, SNMPv2c or an SNMPv3 message, always uniquely identifies a context.

For an agent, the contextEngineID identified by a received message, is always equal to the snmpEngineID of the agent. Otherwise, the message was not intended for the agent. If the agent is configured with more than one context, the instrumentation code must be able to figure out for which context the request was intended. There is a function snmpa:current_context/0 provided for this purpose.

By default, the agent has no knowledge of any other contexts than the default context, "". If it is to support more contexts, these must be explicitly added, by using an appropriate configuration file Agent Configuration Files.

Management of the Agent

There is a set of standard MIBs, which are used to control and configure an SNMP agent. All of these MIBs, with the exception of the optional SNMP-PROXY-MIB (which is only used for proxy agents), are implemented in this agent. Further, it is configurable which of these MIBs are actually loaded, and thus made visible to SNMP managers. For example, in a non-secure environment, it might be a good idea to not make MIBs that define access control visible. Note, the data the MIBs define is used internally in the agent, even if the MIBs not are loaded. This chapter describes these standard MIBs, and some aspects of their implementation.

Any SNMP agent must implement the system group and the snmp group, defined in MIB-II. The definitions of these groups have changed from SNMPv1 to SNMPv2. MIBs and implementations for both of these versions are Provided in the distribution. The MIB file for SNMPv1 is called STANDARD-MIB, and the corresponding for SNMPv2 is called SNMPv2-MIB. If the agent is configured for SNMPv1 only, the STANDARD-MIB is loaded by default; otherwise, the SNMPv2-MIB is loaded by default. It is possible to override this default behavior, by explicitly loading another version of this MIB, for example, you could choose to implement the union of all objects in these two MIBs.

An SNMPv3 agent must implement the SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB. These MIBs are loaded by default, if the agent is configured for SNMPv3. These MIBs can be loaded for other versions as well.

There are five other standard MIBs, which also may be loaded into the agent. These MIBs are:

SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB, which defines managed objects for configuration of management targets, i.e. receivers of notifications (traps and informs). These MIBs can be used with any SNMP version.

SNMP-VIEW-BASED-ACM-MIB, which defined managed objects for access control. This MIB can be used with any SNMP version.

SNMP-COMMUNITY-MIB, which defines managed objects for coexistence of SNMPv1 and SNMPv2c with SNMPv3. This MIB is only useful if SNMPv1 or SNMPv2c is used, possibly in combination with SNMPv3.

SNMP-USER-BASED-SM-MIB, which defines managed objects for authentication and privacy. This MIB is only useful with SNMPv3.

All of these MIBs should be loaded into the Master Agent. Once loaded, these MIBs are always available in all contexts.

The ASN.1 code, the Erlang source code, and the generated .hrl files for them are provided in the distribution and are placed in the directories mibs, src, and include, respectively, in the snmp application.

The .hrl files are generated with snmpc:mib_to_hrl/1. Include these files in your code as in the following example:

-include_lib("snmp/include/SNMPv2-MIB.hrl").

The initial values for the managed objects defined in these tables, are read at start-up from a set of configuration files. These are described in Configuration Files.

STANDARD-MIB and SNMPv2-MIB

These MIBs contain the snmp- and system groups from MIB-II which is defined in RFC1213 (STANDARD-MIB) or RFC1907 (SNMPv2-MIB). They are implemented in the snmp_standard_mib module. The snmp counters all reside in volatile memory and the system and snmpEnableAuthenTraps variables in persistent memory, using the SNMP built-in database (refer to the Reference Manual, section snmp, module snmpa_local_db for more details).

If another implementation of any of these variables is needed, e.g. to store the persistent variables in a Mnesia database, an own implementation of the variables must be made. That MIB will be compiled and loaded instead of the default MIB. The new compiled MIB must have the same name as the original MIB (i.e. STANDARD-MIB or SNMPv2-MIB), and be located in the SNMP configuration directory (see Configuration Files.)

One of these MIBs is always loaded. If only SNMPv1 is used, STANDARD-MIB is loaded, otherwise SNMPv2-MIB is loaded.

Data Types

There are some new data types in SNMPv2 that are useful in SNMPv1 as well. In the STANDARD-MIB, three data types are defined, RowStatus, TruthValue and DateAndTime. These data types are originally defined as textual conventions in SNMPv2-TC (RFC1903).

SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB

The SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB define additional read-only managed objects, which is used in the generic SNMP framework defined in RFC2271 and the generic message processing and dispatching module defined in RFC2272. They are generic in the sense that they are not tied to any specific SNMP version.

The objects in these MIBs are implemented in the modules snmp_framework_mib and snmp_standard_mib, respectively. All objects reside in volatile memory, and the configuration files are always reread at start-up.

If SNMPv3 is used, these MIBs are loaded by default.

SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB

The SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB define managed objects for configuration of notification receivers. They are described in detail in RFC2273. Only a brief description is given here.

All tables in these MIBs have a column of type StorageType. The value of this column specifies how each row is stored, and what happens in case of a restart of the agent. The implementation supports the values volatile and nonVolatile. When the tables are initially filled with data from the configuration files, these rows will automatically have storage type nonVolatile. Should the agent restart, all nonVolatile rows survive the restart, while the volatile rows are lost. The configuration files are not read at restart, by default.

These MIBs are not loaded by default.

snmpNotifyTable

An entry in the snmpNotifyTable selects a set of management targets, which should receive notifications, as well as the type (trap or inform) of notification that should be sent to each selected management target. When an application sends a notification using the function send_notification/5 or the function send_trap the parameter NotifyName, specified in the call, is used as an index in the table. The notification is sent to the management targets selected by that entry.

snmpTargetAddrTable

An entry in the snmpTargetAddrTable defines transport parameters (such as IP address and UDP port) for each management target. Each row in the snmpNotifyTable refers to potentially many rows in the snmpTargetAddrTable. Each row in the snmpTargetAddrTable refers to an entry in the snmpTargetParamsTable.

snmpTargetParamsTable

An entry in the snmpTargetParamsTable defines which SNMP version to use, and which security parameters to use.

Which SNMP version to use is implicitly defined by specifying the Message Processing Model. This version of the agent handles the models v1, v2c and v3.

Each row specifies which security model to use, along with security level and security parameters.

SNMP-VIEW-BASED-ACM-MIB

The SNMP-VIEW-BASED-ACM-MIB defines managed objects to control access to the the managed objects for the managers. The View Based Access Control Module (VACM) can be used with any SNMP version. However, if it is used with SNMPv1 or SNMPv2c, the SNMP-COMMUNITY-MIB defines additional objects to map community strings to VACM parameters.

All tables in this MIB have a column of type StorageType. The value of this column specifies how each row is stored, and what happens in case of a restart of the agent. The implementation supports the values volatile and nonVolatile. When the tables are initially filled with data from the configuration files, these rows will automatically have storage type nonVolatile. Should the agent restart, all nonVolatile rows survive the restart, while the volatile rows are lost. The configuration files are not read at restart by default.

This MIB is not loaded by default.

VACM is described in detail in RFC2275. Here is only a brief description given.

The basic concept is that of a MIB view. An MIB view is a subset of all the objects implemented by an agent. A manager has access to a certain MIB view, depending on which security parameters are used, in which context the request is made, and which type of request is made.

The following picture gives an overview of the mechanism to select an MIB view:

vacmContextTable

The vacmContextTable is a read-only table that lists all available contexts.

vacmSecurityToGroupTable

The vacmSecurityToGroupTable maps a securityModel and a securityName to a groupName.

vacmAccessTable

The vacmAccessTable maps the groupName (found in vacmSecurityToGroupTable), contextName, securityModel, and securityLevel to an MIB view for each type of operation (read, write, or notify). The MIB view is represented as a viewName. The definition of the MIB view represented by the viewName is found in the vacmViewTreeFamilyTable

vacmViewTreeFamilyTable

The vacmViewTreeFamilyTable is indexed by the viewName, and defines which objects are included in the MIB view.

The MIB definition for the table looks as follows:

VacmViewTreeFamilyEntry ::= SEQUENCE
    {
        vacmViewTreeFamilyViewName     SnmpAdminString,
        vacmViewTreeFamilySubtree      OBJECT IDENTIFIER,
        vacmViewTreeFamilyMask         OCTET STRING,
        vacmViewTreeFamilyType         INTEGER,
        vacmViewTreeFamilyStorageType  StorageType,
        vacmViewTreeFamilyStatus       RowStatus
    }

INDEX { vacmViewTreeFamilyViewName,
        vacmViewTreeFamilySubtree
      }

Each vacmViewTreeFamilyViewName refers to a collection of sub-trees.

MIB View Semantics

An MIB view is a collection of included and excluded sub-trees. A sub-tree is identified by an OBJECT IDENTIFIER. A mask is associated with each sub-tree.

For each possible MIB object instance, the instance belongs to a sub-tree if:

the OBJECT IDENTIFIER name of that MIB object instance comprises at least as many sub-identifiers as does the sub-tree, and

each sub-identifier in the name of that MIB object instance matches the corresponding sub-identifier of the sub-tree whenever the corresponding bit of the associated mask is 1 (0 is a wild card that matches anything).

Membership of an object instance in an MIB view is determined by the following algorithm:

If an MIB object instance does not belong to any of the relevant sub-trees, then the instance is not in the MIB view.

If an MIB object instance belongs to exactly one sub-tree, then the instance is included in, or excluded from, the relevant MIB view according to the type of that entry.

If an MIB object instance belongs to more than one sub-tree, then the sub-tree which comprises the greatest number of sub-identifiers, and is the lexicographically greatest, is used.

Note

If the OBJECT IDENTIFIER is longer than an OBJECT IDENTIFIER of an object type in the MIB, it refers to object instances. Because of this, it is possible to control whether or not particular rows in a table shall be visible.

SNMP-COMMUNITY-MIB

The SNMP-COMMUNITY-MIB defines managed objects that is used for coexistence between SNMPv1 and SNMPv2c with SNMPv3. Specifically, it contains objects for mapping between community strings and version-independent SNMP message parameters. In addition, this MIB provides a mechanism for performing source address validation on incoming requests, and for selecting community strings based on target addresses for outgoing notifications.

All tables in this MIB have a column of type StorageType. The value of this column specifies how each row is stored, and what happens in case of a restart of the agent. The implementation supports the values volatile and nonVolatile. When the tables are initially filled with data from the configuration files, these rows will automatically have storage type nonVolatile. Should the agent restart, all nonVolatile rows survive the restart, while the volatile rows are lost. The configuration files are not read at restart, by default.

This MIB is not loaded by default.

SNMP-USER-BASED-SM-MIB

The SNMP-USER-BASED-SM-MIB defines managed objects that is used for the User-Based Security Model.

All tables in this MIB have a column of type StorageType. The value of the column specifies how each row is stored, and what happens in case of a restart of the agent. The implementation supports the values volatile and nonVolatile. When the tables are initially filled with data from the configuration files, these rows will automatically have storage type nonVolatile. Should the agent restart, all nonVolatile rows survive the restart, while the volatile rows are lost. The configuration files are not read at restart, by default.

This MIB is not loaded by default.

OTP-SNMPEA-MIB

The OTP-SNMPEA-MIB was used in earlier versions of the agent, before standard MIBs existed for access control, MIB views, and trap target specification. All objects in this MIB are now obsolete.

Notifications

Notifications are defined in SMIv1 with the TRAP-TYPE macro in the definition of an MIB (see RFC1215). The corresponding macro in SMIv2 is NOTIFICATION-TYPE. When an application decides to send a notification, it calls one of the following functions:

snmpa:send_notification(Agent, Notification, Receiver
                       [, NotifyName, ContextName, Varbinds])
snmpa:send_trap(Agent, Notification, Community [, Receiver, Varbinds])

providing the registered name or process identifier of the agent where the MIB, which defines the notification is loaded and the symbolic name of the notification.

If the send_notification/3,4 function is used, all management targets are selected, as defined in RFC2273. The Receiver parameter defines where the agent should send information about the delivery of inform requests.

If the send_notification/5 function is used, an NotifyName must be provided. This parameter is used as an index in the snmpNotifyTable, and the management targets defined by that single entry is used.

The send_notification/6 function is the most general version of the function. A ContextName must be specified, from which the notification will be sent. If this parameter is not specified, the default context ("") is used.

The function send_trap is kept for backwards compatibility and should not be used in new code. Applications that use this function will continue to work. The snmpNotifyName is used as the community string by the agent when a notification is sent.

Notification Sending

The simplest way to send a notification is to call the function snmpa:send_notification(Agent, Notification, no_receiver). In this case, the agent performs a get-operation to retrieve the object values that are defined in the notification specification (with the TRAP-TYPE or NOTIFICATION-TYPE macros). The notification is sent to all managers defined in the target and notify tables, either unacknowledged as traps, or acknowledged as inform requests.

If the caller of the function wants to know whether or not acknowledgments are received for a certain notification (provided it is sent as an inform), the Receiver parameter can be specified as {Tag, ProcessName} (refer to the Reference Manual, section snmp, module snmp for more details). In this case, the agent send a message {snmp_notification, Tag, {got_response, ManagerAddr}} or {snmp_notification, Tag, {no_response, ManagerAddr}} for each management target.

Sometimes it is not possible to retrieve the values for some of the objects in the notification specification with a get-operation. However, they are known when the send_notification function is called. This is the case if an object is an element in a table. It is possible to give the values of some objects to the send_notification function snmpa:send_notification(Agent, Notification, Receiver, Varbinds). In this function, Varbinds is a list of Varbind, where each Varbind is one of:

{Variable, Value}, where Variable is the symbolic name of a scalar variable referred to in the notification specification.

{Column, RowIndex, Value}, where Column is the symbolic name of a column variable. RowIndex is a list of indices for the specified element. If this is the case, the OBJECT IDENTIFIER sent in the trap is the RowIndex appended to the OBJECT IDENTIFIER for the table column. This is the OBJECT IDENTIFIER which specifies the element.

{OID, Value}, where OID is the OBJECT IDENTIFIER for an instance of an object, scalar variable or column variable.

For example, to specify that sysLocation should have the value "upstairs" in the notification, we could use one of:

{sysLocation, "upstairs"} or

{[1,3,6,1,2,1,1,6,0], "upstairs"}

It is also possible to specify names and values for extra variables that should be sent in the notification, but were not defined in the notification specification.

The notification is sent to all management targets found in the tables. However, make sure that each manager has access to the variables in the notification. If a variable is outside a manager's MIB view, this manager will not receive the notification.

Note

By definition, it is not possible to send objects with ACCESS not-accessible in notifications. However, historically this is often done and for this reason we allow it in notification sending. If a variable has ACCESS not-accessible, the user must provide a value for the variable in the Varbinds list. It is not possible for the agent to perform a get-operation to retrieve this value.

Notification Filters

It is possible to add notification filters to an agent. These filters will be called when a notification is to be sent. Their purpose is to allow modification, suppression or other type of actions.

A notification filter is a module implementing the snmpa_notification_filter behaviour. A filter is added/deleted using the functions: snmpa:register_notification_filter/5 and snmpa:unregister_notification_filter/2.

Unless otherwise specified, the order of the registered filters will be the order in which they are registered.

Sub-agent Path

If a value for an object is not given to the send_notification function, the sub-agent will perform a get-operation to retrieve it. If the object is not implemented in this sub-agent, its parent agent tries to perform a get-operation to retrieve it. If the object is not implemented in this agent either, it forwards the object to its parent, and so on. Eventually the Master Agent is reached and at this point all unknown object values must be resolved. If some object is unknown even to the Master Agent, this is regarded as an error and is reported with a call to user_err/2 of the error report module. No notifications are sent in this case.

For a given notification, the variables, which are referred to in the notification specification, must be implemented by the agent that has the MIB loaded, or by some parent to this agent. If not, the application must provide values for the unknown variables. The application must also provide values for all elements in tables.

Discovery

The sender is authoritative for messages containing payload which does not expect a response (for example SNMPv2-Trap, Response or Report PDU).

The receiver is authoritative for messages containing payload which expects a response (for example Get, GetNext, Get-Bulk, Set or Inform PDU).

The agent can both perform and respond to discovery.

The agent responds to discovery autonomously, without interaction by the user.

Initiating discovery towards a manager is done by calling the snmpa:discovery/6 function. The EngineId field of the target (manager) entry in the target_addr.conf file has to have the value discovery. Note that if the manager does not respond, the Timeout and RetryCount fields decide how long the function will hang before it returns.

Discovery can only be performed towards one manager at a time.

Manager Functional Description

Features

The manager provided with the tool is a lightweight manager that basically provides a means to communicate with agents.

It does not really implement any management capabilities by itself. That is up to the user.

A user in this context is basically a module implementing the snmpm_user behaviour. A user can issue snmp requests and receive notification/traps.

Agents to be accessed by the manager needs to be registered by a user. Once registered, they can be accessed by all registered users.

Notifications/traps from an agent is delivered to the user that did the registration.

Any message from an agent that is not registered is delivered to the default user.

By default, the default user is set to the snmpm_user_default module, which simply sends an info message to the error_logger. It is however highly recommended that this module be replaced by another that does something useful (see configuration params for more info).

When using version 3, then (at least one) usm user has to be registered.

Requests can be issued in two different ways. Synchronous (see sync_set, sync_get, sync_get_next and sync_get_bulk) and asynchronous (see async_set, async_get, async_get_next and async_get_bulk). With synchronous the snmp reply is returned by the function. With asynchronous, the reply will instead be delivered through a call to one of the handle_pdu callback function defined by the handle_pdu behaviour.

Operation

The following steps are needed to get the manager running:

[optional] Implement the default user.

Implement the user(s).

Configure the application (manager).

Start the application (manager).

Register the user(s).

The user(s) register their agents.

MIB loading

It is possible to load mibs into the manager, but this is not necessary for normal operation, and not recommended.

The MIB Compiler

The chapter The MIB Compiler describes the MIB compiler and contains the following topics:

Operation

Import

Consistency checking between MIBs

.hrl file generation

Emacs integration

Deviations from the standard

Note

When importing MIBs, ensure that the imported MIBs as well as the importing MIB are compiled using the same version of the SNMP-compiler.

Operation

The MIB must be written as a text file in SMIv1 or SMIv2 using an ASN.1 notation before it will be compiled. This text file must have the same name as the MIB, but with the suffix .mib. This is necessary for handling the IMPORT statement.

The association file, which contains the names of instrumentation functions for the MIB, should have the suffix .funcs. If the compiler does not find the association file, it gives a warning message and uses default instrumentation functions. (See Default Instrumentation for more details).

The MIB compiler is started with a call to snmpc:compile(<mibname>). For example:

snmpc:compile("RFC1213-MIB").

The output is a new file which is called <mibname>.bin.

The MIB compiler understands both SMIv1 and SMIv2 MIBs. It uses the MODULE-IDENTITY statement to determinate if the MIB is written in SMI version 1 or 2.

Importing MIBs

The compiler handles the IMPORT statement. It is important to import the compiled file and not the ASN.1 (source) file. A MIB must be recompiled to make changes visible to other MIBs importing it.

The compiled files of the imported MIBs must be present in the current directory, or a directory in the current path. The path is supplied with the {i, Path} option, for example:

snmpc:compile("MY-MIB",
       [{i, ["friend_mibs/", "../standard_mibs/"]}]).

It is also possible to import MIBs from OTP applications in an "include_lib" like fashion with the il option. Example:

snmpc:compile("MY-MIB",
       [{il, ["snmp/priv/mibs/", "myapp/priv/mibs/"]}]).

finds the latest version of the snmp and myapp applications in the OTP system and uses the expanded paths as include paths.

Note that an SMIv2 MIB can import an SMIv1 MIB and vice versa.

The following MIBs are built-ins of the Erlang SNMP compiler: SNMPv2-SMI, RFC-1215, RFC-1212, SNMPv2-TC, SNMPv2-CONF, and RFC1155-SMI. They cannot therefore be compiled separately.

MIB Consistency Checking

When an MIB is compiled, the compiler detects if several managed objects use the same OBJECT IDENTIFIER. If that is the case, it issues an error message. However, the compiler cannot detect Oid conflicts between different MIBs. These kinds of conflicts generate an error at load time. To avoid this, the following function can be used to do consistency checking between MIBs:

erl>snmpc:is_consistent(ListOfMibNames).

ListOfMibNames is a list of compiled MIBs, for example ["RFC1213-MIB", "MY-MIB"]. The function also performs consistency checking of trap definitions.

.hrl File Generation

It is possible to generate an .hrl file which contains definitions of Erlang constants from a compiled MIB file. This file can then be included in Erlang source code. The file will contain constants for:

object Identifiers for tables, table entries and variables

column numbers

enumerated values

default values for variables and table columns.

Use the following command to generate a .hrl file from an MIB:

erl>snmpc:mib_to_hrl(MibName).

Emacs Integration

With the Emacs editor, the next-error (C-X `) function can be used indicate where a compilation error occurred, provided the error message is described by a line number.

Use M-x compile to compile an MIB from inside Emacs, and enter:

 erl -s snmpc compile <MibName> -noshell

An example of <MibName> is RFC1213-MIB.

Compiling from a Shell or a Makefile

The erlc commands can be used to compile SNMP MIBs. Example:

 erlc MY-MIB.mib

All the standard erlc flags are supported, e.g.

 erlc -I mymibs -o mymibs -W MY-MIB.mib

The flags specific to the MIB compiler can be specified by using the + syntax:

 erlc +'{group_check,false}' MY-MIB.mib

Deviations from the Standard

In some aspects the Erlang MIB compiler does not follow or implement the SMI fully. Here are the differences:

Tables must be written in the following order: tableObject, entryObject, column1, ..., columnN (in order).

Integer values, for example in the SIZE expression must be entered in decimal syntax, not in hex or bit syntax.

Symbolic names must be unique within a MIB and within a system.

Hyphens are allowed in SMIv2 (a pragmatic approach). The reason for this is that according to SMIv2, hyphens are allowed for objects converted from SMIv1, but not for others. This is impossible to check for the compiler.

If a word is a keyword in any of SMIv1 or SMIv2, it is a keyword in the compiler (deviates from SMIv1 only).

Indexes in a table must be objects, not types (deviates from SMIv1 only).

A subset of all semantic checks on types are implemented. For example, strictly the TimeTicks may not be sub-classed but the compiler allows this (standard MIBs must pass through the compiler) (deviates from SMIv2 only).

The MIB.Object syntax is not implemented (since all objects must be unique anyway).

Two different names cannot define the same OBJECT IDENTIFIER.

The type checking in the SEQUENCE construct is non-strict (i.e. subtypes may be specified). The reason for this is that some standard MIBs use this.

A definition has normally a status field. When the status field has the value deprecated, then the MIB-compiler will ignore this definition. With the MIB-compiler option {deprecated,true} the MIB-compiler does not ignore the deprecated definitions.

An object has a DESCRIPTIONS field. The descriptions-field will not be included in the compiled mib by default. In order to get the description, the mib must be compiled with the option description.

Running the application

The chapter Running the application describes how the application is configured and started. The topics include:

configuration directories and parameters

modifying the configuration files

starting the application (agent and/or manager)

debugging the application (agent and/or manager)

Refer also to the chapter(s) Definition of Agent Configuration Files and Definition of Manager Configuration Files which contains more detailed information about the agent and manager configuration files.

Configuring the application

The following two directories must exist in the system to run the agent:

the configuration directory stores all configuration files used by the agent (refer to the chapter Definition of Agent Configuration Files for more information).

the database directory stores the internal database files.

The following directory must exist in the system to run the manager:

the configuration directory stores all configuration files used by the manager (refer to the chapter Definition of Manager Configuration Files for more information).

the database directory stores the internal database files.

The agent and manager uses (application) configuration parameters to find out where these directories are located. The parameters should be defined in an Erlang system configuration file. The following configuration parameters are defined for the SNMP application:

      agent_options() = [agent_option()]
      agent_option() = {restart_type,     restart_type()}     |
                       {agent_type,       agent_type()}       |
                       {agent_verbosity,  verbosity()}        |
                       {versions,         versions()}         |
                       {discovery,        agent_discovery()}  |
                       {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> - agent_discovery_opt() = {terminating, agent_terminating_discovery_opts()} | {originating, agent_originating_discovery_opts()}

The terminating options effects discovery initiated by a manager.

The originating options effects discovery initiated by this agent.

For defaults see the options in agent_discovery_opt().

agent_terminating_discovery_opts() = [agent_terminating_discovery_opt()] <optional> - agent_terminating_discovery_opt() = {enable, boolean()} | {stage2, discovery | plain} | {trigger_username, string()}

These are options effecting 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> - agent_originating_discovery_opt() = {enable, boolean()}

These are options effecting 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> - 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> - agent_net_if_option() = {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> - 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_backend()}

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> - 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> - 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 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> - 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() - Defines the mib storage module of the SNMP agent as defined by the snmpa_mib_storage behaviour.

Several entities (mib-server via the its data module and the symbolic-store) of the snmp agent uses this for storage of miscellaneous mib related data data retrieved while loading a mib.

There are several implementations provided 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> - This is implementation depended. That is, it depends on the module. For each module a specific set of options are valid. For the module provided with the app, these options are supported:

snmpa_mib_storage_ets: {dir, filename()} | {action, keep | clear}, {checksum, boolean()}

dir - If present, points to a directory where a file to which all data in the ets table is "synced".

Also, when a table is opened this file is read, if it exists.

By default, this will not be used.

action - Specifies the behaviour 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 mandatory option points to a directory where to place the file of a dets table.

action - Specifies the behaviour when a non-empty file is found: Keep its content or clear it out.

Default is keep.

auto_save - Defines the dets auto-save frequency.

Default is default.

repair - Defines the dets repair behaviour.

Default is false.

snmpa_mib_storage_mnesia: {action, keep | clear}, {nodes, [node()]}

action - Specifies the behaviour when a non-empty, already existing, table: Keep its content or clear it out.

Default is keep.

nodes - A list of node names (or an atom describing a list of nodes) defining where to open the table. Its up to the user to ensure that mnesia is actually running on the specified nodes.

The following distinct values are recognised:

[] - 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()}

Defines options specific for the SNMP agent mib server.

For defaults see the options in mib_server_opt().

mibentry_override() = bool() <optional> - If this value is false, then when loading a mib each mib- entry is checked prior to installation of the mib. The purpose of the check is to prevent that the same symbolic mibentry name is used for different oid's.

Default is false.

trapentry_override() = bool() <optional> - If this value is false, then when loading a mib each trap is checked prior to installation of the mib. The purpose of the check is to prevent that the same symbolic trap name is used 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.

At present only the default module is provided with the agent, snmpa_mib_data_tttn.

Default module is snmpa_mib_data_tttn.

mibs_cache() = bool() | mibs_cache_opts() <optional> - Shall the agent utilize the mib server lookup cache or not.

Default is true (in which case the mibs_cache_opts() default values apply).

mibs_cache_opts() = [mibs_cache_opt()] <optional> - mibs_cache_opt() = {autogc, mibs_cache_autogc()} | {gclimit, mibs_cache_gclimit()} | {age, mibs_cache_age()}

Defines options specific for the SNMP agent mib server cache.

For defaults see the options in mibs_cache_opt().

mibs_cache_autogc() = bool() <optional> - Defines if the mib server shall perform 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> - Defines how old the entries in the cache will be allowed to become before they are GC'ed (assuming GC is performed). Each entry in the cache is "touched" whenever it is accessed.

The age is defined in milliseconds.

Default is 10 timutes.

mibs_cache_gclimit() = infinity | integer() > 0 <optional> - When performing a GC, this is the max number of cache entries that will be deleted from the cache.

The reason why its possible to set a limit, is that if the cache is large, the GC can potentially take a long time, during which the agent is "busy". But on a heavily loaded system, we also risk not removing enough elements in the cache, instead causing it to grow over time. This is the reason the default value is infinity, which will ensure that all candidates are 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 are provided 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()}

Defines options specific for the SNMP agent symbolic store.

For defaults see the options in symbolic_store_opt().

target_cache() = [target_cache_opt()] - target_cache_opt() = {verbosity, verbosity()}

Defines options specific for 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 specific config related options for 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.

force_load() = bool() <optional> - If true the configuration files are re-read during start-up, and the contents of the configuration database ignored. Thus, if true, 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.

server_timeout() = integer() <optional> - Asynchronous request cleanup time. For every request, some info is stored internally, in order to be able to deliver the reply (when it arrives) to the proper destination. If the reply arrives, this info will be deleted. But if there is no reply (in time), the info has to be deleted after the best before time has been passed. This cleanup will be performed at regular intervals, defined by the server_timeout() time. The information will have a best before time, defined by the Expire time given when calling the request function (see async_get, async_get_next and async_set).

Time in milli-seconds.

Default is 30000.

server_cbproxy() = temporary (default) | permanent <optional> - This option specifies how the server will handle callback calls.

temporary (default) - A temporary process will be created for each callback call.

permanent - With this the server will create a permanent (named) process that in effect serializes all callback calls.

Default is temporary.

server_nis() = none (default) | {PingTO, PongTO} <optional> - This option specifies if the server should actively supervise the net-if process. Note that this will only work if the used net-if process actually supports the protocol. See 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 between a successful ping (or start) and the time when a ping message is to be sent to the net-if process (basically the time between ping:s).

The PongTO time specifies how long time the net-if process has to respond to a ping message, with a pong message. It starts counting when the ping message has been 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 specific config related options for 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 store persistent data.

manager_repair() = false | true | force <optional> - Defines the repair option for the persistent database (if and how the table is repaired when opened).

Default is true.

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

manager_irb() = auto | user | {user, integer()} <optional> - This option defines how the manager will handle the sending of response (acknowledgment) to received inform-requests.

auto - The manager will autonomously send response (acknowledgment> to inform-request messages.

{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, 15000 milli-seconds, 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.

Default is [].

manager_net_if() = [manager_net_if_opt()] <optional> - manager_net_if_opt() = {module, manager_net_if_module()} | {verbosity, verbosity()} | {options, manager_net_if_options()}

Defines options specific for the SNMP manager network interface entity.

For defaults see the options in manager_net_if_opt().

manager_net_if_options() = [manager_net_if_option()] <optional> - 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_backend()}

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

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.

Default is snmpm_net_if.

manager_net_if_filter_options() = [manager_net_if_filter_option()] <optional> - manager_net_if_filter_option() = {module, manager_net_if_filter_module()}

These options are actually specific to the used module. The ones shown here are applicable to the default 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 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 is unable to open an existing database file. terminate means that the agent/manager will terminate, 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> - version() = v1 | v2 | v3

Which SNMP versions shall be accepted/used.

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 [].

inet_backend() = inet | socket <optional> - Choose the inet-backend.

This option make it possible to use net_if (gen_udp) with a different inet-backend ('inet' or 'socket').

Default is inet.

note_store() = [note_store_opt()] <optional> - note_store_opt() = {timeout, note_store_timeout()} | {verbosity, verbosity()}

Specifies the options for the SNMP note store.

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> - audit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} | {size, atl_size()} | {repair, atl_repair()} | {seqno, atl_seqno()}

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.

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.

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.

Modifying the Configuration Files

To to start the application (agent and/or manager), the configuration files must be modified and there are two ways of doing this. Either edit the files manually, or run the configuration tool as follows.

If authentication or encryption is used (SNMPv3 only), start the crypto application.

1> snmp:config().

Simple SNMP configuration tool (version 4.0)
------------------------------------------------
Note: Non-trivial configurations still has to be
      done manually. IP addresses may be entered
      as dront.ericsson.se (UNIX only) or
      123.12.13.23
------------------------------------------------

Configure an agent (y/n)? [y]

Agent system config:
--------------------
1. Agent process priority (low/normal/high) [normal]
2. What SNMP version(s) should be used (1,2,3,1&2,1&2&3,2&3)? [3] 1&2&3
3. Configuration directory (absolute path)? [/ldisk/snmp] /ldisk/snmp/agent/conf
4. Config verbosity (silence/info/log/debug/trace)? [silence]
5. Database directory (absolute path)? [/ldisk/snmp] /ldisk/snmp/agent/db
6. Mib storage type (ets/dets/mnesia)? [ets]
7. Target cache verbosity (silence/info/log/debug/trace)? [silence]
8. Symbolic store verbosity (silence/info/log/debug/trace)? [silence]
9. Local DB verbosity (silence/info/log/debug/trace)? [silence]
10. Local DB repair (true/false/force)? [true]
11. Local DB auto save (infinity/milli seconds)? [5000]
12. Error report module? [snmpa_error_logger]
13. Agent type (master/sub)? [master]
14. Master-agent verbosity (silence/info/log/debug/trace)? [silence] log
15. Shall the agent re-read the configuration files during startup
    (and ignore the configuration database) (true/false)? [true]
16. Multi threaded agent (true/false)? [false] true
17. Check for duplicate mib entries when installing a mib (true/false)? [false]
18. Check for duplicate trap names when installing a mib (true/false)? [false]
19. Mib server verbosity (silence/info/log/debug/trace)? [silence]
20. Mib server cache (true/false)? [true]
21. Note store verbosity (silence/info/log/debug/trace)? [silence]
22. Note store GC timeout? [30000]
23. Shall the agent use an audit trail log (y/n)? [n] y
23b. Audit trail log type (write/read_write)? [read_write]
23c. Where to store the audit trail log? [/ldisk/snmp] /ldisk/snmp/agent/log
23d. Max number of files? [10]
23e. Max size (in bytes) of each file? [10240]
23f. Audit trail log repair (true/false/truncate)? [true]
24. Which network interface module shall be used? [snmpa_net_if]
25. Network interface verbosity (silence/info/log/debug/trace)? [silence] log
25a. Bind the agent IP address (true/false)? [false]
25b. Shall the agents IP address and port be not reusable (true/false)? [false]
25c. Agent request limit (used for flow control) (infinity/pos integer)? [infinity] 32
25d. Receive buffer size of the agent (in bytes) (default/pos integer)? [default]
25e. Send buffer size of the agent (in bytes) (default/pos integer)? [default]
25f. Do you wish to specify a network interface filter module (or use default) [default]

Agent snmp config:
------------------
1. System name (sysName standard variable) [bmk's agent]
2. Engine ID (snmpEngineID standard variable) [bmk's engine]
3. Max message size? [484]
4. The UDP port the agent listens to. (standard 161) [4000]
5. IP address for the agent (only used as id
   when sending traps) [127.0.0.1]
6. IP address for the manager (only this manager
   will have access to the agent, traps are sent
   to this one) [127.0.0.1]
7. To what UDP port at the manager should traps
   be sent (standard 162)? [5000]
8. Do you want a none- minimum- or semi-secure configuration?
   Note that if you chose v1 or v2, you won't get any security for these
   requests (none, minimum, semi_des, semi_aes) [minimum]
making sure crypto server is started...
8b. Give a password of at least length 8. It is used to generate
    private keys for the configuration:  kalle-anka
9. Current configuration files will now be overwritten. Ok (y/n)? [y]

- - - - - - - - - - - - -
Info: 1. SecurityName "initial" has noAuthNoPriv read access
         and authenticated write access to the "restricted"
         subtree.
      2. SecurityName "all-rights" has noAuthNoPriv read/write
         access to the "internet" subtree.
      3. Standard traps are sent to the manager.
      4. Community "public" is mapped to security name "initial".
      5. Community "all-rights" is mapped to security name "all-rights".
The following agent files were written: agent.conf, community.conf,
standard.conf, target_addr.conf, target_params.conf,
notify.conf, vacm.conf and usm.conf
- - - - - - - - - - - - -

Configure a manager (y/n)? [y]

Manager system config:
----------------------
1. Manager process priority (low/normal/high) [normal]
2. What SNMP version(s) should be used (1,2,3,1&2,1&2&3,2&3)? [3] 1&2&3
3. Configuration directory (absolute path)? [/ldisk/snmp] /ldisk/snmp/manager/conf
4. Config verbosity (silence/info/log/debug/trace)? [silence] log
5. Database directory (absolute path)? [/ldisk/snmp] /ldisk/snmp/manager/db
6. Database repair (true/false/force)? [true]
7. Database auto save (infinity/milli seconds)? [5000]
8. Inform request behaviour (auto/user)? [auto]
9. Server verbosity (silence/info/log/debug/trace)? [silence] log
10. Server GC timeout? [30000]
11. Note store verbosity (silence/info/log/debug/trace)? [silence]
12. Note store GC timeout? [30000]
13. Which network interface module shall be used? [snmpm_net_if]
14. Network interface verbosity (silence/info/log/debug/trace)? [silence] log
15. Bind the manager IP address (true/false)? [false]
16. Shall the manager IP address and port be not reusable (true/false)? [false]
17. Receive buffer size of the manager (in bytes) (default/pos integer)? [default]
18. Send buffer size of the manager (in bytes) (default/pos integer)? [default]
19. Shall the manager use an audit trail log (y/n)? [n] y
19b. Where to store the audit trail log? [/ldisk/snmp] /ldisk/snmp/manager/log
19c. Max number of files? [10]
19d. Max size (in bytes) of each file? [10240]
19e. Audit trail log repair (true/false/truncate)? [true]
20. Do you wish to assign a default user [yes] or use
    the default settings [no] (y/n)? [n]

Manager snmp config:
--------------------
1. Engine ID (snmpEngineID standard variable) [bmk's engine]
2. Max message size? [484]
3. IP address for the manager (only used as id
   when sending requests) [127.0.0.1]
4. Port number (standard 162)? [5000]
5. Configure a user of this manager (y/n)? [y]
5b. User id? kalle
5c. User callback module? snmpm_user_default
5d. User (callback) data? [undefined]
5. Configure a user of this manager (y/n)? [y] n
6. Configure an agent handled by this manager (y/n)? [y]
6b. User id? kalle
6c. Target name? [bmk's agent]
6d. Version (1/2/3)? [1] 3
6e. Community string ? [public]
6f. Engine ID (snmpEngineID standard variable) [bmk's engine]
6g. IP address for the agent [127.0.0.1]
6h. The UDP port the agent listens to. (standard 161) [4000]
6i. Retransmission timeout (infinity/pos integer)? [infinity]
6j. Max message size? [484]
6k. Security model (any/v1/v2c/usm)? [any] usm
6l. Security name? ["initial"]
6m. Security level (noAuthNoPriv/authNoPriv/authPriv)? [noAuthNoPriv] authPriv
6. Configure an agent handled by this manager (y/n)? [y] n
7. Configure an usm user handled by this manager (y/n)? [y]
7a. Engine ID [bmk's engine]
7b. User name? hobbes
7c. Security name? [hobbes]
7d. Authentication protocol (no/sha/md5)? [no] sha
7e  Authentication [sha] key (length 0 or 20)? [""] [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16, \
    17,18,19,20]
7d. Priv protocol (no/des/aes)? [no] des
7f  Priv [des] key (length 0 or 16)? [""] 10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25
7. Configure an usm user handled by this manager (y/n)? [y] n
8. Current configuration files will now be overwritten. Ok (y/n)? [y]

- - - - - - - - - - - - -
The following manager files were written: manager.conf, agents.conf , users.conf and usm.conf
- - - - - - - - - - - - -

--------------------
Configuration directory for system file (absolute path)? [/ldisk/snmp]
ok

Starting the application

Start Erlang with the command:

erl -config /tmp/snmp/sys

If authentication or encryption is used (SNMPv3 only), start the crypto application. If this step is forgotten, the agent will not start, but report a {config_error,{unsupported_crypto,_}} error.

1> application:start(crypto).
ok

2> application:start(snmp).
ok

Debugging the application

It is possible to debug every (non-supervisor) process of the application (both agent and manager), possibly with the exception of the netif module(s), which could be supplied by a user of the application). This is done by calling the snmpa:verbosity/2 and snmpm:verbosity/2 function(s) and/or using configuration parameters. The verbosity itself has several _levels: silence | info | log | debug | trace. For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed. Default value is always silence.

3> snmpa:verbosity(master_agent, log).
ok
5> snmpa:verbosity(net_if, log).
ok
6>
%% Example of output from the agent when a get-next-request arrives:
** SNMP NET-IF LOG:
   got packet from {147,12,12,12}:5000

** SNMP NET-IF MPD LOG:
   v1, community: all-rights

** SNMP NET-IF LOG:
   got pdu from {147,12,12,12}:5000 {pdu, 'get-next-request',
                                          62612569,noError,0,
                                          [{varbind,[1,1],'NULL','NULL',1}]}

** SNMP MASTER-AGENT LOG:
   apply: snmp_generic,variable_func,[get,{sysDescr,persistent}]

** SNMP MASTER-AGENT LOG:
   returned: {value,"Erlang SNMP agent"}

** SNMP NET-IF LOG:
   reply pdu: {pdu,'get-response',62612569,noError,0,
                   [{varbind,[1,3,6,1,2,1,1,1,0],
                             'OCTET STRING',
                             "Erlang SNMP agent",1}]}

** SNMP NET-IF INFO: time in agent: 19711 mysec

Other useful function(s) for debugging the agent are:

snmpa:info/0,1 - info is used to retrieve a list of miscellaneous agent information.

snmpa:which_aliasnames/0 - which_aliasnames is used to retrieve a list of all alias-names known to the agent.

snmpa:which_tables/0 - which_tables is used to retrieve a list of all (MIB) tables known to the agent.

snmpa:which_variables/0 - which_variables is used to retrieve a list of all (MIB) variables known to the agent.

snmpa:which_notifications/0 - which_notifications is used to retrieve a list of all (MIB) notifications/traps known to the agent.

snmpa:restart_worker/0,1 - restart_worker is used to restart the worker process of a multi-threaded agent.

snmpa:restart_set_worker/0,1 - restart_set_worker is used to restart the set-worker process of a multi-threaded agent.

snmpa_local_db:print/0,1,2 - For example, this function can show the counters snmpInPkts and snmpOutPkts.

Another useful way to debug the agent is to pretty-print the content of all the tables and/or variables handled directly by the agent. This can be done by simply calling:

snmpa:print_mib_info/0

See snmpa:print_mib_info/0, snmpa:print_mib_tables/0 or snmpa:print_mib_variables/0 for more info.

Definition of Agent Configuration Files

All configuration data must be included in configuration files that are located in the configuration directory. The name of this directory is given in the config_dir configuration parameter. These files are read at start-up, and are used to initialize the SNMPv2-MIB or STANDARD-MIB, SNMP-FRAMEWORK-MIB, SNMP-MPD-MIB, SNMP-VIEW-BASED-ACM-MIB, SNMP-COMMUNITY-MIB, SNMP-USER-BASED-SM-MIB (adjusted according to SNMP-USM-HMAC-SHA2-MIB), SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB (refer to the Management of the Agent for a description of the MIBs).

The files are:

agent.conf: see Agent Information

standard.conf: see System Information

context.conf: see Contexts

community.conf: see Communities

target_addr.conf: see Target Address Definitions

target_params.conf: see Target Parameters Definitions

vacm.conf: see MIB Views for VACM

usm.conf: see Security data for USM

notify.conf: see Notify Definitions

The directory where the configuration files are found is given as a parameter to the agent.

The entry format in all files are Erlang terms, separated by a '.' and a newline. In the following sections, the formats of these terms are described. Comments may be specified as ordinary Erlang comments.

Syntax errors in these files are discovered and reported with the function config_err/2 of the error report module at start-up.

Agent Information

The agent information should be stored in a file called agent.conf.

Each entry is a tuple of size two:

{AgentVariable, Value}.

AgentVariable is one of the variables in SNMP-FRAMEWORK-MIB or one of the internal variables intAgentUDPPort, which defines which UDP port the agent listens to, or intAgentTransports, which defines the transport domains and addresses of the agent.

Value is the value for the variable.

The following example shows an agent.conf file:

{intAgentUDPPort, 4000}.
{intAgentTransports,
 [{transportDomainUdpIpv4, {141,213,11,24}},
  {transportDomainUdpIpv6, {0,0,0,0,0,0,0,1}}]}.
{snmpEngineID, "mbj's engine"}.
{snmpEngineMaxMessageSize, 484}.

These are the supported entries and their value types:

      {snmpEngine,               string()}.                     % Mandatory
      {snmpEngineMaxMessageSize, snmp_framework_mib:max_message_size()}.  % Mandatory
      {intAgentUDPPort,          inet:port_number()}.                      % Optional
      {intAgentTransports,       [snmpa_conf:intAgentTransport()]}.   % Mandatory

If a "traditional" transport is specified (without explicit Kind, handling both requests and traps) for a transport domain, its not possible to also specify a transport (for that domain) with a specific Kind. This is for example, not allowed:

 [{transportDomainUdpIpv4, {{141,213,11,24}, 4000}},
  {transportDomainUdpIpv4, {{141,213,11,24}, 4001}, trap_sender}].

Note that only one transport per kind for each transport domain can be configured.

PortInfo system is used to indicate that the 'system' should choose (the way port number '0' (zero) is normally used). Port info '0' (zero) cannot be used for this, since it is (internally) used to represent the 'default' port number.

In the traditional transport entries, when the Addr value does not contain a port number, the value of intAgentUDPPort is used.

Note that the (new) extended transport entries (including Kind and Opts) must specify port-info as they ignore any value specified by intAgentUDPPort.

Opts is the same as for the net-if process and takes precedence (for that transport) if present. The point is that each transport can have its own socket options.

The value of snmpEngineID is a string, which for a deployed agent should have a very specific structure. See RFC 2271/2571 for details.

Note

The legacy and intermediate variables intAgentIpAddress and intAgentTransportDomain are still supported so old agent.conf files will work.

But they cannot be combined with intAgentTransports.

Contexts

The context information should be stored in a file called context.conf. The default context "" need not be present.

Each row defines a context in the agent. This information is used in the table vacmContextTable in the SNMP-VIEW-BASED-ACM-MIB.

Each entry is a term:

ContextName.

ContextName is a string.

System Information

The system information should be stored in a file called standard.conf.

Each entry is a tuple of size two:

{SystemVariable, Value}.

SystemVariable is one of the variables in the system group, or snmpEnableAuthenTraps.

Value is the value for the variable.

The following example shows a valid standard.conf file:

{sysDescr, "Erlang SNMP agent"}.
{sysObjectID, [1,2,3]}.
{sysContact, "(mbj,eklas)@erlang.ericsson.se"}.
{sysName, "test"}.
{sysServices, 72}.
{snmpEnableAuthenTraps, enabled}.

A value must be provided for all variables, which lack default values in the MIB.

Communities

The community information should be stored in a file called community.conf. It must be present if the agent is configured for SNMPv1 or SNMPv2c.

An SNMP community is a relationship between an SNMP agent and a set of SNMP managers that defines authentication, access control and proxy characteristics.

The corresponding table is snmpCommunityTable in the SNMP-COMMUNITY-MIB.

Each entry is a term:

{CommunityIndex, CommunityName, SecurityName, ContextName, TransportTag}.

CommunityIndex is a non-empty string.

CommunityName is a string.

SecurityName is a string.

ContextName is a string.

TransportTag is a string.

MIB Views for VACM

The information about MIB Views for VACM should be stored in a file called vacm.conf.

The corresponding tables are vacmSecurityToGroupTable, vacmAccessTable and vacmViewTreeFamilyTable in the SNMP-VIEW-BASED-ACM-MIB.

Each entry is one of the terms, one entry corresponds to one row in one of the tables.

{vacmSecurityToGroup, SecModel, SecName, GroupName}.

{vacmAccess, GroupName, Prefix, SecModel, SecLevel, Match, ReadView, WriteView, NotifyView}.

{vacmViewTreeFamily, ViewIndex, ViewSubtree, ViewStatus, ViewMask}.

SecModel is any, v1, v2c, or usm.

SecName is a string.

GroupName is a string.

Prefix is a string.

SecLevel is noAuthNoPriv, authNoPriv, or authPriv

Match is prefix or exact.

ReadView is a string.

WriteView is a string.

NotifyView is a string.

ViewIndex is an integer.

ViewSubtree is a list of integer.

ViewStatus is either included or excluded

ViewMask is either null or a list of ones and zeros. Ones nominate that an exact match is used for this sub-identifier. Zeros are wild-cards which match any sub-identifier. If the mask is shorter than the sub-tree, the tail is regarded as all ones. null is shorthand for a mask with all ones.

Security data for USM

The information about Security data for USM should be stored in a file called usm.conf, which must be present if the agent is configured for SNMPv3.

The corresponding table is usmUserTable in the SNMP-USER-BASED-SM-MIB (adjusted according to SNMP-USM-HMAC-SHA2-MIB).

Each entry is a term:

{EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey}.

EngineID is a string.

UserName is a string.

SecName is a string.

Clone is zeroDotZero or a list of integers.

AuthP is a usmNoAuthProtocol, usmHMACMD5AuthProtocol, usmHMACSHAAuthProtocol, usmHMAC128SHA224AuthProtocol, usmHMAC192SH256AuthProtocol, usmHMAC256SHA384AuthProtocol or usmHMAC384SHA512AuthProtocol.

AuthKeyC is a string.

OwnAuthKeyC is a string.

PrivP is a usmNoPrivProtocol, usmDESPrivProtocol or usmAesCfb128Protocol.

PrivKeyC is a string.

OwnPrivKeyC is a string.

Public is a string.

AuthKey is a list (of integer). This is the User's secret localized authentication key. It is not visible in the MIB. The length (number of octets) of this key needs to be:

16 if usmHMACMD5AuthProtocol.

20 if usmHMACSHAAuthProtocol.

28 if usmHMAC128SHA224AuthProtocol.

32 if usmHMAC192SHA256AuthProtocol.

48 if usmHMAC256SHA384AuthProtocol.

64 if usmHMAC384SHA512AuthProtocol.

PrivKey is a list (of integer). This is the User's secret localized encryption key. It is not visible in the MIB. The length of this key needs to be 16 if usmDESPrivProtocol or usmAesCfb128Protocol is used.

Notify Definitions

The information about Notify Definitions should be stored in a file called notify.conf.

The corresponding table is snmpNotifyTable in the SNMP-NOTIFICATION-MIB.

Each entry is a term:

{NotifyName, Tag, Type}.

NotifyName is a unique non-empty string.

Tag is a string.

Type is trap or inform.

Target Address Definitions

The information about Target Address Definitions should be stored in a file called target_addr.conf.

The corresponding tables are snmpTargetAddrTable in the SNMP-TARGET-MIB and snmpTargetAddrExtTable in the SNMP-COMMUNITY-MIB.

Each entry is a term:

{TargetName, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId}.
or
{TargetName, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize}.

TargetName is a unique non-empty string.

Domain is one of the atoms: transportDomainUdpIpv4 | transportDomainUdpIpv6.

Addr is either an IpAddr or an {IpAddr, IpPort} tuple. IpAddr is either a regular Erlang/OTP ip_address() or a traditional SNMP integer list, and IpPort is an integer.

If IpPort is omitted 162 is used.

Timeout is an integer.

RetryCount is an integer.

TagList is a string.

ParamsName is a string.

EngineId is a string or the atom discovery.

TMask is specified just as Addr or as []. Note in particular that using a list of 6 bytes for IPv4 or 8 words plus 2 bytes for IPv6 are still valid address formats so old configurations will work.

MaxMessageSize is an integer (default: 2048).

The old tuple formats with Ip address and Udp port number found in old configurations still work.

Note that if EngineId has the value discovery, the agent cannot send inform messages to that manager until it has performed the discovery process with that manager.

Target Parameters Definitions

The information about Target Parameters Definitions should be stored in a file called target_params.conf.

The corresponding table is snmpTargetParamsTable in the SNMP-TARGET-MIB.

Each entry is a term:

{ParamsName, MPModel, SecurityModel, SecurityName, SecurityLevel}.

ParamsName is a unique non-empty string.

MPModel is v1, v2c or v3

SecurityModel is v1, v2c, or usm.

SecurityName is a string.

SecurityLevel is noAuthNoPriv, authNoPriv or authPriv.

Definition of Manager Configuration Files

Configuration data may be included in configuration files that is located in the configuration directory. The name of this directory is given in the config_dir configuration parameter. These files are read at start-up.

The directory where the configuration files are found is given as a parameter to the manager.

The entry format in all files are Erlang terms, separated by a '.' and a newline. In the following sections, the formats of these terms are described. Comments may be specified as ordinary Erlang comments.

If syntax errors are discovered in these files they are reported with the function config_err/2 of the error report module at start-up.

Manager Information

The manager information should be stored in a file called manager.conf.

Each entry is a tuple of size two:

{Variable, Value}.

Variable is one of the following:

transports - which defines the transport domains and their addresses for the manager. Mandatory

Value is a list of {Domain, Addr} tuples or Domain atoms.

Domain is one of transportDomainUdpIpv4 or transportDomainUdpIpv6.

Addr is for the currently supported domains either an IpAddr or an {IpAddr, IpPort} tuple.IpAddr is either a regular Erlang/OTP ip_address() or a traditional SNMP integer list and IpPort is an integer.

When Addr does not contain a port number, the value of port is used.

When a Addr is not specified i.e by using only a Domain atom, the host's name is resolved to find the IP address, and the value of port is used.

port - which defines which UDP port the manager uses for communicating with agents. Mandatory if transports does not define a port number for every transport.

engine_id - The SnmpEngineID as defined in SNMP-FRAMEWORK-MIB. Mandatory.

max_message_size - The snmpEngineMaxMessageSize as defined in SNMP-FRAMEWORK-MIB. Mandatory.

Value is the value for the variable.

The legacy and intermediate variables address and domain are still supported so old configurations will work.

The following example shows a manager.conf file:

{transports,       [{transportDomainUdpIpv4, {{141,213,11,24}, 5000}},
                    {transportDomainUdpIpv6, {{0,0,0,0,0,0,0,1}, 5000}}]}.
{engine_id,        "mgrEngine"}.
{max_message_size, 484}.

The value of engine_id is a string, which should have a very specific structure. See RFC 2271/2571 for details.

Users

For each manager user, the manager needs some information. This information is either added in the users.conf config file or by calling the register_user function in run-time.

Each row defines a manager user of the manager.

Each entry is a tuple of size four:

{UserId, UserMod, UserData, DefaultAgentConfig}.

UserId is any term (used to uniquely identify the user).

UserMod is the user callback module (atom).

UserData is any term (passed on to the user when calling the UserMod.

DefaultAgentConfig is a list of default agent config's. These values are used as default values when this user registers agents.

Agents

The information needed to handle agents should be stored in a file called agents.conf. It is also possible to add agents in run-time by calling the register_agent.

Each entry is a tuple:

{UserId, TargetName, Comm, Domain, Addr, EngineID, Timeout, MaxMessageSize, Version, SecModel, SecName, SecLevel}.

UserId is the identity of the manager user responsible for this agent (term).

TargetName is a unique non-empty string.

Comm is the community string (string).

Domain is the transport domain, either transportDomainUdpIpv4 or transportDomainUdpIpv6.

Addr is the address in the transport domain, either an {IpAddr, IpPort} tuple or a traditional SNMP integer list containing port number. IpAddr is either a regular Erlang/OTP ip_address() or a traditional SNMP integer list not containing port number, and IpPort is an integer.

EngineID is the engine-id of the agent (string).

Timeout is re-transmission timeout (infinity | integer).

MaxMessageSize is the max message size for outgoing messages to this agent (integer).

Version is the version (v1 | v2 | v3).

SecModel is the security model (any | v1 | v2c | usm).

SecName is the security name (string).

SecLevel is security level (noAuthNoPriv | authNoPriv | authPriv).

Legacy configurations using tuples without Domain element, as well as with all TDomain, Ip and Port elements still work.

Security data for USM

The information about Security data for USM should be stored in a file called usm.conf, which must be present if the manager wishes to use SNMPv3 when communicating with agents. It is also possible to add usm data in run-time by calling the register_usm_user.

The corresponding table is usmUserTable in the SNMP-USER-BASED-SM-MIB (adjusted according to SNMP-USM-HMAC-SHA2-MIB).

Each entry is a term:

{EngineID, UserName, AuthP, AuthKey, PrivP, PrivKey}.
{EngineID, UserName, SecName, AuthP, AuthKey, PrivP, PrivKey}.

The first case is when we have the identity-function (SecName = UserName).

EngineID is a string.

UserName is a string.

SecName is a string.

AuthP is a usmNoAuthProtocol, usmHMACMD5AuthProtocol, usmHMACSHAAuthProtocol, usmHMAC128SHA224AuthProtocol, usmHMAC192SH256AuthProtocol, usmHMAC256SHA384AuthProtocol or usmHMAC384SHA512AuthProtocol.

AuthKey is a list (of integer). This is the User's secret localized authentication key. It is not visible in the MIB. The length (number of octets) of this key needs to be:

16 if usmHMACMD5AuthProtocol.

20 if usmHMACSHAAuthProtocol.

28 if usmHMAC128SHA224AuthProtocol.

32 if usmHMAC192SHA256AuthProtocol.

48 if usmHMAC256SHA384AuthProtocol.

64 if usmHMAC384SHA512AuthProtocol.

PrivP is a usmNoPrivProtocol, usmDESPrivProtocol or usmAesCfb128Protocol.

PrivKey is a list (of integer). This is the User's secret localized encryption key. It is not visible in the MIB. The length of this key needs to be 16 if usmDESPrivProtocol or usmAesCfb128Protocol is used.

Agent Implementation Example

This Implementation Example section describes how an MIB can be implemented with the SNMP Development Toolkit.

The example shown can be found in the toolkit distribution.

The agent is configured with the configuration tool, using default suggestions for everything but the manager node.

MIB

The MIB used in this example is called EX1-MIB. It contains two objects, a variable with a name and a table with friends.

EX1-MIB DEFINITIONS ::= BEGIN

          IMPORTS
                  experimental   FROM RFC1155-SMI
                  RowStatus      FROM STANDARD-MIB
                  DisplayString  FROM RFC1213-MIB
                  OBJECT-TYPE    FROM RFC-1212
                  ;

          example1       OBJECT IDENTIFIER ::= { experimental 7 }

          myName OBJECT-TYPE
              SYNTAX  DisplayString (SIZE (0..255))
              ACCESS  read-write
              STATUS  mandatory
              DESCRIPTION
                      "My own name"
              ::= { example1 1 }

          friendsTable OBJECT-TYPE
              SYNTAX  SEQUENCE OF FriendsEntry
              ACCESS  not-accessible
              STATUS  mandatory
              DESCRIPTION
                      "A list of friends."
              ::= { example1 4 }

          friendsEntry OBJECT-TYPE
              SYNTAX  FriendsEntry
              ACCESS  not-accessible
              STATUS  mandatory
              DESCRIPTION
                      ""
              INDEX   { fIndex }
              ::= { friendsTable 1 }

          FriendsEntry ::=
              SEQUENCE {
                   fIndex
                      INTEGER,
                   fName
                      DisplayString,
                   fAddress
                      DisplayString,
                   fStatus
                      RowStatus              }

          fIndex OBJECT-TYPE
              SYNTAX  INTEGER
              ACCESS  not-accessible
              STATUS  mandatory
               DESCRIPTION
                      "number of friend"
              ::= { friendsEntry 1 }

          fName OBJECT-TYPE
              SYNTAX  DisplayString (SIZE (0..255))
              ACCESS  read-write
              STATUS  mandatory
              DESCRIPTION
                      "Name of friend"
              ::= { friendsEntry 2 }

          fAddress OBJECT-TYPE
              SYNTAX  DisplayString (SIZE (0..255))
              ACCESS  read-write
              STATUS  mandatory
              DESCRIPTION
                      "Address of friend"
              ::= { friendsEntry 3 }

           fStatus OBJECT-TYPE
              SYNTAX      RowStatus
              ACCESS      read-write
              STATUS      mandatory
              DESCRIPTION
                      "The status of this conceptual row."
              ::= { friendsEntry 4 }

          fTrap TRAP-TYPE
              ENTERPRISE  example1
              VARIABLES   { myName, fIndex }
              DESCRIPTION
                      "This trap is sent when something happens to
                      the friend specified by fIndex."
              ::= 1
END

Default Implementation

Without writing any instrumentation functions, we can compile the MIB and use the default implementation of it. Recall that MIBs imported by "EX1-MIB.mib" must be present and compiled in the current directory ("./STANDARD-MIB.bin","./RFC1213-MIB.bin") when compiling.

unix> erl -config ./sys
1> application:start(snmp).
ok
2> snmpc:compile("EX1-MIB").
No accessfunction for 'friendsTable', using default.
No accessfunction for 'myName', using default.
{ok, "EX1-MIB.bin"}
3> snmpa:load_mibs(snmp_master_agent, ["EX1-MIB"]).
ok

This MIB is now loaded into the agent, and a manager can ask questions. As an example of this, we start another Erlang system and the simple Erlang manager in the toolkit:

1> snmp_test_mgr:start_link([{agent,"dront.ericsson.se"},{community,"all-rights"},
 %% making it understand symbolic names: {mibs,["EX1-MIB","STANDARD-MIB"]}]).
{ok, <0.89.0>}
%% a get-next request with one OID.
2> snmp_test_mgr:gn([[1,3,6,1,3,7]]).
ok
* Got PDU:
[myName,0] = []
%% A set-request (now using symbolic names for convenience)
3> snmp_test_mgr:s([{[myName,0], "Martin"}]).
ok
* Got PDU:
[myName,0] = "Martin"
%% Try the same get-next request again
4> snmp_test_mgr:gn([[1,3,6,1,3,7]]).
ok
* Got PDU:
[myName,0] = "Martin"
%% ... and we got the new value.
%% you can event do row operations. How to add a row:
5> snmp_test_mgr:s([{[fName,0], "Martin"}, {[fAddress,0],"home"}, {[fStatus,0],4}]).
 %% createAndGo
ok
* Got PDU:
[fName,0] = "Martin"
[fAddress,0] = "home"
[fStatus,0] = 4
6> snmp_test_mgr:gn([[myName,0]]).
ok
* Got PDU:
[fName,0] = "Martin"
7> snmp_test_mgr:gn().
ok
* Got PDU:
[fAddress,0] = "home"
8> snmp_test_mgr:gn().
ok
* Got PDU:
[fStatus,0] = 1
9>

Manual Implementation

The following example shows a "manual" implementation of the EX1-MIB in Erlang. In this example, the values of the objects are stored in an Erlang server. The server has a 2-tuple as loop data, where the first element is the value of variable myName, and the second is a sorted list of rows in the table friendsTable. Each row is a 4-tuple.

Note

There are more efficient ways to create tables manually, i.e. to use the module snmp_index.

Code

-module(ex1).
-author('dummy@flop.org').
%% External exports
-export([start/0, my_name/1, my_name/2, friends_table/3]).
%% Internal exports
-export([init/0]).
-define(status_col, 4).
-define(active, 1).
-define(notInService, 2).
-define(notReady, 3).
-define(createAndGo, 4).   % Action; written, not read
-define(createAndWait, 5). % Action; written, not read
-define(destroy, 6).       % Action; written, not read
start() ->
    spawn(ex1, init, []).
%%----------------------------------------------------------------
%% Instrumentation function for variable myName.
%% Returns: (get) {value, Name}
%%          (set) noError
%%----------------------------------------------------------------
my_name(get) ->
    ex1_server ! {self(), get_my_name},
    Name = wait_answer(),
    {value, Name}.
my_name(set, NewName) ->
    ex1_server ! {self(), {set_my_name, NewName}},
    noError.
%%----------------------------------------------------------------
%% Instrumentation function for table friendsTable.
%%----------------------------------------------------------------
friends_table(get, RowIndex, Cols) ->
    case get_row(RowIndex) of
   {ok, Row} ->
        get_cols(Cols, Row);
   _  ->
        {noValue, noSuchInstance}
    end;
friends_table(get_next, RowIndex, Cols) ->
    case get_next_row(RowIndex) of
   {ok, Row} ->
        get_next_cols(Cols, Row);
   _  ->
       case get_next_row([]) of
     {ok, Row} ->
         % Get next cols from first row.
         NewCols = add_one_to_cols(Cols),
         get_next_cols(NewCols, Row);
     _  ->
        end_of_table(Cols)
        end
    end;
%%----------------------------------------------------------------
%% If RowStatus is set, then:
%%    *) If set to destroy, check that row does exist
%%    *) If set to createAndGo, check that row does not exist AND
%%         that all columns are given values.
%%    *) Otherwise, error (for simplicity).
%% Otherwise, row is modified; check that row exists.
%%----------------------------------------------------------------
friends_table(is_set_ok, RowIndex, Cols) ->
    RowExists =
   case get_row(RowIndex) of
        {ok, _Row} -> true;
       _ -> false
   end,
    case is_row_status_col_changed(Cols) of
   {true, ?destroy} when RowExists == true ->
        {noError, 0};
   {true, ?createAndGo} when RowExists == false,
                                 length(Cols) == 3 ->
        {noError, 0};
   {true, _} ->
       {inconsistentValue, ?status_col};
   false when RowExists == true ->
        {noError, 0};
   _ ->
        [{Col, _NewVal} | _Cols] = Cols,
       {inconsistentName, Col}
      end;
friends_table(set, RowIndex, Cols) ->
    case is_row_status_col_changed(Cols) of
   {true, ?destroy} ->
        ex1_server ! {self(), {delete_row, RowIndex}};
   {true, ?createAndGo} ->
       NewRow = make_row(RowIndex, Cols),
        ex1_server ! {self(), {add_row, NewRow}};
   false ->
       {ok, Row} = get_row(RowIndex),
        NewRow = merge_rows(Row, Cols),
    ex1_server ! {self(), {delete_row, RowIndex}},
       ex1_server ! {self(), {add_row, NewRow}}
   end,
    {noError, 0}.

%%----------------------------------------------------------------
%% Make a list of {value, Val} of the Row and Cols list.
%%----------------------------------------------------------------
get_cols([Col | Cols], Row) ->
    [{value, element(Col, Row)} | get_cols(Cols, Row)];
get_cols([], _Row) ->
    [].
%%----------------------------------------------------------------
%% As get_cols, but the Cols list may contain invalid column
%% numbers. If it does, we must find the next valid column,
%% or return endOfTable.
%%----------------------------------------------------------------
get_next_cols([Col | Cols], Row) when Col < 2 ->
    [{[2, element(1, Row)], element(2, Row)} |
     get_next_cols(Cols, Row)];
get_next_cols([Col | Cols], Row) when Col > 4 ->
    [endOfTable |
     get_next_cols(Cols, Row)];
get_next_cols([Col | Cols], Row) ->
    [{[Col, element(1, Row)], element(Col, Row)} |
     get_next_cols(Cols, Row)];
get_next_cols([], _Row) ->
    [].
%%----------------------------------------------------------------
%% Make a list of endOfTable with as many elems as Cols list.
%%----------------------------------------------------------------
end_of_table([Col | Cols]) ->
    [endOfTable | end_of_table(Cols)];
end_of_table([]) ->
    [].
add_one_to_cols([Col | Cols]) ->
    [Col + 1 | add_one_to_cols(Cols)];
add_one_to_cols([]) ->
    [].
is_row_status_col_changed(Cols) ->
    case lists:keysearch(?status_col, 1, Cols) of
   {value, {?status_col, StatusVal}} ->
        {true, StatusVal};
   _ -> false
    end.
get_row(RowIndex) ->
    ex1_server ! {self(), {get_row, RowIndex}},
    wait_answer().
get_next_row(RowIndex) ->
    ex1_server ! {self(), {get_next_row, RowIndex}},
    wait_answer().
wait_answer() ->
    receive
   {ex1_server, Answer} ->
     Answer
    end.
%%%---------------------------------------------------------------
%%% Server code follows
%%%---------------------------------------------------------------
init() ->
    register(ex1_server, self()),
    loop("", []).

loop(MyName, Table) ->
    receive
   {From, get_my_name} ->
        From ! {ex1_server, MyName},
       loop(MyName, Table);
   {From, {set_my_name, NewName}} ->
        loop(NewName, Table);
   {From, {get_row, RowIndex}} ->
       Res = table_get_row(Table, RowIndex),
       From ! {ex1_server, Res},
       loop(MyName, Table);
   {From, {get_next_row, RowIndex}} ->
       Res = table_get_next_row(Table, RowIndex),
        From ! {ex1_server, Res},
       loop(MyName, Table);
   {From, {delete_row, RowIndex}} ->
    NewTable = table_delete_row(Table, RowIndex),
       loop(MyName, NewTable);
   {From, {add_row, NewRow}} ->
       NewTable = table_add_row(Table, NewRow),
       loop(MyName, NewTable)
    end.
%%%---------------------------------------------------------------
%%% Functions for table operations. The table is represented as
%%% a list of rows.
%%%---------------------------------------------------------------
table_get_row([{Index, Name, Address, Status} | _], [Index]) ->
    {ok, {Index, Name, Address, Status}};
table_get_row([H | T], RowIndex) ->
    table_get_row(T, RowIndex);
table_get_row([], _RowIndex) ->
    no_such_row.
table_get_next_row([Row | T], []) ->
    {ok, Row};
table_get_next_row([Row | T], [Index | _])
when element(1, Row) > Index ->
    {ok, Row};
table_get_next_row([Row | T], RowIndex) ->
    table_get_next_row(T, RowIndex);
table_get_next_row([], RowIndex) ->
    endOfTable.
table_delete_row([{Index, _, _, _} | T], [Index]) ->
    T;
table_delete_row([H | T], RowIndex) ->
    [H | table_delete_row(T, RowIndex)];
table_delete_row([], _RowIndex) ->
    [].
table_add_row([Row | T], NewRow)
  when element(1, Row) > element(1, NewRow) ->
    [NewRow, Row | T];
table_add_row([H | T], NewRow) ->
    [H | table_add_row(T, NewRow)];
table_add_row([], NewRow) ->
    [NewRow].
make_row([Index], [{2, Name}, {3, Address} | _]) ->
    {Index, Name, Address, ?active}.
merge_rows(Row, [{Col, NewVal} | T]) ->
    merge_rows(setelement(Col, Row, NewVal), T);
merge_rows(Row, []) ->
    Row.

Association File

The association file EX1-MIB.funcs for the real implementation looks as follows:

{myName, {ex1, my_name, []}}.
{friendsTable, {ex1, friends_table, []}}.

Transcript

To use the real implementation, we must recompile the MIB and load it into the agent.

1> application:start(snmp).
ok
2> snmpc:compile("EX1-MIB").
{ok,"EX1-MIB.bin"}
3> snmpa:load_mibs(snmp_master_agent, ["EX1-MIB"]).
ok
4> ex1:start().
<0.115.0>
%% Now all requests operates on this "real" implementation.
%% The output from the manager requests will *look* exactly the
%% same as for the default implementation.

Trap Sending

How to send a trap by sending the fTrap from the master agent is shown in this section. The master agent has the MIB EX1-MIB loaded, where the trap is defined. This trap specifies that two variables should be sent along with the trap, myName and fIndex. fIndex is a table column, so we must provide its value and the index for the row in the call to snmpa:send_notification2/3. In the example below, we assume that the row in question is indexed by 2 (the row with fIndex 2).

we use a simple Erlang SNMP manager, which can receive traps.

[MANAGER]
1> snmp_test_mgr:start_link([{agent,"dront.ericsson.se"},{community,"public"}
 %% does not have write-access
1>{mibs,["EX1-MIB","STANDARD-MIB"]}]).
{ok, <0.100.0>}
2> snmp_test_mgr:s([{[myName,0], "Klas"}]).
ok
* Got PDU:
Received a trap:
      Generic: 4       %% authenticationFailure
   Enterprise: [iso,2,3]
     Specific: 0
   Agent addr: [123,12,12,21]
    TimeStamp: 42993
2>
[AGENT]
3> SendOpts = [{receiver, no_receiver}, {varbinds, [{fIndex,[2],2}]}, {name, "standard trap"}, {context, ""}],
4> snmpa:send_notification2(snmp_master_agent, fTrap, SendOpts).
[MANAGER]
2>
* Got PDU:
Received a trap:
      Generic: 6
   Enterprise: [example1]
     Specific: 1
   Agent addr: [123,12,12,21]
    TimeStamp: 69649
[myName,0] = "Martin"
[fIndex,2] = 2
2>

Manager Implementation Example

This Implementation Example section describes how a simple manager can be implemented with the SNMP Development Toolkit.

The example shown, ex2, can be found in the toolkit distribution.

This example has two functions:

A simple example of how to use the manager component of the SNMP Development Toolkit.

A simple example of how to write agent test cases, using the new manager.

The example manager

The example manager, snmp_ex2_manager, is a simple example of how to implement an snmp manager using the manager component of the SNMP Development Toolkit.

The module exports the following functions:

start_link/0, start_link/1

stop/0

agent/2, agent/3

sync_get/2, sync_get/3

sync_get_next/2, sync_get_next/3

sync_get_bulk/4, sync_get_bulk/5

sync_set/2, sync_set/3

oid_to_name/1

This module is also used by the test module described in the next section.

A simple standard test

This simple standard test, snmp_ex2_simple_standard_test, a module which, using the snmp_ex2_manager described in the previous section, implements a simple agent test utility.

Instrumentation Functions

A user-defined instrumentation function for each object attaches the managed objects to real resources. This function is called by the agent on a get or set operation. The function could read some hardware register, perform a calculation, or whatever is necessary to implement the semantics associated with the conceptual variable. These functions must be written both for scalar variables and for tables. They are specified in the association file, which is a text file. In this file, the OBJECT IDENTIFIER, or symbolic name for each managed object, is associated with an Erlang tuple {Module,``Function, ListOfExtraArguments}.

When a managed object is referenced in an SNMP operation, the associated {Module, Function, ListOfExtraArguments} is called. The function is applied to some standard arguments (for example, the operation type) and the extra arguments supplied by the user.

Instrumentation functions must be written for get and set for scalar variables and tables, and for get-next for tables only. The get-bulk operation is translated into a series of calls to get-next.

Instrumentation Functions

The following sections describe how the instrumentation functions should be defined in Erlang for the different operations. In the following, RowIndex is a list of key values for the table, and Column is a column number.

These functions are described in detail in Definition of Instrumentation Functions.

New / Delete Operations

For scalar variables:

variable_access(new [, ExtraArg1, ...])
variable_access(delete [, ExtraArg1, ...])

For tables:

table_access(new [, ExtraArg1, ...])
table_access(delete [, ExtraArg1, ...])

These functions are called for each object in an MIB when the MIB is unloaded or loaded, respectively.

Get Operation

For scalar variables:

variable_access(get [, ExtraArg1, ...])

For tables:

table_access(get,RowIndex,Cols [,ExtraArg1, ...])

Cols is a list of Column. The agent will sort incoming variables so that all operations on one row (same index) will be supplied at the same time. The reason for this is that a database normally retrieves information row by row.

These functions must return the current values of the associated variables.

Set Operation

For scalar variables:

variable_access(set, NewValue [, ExtraArg1, ...])

For tables:

table_access(set, RowIndex, Cols [, ExtraArg1,..])

Cols is a list of tuples {Column, NewValue}.

These functions returns noError if the assignment was successful, otherwise an error code.

Is-set-ok Operation

As a complement to the set operation, it is possible to specify a test function. This function has the same syntax as the set operation above, except that the first argument is is_set_ok instead of set. This function is called before the variable is set. Its purpose is to ensure that it is permissible to set the variable to the new value.

variable_access(is_set_ok, NewValue [, ExtraArg1, ...])

For tables:

table_access(set, RowIndex, Cols [, ExtraArg1,..])

Cols is a list of tuples {Column, NewValue}.

Undo Operation

A function which has been called with is_set_ok will be called again, either with set if there was no error, or with undo, if an error occurred. In this way, resources can be reserved in the is_set_ok operation, released in the undo operation, or made permanent in the set operation.

variable_access(undo, NewValue [, ExtraArg1, ...])

For tables:

table_access(set, RowIndex, Cols [, ExtraArg1,..])

Cols is a list of tuples {Column, NewValue}.

GetNext Operation

The GetNext Operation operation should only be defined for tables since the agent can find the next instance of plain variables in the MIB and call the instrumentation with the get operation.

table_access(get_next, RowIndex, Cols [, ExtraArg1, ...])

Cols is a list of integers, all greater than or equal to zero. This indicates that the instrumentation should find the next accessible instance. This function returns the tuple {NextOid, NextValue}, or endOfTable. NextOid should be the lexicographically next accessible instance of a managed object in the table. It should be a list of integers, where the first integer is the column, and the rest of the list is the indices for the next row. If endOfTable is returned, the agent continues to search for the next instance among the other variables and tables.

RowIndex may be an empty list, an incompletely specified row index, or the index for an unspecified row.

This operation is best described with an example.

GetNext Example

A table called myTable has five columns. The first two are keys (not accessible), and the table has three rows. The instrumentation function for this table is called my_table.

Note

N/A means not accessible.

The manager issues the following getNext request:

getNext{ myTable.myTableEntry.3.1.1,
         myTable.myTableEntry.5.1.1 }

Since both operations involve the 1.1 index, this is transformed into one call to my_table:

my_table(get_next, [1, 1], [3, 5])

In this call, [1, 1] is the RowIndex, where key 1 has value 1, and key 2 has value 1, and [3, 5] is the list of requested columns. The function should now return the lexicographically next elements:

[{[3, 1, 2], d}, {[5, 1, 2], f}]

This is illustrated in the following table:

The manager now issues the following getNext request:

getNext{ myTable.myTableEntry.3.2.1,
         myTable.myTableEntry.5.2.1 }

This is transformed into one call to my_table:

my_table(get_next, [2, 1], [3, 5])

The function should now return:

[{[4, 1, 1], b}, endOfTable]

This is illustrated in the following table:

The manager now issues the following getNext request:

getNext{ myTable.myTableEntry.3.1.2,
         myTable.myTableEntry.4.1.2 }

This will be transform into one call to my_table:

my_table(get_next, [1, 2], [3, 4])

The function should now return:

[{[3, 2, 1], g}, {[5, 1, 1], c}]

This is illustrated in the following table:

The manager now issues the following getNext request:

getNext{ myTable.myTableEntry,
         myTable.myTableEntry.1.3.2 }

This will be transform into two calls to my_table:

my_table(get_next, [], [0]) and
my_table(get_next, [3, 2], [1])

The function should now return:

[{[3, 1, 1], a}] and
[{[3, 1, 1], a}]

In both cases, the first accessible element in the table should be returned. As the key columns are not accessible, this means that the third column is the first row.

Note

Normally, the functions described above behave exactly as shown, but they are free to perform other actions. For example, a get-request may have side effects such as setting some other variable, perhaps a global lastAccessed variable.

Using the ExtraArgument

The ListOfExtraArguments can be used to write generic functions. This list is appended to the standard arguments for each function. Consider two read-only variables for a device, ipAdr and name with object identifiers 1.1.23.4 and 1.1.7 respectively. To access these variables, one could implement the two Erlang functions ip_access and name_access, which will be in the MIB. The functions could be specified in a text file as follows:

{ipAdr, {my_module, ip_access, []}}.
% Or using the oid syntax for 'name'
{[1,1,7], {my_module, name_access, []}}.

The ExtraArgument parameter is the empty list. For example, when the agent receives a get-request for the ipAdr variable, a call will be made to ip_access(get). The value returned by this function is the answer to the get-request.

If ip_access and name_access are implemented similarly, we could write a generic_access function using the ListOfExtraArguments:

{ipAdr, {my_module, generic_access, ['IPADR']}}.
% The mnemonic 'name' is more convenient than 1.1.7
{name, {my_module, generic_access, ['NAME']}}.

When the agent receives the same get-request as above, a call will be made to generic_access(get,'IPADR').

Yet another possibility, closer to the hardware, could be:

{ipAdr, {my_module, generic_access, [16#2543]}}.
{name, {my_module, generic_access, [16#A2B3]}}.

Default Instrumentation

When the MIB definition work is finished, there are two major issues left.

Implementing the MIB

Implementing a Manager Application.

Implementing an MIB can be a tedious task. Most probably, there is a need to test the agent before all tables and variables are implemented. In this case, the default instrumentation functions are useful. The toolkit can generate default instrumentation functions for variables as well as for tables. Consequently, a running prototype agent, which can handle set, get, get-next and table operations, is generated without any programming.

The agent stores the values in an internal volatile database, which is based on the standard module ets. However, it is possible to let the MIB compiler generate functions which use an internal, persistent database, or the Mnesia DBMS. Refer to the Mnesia User Guide and the Reference Manual, section SNMP, module snmp_generic for more information.

When parts of the MIB are implemented, you recompile it and continue on by using default functions. With this approach, the SNMP agent can be developed incrementally.

The default instrumentation allows the application on the manager side to be developed and tested simultaneously with the agent. As soon as the ASN.1 file is completed, let the MIB compiler generate a default implementation and develop the management application from this.

Table Operations

The generation of default functions for tables works for tables which use the RowStatus textual convention from SNMPv2, defined in STANDARD-MIB and SNMPv2-TC.

Note

We strongly encourage the use of the RowStatus convention for every table that can be modified from the manager, even for newly designed SNMPv1 MIBs. In SNMPv1, everybody has invented their own scheme for emulating table operations, which has led to numerous inconsistencies. The convention in SNMPv2 is flexible and powerful and has been tested successfully. If the table is read only, no RowStatus column should be used.

Atomic Set

In SNMP, the set operation is atomic. Either all variables which are specified in a set operation are changed, or none are changed. Therefore, the set operation is divided into two phases. In the first phase, the new value of each variable is checked against the definition of the variable in the MIB. The following definitions are checked:

the type

the length

the range

the variable is writable and within the MIB view.

At the end of phase one, the user defined is_set_ok functions are called for each scalar variable, and for each group of table operations.

If no error occurs, the second phase is performed. This phase calls the user defined set function for all variables.

If an error occurs, either in the is_set_ok phase, or in the set phase, all functions which were called with is_set_ok but not set, are called with undo.

There are limitations with this transaction mechanism. If complex dependencies exist between variables, for example between month and day, another mechanism is needed. Setting the date to 'Feb 31' can be avoided by a somewhat more generic transaction mechanism. You can continue and find more and more complex situations and construct an N-phase set-mechanism. This toolkit only contains a trivial mechanism.

The most common application of transaction mechanisms is to keep row operations together. Since our agent sorts row operations, the mechanism implemented in combination with the RowStatus (particularly 'createAndWait' value) solve most problems elegantly.

Definition of Instrumentation Functions

The section Definition of Instrumentation Functions describes the user defined functions, which the agent calls at different times.

Variable Instrumentation

For scalar variables, a function f(Operation, ...) must be defined.

The Operation can be new, delete, get, is_set_ok, set, or undo.

In case of an error, all instrumentation functions may return either an SNMPv1 or an SNMPv2 error code. If it returns an SNMPv2 code, it is converted into an SNMPv1 code before it is sent to a SNMPv1 manager. It is recommended to use the SNMPv2 error codes for all instrumentation functions, as these provide more details. See Appendix A for a description of error code conversions.

f(new [, ExtraArgs])

The function f(new [, ExtraArgs]) is called for each variable in the MIB when the MIB is loaded into the agent. This makes it possible to perform necessary initialization.

This function is optional. The return value is discarded.

f(delete [, ExtraArgs])

The function f(delete [, ExtraArgs]) is called for each object in an MIB when the MIB is unloaded from the agent. This makes it possible to perform necessary clean-up.

This function is optional. The return value is discarded.

f(get [, ExtraArgs])

The function f(get [, ExtraArgs]) is called when a get-request or a get-next request refers to the variable.

This function is mandatory.

Valid Return Values

{value, Value}. The Value must be of correct type, length and within ranges, otherwise genErr is returned in the response PDU. If the object is an enumerated integer, the symbolic enum value may be used as an atom. If the object is of type BITS, the return value shall be an integer or a list of bits that are set.

{noValue, noSuchName}(SNMPv1)

{noValue, noSuchObject | noSuchInstance}(SNMPv2)

genErr. Used if an error occurred. Note, this should be an internal processing error, e.g. a caused by a programming fault somewhere. If the variable does not exist, use {noValue, noSuchName} or {noValue, noSuchInstance}.

f(is_set_ok, NewValue [, ExtraArgs])

The function f(is_set_ok, NewValue [, ExtraArgs]) is called in phase one of the set-request processing so that the new value can be checked for inconsistencies.

NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used.

This function is optional.

If this function is called, it will be called again, either with undo or with set as first argument.

Valid return values

noError

badValue | noSuchName | genErr(SNMPv1)

noAccess | noCreation | inconsistentValue | resourceUnavailable | inconsistentName | genErr(SNMPv2)

f(undo, NewValue [, ExtraArgs])

If an error occurred, this function is called after the is_set_ok function is called. If set is called for this object, undo is not called.

NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used.

This function is optional.

Valid return values

noError

genErr(SNMPv1)

undoFailed | genErr(SNMPv2)

f(set, NewValue [, ExtraArgs])

This function is called to perform the set in phase two of the set-request processing. It is only called if the corresponding is_set_ok function is present and returns noError.

NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used.

This function is mandatory.

Valid return values

noError

genErr(SNMPv1)

commitFailed | undoFailed | genErr(SNMPv2)

Table Instrumentation

For tables, a f(Operation, ...) function should be defined (the function shown is exemplified with f).

The Operation can be new, delete, get, next, is_set_ok, undo or set.

In case of an error, all instrumentation functions may return either an SNMPv1 or an SNMPv2 error code. If it returns an SNMPv2 code, it is converted into an SNMPv1 code before it is sent to a SNMPv1 manager. It is recommended to use the SNMPv2 error codes for all instrumentation functions, as these provide more details. See Appendix A for a description of error code conversions.

f(new [, ExtraArgs])

The function f(new [, ExtraArgs]) is called for each object in an MIB when the MIB is loaded into the agent. This makes it possible to perform the necessary initialization.

This function is optional. The return value is discarded.

f(delete [, ExtraArgs])

The function f(delete [, ExtraArgs]) is called for each object in an MIB when the MIB is unloaded from the agent. This makes it possible to perform any necessary clean-up.

This function is optional. The return value is discarded.

f(get, RowIndex, Cols [, ExtraArgs])

The function f(get, RowIndex, Cols [, ExtraArgs]) is called when a get-request refers to a table.

This function is mandatory.

Arguments

RowIndex is a list of integers which define the key values for the row. The RowIndex is the list representation (list of integers) which follow the Cols integer in the OBJECT IDENTIFIER.

Cols is a list of integers which represent the column numbers. The Cols are sorted by increasing value and are guaranteed to be valid column numbers.

Valid Return Values

A list with as many elements as the Cols list, where each element is the value of the corresponding column. Each element can be:

{value, Value}. The Value must be of correct type, length and within ranges, otherwise genErr is returned in the response PDU. If the object is an enumerated integer, the symbolic enum value may be used (as an atom). If the object is of type BITS, the return value shall be an integer or a list of bits that are set.

{noValue, noSuchName}(SNMPv1)

{noValue, noSuchObject | noSuchInstance}(SNMPv2)

{noValue, Error}. If the row does not exist, because all columns have {noValue, Error}), the single tuple {noValue, Error} can be returned. This is a shorthand for a list with all elements {noValue, Error}.

genErr. Used if an error occurred. Note that this should be an internal processing error, e.g. a caused by a programming fault somewhere. If some column does not exist, use {noValue, noSuchName} or {noValue, noSuchInstance}.

f(get_next, RowIndex, Cols [, ExtraArgs])

The function f(get_next, RowIndex, Cols [, ExtraArgs]) is called when a get-next- or a get-bulk-request refers to the table.

The RowIndex argument may refer to an existing row or a non-existing row, or it may be unspecified. The Cols list may refer to inaccessible columns or non-existing columns. For each column in the Cols list, the corresponding next instance is determined, and the last part of its OBJECT IDENTIFIER and its value is returned.

This function is mandatory.

Arguments

RowIndex is a list of integers (possibly empty) that defines the key values for a row. The RowIndex is the list representation (list of integers), which follow the Cols integer in the OBJECT IDENTIFIER.

Cols is a list of integers, greater than or equal to zero, which represents the column numbers.

Valid Return Values

A list with as many elements as the Cols list Each element can be:

{NextOid, NextValue}, where NextOid is the lexicographic next OBJECT IDENTIFIER for the corresponding column. This should be specified as the OBJECT IDENTIFIER part following the table entry. This means that the first integer is the column number and the rest is a specification of the keys. NextValue is the value of this element.

endOfTable if there are no accessible elements after this one.

{genErr, Column} where Column denotes the column that caused the error. Column must be one of the columns in the Cols list. Note that this should be an internal processing error, e.g. a caused by a programming fault somewhere. If some column does not exist, you must return the next accessible element (or endOfTable).

f(is_set_ok, RowIndex, Cols [, ExtraArgs])

The function f(is_set_ok, RowIndex, Cols [, ExtraArgs]) is called in phase one of the set-request processing so that new values can be checked for inconsistencies.

If the function is called, it will be called again with undo, or with set as first argument.

This function is optional.

Arguments

RowIndex is a list of integers which define the key values for the row. The RowIndex is the list representation (list of integers) which follow the Cols integer in the OBJECT IDENTIFIER.

Cols is a list of {Column, NewValue}, where Column is an integer, and NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used. The list is sorted by Column (increasing) and each Column is guaranteed to be a valid column number.

Valid Return Values

{noError, 0}

{Error, Column}, where Error is the same as for is_set_ok for variables, and Column denotes the faulty column. Column must be one of the columns in the Cols list.

f(undo, RowIndex, Cols [, ExtraArgs])

If an error occurs, The function f(undo, RowIndex, Cols [, ExtraArgs]) is called after the is_set_ok function. If set is called for this object, undo is not called.

This function is optional.

Arguments

RowIndex is a list of integers which define the key values for the row. The RowIndex is the list representation (list of integers) which follow the Cols integer in the OBJECT IDENTIFIER.

Cols is a list of {Column, NewValue}, where Column is an integer, and NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used. The list is sorted by Column (increasing) and each Column is guaranteed to be a valid column number.

Valid Return Values

{noError, 0}

{Error, Column} where Error is the same as for undo for variables, and Column denotes the faulty column. Column must be one of the columns in the Cols list.

f(set, RowIndex, Cols [, ExtraArgs])

The function f(set, RowIndex, Cols [, ExtraArgs]) is called to perform the set in phase two of the set-request processing. It is only called if the corresponding is_set_ok function did not exist, or returned {noError, 0}.

This function is mandatory.

Arguments

RowIndex is a list of integers that define the key values for the row. The RowIndex is the list representation (list of integers) which follow the Cols integer in the OBJECT IDENTIFIER.

Cols is a list of {Column, NewValue}, where Column is an integer, and NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used. The list is sorted by Column (increasing) and each Column is guaranteed to be a valid column number.

Valid Return Values

{noError, 0}

{Error, Column} where Error is the same as set for variables, and Column denotes the faulty column. Column must be one of the columns in the Cols list.

Definition of Agent Net if

The Network Interface (Net If) process delivers SNMP PDUs to a master agent, and receives SNMP PDUs from the master agent. The most common behaviour of a Net if process is that is receives bytes from a network, decodes them into an SNMP PDU, which it sends to a master agent. When the master agent has processed the PDU, it sends a response PDU to the Net if process, which encodes the PDU into bytes and transmits the bytes onto the network.

However, that simple behaviour can be modified in numerous ways. For example, the Net if process can apply some kind of encrypting/decrypting scheme on the bytes or act as a proxy filter, which sends some packets to a proxy agent and some packets to the master agent.

It is also possible to write your own Net if process. The default Net if process is implemented in the module snmpa_net_if and it uses UDP as the transport protocol i.e the transport domains transportDomainUdpIpv4 and/or transportDomainUdpIpv6.

This section describes how to write a Net if process.

Mandatory Functions

A Net if process must implement the SNMP agent network interface behaviour.

Messages

The section Messages describes mandatory messages, which Net If must send and be able to receive.

In this section an Address field is a {Domain, Addr} tuple where Domain is transportDomainUdpIpv4 or transportDomainUdpIpv4, and Addr is an {IpAddr,IpPort} tuple.

Outgoing Messages

Net if must send the following message when it receives an SNMP PDU from the network that is aimed for the MasterAgent:

MasterAgent ! {snmp_pdu, Vsn, Pdu, PduMS, ACMData, From, Extra}

Vsn is either 'version-1', 'version-2', or 'version-3'.

Pdu is an SNMP PDU record, as defined in snmp_types.hrl, with the SNMP request.

PduMS is the Maximum Size of the response Pdu allowed. Normally this is returned from snmpa_mpd:process_packet (see Reference Manual).

ACMData is data used by the Access Control Module in use. Normally this is returned from snmpa_mpd:process_packet (see Reference Manual).

From is the source Address.

Extra is any term the Net if process wishes to send to the agent. This term can be retrieved by the instrumentation functions by calling snmp:current_net_if_data(). This data is also sent back to the Net if process when the agent generates a response to the request.

The following message is used to report that a response to a request has been received. The only request an agent can send is an Inform-Request.

Pid ! {snmp_response_received, Vsn, Pdu, From}

Pid is the Process that waits for the response for the request. The Pid was specified in the send_pdu_req message (see below).

Vsn is either 'version-1', 'version-2', or 'version-3'.

Pdu is the SNMP Pdu received

From is the source Address.

Incoming Messages

This section describes the incoming messages which a Net if process must be able to receive.

{snmp_response, Vsn, Pdu, Type, ACMData, To, Extra}

This message is sent to the Net if process from a master agent as a response to a previously received request.

Vsn is either 'version-1', 'version-2', or 'version-3'.

Pdu is an SNMP PDU record (as defined in snmp_types.hrl) with the SNMP response.

Type is the #pdu.type of the original request.

ACMData is data used by the Access Control Module in use. Normally this is just sent to snmpa_mpd:generate_response_message (see Reference Manual).

To is the destination Address that comes from the From field in the corresponding snmp_pdu message previously sent to the MasterAgent.

Extra is the term that the Net if process sent to the agent when the request was sent to the agent.

{discarded_pdu, Vsn, ReqId, ACMData, Variable, Extra}

This message is sent from a master agent if it for some reason decided to discard the pdu.

Vsn is either 'version-1', 'version-2', or 'version-3'.

ReqId is the request id of the original request.

ACMData is data used by the Access Control Module in use. Normally this is just sent to snmpa_mpd:generate_response_message (see Reference Manual).

Variable is the name of an snmp counter that represents the error, e.g. snmpInBadCommunityUses.

Extra is the term that the Net if process sent to the agent when the request was sent to the agent.

{send_pdu, Vsn, Pdu, MsgData, To, Extra}

This message is sent from a master agent when a trap is to be sent.

Vsn is either 'version-1', 'version-2', or 'version-3'.

Pdu is an SNMP PDU record (as defined in snmp_types.hrl) with the SNMP response.

MsgData is the message specific data used in the SNMP message. This value is normally sent to snmpa_mpd:generate_msg/5. In SNMPv1 and SNMPv2c, this message data is the community string. In SNMPv3, it is the context information.

To is a list of {Address, SecData} tuples i.e the destination addresses and their corresponding security parameters. This value is normally sent to snmpa_mpd:generate_msg/5.

Extra is any term that the notification sender wishes to pass to the Net if process when sending a notification (see send notification for more info).

{send_pdu_req, Vsn, Pdu, MsgData, To, Pid, Extra}

This message is sent from a master agent when a request is to be sent. The only request an agent can send is Inform-Request. The net if process needs to remember the request id and the Pid, and when a response is received for the request id, send it to Pid, using a snmp_response_received message.

Vsn is either 'version-1', 'version-2', or 'version-3'.

Pdu is an SNMP PDU record (as defined in snmp_types.hrl) with the SNMP response.

MsgData is the message specific data used in the SNMP message. This value is normally sent to snmpa_mpd:generate_msg/5. In SNMPv1 and SNMPv2c, this message data is the community string. In SNMPv3, it is the context information.

To is a list of {Address, SecData} tuples i.e the destination addresses and their corresponding security parameters. This value is normally sent to snmpa_mpd:generate_msg/5.

Pid is a process identifier.

Extra is any term that the notification sender wishes to pass to the Net if process when sending a notification (see send notification for more info).

Notes

Since the Net if process is responsible for encoding and decoding of SNMP messages, it must also update the relevant counters in the SNMP group in MIB-II. It can use the functions in the module snmpa_mpd for this purpose (refer to the Reference Manual, section snmp, module snmpa_mpd for more details.)

There are also some useful functions for encoding and decoding of SNMP messages in the module snmp_pdus.

Definition of Manager Net if

The Network Interface (Net If) process delivers SNMP PDUs to the manager server, and receives SNMP PDUs from the manager server. The most common behaviour of a Net if process is that is receives request PDU from the manager server, encodes the PDU into bytes and transmits the bytes onto the network to an agent. When the reply from the agent is received by the Net if process, which it decodes into an SNMP PDU, which it sends to the manager server.

However, that simple behaviour can be modified in numerous ways. For example, the Net if process can apply some kind of encrypting/decrypting scheme on the bytes.

The snmp application provides two different modules, snmpm_net_if (the default) and snmpm_net_if_mt, both uses UDP as the transport protocol i.e the transport domains transportDomainUdpIpv4 and/or transportDomainUdpIpv6. The difference between the two modules is that the latter is "multi-threaded", i.e. for each message/request a new process is created that processes the message/request and then exits.

There is a server config option, netif_sup that enables "active" Net If supervision. This is very simple mechanism. The (supervising) process simply sends a ping message and expects a pong message response (within a specific time). The interval between each ping/pong exchange is user configurable. As is the time that is allowed for the pong message to arrive. Both the NetIf module(s) provided with the app supports active supervision. If a NetIf module/process is used which do not implement this, then the server cannot be configured with active supervision.

It is also possible to write your own Net if process and this section describes how to do that.

Mandatory Functions

A Net If process must implement the SNMP manager network interface behaviour.

Messages

The section Messages describes mandatory (with exception for the ping/pong messages) messages, which Net If must send to the manager server process.

In this section a Domain field is the transport domain i.e one of transportDomainUdpIpv4 or transportDomainUdpIpv6, and an Addr field is an {IpAddr,IpPort} tuple.

Outgoing Messages

Net if must send the following message when it receives an SNMP PDU from the network that is aimed for the MasterAgent:

Server ! {snmp_pdu, Pdu, Domain, Addr}

Pdu is an SNMP PDU record, as defined in snmp_types.hrl, with the SNMP request.

Domain is the source transport domain.

Addr is the source address.

Server ! {snmp_trap, Trap, Domain, Addr}

Trap is either an SNMP pdu record or an trappdu record, as defined in snmp_types.hrl, with the SNMP request.

Domain is the source transport domain.

Addr is the source address.

Server ! {snmp_inform, Ref, Pdu, PduMS, Domain, Addr}

Ref is either the atom ignore or something that can be used to identify the inform-request (e.g. request-id). ignore is used if the response (acknowledgment) to the inform-request has already been sent (this means that the server will not make the call to the inform_response function). See the inform request behaviour configuration option for more info.

Pdu is an SNMP PDU record, as defined in snmp_types.hrl, with the SNMP request.

Domain is the source transport domain.

Addr is the source address.

Server ! {snmp_report, Data, Domain, Addr}

Data is either {ok, Pdu} or {error, ReqId, ReasonInfo, Pdu}. Which one is used depends on the return value from the MPD process_msg function. If the MsgData is ok, the first is used, and if it is {error, ReqId, Reason} the latter is used.

Pdu is an SNMP PDU record, as defined in snmp_types.hrl, with the SNMP request.

ReqId is an integer.

ReasonInfo is a term().

Domain is the source transport domain.

Addr is the source address.

Supervisor ! {pong, self()}

Supervisor is the process that sent the ping message (see below).

Incoming Messages

This section describes the incoming messages which a Net If process may choose to respond to.

{ping, Supervisor}This message is sent to the Net If process by a process that has been configured to perform "active supervision" of the Net If process. The Net If process should respond immediately with a pong message.

Supervisor is a pid/0.

Notes

Since the Net if process is responsible for encoding and decoding of SNMP messages, it must also update the relevant counters in the SNMP group in MIB-II. It can use the functions in the module snmpm_mpd for this purpose (refer to the Reference Manual, section snmp, module snmpm_mpd for more details).

There are also some useful functions for encoding and decoding of SNMP messages in the module snmp_pdus.

Audit Trail Log

The chapter Audit Trail Log describes the audit trail logging.

Both the agent and the manager can be configured to log incoming and outgoing messages. It uses the Erlang standard log mechanism disk_log for logging. The size and location of the log files are configurable. A wrap log is used, which means that when the log has grown to a maximum size, it starts from the beginning of the log, overwriting existing log records.

The log can be either a read, write or a read_write.

Agent Logging

For the agent, a write, means that all set requests and their responses are stored. No get requests or traps are stored in a write. A read_write, all requests, responses and traps are stored.

The log uses a raw data format (basically the BER encoded message), in order to minimize the CPU load needed for the log mechanism. This means that the log is not human readable, but needs to be formatted off-line before it can be read. Use the function snmpa:log_to_txt/8 for this purpose.

Manager Logging

For the manager, a write, means that all requests (set and get) and their responses are stored. No traps are stored in a write. A read_write, all requests, responses and traps are stored.

The log uses a raw data format (basically the BER encoded message), in order to minimize the CPU load needed for the log mechanism. This means that the log is not human readable, but needs to be formatted off-line before it can be read. Use the function snmpm:log_to_txt/8 for this purpose.

Advanced Agent Topics

The chapter Advanced Agent Topics describes the more advanced agent related features of the SNMP development tool. The following topics are covered:

When to use a Sub-agent

Agent semantics

Sub-agents and dependencies

Distributed tables

Fault tolerance

Using Mnesia tables as SNMP tables

Audit Trail Logging

Deviations from the standard

When to use a Sub-agent

The section When to use a Sub-agent describes situations where the mechanism of loading and unloading MIBs is insufficient. In these cases a sub-agent is needed.

Special Set Transaction Mechanism

Each sub-agent can implement its own mechanisms for set, get and get-next. For example, if the application requires the get mechanism to be asynchronous, or needs a N-phase set mechanism, a specialized sub-agent should be used.

The toolkit allows different kinds of sub-agents at the same time. Accordingly, different MIBs can have different set or get mechanisms.

Process Communication

A simple distributed agent can be managed without sub-agents. The instrumentation functions can use distributed Erlang to communicate with other parts of the application. However, a sub-agent can be used on each node if this generates too much unnecessary traffic. A sub-agent processes requests per incoming SNMP request, not per variable. Therefore the network traffic is minimized.

If the instrumentation functions communicate with UNIX processes, it might be a good idea to use a special sub-agent. This sub-agent sends the SNMP request to the other process in one packet in order to minimize context switches. For example, if a whole MIB is implemented on the C level in UNIX, but you still want to use the Erlang SNMP tool, then you may have one special sub-agent, which sends the variables in the request as a single operation down to C.

Frequent Loading of MIBs

Loading and unloading of MIBs are quite cheap operations. However, if the application does this very often, perhaps several times per minute, it should load the MIBs once and for all in a sub-agent. This sub-agent only registers and unregisters itself under another agent instead of loading the MIBs each time. This is cheaper than loading an MIB.

Interaction With Other SNMP Agent Toolkits

If the SNMP agent needs to interact with sub-agents constructed in another package, a special sub-agent should be used, which communicates through a protocol specified by the other package.

Agent Semantics

The agent can be configured to be multi-threaded, to process one incoming request at a time, or to have a request limit enabled (this can be used for load control or to limit the effect of DoS attacks). If it is multi-threaded, read requests (get, get-next and get-bulk) and traps are processed in parallel with each other and set requests. However, all set requests are serialized, which means that if the agent is waiting for the application to complete a complicated write operation, it will not process any new write requests until this operation is finished. It processes read requests and sends traps, concurrently. The reason for not handle write requests in parallel is that a complex locking mechanism would be needed even in the simplest cases. Even with the scheme described above, the user must be careful not to violate that the set requests are atoms. If this is hard to do, do not use the multi-threaded feature.

The order within an request is undefined and variables are not processed in a defined order. Do not assume that the first variable in the PDU will be processed before the second, even if the agent processes variables in this order. It cannot even be assumed that requests belonging to different sub-agents have any order.

If the manager tries to set the same variable many times in the same PDU, the agent is free to improvise. There is no definition which determines if the instrumentation will be called once or twice. If called once only, there is no definition that determines which of the new values is going to be supplied.

When the agent receives a request, it keeps the request ID for one second after the response is sent. If the agent receives another request with the same request ID during this time, from the same IP address and UDP port, that request will be discarded. This mechanism has nothing to do with the function snmpa:current_request_id/0.

Sub-agents and Dependencies

The toolkit supports the use of different types of sub-agents, but not the construction of sub-agents.

Also, the toolkit does not support dependencies between sub-agents. A sub-agent should by definition be stand alone and it is therefore not good design to create dependencies between them.

Distributed Tables

A common situation in more complex systems is that the data in a table is distributed. Different table rows are implemented in different places. Some SNMP tool-kits dedicate an SNMP sub-agent for each part of the table and load the corresponding MIB into all sub-agents. The Master Agent is responsible for presenting the distributed table as a single table to the manager. The toolkit supplied uses a different method.

The method used to implement distributed tables with this SNMP tool is to implement a table coordinator process responsible for coordinating the processes, which hold the table data and they are called table holders. All table holders must in some way be known by the coordinator; the structure of the table data determines how this is achieved. The coordinator may require that the table holders explicitly register themselves and specify their information. In other cases, the table holders can be determined once at compile time.

When the instrumentation function for the distributed table is called, the request should be forwarded to the table coordinator. The coordinator finds the requested information among the table holders and then returns the answer to the instrumentation function. The SNMP toolkit contains no support for coordination of tables since this must be independent of the implementation.

The advantages of separating the table coordinator from the SNMP tool are:

We do not need a sub-agent for each table holder. Normally, the sub-agent is needed to take care of communication, but in Distributed Erlang we use ordinary message passing.

Most likely, some type of table coordinator already exists. This process should take care of the instrumentation for the table.

The method used to present a distributed table is strongly application dependent. The use of different masking techniques is only valid for a small subset of problems and registering every row in a distributed table makes it non-distributed.

Fault Tolerance

The SNMP agent toolkit gets input from three different sources:

UDP packets from the network

return values from the user defined instrumentation functions

return values from the MIB.

The agent is highly fault tolerant. If the manager gets an unexpected response from the agent, it is possible that some instrumentation function has returned an erroneous value. The agent will not crash even if the instrumentation does. It should be noted that if an instrumentation function enters an infinite loop, the agent will also be blocked forever. The supervisor ,or the application, specifies how to restart the agent.

Using the SNMP Agent in a Distributed Environment

The normal way to use the agent in a distributed environment is to use one master agent located at one node, and zero or more sub-agents located on other nodes. However, this configuration makes the master agent node a single point of failure. If that node goes down, the agent will not work.

One solution to this problem is to make the snmp application a distributed Erlang application, and that means, the agent may be configured to run on one of several nodes. If the node where it runs goes down, another node restarts the agent. This is called failover. When the node starts again, it may takeover the application. This solution to the problem adds another problem. Generally, the new node has another IP address than the first one, which may cause problems in the communication between the SNMP managers and the agent.

If the snmp agent is configured as a distributed Erlang application, it will during takeover try to load the same MIBs that were loaded at the old node. It uses the same filenames as the old node. If the MIBs are not located in the same paths at the different nodes, the MIBs must be loaded explicitly after takeover.

Using Mnesia Tables as SNMP Tables

The Mnesia DBMS can be used for storing data of SNMP tables. This means that an SNMP table can be implemented as a Mnesia table, and that a Mnesia table can be made visible via SNMP. This mapping is largely automated.

There are three main reasons for using this mapping:

We get all features of Mnesia, such as fault tolerance, persistent data storage, replication, and so on.

Much of the work involved is automated. This includes get-next processing and RowStatus handling.

The table may be used as an ordinary Mnesia table, using the Mnesia API internally in the application at the same time as it is visible through SNMP.

When this mapping is used, insertion and deletion in the original Mnesia table is slower, with a factor O(log n). The read access is not affected.

A drawback with implementing an SNMP table as a Mnesia table is that the internal resource is forced to use the table definition from the MIB, which means that the external data model must be used internally. Actually, this is only partially true. The Mnesia table may extend the SNMP table, which means that the Mnesia table may have columns which are use internally and are not seen by SNMP. Still, the data model from SNMP must be maintained. Although this is undesirable, it is a pragmatic compromise in many situations where simple and efficient implementation is preferable to abstraction.

Creating the Mnesia Table

The table must be created in Mnesia before the manager can use it. The table must be declared as type snmp. This makes the table ordered in accordance with the lexicographical ordering rules of SNMP. The name of the Mnesia table must be identical to the SNMP table name. The types of the INDEX fields in the corresponding SNMP table must be specified.

If the SNMP table has more than one INDEX column, the corresponding Mnesia row is a tuple, where the first element is a tuple with the INDEX columns. Generally, if the SNMP table has N INDEX columns and C data columns, the Mnesia table is of arity (C-N)+1, where the key is a tuple of arity N if N > 1, or a single term if N = 1.

Refer to the Mnesia User's Guide for information on how to declare a Mnesia table as an SNMP table.

The following example illustrates a situation in which we have an SNMP table that we wish to implement as a Mnesia table. The table stores information about employees at a company. Each employee is indexed with the department number and the name.

       empTable OBJECT-TYPE
              SYNTAX      SEQUENCE OF EmpEntry
              ACCESS      not-accessible
              STATUS      mandatory
              DESCRIPTION
                      "A table with information about employees."
       ::= { emp 1}
       empEntry OBJECT-TYPE
              SYNTAX      EmpEntry
              ACCESS      not-accessible
              STATUS      mandatory
              DESCRIPTION
                 ""
              INDEX      { empDepNo, empName }
       ::= { empTable 1 }
       EmpEntry ::=
              SEQUENCE {
                  empDepNo         INTEGER,
                  empName          DisplayString,
                  empTelNo         DisplayString,
                  empStatus        RowStatus
              }

The corresponding Mnesia table is specified as follows:

mnesia:create_table([{name, employees},
                     {snmp, [{key, {integer, string}}]},
                     {attributes, [key, telno, row_status]}]).

Note

In the Mnesia tables, the two key columns are stored as a tuple with two elements. Therefore, the arity of the table is 3.

Instrumentation Functions

The MIB table shown in the previous section can be compiled as follows:

1> snmpc:compile("EmpMIB", [{db, mnesia}]).

This is all that has to be done! Now the manager can read, add, and modify rows. Also, you can use the ordinary Mnesia API to access the table from your programs. The only explicit action is to create the Mnesia table, an action the user has to perform in order to create the required table schemas.

Adding Own Actions

It is often necessary to take some specific action when a table is modified. This is accomplished with an instrumentation function. It executes some specific code when the table is set, and passes all other requests down to the pre-defined function.

The following example illustrates this idea:

emp_table(set, RowIndex, Cols) ->
    notify_internal_resources(RowIndex, Cols),
    snmp_generic:table_func(set, RowIndex, Cols, {empTable, mnesia});
emp_table(Op, RowIndex, Cols) ->
    snmp_generic:table_func(Op, RowIndex, Cols, {empTable, mnesia}).

The default instrumentation functions are defined in the module snmp_generic. Refer to the Reference Manual, section SNMP, module snmp_generic for details.

Extending the Mnesia Table

A table may contain columns that are used internally, but should not be visible to a manager. These internal columns must be the last columns in the table. The set operation will not work with this arrangement, because there are columns that the agent does not know about. This situation is handled by adding values for the internal columns in the set function.

To illustrate this, suppose we extend our Mnesia empTable with one internal column. We create it as before, but with an arity of 4, by adding another attribute.

mnesia:create_table([{name, employees},
                     {snmp, [{key, {integer, string}}]},
                     {attributes, {key, telno, row_status, internal_col}}]).

The last column is the internal column. When performing a set operation, which creates a row, we must give a value to the internal column. The instrumentation functions will now look as follows:

-define(createAndGo, 4).
-define(createAndWait, 5).

emp_table(set, RowIndex, Cols) ->
  notify_internal_resources(RowIndex, Cols),
  NewCols =
    case is_row_created(empTable, Cols) of
      true -> Cols ++ [{4, "internal"}]; % add internal column
      false -> Cols                      % keep original cols
  end,
  snmp_generic:table_func(set, RowIndex, NewCols, {empTable, mnesia});
emp_table(Op, RowIndex, Cols) ->
  snmp_generic:table_func(Op, RowIndex, Cols, {empTable, mnesia}).

is_row_created(Name, Cols) ->
  case snmp_generic:get_status_col(Name, Cols) of
    {ok, ?createAndGo} -> true;
    {ok, ?createAndWait} -> true;
    _ -> false
  end.

If a row is created, we always set the internal column to "internal".

Deviations from the Standard

In some aspects the agent does not implement SNMP fully. Here are the differences:

The default functions and snmp_generic cannot handle an object of type NetworkAddress as INDEX (SNMPv1 only!). Use IpAddress instead.

The agent does not check complex ranges specified for INTEGER objects. In these cases it just checks that the value lies within the minimum and maximum values specified. For example, if the range is specified as 1..10 | 12..20 the agent would let 11 through, but not 0 or 21. The instrumentation functions must check the complex ranges itself.

The agent will never generate the wrongEncoding error. If a variable binding is erroneous encoded, the asn1ParseError counter will be incremented.

A tooBig error in an SNMPv1 packet will always use the 'NULL' value in all variable bindings.

The default functions and snmp_generic do not check the range of each OCTET in textual conventions derived from OCTET STRING, e.g. DisplayString and DateAndTime. This must be checked in an overloaded is_set_ok function.

SNMP Appendix A

Appendix A

This appendix describes the conversion of SNMPv2 to SNMPv1 error messages. The instrumentation functions should return v2 error messages.

Mapping of SNMPv2 error message to SNMPv1:

SNMPv2 message | SNMPv1 message
noError | noError
genErr | genErr
noAccess | noSuchName
wrongType | badValue
wrongLength | badValue
wrongEncoding | badValue
wrongValue | badValue
noCreation | noSuchName
inconsistentValue | badValue
resourceUnavailable | genErr
commitFailed | genErr
undoFailed | genErr
notWritable | noSuchName
inconsistentName | noSuchName

Table: Error Messages

SNMP Appendix B

Appendix B

RowStatus (from RFC1903)

RowStatus ::= TEXTUAL-CONVENTION
    STATUS       current
    DESCRIPTION
            "The RowStatus textual convention is used to manage the
            creation and deletion of conceptual rows, and is used as the
            value of the SYNTAX clause for the status column of a
            conceptual row (as described in Section 7.7.1 in RFC1902.)

            The status column has six defined values:

                 - `active', which indicates that the conceptual row is
                 available for use by the managed device;

                 - `notInService', which indicates that the conceptual
                 row exists in the agent, but is unavailable for use by
                 the managed device (see NOTE below);

                 - `notReady', which indicates that the conceptual row
                 exists in the agent, but is missing information
                 necessary in order to be available for use by the
                 managed device;

                 - `createAndGo', which is supplied by a management
                 station wishing to create a new instance of a
                 conceptual row and to have its status automatically set
                 to active, making it available for use by the managed
                 device;

                 - `createAndWait', which is supplied by a management
                 station wishing to create a new instance of a
                 conceptual row (but not make it available for use by
                 the managed device); and,

                 - `destroy', which is supplied by a management station
                 wishing to delete all of the instances associated with
                 an existing conceptual row.

            Whereas five of the six values (all except `notReady') may
            be specified in a management protocol set operation, only
            three values will be returned in response to a management
            protocol retrieval operation:  `notReady', `notInService' or
            `active'.  That is, when queried, an existing conceptual row
            has only three states:  it is either available for use by
            the managed device (the status column has value `active');
            it is not available for use by the managed device, though
            the agent has sufficient information to make it so (the
            status column has value `notInService'); or, it is not
            available for use by the managed device, and an attempt to
            make it so would fail because the agent has insufficient
            information (the state column has value `notReady').

                                     NOTE WELL

                 This textual convention may be used for a MIB table,
                 irrespective of whether the values of that table's
                 conceptual rows are able to be modified while it is
                 active, or whether its conceptual rows must be taken
                 out of service in order to be modified.  That is, it is
                 the responsibility of the DESCRIPTION clause of the
                 status column to specify whether the status column must
                 not be `active' in order for the value of some other
                 column of the same conceptual row to be modified.  If
                 such a specification is made, affected columns may be
                 changed by an SNMP set PDU if the RowStatus would not
                 be equal to `active' either immediately before or after
                 processing the PDU.  In other words, if the PDU also
                 contained a varbind that would change the RowStatus
                 value, the column in question may be changed if the
                 RowStatus was not equal to `active' as the PDU was
                 received, or if the varbind sets the status to a value
                 other than 'active'.

            Also note that whenever any elements of a row exist, the
            RowStatus column must also exist.

            To summarize the effect of having a conceptual row with a
            status column having a SYNTAX clause value of RowStatus,
            consider the following state diagram:

                                         STATE
              +--------------+-----------+-------------+-------------
              |      A       |     B     |      C      |      D
              |              |status col.|status column|
              |status column |    is     |      is     |status column
    ACTION    |does not exist|  notReady | notInService|  is active
--------------+--------------+-----------+-------------+-------------
set status    |noError    ->D|inconsist- |inconsistent-|inconsistent-
column to     |       or     |   entValue|        Value|        Value
createAndGo   |inconsistent- |           |             |
              |         Value|           |             |
--------------+--------------+-----------+-------------+-------------
set status    |noError  see 1|inconsist- |inconsistent-|inconsistent-
column to     |       or     |   entValue|        Value|        Value
createAndWait |wrongValue    |           |             |
--------------+--------------+-----------+-------------+-------------
set status    |inconsistent- |inconsist- |noError      |noError
column to     |         Value|   entValue|             |
active        |              |           |             |
              |              |     or    |             |
              |              |           |             |
              |              |see 2   ->D|          ->D|          ->D
--------------+--------------+-----------+-------------+-------------
set status    |inconsistent- |inconsist- |noError      |noError   ->C
column to     |         Value|   entValue|             |
notInService  |              |           |             |
              |              |     or    |             |      or
              |              |           |             |
              |              |see 3   ->C|          ->C|wrongValue
--------------+--------------+-----------+-------------+-------------
set status    |noError       |noError    |noError      |noError
column to     |              |           |             |
destroy       |           ->A|        ->A|          ->A|          ->A
--------------+--------------+-----------+-------------+-------------
set any other |see 4         |noError    |noError      |see 5
column to some|              |           |             |
value         |              |      see 1|          ->C|          ->D
--------------+--------------+-----------+-------------+-------------

            (1) goto B or C, depending on information available to the
            agent.

            (2) if other variable bindings included in the same PDU,
            provide values for all columns which are missing but
            required, then return noError and goto D.

            (3) if other variable bindings included in the same PDU,
            provide values for all columns which are missing but
            required, then return noError and goto C.

            (4) at the discretion of the agent, the return value may be
            either:

                 inconsistentName:  because the agent does not choose to
                 create such an instance when the corresponding
                 RowStatus instance does not exist, or

                 inconsistentValue:  if the supplied value is
                 inconsistent with the state of some other MIB object's
                 value, or

                 noError: because the agent chooses to create the
                 instance.

            If noError is returned, then the instance of the status
            column must also be created, and the new state is B or C,
            depending on the information available to the agent.  If
            inconsistentName or inconsistentValue is returned, the row
            remains in state A.

            (5) depending on the MIB definition for the column/table,
            either noError or inconsistentValue may be returned.

            NOTE: Other processing of the set request may result in a
            response other than noError being returned, e.g.,
            wrongValue, noCreation, etc.

                              Conceptual Row Creation

            There are four potential interactions when creating a
            conceptual row:  selecting an instance-identifier which is
            not in use; creating the conceptual row; initializing any
            objects for which the agent does not supply a default; and,
            making the conceptual row available for use by the managed
            device.

            Interaction 1: Selecting an Instance-Identifier

            The algorithm used to select an instance-identifier varies
            for each conceptual row.  In some cases, the instance-
            identifier is semantically significant, e.g., the
            destination address of a route, and a management station
            selects the instance-identifier according to the semantics.

            In other cases, the instance-identifier is used solely to
            distinguish conceptual rows, and a management station
            without specific knowledge of the conceptual row might
            examine the instances present in order to determine an
            unused instance-identifier.  (This approach may be used, but
            it is often highly sub-optimal; however, it is also a
            questionable practice for a naive management station to
            attempt conceptual row creation.)

            Alternately, the MIB module which defines the conceptual row
            might provide one or more objects which provide assistance
            in determining an unused instance-identifier.  For example,
            if the conceptual row is indexed by an integer-value, then
            an object having an integer-valued SYNTAX clause might be
            defined for such a purpose, allowing a management station to
            issue a management protocol retrieval operation.  In order
            to avoid unnecessary collisions between competing management
            stations, `adjacent' retrievals of this object should be
            different.

            Finally, the management station could select a pseudo-random
            number to use as the index.  In the event that this index
            was already in use and an inconsistentValue was returned in
            response to the management protocol set operation, the
            management station should simply select a new pseudo-random
            number and retry the operation.

            A MIB designer should choose between the two latter
            algorithms based on the size of the table (and therefore the
            efficiency of each algorithm).  For tables in which a large
            number of entries are expected, it is recommended that a MIB
            object be defined that returns an acceptable index for
            creation.  For tables with small numbers of entries, it is
            recommended that the latter pseudo-random index mechanism be
            used.

            Interaction 2: Creating the Conceptual Row

            Once an unused instance-identifier has been selected, the
            management station determines if it wishes to create and
            activate the conceptual row in one transaction or in a
            negotiated set of interactions.

            Interaction 2a: Creating and Activating the Conceptual Row

            The management station must first determine the column
            requirements, i.e., it must determine those columns for
            which it must or must not provide values.  Depending on the
            complexity of the table and the management station's
            knowledge of the agent's capabilities, this determination
            can be made locally by the management station.  Alternately,
            the management station issues a management protocol get
            operation to examine all columns in the conceptual row that
            it wishes to create.  In response, for each column, there
            are three possible outcomes:

                 - a value is returned, indicating that some other
                 management station has already created this conceptual
                 row.  We return to interaction 1.

                 - the exception `noSuchInstance' is returned,
                 indicating that the agent implements the object-type
                 associated with this column, and that this column in at
                 least one conceptual row would be accessible in the MIB
                 view used by the retrieval were it to exist. For those
                 columns to which the agent provides read-create access,
                 the `noSuchInstance' exception tells the management
                 station that it should supply a value for this column
                 when the conceptual row is to be created.

                 - the exception `noSuchObject' is returned, indicating
                 that the agent does not implement the object-type
                 associated with this column or that there is no
                 conceptual row for which this column would be
                 accessible in the MIB view used by the retrieval.  As
                 such, the management station cannot issue any
                 management protocol set operations to create an
                 instance of this column.

            Once the column requirements have been determined, a
            management protocol set operation is accordingly issued.
            This operation also sets the new instance of the status
            column to `createAndGo'.

            When the agent processes the set operation, it verifies that
            it has sufficient information to make the conceptual row
            available for use by the managed device.  The information
            available to the agent is provided by two sources:  the
            management protocol set operation which creates the
            conceptual row, and, implementation-specific defaults
            supplied by the agent (note that an agent must provide
            implementation-specific defaults for at least those objects
            which it implements as read-only).  If there is sufficient
            information available, then the conceptual row is created, a
            `noError' response is returned, the status column is set to
            `active', and no further interactions are necessary (i.e.,
            interactions 3 and 4 are skipped).  If there is insufficient
            information, then the conceptual row is not created, and the
            set operation fails with an error of `inconsistentValue'.
            On this error, the management station can issue a management
            protocol retrieval operation to determine if this was
            because it failed to specify a value for a required column,
            or, because the selected instance of the status column
            already existed.  In the latter case, we return to
            interaction 1.  In the former case, the management station
            can re-issue the set operation with the additional
            information, or begin interaction 2 again using
            `createAndWait' in order to negotiate creation of the
            conceptual row.

                                     NOTE WELL

                 Regardless of the method used to determine the column
                 requirements, it is possible that the management
                 station might deem a column necessary when, in fact,
                 the agent will not allow that particular columnar
                 instance to be created or written.  In this case, the
                 management protocol set operation will fail with an
                 error such as `noCreation' or `notWritable'.  In this
                 case, the management station decides whether it needs
                 to be able to set a value for that particular columnar
                 instance.  If not, the management station re-issues the
                 management protocol set operation, but without setting
                 a value for that particular columnar instance;
                 otherwise, the management station aborts the row
                 creation algorithm.

            Interaction 2b: Negotiating the Creation of the Conceptual
            Row

            The management station issues a management protocol set
            operation which sets the desired instance of the status
            column to `createAndWait'.  If the agent is unwilling to
            process a request of this sort, the set operation fails with
            an error of `wrongValue'.  (As a consequence, such an agent
            must be prepared to accept a single management protocol set
            operation, i.e., interaction 2a above, containing all of the
            columns indicated by its column requirements.)  Otherwise,
            the conceptual row is created, a `noError' response is
            returned, and the status column is immediately set to either
            `notInService' or `notReady', depending on whether it has
            sufficient information to make the conceptual row available
            for use by the managed device.  If there is sufficient
            information available, then the status column is set to
            `notInService'; otherwise, if there is insufficient
            information, then the status column is set to `notReady'.
            Regardless, we proceed to interaction 3.

            Interaction 3: Initializing non-defaulted Objects

            The management station must now determine the column
            requirements.  It issues a management protocol get operation
            to examine all columns in the created conceptual row.  In
            the response, for each column, there are three possible
            outcomes:

                 - a value is returned, indicating that the agent
                 implements the object-type associated with this column
                 and had sufficient information to provide a value.  For
                 those columns to which the agent provides read-create
                 access (and for which the agent allows their values to
                 be changed after their creation), a value return tells
                 the management station that it may issue additional
                 management protocol set operations, if it desires, in
                 order to change the value associated with this column.

                 - the exception `noSuchInstance' is returned,
                 indicating that the agent implements the object-type
                 associated with this column, and that this column in at
                 least one conceptual row would be accessible in the MIB
                 view used by the retrieval were it to exist. However,
                 the agent does not have sufficient information to
                 provide a value, and until a value is provided, the
                 conceptual row may not be made available for use by the
                 managed device.  For those columns to which the agent
                 provides read-create access, the `noSuchInstance'
                 exception tells the management station that it must
                 issue additional management protocol set operations, in
                 order to provide a value associated with this column.

                 - the exception `noSuchObject' is returned, indicating
                 that the agent does not implement the object-type
                 associated with this column or that there is no
                 conceptual row for which this column would be
                 accessible in the MIB view used by the retrieval.  As
                 such, the management station cannot issue any
                 management protocol set operations to create an
                 instance of this column.

            If the value associated with the status column is
            `notReady', then the management station must first deal with
            all `noSuchInstance' columns, if any.  Having done so, the
            value of the status column becomes `notInService', and we
            proceed to interaction 4.

            Interaction 4: Making the Conceptual Row Available

            Once the management station is satisfied with the values
            associated with the columns of the conceptual row, it issues
            a management protocol set operation to set the status column
            to `active'.  If the agent has sufficient information to
            make the conceptual row available for use by the managed
            device, the management protocol set operation succeeds (a
            `noError' response is returned).  Otherwise, the management
            protocol set operation fails with an error of
            `inconsistentValue'.

                                     NOTE WELL

                 A conceptual row having a status column with value
                 `notInService' or `notReady' is unavailable to the
                 managed device.  As such, it is possible for the
                 managed device to create its own instances during the
                 time between the management protocol set operation
                 which sets the status column to `createAndWait' and the
                 management protocol set operation which sets the status
                 column to `active'.  In this case, when the management
                 protocol set operation is issued to set the status
                 column to `active', the values held in the agent
                 supersede those used by the managed device.

            If the management station is prevented from setting the
            status column to `active' (e.g., due to management station
            or network failure) the conceptual row will be left in the
            `notInService' or `notReady' state, consuming resources
            indefinitely.  The agent must detect conceptual rows that
            have been in either state for an abnormally long period of
            time and remove them.  It is the responsibility of the
            DESCRIPTION clause of the status column to indicate what an
            abnormally long period of time would be.  This period of
            time should be long enough to allow for human response time
            (including `think time') between the creation of the
            conceptual row and the setting of the status to `active'.
            In the absence of such information in the DESCRIPTION
            clause, it is suggested that this period be approximately 5
            minutes in length.  This removal action applies not only to
            newly-created rows, but also to previously active rows which
            are set to, and left in, the notInService state for a
            prolonged period exceeding that which is considered normal
            for such a conceptual row.

                             Conceptual Row Suspension

            When a conceptual row is `active', the management station
            may issue a management protocol set operation which sets the
            instance of the status column to `notInService'.  If the
            agent is unwilling to do so, the set operation fails with an
            error of `wrongValue'.  Otherwise, the conceptual row is
            taken out of service, and a `noError' response is returned.
            It is the responsibility of the DESCRIPTION clause of the
            status column to indicate under what circumstances the
            status column should be taken out of service (e.g., in order
            for the value of some other column of the same conceptual
            row to be modified).

                              Conceptual Row Deletion

            For deletion of conceptual rows, a management protocol set
            operation is issued which sets the instance of the status
            column to `destroy'.  This request may be made regardless of
            the current value of the status column (e.g., it is possible
            to delete conceptual rows which are either `notReady',
            `notInService' or `active'.)  If the operation succeeds,
            then all instances associated with the conceptual row are
            immediately removed."

    SYNTAX       INTEGER {
                     -- the following two values are states:
                     -- these values may be read or written
                     active(1),
                     notInService(2),

                     -- the following value is a state:
                     -- this value may be read, but not written
                     notReady(3),

                     -- the following three values are
                     -- actions: these values may be written,
                     --   but are never read
                     createAndGo(4),
                     createAndWait(5),
                     destroy(6)
                 }

SNMP Appendix C

Appendix C

Compile time configuration

There is one compile/configure time option: Defining the size of an "empty" PDU. This is used when processing get-bulk requests. The default value for this is 21, but can be increased in two ways:

configure: --with-snmp-empty-pdu-size=SIZE

compile time: environment variable: SNMP_EMPTY_PDU_SIZE=SIZE"

Where SIZE is a value greater or equal to 21.

snmpc

SNMP MIB compiler frontend

Description

The snmpc program provides a way to run the SNMP MIB compiler of the Erlang system.

snmpc [options] file.mib | file.bin

snmpc compile a SNMP MIB file, see compile/1,2 for more info.

It can also be used to generate a header file (.hrl) with definitions of Erlang constants for the objects in the MIB, see mib_to_hrl/1.

Compiler options

The following options are supported (note that most of these relate to the compilation of the MIB file):

--help - Prints help info.

--version - Prints application and mib format version.

--verbosity verbosity - Print debug info.

verbosity = trace | debug | log | info | silence

Defaults to silence.

--warnings | --W - Print warning messages.

--wae | --Werror - Warnings as errors. Indicates that warnings shall be treated as errors.

--o directory - The directory where the compiler should place the output files. If not specified, output files will be placed in the current working directory.

--i Directory - Specifies the path to search for imported (compiled) MIB files. By default, the current working directory is always included.

This option can be present several times, each time specifying one path.

--il Directory - This option (include_lib), specifies a list of directories to search for imported MIBs. It assumes that the first element in the directory name corresponds to an OTP application. The compiler will find the current installed version. For example, the value ["snmp/mibs/"] will be replaced by ["snmp-3.1.1/mibs/"] (or what the current version may be in the system). The current directory and the "snmp-home"/priv/mibs/ are always listed last in the include path.

--sgc - This option (skip group check), if present, disables the group check of the mib compiler. That is, should the OBJECT-GROUP and the NOTIFICATION-GROUP macro(s) be checked for correctness or not.

--dep - Keep deprecated definition(s). If not specified the compiler will ignore deprecated definitions.

--desc - The DESCRIPTION field will be included.

--ref - The REFERENCE field will be included.

--imp - The IMPORTS field will be included.

--mi - The MODULE-IDENTITY field will be included.

--mc - The MODULE-COMPLIANCE field will be included.

--ac - The AGENT-CAPABILITIES field will be included.

--mod module - The module which implements all the instrumentation functions.

The name of all instrumentation functions must be the same as the corresponding managed object it implements.

--nd - The default instrumentation functions will not be used if a managed object have no instrumentation function. Instead this will be reported as an error, and the compilation aborts.

--rrnac - This option, if present, specifies that the row name assign check shall not be done strictly according to the SMI (which allows only the value 1).

With this option, all values greater than zero is allowed (>= 1). This means that the error will be converted to a warning.

By default it is not included, but if this option is present it will be.

SEE ALSO

erlc(1), compile, snmpc

snmp

Interface functions to the SNMP toolkit

The module snmp contains interface functions to the SNMP toolkit.

See Also

calendar(3)

Summary

Types

algorithm()

asn1_type()

atl_type()

bits()

The Erlang representation of the SNMP BITS (pseudo) data type.

column()

community()

context_name()

date_and_time_validator()

The input to the validator fun looks like this

date_and_time_validator_kind()

dir()

A string, that is a file path to a directory.

engine_id()

error_index()

0 is used when error status is noError and when error status is an actual error; error index is pos_integer/0.

error_status()

We should really specify all of these, but they are so numerous... Also, normally all you need to know is that 'noError' is ok and everything else is an error.

ivarbind()

log_size()

This is basically a copy of the dlog_size().

log_time()

me()

mib()

mib_name()

mms()

notification()

octet()

octet_string()

oid()

Represent an ASN.1 OBJECT IDENTIFIER.

pdu()

pdu_type()

rfc1903_date_and_time()

The data type DateAndTime, an OCTET STRING, as specified in RFC1903.

row_index()

Denotes the last part of the OID which specifies the index of the row in the table (see RFC1212, 4.1.6 for more information about INDEX).

row_pointer()

Note

"Represents a pointer to a conceptual row. The value is the name of the instance of the first accessible columnar object in the conceptual row."

sec_level()

sec_model()

sec_name()

snmp_timer()

table_info()

taddress()

tdomain()

time_interval()

Note

"A period of time, measured in units of 0.01 seconds."

trap()

trappdu()

usm_auth_key()

usm_auth_protocol()

usm_name()

usm_priv_key()

usm_priv_protocol()

varbind()

variable_info()

verbosity()

For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

version()

void()

The type is used when a functions return is to be ignored.

Functions

bits_to_octet_string(B)

Utility function for converting a value of type BITS to OCTET-STRING, according to RFC1906, section 8.

change_log_size(LogName, NewSize)

Changes the log size of the Audit Trail Log. The application must be configured to use the audit trail log function. Please refer to disk_log(3) in Kernel Reference Manual for a description of how to change the log size.

config()

A simple interactive configuration tool. Simple configuration files can be generated, but more complex configurations still have to be edited manually.

date_and_time()

Returns current date and time as the data type DateAndTime, as specified in RFC1903. This is an OCTET STRING.

date_and_time_to_string2(DAT)

Converts a DateAndTime list to a printable string, according to the DISPLAY-HINT definition in RFC2579, with the extension that it also allows the values "hours from UTC" = 14 together with "minutes from UTC" = 0.

date_and_time_to_string(DAT)

Equivalent to date_and_time_to_string/2.

date_and_time_to_string(DAT, Validate)

Converts a DateAndTime list to a printable string, according to the DISPLAY-HINT definition in RFC2579.

date_and_time_to_universal_time_dst(DAT)

Converts a DateAndTime list to a list of possible universal time(s). The universal time value on the same format as defined in calendar(3).

disable_trace()

Stop the tracer.

enable_trace()

Starts a dbg tracer that prints trace events to stdout (using plain io:format after a minor formatting).

local_time_to_date_and_time_dst(Local)

Converts a local time value to a list of possible DateAndTime list(s). The local time value on the same format as defined in calendar(3).

log_to_io(LogDir, Mibs, LogName, LogFile)

Equivalent to log_to_io/7.

log_to_io/5

Equivalent to log_to_io/7.

log_to_io/6

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable format and prints it on stdio. See log_to_txt above for more info.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile)

Equivalent to log_to_txt/8.

log_to_txt/6

Equivalent to log_to_txt/8.

log_to_txt/7

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable text file, where each item has a trailing TAB character, and any TAB character in the body of an item has been replaced by ESC TAB.

octet_string_to_bits(S)

Utility function for converting a value of type OCTET-STRING to BITS, according to RFC1906, section 8.

passwd2localized_key(Algorithm, Passwd, EngineID)

Generates a key that can be used as an authentication or privacy key using MD5, SHA, SHA224, SHA256, SHA384 or SHA512. The key is localized for EngineID.

print_version_info()

Equivalent to print_version_info/1.

print_version_info(Prefix)

Utility function(s) to produce a formatted printout of the versions info generated by the versions1 function

print_versions(Versions)

Equivalent to print_versions/2.

print_versions(Prefix, Versions)

Utility function to produce a formatted printout of the versions info generated by the versions1 and versions2 functions

read_mib(FileName)

Read a compiled mib.

reset_trace(Targets)

This function is used to reset (disable) trace for the given module(s).

set_trace(Targets)

This function is used to set up default trace on function(s) for the given module or modules. The scope of the trace will be all exported functions (both the call info and the return value). Timestamp info will also be included.

set_trace(Targets, TraceOpts)

This function is used to set up trace on function(s) for the given module or modules.

start()

Equivalent to start/1.

start(Type)

Starts the SNMP application.

start_agent()

Equivalent to start_agent/1.

start_agent(Type)

The SNMP application consists of several entities, of which the agent is one. This function starts the agent entity of the application.

start_manager()

Equivalent to start_manager/1.

start_manager(Type)

The SNMP application consists of several entities, of which the manager is one. This function starts the manager entity of the application.

stop()

Stops the SNMP application.

universal_time_to_date_and_time(UTC)

Converts a universal time value to a DateAndTime list. The universal time value on the same format as defined in calendar(3).

validate_date_and_time(DateAndTime)

Equivalent to validate_date_and_time/2.

validate_date_and_time(DateAndTime, Validate)

Checks if DateAndTime is a correct DateAndTime value, as specified in RFC2579. This function can be used in instrumentation functions to validate a DateAndTime value.

versions1()

Equivalent to versions2/0.

versions2()

Utility functions used to retrieve some system and application info.

Types

Link to this type

algorithm()

View Source (not exported)

-type algorithm() :: md5 | sha | sha224 | sha256 | sha384 | sha512.

Link to this type

asn1_type()

View Source

-type asn1_type() ::
    #asn1_type{bertype :: term(),
               lo :: term(),
               hi :: term(),
               assocList :: term(),
               imported :: term(),
               aliasname :: term(),
               implied :: term(),
               display_hint :: term()}.

Link to this type

atl_type()

View Source

-type atl_type() :: read | write | read_write.

Link to this type

bits()

View Source

-type bits() :: integer().

The Erlang representation of the SNMP BITS (pseudo) data type.

Link to this type

column()

View Source

-type column() :: pos_integer().

Link to this type

community()

View Source

-type community() :: snmp_community_mib:name().

Link to this type

context_name()

View Source

-type context_name() :: snmp_community_mib:context_name().

Link to this type

date_and_time_validator()

View Source

-type date_and_time_validator() ::
    fun((Kind :: date_and_time_validator_kind(), Data :: term()) -> boolean()).

The input to the validator fun looks like this:

	  Kind             Data
	  --------------   ----------------------
	  year             {Year1, Year2}
	  month            Month
	  day              Day
	  hour             Hour
	  minute           Minute
	  seconds          Seconds
	  deci_seconds     DeciSeconds
	  diff             [Sign, Hour, Minute]
	  valid_date       {Year, Month, Day}

Link to this type

date_and_time_validator_kind()

View Source

-type date_and_time_validator_kind() ::
    year | month | day | hour | minute | seconds | deci_seconds | diff | valid_date.

Link to this type

dir()

View Source

-type dir() :: string().

A string, that is a file path to a directory.

Link to this type

engine_id()

View Source

-type engine_id() :: snmp_framework_mib:engine_id().

Link to this type

error_index()

View Source

-type error_index() :: non_neg_integer().

0 is used when error status is noError and when error status is an actual error; error index is pos_integer/0.

Link to this type

error_status()

View Source

-type error_status() :: noError | atom().

We should really specify all of these, but they are so numerous... Also, normally all you need to know is that 'noError' is ok and everything else is an error.

Link to this type

ivarbind()

View Source

-type ivarbind() :: #ivarbind{status :: term(), mibentry :: term(), varbind :: term()}.

Link to this type

log_size()

View Source

-type log_size() ::
    infinity | pos_integer() | {MaxNoBytes :: pos_integer(), MaxNoFiles :: pos_integer()}.

This is basically a copy of the dlog_size().

Link to this type

log_time()

View Source

-type log_time() ::
    calendar:datetime() |
    {local_time, calendar:datetime()} |
    {universal_time, calendar:datetime()}.

Link to this type

me()

View Source

-type me() ::
    #me{oid :: term(),
        entrytype :: term(),
        aliasname :: term(),
        asn1_type :: term(),
        access :: term(),
        mfa :: term(),
        imported :: term(),
        assocList :: term(),
        description :: term(),
        units :: term()}.

Link to this type

mib()

View Source

-type mib() ::
    #mib{misc :: term(),
         mib_format_version :: term(),
         name :: term(),
         module_identity :: term(),
         mes :: term(),
         asn1_types :: term(),
         traps :: term(),
         variable_infos :: term(),
         table_infos :: term(),
         imports :: term()}.

Link to this type

mib_name()

View Source

-type mib_name() :: string().

Link to this type

mms()

View Source

-type mms() :: snmp_framework_mib:max_message_size().

Link to this type

notification()

View Source

-type notification() ::
    #notification{trapname :: term(), oid :: term(), oidobjects :: term(), description :: term()}.

Link to this type

octet()

View Source

-type octet() :: 0..255.

Link to this type

octet_string()

View Source

-type octet_string() :: [octet()].

Link to this type

oid()

View Source

-type oid() :: [non_neg_integer()].

Represent an ASN.1 OBJECT IDENTIFIER.

Link to this type

pdu()

View Source

-type pdu() ::
    #pdu{type :: term(),
         request_id :: term(),
         error_status :: term(),
         error_index :: term(),
         varbinds :: term()}.

Link to this type

pdu_type()

View Source

-type pdu_type() :: snmp_pdus:pdu_type().

Link to this type

rfc1903_date_and_time()

View Source

-type rfc1903_date_and_time() :: octet_string().

The data type DateAndTime, an OCTET STRING, as specified in RFC1903.

Link to this type

row_index()

View Source

-type row_index() :: oid().

Denotes the last part of the OID which specifies the index of the row in the table (see RFC1212, 4.1.6 for more information about INDEX).

Link to this type

row_pointer()

View Source

-type row_pointer() :: oid().

Note

"Represents a pointer to a conceptual row. The value is the name of the instance of the first accessible columnar object in the conceptual row."

OBJECT IDENTIFIER

Defined by SNMPv2-TC.

Link to this type

sec_level()

View Source

-type sec_level() :: snmp_framework_mib:security_level().

Link to this type

sec_model()

View Source

-type sec_model() :: snmp_framework_mib:security_model().

Link to this type

sec_name()

View Source

-type sec_name() :: snmp_framework_mib:admin_string().

Link to this type

snmp_timer()

View Source

-type snmp_timer() ::
    #snmp_incr_timer{wait_for :: term(), factor :: term(), incr :: term(), max_retries :: term()}.

Link to this type

table_info()

View Source

-type table_info() ::
    #table_info{nbr_of_cols :: term(),
                defvals :: term(),
                status_col :: term(),
                not_accessible :: term(),
                index_types :: term(),
                first_accessible :: term(),
                first_own_index :: term()}.

Link to this type

taddress()

View Source

-type taddress() :: snmpa_conf:transportAddress().

Link to this type

tdomain()

View Source

-type tdomain() :: transportDomainUdpIpv4 | transportDomainUdpIpv6.

Link to this type

time_interval()

View Source

-type time_interval() :: 0..2147483647.

Note

"A period of time, measured in units of 0.01 seconds."

INTEGER (0..2147483647)

Defined by SNMPv2-TC.

Link to this type

trap()

View Source

-type trap() ::
    #trap{trapname :: term(),
          enterpriseoid :: term(),
          specificcode :: term(),
          oidobjects :: term(),
          description :: term()}.

Link to this type

trappdu()

View Source

-type trappdu() ::
    #trappdu{enterprise :: term(),
             agent_addr :: term(),
             generic_trap :: term(),
             specific_trap :: term(),
             time_stamp :: term(),
             varbinds :: term()}.

Link to this type

usm_auth_key()

View Source

-type usm_auth_key() :: snmp_user_based_sm_mib:auth_key().

Link to this type

usm_auth_protocol()

View Source

-type usm_auth_protocol() :: snmp_user_based_sm_mib:auth_protocol().

Link to this type

usm_name()

View Source

-type usm_name() :: snmp_user_based_sm_mib:name().

Link to this type

usm_priv_key()

View Source

-type usm_priv_key() :: snmp_user_based_sm_mib:priv_key().

Link to this type

usm_priv_protocol()

View Source

-type usm_priv_protocol() :: snmp_user_based_sm_mib:priv_protocol().

Link to this type

varbind()

View Source

-type varbind() :: #varbind{oid :: term(), variabletype :: term(), value :: term(), org_index :: term()}.

Link to this type

variable_info()

View Source

-type variable_info() :: #variable_info{defval :: term()}.

Link to this type

verbosity()

View Source

-type verbosity() :: silence | info | log | debug | trace.

For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

Link to this type

version()

View Source

-type version() :: v1 | v2 | v3.

Link to this type

void()

View Source

-type void() :: term().

The type is used when a functions return is to be ignored.

Functions

Link to this function

bits_to_octet_string(B)

View Source

-spec bits_to_octet_string(B) -> octet_string() when B :: bits().

Utility function for converting a value of type BITS to OCTET-STRING, according to RFC1906, section 8.

Link to this function

change_log_size(LogName, NewSize)

View Source

-spec change_log_size(LogName, NewSize) -> ok | {error, Reason}
                   when LogName :: string(), NewSize :: log_size(), Reason :: term().

Changes the log size of the Audit Trail Log. The application must be configured to use the audit trail log function. Please refer to disk_log(3) in Kernel Reference Manual for a description of how to change the log size.

The change is permanent, as long as the log is not deleted. That means, the log size is remembered across reboots.

Link to this function

config()

View Source

-spec config() -> ok | {error, Reason} when Reason :: term().

A simple interactive configuration tool. Simple configuration files can be generated, but more complex configurations still have to be edited manually.

The tool is a textual based tool that asks some questions and generates sys.config and *.conf files.

Note that if the application shall support version 3, then the crypto app must be started before running this function (password generation).

Note also that some of the configuration files for the agent and manager share the same names. This means that they have to be stored in different directories!

Link to this function

date_and_time()

View Source

-spec date_and_time() -> DateAndTime when DateAndTime :: rfc1903_date_and_time().

Returns current date and time as the data type DateAndTime, as specified in RFC1903. This is an OCTET STRING.

Link to this function

date_and_time_to_string2(DAT)

View Source

-spec date_and_time_to_string2(DAT) -> string() when DAT :: rfc1903_date_and_time().

Converts a DateAndTime list to a printable string, according to the DISPLAY-HINT definition in RFC2579, with the extension that it also allows the values "hours from UTC" = 14 together with "minutes from UTC" = 0.

Link to this function

date_and_time_to_string(DAT)

View Source

-spec date_and_time_to_string(DAT) -> string() when DAT :: rfc1903_date_and_time().

Equivalent to date_and_time_to_string/2.

Link to this function

date_and_time_to_string(DAT, Validate)

View Source

-spec date_and_time_to_string(DAT, Validate) -> string()
                           when
                               DAT :: rfc1903_date_and_time(),
                               Validate :: date_and_time_validator().

Converts a DateAndTime list to a printable string, according to the DISPLAY-HINT definition in RFC2579.

The validation fun, Validate, allows for a more "flexible" validation of the DateAndTime argument. Whenever the data is found to not follow RFC2579, the fun is called to allow a more "lax" validation. See the validate_date_and_time/2 function for more info on the Validate fun.

Link to this function

date_and_time_to_universal_time_dst(DAT)

View Source

-spec date_and_time_to_universal_time_dst(DAT) -> UTCs
                                       when
                                           DAT :: rfc1903_date_and_time(),
                                           UTCs :: [calendar:datetime1970()].

Converts a DateAndTime list to a list of possible universal time(s). The universal time value on the same format as defined in calendar(3).

Link to this function

disable_trace()

View Source

-spec disable_trace() -> void().

Stop the tracer.

Link to this function

enable_trace()

View Source

-spec enable_trace() -> void().

Starts a dbg tracer that prints trace events to stdout (using plain io:format after a minor formatting).

Link to this function

local_time_to_date_and_time_dst(Local)

View Source

-spec local_time_to_date_and_time_dst(Local) -> DATs
                                   when
                                       Local :: calendar:datetime1970(),
                                       DATs :: [rfc1903_date_and_time()].

Converts a local time value to a list of possible DateAndTime list(s). The local time value on the same format as defined in calendar(3).

Link to this function

log_to_io(LogDir, Mibs, LogName, LogFile)

View Source (since OTP R15B01,OTP R16B03)

-spec log_to_io(LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/5

View Source (since OTP R15B01,OTP R16B03)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName, LogFile, Start) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Start :: null | log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/6

View Source (since OTP R15B01,OTP R16B03)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Start :: null | log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Start :: null | log_time(),
                 Stop :: null | log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

View Source (since OTP R15B01,OTP R16B03)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Start :: null | log_time(),
                 Stop :: null | log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Converts an Audit Trail Log to a readable format and prints it on stdio. See log_to_txt above for more info.

Link to this function

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile)

View Source (since OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
              when
                  LogDir :: string(),
                  Mibs :: [mib_name()],
                  OutFile :: string(),
                  LogName :: string(),
                  LogFile :: string(),
                  Cnt :: {NumOK, NumERR},
                  NumOK :: non_neg_integer(),
                  NumERR :: pos_integer(),
                  Reason :: term().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/6

View Source (since OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block) -> ok | {ok, Cnt} | {error, Reason}
              when
                  LogDir :: string(),
                  Mibs :: [mib_name()],
                  OutFile :: string(),
                  LogName :: string(),
                  LogFile :: string(),
                  Block :: boolean(),
                  Cnt :: {NumOK, NumERR},
                  NumOK :: non_neg_integer(),
                  NumERR :: pos_integer(),
                  Reason :: term();
          (LogDir, Mibs, OutFile, LogName, LogFile, Start) -> ok | {ok, Cnt} | {error, Reason}
              when
                  LogDir :: string(),
                  Mibs :: [mib_name()],
                  OutFile :: string(),
                  LogName :: string(),
                  LogFile :: string(),
                  Start :: null | log_time(),
                  Cnt :: {NumOK, NumERR},
                  NumOK :: non_neg_integer(),
                  NumERR :: pos_integer(),
                  Reason :: term().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/7

View Source (since OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) ->
              ok | {ok, Cnt} | {error, Reason}
              when
                  LogDir :: string(),
                  Mibs :: [mib_name()],
                  OutFile :: string(),
                  LogName :: string(),
                  LogFile :: string(),
                  Block :: boolean(),
                  Start :: null | log_time(),
                  Cnt :: {NumOK, NumERR},
                  NumOK :: non_neg_integer(),
                  NumERR :: pos_integer(),
                  Reason :: term();
          (LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) ->
              ok | {ok, Cnt} | {error, Reason}
              when
                  LogDir :: string(),
                  Mibs :: [mib_name()],
                  OutFile :: string(),
                  LogName :: string(),
                  LogFile :: string(),
                  Start :: null | log_time(),
                  Stop :: null | log_time(),
                  Cnt :: {NumOK, NumERR},
                  NumOK :: non_neg_integer(),
                  NumERR :: pos_integer(),
                  Reason :: term().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

View Source (since OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) ->
              ok | {ok, Cnt} | {error, Reason}
              when
                  LogDir :: string(),
                  Mibs :: [mib_name()],
                  OutFile :: string(),
                  LogName :: string(),
                  LogFile :: string(),
                  Block :: boolean(),
                  Start :: null | log_time(),
                  Stop :: null | log_time(),
                  Cnt :: {NumOK, NumERR},
                  NumOK :: non_neg_integer(),
                  NumERR :: pos_integer(),
                  Reason :: term().

Converts an Audit Trail Log to a readable text file, where each item has a trailing TAB character, and any TAB character in the body of an item has been replaced by ESC TAB.

The function can be used on a running system, or by copying the entire log directory and calling this function. SNMP must be running in order to provide MIB information.

LogDir is the name of the directory where the audit trail log is stored. Mibs is a list of Mibs to be used. The function uses the information in the Mibs to convert for example object identifiers to their symbolic name. OutFile is the name of the generated text-file. LogName is the name of the log, LogFile is the name of the log file. Start is the start (first) date and time from which log events will be converted and Stop is the stop (last) date and time to which log events will be converted. The Block argument indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

The format of an audit trail log text item is as follows:

Tag Addr - Community [TimeStamp] Vsn
PDU

where Tag is request, response, report, trap or inform; Addr is IP:Port (or comma space separated list of such); Community is the community parameter (SNMP version v1 and v2), or SecLevel:"AuthEngineID":"UserName" (SNMP v3); TimeStamp is a date and time stamp, and Vsn is the SNMP version. PDU is a textual version of the protocol data unit. There is a new line between Vsn and PDU.

If the entire log is successfully converted, the function will return ok. If one of more entries fail to convert, the function will instead return {ok, {NumOK, NumERR}}, where the counters indicate how many valid and erroneous entries where found. If instead {error, Reason} is returned, the conversion encountered a fatal error and where either never done of aborted midway.

Link to this function

octet_string_to_bits(S)

View Source

-spec octet_string_to_bits(S) -> bits() when S :: octet_string().

Utility function for converting a value of type OCTET-STRING to BITS, according to RFC1906, section 8.

Link to this function

passwd2localized_key(Algorithm, Passwd, EngineID)

View Source

-spec passwd2localized_key(Algorithm, Passwd, EngineID) -> Key
                        when
                            Algorithm :: algorithm(),
                            Passwd :: string(),
                            EngineID :: string(),
                            Key :: list().

Generates a key that can be used as an authentication or privacy key using MD5, SHA, SHA224, SHA256, SHA384 or SHA512. The key is localized for EngineID.

Link to this function

print_version_info()

View Source

-spec print_version_info() -> void().

Equivalent to print_version_info/1.

Link to this function

print_version_info(Prefix)

View Source

-spec print_version_info(Prefix) -> void() when Prefix :: string() | non_neg_integer().

Utility function(s) to produce a formatted printout of the versions info generated by the versions1 function

This is the same as doing, e.g.:

           {ok, V} = snmp:versions1(),
           snmp:print_versions(V).

Link to this function

print_versions(Versions)

View Source

-spec print_versions(Versions) -> void() when Versions :: [VersionInfo], VersionInfo :: term().

Equivalent to print_versions/2.

Link to this function

print_versions(Prefix, Versions)

View Source

-spec print_versions(Prefix, Versions) -> void()
                  when
                      Prefix :: string() | non_neg_integer(),
                      Versions :: [VersionInfo],
                      VersionInfo :: term().

Utility function to produce a formatted printout of the versions info generated by the versions1 and versions2 functions

Example:

           {ok, V} = snmp:versions1(),
           snmp:print_versions(V).

Link to this function

read_mib(FileName)

View Source

-spec read_mib(FileName) -> {ok, Mib} | {error, Reason}
            when FileName :: string(), Mib :: mib(), Reason :: term().

Read a compiled mib.

Link to this function

reset_trace(Targets)

View Source

-spec reset_trace(Targets) -> void() when Targets :: module() | [module()].

This function is used to reset (disable) trace for the given module(s).

Link to this function

set_trace(Targets)

View Source

-spec set_trace(Targets) -> void()
             when
                 Targets :: module() | [module() | {module(), [TargetOpt]}],
                 TargetOpt :: {return_trace, boolean()} | {scope, Scope},
                 Scope ::
                     all_functions | exported_functions | FunctionName |
                     {FunctionName, FunctionArity},
                 FunctionName :: atom(),
                 FunctionArity :: non_neg_integer().

This function is used to set up default trace on function(s) for the given module or modules. The scope of the trace will be all exported functions (both the call info and the return value). Timestamp info will also be included.

Link to this function

set_trace(Targets, TraceOpts)

View Source

-spec set_trace(Targets, TraceOpts) -> void()
             when
                 Targets :: module() | [module() | {module(), [TargetOpt]}],
                 TargetOpt :: {return_trace, boolean()} | {scope, Scope},
                 Scope ::
                     all_functions | exported_functions | FunctionName |
                     {FunctionName, FunctionArity},
                 FunctionName :: atom(),
                 FunctionArity :: non_neg_integer(),
                 TraceOpts :: disable | [TraceOpt],
                 TraceOpt :: {timestamp, boolean()} | TargetOpt.

This function is used to set up trace on function(s) for the given module or modules.

The example below sets up trace on the exported functions (default) of module snmp_generic and all functions of module snmp_generic_mnesia. With return values (which is default) and timestamps in both cases (which is also default):

	  snmp:enable_trace(),
	  snmp:set_trace([snmp_generic,
                          {snmp_generic_mnesia, [{scope, all_functions}]}]),
	  .
	  .
	  .
          snmp:set_trace(snmp_generic, disable),
	  .
	  .
	  .
	  snmp:disable_trace(),

Link to this function

start()

View Source

-spec start() -> ok | {error, Reason} when Reason :: term().

Equivalent to start/1.

Link to this function

start(Type)

View Source

-spec start(Type) -> ok | {error, Reason}
         when Type :: p | permanent | tr | transient | te | temporary, Reason :: term().

Starts the SNMP application.

See application for more info.

Link to this function

start_agent()

View Source

-spec start_agent() -> ok | {error, Reason} when Reason :: term().

Equivalent to start_agent/1.

Link to this function

start_agent(Type)

View Source

-spec start_agent(Type) -> ok | {error, Reason} when Type :: application:start_type(), Reason :: term().

The SNMP application consists of several entities, of which the agent is one. This function starts the agent entity of the application.

Note that the only way to actually start the agent in this way is to add the agent related config after starting the application (e.g it cannot be part of the normal application config; sys.config). This is done by calling: application:set_env(snmp, agent, Conf).

The default value for Type is normal.

Link to this function

start_manager()

View Source

-spec start_manager() -> ok | {error, Reason} when Reason :: term().

Equivalent to start_manager/1.

Link to this function

start_manager(Type)

View Source

-spec start_manager(Type) -> ok | {error, Reason}
                 when Type :: application:start_type(), Reason :: term().

The SNMP application consists of several entities, of which the manager is one. This function starts the manager entity of the application.

Note that the only way to actually start the manager in this way is to add the manager related config after starting the application (e.g it cannot be part of the normal application config; sys.config). This is done by calling: application:set_env(snmp, manager, Conf).

The default value for Type is normal.

Link to this function

stop()

View Source

-spec stop() -> ok | {error, Reason} when Reason :: term().

Stops the SNMP application.

See application for more info.

Link to this function

universal_time_to_date_and_time(UTC)

View Source

-spec universal_time_to_date_and_time(UTC) -> DateAndTime
                                   when
                                       UTC :: calendar:datetime(),
                                       DateAndTime :: rfc1903_date_and_time().

Converts a universal time value to a DateAndTime list. The universal time value on the same format as defined in calendar(3).

Link to this function

validate_date_and_time(DateAndTime)

View Source

-spec validate_date_and_time(DateAndTime) -> boolean() when DateAndTime :: rfc1903_date_and_time().

Equivalent to validate_date_and_time/2.

Link to this function

validate_date_and_time(DateAndTime, Validate)

View Source

-spec validate_date_and_time(DateAndTime, Validate) -> boolean()
                          when
                              DateAndTime :: rfc1903_date_and_time(),
                              Validate :: date_and_time_validator().

Checks if DateAndTime is a correct DateAndTime value, as specified in RFC2579. This function can be used in instrumentation functions to validate a DateAndTime value.

The validation fun, Validate, allows for a more "flexible" validation of the DateAndTime argument. Whenever the data is found to not follow RFC2579, the fun is called to allow a more "lax" validation.

Link to this function

versions1()

View Source

-spec versions1() -> {ok, VersionsInfo} | {error, Reason}
             when VersionsInfo :: [VersionInfo], VersionInfo :: term(), Reason :: term().

Equivalent to versions2/0.

Link to this function

versions2()

View Source

-spec versions2() -> {ok, VersionsInfo} | {error, Reason}
             when VersionsInfo :: [VersionInfo], VersionInfo :: term(), Reason :: term().

Utility functions used to retrieve some system and application info.

The difference between the two functions is in how they get the modules to check. versions1 uses the app-file and versions2 uses the function application:get_key.

snmp_community_mib

Instrumentation Functions for SNMP-COMMUNITY-MIB

The module snmp_community_mib implements the instrumentation functions for the SNMP-COMMUNITY-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Types

context_name()

A human readable string.

index()

SnmpAdminString (SIZE(1..32))

name()

OCTET STRING (SIZE(1..64))

security_name()

SnmpAdminString

transport_tag()

SnmpTagValue

Functions

add_community(Idx, CommName, SecName, CtxName, TransportTag)

Equivalent to add_community/6.

add_community(Idx, CommName, SecName, EngineId, CtxName, TransportTag)

Adds a community to the agent config. Equivalent to one line in the community.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_community(Key)

Delete a community from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Types

Link to this type

context_name()

View Source

-type context_name() :: snmp_framework_mib:admin_string().

A human readable string.

SnmpAdminString

Link to this type

index()

View Source

-type index() :: snmp_framework_mib:admin_string().

SnmpAdminString (SIZE(1..32))

Link to this type

name()

View Source

-type name() :: string().

OCTET STRING (SIZE(1..64))

Link to this type

security_name()

View Source

-type security_name() :: snmp_framework_mib:admin_string().

SnmpAdminString

Link to this type

transport_tag()

View Source

-type transport_tag() :: snmp_target_mib:tag_value().

SnmpTagValue

Functions

Link to this function

add_community(Idx, CommName, SecName, CtxName, TransportTag)

View Source (since OTP R14B03)

-spec add_community(Idx, CommName, SecName, CtxName, TransportTag) -> {ok, Key} | {error, Reason}
                 when
                     Idx :: index(),
                     CommName :: name(),
                     SecName :: security_name(),
                     CtxName :: context_name(),
                     TransportTag :: transport_tag(),
                     Key :: term(),
                     Reason :: term().

Equivalent to add_community/6.

Link to this function

add_community(Idx, CommName, SecName, EngineId, CtxName, TransportTag)

View Source (since OTP R14B03)

-spec add_community(Idx, CommName, SecName, EngineId, CtxName, TransportTag) ->
                 {ok, Key} | {error, Reason}
                 when
                     Idx :: index(),
                     CommName :: name(),
                     SecName :: security_name(),
                     EngineId :: snmp_framework_mib:engine_id(),
                     CtxName :: context_name(),
                     TransportTag :: transport_tag(),
                     Key :: term(),
                     Reason :: term().

Adds a community to the agent config. Equivalent to one line in the community.conf file.

With the EngineId argument it is possible to override the configured engine-id (SNMP-FRAMEWORK-MIB).

Link to this function

configure(ConfDir)

View Source

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error, report module and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: community.conf.

Link to this function

delete_community(Key)

View Source

-spec delete_community(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a community from the agent config.

Link to this function

reconfigure(ConfDir)

View Source

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-COMMUNITY-MIB, after this function has been called, is from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: community.conf.

snmp_framework_mib

Instrumentation Functions for SNMP-FRAMEWORK-MIB

The module snmp_framework_mib implements instrumentation functions for the SNMP-FRAMEWORK-MIB, and functions for initializing and configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Types

admin_string()

OCTET STRING (SIZE(0..255))

engine_id()

OCTET STRING (SIZE(5..32))

max_message_size()

Note

"The maximum length in octets of an SNMP message which this SNMP engine can send or receive and process, determined as the minimum of the maximum message size values supported among all of the transports available to and supported by the engine."

message_processing_model()

Note

"As of this writing, there are several values of messageProcessingModel defined for use with SNMP. They are as follows: "

security_level()

Note

"A Level of Security at which SNMP messages can be sent or with which operations are being processed; in particular, one of: "

security_model()

Note

"As of this writing, there are several values of securityModel defined for use with SNMP or reserved for use with supporting MIB objects. They are as follows: "

Functions

add_context(Ctx)

Adds a context to the agent config. Equivalent to one line in the context.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_context(Key)

Delete a context from the agent config.

init()

This function is called from the supervisor at system start-up.

Types

Link to this type

admin_string()

View Source

-type admin_string() :: string().

OCTET STRING (SIZE(0..255))

Link to this type

engine_id()

View Source

-type engine_id() :: string().

OCTET STRING (SIZE(5..32))

Link to this type

max_message_size()

View Source

-type max_message_size() :: 484..2147483647.

Note

"The maximum length in octets of an SNMP message which this SNMP engine can send or receive and process, determined as the minimum of the maximum message size values supported among all of the transports available to and supported by the engine."

INTEGER (484..2147483647)

Link to this type

message_processing_model()

View Source

-type message_processing_model() :: v1 | v2c | v3.

Note

"As of this writing, there are several values of messageProcessingModel defined for use with SNMP. They are as follows: "

                        0  reserved for SNMPv1
                        1  reserved for SNMPv2c
                        2  reserved for SNMPv2u and SNMPv2*
                        3  reserved for SNMPv3

INTEGER(0 .. 2147483647)

Link to this type

security_level()

View Source

-type security_level() :: noAuthNoPriv | authNoPriv | authPriv.

Note

"A Level of Security at which SNMP messages can be sent or with which operations are being processed; in particular, one of: "

                      noAuthNoPriv - without authentication and
                                     without privacy,
                      authNoPriv   - with authentication but
                                     without privacy,
                      authPriv     - with authentication and
                                     with privacy.

"These three values are ordered such that noAuthNoPriv is less than authNoPriv and authNoPriv is less than authPriv."

INTEGER { noAuthNoPriv(1), authNoPriv(2), authPriv(3) }

Link to this type

security_model()

View Source

-type security_model() :: any | v1 | v2c | usm.

Note

"As of this writing, there are several values of securityModel defined for use with SNMP or reserved for use with supporting MIB objects. They are as follows: "

                        0  reserved for 'any'
                        1  reserved for SNMPv1
                        2  reserved for SNMPv2c
                        3  User-Based Security Model (USM)

INTEGER(0 .. 2147483647)

Functions

Link to this function

add_context(Ctx)

View Source

-spec add_context(Ctx) -> {ok, Key} | {error, Reason}
               when Ctx :: string(), Key :: term(), Reason :: term().

Adds a context to the agent config. Equivalent to one line in the context.conf file.

Link to this function

configure(ConfDir)

View Source

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old data.

Thus, the data in the SNMP-FRAMEWORK-MIB, after this function has been called, is from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: context.conf.

Link to this function

delete_context(Key)

View Source

-spec delete_context(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a context from the agent config.

Link to this function

init()

View Source

-spec init() -> snmp:void().

This function is called from the supervisor at system start-up.

Creates the necessary objects in the database if they do not exist. It does not destroy any old values.

snmp_generic

Generic Functions for Implementing SNMP Objects in a Database

The module snmp_generic contains generic functions for implementing tables (and variables) using the SNMP built-in database or Mnesia. These default functions are used if no instrumentation function is provided for a managed object in a MIB. Sometimes, it might be necessary to customize the behaviour of the default functions. For example, in some situations a trap should be sent if a row is deleted or modified, or some hardware is to be informed, when information is changed.

The overall structure is shown in the following figure:

         +---------------+
         |   SNMP Agent  |
         +- - - - - - - -+
         |      MIB      |
         +---------------+
                 |
         Association file       (associates a MIB object with
                 |               snmp_generic:table_funct
                 |               snmp_generic:variable_func)
+--------------------------------------+
|           snmp_generic               |  Support for get-next,
|                                      |  RowStatus operations
+----------------------+---------------+
|    snmpa_local_db    |    Mnesia     |  Database
+--------------+-------+---------------+
|     dets     |  ets  |
| (persistent) |       |
+--------------+-------+

Each function takes the argument NameDb, which is a tuple {Name, Db}, to identify which database the functions should use. Name is the symbolic name of the managed object as defined in the MIB, and Db is either volatile, persistent, or mnesia. If it is mnesia, all variables are stored in the Mnesia table snmp_variables which must be a table with two attributes (not a Mnesia SNMP table). The SNMP tables are stored in Mnesia tables with the same names as the SNMP tables. All functions assume that a Mnesia table exists with the correct name and attributes. It is the programmer's responsibility to ensure this. Specifically, if variables are stored in Mnesia, the table snmp_variables must be created by the programmer. The record definition for this table is defined in the file snmp/include/snmp_types.hrl.

If an instrumentation function in the association file for a variable myVar does not have a name when compiling an MIB, the compiler generates an entry.

{myVar, {snmp_generic, variable_func, [{myVar, Db]}}.

And for a table:

{myTable, {snmp_generic, table_func, [{myTable, Db]}}.

DATA TYPES

In the functions defined below, the following types are used:

name_db() = {name(), db()}
name() = atom()
db() = volatile | persistent | mnesia
row_index() = [int()]
columns() = [column()] | [{column(), value()}]
column() = int()
value() = term()

row_index() - Denotes the last part of the OID which specifies the index of the row in the table (see RFC1212, 4.1.6 for more information about INDEX).

columns/0 - Is a list of column numbers in the case of a get operation, and a list of column numbers and values in the case of a set operation.

Example

The following example shows an implementation of a table which is stored in Mnesia, but with some checks performed at set-request operations.

myTable_func(new, NameDb) ->   % pass unchanged
  snmp_generic:table_func(new, NameDb).

myTable_func(delete, NameDb) ->   % pass unchanged
  snmp_generic:table_func(delete, NameDb).

%% change row
myTable_func(is_set_ok, RowIndex, Cols, NameDb) ->
  case snmp_generic:table_func(is_set_ok, RowIndex,
                               Cols, NameDb) of
    {noError, 0} ->
      myApplication:is_set_ok(RowIndex, Cols);
    Err ->
      Err
  end;

myTable_func(set, RowIndex, Cols, NameDb) ->
  case snmp_generic:table_func(set, RowIndex, Cols,
                               NameDb),
    {noError, 0} ->
      % Now the row is updated, tell the application
      myApplication:update(RowIndex, Cols);
    Err ->
      Err
  end;

myTable_func(Op, RowIndex, Cols, NameDb) ->   % pass unchanged
  snmp_generic:table_func(Op, RowIndex, Cols, NameDb).

The .funcs file would look like:

{myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.

Summary

Types

column()

columns()

Is a list of column numbers in the case of a get operation, and a list of column numbers and values in the case of a set operation.

table_info_item()

For an ordinary table, the types will be the following

Functions

get_index_types(Name)

Gets the index types of Name

get_status_col(Name, Cols)

Gets the value of the status column from Cols.

get_table_info/2

Get the specific table info item (nbr_of_cols).

table_func(Op, NameDb)

This is the default instrumentation function for tables.

table_func(Op, RowIndex, Cols, NameDb)

This is the default instrumentation function for tables.

table_get_elements(NameDb, RowIndex, Cols)

Returns a list with values for all columns in Cols. If a column is undefined, its value is noinit.

table_next/2

table_next(NameDb, RestOid) -> RowIndex | endOfTable

table_row_exists(NameDb, RowIndex)

table_row_exists(NameDb, RowIndex) -> bool()

table_set_elements/3

table_set_elements(NameDb, RowIndex, Cols) -> bool()

variable_func/2

This is the default instrumentation function for variables.

variable_func/3

This is the default instrumentation function for variables.

variable_get(Name)

Gets the value of a variable.

variable_set(Name, Value)

Sets a new value to a variable. The variable is created if it does not exist. No checks are made on the type of the new value.

Types

Link to this type

column()

View Source

-type column() :: pos_integer().

Link to this type

columns()

View Source

-type columns() :: [column()] | [{column(), Value :: term()}].

Is a list of column numbers in the case of a get operation, and a list of column numbers and values in the case of a set operation.

Link to this type

table_info_item()

View Source (not exported)

-type table_info_item() ::
    nbr_of_cols | defvals | status_col | not_accessible | index_types | first_accessible |
    first_own_index.

For an ordinary table, the types will be the following:

nbr_of_cols - Number of columns.

Value type: pos_integer()

defvals - A list of default values, ordered by column.

Value type: [{Col :: pos_integer(), DefVal :: term()}]

status_col - Column number of the status column.

Value type: pos_integer()

not_accessible - A sorted list of columns (> first_accessible) that are 'not-accessible'.

Value type: [pos_integer()]

index_types - A list of asn1_type() for the index columns, ordered by column number or an "augment"-tuple (see below).

Value type: [asn1_type()]

first_accessible - The first accessible column.

Value type: pos_integer()

first_own_index - Column number of the first own index. Will be 0 if there is no such index for this table.

Value type: non_neg_integer()

For a augmented table, it will instead look like this:

index_types - Value type: {augments, {atom(), asn1_type()}}

nbr_of_cols - Value type: pos_integer()

not_accessible - Value type: [pos_integer()]

first_accessible - Value type: pos_integer()

Functions

Link to this function

get_index_types(Name)

View Source

-spec get_index_types(Name) -> IndexTypes
                   when Name :: snmpa:name() | snmpa:name_db(), IndexTypes :: [snmp:asn1_type()].

Gets the index types of Name

This function can be used in instrumentation functions to retrieve the index types part of the table info.

Link to this function

get_status_col(Name, Cols)

View Source

-spec get_status_col(Name, Cols) -> false | {value, StatusCol}
                  when
                      Name :: snmpa:name() | snmpa:name_db(),
                      Cols :: columns(),
                      StatusCol :: term().

Gets the value of the status column from Cols.

This function can be used in instrumentation functions for is_set_ok, undo or set to check if the status column of a table is modified.

Link to this function

get_table_info/2

View Source (since OTP R15B01)

-spec get_table_info(Name, Item :: nbr_of_cols) -> Result
                  when Name :: snmpa:name() | snmpa:name_db(), Result :: pos_integer();
              (Name, Item :: defvals) -> Result
                  when
                      Name :: snmpa:name() | snmpa:name_db(),
                      Result :: [{Col, DefVal}],
                      Col :: pos_integer(),
                      DefVal :: term();
              (Name, Item :: status_col) -> Result
                  when Name :: snmpa:name() | snmpa:name_db(), Result :: pos_integer();
              (Name, Item :: not_accessible) -> Result
                  when Name :: snmpa:name() | snmpa:name_db(), Result :: [pos_integer()];
              (Name, Item :: index_types) -> Result
                  when Name :: snmpa:name() | snmpa:name_db(), Result :: [snmp:asn1_type()];
              (Name, Item :: first_accessible) -> Result
                  when Name :: snmpa:name() | snmpa:name_db(), Result :: pos_integer();
              (Name, Item :: first_own_index) -> Result
                  when Name :: snmpa:name() | snmpa:name_db(), Result :: non_neg_integer();
              (Name, Item :: all) -> Result
                  when
                      Name :: snmpa:name() | snmpa:name_db(),
                      Result :: [{table_info_item(), term()}].

Get the specific table info item (nbr_of_cols).

This function can be used in instrumentation functions to retrieve a given part of the table info.

Get a specific table info item (defvals).

This function can be used in instrumentation functions to retrieve a given part of the table info.

Get a specific table info item (status_col).

This function can be used in instrumentation functions to retrieve a given part of the table info.

Get a specific table info item (not_accessible).

This function can be used in instrumentation functions to retrieve a given part of the table info.

Get a specific table info item (index_types).

This function can be used in instrumentation functions to retrieve a given part of the table info.

Get a specific table info item (first_accessible).

This function can be used in instrumentation functions to retrieve a given part of the table info.

Get a specific table info item (first_own_index).

This function can be used in instrumentation functions to retrieve a given part of the table info.

Get all table info item(s), a two tuple list (property list) is returned with all the items and their respctive values of the given table.

This function can be used in instrumentation functions to retrieve a given part of the table info.

Link to this function

table_func(Op, NameDb)

View Source

-spec table_func(Op, NameDb) -> Return
              when Op :: new | delete, NameDb :: snmpa:name_db(), Return :: term().

This is the default instrumentation function for tables.

The new function creates the table if it does not exist, but only if the database is the SNMP internal db.

The delete function does not delete the table from the database since unloading an MIB does not necessarily mean that the table should be destroyed.

If it is possible for a manager to create or delete rows in the table, there must be a RowStatus column for is_set_ok, set and undo to work properly.

The function returns according to the specification of an instrumentation function.

Link to this function

table_func(Op, RowIndex, Cols, NameDb)

View Source

-spec table_func(Op, RowIndex, Cols, NameDb) -> Return
              when
                  Op :: get | next | is_set_ok | set | undo,
                  RowIndex :: snmp:row_index(),
                  Cols :: columns(),
                  NameDb :: snmpa:name_db(),
                  Return :: term().

This is the default instrumentation function for tables.

The is_set_ok function checks that a row which is to be modified or deleted exists, and that a row which is to be created does not exist.

The undo function does nothing.

The set function checks if it has enough information to make the row change its status from notReady to notInService (when a row has been been set to createAndWait). If a row is set to createAndWait, columns without a value are set to noinit. If Mnesia is used, the set functionality is handled within a transaction.

If it is possible for a manager to create or delete rows in the table, there must be a RowStatus column for is_set_ok, set and undo to work properly.

The function returns according to the specification of an instrumentation function.

Link to this function

table_get_elements(NameDb, RowIndex, Cols)

View Source

-spec table_get_elements(NameDb, RowIndex, Cols) -> Values
                      when
                          NameDb :: snmpa:name_db(),
                          RowIndex :: snmp:row_index(),
                          Cols :: columns(),
                          Values :: [noinit | Value],
                          Value :: term().

Returns a list with values for all columns in Cols. If a column is undefined, its value is noinit.

Link to this function

table_next/2

View Source

table_next(NameDb, RestOid) -> RowIndex | endOfTable

Finds the indices of the next row in the table. RestOid does not have to specify an existing row.

Link to this function

table_row_exists(NameDb, RowIndex)

View Source

table_row_exists(NameDb, RowIndex) -> bool()

Checks if a row in a table exists.

Link to this function

table_set_elements/3

View Source

table_set_elements(NameDb, RowIndex, Cols) -> bool()

Sets the elements in Cols to the row specified by RowIndex. No checks are performed on the new values.

If the Mnesia database is used, this function calls mnesia:write to store the values. This means that this function must be called from within a transaction (mnesia:transaction/1).

Link to this function

variable_func/2

View Source

-spec variable_func(Op :: new, Name) -> Result
                 when Name :: snmpa:name() | snmpa:name_db(), Result :: ok | boolean();
             (Op :: delete, Name) -> Result
                 when Name :: snmpa:name() | snmpa:name_db(), Result :: ok;
             (Op :: get, Name) -> Result
                 when
                     Name :: snmpa:name() | snmpa:name_db(),
                     Result :: {value, Value} | genErr,
                     Value :: term().

This is the default instrumentation function for variables.

The new function creates a new variable in the database with a default value as defined in the MIB, or a zero value (depending on the type).

The function returns according to the specification of an instrumentation function.

This is the default instrumentation function for variables.

The delete function does not delete the variable from the database.

The function returns according to the specification of an instrumentation function.

This is the default instrumentation function for variables.

The function returns according to the specification of an instrumentation function.

Link to this function

variable_func/3

View Source

-spec variable_func(Op :: is_set_ok, Value, Name) -> Result
                 when Value :: term(), Name :: snmpa:name() | snmpa:name_db(), Result :: noError;
             (Op :: set, Value, Name) -> Result
                 when
                     Value :: term(),
                     Name :: snmpa:name() | snmpa:name_db(),
                     Result :: noError | commitFailed;
             (Op :: undo, Value, Name) -> Result
                 when Value :: term(), Name :: snmpa:name() | snmpa:name_db(), Result :: noError.

This is the default instrumentation function for variables.

The function returns according to the specification of an instrumentation function.

This is the default instrumentation function for variables.

The function returns according to the specification of an instrumentation function.

This is the default instrumentation function for variables.

The function returns according to the specification of an instrumentation function.

Link to this function

variable_get(Name)

View Source

-spec variable_get(Name) -> {value, Value} | undefined
                when Name :: snmpa:name() | snmpa:name_db(), Value :: term().

Gets the value of a variable.

Link to this function

variable_set(Name, Value)

View Source

-spec variable_set(Name, Value) -> boolean()
                when Name :: snmpa:name() | snmpa:name_db(), Value :: term().

Sets a new value to a variable. The variable is created if it does not exist. No checks are made on the type of the new value.

Returns false if the NameDb argument is incorrectly specified, otherwise true.

snmp_index

Abstract Data Type for SNMP Indexing

The module snmp_index implements an Abstract Data Type (ADT) for an SNMP index structure for SNMP tables. It is implemented as an ets table of the ordered_set data-type, which means that all operations are O(log n). In the table, the key is an ASN.1 OBJECT IDENTIFIER.

This index is used to separate the implementation of the SNMP ordering from the actual implementation of the table. The SNMP ordering, that is implementation of GET NEXT, is implemented in this module.

For example, suppose there is an SNMP table, which is best implemented in Erlang as one process per SNMP table row. Suppose further that the INDEX in the SNMP table is an OCTET STRING. The index structure would be created as follows:

snmp_index:new(string)

For each new process we create, we insert an item in an snmp_index structure:

new_process(Name, SnmpIndex) ->
  Pid = start_process(),
  NewSnmpIndex =
    snmp_index:insert(SnmpIndex, Name, Pid),
  <...>

With this structure, we can now map an OBJECT IDENTIFIER in e.g. a GET NEXT request, to the correct process:

get_next_pid(Oid, SnmpIndex) ->
  {ok, {_, Pid}} = snmp_index:get_next(SnmpIndex, Oid),
  Pid.

Warnings

Warning

All API functions that update the index return a NewIndex term. This is for backward compatibility with a previous implementation that used a B+ tree written purely in Erlang for the index. The NewIndex return value can now be ignored. The return value is now the unchanged table identifier for the ets table.

The implementation using ets tables introduces a semantic incompatibility with older implementations. In those older implementations, using pure Erlang terms, the index was garbage collected like any other Erlang term and did not have to be deleted when discarded. An ets table is deleted only when the process creating it explicitly deletes it or when the creating process terminates.

A new interface delete/1 is now added to handle the case when a process wants to discard an index table (i.e. to build a completely new). Any application using transient snmp indexes has to be modified to handle this.

As an snmp adaption usually keeps the index for the whole of the systems lifetime, this is rarely a problem.

Summary

Types

index()

This type denotes an snmp index structure.

key()

This type correlates to the key_types/0 type. If the key_types/0 is a single atom, the corresponding key/0 is a single type as well, but if the key_types/0 is a tuple, key/0 must be a tuple of the same size.

key_spec()

key_types()

This type is used when creating the index structure, and the key/0 type is used when inserting and deleting items from the structure.

type_spec()

Functions

delete(Index)

Deletes a complete index structure (i.e. the ets table holding the index). The index can no longer be referenced after this call. See the warning note above.

delete(Index, Key)

Deletes a key and its value from the index structure. Returns a new structure.

get(Index, KeyOid)

Gets the item with key KeyOid. Could be used from within an SNMP instrumentation function.

get_last(Index)

Gets the last item in the index structure.

get_next(Index, KeyOid)

Gets the next item in the SNMP lexicographic ordering, after KeyOid in the index structure. KeyOid does not have to refer to an existing item in the index.

insert(Index, Key, Value)

Inserts a new key value tuple into the index structure. If an item with the same key already exists, the new Value overwrites the old value.

key_to_oid(Index, Key)

Converts Key to an OBJECT IDENTIFIER.

new(KeyTypes)

Equivalent to new/2.

new(KeyTypes, Name)

Creates a new snmp index structure.

Types

Link to this opaque

index()

View Source

-opaque index()

This type denotes an snmp index structure.

Link to this type

key()

View Source

-type key() :: key_spec() | tuple().

This type correlates to the key_types/0 type. If the key_types/0 is a single atom, the corresponding key/0 is a single type as well, but if the key_types/0 is a tuple, key/0 must be a tuple of the same size.

In the example above, valid keys could be {"hi", "mom"} and {"no", "thanks"}, whereas "hi", {"hi", 42} and {"hello", "there"} would be invalid.

There is no way to propely describe this type in the erlang type language, which is why tuple/0 was used above. The proper definition looks like:

key() = key_spec() | {key_spec(), key_spec(), ...}

Link to this type

key_spec()

View Source

-type key_spec() :: string() | integer().

Link to this type

key_types()

View Source

-type key_types() :: type_spec() | tuple().

This type is used when creating the index structure, and the key/0 type is used when inserting and deleting items from the structure.

If the INDEX column is of type INTEGER, or derived from INTEGER, the corresponding type should be integer. If it is a variable length type (e.g. OBJECT IDENTIFIER, OCTET STRING), the corresponding type should be string. Finally, if the type is of variable length, but with a fixed size restriction (e.g. IpAddress), the corresponding type should be fix_string.

There is no way to propely describe this type in the erlang type language, which is why tuple/0 was used above. The proper definition looks like:

key_types = type_spec() | {type_spec(), type_spec(), ...}

Link to this type

type_spec()

View Source

-type type_spec() :: fix_string | string | integer.

Functions

Link to this function

delete(Index)

View Source

-spec delete(Index) -> true when Index :: index().

Deletes a complete index structure (i.e. the ets table holding the index). The index can no longer be referenced after this call. See the warning note above.

Link to this function

delete(Index, Key)

View Source

-spec delete(Index, Key) -> NewIndex when Index :: index(), Key :: key(), NewIndex :: index().

Deletes a key and its value from the index structure. Returns a new structure.

Link to this function

get(Index, KeyOid)

View Source

-spec get(Index, KeyOid) -> {ok, {KeyOid, Value}} | undefined
       when Index :: index(), KeyOid :: snmp:oid(), Value :: term().

Gets the item with key KeyOid. Could be used from within an SNMP instrumentation function.

Link to this function

get_last(Index)

View Source

-spec get_last(Index) -> {ok, {KeyOid, Value}} | undefined
            when Index :: index(), KeyOid :: snmp:oid(), Value :: term().

Gets the last item in the index structure.

Link to this function

get_next(Index, KeyOid)

View Source

-spec get_next(Index, KeyOid) -> {ok, {NextKeyOid, Value}} | undefined
            when Index :: index(), KeyOid :: snmp:oid(), NextKeyOid :: snmp:oid(), Value :: term().

Gets the next item in the SNMP lexicographic ordering, after KeyOid in the index structure. KeyOid does not have to refer to an existing item in the index.

Link to this function

insert(Index, Key, Value)

View Source

-spec insert(Index, Key, Value) -> NewIndex
          when Index :: index(), Key :: key(), Value :: term(), NewIndex :: index().

Inserts a new key value tuple into the index structure. If an item with the same key already exists, the new Value overwrites the old value.

Link to this function

key_to_oid(Index, Key)

View Source

-spec key_to_oid(Index, Key) -> KeyOid when Index :: index(), Key :: key(), KeyOid :: snmp:oid().

Converts Key to an OBJECT IDENTIFIER.

Link to this function

new(KeyTypes)

View Source

-spec new(KeyTypes) -> Index when KeyTypes :: key_types(), Index :: index().

Equivalent to new/2.

Link to this function

new(KeyTypes, Name)

View Source

-spec new(KeyTypes, Name) -> Index when KeyTypes :: key_types(), Name :: atom(), Index :: index().

Creates a new snmp index structure.

snmp_notification_mib

Instrumentation Functions for SNMP-NOTIFICATION-MIB

The module snmp_notification_mib implements the instrumentation functions for the SNMP-NOTIFICATION-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Types

notify_name()

SnmpAdminString (SIZE(1..32))

notify_tag()

notify_type()

Functions

add_notify(Name, Tag, Type)

Adds a notify definition to the agent config. Equivalent to one line in the notify.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_notify(Key)

Delete a notify definition from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Types

Link to this type

notify_name()

View Source

-type notify_name() :: snmp_framework_mib:admin_string().

SnmpAdminString (SIZE(1..32))

Link to this type

notify_tag()

View Source

-type notify_tag() :: snmp_target_mib:tag_value().

Link to this type

notify_type()

View Source

-type notify_type() :: trap | inform.

Functions

Link to this function

add_notify(Name, Tag, Type)

View Source

-spec add_notify(Name, Tag, Type) -> {ok, Key} | {error, Reason}
              when
                  Name :: notify_name(),
                  Tag :: notify_tag(),
                  Type :: notify_type(),
                  Key :: term(),
                  Reason :: term().

Adds a notify definition to the agent config. Equivalent to one line in the notify.conf file.

Link to this function

configure(ConfDir)

View Source

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: notify.conf.

Link to this function

delete_notify(Key)

View Source

-spec delete_notify(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a notify definition from the agent config.

Link to this function

reconfigure(ConfDir)

View Source

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-NOTIFICATION-MIB, after this function has been called, is from the configuration files.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: notify.conf.

snmp_pdus

Encode and Decode Functions for SNMP PDUs

RFC1157, RFC1905 and/or RFC2272 should be studied carefully before using this module, snmp_pdus.

The module snmp_pdus contains functions for encoding and decoding of SNMP protocol data units (PDUs). In short, this module converts a list of bytes to Erlang record representations and vice versa. The record definitions can be found in the file snmp/include/snmp_types.hrl. If snmpv3 is used, the module that includes snmp_types.hrl must define the constant SNMP_USE_V3 before the header file is included. Example:

-define(SNMP_USE_V3, true).
-include_lib("snmp/include/snmp_types.hrl").

Encoding and decoding must be done explicitly when writing your own Net if process.

Summary

Types

message()

The message is version dependent. 'vsn_hdr' is either a community string (v1 and v2) or a 'v3_hdr' record (v3). 'data' is either a PDU (v1 and v2c) or a (possibly encrypted) 'scopedPdu'.

msg_id()

msg_security_model()

pdu()

pdu_type()

scoped_pdu()

trappdu()

usm_security_parameters()

v3_hdr()

version()

Functions

dec_message(Bytes)

Decodes a list of bytes into an SNMP Message. Note, if there is a v3 message, the msgSecurityParameters are not decoded. They must be explicitly decoded by a call to a security model specific decoding function, e.g. dec_usm_security_parameters/1. Also note, if the scopedPDU is encrypted, the OCTET STRING encoded encryptedPDU will be present in the data field.

dec_message_only(Bytes)

Decodes a list of bytes into an SNMP Message, but does not decode the data part of the Message. That means, data is still a list of bytes, normally an encoded PDU (v1 and V2) or an encoded and possibly encrypted scopedPDU (v3).

dec_pdu(Bytes)

Decodes a list of bytes into an SNMP Pdu.

dec_scoped_pdu(Bytes)

Decodes a list of bytes into an SNMP ScopedPdu.

dec_scoped_pdu_data(Bytes)

Decodes a list of bytes into either a scoped pdu record, or - if the scoped pdu was encrypted - to a list of bytes.

dec_usm_security_parameters(Bytes)

Decodes a list of bytes into an SNMP UsmSecurityParameters.

enc_message(Message)

Encodes a message record to a list of bytes.

enc_message_only(Message)

Message is a record where the data field is assumed to be encoded (a list of bytes). If there is a v1 or v2 message, the data field is an encoded PDU, and if there is a v3 message, data is an encoded and possibly encrypted scopedPDU.

enc_pdu(Pdu)

Encodes an SNMP Pdu into a list of bytes.

enc_scoped_pdu(ScopedPdu)

Encodes an SNMP ScopedPdu into a list of bytes, which can be encrypted, and after encryption, encoded with a call to enc_encrypted_scoped_pdu/1; or it can be used as the data field in a message record, which then can be encoded with enc_message_only/1.

enc_usm_security_parameters(UsmSecParams)

Encodes SNMP UsmSecurityParameters into a list of bytes.

Types

Link to this type

message()

View Source

-type message() :: #message{version :: term(), vsn_hdr :: term(), data :: term()}.

The message is version dependent. 'vsn_hdr' is either a community string (v1 and v2) or a 'v3_hdr' record (v3). 'data' is either a PDU (v1 and v2c) or a (possibly encrypted) 'scopedPdu'.

Link to this type

msg_id()

View Source

-type msg_id() :: 0..2147483647.

Link to this type

msg_security_model()

View Source

-type msg_security_model() :: 0..2147483647.

Link to this type

pdu()

View Source

-type pdu() ::
    #pdu{type :: term(),
         request_id :: term(),
         error_status :: term(),
         error_index :: term(),
         varbinds :: term()}.

Link to this type

pdu_type()

View Source

-type pdu_type() ::
    'get-request' | 'get-next-request' | 'get-bulk-request' | 'get-response' | 'set-request' |
    'inform-request' | 'snmpv2-trap' | report.

Link to this type

scoped_pdu()

View Source

-type scoped_pdu() :: #scopedPdu{contextEngineID :: term(), contextName :: term(), data :: term()}.

Link to this type

trappdu()

View Source

-type trappdu() ::
    #trappdu{enterprise :: term(),
             agent_addr :: term(),
             generic_trap :: term(),
             specific_trap :: term(),
             time_stamp :: term(),
             varbinds :: term()}.

Link to this type

usm_security_parameters()

View Source

-type usm_security_parameters() ::
    #usmSecurityParameters{msgAuthoritativeEngineID :: term(),
                           msgAuthoritativeEngineBoots :: term(),
                           msgAuthoritativeEngineTime :: term(),
                           msgUserName :: term(),
                           msgAuthenticationParameters :: term(),
                           msgPrivacyParameters :: term()}.

Link to this type

v3_hdr()

View Source

-type v3_hdr() ::
    #v3_hdr{msgID :: term(),
            msgMaxSize :: term(),
            msgFlags :: term(),
            msgSecurityModel :: term(),
            msgSecurityParameters :: term(),
            hdr_size :: term()}.

Link to this type

version()

View Source

-type version() :: 'version-1' | 'version-2' | 'version-3'.

Functions

Link to this function

dec_message(Bytes)

View Source

-spec dec_message(Bytes) -> Message when Bytes :: [byte()], Message :: message().

Decodes a list of bytes into an SNMP Message. Note, if there is a v3 message, the msgSecurityParameters are not decoded. They must be explicitly decoded by a call to a security model specific decoding function, e.g. dec_usm_security_parameters/1. Also note, if the scopedPDU is encrypted, the OCTET STRING encoded encryptedPDU will be present in the data field.

Link to this function

dec_message_only(Bytes)

View Source

-spec dec_message_only(Bytes) -> Message when Bytes :: [byte()], Message :: message().

Decodes a list of bytes into an SNMP Message, but does not decode the data part of the Message. That means, data is still a list of bytes, normally an encoded PDU (v1 and V2) or an encoded and possibly encrypted scopedPDU (v3).

Link to this function

dec_pdu(Bytes)

View Source

-spec dec_pdu(Bytes) -> Pdu when Bytes :: [byte()], Pdu :: trappdu() | pdu().

Decodes a list of bytes into an SNMP Pdu.

Link to this function

dec_scoped_pdu(Bytes)

View Source

-spec dec_scoped_pdu(Bytes) -> ScopedPDU when Bytes :: [byte()], ScopedPDU :: scoped_pdu().

Decodes a list of bytes into an SNMP ScopedPdu.

Link to this function

dec_scoped_pdu_data(Bytes)

View Source

-spec dec_scoped_pdu_data(Bytes) -> ScopedPduData
                       when
                           Bytes :: [byte()],
                           ScopedPduData :: scoped_pdu() | EncryptedPDU,
                           EncryptedPDU :: [byte()].

Decodes a list of bytes into either a scoped pdu record, or - if the scoped pdu was encrypted - to a list of bytes.

Link to this function

dec_usm_security_parameters(Bytes)

View Source

-spec dec_usm_security_parameters(Bytes) -> UsmSecParams
                               when Bytes :: [byte()], UsmSecParams :: usm_security_parameters().

Decodes a list of bytes into an SNMP UsmSecurityParameters.

Link to this function

enc_message(Message)

View Source

-spec enc_message(Message) -> Bytes when Message :: message(), Bytes :: [byte()].

Encodes a message record to a list of bytes.

Link to this function

enc_message_only(Message)

View Source

-spec enc_message_only(Message) -> Bytes when Message :: message(), Bytes :: [byte()].

Message is a record where the data field is assumed to be encoded (a list of bytes). If there is a v1 or v2 message, the data field is an encoded PDU, and if there is a v3 message, data is an encoded and possibly encrypted scopedPDU.

Link to this function

enc_pdu(Pdu)

View Source

-spec enc_pdu(Pdu) -> Bytes when Pdu :: pdu(), Bytes :: [byte()].

Encodes an SNMP Pdu into a list of bytes.

Link to this function

enc_scoped_pdu(ScopedPdu)

View Source

-spec enc_scoped_pdu(ScopedPdu) -> Bytes when ScopedPdu :: scoped_pdu(), Bytes :: [byte()].

Encodes an SNMP ScopedPdu into a list of bytes, which can be encrypted, and after encryption, encoded with a call to enc_encrypted_scoped_pdu/1; or it can be used as the data field in a message record, which then can be encoded with enc_message_only/1.

Link to this function

enc_usm_security_parameters(UsmSecParams)

View Source

-spec enc_usm_security_parameters(UsmSecParams) -> Bytes
                               when UsmSecParams :: usm_security_parameters(), Bytes :: [byte()].

Encodes SNMP UsmSecurityParameters into a list of bytes.

snmp_standard_mib

Instrumentation Functions for STANDARD-MIB and SNMPv2-MIB

The module snmp_standard_mib implements the instrumentation functions for the STANDARD-MIB and SNMPv2-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Functions

configure(ConfDir)

This function is called from the supervisor at system start-up.

inc(Name)

Equivalent to inc/2.

inc(Name, N)

Increments a variable in the MIB with N, or one if N is not specified.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

reset()

Resets all snmp counters to 0.

sys_up_time()

Gets the system up time in hundredth of a second.

Functions

Link to this function

configure(ConfDir)

View Source

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: standard.conf.

Link to this function

inc(Name)

View Source

-spec inc(Name) -> snmp:void() when Name :: atom().

Equivalent to inc/2.

Link to this function

inc(Name, N)

View Source

-spec inc(Name, N) -> snmp:void() when Name :: atom(), N :: integer().

Increments a variable in the MIB with N, or one if N is not specified.

Link to this function

reconfigure(ConfDir)

View Source

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-STANDARD-MIB and SNMPv2-MIB, after this function has been called, is from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: standard.conf.

Link to this function

reset()

View Source

-spec reset() -> snmp:void().

Resets all snmp counters to 0.

Link to this function

sys_up_time()

View Source

-spec sys_up_time() -> Time when Time :: integer().

Gets the system up time in hundredth of a second.

snmp_target_mib

Instrumentation Functions for SNMP-TARGET-MIB

The module snmp_target_mib implements the instrumentation functions for the SNMP-TARGET-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Legacy API functions add_addr/10 that does not specify transport domain, and add_addr/11 that has got separate IpAddr and PortNumber arguments still work as before for backwards compatibility reasons.

DATA TYPES

See the data types in snmpa_conf.

Summary

Types

mms()

Note

"The maximum message size value associated with an entry in the snmpTargetAddrTable.".

name()

Note

"The locally arbitrary, but unique identifier associated with this snmpTargetAddrEntry."

params()

Note

"The value of this object identifies an entry in the snmpTargetParamsTable."

retry_count()

Note

"This object specifies a default number of retries to be attempted when a response is not received for a generated message."

tag_list()

Note

"An octet string containing a list of tag values. Tag values are preferably in human-readable form."

tag_value()

Note

"An octet string containing a tag value. Tag values are preferably in human-readable form."

tmask()

Note

"The mask value associated with an entry in the snmpTargetAddrTable. The value of this object must have the same length as the corresponding instance of snmpTargetAddrTAddress, or must have length 0."

Functions

add_addr/10

Adds a target address definition to the agent config. Equivalent to one line in the target_addr.conf file.

add_params(Name, MPModel, SecModel, SecName, SecLevel)

Adds a target parameter definition to the agent config. Equivalent to one line in the target_params.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_addr(Key)

Delete a target address definition from the agent config.

delete_params(Key)

Delete a target parameter definition from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

set_target_engine_id(TargetAddrName, EngineId)

Changes the engine id for a target in the snmpTargetAddrTable. If notifications are sent as Inform requests to a target, its engine id must be set.

Types

Link to this type

mms()

View Source

-type mms() :: 484..65535.

Note

"The maximum message size value associated with an entry in the snmpTargetAddrTable.".

Integer32 (484..65535)

Link to this type

name()

View Source

-type name() :: snmp_framework_mib:admin_string().

Note

"The locally arbitrary, but unique identifier associated with this snmpTargetAddrEntry."

SnmpAdminString (SIZE(1..32))

Link to this type

params()

View Source

-type params() :: snmp_framework_mib:admin_string().

Note

"The value of this object identifies an entry in the snmpTargetParamsTable."

SnmpAdminString (SIZE(1..32))

Link to this type

retry_count()

View Source

-type retry_count() :: 0..255.

Note

"This object specifies a default number of retries to be attempted when a response is not received for a generated message."

Integer32 (0..255)

Link to this type

tag_list()

View Source

-type tag_list() :: string().

Note

"An octet string containing a list of tag values. Tag values are preferably in human-readable form."

"To facilitate internationalization, this information is represented using the ISO/IEC IS 10646-1 character set, encoded as an octet string using the UTF-8 character encoding scheme described in RFC 2279."

OCTET STRING (SIZE (0..255))

Link to this type

tag_value()

View Source

-type tag_value() :: string().

Note

"An octet string containing a tag value. Tag values are preferably in human-readable form."

OCTET STRING (SIZE (0..255))

Link to this type

tmask()

View Source

-type tmask() :: snmpa_conf:transportAddressMask().

Note

"The mask value associated with an entry in the snmpTargetAddrTable. The value of this object must have the same length as the corresponding instance of snmpTargetAddrTAddress, or must have length 0."

OCTET STRING (SIZE (0..255))

Functions

Link to this function

add_addr/10

View Source

-spec add_addr(Name, TDomain, TAddr, Timeout, Retry, TagList, Params, EngineId, TMask, MMS) ->
            {ok, Key} | {error, Reason}
            when
                Name :: name(),
                TDomain :: snmpa_conf:transportDomain(),
                TAddr :: snmpa_conf:transportAddress(),
                Timeout :: snmp:time_interval(),
                Retry :: integer(),
                TagList :: tag_list(),
                Params :: params(),
                EngineId :: snmp_framework_mib:engine_id(),
                TMask :: tmask(),
                MMS :: snmp_framework_mib:max_message_size(),
                Key :: term(),
                Reason :: term();
        (Name, Ip, Port, Timeout, Retry, TagList, Params, EngineId, TMask, MMS) ->
            {ok, Key} | {error, Reason}
            when
                Name :: name(),
                Ip :: snmpa_conf:transportAddressWithoutPort(),
                Port :: inet:port_number(),
                Timeout :: snmp:time_interval(),
                Retry :: integer(),
                TagList :: tag_list(),
                Params :: params(),
                EngineId :: snmp_framework_mib:engine_id(),
                TMask :: tmask(),
                MMS :: snmp_framework_mib:max_message_size(),
                Key :: term(),
                Reason :: term().

Adds a target address definition to the agent config. Equivalent to one line in the target_addr.conf file.

Link to this function

add_params(Name, MPModel, SecModel, SecName, SecLevel)

View Source

-spec add_params(Name, MPModel, SecModel, SecName, SecLevel) -> {ok, Key} | {error, Reason}
              when
                  Name :: name(),
                  MPModel :: snmp_framework_mib:message_processing_model(),
                  SecModel :: snmp_framework_mib:security_model(),
                  SecName :: snmp_framework_mib:admin_string(),
                  SecLevel :: snmp_framework_mib:security_level(),
                  Key :: term(),
                  Reason :: term().

Adds a target parameter definition to the agent config. Equivalent to one line in the target_params.conf file.

Link to this function

configure(ConfDir)

View Source

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration files read are: target_addr.conf and target_params.conf.

Link to this function

delete_addr(Key)

View Source

-spec delete_addr(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a target address definition from the agent config.

Link to this function

delete_params(Key)

View Source

-spec delete_params(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a target parameter definition from the agent config.

Link to this function

reconfigure(ConfDir)

View Source

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-TARGET-MIB, after this function has been called, is the data from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the , and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration files read are: target_addr.conf and target_params.conf.

Link to this function

set_target_engine_id(TargetAddrName, EngineId)

View Source

-spec set_target_engine_id(TargetAddrName, EngineId) -> boolean()
                        when TargetAddrName :: name(), EngineId :: snmp_framework_mib:engine_id().

Changes the engine id for a target in the snmpTargetAddrTable. If notifications are sent as Inform requests to a target, its engine id must be set.

snmp_user_based_sm_mib

Instrumentation Functions for SNMP-USER-BASED-SM-MIB

The module snmp_user_based_sm_mib implements the instrumentation functions for the SNMP-USER-BASED-SM-MIB, and functions for configuring the database.

Note that authentication has been extended according to RFC 7860 (SNMP-USM-HMAC-SHA2-MIB).

The configuration files are described in the SNMP User's Manual.

Summary

Types

auth_key()

The size/length of the list depends on auth protocol

auth_protocol()

Note

"An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be authenticated, and if so, the type of authentication protocol which is used."

clone_from()

Note

"A pointer to another conceptual row in this usmUserTable. The user in this other conceptual row is called the clone-from user."

key_change()

Note

"Every definition of an object with this syntax must identify a protocol P, a secret key K, and a hash algorithm H that produces output of L octets."

name()

Note

"A human readable string representing the name of the user. This is the (User-based Security) Model dependent security ID."

priv_key()

The size/length of the list depends on priv protocol

priv_protocol()

Note

"An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be protected from disclosure, and if so, the type of privacy protocol which is used."

public()

OCTET STRING (SIZE(0..32))

usm_entry()

Functions

add_user(EngineID, Name, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey)

Adds a USM security data (user) to the agent config. Equivalent to one line in the usm.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_user(Key)

Delete a USM security data (user) from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Types

Link to this type

auth_key()

View Source

-type auth_key() :: snmp:octet_string().

The size/length of the list depends on auth protocol:

               Size any for usmNoAuthProtocol
               Size 16  for usmHMACMD5AuthProtocol
               Size 20  for usmHMACSHAAuthProtocol
               Size 28  for usmHMAC128SHA224AuthProtocol
               Size 32  for usmHMAC192SHA256AuthProtocol
               Size 48  for usmHMAC256SHA384AuthProtocol
	       Size 64  for usmHMAC384SHA512AuthProtocol

Link to this type

auth_protocol()

View Source

-type auth_protocol() ::
    usmNoAuthProtocol | usmHMACMD5AuthProtocol | usmHMACSHAAuthProtocol |
    usmHMAC128SHA224AuthProtocol | usmHMAC192SH256AuthProtocol | usmHMAC256SHA384AuthProtocol |
    usmHMAC384SHA512AuthProtocol.

Note

"An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be authenticated, and if so, the type of authentication protocol which is used."

Note

Some of the entries of this tyype are actually defined by the SNMP-USM-HMAC-SHA2-MIB mib.

AutonomousType

Link to this type

clone_from()

View Source

-type clone_from() :: zeroDotZero | snmp:row_pointer().

Note

"A pointer to another conceptual row in this usmUserTable. The user in this other conceptual row is called the clone-from user."

RowPointer

Link to this type

key_change()

View Source

-type key_change() :: snmp:octet_string().

Note

"Every definition of an object with this syntax must identify a protocol P, a secret key K, and a hash algorithm H that produces output of L octets."

OCTET STRING

Link to this type

name()

View Source

-type name() :: snmp_framework_mib:admin_string().

Note

"A human readable string representing the name of the user. This is the (User-based Security) Model dependent security ID."

SnmpAdminString (SIZE(1..32))

Link to this type

priv_key()

View Source

-type priv_key() :: snmp:octet_string().

The size/length of the list depends on priv protocol:

	       Size any for usmNoPrivProtocol
               Size 16  for usmDESPrivProtocol
               Size 16  for usmAesCfb128Protocol

Link to this type

priv_protocol()

View Source

-type priv_protocol() :: usmNoPrivProtocol | usmDESPrivProtocol | usmAesCfb128Protocol.

Note

"An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be protected from disclosure, and if so, the type of privacy protocol which is used."

Note

Some of the entries of this tyype are actually defined by the SNMP-USM-AES-MIB mib.

AutonomousType

Link to this type

public()

View Source

-type public() :: string().

OCTET STRING (SIZE(0..32))

Link to this type

usm_entry()

View Source

-type usm_entry() ::
    {EngineID :: snmp_framework_mib:engine_id(),
     UserName :: name(),
     SecName :: snmp_framework_mib:admin_string(),
     Clone :: clone_from(),
     AuthP :: auth_protocol(),
     AuthKeyC :: key_change(),
     OwnAuthKeyC :: key_change(),
     PrivP :: priv_protocol(),
     PrivKeyC :: key_change(),
     OwnPrivKeyC :: key_change(),
     Public :: public(),
     AuthKey :: auth_key(),
     PrivKey :: priv_key()}.

Functions

Link to this function

add_user(EngineID, Name, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey)

View Source

-spec add_user(EngineID, Name, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC,
         OwnPrivKeyC, Public, AuthKey, PrivKey) ->
            {ok, Key} | {error, Reason}
            when
                EngineID :: snmp_framework_mib:engine_id(),
                Name :: name(),
                SecName :: snmp_framework_mib:admin_string(),
                Clone :: clone_from(),
                AuthP :: auth_protocol(),
                AuthKeyC :: key_change(),
                OwnAuthKeyC :: key_change(),
                PrivP :: priv_protocol(),
                PrivKeyC :: key_change(),
                OwnPrivKeyC :: key_change(),
                Public :: public(),
                AuthKey :: auth_key(),
                PrivKey :: priv_key(),
                Key :: term(),
                Reason :: term().

Adds a USM security data (user) to the agent config. Equivalent to one line in the usm.conf file.

Link to this function

configure(ConfDir)

View Source

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: usm.conf.

Link to this function

delete_user(Key)

View Source

-spec delete_user(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a USM security data (user) from the agent config.

Link to this function

reconfigure(ConfDir)

View Source

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-USER-BASED-SM-MIB, after this function has been called, is the data from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: usm.conf.

snmp_view_based_acm_mib

Instrumentation Functions for SNMP-VIEW-BASED-ACM-MIB

The module snmp_view_based_acm_mib implements the instrumentation functions for the SNMP-VIEW-BASED-ACM-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Types

access_notify_view_name()

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes access for notifications."

access_read_view_name()

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes read access."

access_write_view_name()

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes write access."

context_match()

	  exact  - exact match of prefix and contextName
          prefix - Only match to the prefix

INTEGER { exact (1), prefix (2) }

context_prefix()

SnmpAdminString (SIZE(0..32))

group_name()

Note

"The name of the group to which this entry (e.g., the combination of securityModel and securityName) belongs."

internal_view_mask()

internal_view_mask_element()

internal_view_type()

mibview()

security_name()

Note

"The securityName for the principal, represented in a Security Model independent format."

view_mask()

The bit mask which, in combination with the corresponding instance of vacmViewTreeFamilySubtree, defines a family of view subtrees.

view_name()

Note

"The human readable name for a family of view subtrees."

view_type()

Does the corresponding instances of subtree and mask define a family of view subtrees which are included in or excluded from the MIB view.

Functions

add_access(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV)

Adds a access definition to the agent config. Equivalent to one vacmAccess-line in the vacm.conf file.

add_sec2group(SecModel, SecName, GroupName)

Adds a security to group definition to the agent config. Equivalent to one vacmSecurityToGroup-line in the vacm.conf file.

add_view_tree_fam(ViewName, SubTree, Status, Mask)

Adds a view tree family definition to the agent config. Equivalent to one vacmViewTreeFamily-line in the vacm.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_access(Key)

Delete a access definition from the agent config.

delete_sec2group(Key)

Delete a security to group definition from the agent config.

delete_view_tree_fam(Key)

Delete a view tree family definition from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Types

Link to this type

access_notify_view_name()

View Source

-type access_notify_view_name() :: snmp_framework_mib:admin_string().

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes access for notifications."

SnmpAdminString (SIZE(0..32))

Link to this type

access_read_view_name()

View Source

-type access_read_view_name() :: snmp_framework_mib:admin_string().

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes read access."

SnmpAdminString (SIZE(0..32))

Link to this type

access_write_view_name()

View Source

-type access_write_view_name() :: snmp_framework_mib:admin_string().

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes write access."

SnmpAdminString (SIZE(0..32))

Link to this type

context_match()

View Source

-type context_match() :: exact | prefix.

	  exact  - exact match of prefix and contextName
          prefix - Only match to the prefix

INTEGER { exact (1), prefix (2) }

Link to this type

context_prefix()

View Source

-type context_prefix() :: snmp_framework_mib:admin_string().

SnmpAdminString (SIZE(0..32))

Link to this type

group_name()

View Source

-type group_name() :: snmp_framework_mib:admin_string().

Note

"The name of the group to which this entry (e.g., the combination of securityModel and securityName) belongs."

SnmpAdminString (SIZE(1..32))

Link to this type

internal_view_mask()

View Source

-type internal_view_mask() :: null | [internal_view_mask_element()].

Link to this type

internal_view_mask_element()

View Source

-type internal_view_mask_element() :: 0 | 1.

Link to this type

internal_view_type()

View Source

-type internal_view_type() :: 1 | 2.

Link to this type

mibview()

View Source

-type mibview() :: [{SubTree :: snmp:oid(), Mask :: internal_view_mask(), Type :: internal_view_type()}].

Link to this type

security_name()

View Source

-type security_name() :: snmp_framework_mib:admin_string().

Note

"The securityName for the principal, represented in a Security Model independent format."

SnmpAdminString (SIZE(1..32))

Link to this type

view_mask()

View Source

-type view_mask() :: [0 | 1].

The bit mask which, in combination with the corresponding instance of vacmViewTreeFamilySubtree, defines a family of view subtrees.

A '1' indicates that an exact match must occur, a '0' indicates 'wild card' (any sub-identifier value matches).

Note

Note that in the "external" format, each bit of each octet is represented by a "bit" in this list. That is, each octet "contains" 8 bits; so at most 8*16 = 128 bits in total.

OCTET STRING (SIZE (0..16))

Link to this type

view_name()

View Source

-type view_name() :: snmp_framework_mib:admin_string().

Note

"The human readable name for a family of view subtrees."

SnmpAdminString (SIZE(1..32))

Link to this type

view_type()

View Source

-type view_type() :: included | excluded.

Does the corresponding instances of subtree and mask define a family of view subtrees which are included in or excluded from the MIB view.

INTEGER { included(1), excluded(2) }

Functions

Link to this function

add_access(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV)

View Source

-spec add_access(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV) ->
              {ok, Key} | {error, Reason}
              when
                  GroupName :: group_name(),
                  Prefix :: context_prefix(),
                  SecModel :: snmp_framework_mib:security_model(),
                  SecLevel :: snmp_framework_mib:security_level(),
                  Match :: context_match(),
                  RV :: access_read_view_name(),
                  WV :: access_write_view_name(),
                  NV :: access_notify_view_name(),
                  Key :: term(),
                  Reason :: term().

Adds a access definition to the agent config. Equivalent to one vacmAccess-line in the vacm.conf file.

Link to this function

add_sec2group(SecModel, SecName, GroupName)

View Source

-spec add_sec2group(SecModel, SecName, GroupName) -> {ok, Key} | {error, Reason}
                 when
                     SecModel :: snmp_framework_mib:security_model(),
                     SecName :: security_name(),
                     GroupName :: group_name(),
                     Key :: term(),
                     Reason :: term().

Adds a security to group definition to the agent config. Equivalent to one vacmSecurityToGroup-line in the vacm.conf file.

Link to this function

add_view_tree_fam(ViewName, SubTree, Status, Mask)

View Source

-spec add_view_tree_fam(ViewName, SubTree, Status, Mask) -> {ok, Key} | {error, Reason}
                     when
                         ViewName :: view_name(),
                         SubTree :: snmp:oid(),
                         Status :: view_type(),
                         Mask :: null | view_mask(),
                         Key :: term(),
                         Reason :: term().

Adds a view tree family definition to the agent config. Equivalent to one vacmViewTreeFamily-line in the vacm.conf file.

Link to this function

configure(ConfDir)

View Source

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: vacm.conf.

Link to this function

delete_access(Key)

View Source

-spec delete_access(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a access definition from the agent config.

Link to this function

delete_sec2group(Key)

View Source

-spec delete_sec2group(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a security to group definition from the agent config.

Link to this function

delete_view_tree_fam(Key)

View Source

-spec delete_view_tree_fam(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a view tree family definition from the agent config.

Link to this function

reconfigure(ConfDir)

View Source

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-VIEW-BASED-ACM-MIB, after this function has been called, is the data from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: vacm.conf.

snmpa

Interface Functions to the SNMP toolkit agent

The module snmpa contains interface functions to the SNMP agent.

Summary

Types

db()

discovery_handler()

Module implementing the snmpa_discovery_handler behaviour.

me()

mib_storage()

mib_storage_module()

mib_storage_opt()

mib_storage_options()

name()

name_db()

nfilter_id()

nfilter_position()

notification_delivery_info()

How shall (notification) delivery info be reported.

pdu_type()

table_name()

transport_kind()

variable_name()

Functions

add_agent_caps(Oid, Descr)

This function can be used to add an AGENT-CAPABILITY statement to the sysORTable in the agent. The table is defined in the SNMPv2-MIB.

backup(BackupDir)

Equivalent to backup/2.

backup(Agent, BackupDir)

Backup persistent/permanent data handled by the agent (such as local-db, mib-data and vacm).

change_log_size(NewSize)

Changes the log size of the Audit Trail Log. The application must be configured to use the audit trail log function. Please refer to disk_log(3) in Kernel Reference Manual for a description of how to change the log size.

convert_config(OldConfig)

This off-line utility function can be used to convert the old snmp application config (pre snmp-4.0) to the new snmp agent config (as of snmp-4.0).

current_address()

Get the address of the request currently being processed by the agent.

current_community()

Get the community of the request currently being processed by the agent.

current_context()

Get the context of the request currently being processed by the agent.

current_request_id()

Get the request-id of the request currently being processed by the agent.

del_agent_caps(Index)

This function can be used to delete an AGENT-CAPABILITY statement to the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

disable_mibs_cache()

Equivalent to disable_mibs_cache/1.

disable_mibs_cache(Agent)

Disable the mib server cache.

disable_mibs_cache_autogc()

Equivalent to disable_mibs_cache_autogc/1.

disable_mibs_cache_autogc(Agent)

Disable automatic gc of the mib server cache.

discovery(TargetName, Notification)

Equivalent to discovery/6.

discovery/3

Equivalent to discovery/6.

discovery/4

Equivalent to discovery/6.

discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler)

Equivalent to discovery/6.

discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler, ExtraInfo)

Initiate the discovery process with the manager identified by TargetName using the notification Notification.

enable_mibs_cache()

Equivalent to enable_mibs_cache/1.

enable_mibs_cache(Agent)

Enable the mib server cache.

enable_mibs_cache_autogc()

Equivalent to enable_mibs_cache_autogc/1.

enable_mibs_cache_autogc(Agent)

Enable automatic gc of the mib server cache.

enum_to_int(Name, Enum)

Equivalent to enum_to_int/3.

enum_to_int(Db, Name, Enum)

Converts the symbolic value Enum to the corresponding integer of the enumerated object or type Name in a MIB. The MIB must be loaded.

gc_mibs_cache()

Equivalent to gc_mibs_cache/3.

gc_mibs_cache/1

Equivalent to gc_mibs_cache/3.

gc_mibs_cache/2

Equivalent to gc_mibs_cache/3.

gc_mibs_cache(Agent, Age, GcLimit)

Perform mib server cache gc.

get(Agent, Vars)

Equivalent to get/3.

get(Agent, Vars, Context)

Performs a GET operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

get_agent_caps()

Returns all AGENT-CAPABILITY statements in the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

get_next(Agent, Vars)

Equivalent to get_next/3.

get_next(Agent, Vars, Context)

Performs a GET-NEXT operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

info()

Equivalent to info/1.

info(Agent)

Returns a list (a dictionary) containing information about the agent. Information includes loaded MIBs, registered sub-agents, some information about the memory allocation.

int_to_enum(Name, Int)

Equivalent to int_to_enum/3.

int_to_enum(Db, Name, Int)

Converts the integer Int to the corresponding symbolic value of the enumerated object or type Name in a MIB. The MIB must be loaded.

invalidate_mibs_cache()

Equivalent to invalidate_mibs_cache/1.

invalidate_mibs_cache(Agent)

Invalidate the mib server cache.

load_mib(Mib)

Equivalent to load_mib/2.

load_mib(Agent, Mib)

Load a single Mib into an agent. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example

load_mibs(Mibs)

Equivalent to load_mibs/3.

load_mibs/2

Equivalent to load_mibs/3.

load_mibs(Agent, Mibs, Force)

Load Mibs into an agent. If the agent cannot load all MIBs (the default value of the Force argument is false), it will indicate where loading was aborted. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

log_to_io(LogDir)

Equivalent to log_to_io/7.

log_to_io/2

Equivalent to log_to_io/7.

log_to_io/3

Equivalent to log_to_io/7.

log_to_io/4

Equivalent to log_to_io/7.

log_to_io/5

Equivalent to log_to_io/7.

log_to_io/6

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable format and prints it on stdio. LogName defaults to "snmpa_log". LogFile defaults to "snmpa.log".

log_to_txt(LogDir)

Equivalent to log_to_txt/8.

log_to_txt/2

Equivalent to log_to_txt/8.

log_to_txt/3

Equivalent to log_to_txt/8.

log_to_txt/4

Equivalent to log_to_txt/8.

log_to_txt/5

Equivalent to log_to_txt/8.

log_to_txt/6

Equivalent to log_to_txt/8.

log_to_txt/7

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable text file. OutFile defaults to "./snmpa_log.txt". LogName defaults to "snmpa_log". LogFile defaults to "snmpa.log".

me_of(Oid)

Equivalent to me_of/2.

me_of(Agent, Oid)

Finds the mib entry corresponding to the Oid.

mib_of(Oid)

Equivalent to mib_of/2.

mib_of(Agent, Oid)

Finds the mib corresponding to the Oid.

name_to_oid(Name)

Equivalent to name_to_oid/2.

name_to_oid(Db, Name)

Looks up the OBJECT IDENTIFIER of a MIB object, given the symbolic name. Note, the OBJECT IDENTIFIER is given for the object, not for an instance.

oid_to_name(Oid)

Equivalent to oid_to_name/2.

oid_to_name(Db, Oid)

Looks up the symbolic name of a MIB object, given OBJECT IDENTIFIER.

print_mib_info()

Prints the content of all the (snmp) tables and variables for all mibs handled by the snmp agent.

print_mib_tables()

Prints the content of all the (snmp) tables for all mibs handled by the snmp agent.

print_mib_variables()

Prints the content of all the (snmp) variables for all mibs handled by the snmp agent.

register_notification_filter(Id, Mod, Data)

Equivalent to register_notification_filter/5.

register_notification_filter/4

Equivalent to register_notification_filter/5.

register_notification_filter(Agent, Id, Mod, Data, Where)

Registers a notification filter.

register_subagent(Agent, SubTree, SubAgent)

Registers a sub-agent under a sub-tree of another agent.

restart_set_worker()

Equivalent to restart_set_worker/1.

restart_set_worker(Agent)

Restart the set worker process of a multi-threaded agent.

restart_worker()

Equivalent to restart_worker/1.

restart_worker(Agent)

Restart the worker process of a multi-threaded agent.

send_notification2(Agent, Notification, SendOpts)

Send the notification Notification to the management targets defined for notify-name (name) in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context.

send_notification(Agent, Notification, Receiver)

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, Varbinds)

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds)

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds, LocalEngineID)

Sends the notification Notification to the management targets defined for NotifyName in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context.

set_log_type(NewType)

Equivalent to set_log_type/2.

set_log_type(Agent, NewType)

Changes the run-time Audit Trail log type.

set_request_limit(NewLimit)

Equivalent to set_request_limit/2.

set_request_limit(Agent, NewLimit)

Changes the request limit.

unload_mib(Mib)

Equivalent to unload_mib/2.

unload_mib(Agent, Mib)

Unload a single Mib from an agent.

unload_mibs(Mibs)

Equivalent to unload_mibs/3.

unload_mibs/2

Equivalent to unload_mibs/3.

unload_mibs(Agent, Mibs, Force)

Unload Mibs from an agent. If it cannot unload all MIBs (the default value of the Force argument is false), it will indicate where unloading was aborted.

unregister_notification_filter(Id)

Equivalent to unregister_notification_filter/2.

unregister_notification_filter(Agent, Id)

Unregister a notification filter.

unregister_subagent(Agent, SubAgentOidOrPid)

Unregister a sub-agent. If the second argument is a pid, then that sub-agent will be unregistered from all trees in Agent.

update_mibs_cache_age(Age)

Equivalent to update_mibs_cache_age/2.

update_mibs_cache_age(Agent, Age)

Change the mib server cache age property.

update_mibs_cache_gclimit(GcLimit)

Equivalent to update_mibs_cache_gclimit/2.

update_mibs_cache_gclimit(Agent, GcLimit)

Change the mib server cache gclimit property.

verbosity/2

Sets 'verbosity' for the indicated process(s)

whereis_mib(MibName)

Equivalent to whereis_mib/2.

whereis_mib(Agent, MibName)

Get the full path to the (compiled) mib-file.

which_aliasnames()

Retrieve all alias-names known to the agent.

which_mibs()

Equivalent to which_mibs/1.

which_mibs(Agent)

Retrieve the list of all the mibs loaded into this agent. Default is the master agent.

which_mibs_cache_size()

Equivalent to which_mibs_cache_size/1.

which_mibs_cache_size(Agent)

Retrieve the size of the mib server cache.

which_notification_filter()

Equivalent to which_notification_filter/1.

which_notification_filter(Agent)

List all notification filters in an agent.

which_notifications()

Retrieve all notifications (and traps) known to the agent.

which_tables()

Retrieve all tables known to the agent.

which_transports()

Retrieve all configured transports.

which_variables()

Retrieve all variables known to the agent.

Types

Link to this type

db()

View Source

-type db() :: volatile | persistent | mnesia.

Link to this type

discovery_handler()

View Source

-type discovery_handler() :: module().

Module implementing the snmpa_discovery_handler behaviour.

Link to this type

me()

View Source

-type me() :: snmp:me().

Link to this type

mib_storage()

View Source

-type mib_storage() :: [mib_storage_opt()].

Link to this type

mib_storage_module()

View Source

-type mib_storage_module() :: atom().

Link to this type

mib_storage_opt()

View Source

-type mib_storage_opt() :: {module, mib_storage_module()} | {options, mib_storage_options()}.

Link to this type

mib_storage_options()

View Source

-type mib_storage_options() :: list().

Link to this type

name()

View Source

-type name() :: table_name() | variable_name().

Link to this type

name_db()

View Source

-type name_db() :: {name(), db()}.

Link to this type

nfilter_id()

View Source

-type nfilter_id() :: term().

Link to this type

nfilter_position()

View Source

-type nfilter_position() :: first | last | {insert_before, nfilter_id()} | {insert_after, nfilter_id()}.

Link to this type

notification_delivery_info()

View Source

-type notification_delivery_info() ::
    snmpa_notification_delivery_info_receiver:notification_delivery_info().

How shall (notification) delivery info be reported.

Link to this type

pdu_type()

View Source

-type pdu_type() :: snmp:pdu_type().

Link to this type

table_name()

View Source

-type table_name() :: atom().

Link to this type

transport_kind()

View Source

-type transport_kind() :: req_responder | trap_sender.

Link to this type

variable_name()

View Source

-type variable_name() :: atom().

Functions

Link to this function

add_agent_caps(Oid, Descr)

View Source

-spec add_agent_caps(Oid, Descr) -> Index when Oid :: snmp:oid(), Descr :: string(), Index :: integer().

This function can be used to add an AGENT-CAPABILITY statement to the sysORTable in the agent. The table is defined in the SNMPv2-MIB.

Link to this function

backup(BackupDir)

View Source

-spec backup(BackupDir) -> ok | {error, Reason}
          when BackupDir :: string(), Reason :: backup_in_progress | term().

Equivalent to backup/2.

Link to this function

backup(Agent, BackupDir)

View Source

-spec backup(Agent, BackupDir) -> ok | {error, Reason}
          when
              Agent :: pid() | AgentName,
              AgentName :: atom(),
              BackupDir :: string(),
              Reason :: backup_in_progress | term().

Backup persistent/permanent data handled by the agent (such as local-db, mib-data and vacm).

Data stored by mnesia is not handled.

BackupDir cannot be identical to DbDir.

Simultaneous backup calls are not allowed. That is, two different processes cannot simultaneously successfully call this function. One of them will be first, and succeed. The second will fail with the error reason backup_in_progress.

Link to this function

change_log_size(NewSize)

View Source

-spec change_log_size(NewSize) -> ok | {error, Reason} when NewSize :: snmp:log_size(), Reason :: term().

Changes the log size of the Audit Trail Log. The application must be configured to use the audit trail log function. Please refer to disk_log(3) in Kernel Reference Manual for a description of how to change the log size.

The change is permanent, as long as the log is not deleted. That means, the log size is remembered across reboots.

Link to this function

convert_config(OldConfig)

View Source

-spec convert_config(OldConfig) -> NewConfig when OldConfig :: list(), NewConfig :: list().

This off-line utility function can be used to convert the old snmp application config (pre snmp-4.0) to the new snmp agent config (as of snmp-4.0).

For information about the old config (OldConfig) see the OTP R9C documentation.

For information about the current agent config (AgentConfig), see the Configuring the application chapter of the SNMP user's guide.

Link to this function

current_address()

View Source

-spec current_address() -> {value, Address} | false when Address :: term().

Get the address of the request currently being processed by the agent.

Note that this function is intended to be called by the instrumentation functions and only if it is executed in the context of the agent process (e.g. it does not work if called from a spawned process).

Link to this function

current_community()

View Source

-spec current_community() -> {value, Community} | false when Community :: snmp_community_mib:name().

Get the community of the request currently being processed by the agent.

Note that this function is intended to be called by the instrumentation functions and only if it is executed in the context of the agent process (e.g. it does not work if called from a spawned process).

Link to this function

current_context()

View Source

-spec current_context() -> {value, Context} | false when Context :: snmp_community_mib:context_name().

Get the context of the request currently being processed by the agent.

Note that this function is intended to be called by the instrumentation functions and only if it is executed in the context of the agent process (e.g. it does not work if called from a spawned process).

Link to this function

current_request_id()

View Source

-spec current_request_id() -> {value, RequestId} | false when RequestId :: integer().

Get the request-id of the request currently being processed by the agent.

Note that this function is intended to be called by the instrumentation functions and only if it is executed in the context of the agent process (e.g. it does not work if called from a spawned process).

Link to this function

del_agent_caps(Index)

View Source

-spec del_agent_caps(Index) -> snmp:void() when Index :: integer().

This function can be used to delete an AGENT-CAPABILITY statement to the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

Link to this function

disable_mibs_cache()

View Source

-spec disable_mibs_cache() -> snmp:void().

Equivalent to disable_mibs_cache/1.

Link to this function

disable_mibs_cache(Agent)

View Source

-spec disable_mibs_cache(Agent) -> snmp:void() when Agent :: pid() | AgentName, AgentName :: atom().

Disable the mib server cache.

Link to this function

disable_mibs_cache_autogc()

View Source

-spec disable_mibs_cache_autogc() -> snmp:void().

Equivalent to disable_mibs_cache_autogc/1.

Link to this function

disable_mibs_cache_autogc(Agent)

View Source

-spec disable_mibs_cache_autogc(Agent) -> snmp:void()
                             when Agent :: pid() | AgentName, AgentName :: atom().

Disable automatic gc of the mib server cache.

Link to this function

discovery(TargetName, Notification)

View Source

-spec discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error, Reason}
             when
                 TargetName :: string(),
                 Notification :: atom(),
                 ManagerEngineID :: snmp_framework_mib:engine_id(),
                 Reason :: term().

Equivalent to discovery/6.

Link to this function

discovery/3

View Source

-spec discovery(TargetName, Notification, Varbinds) -> {ok, ManagerEngineID} | {error, Reason}
             when
                 TargetName :: string(),
                 Notification :: atom(),
                 Varbinds :: [Varbind],
                 Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                 Variable :: atom(),
                 Column :: atom(),
                 RowIndex :: snmp:row_index(),
                 OID :: snmp:oid(),
                 Value :: term(),
                 ManagerEngineID :: snmp_framework_mib:engine_id(),
                 Reason :: term();
         (TargetName, Notification, ContextName) -> {ok, ManagerEngineID} | {error, Reason}
             when
                 TargetName :: string(),
                 Notification :: atom(),
                 ContextName :: snmp_community_mib:context_name(),
                 ManagerEngineID :: snmp_framework_mib:engine_id(),
                 Reason :: term().

Equivalent to discovery/6.

Link to this function

discovery/4

View Source

-spec discovery(TargetName, Notification, ContextName, Varbinds) ->
             {ok, ManagerEngineID} | {error, Reason}
             when
                 TargetName :: string(),
                 Notification :: atom(),
                 ContextName :: snmp_community_mib:context_name(),
                 Varbinds :: [Varbind],
                 Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                 Variable :: atom(),
                 Column :: atom(),
                 RowIndex :: snmp:row_index(),
                 OID :: snmp:oid(),
                 Value :: term(),
                 ManagerEngineID :: snmp_framework_mib:engine_id(),
                 Reason :: term();
         (TargetName, Notification, Varbinds, DiscoHandler) ->
             {ok, ManagerEngineID} | {error, Reason}
             when
                 TargetName :: string(),
                 Notification :: atom(),
                 Varbinds :: [Varbind],
                 Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                 Variable :: atom(),
                 Column :: atom(),
                 RowIndex :: snmp:row_index(),
                 OID :: snmp:oid(),
                 Value :: term(),
                 DiscoHandler :: discovery_handler(),
                 ManagerEngineID :: snmp_framework_mib:engine_id(),
                 Reason :: term().

Equivalent to discovery/6.

Link to this function

discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler)

View Source

-spec discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler) ->
             {ok, ManagerEngineID} | {error, Reason}
             when
                 TargetName :: string(),
                 Notification :: atom(),
                 ContextName :: snmp_community_mib:context_name(),
                 Varbinds :: [Varbind],
                 Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                 Variable :: atom(),
                 Column :: atom(),
                 RowIndex :: snmp:row_index(),
                 OID :: snmp:oid(),
                 Value :: term(),
                 DiscoHandler :: discovery_handler(),
                 ManagerEngineID :: snmp_framework_mib:engine_id(),
                 Reason :: term().

Equivalent to discovery/6.

Link to this function

discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler, ExtraInfo)

View Source

-spec discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler, ExtraInfo) ->
             {ok, ManagerEngineID} | {error, Reason}
             when
                 TargetName :: string(),
                 Notification :: atom(),
                 ContextName :: snmp_community_mib:context_name(),
                 Varbinds :: [Varbind],
                 Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                 Variable :: atom(),
                 Column :: atom(),
                 RowIndex :: snmp:row_index(),
                 OID :: snmp:oid(),
                 Value :: term(),
                 DiscoHandler :: discovery_handler(),
                 ExtraInfo :: term(),
                 ManagerEngineID :: snmp_framework_mib:engine_id(),
                 Reason :: term().

Initiate the discovery process with the manager identified by TargetName using the notification Notification.

This function is synchronous, which means that it will return when the discovery process has been completed or failed.

The DiscoHandler module is used during the discovery process. See discovery handler for more info.

The ExtraInfo argument is passed on to the callback functions of the DiscoHandler.

Note

If we are not at security-level noAuthNoPriv, this could be complicated, since the agent will then continue with stage 2, before which the usm-related updates must be done.

Note

The default discovery handler will require additional actions by the caller and the discovery will not work if the security-level is higher then noAuthNoPriv.

Link to this function

enable_mibs_cache()

View Source

-spec enable_mibs_cache() -> snmp:void().

Equivalent to enable_mibs_cache/1.

Link to this function

enable_mibs_cache(Agent)

View Source

-spec enable_mibs_cache(Agent) -> snmp:void() when Agent :: pid() | AgentName, AgentName :: atom().

Enable the mib server cache.

Link to this function

enable_mibs_cache_autogc()

View Source

-spec enable_mibs_cache_autogc() -> snmp:void().

Equivalent to enable_mibs_cache_autogc/1.

Link to this function

enable_mibs_cache_autogc(Agent)

View Source

-spec enable_mibs_cache_autogc(Agent) -> snmp:void()
                            when Agent :: pid() | AgentName, AgentName :: atom().

Enable automatic gc of the mib server cache.

Link to this function

enum_to_int(Name, Enum)

View Source

-spec enum_to_int(Name, Enum) -> {value, Int} | false
               when Name :: atom(), Enum :: atom(), Int :: integer().

Equivalent to enum_to_int/3.

Link to this function

enum_to_int(Db, Name, Enum)

View Source

-spec enum_to_int(Db, Name, Enum) -> {value, Int} | false
               when Db :: term(), Name :: atom(), Enum :: atom(), Int :: integer().

Converts the symbolic value Enum to the corresponding integer of the enumerated object or type Name in a MIB. The MIB must be loaded.

false is returned if the object or type is not defined in any loaded MIB, or if it does not define the symbolic value as enumerated.

Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0).

Link to this function

gc_mibs_cache()

View Source

-spec gc_mibs_cache() -> {ok, NumElementsGCed} | {error, Reason}
                 when NumElementsGCed :: non_neg_integer(), Reason :: term().

Equivalent to gc_mibs_cache/3.

Link to this function

gc_mibs_cache/1

View Source

-spec gc_mibs_cache(Agent) -> {ok, NumElementsGCed} | {error, Reason}
                 when
                     Agent :: pid() | AgentName,
                     AgentName :: atom(),
                     NumElementsGCed :: non_neg_integer(),
                     Reason :: term();
             (Age) -> {ok, NumElementsGCed} | {error, Reason}
                 when Age :: pos_integer(), NumElementsGCed :: non_neg_integer(), Reason :: term().

Equivalent to gc_mibs_cache/3.

Link to this function

gc_mibs_cache/2

View Source

-spec gc_mibs_cache(Agent, Age) -> {ok, NumElementsGCed} | {error, Reason}
                 when
                     Agent :: pid() | AgentName,
                     AgentName :: atom(),
                     Age :: pos_integer(),
                     NumElementsGCed :: non_neg_integer(),
                     Reason :: term();
             (Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}
                 when
                     Age :: pos_integer(),
                     GcLimit :: pos_integer() | infinity,
                     NumElementsGCed :: non_neg_integer(),
                     Reason :: term().

Equivalent to gc_mibs_cache/3.

Link to this function

gc_mibs_cache(Agent, Age, GcLimit)

View Source

-spec gc_mibs_cache(Agent, Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}
                 when
                     Agent :: pid() | AgentName,
                     AgentName :: atom(),
                     Age :: pos_integer(),
                     GcLimit :: pos_integer() | infinity,
                     NumElementsGCed :: non_neg_integer(),
                     Reason :: term().

Perform mib server cache gc.

Manually performs a mib server cache gc. This can be done regardless of the value of the autogc option. The NumElementsGCed value indicates how many elements where actually removed from the cache.

Link to this function

get(Agent, Vars)

View Source

-spec get(Agent, Vars) -> Values | {error, Reason}
       when
           Agent :: pid() | AgentName,
           AgentName :: atom(),
           Vars :: [snmp:oid()],
           Values :: [term()],
           Reason :: term().

Equivalent to get/3.

Link to this function

get(Agent, Vars, Context)

View Source

-spec get(Agent, Vars, Context) -> Values | {error, Reason}
       when
           Agent :: pid() | AgentName,
           AgentName :: atom(),
           Vars :: [snmp:oid()],
           Context :: snmp_community_mib:context_name(),
           Values :: [term()],
           Reason :: term().

Performs a GET operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

Note that the request specific parameters (such as current_request_id/0) are not accessible for the instrumentation functions if this function is used.

Link to this function

get_agent_caps()

View Source

-spec get_agent_caps() -> Caps
                  when
                      Caps :: [[Cap]],
                      Cap :: SysORIndex | SysORID | SysORDescr | SysORUpTime,
                      SysORIndex :: integer(),
                      SysORID :: snmp:oid(),
                      SysORDescr :: string(),
                      SysORUpTime :: integer().

Returns all AGENT-CAPABILITY statements in the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

Note that the Erlang type language do not permit us to properly describe what this function returns. The exact return is:

[[SysORIndex, SysORID, SysORDescr, SysORUpTime]]

Link to this function

get_next(Agent, Vars)

View Source

-spec get_next(Agent, Vars) -> Values | {error, Reason}
            when
                Agent :: pid() | AgentName,
                AgentName :: atom(),
                Vars :: [snmp:oid()],
                Values :: [{snmp:oid(), term()}],
                Reason :: term().

Equivalent to get_next/3.

Link to this function

get_next(Agent, Vars, Context)

View Source

-spec get_next(Agent, Vars, Context) -> Values | {error, Reason}
            when
                Agent :: pid() | AgentName,
                AgentName :: atom(),
                Vars :: [snmp:oid()],
                Context :: snmp_community_mib:context_name(),
                Values :: [{snmp:oid(), term()}],
                Reason :: {atom(), snmp:oid()}.

Performs a GET-NEXT operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

Note that the request specific parameters (such as snmpa:current_request_id/0 are not accessible for the instrumentation functions if this function is used.

Link to this function

info()

View Source

-spec info() -> Info when Info :: [{Key, Value}], Key :: term(), Value :: term().

Equivalent to info/1.

Link to this function

info(Agent)

View Source

-spec info(Agent) -> Info
        when
            Agent :: pid() | AgentName,
            AgentName :: atom(),
            Info :: [{Key, Value}],
            Key :: term(),
            Value :: term().

Returns a list (a dictionary) containing information about the agent. Information includes loaded MIBs, registered sub-agents, some information about the memory allocation.

Link to this function

int_to_enum(Name, Int)

View Source

-spec int_to_enum(Name, Int) -> {value, Enum} | false
               when Name :: atom(), Int :: integer(), Enum :: atom().

Equivalent to int_to_enum/3.

Link to this function

int_to_enum(Db, Name, Int)

View Source

-spec int_to_enum(Db, Name, Int) -> {value, Enum} | false
               when Db :: term(), Name :: atom(), Int :: integer(), Enum :: atom().

Converts the integer Int to the corresponding symbolic value of the enumerated object or type Name in a MIB. The MIB must be loaded.

false is returned if the object or type is not defined in any loaded MIB, or if it does not define the symbolic value as enumerated.

Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0).

Link to this function

invalidate_mibs_cache()

View Source

-spec invalidate_mibs_cache() -> snmp:void().

Equivalent to invalidate_mibs_cache/1.

Link to this function

invalidate_mibs_cache(Agent)

View Source

-spec invalidate_mibs_cache(Agent) -> snmp:void() when Agent :: pid() | AgentName, AgentName :: atom().

Invalidate the mib server cache.

The entire contents of the cache will be deleted.

Link to this function

load_mib(Mib)

View Source (since OTP R16B02)

-spec load_mib(Mib) -> ok | {error, Reason} when Mib :: string(), Reason :: already_loaded | term().

Equivalent to load_mib/2.

Link to this function

load_mib(Agent, Mib)

View Source (since OTP R16B02)

-spec load_mib(Agent, Mib) -> ok | {error, Reason}
            when
                Agent :: pid() | AgentName,
                AgentName :: atom(),
                Mib :: string(),
                Reason :: already_loaded | term().

Load a single Mib into an agent. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example:

          Dir = code:priv_dir(my_app) ++ "/mibs/",
          snmpa:load_mib(snmp_master_agent, Dir ++ "MY-MIB").

Link to this function

load_mibs(Mibs)

View Source (since OTP R16B02)

-spec load_mibs(Mibs) -> ok | {error, Reason}
             when
                 Mibs :: [MibName],
                 MibName :: string(),
                 Reason :: {'load aborted at', MibName, InternalReason},
                 InternalReason :: already_loaded | term().

Equivalent to load_mibs/3.

Link to this function

load_mibs/2

View Source (since OTP R16B02)

-spec load_mibs(Agent, Mibs) -> ok | {error, Reason}
             when
                 Agent :: pid() | AgentName,
                 AgentName :: atom(),
                 Mibs :: [MibName],
                 MibName :: string(),
                 Reason :: {'load aborted at', MibName, InternalReason},
                 InternalReason :: already_loaded | term();
         (Mibs, Force) -> ok | {error, Reason}
             when
                 Mibs :: [MibName],
                 MibName :: string(),
                 Force :: boolean(),
                 Reason :: {'load aborted at', MibName, InternalReason},
                 InternalReason :: already_loaded | term().

Equivalent to load_mibs/3.

Link to this function

load_mibs(Agent, Mibs, Force)

View Source (since OTP R16B02)

-spec load_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
             when
                 Agent :: pid() | AgentName,
                 AgentName :: atom(),
                 Mibs :: [MibName],
                 MibName :: string(),
                 Force :: boolean(),
                 Reason :: {'load aborted at', MibName, InternalReason},
                 InternalReason :: already_loaded | term().

Load Mibs into an agent. If the agent cannot load all MIBs (the default value of the Force argument is false), it will indicate where loading was aborted. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

          Dir = code:priv_dir(my_app) ++ "/mibs/",
          snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).

If Force = true then the agent will continue attempting to load each mib even after failing to load a previous mib. Use with care.

Link to this function

log_to_io(LogDir)

View Source (since OTP R15B01)

-spec log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/2

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/3

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/4

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/5

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName, LogFile, Start) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Start :: null | snmp:log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/6

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Start :: null | snmp:log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Start :: null | snmp:log_time(),
                 Stop :: null | snmp:log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: string(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Start :: null | snmp:log_time(),
                 Stop :: null | snmp:log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Converts an Audit Trail Log to a readable format and prints it on stdio. LogName defaults to "snmpa_log". LogFile defaults to "snmpa.log".

The Block option indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

See snmp:log_to_io for more info.

Link to this function

log_to_txt(LogDir)

View Source (since OTP R15B01, OTP R16B03)

-spec log_to_txt(LogDir) -> snmp:void() when LogDir :: snmp:dir().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/2

View Source (since OTP R15B01, OTP R16B03)

-spec log_to_txt(LogDir, Block) -> snmp:void() when LogDir :: snmp:dir(), Block :: boolean();
          (LogDir, Mibs) -> snmp:void() when LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()].

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/3

View Source (since OTP R15B01, OTP R16B03)

-spec log_to_txt(LogDir, Mibs, Block) -> snmp:void()
              when LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()], Block :: boolean();
          (LogDir, Mibs, OutFile) -> snmp:void()
              when LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()], OutFile :: file:filename().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/4

View Source (since OTP R15B01, OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, Block) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  Block :: boolean();
          (LogDir, Mibs, OutFile, LogName) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  LogName :: string().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/5

View Source (since OTP R15B01, OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, Block) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  LogName :: string(),
                  Block :: boolean();
          (LogDir, Mibs, OutFile, LogName, LogFile) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  LogName :: string(),
                  LogFile :: string().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/6

View Source (since OTP R15B01, OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  LogName :: string(),
                  LogFile :: string(),
                  Block :: boolean();
          (LogDir, Mibs, OutFile, LogName, LogFile, Start) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  LogName :: string(),
                  LogFile :: string(),
                  Start :: null | snmp:log_time().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/7

View Source (since OTP R15B01, OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  LogName :: string(),
                  LogFile :: string(),
                  Block :: boolean(),
                  Start :: null | snmp:log_time();
          (LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  LogName :: string(),
                  LogFile :: string(),
                  Start :: null | snmp:log_time(),
                  Stop :: null | snmp:log_time().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

View Source (since OTP R15B01, OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) -> snmp:void()
              when
                  LogDir :: snmp:dir(),
                  Mibs :: [snmp:mib_name()],
                  OutFile :: file:filename(),
                  LogName :: string(),
                  LogFile :: string(),
                  Block :: boolean(),
                  Start :: null | snmp:log_time(),
                  Stop :: null | snmp:log_time().

Converts an Audit Trail Log to a readable text file. OutFile defaults to "./snmpa_log.txt". LogName defaults to "snmpa_log". LogFile defaults to "snmpa.log".

The Block option indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

See snmp:log_to_txt for more info.

Link to this function

me_of(Oid)

View Source

-spec me_of(Oid) -> {ok, Me} | {error, Reason} when Oid :: snmp:oid(), Me :: snmp:me(), Reason :: term().

Equivalent to me_of/2.

Link to this function

me_of(Agent, Oid)

View Source

-spec me_of(Agent, Oid) -> {ok, Me} | {error, Reason}
         when
             Agent :: pid() | AgentName,
             AgentName :: atom(),
             Oid :: snmp:oid(),
             Me :: snmp:me(),
             Reason :: term().

Finds the mib entry corresponding to the Oid.

If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be <table>.<entry>.<col>.<any>

Link to this function

mib_of(Oid)

View Source

-spec mib_of(Oid) -> {ok, MibName} | {error, Reason}
          when Oid :: snmp:oid(), MibName :: atom(), Reason :: term().

Equivalent to mib_of/2.

Link to this function

mib_of(Agent, Oid)

View Source

-spec mib_of(Agent, Oid) -> {ok, MibName} | {error, Reason}
          when
              Agent :: pid() | AgentName,
              AgentName :: atom(),
              Oid :: snmp:oid(),
              MibName :: atom(),
              Reason :: term().

Finds the mib corresponding to the Oid.

If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be <table>.<entry>.<col>.<any>.

Link to this function

name_to_oid(Name)

View Source

-spec name_to_oid(Name) -> {value, Oid} | false when Name :: atom(), Oid :: snmp:oid().

Equivalent to name_to_oid/2.

Link to this function

name_to_oid(Db, Name)

View Source

-spec name_to_oid(Db, Name) -> {value, Oid} | false when Db :: term(), Name :: atom(), Oid :: snmp:oid().

Looks up the OBJECT IDENTIFIER of a MIB object, given the symbolic name. Note, the OBJECT IDENTIFIER is given for the object, not for an instance.

false is returned if the object is not defined in any loaded MIB.

Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0).

Link to this function

oid_to_name(Oid)

View Source

-spec oid_to_name(Oid) -> {value, Name} | false when Oid :: snmp:oid(), Name :: atom().

Equivalent to oid_to_name/2.

Link to this function

oid_to_name(Db, Oid)

View Source

-spec oid_to_name(Db, Oid) -> {value, Name} | false when Db :: term(), Oid :: snmp:oid(), Name :: atom().

Looks up the symbolic name of a MIB object, given OBJECT IDENTIFIER.

false is returned if the object is not defined in any loaded MIB.

Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0).

Link to this function

print_mib_info()

View Source (since OTP R14B02)

-spec print_mib_info() -> snmp:void().

Prints the content of all the (snmp) tables and variables for all mibs handled by the snmp agent.

Link to this function

print_mib_tables()

View Source (since OTP R14B02)

-spec print_mib_tables() -> snmp:void().

Prints the content of all the (snmp) tables for all mibs handled by the snmp agent.

Link to this function

print_mib_variables()

View Source (since OTP R14B02)

-spec print_mib_variables() -> snmp:void().

Prints the content of all the (snmp) variables for all mibs handled by the snmp agent.

Link to this function

register_notification_filter(Id, Mod, Data)

View Source

-spec register_notification_filter(Id, Mod, Data) -> ok | {error, Reason}
                                when
                                    Id :: nfilter_id(),
                                    Mod :: module(),
                                    Data :: term(),
                                    Reason :: term().

Equivalent to register_notification_filter/5.

Link to this function

register_notification_filter/4

View Source

-spec register_notification_filter(Agent, Id, Mod, Data) -> ok | {error, Reason}
                                when
                                    Agent :: pid() | AgentName,
                                    AgentName :: atom(),
                                    Id :: nfilter_id(),
                                    Mod :: module(),
                                    Data :: term(),
                                    Reason :: term();
                            (Id, Mod, Data, Where) -> ok | {error, Reason}
                                when
                                    Id :: nfilter_id(),
                                    Mod :: module(),
                                    Data :: term(),
                                    Where :: nfilter_position(),
                                    Reason :: term().

Equivalent to register_notification_filter/5.

Link to this function

register_notification_filter(Agent, Id, Mod, Data, Where)

View Source

-spec register_notification_filter(Agent, Id, Mod, Data, Where) -> ok | {error, Reason}
                                when
                                    Agent :: pid() | AgentName,
                                    AgentName :: atom(),
                                    Id :: nfilter_id(),
                                    Mod :: module(),
                                    Data :: term(),
                                    Where :: nfilter_position(),
                                    Reason :: term().

Registers a notification filter.

Mod is a module implementing the snmpa_notification_filter behaviour.

Data will be passed on to the filter when calling the functions of the behaviour.

Link to this function

register_subagent(Agent, SubTree, SubAgent)

View Source

-spec register_subagent(Agent, SubTree, SubAgent) -> ok | {error, Reason}
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         SubTree :: snmp:oid(),
                         SubAgent :: pid(),
                         Reason :: term().

Registers a sub-agent under a sub-tree of another agent.

It is easy to make mistakes when registering sub-agents and this activity should be done carefully. For example, a strange behaviour would result from the following configuration:

snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1),
snmp_agent:register_subagent(SA1,[1,2,3], SA2).

SA2 will not get requests starting with object identifier [1,2,3] since SA1 does not.

Link to this function

restart_set_worker()

View Source

-spec restart_set_worker() -> snmp:void().

Equivalent to restart_set_worker/1.

Link to this function

restart_set_worker(Agent)

View Source

-spec restart_set_worker(Agent) -> snmp:void() when Agent :: pid | AgentName, AgentName :: atom().

Restart the set worker process of a multi-threaded agent.

This is a utility function, that can be useful when e.g. debugging instrumentation functions.

Link to this function

restart_worker()

View Source

-spec restart_worker() -> snmp:void().

Equivalent to restart_worker/1.

Link to this function

restart_worker(Agent)

View Source

-spec restart_worker(Agent) -> snmp:void() when Agent :: pid | AgentName, AgentName :: atom().

Restart the worker process of a multi-threaded agent.

This is a utility function, that can be useful when e.g. debugging instrumentation functions.

Link to this function

send_notification2(Agent, Notification, SendOpts)

View Source (since OTP R14B03)

-spec send_notification2(Agent, Notification, SendOpts) -> snmp:void()
                      when
                          Agent :: pid() | AgentName,
                          AgentName :: atom(),
                          Notification :: atom(),
                          SendOpts :: [SendOpt],
                          SendOpt ::
                              {receiver, Receiver} |
                              {name, snmp_notification_mib:notify_name()} |
                              {context, snmp_community_mib:context_name()} |
                              {varbinds, [Varbind]} |
                              {local_engine_id, snmp_framework_mib:engine_id()} |
                              {extra, term()},
                          Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                          Tag :: term(),
                          Recv :: pid() | atom() | MFA,
                          MFA :: {Mod, Func, Args},
                          Mod :: module(),
                          Func :: atom(),
                          Args :: list(),
                          Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                          Variable :: atom(),
                          Column :: atom(),
                          RowIndex :: snmp:row_index(),
                          Oid :: snmp:oid(),
                          Value :: term().

Send the notification Notification to the management targets defined for notify-name (name) in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context.

If no name is specified (or if it is ""), the notification is sent to all management targets.

If no context is specified, the default context, "", is used.

The send option receiver specifies where information about delivery of Inform-Requests should be sent. The agent sends Inform-Requests and waits for acknowledgments from the management targets. The receiver can have three values:

no_receiver - No information is delivered.

notification_delivery_info/0 - The information is delivered via a function call according to this data.

{tag(), tag_receiver()} - The information is delivered either via messages or via a function call according to the value of tag_receiver().

Delivery is done differently depending on the value of tag_receiver():

pid() | registered_name() - The info will be delivered in the following messages:

{snmp_targets, tag(), Addresses}

This informs the user which target addresses the notification was sent to.

{snmp_notification, tag(), {got_response, Address}}

This informs the user that this target address acknowledged the notification.

{snmp_notification, tag(), {no_response, Address}}

This informs the user that this target address did not acknowledge the notification.

The notification is sent as an Inform-Request to each target address in Addresses and if there are no targets for which an Inform-Request is sent, Addresses is the empty list [].

The tag_receiver() will first be sent the snmp_targets message, and then for each address in Addresses list, one of the two snmp_notification messages.

{Mod, Func, Args} - The info will be delivered via the function call:

Mod:Func([Msg | Args])

where Msg has the same content and purpose as the messages descrived above.

The 'process oid' "tag" that can be provided with the variable name / oids is intended to be used for oid post processing. The value 'keep', which is the default, leaves the oid as is. The value 'truncate', will cause the oid to be "truncated". That is, any trailing ".0" will be removed.

Note

There is a way to exclude a varbind from the notification. In the normal varbinds list, providing the special value '$ignore-oid' (instead of a normal value) will exclude this varbind from the notification.

A define for this has been added to the snmp_types.hrl include file, NOTIFICATION_IGNORE_VB_VALUE.

Note

The extra info is not normally interpreted by the agent, instead it is passed through to the net-if process. It is up to the implementor of that process to make use of this data.

The version of net-if provided by this application makes no use of this data, with one exception: Any tuple containing the atom snmpa_default_notification_extra_info may be used by the agent and is therefore reserved.

See the net-if incoming messages for sending a trap and notification for more info.

Link to this function

send_notification(Agent, Notification, Receiver)

View Source (since OTP R14B)

-spec send_notification(Agent, Notification, Receiver) -> snmp:void()
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         Notification :: atom(),
                         Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                         Tag :: term(),
                         Recv :: pid() | atom() | MFA,
                         MFA :: {Mod, Func, Args},
                         Mod :: module(),
                         Func :: atom(),
                         Args :: list().

Equivalent to send_notification/7.

Link to this function

send_notification(Agent, Notification, Receiver, Varbinds)

View Source (since OTP R14B)

-spec send_notification(Agent, Notification, Receiver, Varbinds) -> snmp:void()
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         Notification :: atom(),
                         Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                         Tag :: term(),
                         Recv :: pid() | atom() | MFA,
                         MFA :: {Mod, Func, Args},
                         Mod :: module(),
                         Func :: atom(),
                         Args :: list(),
                         Varbinds :: [Varbind],
                         Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                         Variable :: atom(),
                         Column :: atom(),
                         RowIndex :: snmp:row_index(),
                         Oid :: snmp:oid(),
                         Value :: term().

Equivalent to send_notification/7.

Link to this function

send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)

View Source (since OTP R14B)

-spec send_notification(Agent, Notification, Receiver, NotifyName, Varbinds) -> snmp:void()
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         Notification :: atom(),
                         Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                         Tag :: term(),
                         Recv :: pid() | atom() | MFA,
                         MFA :: {Mod, Func, Args},
                         Mod :: module(),
                         Func :: atom(),
                         Args :: list(),
                         NotifyName :: snmp_notification_mib:notify_name(),
                         Varbinds :: [Varbind],
                         Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                         Variable :: atom(),
                         Column :: atom(),
                         RowIndex :: snmp:row_index(),
                         Oid :: snmp:oid(),
                         Value :: term().

Equivalent to send_notification/7.

Link to this function

send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds)

View Source (since OTP R14B)

-spec send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds) -> snmp:void()
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         Notification :: atom(),
                         Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                         Tag :: term(),
                         Recv :: pid() | atom() | MFA,
                         MFA :: {Mod, Func, Args},
                         Mod :: module(),
                         Func :: atom(),
                         Args :: list(),
                         NotifyName :: snmp_notification_mib:notify_name(),
                         ContextName :: snmp_community_mib:context_name(),
                         Varbinds :: [Varbind],
                         Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                         Variable :: atom(),
                         Column :: atom(),
                         RowIndex :: snmp:row_index(),
                         Oid :: snmp:oid(),
                         Value :: term().

Equivalent to send_notification/7.

Link to this function

send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds, LocalEngineID)

View Source (since OTP R14B)

-spec send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds, LocalEngineID) ->
                     snmp:void()
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         Notification :: atom(),
                         Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                         Tag :: term(),
                         Recv :: pid() | atom() | MFA,
                         MFA :: {Mod, Func, Args},
                         Mod :: module(),
                         Func :: atom(),
                         Args :: list(),
                         NotifyName :: snmp_notification_mib:notify_name(),
                         ContextName :: snmp_community_mib:context_name(),
                         Varbinds :: [Varbind],
                         Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                         Variable :: atom(),
                         Column :: atom(),
                         RowIndex :: snmp:row_index(),
                         Oid :: snmp:oid(),
                         Value :: term(),
                         LocalEngineID :: snmp_framework_mib:engine_id().

Sends the notification Notification to the management targets defined for NotifyName in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context.

If no NotifyName is specified (or if it is ""), the notification is sent to all management targets (Addresses below).

If no ContextName is specified, the default "" context is used.

The parameter Receiver specifies where information about delivery of Inform-Requests should be sent. The agent sends Inform-Requests and waits for acknowledgments from the managers. Receiver can have three values:

no_receiver - No information is delivered.

notification_delivery_info/0 - The information is delivered via a function call according to this data.

{Tag, Recv} - The information is delivered either via messages or via a function call according to the value of Recv.

If Receiver has the value {Tag, Recv}, the delivery is done according to Recv:

pid() | atom() - The info will be delivered in the following messages:

{snmp_targets, Tag, Addresses}

This inform the user which target addresses the notification was sent to.

{snmp_notification, Tag, {got_response, Address}}

This informs the user that this target address acknowledged the notification.

{snmp_notification, Tag, {no_response, Address}}

This informs the user that this target address did not acknowledge notification.

The notification is sent as an Inform-Request to each target address in Addresses and if there are no targets for which an Inform-Request is sent, Addresses is the empty list [].

The receiver will first be sent the snmp_targets message, and then for each address in Addresses list, one of the two snmp_notification messages.

{Mod, Func, Args} - The info will be delivered via the function call:

Mod:Func([Msg | Args])

where Msg has the same content and purpose as the messages descrived above.

Address is a management target address and Addresses is a list of management target addresses. They are defined as followes:

        Addresses  = [address()]
        Address    = address()
        address()  = v1_address() | v3_address()
        v1_address() = {TDomain, TAddress}
        v3_address() = {{TDomain, TAddress}, V3MsgData}
        TDomain    = tdoamin()
        TAddress   = taddress()
        tdomain()  = The oid of snmpUDPDomain
                     This is the only supported transport domain.
        taddress() = [A1, A2, A3, A4, P1, P3]
                     The 4 first bytes makes up the IP-address and the last 2,
                     the UDP-port number.
        V3MsgData  = v3_msg_data()
        v3_msg_data() = term()

If Receiver is a notification_delivery_info/0 record, then the information about the notification delivery will be delivered to the receiver via the callback functions defined by the snmpa_notification_delivery_info_receiver behaviour according to the content of the notification_delivery_info/0 record.

The optional argument Varbinds defines values for the objects in the notification. If no value is given for an object, the Agent performs a get-operation to retrieve the value.

Varbinds is a list of Varbind, where each Varbind is one of:

{Variable, Value}, where Variable is the symbolic name of a scalar variable referred to in the notification specification.

{Column, RowIndex, Value}, where Column is the symbolic name of a column variable. RowIndex is a list of indices for the specified element. If this is the case, the OBJECT IDENTIFIER sent in the notification is the RowIndex appended to the OBJECT IDENTIFIER for the table column. This is the OBJECT IDENTIFIER which specifies the element.

{OID, Value}, where OID is the OBJECT IDENTIFIER for an instance of an object, scalar variable, or column variable.

For example, to specify that sysLocation should have the value "upstairs" in the notification, we could use one of:

{sysLocation, "upstairs"} or

{[1,3,6,1,2,1,1,6,0], "upstairs"} or

{?sysLocation_instance, "upstairs"} (provided that the generated .hrl file is included)

If a variable in the notification is a table element, the RowIndex for the element must be given in the Varbinds list. In this case, the OBJECT IDENTIFIER sent in the notification is the OBJECT IDENTIFIER that identifies this element. This OBJECT IDENTIFIER could be used in a get operation later.

This function is asynchronous, and does not return any information. If an error occurs, user_err/2 of the error report module is called and the notification is discarded.

Note

Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

ExtraInfo is not normally used in any way by the agent. It is intended to be passed along to the net-if process, which is a component that a user can implement themself. The users own net-if may then make use of ExtraInfo. The net-if provided with this application does not process ExtraInfo.

There is one exception. Any tuple containing the atom snmpa_default_notification_extra_info will, in this context, be considered belonging to this application, and may be processed by the agent.

Link to this function

set_log_type(NewType)

View Source

-spec set_log_type(NewType) -> {ok, OldType} | {error, Reason}
                when NewType :: snmp:atl_type(), OldType :: snmp:atl_type(), Reason :: term().

Equivalent to set_log_type/2.

Link to this function

set_log_type(Agent, NewType)

View Source

-spec set_log_type(Agent, NewType) -> {ok, OldType} | {error, Reason}
                when
                    Agent :: pid() | AgentName,
                    AgentName :: atom(),
                    NewType :: snmp:atl_type(),
                    OldType :: snmp:atl_type(),
                    Reason :: term().

Changes the run-time Audit Trail log type.

Note that this has no effect on the application configuration as defined by configuration files, so a node restart will revert the config to whatever is in those files.

This function is primarily useful in testing/debugging scenarios.

Link to this function

set_request_limit(NewLimit)

View Source

-spec set_request_limit(NewLimit) -> {ok, OldLimit} | {error, Reason}
                     when
                         NewLimit :: infinity | non_neg_integer(),
                         OldLimit :: infinity | non_neg_integer(),
                         Reason :: term().

Equivalent to set_request_limit/2.

Link to this function

set_request_limit(Agent, NewLimit)

View Source

-spec set_request_limit(Agent, NewLimit) -> {ok, OldLimit} | {error, Reason}
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         NewLimit :: infinity | non_neg_integer(),
                         OldLimit :: infinity | non_neg_integer(),
                         Reason :: term().

Changes the request limit.

Note that this has no effect on the application configuration as defined by configuration files, so a node restart will revert the config to whatever is in those files.

This function is primarily useful in load regulation scenarios.

Link to this function

unload_mib(Mib)

View Source (since OTP R16B02)

-spec unload_mib(Mib) -> ok | {error, Reason} when Mib :: string(), Reason :: not_loaded | term().

Equivalent to unload_mib/2.

Link to this function

unload_mib(Agent, Mib)

View Source (since OTP R16B02)

-spec unload_mib(Agent, Mib) -> ok | {error, Reason}
              when
                  Agent :: pid() | AgentName,
                  AgentName :: atom(),
                  Mib :: string(),
                  Reason :: not_loaded | term().

Unload a single Mib from an agent.

Link to this function

unload_mibs(Mibs)

View Source (since OTP R16B02)

-spec unload_mibs(Mibs) -> ok | {error, Reason}
               when
                   Mibs :: [MibName],
                   MibName :: string(),
                   Reason :: {'unload aborted at', MibName, InternalReason},
                   InternalReason :: not_loaded | term().

Equivalent to unload_mibs/3.

Link to this function

unload_mibs/2

View Source (since OTP R16B02)

-spec unload_mibs(Agent, Mibs) -> ok | {error, Reason}
               when
                   Agent :: pid() | AgentName,
                   AgentName :: atom(),
                   Mibs :: [MibName],
                   MibName :: string(),
                   Reason :: {'unload aborted at', MibName, InternalReason},
                   InternalReason :: not_loaded | term();
           (Mibs, Force) -> ok | {error, Reason}
               when
                   Mibs :: [MibName],
                   MibName :: string(),
                   Force :: boolean(),
                   Reason :: {'unload aborted at', MibName, InternalReason},
                   InternalReason :: not_loaded | term().

Equivalent to unload_mibs/3.

Link to this function

unload_mibs(Agent, Mibs, Force)

View Source (since OTP R16B02)

-spec unload_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
               when
                   Agent :: pid() | AgentName,
                   AgentName :: atom(),
                   Mibs :: [MibName],
                   MibName :: string(),
                   Force :: boolean(),
                   Reason :: {'unload aborted at', MibName, InternalReason},
                   InternalReason :: not_loaded | term().

Unload Mibs from an agent. If it cannot unload all MIBs (the default value of the Force argument is false), it will indicate where unloading was aborted.

If Force = true then the agent will continue attempting to unload each mib even after failing to unload a previous mib. Use with care.

Link to this function

unregister_notification_filter(Id)

View Source

-spec unregister_notification_filter(Id) -> ok | {error, Reason}
                                  when Id :: nfilter_id(), Reason :: term().

Equivalent to unregister_notification_filter/2.

Link to this function

unregister_notification_filter(Agent, Id)

View Source

-spec unregister_notification_filter(Agent, Id) -> ok | {error, Reason}
                                  when
                                      Agent :: pid() | AgentName,
                                      AgentName :: atom(),
                                      Id :: nfilter_id(),
                                      Reason :: term().

Unregister a notification filter.

Link to this function

unregister_subagent(Agent, SubAgentOidOrPid)

View Source

-spec unregister_subagent(Agent, SubAgentOidOrPid) -> ok | {error, Reason}
                       when
                           Agent :: pid() | AgentName,
                           AgentName :: atom(),
                           SubAgentOidOrPid :: snmp:oid() | pid(),
                           Reason :: term().

Unregister a sub-agent. If the second argument is a pid, then that sub-agent will be unregistered from all trees in Agent.

Link to this function

update_mibs_cache_age(Age)

View Source

-spec update_mibs_cache_age(Age) -> ok | {error, Reason} when Age :: pos_integer(), Reason :: term().

Equivalent to update_mibs_cache_age/2.

Link to this function

update_mibs_cache_age(Agent, Age)

View Source

-spec update_mibs_cache_age(Agent, Age) -> ok | {error, Reason}
                         when
                             Agent :: pid() | AgentName,
                             AgentName :: atom(),
                             Age :: pos_integer(),
                             Reason :: term().

Change the mib server cache age property.

Link to this function

update_mibs_cache_gclimit(GcLimit)

View Source

-spec update_mibs_cache_gclimit(GcLimit) -> ok | {error, Reason}
                             when GcLimit :: pos_integer(), Reason :: term().

Equivalent to update_mibs_cache_gclimit/2.

Link to this function

update_mibs_cache_gclimit(Agent, GcLimit)

View Source

-spec update_mibs_cache_gclimit(Agent, GcLimit) -> ok | {error, Reason}
                             when
                                 Agent :: pid() | AgentName,
                                 AgentName :: atom(),
                                 GcLimit :: pos_integer(),
                                 Reason :: term().

Change the mib server cache gclimit property.

Link to this function

verbosity/2

View Source

-spec verbosity(Target, Verbosity) -> snmp:void() when Target :: all, Verbosity :: snmp:verbosity();
         (Target, Verbosity) -> snmp:void() when Target :: net_if, Verbosity :: snmp:verbosity();
         (Target, Verbosity) -> snmp:void()
             when Target :: note_store, Verbosity :: snmp:verbosity();
         (Target, Verbosity) -> snmp:void()
             when Target :: mib_server, Verbosity :: snmp:verbosity();
         (Target, Verbosity) -> snmp:void()
             when Target :: symbolic_store, Verbosity :: snmp:verbosity();
         (Target, Verbosity) -> snmp:void() when Target :: local_db, Verbosity :: snmp:verbosity();
         (Target, Verbosity) -> snmp:void()
             when
                 Target :: master_agent | Agent,
                 Agent :: pid() | AgentName,
                 AgentName :: atom(),
                 Verbosity :: {subagents, snmp:verbosity()};
         (Agent, Verbosity) -> snmp:void()
             when Agent :: pid() | AgentName, AgentName :: atom(), Verbosity :: snmp:verbosity().

Sets 'verbosity' for the indicated process(s):

all - Sets verbosity for all the agent processes; net_if, note_store, mib_server, symbolic_store, local_db and master_agent (and sub-agents).

net_if - Sets verbosity for the net-if process.

note_store - Sets verbosity for the note store process.

mib_server - Sets verbosity for the mib server process.

symbolic_store - Sets verbosity for the symbolic store process.

local_db - Sets verbosity for the local-db process.

master_agent | pid() when Verbosity = {subagents, snmp:verbosity()} - Sets verbosity for all sub-agent(s) controlled by this (master) agent.

master_agent | pid() - Sets verbosity for the agent process.

Link to this function

whereis_mib(MibName)

View Source

-spec whereis_mib(MibName) -> {ok, MibFile} | {error, Reason}
               when MibName :: atom(), MibFile :: string(), Reason :: term().

Equivalent to whereis_mib/2.

Link to this function

whereis_mib(Agent, MibName)

View Source

-spec whereis_mib(Agent, MibName) -> {ok, MibFile} | {error, Reason}
               when
                   Agent :: pid() | AgentName,
                   AgentName :: atom(),
                   MibName :: atom(),
                   MibFile :: string(),
                   Reason :: term().

Get the full path to the (compiled) mib-file.

Link to this function

which_aliasnames()

View Source

-spec which_aliasnames() -> AliasNames when AliasNames :: [AliasName], AliasName :: atom().

Retrieve all alias-names known to the agent.

Link to this function

which_mibs()

View Source

-spec which_mibs() -> Mibs when Mibs :: [{MibName, MibFile}], MibName :: atom(), MibFile :: string().

Equivalent to which_mibs/1.

Link to this function

which_mibs(Agent)

View Source

-spec which_mibs(Agent) -> Mibs
              when
                  Agent :: pid() | AgentName,
                  AgentName :: atom(),
                  Mibs :: [{MibName, MibFile}],
                  MibName :: atom(),
                  MibFile :: string().

Retrieve the list of all the mibs loaded into this agent. Default is the master agent.

Link to this function

which_mibs_cache_size()

View Source (since OTP R14B)

-spec which_mibs_cache_size() -> {ok, Size} | {error, Reason}
                         when Size :: non_neg_integer(), Reason :: term().

Equivalent to which_mibs_cache_size/1.

Link to this function

which_mibs_cache_size(Agent)

View Source (since OTP R14B)

-spec which_mibs_cache_size(Agent) -> {ok, Size} | {error, Reason}
                         when
                             Agent :: pid() | AgentName,
                             AgentName :: atom(),
                             Size :: non_neg_integer(),
                             Reason :: term().

Retrieve the size of the mib server cache.

Link to this function

which_notification_filter()

View Source

-spec which_notification_filter() -> Filters when Filters :: [FilterId], FilterId :: nfilter_id().

Equivalent to which_notification_filter/1.

Link to this function

which_notification_filter(Agent)

View Source

-spec which_notification_filter(Agent) -> Filters
                             when
                                 Agent :: pid() | AgentName,
                                 AgentName :: atom(),
                                 Filters :: [FilterId],
                                 FilterId :: nfilter_id().

List all notification filters in an agent.

Link to this function

which_notifications()

View Source

-spec which_notifications() -> Notifications
                       when
                           Notifications :: [{Name, MibName, Info}],
                           Name :: atom(),
                           MibName :: atom(),
                           Info :: term().

Retrieve all notifications (and traps) known to the agent.

Link to this function

which_tables()

View Source

-spec which_tables() -> Tables when Tables :: [Table], Table :: atom().

Retrieve all tables known to the agent.

Link to this function

which_transports()

View Source (since OTP 23.3)

-spec which_transports() -> Transports
                    when
                        Transports :: [Transport],
                        Transport :: {TDomain, TAddress} | {TDomain, TAddress, Kind},
                        TDomain :: snmp:tdomain(),
                        TAddress :: {IpAddr, IpPort},
                        IpAddr :: inet:ip_address(),
                        IpPort :: inet:port_number(),
                        Kind :: transport_kind().

Retrieve all configured transports.

Link to this function

which_variables()

View Source

-spec which_variables() -> Variables when Variables :: [Variable], Variable :: atom().

Retrieve all variables known to the agent.

snmpa_conf

Utility functions for handling the agent config files.

The module snmpa_conf contains various utility functions to use for manipulating (write/read/append) the config files of the SNMP agent.

DATA TYPES

transportDomain() = transportDomainUdpIpv4 | transportDomainUdpIpv6

transportAddress() =
    transportAddressIPv4() | transportAddressIPv6()

transportAddressWithPort() =
    transportAddressIPv4WithPort() | transportAddressIPv6WithPort()

transportAddressWithoutPort() =
    transportAddressIPv4WithoutPort() | transportAddressIPv6WithoutPort()

transportAddressIPv4() =
    transportAddressIPv4WithPort() | transportAddressIPv4WithoutPort()
transportAddressIPv4WithPort =
    {transportAddressIPv4WithoutPort(), inet:port_number()} |
    [byte() x 4, byte() x 2]
transportAddressIPv4WithoutPort =
    inet:ip4_address() | [byte() x 4]

transportAddressIPv6() =
    transportAddressIPv6WithPort() | transportAddressIPv6WithoutPort()
transportAddressIPv6WithPort =
    {transportAddressIPv6WithoutPort(), inet:port_number()} |
    [word() x 8, inet:port_number()] |
    [word() x 8, byte() x 2] |
    [byte() x 16, byte() x 2]
transportAddressIPv6WithoutPort =
    inet:ip6_address() | [word() x 8] | [byte() x 16]

transportAddressMask() =
    [] | transportAddressWithPort()

byte() = 0..255
word() = 0..65535

For inet:ip4_address(), inet:ip6_address() and inet:port_number(), see also inet:ip_address/0

Summary

Types

agent_entry()

An opaque term that represents an entry in the 'agent' config.

community_entry()

An opaque term that represents an entry in the 'community' (agent) config.

context_entry()

An opaque term that represents an entry in the 'context' (agent) config.

extended_transport_address()

intAgentTransport()

ip_address()

notify_entry()

An opaque term that represents an entry in the 'notify' (agent) config.

port_info()

Port number 0 (zero) cannot be specified directly (it is used internally). Instead the atom 'system' should be used.

range()

Min < Max

ranges()

snmp_ip_address()

standard_entry()

An opaque term that represents an entry in the 'standard' (agent) config.

target_addr_entry()

An opaque term that represents an entry in the 'target address' (agent) config.

target_params_entry()

An opaque term that represents an entry in the 'target parameters' (agent) config.

transport_address()

transport_opts()

transportAddress()

transportAddressIPv4()

transportAddressIPv4WithoutPort()

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

transportAddressIPv4WithPort()

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

transportAddressIPv6()

transportAddressIPv6WithoutPort()

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

transportAddressIPv6WithPort()

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

transportAddressMask()

transportAddressWithoutPort()

transportAddressWithPort()

transportDomain()

usm_entry()

An opaque term that represents an entry in the 'user based sm' (agent) config.

vacm_acc_entry()

An opaque term that represents an (access) entry in the 'vacm access' (agent) config.

vacm_entry()

An basically opaque term that represents an entry in the 'view based acm' (agent) config.

vacm_s2g_entry()

An opaque term that represents an (security to group) entry in the 'vacm security to group' (agent) config.

vacm_vtf_entry()

An opaque term that represents an (tree family) entry in the 'vacm tree family' (agent) config.

word()

Functions

agent_entry(Tag, Val)

Create an entry for the agent config file, agent.conf.

append_agent_config(Dir, Conf)

Append the config to the current agent config file.

append_community_config(Dir, Conf)

Append the community config to the current agent community config file.

append_context_config(Dir, Conf)

Append the context config to the current agent context config file.

append_notify_config(Dir, Conf)

Append the notify config to the current agent notify config file.

append_standard_config(Dir, Conf)

Append the standard config to the current agent standard config file.

append_target_addr_config(Dir, Conf)

Append the target_addr config to the current agent target_addr config file.

append_target_params_config(Dir, Conf)

Append the target_params config to the current agent target_params config file.

append_usm_config(Dir, Conf)

Append the usm config to the current agent usm config file.

append_vacm_config(Dir, Conf)

Append the vacm config to the current agent vacm config file.

community_entry(CommIndex)

Create an entry for the agent community config file, community.conf.

community_entry(CommIndex, CommName, SecName, CtxName, TransportTag)

Create an entry for the agent community config file, community.conf.

context_entry(Ctx)

Create an entry for the agent context config file, context.conf.

notify_entry(Name, Tag, Type)

Create an entry for the agent notify config file, notify.conf.

read_agent_config(Dir)

Read the current agent config file.

read_community_config(Dir)

Read the current agent community config file.

read_context_config(Dir)

Read the current agent context config file.

read_notify_config(Dir)

Read the current agent notify config file.

read_standard_config(Dir)

Read the current agent standard config file.

read_target_addr_config(Dir)

Read the current agent target_addr config file.

read_target_params_config(Dir)

Read the current agent target_params config file.

read_usm_config(Dir)

Read the current agent usm config file.

read_vacm_config(Dir)

Read the current agent vacm config file.

standard_entry(Tag, Val)

Create an entry for the agent standard config file, standard.conf.

target_addr_entry/6

Create an entry for the agent target_addr config file, target_addr.conf.

target_addr_entry/7

Create an entry for the agent target_addr config file, target_addr.conf.

target_addr_entry/8

Create an entry for the agent target_addr config file, target_addr.conf.

target_addr_entry(Name, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize)

Create an entry for the agent target_addr config file, target_addr.conf.

target_params_entry(Name, Vsn)

Create an entry for the agent target_params config file, target_params.conf.

target_params_entry(Name, Vsn, SecName, SecLevel)

Create an entry for the agent target_params config file, target_params.conf.

target_params_entry(Name, MPModel, SecModel, SecName, SecLevel)

Create an entry for the agent target_params config file, target_params.conf.

usm_entry(EngineID)

Create an entry for the agent usm config file, usm.conf.

usm_entry(EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey)

Create an entry for the agent usm config file, usm.conf.

vacm_acc_entry(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV)

Create an (access) entry for the agent vacm config file, vacm.conf.

vacm_s2g_entry(SecModel, SecName, GroupName)

Create an (security to group) entry for the agent vacm config file, vacm.conf.

vacm_vtf_entry(ViewName, ViewSubtree)

Create an (view tree family) entry for the agent vacm config file, vacm.conf.

vacm_vtf_entry(ViewName, ViewSubtree, ViewType, ViewMask)

Create an (view tree family) entry for the agent vacm config file, vacm.conf.

write_agent_config(Dir, Conf)

Equivalent to write_agent_config/3.

write_agent_config(Dir, Hdr, Conf)

Write the agent config to the agent config file.

write_community_config(Dir, Conf)

Equivalent to write_community_config/3.

write_community_config(Dir, Hdr, Conf)

Write the agent community config to the agent community config file.

write_context_config(Dir, Conf)

Equivalent to write_context_config/3.

write_context_config(Dir, Hdr, Conf)

Write the agent context config to the agent context config file.

write_notify_config(Dir, Conf)

Equivalent to write_notify_config/3.

write_notify_config(Dir, Hdr, Conf)

Write the agent notify config to the agent notify config file.

write_standard_config(Dir, Conf)

Equivalent to write_standard_config/3.

write_standard_config(Dir, Hdr, Conf)

Write the agent standard config to the agent standard config file.

write_target_addr_config(Dir, Conf)

Equivalent to write_target_addr_config/3.

write_target_addr_config(Dir, Hdr, Conf)

Write the agent target_addr config to the agent target_addr config file.

write_target_params_config(Dir, Conf)

Equivalent to write_target_params_config/3.

write_target_params_config(Dir, Hdr, Conf)

Write the agent target_params config to the agent target_params config file.

write_usm_config(Dir, Conf)

Equivalent to write_usm_config/3.

write_usm_config(Dir, Hdr, Conf)

Write the agent usm config to the agent usm config file.

write_vacm_config(Dir, Conf)

Equivalent to write_vacm_config/3.

write_vacm_config(Dir, Hdr, Conf)

Write the agent vacm config to the agent vacm config file.

Types

Link to this opaque

agent_entry()

View Source

-opaque agent_entry()

An opaque term that represents an entry in the 'agent' config.

Link to this opaque

community_entry()

View Source

-opaque community_entry()

An opaque term that represents an entry in the 'community' (agent) config.

Link to this opaque

context_entry()

View Source

-opaque context_entry()

An opaque term that represents an entry in the 'context' (agent) config.

Link to this type

extended_transport_address()

View Source

-type extended_transport_address() :: {inet:ip_address(), port_info()}.

Link to this type

intAgentTransport()

View Source

-type intAgentTransport() ::
    {transportDomain(), transport_address()} |
    {transportDomain(), extended_transport_address(), snmpa:transport_kind()} |
    {transportDomain(), extended_transport_address(), transport_opts()} |
    {transportDomain(), extended_transport_address(), snmpa:transport_kind(), transport_opts()}.

Link to this type

ip_address()

View Source (not exported)

-type ip_address() :: inet:ip_address() | snmp_ip_address().

Link to this opaque

notify_entry()

View Source

-opaque notify_entry()

An opaque term that represents an entry in the 'notify' (agent) config.

Link to this type

port_info()

View Source

-type port_info() :: inet:port_number() | system | range() | ranges().

Port number 0 (zero) cannot be specified directly (it is used internally). Instead the atom 'system' should be used.

Link to this type

range()

View Source

-type range() :: {Min :: inet:port_number(), Max :: inet:port_number()}.

Min < Max

Link to this type

ranges()

View Source

-type ranges() :: [inet:port_number() | range()].

Link to this type

snmp_ip_address()

View Source (not exported)

-type snmp_ip_address() :: [non_neg_integer()].

Link to this opaque

standard_entry()

View Source

-opaque standard_entry()

An opaque term that represents an entry in the 'standard' (agent) config.

Link to this opaque

target_addr_entry()

View Source

-opaque target_addr_entry()

An opaque term that represents an entry in the 'target address' (agent) config.

Link to this opaque

target_params_entry()

View Source

-opaque target_params_entry()

An opaque term that represents an entry in the 'target parameters' (agent) config.

Link to this type

transport_address()

View Source

-type transport_address() :: {ip_address(), inet:port_number()} | ip_address().

Link to this type

transport_opts()

View Source (not exported)

-type transport_opts() :: list().

Link to this type

transportAddress()

View Source

-type transportAddress() :: transportAddressIPv4() | transportAddressIPv6().

Link to this type

transportAddressIPv4()

View Source (not exported)

-type transportAddressIPv4() :: transportAddressIPv4WithPort() | transportAddressIPv4WithoutPort().

Link to this type

transportAddressIPv4WithoutPort()

View Source (not exported)

-type transportAddressIPv4WithoutPort() :: inet:ip4_address() | [byte()].

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

The list variant, 4 bytes for address:

[byte() x 4]

Link to this type

transportAddressIPv4WithPort()

View Source (not exported)

-type transportAddressIPv4WithPort() ::
    {transportAddressIPv4WithoutPort(), inet:port_number()} | [byte()].

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

The list variant, 4 bytes for address + 2 bytes for port:

[byte() x 4, byte() x 2]

Link to this type

transportAddressIPv6()

View Source (not exported)

-type transportAddressIPv6() :: transportAddressIPv6WithPort() | transportAddressIPv6WithoutPort().

Link to this type

transportAddressIPv6WithoutPort()

View Source (not exported)

-type transportAddressIPv6WithoutPort() :: inet:ip6_address() | [word()] | [byte()].

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

First list variant, 8 words for address:

[word() x 8]

Second list variant, 16 bytes for address:

[byte() x 16]

Link to this type

transportAddressIPv6WithPort()

View Source (not exported)

-type transportAddressIPv6WithPort() ::
    {transportAddressIPv6WithoutPort(), inet:port_number()} |
    [word() | inet:port_number()] |
    [word() | byte()] |
    [byte()].

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

First list variant, 8 words for address + 1 word for port:

[word() x 8, inet:port_number()]

Second list variant, 8 words for address + 2 bytes for port:

[word() x 8, byte() x 2]

Third list variant, 16 bytes for address + 2 bytes for port:

[byte() x 16, byte() x 2]

Link to this type

transportAddressMask()

View Source

-type transportAddressMask() :: [] | transportAddressWithPort().

Link to this type

transportAddressWithoutPort()

View Source

-type transportAddressWithoutPort() ::
    transportAddressIPv4WithoutPort() | transportAddressIPv6WithoutPort().

Link to this type

transportAddressWithPort()

View Source

-type transportAddressWithPort() :: transportAddressIPv4WithPort() | transportAddressIPv6WithPort().

Link to this type

transportDomain()

View Source

-type transportDomain() :: snmp:tdomain().

Link to this opaque

usm_entry()

View Source

-opaque usm_entry()

An opaque term that represents an entry in the 'user based sm' (agent) config.

Link to this opaque

vacm_acc_entry()

View Source

-opaque vacm_acc_entry()

An opaque term that represents an (access) entry in the 'vacm access' (agent) config.

Link to this type

vacm_entry()

View Source

-type vacm_entry() :: vacm_s2g_entry() | vacm_acc_entry() | vacm_vtf_entry().

An basically opaque term that represents an entry in the 'view based acm' (agent) config.

Link to this opaque

vacm_s2g_entry()

View Source

-opaque vacm_s2g_entry()

An opaque term that represents an (security to group) entry in the 'vacm security to group' (agent) config.

Link to this opaque

vacm_vtf_entry()

View Source

-opaque vacm_vtf_entry()

An opaque term that represents an (tree family) entry in the 'vacm tree family' (agent) config.

Link to this type

word()

View Source (not exported)

-type word() :: 0..65535.

Functions

Link to this function

agent_entry(Tag, Val)

View Source

-spec agent_entry(Tag, Val) -> AgentEntry
               when
                   Tag ::
                       intAgentTransports | intAgentUDPPort | snmpEngineMaxMessageSize |
                       snmpEngineID,
                   Val :: term(),
                   AgentEntry :: agent_entry().

Create an entry for the agent config file, agent.conf.

The type of Val depends on the value of Tag:

intAgentTransports:snmpa_conf:intAgentTransport() <mandatory>

intAgentUDPPort:inet:port_number/0 <optional>

snmpEngineMaxMessageSize: snmp_framework_mib:max_message_size/0 <mandatory>

snmpEngineID:snmp_framework_mib:engine_id/0 <mandatory>

See Agent Information for more info.

Link to this function

append_agent_config(Dir, Conf)

View Source

-spec append_agent_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [agent_entry()].

Append the config to the current agent config file.

Dir is the path to the directory where to store the config file.

See Agent Information for more info.

Link to this function

append_community_config(Dir, Conf)

View Source

-spec append_community_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [community_entry()].

Append the community config to the current agent community config file.

Dir is the path to the directory where to store the config file.

See Community for more info.

Link to this function

append_context_config(Dir, Conf)

View Source

-spec append_context_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [context_entry()].

Append the context config to the current agent context config file.

Dir is the path to the directory where to store the config file.

See Contexts for more info.

Link to this function

append_notify_config(Dir, Conf)

View Source

-spec append_notify_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [notify_entry()].

Append the notify config to the current agent notify config file.

Dir is the path to the directory where to store the config file.

See Notify Definitions for more info.

Link to this function

append_standard_config(Dir, Conf)

View Source

-spec append_standard_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [standard_entry()].

Append the standard config to the current agent standard config file.

Dir is the path to the directory where to store the config file.

See System Information for more info.

Link to this function

append_target_addr_config(Dir, Conf)

View Source

-spec append_target_addr_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [target_addr_entry()].

Append the target_addr config to the current agent target_addr config file.

Dir is the path to the directory where to store the config file.

See Target Address Definitions for more info.

Link to this function

append_target_params_config(Dir, Conf)

View Source

-spec append_target_params_config(Dir, Conf) -> ok
                               when Dir :: snmp:dir(), Conf :: [target_params_entry()].

Append the target_params config to the current agent target_params config file.

Dir is the path to the directory where to store the config file.

See Target Parameters Definitions for more info.

Link to this function

append_usm_config(Dir, Conf)

View Source

-spec append_usm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [usm_entry()].

Append the usm config to the current agent usm config file.

Dir is the path to the directory where to store the config file.

See Security data for USM for more info.

Link to this function

append_vacm_config(Dir, Conf)

View Source

-spec append_vacm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [vacm_entry()].

Append the vacm config to the current agent vacm config file.

Dir is the path to the directory where to store the config file.

See MIB Views for VACM for more info.

Link to this function

community_entry(CommIndex)

View Source

-spec community_entry(CommIndex) -> CommunityEntry
                   when
                       CommIndex :: snmp_framework_mib:admin_string(),
                       CommunityEntry :: community_entry().

Create an entry for the agent community config file, community.conf.

CommunityIndex must be a non-empty string.

This function only accepts values of CommIndex of the following values:

"public" - Translates to the following call:

community_entry(CommunityIndex, CommunityIndex, "initial", "", "").

"all-rights" - Translates to the following call:

community_entry(CommunityIndex, CommunityIndex, CommunityIndex, "", "").

See Community for more info.

Link to this function

community_entry(CommIndex, CommName, SecName, CtxName, TransportTag)

View Source

-spec community_entry(CommIndex, CommName, SecName, CtxName, TransportTag) -> CommunityEntry
                   when
                       CommIndex :: snmp_community_mib:index(),
                       CommName :: snmp_community_mib:name(),
                       SecName :: snmp_community_mib:security_name(),
                       CtxName :: snmp_community_mib:context_name(),
                       TransportTag :: snmp_community_mib:transport_tag(),
                       CommunityEntry :: community_entry().

Create an entry for the agent community config file, community.conf.

CommunityIndex must be a non-empty string.

See Community for more info.

Link to this function

context_entry(Ctx)

View Source

-spec context_entry(Ctx) -> ContextEntry
                 when Ctx :: snmp_community_mib:context_name(), ContextEntry :: context_entry().

Create an entry for the agent context config file, context.conf.

See Contexts for more info.

Link to this function

notify_entry(Name, Tag, Type)

View Source

-spec notify_entry(Name, Tag, Type) -> NotifyEntry
                when
                    Name :: snmp_notification_mib:notify_name(),
                    Tag :: snmp_notification_mib:notify_tag(),
                    Type :: snmp_notification_mib:notify_type(),
                    NotifyEntry :: notify_entry().

Create an entry for the agent notify config file, notify.conf.

Name must be a non-empty string.

See Notify Definitions for more info.

Link to this function

read_agent_config(Dir)

View Source

-spec read_agent_config(Dir) -> {ok, Conf} | {error, Reason}
                     when Dir :: snmp:dir(), Conf :: [agent_entry()], Reason :: term().

Read the current agent config file.

Dir is the path to the directory where to store the config file.

See Agent Information for more info.

Link to this function

read_community_config(Dir)

View Source

-spec read_community_config(Dir) -> {ok, Conf} | {error, Reason}
                         when Dir :: snmp:dir(), Conf :: [community_entry()], Reason :: term().

Read the current agent community config file.

Dir is the path to the directory where to store the config file.

See Communities for more info.

Link to this function

read_context_config(Dir)

View Source

-spec read_context_config(Dir) -> {ok, Conf} | {error, Reason}
                       when Dir :: snmp:dir(), Conf :: [context_entry()], Reason :: term().

Read the current agent context config file.

Dir is the path to the directory where to store the config file.

See Contexts for more info.

Link to this function

read_notify_config(Dir)

View Source

-spec read_notify_config(Dir) -> {ok, Conf} | {error, Reason}
                      when Dir :: snmp:dir(), Conf :: [notify_entry()], Reason :: term().

Read the current agent notify config file.

Dir is the path to the directory where to store the config file.

See Notify Definitions for more info.

Link to this function

read_standard_config(Dir)

View Source

-spec read_standard_config(Dir) -> {ok, Conf} | {error, Reason}
                        when Dir :: snmp:dir(), Conf :: [standard_entry()], Reason :: term().

Read the current agent standard config file.

Dir is the path to the directory where to store the config file.

See System Information for more info.

Link to this function

read_target_addr_config(Dir)

View Source

-spec read_target_addr_config(Dir) -> {ok, Conf} | {error, Reason}
                           when Dir :: snmp:dir(), Conf :: [target_addr_entry()], Reason :: term().

Read the current agent target_addr config file.

Dir is the path to the directory where to store the config file.

See Target Address Definitions for more info.

Link to this function

read_target_params_config(Dir)

View Source

-spec read_target_params_config(Dir) -> {ok, Conf} | {error, Reason}
                             when
                                 Dir :: snmp:dir(),
                                 Conf :: [target_params_entry()],
                                 Reason :: term().

Read the current agent target_params config file.

Dir is the path to the directory where to store the config file.

See Target Parameters Definitions for more info.

Link to this function

read_usm_config(Dir)

View Source

-spec read_usm_config(Dir) -> {ok, Conf} | {error, Reason}
                   when Dir :: snmp:dir(), Conf :: [usm_entry()], Reason :: term().

Read the current agent usm config file.

Dir is the path to the directory where to store the config file.

See Security data for USM for more info.

Link to this function

read_vacm_config(Dir)

View Source

-spec read_vacm_config(Dir) -> {ok, Conf} | {error, Reason}
                    when Dir :: snmp:dir(), Conf :: [vacm_entry()], Reason :: term().

Read the current agent vacm config file.

Dir is the path to the directory where to store the config file.

See MIB Views for VACM for more info.

Link to this function

standard_entry(Tag, Val)

View Source

-spec standard_entry(Tag, Val) -> StandardEntry
                  when
                      Tag ::
                          sysDescr | sysObjectID | sysContact | sysName | sysLocation |
                          sysServices | snmpEnableAuthenTraps,
                      Val :: term(),
                      StandardEntry :: standard_entry().

Create an entry for the agent standard config file, standard.conf.

The type of Val depends on the value of Tag:

sysDescr:string() <mandatory> - DisplayString (SIZE(0..255))

sysObjectID:snmp:oid/0 <mandatory> - OBJECT IDENTIFIER

sysContact:string() <mandatory> - DisplayString (SIZE(0..255))

sysName:string() <mandatory> - DisplayString (SIZE(0..255))

sysLocation:string() <mandatory> - DisplayString (SIZE(0..255))

sysLocation:non_neg_integer() <mandatory> - "A value which indicates the set of services that this entity primarily offers."

INTEGER (0..127)

snmpEnableAuthenTraps:enabled | disabled <mandatory> - INTEGER { enabled(1), disabled(2) }

See System Information for more info.

Link to this function

target_addr_entry/6

View Source (since OTP 17.3)

-spec target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId) -> TargetAddrEntry
                     when
                         Name :: snmp_target_mib:name(),
                         Domain :: transportDomain(),
                         Addr :: transportAddress(),
                         TagList :: snmp_target_mib:tag_list(),
                         ParamsName :: snmp_target_mib:params(),
                         EngineId :: snmp_framework_mib:engine_id(),
                         TargetAddrEntry :: target_addr_entry();
                 (Name, IP, TagList, ParamsName, EngineId, TMask) -> TargetAddrEntry
                     when
                         Name :: snmp_target_mib:name(),
                         IP :: inet:ip_address(),
                         TagList :: snmp_target_mib:tag_list(),
                         ParamsName :: snmp_target_mib:params(),
                         EngineId :: snmp_framework_mib:engine_id(),
                         TMask :: snmp_target_mib:tmask(),
                         TargetAddrEntry :: target_addr_entry().

Create an entry for the agent target_addr config file, target_addr.conf.

Name must be a non-empty string.

target_addr_entry/6 (1) translates to the following call: target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, []).

target_addr_entry/6 (2) translates to the following call (with Domain and Addr built from IP and the default port number): target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask, 2048).

See Target Address Definitions for more info.

Link to this function

target_addr_entry/7

View Source (since OTP 17.3)

-spec target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask) -> TargetAddrEntry
                     when
                         Name :: snmp_target_mib:name(),
                         Domain :: transportDomain(),
                         Addr :: transportAddress(),
                         TagList :: snmp_target_mib:tag_list(),
                         ParamsName :: snmp_target_mib:params(),
                         EngineId :: snmp_framework_mib:engine_id(),
                         TMask :: snmp_target_mib:tmask(),
                         TargetAddrEntry :: target_addr_entry();
                 (Name, IP, Port, TagList, ParamsName, EngineId, TMask) -> TargetAddrEntry
                     when
                         Name :: snmp_target_mib:name(),
                         IP :: inet:ip_address(),
                         Port :: inet:port_number(),
                         TagList :: snmp_target_mib:tag_list(),
                         ParamsName :: snmp_target_mib:params(),
                         EngineId :: snmp_framework_mib:engine_id(),
                         TMask :: snmp_target_mib:tmask(),
                         TargetAddrEntry :: target_addr_entry().

Create an entry for the agent target_addr config file, target_addr.conf.

Name must be a non-empty string.

target_addr_entry/7 (1) translates to the following call: target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask, 2048).

target_addr_entry/7 (2) translates to the following call (with Domain and Addr built from IP and Port): target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask, 2048).

See Target Address Definitions for more info.

Link to this function

target_addr_entry/8

View Source (since OTP 17.3)

-spec target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask, MaxMessageSize) ->
                     TargetAddrEntry
                     when
                         Name :: snmp_target_mib:name(),
                         Domain :: transportDomain(),
                         Addr :: transportAddress(),
                         TagList :: snmp_target_mib:tag_list(),
                         ParamsName :: snmp_target_mib:params(),
                         EngineId :: snmp_framework_mib:engine_id(),
                         TMask :: snmp_target_mib:tmask(),
                         MaxMessageSize :: snmp_target_mib:mms(),
                         TargetAddrEntry :: target_addr_entry();
                 (Name, IP, Port, TagList, ParamsName, EngineId, TMask, MaxMessageSize) ->
                     TargetAddrEntry
                     when
                         Name :: snmp_target_mib:name(),
                         IP :: inet:ip_address(),
                         Port :: inet:port_number(),
                         TagList :: snmp_target_mib:tag_list(),
                         ParamsName :: snmp_target_mib:params(),
                         EngineId :: snmp_framework_mib:engine_id(),
                         TMask :: snmp_target_mib:tmask(),
                         MaxMessageSize :: snmp_target_mib:mms(),
                         TargetAddrEntry :: target_addr_entry().

Create an entry for the agent target_addr config file, target_addr.conf.

Name must be a non-empty string.

target_addr_entry/8 (1) translates to the following call: target_addr_entry(Name, Domain, Addr, 1500, 3, TagList, ParamsName, EngineId, TMask, MaxMessageSize).

target_addr_entry/8 (2) translates to the following call (with Domain and Addr built from IP and Port): target_addr_entry(Name, Domain, Addr, 1500, 3, TagList, ParamsName, EngineId, TMask, MaxMessageSize).

See Target Address Definitions for more info.

Link to this function

target_addr_entry(Name, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize)

View Source (since OTP 17.3)

-spec target_addr_entry(Name, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask,
                  MaxMessageSize) ->
                     TargetAddrEntry
                     when
                         Name :: snmp_target_mib:name(),
                         Domain :: transportDomain(),
                         Addr :: transportAddress(),
                         Timeout :: snmp:time_interval(),
                         RetryCount :: snmp_target_mib:retry_count(),
                         TagList :: snmp_target_mib:tag_list(),
                         ParamsName :: snmp_framework_mib:admin_string(),
                         EngineId :: snmp_framework_mib:engine_id(),
                         TMask :: snmp_target_mib:tmask(),
                         MaxMessageSize :: snmp_target_mib:mms(),
                         TargetAddrEntry :: target_addr_entry().

Create an entry for the agent target_addr config file, target_addr.conf.

Name must be a non-empty string.

See Target Address Definitions for more info.

Link to this function

target_params_entry(Name, Vsn)

View Source

-spec target_params_entry(Name, Vsn) -> TargetParamsEntry
                       when
                           Name :: snmp_target_mib:name(),
                           Vsn :: snmp:version(),
                           TargetParamsEntry :: target_params_entry().

Create an entry for the agent target_params config file, target_params.conf.

Name must be a non-empty string.

target_params_entry/2 translates to the following call:

	  target_params_entry(Name, Vsn, "initial", noAuthNoPriv)

See Target Parameters Definitions for more info.

Link to this function

target_params_entry(Name, Vsn, SecName, SecLevel)

View Source

-spec target_params_entry(Name, Vsn, SecName, SecLevel) -> TargetParamsEntry
                       when
                           Name :: snmp_target_mib:name(),
                           Vsn :: snmp:version(),
                           SecName :: snmp_framework_mib:admin_string(),
                           SecLevel :: snmp_framework_mib:security_level(),
                           TargetParamsEntry :: target_params_entry().

Create an entry for the agent target_params config file, target_params.conf.

Name must be a non-empty string.

Vsn translates into MPModel and SecModel as follows:

	  Vsn = v1 => MPModel = v1,  SecModel = v1
	  Vsn = v2 => MPModel = v2c, SecModel = v2c
	  Vsn = v3 => MPModel = v3,  SecModel = usm

target_params_entry/4 translates to the following call:

	  target_params_entry(Name, MPModel, SecModel, SecName, SecLevel)

Where MPModel and SecModel is mapped from Vsn, see above.

See Target Parameters Definitions for more info.

Link to this function

target_params_entry(Name, MPModel, SecModel, SecName, SecLevel)

View Source

-spec target_params_entry(Name, MPModel, SecModel, SecName, SecLevel) -> TargetParamsEntry
                       when
                           Name :: snmp_target_mib:name(),
                           MPModel :: snmp_framework_mib:message_processing_model(),
                           SecModel :: snmp_framework_mib:security_model(),
                           SecName :: snmp_framework_mib:admin_string(),
                           SecLevel :: snmp_framework_mib:security_level(),
                           TargetParamsEntry :: target_params_entry().

Create an entry for the agent target_params config file, target_params.conf.

Name must be a non-empty string.

See Target Parameters Definitions for more info.

Link to this function

usm_entry(EngineID)

View Source

-spec usm_entry(EngineID) -> UsmEntry
             when EngineID :: snmp_framework_mib:engine_id(), UsmEntry :: usm_entry().

Create an entry for the agent usm config file, usm.conf.

usm_entry/1 translates to the following call:

	  usm_entry(EngineID,
	            "initial", "initial", zeroDotZero,
		    usmNoAuthProtocol, "", "",
		    usmNoPrivProtocol, "", "",
		    "", "", "").

See Security data for USM for more info.

Link to this function

usm_entry(EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey)

View Source

-spec usm_entry(EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC,
          OwnPrivKeyC, Public, AuthKey, PrivKey) ->
             UsmEntry
             when
                 EngineID :: snmp_framework_mib:engine_id(),
                 UserName :: snmp_user_based_sm_mib:name(),
                 SecName :: snmp_framework_mib:admin_string(),
                 Clone :: snmp_user_based_sm_mib:clone_from(),
                 AuthP :: snmp_user_based_sm_mib:auth_protocol(),
                 AuthKeyC :: snmp_user_based_sm_mib:key_change(),
                 OwnAuthKeyC :: snmp_user_based_sm_mib:key_change(),
                 PrivP :: snmp_user_based_sm_mib:priv_protocol(),
                 PrivKeyC :: snmp_user_based_sm_mib:key_change(),
                 OwnPrivKeyC :: snmp_user_based_sm_mib:key_change(),
                 Public :: snmp_user_based_sm_mib:public(),
                 AuthKey :: snmp_user_based_sm_mib:auth_key(),
                 PrivKey :: snmp_user_based_sm_mib:priv_key(),
                 UsmEntry :: usm_entry().

Create an entry for the agent usm config file, usm.conf.

See Security data for USM for more info.

Link to this function

vacm_acc_entry(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV)

View Source

-spec vacm_acc_entry(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV) -> VacmAccEntry
                  when
                      GroupName :: snmp_framework_mib:admin_string(),
                      Prefix :: snmp_view_based_acm_mib:context_prefix(),
                      SecModel :: snmp_framework_mib:security_model(),
                      SecLevel :: snmp_framework_mib:security_level(),
                      Match :: snmp_view_based_acm_mib:context_match(),
                      RV :: snmp_framework_mib:admin_string(),
                      WV :: snmp_framework_mib:admin_string(),
                      NV :: snmp_framework_mib:admin_string(),
                      VacmAccEntry :: vacm_acc_entry().

Create an (access) entry for the agent vacm config file, vacm.conf.

See MIB Views for VACM for more info.

Link to this function

vacm_s2g_entry(SecModel, SecName, GroupName)

View Source

-spec vacm_s2g_entry(SecModel, SecName, GroupName) -> VacmS2GEntry
                  when
                      SecModel :: snmp_framework_mib:security_model(),
                      SecName :: snmp_view_based_acm_mib:security_name(),
                      GroupName :: snmp_framework_mib:admin_string(),
                      VacmS2GEntry :: vacm_s2g_entry().

Create an (security to group) entry for the agent vacm config file, vacm.conf.

See MIB Views for VACM for more info.

Link to this function

vacm_vtf_entry(ViewName, ViewSubtree)

View Source

-spec vacm_vtf_entry(ViewName, ViewSubtree) -> VacmVtfEntry
                  when
                      ViewName :: snmp_framework_mib:admin_string(),
                      ViewSubtree :: snmp:oid(),
                      VacmVtfEntry :: VacmVtfEntry.

Create an (view tree family) entry for the agent vacm config file, vacm.conf.

vacm_vtf_entry/2 translates to the following call:

	  vacm_vtf_entry(ViewIndex, ViewSubtree, included, null).

See MIB Views for VACM for more info.

Link to this function

vacm_vtf_entry(ViewName, ViewSubtree, ViewType, ViewMask)

View Source

-spec vacm_vtf_entry(ViewName, ViewSubtree, ViewType, ViewMask) -> VacmVtfEntry
                  when
                      ViewName :: snmp_framework_mib:admin_string(),
                      ViewSubtree :: snmp:oid(),
                      ViewType :: snmp_view_based_acm_mib:view_type(),
                      ViewMask :: null | snmp_view_based_acm_mib:view_mask(),
                      VacmVtfEntry :: VacmVtfEntry.

Create an (view tree family) entry for the agent vacm config file, vacm.conf.

See MIB Views for VACM for more info.

Link to this function

write_agent_config(Dir, Conf)

View Source

-spec write_agent_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [agent_entry()].

Equivalent to write_agent_config/3.

Link to this function

write_agent_config(Dir, Hdr, Conf)

View Source

-spec write_agent_config(Dir, Hdr, Conf) -> ok
                      when Dir :: snmp:dir(), Hdr :: string(), Conf :: [agent_entry()].

Write the agent config to the agent config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Agent Information for more info.

Link to this function

write_community_config(Dir, Conf)

View Source

-spec write_community_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [community_entry()].

Equivalent to write_community_config/3.

Link to this function

write_community_config(Dir, Hdr, Conf)

View Source

-spec write_community_config(Dir, Hdr, Conf) -> ok
                          when Dir :: snmp:dir(), Hdr :: string(), Conf :: [community_entry()].

Write the agent community config to the agent community config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Community for more info.

Link to this function

write_context_config(Dir, Conf)

View Source

-spec write_context_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [context_entry()].

Equivalent to write_context_config/3.

Link to this function

write_context_config(Dir, Hdr, Conf)

View Source

-spec write_context_config(Dir, Hdr, Conf) -> ok
                        when Dir :: snmp:dir(), Hdr :: string(), Conf :: [context_entry()].

Write the agent context config to the agent context config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Contexts for more info.

Link to this function

write_notify_config(Dir, Conf)

View Source

-spec write_notify_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [notify_entry()].

Equivalent to write_notify_config/3.

Link to this function

write_notify_config(Dir, Hdr, Conf)

View Source

-spec write_notify_config(Dir, Hdr, Conf) -> ok
                       when Dir :: snmp:dir(), Hdr :: string(), Conf :: [notify_entry()].

Write the agent notify config to the agent notify config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Notify Definitions for more info.

Link to this function

write_standard_config(Dir, Conf)

View Source

-spec write_standard_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [standard_entry()].

Equivalent to write_standard_config/3.

Link to this function

write_standard_config(Dir, Hdr, Conf)

View Source

-spec write_standard_config(Dir, Hdr, Conf) -> ok
                         when Dir :: snmp:dir(), Hdr :: string(), Conf :: [standard_entry()].

Write the agent standard config to the agent standard config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See System Information for more info.

Link to this function

write_target_addr_config(Dir, Conf)

View Source

-spec write_target_addr_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [target_addr_entry()].

Equivalent to write_target_addr_config/3.

Link to this function

write_target_addr_config(Dir, Hdr, Conf)

View Source

-spec write_target_addr_config(Dir, Hdr, Conf) -> ok
                            when Dir :: snmp:dir(), Hdr :: string(), Conf :: [target_addr_entry()].

Write the agent target_addr config to the agent target_addr config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Target Address Definitions for more info.

Link to this function

write_target_params_config(Dir, Conf)

View Source

-spec write_target_params_config(Dir, Conf) -> ok
                              when Dir :: snmp:dir(), Conf :: [target_params_entry()].

Equivalent to write_target_params_config/3.

Link to this function

write_target_params_config(Dir, Hdr, Conf)

View Source

-spec write_target_params_config(Dir, Hdr, Conf) -> ok
                              when
                                  Dir :: snmp:dir(),
                                  Hdr :: string(),
                                  Conf :: [target_params_entry()].

Write the agent target_params config to the agent target_params config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Target Parameters Definitions for more info.

Link to this function

write_usm_config(Dir, Conf)

View Source

-spec write_usm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [usm_entry()].

Equivalent to write_usm_config/3.

Link to this function

write_usm_config(Dir, Hdr, Conf)

View Source

-spec write_usm_config(Dir, Hdr, Conf) -> ok
                    when Dir :: snmp:dir(), Hdr :: string(), Conf :: [usm_entry()].

Write the agent usm config to the agent usm config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Security data for USM for more info.

Link to this function

write_vacm_config(Dir, Conf)

View Source

-spec write_vacm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [vacm_entry()].

Equivalent to write_vacm_config/3.

Link to this function

write_vacm_config(Dir, Hdr, Conf)

View Source

-spec write_vacm_config(Dir, Hdr, Conf) -> ok
                     when Dir :: snmp:dir(), Hdr :: string(), Conf :: [vacm_entry()].

Write the agent vacm config to the agent vacm config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See MIB Views for VACM for more info.

snmpa_discovery_handler behaviour

Behaviour module for the SNMP agent discovery handler.

This module defines the behaviour of the agent discovery handler. A snmpa_discovery_handler compliant module must export the following functions:

stage1_finish/3

The semantics of them and their exact signatures are explained below.

Summary

Callbacks

stage1_finish(TargetName, ManagerEngineID, ExtraInfo)

This function is called at the end of stage 1 of the discovery process. It should return either the atom ignore or {ok, usm_entry() | [usm_entry()]}. See usm_entry() and usm_entry/1,3 for more info.

Callbacks

Link to this callback

stage1_finish(TargetName, ManagerEngineID, ExtraInfo)

View Source

-callback stage1_finish(TargetName, ManagerEngineID, ExtraInfo) ->
                 ignore | {ok, UsmEntry | [UsmEntry]} | {ok, UsmEntry | [UsmEntry], NewExtraInfo}
                 when
                     TargetName :: snmp_target_mib:name(),
                     ManagerEngineID :: snmp_framework_mib:engine_id(),
                     ExtraInfo :: term(),
                     UsmEntry :: snmp_user_based_sm_mib:usm_entry(),
                     NewExtraInfo :: term().

This function is called at the end of stage 1 of the discovery process. It should return either the atom ignore or {ok, usm_entry() | [usm_entry()]}. See usm_entry() and usm_entry/1,3 for more info.

If the function returns ignore, then it is assumed that either:

The caller (of the discovery function) will make the needed updates later.

The callback function itself did the updates.

In either case, the agent will do nothing, but return the retrieved ManagerEngineID (see snmpa:discovery/6 for more info) and possible continue with stage 2 of the discovery process.

The ExtraInfo argument is passed on from the snmpa:discovery/6 function.

This function may return an updated NewExtraInfo that will be used in subsequent calls to the callback functions. Intended for future use.

The purpose of this function is to generate the usm- related security data needed for usm processing in the agent. Specifically, updating the usmUserTable.

When an usm_entry() tuple (or a list of such tuples) is returned, this data is then added to the usmUserTable by the (master-) agent.

When an usm_entry() tuple (or a list of such tuples) is returned, this data is then added to the usmUserTable by the (master-) agent.

Note

Note that the function does not check if this entry already exists.

Note

Note that this function is executed in the context of the master-agent process.

snmpa_error

Functions for Reporting SNMP Errors

The module snmpa_error contains two callback functions which are called if an error occurs at different times during agent operation. These functions in turn calls the corresponding function in the configured error report module, which implements the actual report functionality.

Two simple implementation(s) is provided with the toolkit; the modules snmpa_error_logger which is the default and snmpa_error_io.

The error report module is configured using the directive error_report_mod, see configuration parameters.

Summary

Functions

config_err(Format, Args)

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

user_err(Format, Args)

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Functions

Link to this function

config_err(Format, Args)

View Source

-spec config_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

Format and Args are as in io:format(Format, Args).

Link to this function

user_err(Format, Args)

View Source

-spec user_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Format and Args are as in io:format(Format, Args).

snmpa_error_io

Functions for Reporting SNMP Errors on stdio

The module snmpa_error_io implements the snmp_error_report behaviour (see snmpa_error_report) containing two callback functions which are called in order to report SNMP errors.

This module provides a simple mechanism for reporting SNMP errors. Errors are written to stdout using the io module. It is provided as an simple example.

This module needs to be explicitly configured, see snmpa_error and configuration parameters.

Summary

Functions

config_err(Format, Args)

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

user_err(Format, Args)

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Functions

Link to this function

config_err(Format, Args)

View Source

-spec config_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

Format and Args are as in io:format(Format, Args).

Link to this function

user_err(Format, Args)

View Source

-spec user_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Format and Args are as in io:format(Format, Args).

snmpa_error_logger

Functions for Reporting SNMP Errors through the error_logger

The module snmpa_error_logger implements the snmpa_error_report behaviour (see snmpa_error_report) containing two callback functions which are called in order to report SNMP errors.

This module provides a simple mechanism for reporting SNMP errors. Errors are sent to the error_logger after a size check. Messages are truncated after 1024 chars. It is provided as an example.

This module is the default error report module, but can be explicitly configured, see snmpa_error and configuration parameters.

See Also

error_logger(3)

Summary

Functions

config_err(Format, Args)

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

user_err(Format, Args)

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Functions

Link to this function

config_err(Format, Args)

View Source

-spec config_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

Format and Args are as in io:format(Format, Args).

Link to this function

user_err(Format, Args)

View Source

-spec user_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Format and Args are as in io:format(Format, Args).

snmpa_error_report behaviour

Behaviour module for reporting SNMP agent errors

This module defines the behaviour of the agent error reporting. A snmpa_error_report compliant module must export the following functions:

config_err/2

user_err/2

The semantics of them and their exact signatures are explained below.

Summary

Callbacks

config_err(Format, Args)

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

user_err(Format, Args)

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Callbacks

Link to this callback

config_err(Format, Args)

View Source

-callback config_err(Format, Args) -> snmp:void() when Format :: string(), Args :: [term()].

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

Format and Args are as in io:format(Format, Args).

Link to this callback

user_err(Format, Args)

View Source

-callback user_err(Format, Args) -> snmp:void() when Format :: string(), Args :: [term()].

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Format and Args are as in io:format(Format, Args).

snmpa_local_db

The SNMP built-in database

The module snmpa_local_db contains functions for implementing tables (and variables) using the SNMP built-in database. The database exists in two instances, one volatile and one persistent. The volatile database is implemented with ets. The persistent database is implemented with dets.

There is a scaling problem with this database.

Insertions and deletions are inefficient for large tables.

This problem is best solved by using Mnesia instead.

The following functions describe the interface to snmpa_local_db. Each function has a Mnesia equivalent. The argument NameDb is a tuple {Name, Db} where Name is the symbolic name of the managed object (as defined in the MIB), and Db is either volatile or persistent. mnesia is not possible since all these functions are snmpa_local_db specific.

Common Data Types

In the functions defined below, the following limitation applies:

Db = volatile | persistent

See Also

ets(3), dets(3), snmp_generic(3)

Summary

Functions

dump()

This function can be used to manually dump the database to file.

match(Table, Pattern)

Performs an ets/dets matching on the table.

print()

Equivalent to print/2.

print(Table)

Equivalent to print/2.

print(Table, Db)

Prints the contents of the database on screen. This is useful for debugging since the STANDARD-MIB and OTP-SNMPEA-MIB (and maybe your own MIBs) are stored in snmpa_local_db.

table_create(Table)

Creates a table. If the table already exist, the old copy is destroyed.

table_create_row(Table, RowIndex, Row)

Creates a row in a table. Row is a tuple with values for all columns, including the index columns.

table_delete(Table)

Deletes a table.

table_delete_row(Table, RowIndex)

Deletes the row in the table.

table_exists(Table)

Checks if a table exists.

table_get_element(Table, RowIndex, Col)

Get a column value (element) from a row of the table.

table_get_row(Table, RowIndex)

Row is a tuple with values for all columns, including the index columns.

table_set_elements(Table, RowIndex, Cols)

Update the specified columnar objects of the row of this table.

Functions

Link to this function

dump()

View Source

-spec dump() -> ok | {error, Reason} when Reason :: term().

This function can be used to manually dump the database to file.

Link to this function

match(Table, Pattern)

View Source

-spec match(Table, Pattern) -> [Match]
         when
             Table :: snmpa:name_db() | snmpa:name(),
             Pattern :: ets:match_pattern(),
             Match :: term().

Performs an ets/dets matching on the table.

See ets:match/2 for a description of Pattern and the return values.

Link to this function

print()

View Source

-spec print() -> term().

Equivalent to print/2.

Link to this function

print(Table)

View Source

-spec print(Table) -> term() when Table :: snmpa:name().

Equivalent to print/2.

Link to this function

print(Table, Db)

View Source

-spec print(Table, Db) -> term() when Table :: snmpa:name(), Db :: volatile | persistent.

Prints the contents of the database on screen. This is useful for debugging since the STANDARD-MIB and OTP-SNMPEA-MIB (and maybe your own MIBs) are stored in snmpa_local_db.

Table is an atom for a table in the database. When no name is supplied, the whole database is shown.

Note that these functions does not actually print, using io:format/2, instead they (just) return the information. If executed in a shell, the information will then be displayed (probably truncated) there.

A better use would be:

	  io:format("~p~n", [snmpa_local_db:print()]).

Link to this function

table_create(Table)

View Source

-spec table_create(Table) -> boolean() when Table :: snmpa:name_db() | snmpa:name().

Creates a table. If the table already exist, the old copy is destroyed.

Returns false if the NameDb argument is incorrectly specified, true otherwise.

Database (only table name specified) defaults to volatile.

Link to this function

table_create_row(Table, RowIndex, Row)

View Source

-spec table_create_row(Table, RowIndex, Row) -> boolean()
                    when
                        Table :: snmpa:name_db() | snmpa:name(),
                        RowIndex :: snmp:row_index(),
                        Row :: tuple().

Creates a row in a table. Row is a tuple with values for all columns, including the index columns.

Database (only table name specified) defaults to volatile.

Link to this function

table_delete(Table)

View Source

-spec table_delete(Table) -> true when Table :: snmpa:name_db() | snmpa:name().

Deletes a table.

Database (only table name specified) defaults to volatile.

Link to this function

table_delete_row(Table, RowIndex)

View Source

-spec table_delete_row(Table, RowIndex) -> boolean()
                    when Table :: snmpa:name_db() | snmpa:name(), RowIndex :: snmp:row_index().

Deletes the row in the table.

Database (only table name specified) defaults to volatile.

Link to this function

table_exists(Table)

View Source

-spec table_exists(Table) -> boolean() when Table :: snmpa:name_db() | snmpa:name().

Checks if a table exists.

Database (only table name specified) defaults to volatile.

Link to this function

table_get_element(Table, RowIndex, Col)

View Source

-spec table_get_element(Table, RowIndex, Col) -> {value, Value} | undefined
                     when
                         Table :: snmpa:name_db() | snmpa:name(),
                         RowIndex :: snmp:row_index(),
                         Col :: snmp:column(),
                         Value :: term().

Get a column value (element) from a row of the table.

Database (only table name specified) defaults to volatile.

Link to this function

table_get_row(Table, RowIndex)

View Source

-spec table_get_row(Table, RowIndex) -> Row | undefined
                 when
                     Table :: snmpa:name_db() | snmpa:name(),
                     RowIndex :: snmp:row_index(),
                     Row :: tuple().

Row is a tuple with values for all columns, including the index columns.

Database (only table name specified) defaults to volatile.

Link to this function

table_set_elements(Table, RowIndex, Cols)

View Source

-spec table_set_elements(Table, RowIndex, Cols) -> boolean()
                      when
                          Table :: snmpa:name_db() | snmpa:name(),
                          RowIndex :: snmp:row_index(),
                          Cols :: [{Col, Value}],
                          Col :: snmp:column(),
                          Value :: term().

Update the specified columnar objects of the row of this table.

Database (only table name specified) defaults to volatile.

snmpa_mib_data behaviour

Behaviour module for the SNMP agent mib-server data module.

This module defines the behaviour of the SNMP agent mib-server data module. A snmpa_mib_data compliant module must export the following functions:

new/1

close/1

sync/1

load_mib/4

unload_mib/4

lookup/2

next/3

register_subagent/3

unregister_subagent/2

which_mib/2

which_mibs/1

whereis_mib/2

dump/2

info/1

backup/2

code_change/4

The semantics of them and their exact signatures are explained below.

Note that the data extracted from the imported (loaded) mibs are stored partly by the mib-server and partly by the symbolic-store server. See the default mib-server data module, snmpa_mib_data_tttn for details.

Summary

Types

filename()

mib_view()

mib_view_elem()

mib_view_inclusion()

mib_view_mask()

Callbacks

backup(State, BackupDir)

Perform a backup of the mib-server data.

close(State)

Close the mib-storage.

code_change(Direction, Vsn, Extra, State)

Perform a code-change (upgrade or downgrade).

dump(State, Destination)

Dump the mib-server data to stdio (Destination = io) or the specified file.

info(State)

Retrieve misc info for the mib data.

load_mib(State, FileName, MeOverride, TeOverride)

Load the mib specified by the Filename argument into the mib-server. The MeOverride and TeOverride arguments specifies how the mib-server shall handle duplicate mib- and trap- entries.

lookup(State, Oid)

Find the mib-entry corresponding to the Oid. If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be

new(MibStorage)

Create a new mib-server data instance.

next(State, Oid, MibView)

Finds the lexicographically next oid.

register_subagent(State, Oid, Pid)

Register the subagent, process, handling part of the mib-tree.

sync(State)

Synchronize (write to disc, if possible) the mib-server data. This depends on the mib_storage option, and will only have an effect if the mib-storage option has an actual disc component (such as dets, or ets with a file).

unload_mib(State, Filename)

unload_mib(State, FileName, MeOverride, TeOverride)

Unload the mib specified by the Filename argument from the mib-server. The MeOverride and TeOverride arguments specifies how the mib-server shall handle duplicate mib- and trap- entries.

unregister_subagent(State, PidOrOid)

Unregister the subagent, handling part of the mib-tree, as specified by the oid() or pid/0 (PidOrOid).

whereis_mib(State, MibName)

Retrieve the mib file for the mib.

which_mib(State, Oid)

Retrieve the mib-file to which an given oid() belongs.

which_mibs(State)

Retrieve all loaded mib-files.

Types

Link to this type

filename()

View Source (not exported) (since OTP R16B01)

-type filename() :: file:filename().

Link to this type

mib_view()

View Source (since OTP R16B01)

-type mib_view() :: [mib_view_elem()].

Link to this type

mib_view_elem()

View Source (since OTP R16B01)

-type mib_view_elem() ::
    {SubTree :: snmp:oid(), Mask :: [non_neg_integer()], Inclusion :: mib_view_inclusion()}.

Link to this type

mib_view_inclusion()

View Source (since OTP R16B01)

-type mib_view_inclusion() :: 1 | 2.

Link to this type

mib_view_mask()

View Source (since OTP R16B01)

-type mib_view_mask() :: [non_neg_integer()].

Callbacks

Link to this callback

backup(State, BackupDir)

View Source (since OTP R16B01)

-callback backup(State :: term(), BackupDir :: string()) -> ok | {error, Reason :: term()}.

Perform a backup of the mib-server data.

Note that its implementation dependent (and also dependent on mib-storage is used) if a backup is possible.

Link to this callback

close(State)

View Source (since OTP R16B01)

-callback close(State :: term()) -> ok.

Close the mib-storage.

Link to this callback

code_change(Direction, Vsn, Extra, State)

View Source (since OTP R16B01)

-callback code_change(Direction :: up | down, Vsn :: term(), Extra :: term(), State :: term()) ->
               NewState :: term().

Perform a code-change (upgrade or downgrade).

See gen_server for more info regarding the Vsn and Extra arguments.

Link to this callback

dump(State, Destination)

View Source (since OTP R16B01)

-callback dump(State :: term(), Destination :: io | filename()) -> ok | {error, Reason :: term()}.

Dump the mib-server data to stdio (Destination = io) or the specified file.

Link to this callback

info(State)

View Source (since OTP R16B01)

-callback info(State :: term()) -> list().

Retrieve misc info for the mib data.

This is a utility function used to inspect, for instance, memory usage, in a simple way.

Link to this callback

load_mib(State, FileName, MeOverride, TeOverride)

View Source (since OTP R16B01)

-callback load_mib(State :: term(),
         FileName :: filename(),
         MeOverride :: boolean(),
         TeOverride :: boolean()) ->
            {ok, NewState :: term()} | {error, Reason :: already_loaded | term()}.

Load the mib specified by the Filename argument into the mib-server. The MeOverride and TeOverride arguments specifies how the mib-server shall handle duplicate mib- and trap- entries.

Link to this callback

lookup(State, Oid)

View Source (since OTP R16B01)

-callback lookup(State :: term(), Oid :: snmp:oid()) ->
          {false, Reason :: term()} |
          {variable, MibEntry :: snmpa:me()} |
          {table_column, MibEntry :: snmpa:me(), TableEntryOid :: snmp:oid()} |
          {subagent, SubAgentPid :: pid(), SAOid :: snmp:oid()}.

Find the mib-entry corresponding to the Oid. If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be

Link to this callback

new(MibStorage)

View Source (since OTP R16B01)

-callback new(MibStorage :: snmpa:mib_storage()) -> State :: term().

Create a new mib-server data instance.

Link to this callback

next(State, Oid, MibView)

View Source (since OTP R16B01)

-callback next(State :: term(), Oid :: snmp:oid(), MibView :: mib_view()) ->
        endOfView | false |
        {subagent, SubAgentPid :: pid(), SAOid :: snmp:oid()} |
        {variable, MibEntry :: snmpa:me(), VarOid :: snmp:oid()} |
        {table, TableOid :: snmp:oid(), TableRestOid :: snmp:oid(), MibEntry :: snmpa:me()}.

Finds the lexicographically next oid.

Link to this callback

register_subagent(State, Oid, Pid)

View Source (since OTP R16B01)

-callback register_subagent(State :: term(), Oid :: snmp:oid(), Pid :: pid()) ->
                     {ok, NewState :: term()} | {error, Reason :: term()}.

Register the subagent, process, handling part of the mib-tree.

Link to this callback

sync(State)

View Source (since OTP R16B01)

-callback sync(State :: term()) -> ok.

Synchronize (write to disc, if possible) the mib-server data. This depends on the mib_storage option, and will only have an effect if the mib-storage option has an actual disc component (such as dets, or ets with a file).

Link to this callback

unload_mib(State, Filename)

View Source (optional) (since OTP R16B01)

-callback unload_mib(State, Filename) -> {ok, NewState} | {error, Reason}
              when
                  State :: term(),
                  Filename :: filename(),
                  NewState :: term(),
                  Reason :: not_loaded | term().

Link to this callback

unload_mib(State, FileName, MeOverride, TeOverride)

View Source (since OTP R16B01)

-callback unload_mib(State :: term(),
           FileName :: filename(),
           MeOverride :: boolean(),
           TeOverride :: boolean()) ->
              {ok, NewState :: term()} | {error, Reason :: not_loaded | term()}.

Unload the mib specified by the Filename argument from the mib-server. The MeOverride and TeOverride arguments specifies how the mib-server shall handle duplicate mib- and trap- entries.

Link to this callback

unregister_subagent(State, PidOrOid)

View Source (since OTP R16B01)

-callback unregister_subagent(State :: term(), PidOrOid :: pid() | snmp:oid()) ->
                       {ok, NewState :: term()} |
                       {ok, NewState :: term(), Pid :: pid()} |
                       {error, Reason :: term()}.

Unregister the subagent, handling part of the mib-tree, as specified by the oid() or pid/0 (PidOrOid).

When unregister the subagent using an oid(), the pid/0 of the process handling the sub-tree is also returned.

Link to this callback

whereis_mib(State, MibName)

View Source (since OTP R16B01)

-callback whereis_mib(State :: term(), MibName :: atom()) ->
               {ok, Filename :: filename()} | {error, Reason :: term()}.

Retrieve the mib file for the mib.

Link to this callback

which_mib(State, Oid)

View Source (since OTP R16B01)

-callback which_mib(State :: term(), Oid :: snmp:oid()) -> {ok, Mib :: string()} | {error, Reason :: term()}.

Retrieve the mib-file to which an given oid() belongs.

Link to this callback

which_mibs(State)

View Source (since OTP R16B01)

-callback which_mibs(State :: term()) -> [{MibName :: atom(), Filename :: filename()}].

Retrieve all loaded mib-files.

snmpa_mib_storage behaviour

Behaviour module for the SNMP agent mib storage.

This module defines the behaviour of the SNMP agent mib storage.

The mib storage is used by the agent to store internal mib- related information. The mib storage module is used by several entities, not just the mib-server.

A snmpa_mib_storage compliant module must export the following functions:

open/5

close/1

read/2

write/2

delete/1

delete/2

match_object/2

match_delete/2

tab2list/1

info/1

sync/1

backup/2

The semantics of them and their exact signatures are explained below.

Summary

Types

mib_storage_fields()

mib_storage_table_id()

mib_storage_table_type()

Callbacks

backup(TabId, Dir)

Perform a backup of the mib-storage table.

close(TabId)

Close the mib-storage table.

delete(TabId)

Delete an entire mib-storage table.

delete(TabId, Key)

Delete a record from the mib-storage table.

info(TabId)

Retrieve implementation dependent mib-storage table information.

info(TabId, Item)

match_delete(TabId, Pattern)

Search the mib-storage table for record that match the specified pattern and then delete them. The records deleted are also returned.

match_object(TabId, Pattern)

Search the mib-storage table for record that match the specified pattern.

open(Name, RecName, Fields, Type, Options)

Create or open a mib storage table.

read(TabId, Key)

Read a record from the mib-storage table.

sync(TabId)

Synchronize the mib-storage table.

tab2list(TabId)

Return all records in the mib-storage table in the form of a list.

write(TabId, Record)

Write a record to the mib-storage table.

Types

Link to this type

mib_storage_fields()

View Source (since OTP R16B01)

-type mib_storage_fields() :: [atom()].

Link to this type

mib_storage_table_id()

View Source (since OTP R16B01)

-type mib_storage_table_id() :: term().

Link to this type

mib_storage_table_type()

View Source (since OTP R16B01)

-type mib_storage_table_type() :: set | bag.

Callbacks

Link to this callback

backup(TabId, Dir)

View Source (since OTP R16B01)

-callback backup(TabId :: mib_storage_table_id(), Dir :: file:filename()) -> ok | {error, Reason :: term()}.

Perform a backup of the mib-storage table.

What this means, if anything, is implementation dependent.

Link to this callback

close(TabId)

View Source (since OTP R16B01)

-callback close(TabId :: mib_storage_table_id()) -> term().

Close the mib-storage table.

Link to this callback

delete(TabId)

View Source (since OTP R16B01)

-callback delete(TabId :: mib_storage_table_id()) -> snmp:void().

Delete an entire mib-storage table.

Link to this callback

delete(TabId, Key)

View Source (since OTP R16B01)

-callback delete(TabId :: mib_storage_table_id(), Key :: term()) -> ok | {error, Reason :: term()}.

Delete a record from the mib-storage table.

Link to this callback

info(TabId)

View Source (since OTP R16B01)

-callback info(TabId :: mib_storage_table_id()) -> Info :: term().

Retrieve implementation dependent mib-storage table information.

Link to this callback

info(TabId, Item)

View Source (since OTP R16B01)

-callback info(TabId :: mib_storage_table_id(), Item :: atom()) -> Info :: term().

Link to this callback

match_delete(TabId, Pattern)

View Source (since OTP R16B01)

-callback match_delete(TabId :: mib_storage_table_id(), Pattern :: ets:match_pattern()) ->
                Recs :: [tuple()] | {error, Reason :: term()}.

Search the mib-storage table for record that match the specified pattern and then delete them. The records deleted are also returned.

Link to this callback

match_object(TabId, Pattern)

View Source (since OTP R16B01)

-callback match_object(TabId :: mib_storage_table_id(), Pattern :: ets:match_pattern()) ->
                Recs :: [tuple()] | {error, Reason :: term()}.

Search the mib-storage table for record that match the specified pattern.

Link to this callback

open(Name, RecName, Fields, Type, Options)

View Source (since OTP R16B01)

-callback open(Name :: atom(),
     RecName :: atom(),
     Fields :: mib_storage_fields(),
     Type :: mib_storage_table_type(),
     Options :: list()) ->
        {ok, TabId :: mib_storage_table_id()} | {error, Reason :: term()}.

Create or open a mib storage table.

Note that the RecordName and Fields arguments my not be used in all implementations (they are actually only needed for mnesia-based implementations).

Note also that the Options argument comes from the options config option of the mib-storage config option, and is passed on as is.

Link to this callback

read(TabId, Key)

View Source (since OTP R16B01)

-callback read(TabId :: mib_storage_table_id(), Key :: term()) -> false | {value, Record :: tuple()}.

Read a record from the mib-storage table.

Link to this callback

sync(TabId)

View Source (since OTP R16B01)

-callback sync(TabId :: mib_storage_table_id()) -> snmp:void().

Synchronize the mib-storage table.

What this means, if anything, is implementation dependent.

Link to this callback

tab2list(TabId)

View Source (since OTP R16B01)

-callback tab2list(TabId :: mib_storage_table_id()) -> [tuple()].

Return all records in the mib-storage table in the form of a list.

Link to this callback

write(TabId, Record)

View Source (since OTP R16B01)

-callback write(TabId :: mib_storage_table_id(), Record :: tuple()) -> ok | {error, Reason :: term()}.

Write a record to the mib-storage table.

snmpa_mpd

Message Processing and Dispatch module for the SNMP agent

The module snmpa_mpd implements the version independent Message Processing and Dispatch functionality in SNMP for the agent. It is supposed to be used from a Network Interface process (Definition of Agent Net if).

DATA TYPES

For more information, see the data types in snmpa_conf.

Summary

Types

acm_data()

This is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent (by the net-if process).

acm_data_cmy()

This is the message specific data used in the SNMPv1 and SNMPv2c message.

acm_data_v3()

This is the message specific data used in the SNMPv3 message.

logger()

A fun that handles audit trail logging.

mpd_state()

msg_data()

This is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent (by the net-if process).

msg_data_cmy()

This is the message specific data used in the SNMP message. In SNMPv1 and SNMPv2c, this message data is the community string.

msg_data_ctx()

This is the message specific data used in the SNMP message. In SNMPv3, it is the context information.

Functions

discarded_pdu(Variable)

Increments the variable associated with a discarded pdu. This function can be used when the net_if process receives a discarded_pdu message from the agent.

generate_msg(Vsn, NoteStore, Pdu, MsgData, To)

Equivalent to generate_msg/6.

generate_msg(Vsn, NoteStore, Pdu, MsgData, LocalEngineID, To)

Generates a possibly encrypted request packet to be sent to the network.

generate_response_msg(Vsn, RePdu, Type, ACMData, Log)

Equivalent to generate_response_msg/6.

generate_response_msg(Vsn, RePdu, Type, ACMData, LocalEngineID, Log)

Generates a possibly encrypted response packet to be sent to the network. Type is the #pdu.type of the original request.

init(Vsns)

This function can be called from the net_if process at start-up. The options list defines which versions to use.

process_packet(Packet, From, State, NoteStore, Log)

Equivalent to process_packet/6.

process_packet/6

Processes an incoming packet. Performs authentication and decryption as necessary. The return values should be passed to the agent.

process_taddrs(InDests)

Transforms addresses from internal MIB format to one more useful to Agent Net if.

Types

Link to this type

acm_data()

View Source

-type acm_data() :: acm_data_cmy() | acm_data_v3().

This is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent (by the net-if process).

Link to this opaque

acm_data_cmy()

View Source

-opaque acm_data_cmy()

This is the message specific data used in the SNMPv1 and SNMPv2c message.

Link to this opaque

acm_data_v3()

View Source

-opaque acm_data_v3()

This is the message specific data used in the SNMPv3 message.

Link to this type

logger()

View Source

-type logger() ::
    fun((Type :: snmp_pdus:pdu_type(),
         Data :: binary() | {V3Hdr :: snmp_pdus:v3_hdr(), ScopedPDUBytes :: binary()}) ->
            snmp:void()).

A fun that handles audit trail logging.

Link to this opaque

mpd_state()

View Source

-opaque mpd_state()

Link to this type

msg_data()

View Source

-type msg_data() :: msg_data_cmy() | msg_data_ctx().

This is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent (by the net-if process).

Link to this opaque

msg_data_cmy()

View Source

-opaque msg_data_cmy()

This is the message specific data used in the SNMP message. In SNMPv1 and SNMPv2c, this message data is the community string.

Link to this opaque

msg_data_ctx()

View Source

-opaque msg_data_ctx()

This is the message specific data used in the SNMP message. In SNMPv3, it is the context information.

Functions

Link to this function

discarded_pdu(Variable)

View Source

-spec discarded_pdu(Variable) -> snmp:void() when Variable :: snmpa:name() | false.

Increments the variable associated with a discarded pdu. This function can be used when the net_if process receives a discarded_pdu message from the agent.

Link to this function

generate_msg(Vsn, NoteStore, Pdu, MsgData, To)

View Source (since OTP R14B)

-spec generate_msg(Vsn, NoteStore, Pdu, MsgData, To) -> {ok, PacketsAndAddresses} | {discarded, Reason}
                when
                    Vsn :: snmp_pdus:version(),
                    NoteStore :: pid(),
                    Pdu :: snmp_pdus:pdu(),
                    MsgData :: msg_data(),
                    To :: [{Domain, Address}],
                    PacketsAndAddresses :: [{Domain, Address, Packet}],
                    Domain :: snmpa_conf:transportDomain(),
                    Address :: snmpa_conf:transportAddress(),
                    Packet :: binary(),
                    Reason :: term().

Equivalent to generate_msg/6.

Link to this function

generate_msg(Vsn, NoteStore, Pdu, MsgData, LocalEngineID, To)

View Source (since OTP R14B)

-spec generate_msg(Vsn, NoteStore, Pdu, MsgData, LocalEngineID, To) ->
                {ok, PacketsAndAddresses} | {discarded, Reason}
                when
                    Vsn :: snmp_pdus:version(),
                    NoteStore :: pid(),
                    Pdu :: snmp_pdus:pdu(),
                    MsgData :: msg_data(),
                    LocalEngineID :: snmp_framework_mib:engine_id(),
                    To :: [DestAddr],
                    DestAddr :: {Domain, Address} | {{Domain, Address}, SecData},
                    SecData :: term(),
                    PacketsAndAddresses :: [{Domain, Address, Packet}],
                    Domain :: snmpa_conf:transportDomain(),
                    Address :: snmpa_conf:transportAddress(),
                    Packet :: binary(),
                    Reason :: term().

Generates a possibly encrypted request packet to be sent to the network.

MsgData is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent. In SNMPv1 and SNMPv2c, this message data is the community string. In SNMPv3, it is the context information.

To is a list of destination addresses and their corresponding security parameters. This value is received in the same message from the agent and then transformed through process_taddrs before passed to this function.

Note

Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

Link to this function

generate_response_msg(Vsn, RePdu, Type, ACMData, Log)

View Source (since OTP R14B)

-spec generate_response_msg(Vsn, RePdu, Type, ACMData, Log) -> {ok, Packet} | {discarded, Reason}
                         when
                             Vsn :: snmp_pdus:version(),
                             RePdu :: snmp_pdus:pdu(),
                             Type :: snmp_pdus:pdu_type(),
                             ACMData :: acm_data(),
                             Log :: logger(),
                             Packet :: binary(),
                             Reason :: term().

Equivalent to generate_response_msg/6.

Link to this function

generate_response_msg(Vsn, RePdu, Type, ACMData, LocalEngineID, Log)

View Source (since OTP R14B)

-spec generate_response_msg(Vsn, RePdu, Type, ACMData, LocalEngineID, Log) ->
                         {ok, Packet} | {discarded, Reason}
                         when
                             Vsn :: snmp_pdus:version(),
                             RePdu :: snmp_pdus:pdu(),
                             Type :: snmp_pdus:pdu_type(),
                             ACMData :: acm_data(),
                             LocalEngineID :: snmp_framework_mib:engine_id(),
                             Log :: logger(),
                             Packet :: binary(),
                             Reason :: term().

Generates a possibly encrypted response packet to be sent to the network. Type is the #pdu.type of the original request.

Note

Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

Link to this function

init(Vsns)

View Source

-spec init(Vsns) -> MPDState when Vsns :: [snmp:version()], MPDState :: mpd_state().

This function can be called from the net_if process at start-up. The options list defines which versions to use.

It also initializes some SNMP counters.

Link to this function

process_packet(Packet, From, State, NoteStore, Log)

View Source (since OTP 17.3)

-spec process_packet(Packet, From, State, NoteStore, Log) ->
                  {ok, Vsn, Pdu, PduMS, ACMData} | {discarded, Reason} | {discovery, DiscoPacket}
                  when
                      Packet :: binary(),
                      From :: {TDomain, TAddress},
                      TDomain :: snmpa_conf:transportDomain(),
                      TAddress :: {IpAddr, IpPort},
                      IpAddr :: inet:ip_address(),
                      IpPort :: inet:port_number(),
                      State :: mpd_state(),
                      NoteStore :: pid(),
                      Log :: logger(),
                      Vsn :: snmp_pdus:version(),
                      Pdu :: snmp_pdus:pdu(),
                      PduMS :: pos_integer(),
                      ACMData :: acm_data(),
                      Reason :: term(),
                      DiscoPacket :: binary().

Equivalent to process_packet/6.

Link to this function

process_packet/6

View Source (since OTP R14B)

-spec process_packet(Packet, TDomain, TAddress, State, NoteStore, Log) ->
                  {ok, Vsn, Pdu, PduMS, ACMData} | {discarded, Reason} | {discovery, DiscoPacket}
                  when
                      Packet :: binary(),
                      TDomain :: snmpa_conf:transportDomain(),
                      TAddress :: {IpAddr, IpPort},
                      IpAddr :: inet:ip_address(),
                      IpPort :: inet:port_number(),
                      State :: mpd_state(),
                      NoteStore :: pid(),
                      Log :: logger(),
                      Vsn :: snmp_pdus:version(),
                      Pdu :: snmp_pdus:pdu(),
                      PduMS :: pos_integer(),
                      ACMData :: acm_data(),
                      Reason :: term(),
                      DiscoPacket :: binary();
              (Packet, From, LocalEngineID, State, NoteStore, Log) ->
                  {ok, Vsn, Pdu, PduMS, ACMData} | {discarded, Reason} | {discovery, DiscoPacket}
                  when
                      Packet :: binary(),
                      From :: {TDomain, TAddress},
                      TDomain :: snmpa_conf:transportDomain(),
                      TAddress :: {IpAddr, IpPort},
                      IpAddr :: inet:ip_address(),
                      IpPort :: inet:port_number(),
                      LocalEngineID :: snmp_framework_mib:engine_id(),
                      State :: mpd_state(),
                      NoteStore :: pid(),
                      Log :: logger(),
                      Vsn :: snmp_pdus:version(),
                      Pdu :: snmp_pdus:pdu(),
                      PduMS :: pos_integer(),
                      ACMData :: acm_data(),
                      Reason :: term(),
                      DiscoPacket :: binary().

Processes an incoming packet. Performs authentication and decryption as necessary. The return values should be passed to the agent.

Note

Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

Link to this function

process_taddrs(InDests)

View Source (since OTP 17.3)

-spec process_taddrs(InDests) -> OutDests
                  when
                      InDests :: [InDest],
                      InDest :: {{InDomain, InAddress}, SecData} | {InDomain, InAddress},
                      InDomain :: term(),
                      InAddress :: term(),
                      SecData :: term(),
                      OutDests :: [OutDest],
                      OutDest :: {{OutDomain, OutAddress}, SecData} | {OutDomain, OutAddress},
                      OutDomain :: snmpa_conf:transportDomain(),
                      OutAddress :: snmpa_conf:transportAddress().

Transforms addresses from internal MIB format to one more useful to Agent Net if.

See also generate_msg.

snmpa_network_interface behaviour

Behaviour module for the SNMP agent network interface.

This module defines the behaviour of the agent network interface. A snmpa_network_interface compliant module must export the following functions:

start_link/4

info/1

get_log_type/1

set_log_type/2

verbosity/2

The semantics of them and their exact signatures are explained below.

But this is not enough. There is also a set of mandatory messages which the network interface entity must be able to receive and be able to send. This is described in chapter snmp_agent_netif.

Summary

Callbacks

get_log_type(Pid)

The Audit Trail Log is managed by the network interface process. So, it is this process that has to retrieve the actual log-type.

get_request_limit(Pid)

info(Pid)

The info returned is basically up to the implementer to decide. This implementation provided by the application provides info about memory allocation and various socket information.

set_log_type(Pid, NewType)

The Audit Trail Log is managed by the network interface process. So, it is this process that has to do the actual changing of the type.

set_request_limit(Pid, NewLimit)

start_link(Prio, NoteStore, MasterAgent, Opts)

Start-link the network interface process.

verbosity(Pid, Verbosity)

Change the verbosity of a running network interface process.

Callbacks

Link to this callback

get_log_type(Pid)

View Source

-callback get_log_type(Pid) -> {ok, LogType} | {error, Reason}
                when Pid :: pid(), LogType :: snmp:atl_type(), Reason :: term().

The Audit Trail Log is managed by the network interface process. So, it is this process that has to retrieve the actual log-type.

Link to this callback

get_request_limit(Pid)

View Source

-callback get_request_limit(Pid) -> {ok, Limit} when Pid :: pid(), Limit :: non_neg_integer() | infinity.

Link to this callback

info(Pid)

View Source

-callback info(Pid) -> Info when Pid :: pid(), Info :: [{Key, Value}], Key :: term(), Value :: term().

The info returned is basically up to the implementer to decide. This implementation provided by the application provides info about memory allocation and various socket information.

The info returned by this function is returned together with other info collected by the agent when the info/1 function is called (tagged with with the key net_if).

Link to this callback

set_log_type(Pid, NewType)

View Source

-callback set_log_type(Pid, NewType) -> {ok, OldType} | {error, Reason}
                when
                    Pid :: pid(),
                    NewType :: snmp:atl_type(),
                    OldType :: snmp:atl_type(),
                    Reason :: term().

The Audit Trail Log is managed by the network interface process. So, it is this process that has to do the actual changing of the type.

See snmpa:set_log_type/2 for more info.

Link to this callback

set_request_limit(Pid, NewLimit)

View Source

-callback set_request_limit(Pid, NewLimit) -> {ok, OldLimit}
                     when
                         Pid :: pid(),
                         NewLimit :: non_neg_integer() | infinity,
                         OldLimit :: non_neg_integer() | infinity.

Link to this callback

start_link(Prio, NoteStore, MasterAgent, Opts)

View Source

-callback start_link(Prio, NoteStore, MasterAgent, Opts) -> {ok, Pid} | {error, Reason}
              when
                  Prio :: low | normal | high,
                  NoteStore :: pid(),
                  MasterAgent :: pid(),
                  Opts :: [Option],
                  Option :: {verbosity, snmp:verbosity()} | {versions, [snmp:version()]} | term(),
                  Pid :: pid(),
                  Reason :: term().

Start-link the network interface process.

NoteStore is the pid of the note-store process and MasterAgent is the pid of the master-agent process.

Opts is an (basically) implementation dependent list of options to the network interface process. There are however a number of options which must be handled: versions and verbosity.

Link to this callback

verbosity(Pid, Verbosity)

View Source

-callback verbosity(Pid, Verbosity) -> snmp:void() when Pid :: pid(), Verbosity :: snmp:verbosity().

Change the verbosity of a running network interface process.

snmpa_network_interface_filter behaviour

Behaviour module for the SNMP agent network-interface filter.

This module defines the behaviour of the agent network interface filter. A snmpa_network_interface_filter compliant module must export the following functions:

accept_recv/2

accept_send/2

accept_recv_pdu/3

accept_send_pdu/2

The semantics of them and their exact signatures are explained below.

The purpose of the network interface filter is to allow for filtering of messages (accept or reject) receive and send. This is done on two levels:

The first level is at the transport entry / exit point, i.e. immediately after the receipt of the message before any message processing is done (accept_recv) and immediately before sending the message after all message processing is done (accept_send).

The second level is at the MPD entry / exit point, i.e. immediately after the basic message processing (accept_recv_pdu) / immediately before the basic message processing (accept_send_pdu).

Note that the network interface filter is something which is used by the network interface implementation provided by the application (snmpa_net_if). The default filter accepts all messages.

A network interface filter can e.g. be used during testing or for load regulation. If the intended use is load regulation, see also req_limit and the function register_notification_filter.

Legacy network interface filter modules used arguments on the form (IpAddr, PortNumber,...) instead of (Domain, Addr, ...), and if the SNMP agent is run without changing the configuration to use transport domains the network interface filter will still get the old arguments and work as before.

DATA TYPES

port() = integer() > 0
pdu_type() = 'get-request' | 'get-next-request' | 'get-response' |
             'set-request' | trap | 'get-bulk-request' | 'inform-request' |
             report

See also the data types in snmpa_conf.

Summary

Types

pdu_type()

transportAddressWithPort()

transportDomain()

Callbacks

accept_recv(Domain, Addr)

Called at the reception of a message (before any processing has been done).

accept_recv_pdu(Domain, Addr, PduType)

Called after the basic message processing (MPD) has been done, but before the pdu is handed over to the master-agent for primary processing.

accept_send(Domain, Addr)

Called before the sending of a message (after all processing has been done).

accept_send_pdu(Targets, PduType)

Called before the basic message processing (MPD) is done, when a pdu has been received from the master-agent.

Types

Link to this type

pdu_type()

View Source (not exported)

-type pdu_type() :: snmpa:pdu_type().

Link to this type

transportAddressWithPort()

View Source (not exported)

-type transportAddressWithPort() :: snmpa_conf:transportAddressWithPort().

Link to this type

transportDomain()

View Source (not exported)

-type transportDomain() :: snmpa_conf:transportDomain().

Callbacks

Link to this callback

accept_recv(Domain, Addr)

View Source

-callback accept_recv(Domain, Addr) -> boolean()
               when Domain :: transportDomain(), Addr :: transportAddressWithPort().

Called at the reception of a message (before any processing has been done).

For the message to be discarded, the function must return false.

Link to this callback

accept_recv_pdu(Domain, Addr, PduType)

View Source

-callback accept_recv_pdu(Domain, Addr, PduType) -> boolean()
                   when
                       Domain :: transportDomain(),
                       Addr :: transportAddressWithPort(),
                       PduType :: pdu_type().

Called after the basic message processing (MPD) has been done, but before the pdu is handed over to the master-agent for primary processing.

For the pdu to be discarded, the function must return false.

Link to this callback

accept_send(Domain, Addr)

View Source

-callback accept_send(Domain, Addr) -> boolean()
               when Domain :: transportDomain(), Addr :: transportAddressWithPort().

Called before the sending of a message (after all processing has been done).

For the message to be discarded, the function must return false.

Link to this callback

accept_send_pdu(Targets, PduType)

View Source

-callback accept_send_pdu(Targets, PduType) -> Reply
                   when
                       Targets :: [Target],
                       Target :: {Domain, Addr},
                       Domain :: transportDomain(),
                       Addr :: transportAddressWithPort(),
                       PduType :: pdu_type(),
                       Reply :: boolean() | NewTargets,
                       NewTargets :: Targets.

Called before the basic message processing (MPD) is done, when a pdu has been received from the master-agent.

For the message to be discarded all together, the function must return false.

Note that it is possible for this function to filter out targets (but not to add its own) by returning an updated Targets list (NewTargets).

snmpa_notification_delivery_info_receiver behaviour

Behaviour module for the SNMP agent notification delivery information receiver.

This module defines the behaviour of the notification delivery information receiver.

A snmpa_notification_delivery_info_receiver compliant module must export the following functions:

delivery_targets/3

delivery_info/4

The semantics of them and their exact signatures are explained below.

Legacy notification delivery information receiver modules used a target argument on the form {IpAddr, PortNumber} instead of {Domain, Addr}, and if the SNMP Agent is run without changing the configuration to use transport domains the notification delivery information receiver will still get the old arguments and work as before.

DATA TYPES

See the transportDomain() and transportAddressWithPort() for more info.

Summary

Types

notification_delivery_info()

How shall (notification) delivery info be reported.

transportAddressWithPort()

transportDomain()

Callbacks

delivery_info(Tag, Targets, DeliveryResult, Extra)

Inform about delivery result.

delivery_targets(Tag, Targets, Extra)

Inform about target addresses.

Types

Link to this type

notification_delivery_info()

View Source

-type notification_delivery_info() ::
    #snmpa_notification_delivery_info{tag :: term(), mod :: term(), extra :: term()}.

How shall (notification) delivery info be reported.

This record defines the info related to inform delivery info. That is, when sending an inform, info about the delivery (such if it was acknowledged) will be delivered using the info in this record.

The delivery will be performed according to:

	Mod:delivery_targets(Tag, Addresses, Extra)
	Mod:delivery_info(Tag, Address, DeliveryResult, Extra)

The Extra is any term, provided by the user.

The fields of this record has the following meaning:

tag = term() - Value selected by the user to identify this sending

mod = module() - A module implementing the snmpa_notification_delivery_info_receiver behaviour.

extra = term() - This is any extra info the user wants to have supplied when the functions in the callback module is called. Provided when calling the send function.

Link to this type

transportAddressWithPort()

View Source (not exported)

-type transportAddressWithPort() :: snmpa_conf:transportAddressWithPort().

Link to this type

transportDomain()

View Source (not exported)

-type transportDomain() :: snmpa_conf:transportDomain().

Callbacks

Link to this callback

delivery_info(Tag, Targets, DeliveryResult, Extra)

View Source

-callback delivery_info(Tag, Targets, DeliveryResult, Extra) -> snmp:void()
                 when
                     Tag :: term(),
                     Targets :: [Target],
                     Target :: {transportDomain(), transportAddressWithPort()},
                     DeliveryResult :: no_response | got_response,
                     Extra :: term().

Inform about delivery result.

This function is called for each target in the Targets argument of the delivery_targets/3 function, see above.

The purpose is to inform the receiver of the result of the delivery (was the notification acknowledged or not) for each target.

Link to this callback

delivery_targets(Tag, Targets, Extra)

View Source

-callback delivery_targets(Tag, Targets, Extra) -> snmp:void()
                    when
                        Tag :: term(),
                        Targets :: [Target],
                        Target :: {transportDomain(), transportAddressWithPort()},
                        Extra :: term().

Inform about target addresses.

This is the first function called when a notification delivery is in progress. It informs the receiver which targets will get the notification. The result of the delivery will be provided via successive calls to delivery_info/4 function, see below.

snmpa_notification_filter behaviour

Behaviour module for the SNMP agent notification filters.

This module defines the behaviour of the agent notification filters. A snmpa_notification_filter compliant module must export the following functions:

handle_notification/2

The semantics of them and their exact signatures are explained below.

The purpose of notification filters is to allow for modification and/or suppression of a notification.

A misbehaving filter will be removed.

Summary

Types

notification()

trap()

Callbacks

handle_notification(Notif, Data)

Handle a notification to be sent. The filter can either accept the notification as is, return send, modify the notification, return {send, NewNotif} or suppress the notification, return dont_send.

Types

Link to this type

notification()

View Source (not exported)

-type notification() :: term().

Link to this type

trap()

View Source (not exported)

-type trap() :: term().

Callbacks

Link to this callback

handle_notification(Notif, Data)

View Source

-callback handle_notification(Notif, Data) -> Reply
                       when
                           Reply :: send | {send, NewNotif} | dont_send,
                           Notif :: notification() | trap(),
                           NewNotif :: notification() | trap(),
                           Data :: term().

Handle a notification to be sent. The filter can either accept the notification as is, return send, modify the notification, return {send, NewNotif} or suppress the notification, return dont_send.

Data is supplied at filter registration time, see snmpa:register_notification_filter/5.

snmpa_supervisor

A supervisor for the SNMP agent Processes

This is the top supervisor for the agent part of the SNMP application. There is always one supervisor at each node with an SNMP agent (master agent or sub-agent).

Summary

Functions

start_master_sup(Opts)

Starts a supervisor for the SNMP agent system. The supervisor starts all involved SNMP processes, including the master agent. Sub-agents should be started by calling start_subagent/3.

start_sub_agent(ParentAgent, Subtree, Mibs)

Starts a sub-agent on the node where the function is called. The snmpa_supervisor must be running.

start_sub_sup(Opts)

Starts a supervisor for the SNMP agent system without a master agent. The supervisor starts all involved SNMP agent processes, but no agent processes. Sub-agents should be started by calling start_sub_agent/3.

stop_sub_agent(SubAgentPid)

Stops the sub-agent on the node where the function is called. The snmpa_supervisor must be running.

Functions

Link to this function

start_master_sup(Opts)

View Source

-spec start_master_sup(Opts) -> {ok, Pid} | {error, Reason}
                    when
                        Opts :: [Opt],
                        Opt :: {db_dir, string()} | {config, ConfOpts} | {atom(), term()},
                        ConfOpts :: [ConfOpt],
                        ConfOpt :: {dir, string()} | {atom(), term()},
                        Pid :: pid(),
                        Reason :: {already_started, Pid} | term().

Starts a supervisor for the SNMP agent system. The supervisor starts all involved SNMP processes, including the master agent. Sub-agents should be started by calling start_subagent/3.

db_dir is mandatory.

dir in config is mandatory.

See snmp config for a description of the options.

Link to this function

start_sub_agent(ParentAgent, Subtree, Mibs)

View Source

-spec start_sub_agent(ParentAgent, Subtree, Mibs) -> {ok, Pid} | {error, Reason}
                   when
                       ParentAgent :: pid(),
                       Subtree :: snmp:oid(),
                       Mibs :: [MibName],
                       MibName :: string(),
                       Pid :: pid(),
                       Reason :: term().

Starts a sub-agent on the node where the function is called. The snmpa_supervisor must be running.

If the supervisor is not running, the function fails with the reason badarg.

Link to this function

start_sub_sup(Opts)

View Source

-spec start_sub_sup(Opts) -> {ok, Pid} | {error, Reason}
                 when
                     Opts :: [Opt],
                     Opt :: {db_dir, snmp:dir()} | {atom(), term()},
                     Pid :: pid(),
                     Reason :: {already_started, Pid} | term().

Starts a supervisor for the SNMP agent system without a master agent. The supervisor starts all involved SNMP agent processes, but no agent processes. Sub-agents should be started by calling start_sub_agent/3.

db_dir is mandatory.

See configuration parameters for a description of the options.

Link to this function

stop_sub_agent(SubAgentPid)

View Source

-spec stop_sub_agent(SubAgentPid) -> ok | no_such_child when SubAgentPid :: pid().

Stops the sub-agent on the node where the function is called. The snmpa_supervisor must be running.

If the supervisor is not running, the function fails with the reason badarg.

snmpc

Interface Functions to the SNMP toolkit MIB compiler

The module snmpc contains interface functions to the SNMP toolkit MIB compiler.

See Also

erlc(1)

snmpc(command)

Summary

Functions

compile/1

Equivalent to compile/2.

compile(FileName, Options)

Compiles the specified MIB file <FileName>.mib. The compiled file BinFileName is called <FileName>.bin.

is_consistent(FileNames)

Checks for multiple usage of object identifiers and traps between MIBs.

mib_to_hrl(MibName)

Generates a .hrl file with definitions of Erlang constants for the objects in the MIB. The .hrl file is called <MibName>.hrl. The MIB must be compiled, and present in the current directory.

Functions

Link to this function

compile/1

View Source

-spec compile([AtomFileName]) -> {ok, BinFileName} | {error, Reason}
           when AtomFileName :: atom(), BinFileName :: string(), Reason :: term();
       (FileName) -> {ok, BinFileName} | {error, Reason}
           when FileName :: string(), BinFileName :: string(), Reason :: term().

Equivalent to compile/2.

Link to this function

compile(FileName, Options)

View Source

-spec compile(FileName, Options) -> {ok, BinFileName} | {error, Reason}
           when
               FileName :: string(),
               Options :: [Option],
               Option ::
                   agent_capabilities |
                   {db, volatile | persistent | mnesia} |
                   {deprecated, boolean()} |
                   description |
                   {group_check, boolean()} |
                   {i, [snmp:dir()]} |
                   {il, [snmp:dir()]} |
                   imports |
                   {module, module()} |
                   module_identity | module_compliance | no_defs |
                   {outdir, snmp:dir()} |
                   reference | relaxed_row_name_assign_check |
                   {verbosity, snmp:verbosity()} |
                   {warnings, boolean()} |
                   {warnings_as_errors, boolean()},
               BinFileName :: string(),
               Reason :: term().

Compiles the specified MIB file <FileName>.mib. The compiled file BinFileName is called <FileName>.bin.

The option agent_capabilities, if present, specifies that the AGENT-CAPABILITIES statement of the MIB shall be included (with a mib-entry record) in the compiled mib. The mib-entry record of the agent-capabilitie will contain reference and modules part(s) this info in the assocList field).

The option db specifies which database should be used for the default instrumentation.

Default is volatile.

The option deprecated specifies if a deprecated definition should be kept or not. If the option is false the MIB compiler will ignore all deprecated definitions.

Default is true.

The option description specifies if the text of the DESCRIPTION field will be included or not.

By default it is not included, but if this option is present it will be.

The option group_check specifies whether the mib compiler should check the OBJECT-GROUP macro and the NOTIFICATION-GROUP macro for correctness or not.

Default is true.

The option i specifies the path to search for imported (compiled) MIB files. The directories should be strings with a trailing directory delimiter.

Default is ["./"].

The option il (include_lib) also specifies a list of directories to search for imported MIBs. It assumes that the first element in the directory name corresponds to an OTP application. The compiler will find the current installed version. For example, the value ["snmp/mibs/"] will be replaced by ["snmp-3.1.1/mibs/"] (or what the current version may be in the system). The current directory and the <snmp-home>/priv/mibs/ are always listed last in the include path.

The option imports, if present, specifies that the IMPORT statement of the MIB shall be included in the compiled mib.

The option module, if present, specifies the name of a module which implements all instrumentation functions for the MIB.

The name of all instrumentation functions must be the same as the corresponding managed object it implements.

The option module_identity, if present, specifies that the info part of the MODULE-IDENTITY statement of the MIB shall be included in the compiled mib.

The option module_compliance, if present, specifies that the MODULE-COMPLIANCE statement of the MIB shall be included (with a mib-entry record) in the compiled mib. The mib-entry record of the module-compliance will contain reference and module part(s) this info in the assocList field).

The option no_defs, if present, specifies that if a managed object does not have an instrumentation function, the default instrumentation function should NOT be used, instead this is reported as an error, and the compilation aborts.

The option reference specifies if the text of the REFERENCE field, when found in a table definition, will be included or not.

By default it is not included, but if this option is present it will be. The reference text will be placed in the allocList field of the mib-entry record (#me{}) for the table.

The option relaxed_row_name_assign_check, if present, specifies that the row name assign check shall not be done strictly according to the SMI (which allows only the value 1). With this option, all values greater than zero is allowed (>= 1). This means that the error will be converted to a warning.

By default it is not included, but if this option is present it will be.

The option verbosity specifies the verbosity of the SNMP mib compiler. I.e. if warning, info, log, debug and trace messages shall be shown.

Default is silence.

Note that if the option warnings is true and the option verbosity is silence, warning messages will still be shown.

The option warnings specifies whether warning messages should be shown.

Default is true.

The option warnings_as_errors, if present, specifies whether warnings should be treated as errors.

The MIB compiler understands both SMIv1 and SMIv2 MIBs. It uses the MODULE-IDENTITY statement to determine if the MIB is version 1 or 2.

The MIB compiler can also be invoked from the OS command line by these two commands; erlc and snmpc.

erlc - erlc recognizes the extension .mib, and invokes the SNMP MIB compiler for files with that extension. The options db, group_check, deprecated, description, verbosity, imports and module_identity have to be specified to erlc using the syntax +term.

See erlc(1) for details.

snmpc - snmpc is an escript that provides a more traditional interface to the MIB compiler.

See snmpc(command) for details.

Link to this function

is_consistent(FileNames)

View Source

-spec is_consistent(FileNames) -> ok | {error, Reason}
                 when FileNames :: [MibName], MibName :: string(), Reason :: term().

Checks for multiple usage of object identifiers and traps between MIBs.

Link to this function

mib_to_hrl(MibName)

View Source

Generates a .hrl file with definitions of Erlang constants for the objects in the MIB. The .hrl file is called <MibName>.hrl. The MIB must be compiled, and present in the current directory.

The mib_to_hrl generator can be invoked from the OS command line by using the command erlc. erlc recognizes the extension .bin, and invokes this function for files with that extension.

snmpm

Interface functions to the SNMP toolkit manager

The module snmpm contains interface functions to the SNMP manager.

Summary

Types

agent_config()

agent_config_item()

Value type depend on the item according to

pdu_type()

register_timeout()

The time to complete a (agent) registration.

request_id()

Is a unique term that identifies a request.

snmp_reply()

snmpm_user()

Module implementing the snmpm_user behaviour.

target_name()

Is a unique non-empty string.

user_id()

Is a unique term that identifies a user.

usm_config_item()

Value type depend on the item according to

value_type()

o - 'OBJECT IDENTIFIER'

var_and_val()

Functions

agent_info(TargetName, Item)

Retrieve agent config.

async_get2(UserId, TargetName, Oids)

Equivalent to async_get2/4.

async_get2(UserId, TargetName, Oids, SendOpts)

Asynchronous get-request.

async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids)

Equivalent to async_get_bulk2/6.

async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts)

Asynchronous get-bulk-request (See RFC1905).

async_get_next2(UserId, TargetName, Oids)

Equivalent to async_get_next2/4.

async_get_next2(UserId, TargetName, Oids, SendOpts)

Asynchronous get-next-request.

async_set2(UserId, TargetName, VarsAndVals)

Equivalent to async_set2/4.

async_set2(UserId, TargetName, VarsAndVals, SendOpts)

Asynchronous set-request.

backup(BackupDir)

Backup persistent data handled by the manager.

cancel_async_request(UserId, ReqId)

Cancel a previous asynchronous request.

cancel_notify_started(Pid)

Cancel a previous request to be notified of SNMP manager start.

change_log_size(NewSize)

Changes the log size of the Audit Trail Log. The application must be configured to use the audit trail log function. Please refer to disk_log(3) in Kernel Reference Manual for a description of how to change the log size.

demonitor(Ref)

Turn off monitoring of the SNMP manager.

format_reason(Reason)

Equivalent to format_reason/2.

format_reason(Prefix, Reason)

This utility function is used to create a formatted (pretty printable) string of the error reason received from either

info()

Returns a list (a dictionary) containing information about the manager. Information includes statistics counters, miscellaneous info about each process (e.g. memory allocation), and so on.

load_mib(MibName)

Load a Mib into the manager. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

log_to_io(LogDir)

Equivalent to log_to_io/7.

log_to_io/2

Equivalent to log_to_io/7.

log_to_io/3

Equivalent to log_to_io/7.

log_to_io/4

Equivalent to log_to_io/7.

log_to_io/5

Equivalent to log_to_io/7.

log_to_io/6

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable format and prints it on stdio. LogName defaults to "snmpm_log". LogFile defaults to "snmpm.log".

log_to_txt(LogDir)

Equivalent to log_to_txt/8.

log_to_txt/2

Equivalent to log_to_txt/8.

log_to_txt/3

Equivalent to log_to_txt/8.

log_to_txt/4

Equivalent to log_to_txt/8.

log_to_txt/5

Equivalent to log_to_txt/8.

log_to_txt/6

Equivalent to log_to_txt/8.

log_to_txt/7

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}

monitor()

Monitor the SNMP manager. In case of a crash, the calling (monitoring) process will get a 'DOWN' message (see the erlang module for more info).

name_to_oid(AliasName)

Transform a alias-name to its oid.

notify_started(Timeout)

Request a notification (message) when the SNMP manager has started.

oid_to_name(OID)

Transform a oid to its aliasname.

oid_to_type(OID)

Retrieve the type (asn1 bertype) of an oid.

register_agent(UserId, TargetName, Config)

Explicitly instruct the manager to handle this agent, with UserId as the responsible user.

register_user(UserId, Module, Data)

Equivalent to register_user/4.

register_user(UserId, Module, Data, DefaultAgentConfig)

Register the manager entity (=user) responsible for specific agent(s).

register_user_monitor(UserId, Module, Data)

Equivalent to register_user_monitor/4.

register_user_monitor(UserId, Module, Data, DefaultAgentConfig)

Register the monitored manager entity (=user) responsible for specific agent(s).

register_usm_user(EngineID, UserName, Config)

Explicitly instruct the manager to handle this USM user. Note that there is an alternate way to do the same thing: Add the usm user to the manager config files (see usm.conf).

restart(What)

Restart the indicated process (What). Note that its not without risk to restart a process, and should therefore be used with care.

set_log_type(NewType)

Changes the run-time Audit Trail log type.

sync_get2(UserId, TargetName, Oids)

Equivalent to sync_get2/4.

sync_get2(UserId, TargetName, Oids, SendOpts)

Synchronous get-request.

sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids)

Equivalent to sync_get_bulk2/6.

sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts)

Synchronous get-bulk-request (See RFC1905).

sync_get_next2(UserId, TargetName, Oids)

Equivalent to sync_get_next2/4.

sync_get_next2(UserId, TargetName, Oids, SendOpts)

Synchronous get-next-request.

sync_set2(UserId, TargetName, VarsAndVals)

Equivalent to sync_set2/4.

sync_set2(UserId, TargetName, VarsAndVals, SendOpts)

Synchronous set-request.

unload_mib(MibName)

Unload a Mib from the manager. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

unregister_agent(UserId, TargetName)

Unregister the agent.

unregister_user(UserId)

Unregister the user.

unregister_usm_user(EngineID, UserName)

Unregister this USM user.

update_agent_info(UserId, TargetName, Info)

Update agent config.

update_agent_info(UserId, TargetName, Item, Value)

Update agent config.

update_usm_user_info(EngineID, UserName, Item, Value)

Update usm user config.

usm_user_info(EngineID, UserName, Item)

Retrieve usm user config.

verbosity(Target, Verbosity)

Sets verbosity for the designated process. For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

which_agents()

Equivalent to which_agents/1.

which_agents(UserId)

Get a list of all registered agents or all agents registered by a specific user.

which_mibs()

Get a list of all the mib's loaded into the manager.

which_users()

Get a list of the identities of all registered users.

which_usm_users()

Get a list of all registered usm users.

which_usm_users(EngineID)

Get a list of all registered usm users with engine-id EngineID.

Types

Link to this type

agent_config()

View Source

-type agent_config() ::
    {engine_id, snmp:engine_id()} |
    {address, inet:ip_address()} |
    {port, inet:port_number()} |
    {tdomain, snmp:tdomain()} |
    {community, snmp:community()} |
    {timeout, register_timeout()} |
    {max_message_size, snmp:mms()} |
    {version, snmp:version()} |
    {sec_model, snmp:sec_model()} |
    {sec_name, snmp:sec_name()} |
    {sec_level, snmp:sec_level()}.

Link to this type

agent_config_item()

View Source

-type agent_config_item() ::
    engine_id | address | port | tdomain | community | timeout | max_message_size | version |
    sec_model | sec_name | sec_level.

Value type depend on the item according to:

engine_id - Engine ID of the agent.

Value type: engine_id()

address - The IP address of the agent.

Value type: ip_address()

port - Port number of the agent.

Value type: port_number()

tdomain - Transport domain.

Value type: tdomain()

community - Community.

Value type: community()

timeout - Registration timeout.

Value type: register_timeout/0

max_message_size - Max Message Size of a message.

Value type: mms()

version - What SNMP version is used when communicating with this agent.

Value type: version()

sec_model - Security Model.

Value type: sec_model()

sec_name - Security Name.

Value type: sec_name()

sec_level - Security Level.

Value type: sec_level()

Link to this type

pdu_type()

View Source

-type pdu_type() :: snmp:pdu_type() | trappdu.

Link to this type

register_timeout()

View Source

-type register_timeout() :: pos_integer() | snmp:snmp_timer().

The time to complete a (agent) registration.

Link to this opaque

request_id()

View Source

-opaque request_id()

Is a unique term that identifies a request.

Link to this type

snmp_reply()

View Source

-type snmp_reply() :: {snmp:error_status(), snmp:error_index(), [snmp:varbind()]}.

Link to this type

snmpm_user()

View Source

-type snmpm_user() :: module().

Module implementing the snmpm_user behaviour.

Link to this type

target_name()

View Source

-type target_name() :: string().

Is a unique non-empty string.

Link to this type

user_id()

View Source

-type user_id() :: term().

Is a unique term that identifies a user.

Link to this type

usm_config_item()

View Source

-type usm_config_item() :: sec_name | auth | auth_key | priv | priv_key.

Value type depend on the item according to:

sec_name - Security Name.

Value type: sec_name()

auth - The IP address of the agent.

Value type: snmp:usm_auth_protocol/0

auth_key - Port number of the agent.

Value type: snmp:usm_auth_key/0

priv - Value type: snmp:usm_priv_protocol/0

priv_key - Value type: snmp:usm_priv_key/0

Link to this type

value_type()

View Source

-type value_type() :: o | i | u | g | s | s | b | ip | op | c32 | c64 | tt.

o - 'OBJECT IDENTIFIER'

i - 'INTEGER'

u - 'Unsigned32

g - 'Unsigned32'

s - 'OCTET STRING'

b - 'BITS'

ip - 'IpAddress'

op - 'Opaque'

c32 - 'Counter32'

c64 - 'Counter64'

tt - 'TimeTicks'

Link to this type

var_and_val()

View Source

-type var_and_val() ::
    {OID :: snmp:oid(), ValueType :: value_type(), Value :: term()} |
    {OID :: snmp:oid(), Value :: term()}.

Functions

Link to this function

agent_info(TargetName, Item)

View Source

-spec agent_info(TargetName, Item) -> {ok, Value} | {error, Reason}
              when
                  TargetName :: target_name(),
                  Item :: agent_config_item(),
                  Value :: term(),
                  Reason :: term().

Retrieve agent config.

Link to this function

async_get2(UserId, TargetName, Oids)

View Source (since OTP R14B03)

-spec async_get2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
              when
                  UserId :: user_id(),
                  TargetName :: target_name(),
                  Oids :: [snmp:oid()],
                  ReqId :: request_id(),
                  Reason :: term().

Equivalent to async_get2/4.

Link to this function

async_get2(UserId, TargetName, Oids, SendOpts)

View Source (since OTP R14B03)

-spec async_get2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}
              when
                  UserId :: user_id(),
                  TargetName :: target_name(),
                  Oids :: [snmp:oid()],
                  SendOpts :: [SendOpt],
                  SendOpt ::
                      {context, snmp:context_name()} |
                      {timeout, pos_integer()} |
                      {community, snmp:community()} |
                      {sec_model, snmp:sec_model()} |
                      {sec_name, snmp:sec_name()} |
                      {sec_level, snmp:sec_level()} |
                      {max_message_size, snmp:mms()} |
                      {extra, term()},
                  ReqId :: request_id(),
                  Reason :: term().

Asynchronous get-request.

The reply, if it arrives, will be delivered to the user through a call to the snmpm_user callback function handle_pdu.

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

Link to this function

async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids)

View Source (since OTP R14B03)

-spec async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId} | {error, Reason}
                   when
                       UserId :: user_id(),
                       TargetName :: target_name(),
                       NonRep :: non_neg_integer(),
                       MaxRep :: non_neg_integer(),
                       Oids :: [snmp:oid()],
                       ReqId :: request_id(),
                       Reason :: term().

Equivalent to async_get_bulk2/6.

Link to this function

async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts)

View Source (since OTP R14B03)

-spec async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts) ->
                   {ok, ReqId} | {error, Reason}
                   when
                       UserId :: user_id(),
                       TargetName :: target_name(),
                       NonRep :: non_neg_integer(),
                       MaxRep :: non_neg_integer(),
                       Oids :: [snmp:oid()],
                       SendOpts :: [SendOpt],
                       SendOpt ::
                           {context, snmp:context_name()} |
                           {timeout, pos_integer()} |
                           {community, snmp:community()} |
                           {sec_model, snmp:sec_model()} |
                           {sec_name, snmp:sec_name()} |
                           {sec_level, snmp:sec_level()} |
                           {max_message_size, snmp:mms()} |
                           {extra, term()},
                       ReqId :: request_id(),
                       Reason :: term().

Asynchronous get-bulk-request (See RFC1905).

The reply, if it arrives, will be delivered to the user through a call to the snmpm_user callback function handle_pdu.

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes no use of this info, so the only use for it in such a configuration (when using the built in net-if) would be tracing.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

Link to this function

async_get_next2(UserId, TargetName, Oids)

View Source (since OTP R14B03)

-spec async_get_next2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
                   when
                       UserId :: user_id(),
                       TargetName :: target_name(),
                       Oids :: [snmp:oid()],
                       ReqId :: request_id(),
                       Reason :: term().

Equivalent to async_get_next2/4.

Link to this function

async_get_next2(UserId, TargetName, Oids, SendOpts)

View Source (since OTP R14B03)

-spec async_get_next2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}
                   when
                       UserId :: user_id(),
                       TargetName :: target_name(),
                       Oids :: [snmp:oid()],
                       SendOpts :: [SendOpt],
                       SendOpt ::
                           {context, snmp:context_name()} |
                           {timeout, pos_integer()} |
                           {community, snmp:community()} |
                           {sec_model, snmp:sec_model()} |
                           {sec_name, snmp:sec_name()} |
                           {sec_level, snmp:sec_level()} |
                           {max_message_size, snmp:mms()} |
                           {extra, term()},
                       ReqId :: request_id(),
                       Reason :: term().

Asynchronous get-next-request.

The reply, if it arrives, will be delivered to the user through a call to the snmpm_user callback function handle_pdu.

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

Link to this function

async_set2(UserId, TargetName, VarsAndVals)

View Source (since OTP R14B03)

-spec async_set2(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error, Reason}
              when
                  UserId :: user_id(),
                  TargetName :: target_name(),
                  VarsAndVals :: [var_and_val()],
                  ReqId :: request_id(),
                  Reason :: term().

Equivalent to async_set2/4.

Link to this function

async_set2(UserId, TargetName, VarsAndVals, SendOpts)

View Source (since OTP R14B03)

-spec async_set2(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, ReqId} | {error, Reason}
              when
                  UserId :: user_id(),
                  TargetName :: target_name(),
                  VarsAndVals :: [var_and_val()],
                  SendOpts :: [SendOpt],
                  SendOpt ::
                      {context, snmp:context_name()} |
                      {timeout, pos_integer()} |
                      {community, snmp:community()} |
                      {sec_model, snmp:sec_model()} |
                      {sec_name, snmp:sec_name()} |
                      {sec_level, snmp:sec_level()} |
                      {max_message_size, snmp:mms()} |
                      {extra, term()},
                  ReqId :: request_id(),
                  Reason :: term().

Asynchronous set-request.

The reply will be delivered to the user through a call to the snmpm_user callback function handle_pdu.

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

When var_and_val() is {oid(), value()}, the manager makes an educated guess based on the loaded mibs.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

Link to this function

backup(BackupDir)

View Source

-spec backup(BackupDir) -> ok | {error, Reason} when BackupDir :: snmp:dir(), Reason :: term().

Backup persistent data handled by the manager.

BackupDir cannot be identical to DbDir.

Link to this function

cancel_async_request(UserId, ReqId)

View Source

-spec cancel_async_request(UserId, ReqId) -> ok | {error, Reason}
                        when UserId :: user_id(), ReqId :: request_id(), Reason :: term().

Cancel a previous asynchronous request.

Link to this function

cancel_notify_started(Pid)

View Source

-spec cancel_notify_started(Pid) -> snmp:void() when Pid :: pid().

Cancel a previous request to be notified of SNMP manager start.

Link to this function

change_log_size(NewSize)

View Source

-spec change_log_size(NewSize) -> ok | {error, Reason} when NewSize :: snmp:log_size(), Reason :: term().

Changes the log size of the Audit Trail Log. The application must be configured to use the audit trail log function. Please refer to disk_log(3) in Kernel Reference Manual for a description of how to change the log size.

The change is permanent, as long as the log is not deleted. That means, the log size is remembered across reboots.

Link to this function

demonitor(Ref)

View Source

-spec demonitor(Ref) -> true when Ref :: reference().

Turn off monitoring of the SNMP manager.

Link to this function

format_reason(Reason)

View Source

-spec format_reason(Reason) -> FReason when Reason :: term(), FReason :: string().

Equivalent to format_reason/2.

Link to this function

format_reason(Prefix, Reason)

View Source

-spec format_reason(Prefix, Reason) -> FReason
                 when
                     Prefix :: non_neg_integer() | string(), Reason :: term(), FReason :: string().

This utility function is used to create a formatted (pretty printable) string of the error reason received from either:

The Reason returned value if any of the sync/async get/get-next/set/get-bulk functions returns {error, Reason}

The Reason parameter in the handle_error user callback function.

Prefix should either be an indentation string (e.g. a list of spaces) or a positive integer (which will be used to create the indentation string of that length).

Link to this function

info()

View Source

-spec info() -> [{Key, Value}] when Key :: atom(), Value :: term().

Returns a list (a dictionary) containing information about the manager. Information includes statistics counters, miscellaneous info about each process (e.g. memory allocation), and so on.

Link to this function

load_mib(MibName)

View Source

-spec load_mib(MibName) -> ok | {error, Reason} when MibName :: snmp:mib_name(), Reason :: term().

Load a Mib into the manager. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

          Dir = code:priv_dir(my_app) ++ "/mibs/",
          snmpm:load_mib(Dir ++ "MY-MIB").

Link to this function

log_to_io(LogDir)

View Source (since OTP R15B01)

-spec log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/2

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/3

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/4

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/5

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName, LogFile, Start) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Start :: null | snmp:log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io/6

View Source (since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Start :: null | snmp:log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term();
         (LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Start :: null | snmp:log_time(),
                 Stop :: null | snmp:log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Equivalent to log_to_io/7.

Link to this function

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

View Source (since OTP R16B03)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
             when
                 LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Start :: null | snmp:log_time(),
                 Stop :: null | snmp:log_time(),
                 Cnt :: {NumOK, NumERR},
                 NumOK :: non_neg_integer(),
                 NumERR :: pos_integer(),
                 Reason :: term().

Converts an Audit Trail Log to a readable format and prints it on stdio. LogName defaults to "snmpm_log". LogFile defaults to "snmpm.log".

The Block argument indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

See snmp:log_to_io for more info.

Link to this function

log_to_txt(LogDir)

View Source (since OTP R16B03)

-spec log_to_txt(LogDir :: snmp:dir()) -> snmp:void().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/2

View Source

-spec log_to_txt(LogDir :: snmp:dir(), Block :: boolean()) -> snmp:void();
          (LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()]) -> snmp:void().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/3

View Source

-spec log_to_txt(LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()], Block :: boolean()) -> snmp:void();
          (LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()], OutFile :: file:filename()) ->
              snmp:void().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/4

View Source

-spec log_to_txt(LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           Block :: boolean()) ->
              snmp:void();
          (LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           LogName :: string()) ->
              snmp:void().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/5

View Source

-spec log_to_txt(LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           LogName :: string(),
           Block :: boolean()) ->
              snmp:void();
          (LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           LogName :: string(),
           LogFile :: string()) ->
              snmp:void().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/6

View Source

-spec log_to_txt(LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           LogName :: string(),
           LogFile :: string(),
           Block :: boolean()) ->
              snmp:void();
          (LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           LogName :: string(),
           LogFile :: string(),
           Start :: null | snmp:log_time()) ->
              snmp:void().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt/7

View Source

-spec log_to_txt(LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           LogName :: string(),
           LogFile :: string(),
           Block :: boolean(),
           Start :: null | snmp:log_time()) ->
              snmp:void();
          (LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           LogName :: string(),
           LogFile :: string(),
           Start :: null | snmp:log_time(),
           Stop :: null | snmp:log_time()) ->
              snmp:void().

Equivalent to log_to_txt/8.

Link to this function

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

View Source (since OTP R16B03)

-spec log_to_txt(LogDir :: snmp:dir(),
           Mibs :: [snmp:mib_name()],
           OutFile :: file:filename(),
           LogName :: string(),
           LogFile :: string(),
           Block :: boolean(),
           Start :: snmp:log_time(),
           Stop :: snmp:log_time()) ->
              snmp:void().

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}

Converts an Audit Trail Log to a readable text file. OutFile defaults to "./snmpm_log.txt". LogName defaults to "snmpm_log". LogFile defaults to "snmpm.log".

The Block argument indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

See snmp:log_to_txt for more info.

Link to this function

monitor()

View Source

-spec monitor() -> MRef when MRef :: reference().

Monitor the SNMP manager. In case of a crash, the calling (monitoring) process will get a 'DOWN' message (see the erlang module for more info).

Link to this function

name_to_oid(AliasName)

View Source

-spec name_to_oid(AliasName) -> {ok, OIDs} | {error, Reason}
               when AliasName :: atom(), OIDs :: [snmp:oid()], Reason :: term().

Transform a alias-name to its oid.

Note that an alias-name is only unique within the mib, so when loading several mib's into a manager, there might be several instances of the same aliasname.

Link to this function

notify_started(Timeout)

View Source

-spec notify_started(Timeout) -> Pid when Timeout :: pos_integer(), Pid :: pid().

Request a notification (message) when the SNMP manager has started.

The Timeout is the time the request is valid. The value has to be greater then zero.

The Pid is the process handling the supervision of the SNMP manager start. When the manager has started a completion message will be sent to the client from this process: {snmpm_started, Pid}. If the SNMP manager was not started in time, a timeout message will be sent to the client: {snmpm_start_timeout, Pid}.

A client application that is dependent on the SNMP manager will use this function in order to be notified of when the manager has started. There are two situations when this is useful:

During the start of a system, when a client application could start prior to the SNMP manager but is dependent upon it, and therefore has to wait for it to start.

When the SNMP manager has crashed, the dependent client application has to wait for the SNMP manager to be restarted before it can reconnect.

The function returns the pid() of a handler process, that does the supervision on behalf of the client application. Note that the client application is linked to this handler.

This function is used in conjunction with the monitor function.

Link to this function

oid_to_name(OID)

View Source

-spec oid_to_name(OID) -> {ok, AliasName} | {error, Reason}
               when OID :: snmp:oid(), AliasName :: atom(), Reason :: term().

Transform a oid to its aliasname.

Link to this function

oid_to_type(OID)

View Source

-spec oid_to_type(OID) -> {ok, Type} | {error, Reason}
               when OID :: snmp:oid(), Type :: atom(), Reason :: term().

Retrieve the type (asn1 bertype) of an oid.

Link to this function

register_agent(UserId, TargetName, Config)

View Source

-spec register_agent(UserId, TargetName, Config) -> ok | {error, Reason}
                  when
                      UserId :: user_id(),
                      TargetName :: target_name(),
                      Config :: [ConfigEntry],
                      ConfigEntry :: {Item, Value},
                      Item :: agent_config_item(),
                      Value :: term(),
                      Reason :: term().

Explicitly instruct the manager to handle this agent, with UserId as the responsible user.

Called to instruct the manager that this agent shall be handled. This function is used when the user knows in advance which agents the manager shall handle. Note that there is an alternate way to do the same thing: Add the agent to the manager config files (see agents.conf).

TargetName is a non-empty string, uniquely identifying the agent.

The type of Val depends on Item:

[mandatory] engine_id = engine_id()
[mandatory] address = inet:ip_address()  % Depends on tdomain
[optional]  port = inet:port_number()
[optional]  tdomain = snmp:tdomain()
[optional]  community = snmp:community()
[optional]  timeout = register_timeout()
[optional]  max_message_size = snmp:mms()
[optional]  version = snmp:version()
[optional]  sec_model = snmp:sec_model()
[optional]  sec_name = snmp:sec_name()
[optional]  sec_level = snmp:sec_level()

Note that if no tdomain is given, the default value, transportDomainUdpIpv4, is used.

Note that if no port is given and if taddress does not contain a port number, the default value is used.

Link to this function

register_user(UserId, Module, Data)

View Source

-spec register_user(UserId, Module, Data) -> ok | {error, Reason}
                 when
                     UserId :: user_id(), Module :: snmpm_user(), Data :: term(), Reason :: term().

Equivalent to register_user/4.

Link to this function

register_user(UserId, Module, Data, DefaultAgentConfig)

View Source

-spec register_user(UserId, Module, Data, DefaultAgentConfig) -> ok | {error, Reason}
                 when
                     UserId :: user_id(),
                     Module :: snmpm_user(),
                     Data :: term(),
                     DefaultAgentConfig :: [DefaultConfigEntry],
                     DefaultConfigEntry :: {Item, Value},
                     Item :: agent_config_item(),
                     Value :: term(),
                     Reason :: term().

Register the manager entity (=user) responsible for specific agent(s).

Module is the callback module (snmpm_user behaviour) which will be called whenever something happens (detected agent, incoming reply or incoming trap/notification).

Data is an opaque data structure, not inspected by the manager, that will be included in all callback calls to the Module callback module (snmpm_user behaviour).

The argument DefaultAgentConfig is used as default values when this user register agents.

Note that this operation (register user) could have already been done as a consequence of the node config. (see users.conf).

Link to this function

register_user_monitor(UserId, Module, Data)

View Source

-spec register_user_monitor(UserId, Module, Data) -> ok | {error, Reason}
                         when
                             UserId :: user_id(),
                             Module :: snmpm_user(),
                             Data :: term(),
                             Reason :: term().

Equivalent to register_user_monitor/4.

Link to this function

register_user_monitor(UserId, Module, Data, DefaultAgentConfig)

View Source

-spec register_user_monitor(UserId, Module, Data, DefaultAgentConfig) -> ok | {error, Reason}
                         when
                             UserId :: user_id(),
                             Module :: snmpm_user(),
                             Data :: term(),
                             DefaultAgentConfig :: [DefaultConfigEntry],
                             DefaultConfigEntry :: {Item, Value},
                             Item :: agent_config_item(),
                             Value :: term(),
                             Reason :: term().

Register the monitored manager entity (=user) responsible for specific agent(s).

The process performing the registration will be monitored. Which means that if that process should die, all agents registered by that user process will be unregistered. All outstanding requests will be canceled.

Module is the callback module (snmpm_user behaviour) which will be called whenever something happens (detected agent, incoming reply or incoming trap/notification).

Data is an opaque data structure, not inspected by the manager, that will be included in all callback calls to the Module callback module (snmpm_user behaviour).

The argument DefaultAgentConfig is used as default values when this user register agents.

Link to this function

register_usm_user(EngineID, UserName, Config)

View Source

-spec register_usm_user(EngineID, UserName, Config) -> ok | {error, Reason}
                     when
                         EngineID :: snmp:engine_id(),
                         UserName :: snmp:usm_name(),
                         Config :: [ConfigEntry],
                         ConfigEntry :: {Item, Value},
                         Item :: usm_config_item(),
                         Value :: term(),
                         Reason :: term().

Explicitly instruct the manager to handle this USM user. Note that there is an alternate way to do the same thing: Add the usm user to the manager config files (see usm.conf).

Link to this function

restart(What)

View Source (since OTP 22.3)

-spec restart(What) -> snmp:void() when What :: net_if.

Restart the indicated process (What). Note that its not without risk to restart a process, and should therefore be used with care.

Link to this function

set_log_type(NewType)

View Source

-spec set_log_type(NewType) -> {ok, OldType} | {error, Reason}
                when NewType :: snmp:atl_type(), OldType :: snmp:atl_type(), Reason :: term().

Changes the run-time Audit Trail log type.

Note that this has no effect on the application configuration as defined by configuration files, so a node restart will revert the config to whatever is in those files.

This function is primarily useful in testing/debugging scenarios.

Link to this function

sync_get2(UserId, TargetName, Oids)

View Source (since OTP R14B03)

-spec sync_get2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}
             when
                 UserId :: user_id(),
                 TargetName :: target_name(),
                 Oids :: [snmp:oid()],
                 SnmpReply :: snmp_reply(),
                 Remaining :: non_neg_integer(),
                 Reason ::
                     {send_failed, ReqId, ActualReason} |
                     {invalid_sec_info, SecInfo, SnmpInfo} |
                     term(),
                 ReqId :: request_id(),
                 ActualReason :: term(),
                 SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                 SecTag :: atom(),
                 ExpectedValue :: term(),
                 ReceivedValue :: term(),
                 SnmpInfo :: term().

Equivalent to sync_get2/4.

Link to this function

sync_get2(UserId, TargetName, Oids, SendOpts)

View Source (since OTP R14B03)

-spec sync_get2(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason}
             when
                 UserId :: user_id(),
                 TargetName :: target_name(),
                 Oids :: [snmp:oid()],
                 SendOpts :: [SendOpt],
                 SendOpt ::
                     {context, snmp:context_name()} |
                     {timeout, pos_integer()} |
                     {community, snmp:community()} |
                     {sec_model, snmp:sec_model()} |
                     {sec_name, snmp:sec_name()} |
                     {sec_level, snmp:sec_level()} |
                     {max_message_size, snmp:mms()} |
                     {extra, term()},
                 SnmpReply :: snmp_reply(),
                 Remaining :: non_neg_integer(),
                 Reason ::
                     {send_failed, ReqId, ActualReason} |
                     {invalid_sec_info, SecInfo, SnmpInfo} |
                     term(),
                 ReqId :: request_id(),
                 ActualReason :: term(),
                 SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                 SecTag :: atom(),
                 ExpectedValue :: term(),
                 ReceivedValue :: term(),
                 SnmpInfo :: term().

Synchronous get-request.

Remaining is the remaining time of the given (or default) timeout time.

When Reason is {send_failed, ...} it means that the netif process failed to send the (get-request ) message. This could happen because of any number of reasons, i.e. encoding error. _ActualReason is the actual reason in this case.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

For SnmpInfo, see the user callback function handle_report.

Link to this function

sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids)

View Source (since OTP R14B03)

-spec sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) ->
                  {ok, SnmpReply, Remaining} | {error, Reason}
                  when
                      UserId :: user_id(),
                      TargetName :: target_name(),
                      NonRep :: non_neg_integer(),
                      MaxRep :: non_neg_integer(),
                      Oids :: [snmp:oid()],
                      SnmpReply :: snmp_reply(),
                      Remaining :: non_neg_integer(),
                      Reason ::
                          {send_failed, ReqId, ActualReason} |
                          {invalid_sec_info, SecInfo, SnmpInfo} |
                          term(),
                      ReqId :: request_id(),
                      ActualReason :: term(),
                      SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                      SecTag :: atom(),
                      ExpectedValue :: term(),
                      ReceivedValue :: term(),
                      SnmpInfo :: term().

Equivalent to sync_get_bulk2/6.

Link to this function

sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts)

View Source (since OTP R14B03)

-spec sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts) ->
                  {ok, SnmpReply, Remaining} | {error, Reason}
                  when
                      UserId :: user_id(),
                      TargetName :: target_name(),
                      NonRep :: non_neg_integer(),
                      MaxRep :: non_neg_integer(),
                      Oids :: [snmp:oid()],
                      SendOpts :: [SendOpt],
                      SendOpt ::
                          {context, snmp:context_name()} |
                          {timeout, pos_integer()} |
                          {community, snmp:community()} |
                          {sec_model, snmp:sec_model()} |
                          {sec_name, snmp:sec_name()} |
                          {sec_level, snmp:sec_level()} |
                          {max_message_size, snmp:mms()} |
                          {extra, term()},
                      ReqId :: request_id(),
                      SnmpReply :: snmp_reply(),
                      Remaining :: non_neg_integer(),
                      Reason ::
                          {send_failed, ReqId, ActualReason} |
                          {invalid_sec_info, SecInfo, SnmpInfo} |
                          term(),
                      ReqId :: request_id(),
                      ActualReason :: term(),
                      SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                      SecTag :: atom(),
                      ExpectedValue :: term(),
                      ReceivedValue :: term(),
                      SnmpInfo :: term().

Synchronous get-bulk-request (See RFC1905).

Remaining is the remaining time of the given (or default) timeout time.

When Reason is {send_failed, ...} it means that the netif process failed to send the message. This could happen because of any number of reasons, i.e. encoding error. _ActualReason is the actual reason in this case.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

For SnmpInfo, see the user callback function handle_report.

Link to this function

sync_get_next2(UserId, TargetName, Oids)

View Source (since OTP R14B03)

-spec sync_get_next2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}
                  when
                      UserId :: user_id(),
                      TargetName :: target_name(),
                      Oids :: [snmp:oid()],
                      SnmpReply :: snmp_reply(),
                      Remaining :: non_neg_integer(),
                      Reason ::
                          {send_failed, ReqId, ActualReason} |
                          {invalid_sec_info, SecInfo, SnmpInfo} |
                          term(),
                      ReqId :: request_id(),
                      ActualReason :: term(),
                      SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                      SecTag :: atom(),
                      ExpectedValue :: term(),
                      ReceivedValue :: term(),
                      SnmpInfo :: term().

Equivalent to sync_get_next2/4.

Link to this function

sync_get_next2(UserId, TargetName, Oids, SendOpts)

View Source (since OTP R14B03)

-spec sync_get_next2(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason}
                  when
                      UserId :: user_id(),
                      TargetName :: target_name(),
                      Oids :: [snmp:oid()],
                      SendOpts :: [SendOpt],
                      SendOpt ::
                          {context, snmp:context_name()} |
                          {timeout, pos_integer()} |
                          {community, snmp:community()} |
                          {sec_model, snmp:sec_model()} |
                          {sec_name, snmp:sec_name()} |
                          {sec_level, snmp:sec_level()} |
                          {max_message_size, snmp:mms()} |
                          {extra, term()},
                      SnmpReply :: snmp_reply(),
                      Remaining :: non_neg_integer(),
                      Reason ::
                          {send_failed, ReqId, ActualReason} |
                          {invalid_sec_info, SecInfo, SnmpInfo} |
                          term(),
                      ReqId :: request_id(),
                      ActualReason :: term(),
                      SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                      SecTag :: atom(),
                      ExpectedValue :: term(),
                      ReceivedValue :: term(),
                      SnmpInfo :: term().

Synchronous get-next-request.

Remaining is the remaining time of the given (or default) timeout time.

When Reason is {send_failed, ...} it means that the netif process failed to send the message. This could happen because of any number of reasons, i.e. encoding error. _ActualReason is the actual reason in this case.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

For SnmpInfo, see the user callback function handle_report.

Link to this function

sync_set2(UserId, TargetName, VarsAndVals)

View Source (since OTP R14B03)

-spec sync_set2(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason}
             when
                 UserId :: user_id(),
                 TargetName :: target_name(),
                 VarsAndVals :: [var_and_val()],
                 SnmpReply :: snmp_reply(),
                 Remaining :: non_neg_integer(),
                 Reason ::
                     {send_failed, ReqId, ActualReason} |
                     {invalid_sec_info, SecInfo, SnmpInfo} |
                     term(),
                 ReqId :: request_id(),
                 ActualReason :: term(),
                 SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                 SecTag :: atom(),
                 ExpectedValue :: term(),
                 ReceivedValue :: term(),
                 SnmpInfo :: term().

Equivalent to sync_set2/4.

Link to this function

sync_set2(UserId, TargetName, VarsAndVals, SendOpts)

View Source (since OTP R14B03)

-spec sync_set2(UserId, TargetName, VarsAndVals, SendOpts) ->
             {ok, SnmpReply, Remaining} | {error, Reason}
             when
                 UserId :: user_id(),
                 TargetName :: target_name(),
                 VarsAndVals :: [var_and_val()],
                 SendOpts :: [SendOpt],
                 SendOpt ::
                     {context, snmp:context_name()} |
                     {timeout, pos_integer()} |
                     {community, snmp:community()} |
                     {sec_model, snmp:sec_model()} |
                     {sec_name, snmp:sec_name()} |
                     {sec_level, snmp:sec_level()} |
                     {max_message_size, snmp:mms()} |
                     {extra, term()},
                 SnmpReply :: snmp_reply(),
                 Remaining :: non_neg_integer(),
                 Reason ::
                     {send_failed, ReqId, ActualReason} |
                     {invalid_sec_info, SecInfo, SnmpInfo} |
                     term(),
                 ReqId :: request_id(),
                 ActualReason :: term(),
                 SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                 SecTag :: atom(),
                 ExpectedValue :: term(),
                 ReceivedValue :: term(),
                 SnmpInfo :: term().

Synchronous set-request.

Remaining is the remaining time of the given (or default) timeout time.

When Reason is {send_failed, ...} it means that the netif process failed to send the message. This could happen because of any number of reasons, i.e. encoding error. _ActualReason is the actual reason in this case.

When var_and_val() is {oid(), value()}, the manager makes an educated guess based on the loaded mibs.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

For SnmpInfo, see the user callback function handle_report.

Link to this function

unload_mib(MibName)

View Source

-spec unload_mib(MibName) -> ok | {error, Reason} when MibName :: snmp:mib_name(), Reason :: term().

Unload a Mib from the manager. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

	  Dir = code:priv_dir(my_app) ++ "/mibs/",
          snmpm:unload_mib(Dir ++ "MY-MIB").

Link to this function

unregister_agent(UserId, TargetName)

View Source

-spec unregister_agent(UserId, TargetName) -> ok | {error, Reason}
                    when UserId :: user_id(), TargetName :: target_name(), Reason :: term().

Unregister the agent.

Link to this function

unregister_user(UserId)

View Source

-spec unregister_user(UserId) -> ok | {error, Reason} when UserId :: user_id(), Reason :: term().

Unregister the user.

Link to this function

unregister_usm_user(EngineID, UserName)

View Source

-spec unregister_usm_user(EngineID, UserName) -> ok | {error, Reason}
                       when
                           EngineID :: snmp:engine_id(),
                           UserName :: snmp:usm_name(),
                           Reason :: term().

Unregister this USM user.

Link to this function

update_agent_info(UserId, TargetName, Info)

View Source (since OTP R14B04)

-spec update_agent_info(UserId, TargetName, Info) -> ok | {error, Reason}
                     when
                         UserId :: user_id(),
                         TargetName :: target_name(),
                         Info :: [{Item, Value}],
                         Item :: agent_config_item(),
                         Value :: term(),
                         Reason :: term().

Update agent config.

This function, update_agent_info/3, should be used when several values needs to be updated atomically.

See function register_agent/3 for more info about what kind of items are allowed.

Link to this function

update_agent_info(UserId, TargetName, Item, Value)

View Source

-spec update_agent_info(UserId, TargetName, Item, Value) -> ok | {error, Reason}
                     when
                         UserId :: user_id(),
                         TargetName :: target_name(),
                         Item :: agent_config_item(),
                         Value :: term(),
                         Reason :: term().

Update agent config.

See function register_agent/3 for more info about what kind of items are allowed.

Link to this function

update_usm_user_info(EngineID, UserName, Item, Value)

View Source

-spec update_usm_user_info(EngineID, UserName, Item, Value) -> ok | {error, Reason}
                        when
                            EngineID :: snmp:engine_id(),
                            UserName :: snmp:usm_name(),
                            Item :: usm_config_item(),
                            Value :: term(),
                            Reason :: term().

Update usm user config.

Link to this function

usm_user_info(EngineID, UserName, Item)

View Source

-spec usm_user_info(EngineID, UserName, Item) -> {ok, Value} | {error, Reason}
                 when
                     EngineID :: snmp:engine_id(),
                     UserName :: snmp:usm_name(),
                     Item :: usm_config_item(),
                     Value :: term(),
                     Reason :: term().

Retrieve usm user config.

Link to this function

verbosity(Target, Verbosity)

View Source

-spec verbosity(Target, Verbosity) -> snmp:void()
             when
                 Target :: config | server | net_if | note_store | all,
                 Verbosity :: snmp:verbosity().

Sets verbosity for the designated process. For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

Link to this function

which_agents()

View Source

-spec which_agents() -> Agents when Agents :: [target_name()].

Equivalent to which_agents/1.

Link to this function

which_agents(UserId)

View Source

-spec which_agents(UserId) -> Agents when UserId :: user_id(), Agents :: [target_name()].

Get a list of all registered agents or all agents registered by a specific user.

Link to this function

which_mibs()

View Source

-spec which_mibs() -> Mibs
              when Mibs :: [{MibName, MibFile}], MibName :: snmp:mib_name(), MibFile :: string().

Get a list of all the mib's loaded into the manager.

Link to this function

which_users()

View Source

-spec which_users() -> Users when Users :: [user_id()].

Get a list of the identities of all registered users.

Link to this function

which_usm_users()

View Source

-spec which_usm_users() -> UsmUsers
                   when
                       UsmUsers :: [{EngineID, UserName}],
                       EngineID :: snmp:engine_id(),
                       UserName :: snmp:usm_name().

Get a list of all registered usm users.

Link to this function

which_usm_users(EngineID)

View Source

-spec which_usm_users(EngineID) -> UsmUsers
                   when
                       EngineID :: snmp:engine_id(),
                       UsmUsers :: [UserName],
                       UserName :: snmp:usm_name().

Get a list of all registered usm users with engine-id EngineID.

snmpm_conf

Utility functions for handling the manager config files.

The module snmpm_conf contains various utility functions to used for manipulating (write/append/read) the config files of the SNMP manager.

Summary

Types

agent_entry()

An opaque data structure containg all configuration for one agent for the manager.

manager_entry()

An opaque data structure that represents one configuration entry for the manager.

user_entry()

An opaque data structure containg all configuration for one user for the manager.

usm_entry()

An opaque data structure containg information about security data for usm for the manager.

Functions

agents_entry/12

Create an entry for the manager agents config file, agents.conf.

append_agents_config(Dir, Conf)

Append the agents config to the current manager agents config file.

append_manager_config(Dir, Conf)

Append the config to the current manager config file.

append_users_config(Dir, Conf)

Append the users config to the current manager users config file.

append_usm_config(Dir, Conf)

Append the usm config to the current manager usm config file.

manager_entry(Tag, Val)

Create an entry for the manager config file, manager.conf.

read_agents_config(Dir)

Read the current manager agents config file.

read_manager_config(Dir)

Read the current manager config file.

read_users_config(Dir)

Read the current manager users config file.

read_usm_config(Dir)

Read the current manager usm config file.

users_entry(UserId)

Equivalent to users_entry/4.

users_entry(UserId, UserMod)

Equivalent to users_entry/4.

users_entry(UserId, UserMod, UserData)

Equivalent to users_entry/4.

users_entry(UserId, UserMod, UserData, DefaultAgentConfig)

Create an entry for the manager users config file, users.conf.

usm_entry(EngineID, UserName, AuthP, AuthKey, PrivP, PrivKey)

Equivalent to usm_entry/7.

usm_entry(EngineID, UserName, SecName, AuthP, AuthKey, PrivP, PrivKey)

Create an entry for the agent community config file, community.conf.

write_agents_config(Dir, Conf)

Equivalent to write_agents_config/3.

write_agents_config(Dir, Hdr, Conf)

Write the manager agents config to the manager agents config file.

write_manager_config(Dir, Conf)

Equivalent to write_manager_config/3.

write_manager_config(Dir, Hdr, Conf)

Write the manager config to the manager config file.

write_users_config(Dir, Conf)

Equivalent to write_users_config/3.

write_users_config(Dir, Hdr, Conf)

Write the manager users config to the manager users config file.

write_usm_config(Dir, Conf)

Equivalent to write_usm_config/3.

write_usm_config(Dir, Hdr, Conf)

Write the manager usm config to the manager usm config file.

Types

Link to this opaque

agent_entry()

View Source

-opaque agent_entry()

An opaque data structure containg all configuration for one agent for the manager.

Link to this opaque

manager_entry()

View Source

-opaque manager_entry()

An opaque data structure that represents one configuration entry for the manager.

Link to this opaque

user_entry()

View Source

-opaque user_entry()

An opaque data structure containg all configuration for one user for the manager.

Link to this opaque

usm_entry()

View Source

-opaque usm_entry()

An opaque data structure containg information about security data for usm for the manager.

Functions

Link to this function

agents_entry/12

View Source

-spec agents_entry(UserId, TargetName, Comm, TDomain, TAddr, EngineID, Timeout, MaxMessageSize, Version,
             SecModel, SecName, SecLevel) ->
                Entry
                when
                    UserId :: snmpm:user_id(),
                    TargetName :: snmpm:target_name(),
                    Comm :: snmp:community(),
                    TDomain :: snmp:tdomain(),
                    TAddr :: snmp:taddress(),
                    EngineID :: snmp:engine_id(),
                    Timeout :: snmpm:register_timeout(),
                    MaxMessageSize :: snmp:mms(),
                    Version :: snmp:version(),
                    SecModel :: snmp:sec_model(),
                    SecName :: snmp:sec_name(),
                    SecLevel :: snmp:sec_level(),
                    Entry :: agent_entry();
            (UserId, TargetName, Comm, Ip, Port, EngineID, Timeout, MaxMessageSize, Version,
             SecModel, SecName, SecLevel) ->
                Entry
                when
                    UserId :: snmpm:user_id(),
                    TargetName :: snmpm:target_name(),
                    Comm :: snmp:community(),
                    Ip :: inet:ip_address(),
                    Port :: inet:port_number(),
                    EngineID :: snmp:engine_id(),
                    Timeout :: snmpm:register_timeout(),
                    MaxMessageSize :: snmp:mms(),
                    Version :: snmp:version(),
                    SecModel :: snmp:sec_model(),
                    SecName :: snmp:sec_name(),
                    SecLevel :: snmp:sec_level(),
                    Entry :: agent_entry().

Create an entry for the manager agents config file, agents.conf.

See Agents for more info.

Link to this function

append_agents_config(Dir, Conf)

View Source

-spec append_agents_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [agent_entry()].

Append the agents config to the current manager agents config file.

Dir is the path to the directory where to store the config file.

See Agents for more info.

Link to this function

append_manager_config(Dir, Conf)

View Source

-spec append_manager_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [manager_entry()].

Append the config to the current manager config file.

Dir is the path to the directory where to store the config file.

See Manager Information for more info.

Link to this function

append_users_config(Dir, Conf)

View Source

-spec append_users_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [user_entry()].

Append the users config to the current manager users config file.

Dir is the path to the directory where to store the config file.

See Users for more info.

Link to this function

append_usm_config(Dir, Conf)

View Source

-spec append_usm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [usm_entry()].

Append the usm config to the current manager usm config file.

Dir is the path to the directory where to store the config file.

See Security data for USM for more info.

Link to this function

manager_entry(Tag, Val)

View Source

-spec manager_entry(Tag, Val) -> ManagerEntry
                 when
                     Tag :: transports | port | engine_id | max_message_size,
                     Val :: term(),
                     ManagerEntry :: manager_entry();
             (Tag, Val) -> ManagerEntry
                 when Tag :: address, Val :: term(), ManagerEntry :: manager_entry().

Create an entry for the manager config file, manager.conf.

The type of Val depends on the value of Tag, see Manager Information for more info.

Link to this function

read_agents_config(Dir)

View Source

-spec read_agents_config(Dir) -> {ok, Conf} | {error, Reason}
                      when Dir :: snmp:dir(), Conf :: [agent_entry()], Reason :: term().

Read the current manager agents config file.

Dir is the path to the directory where to store the config file.

See Agents for more info.

Link to this function

read_manager_config(Dir)

View Source

-spec read_manager_config(Dir) -> {ok, Conf} | {error, Reason}
                       when Dir :: snmp:dir(), Conf :: [manager_entry()], Reason :: term().

Read the current manager config file.

Dir is the path to the directory where to store the config file.

See Manager Information for more info.

Link to this function

read_users_config(Dir)

View Source

-spec read_users_config(Dir) -> {ok, Conf} | {error, Reason}
                     when Dir :: snmp:dir(), Conf :: [user_entry()], Reason :: term().

Read the current manager users config file.

Dir is the path to the directory where to store the config file.

See Users for more info.

Link to this function

read_usm_config(Dir)

View Source

-spec read_usm_config(Dir) -> {ok, Conf} | {error, Reason}
                   when Dir :: snmp:dir(), Conf :: [usm_entry()], Reason :: term().

Read the current manager usm config file.

Dir is the path to the directory where to store the config file.

See Security data for USM for more info.

Link to this function

users_entry(UserId)

View Source

-spec users_entry(UserId) -> UserEntry when UserId :: snmpm:user_id(), UserEntry :: user_entry().

Equivalent to users_entry/4.

Link to this function

users_entry(UserId, UserMod)

View Source

-spec users_entry(UserId, UserMod) -> UserEntry
               when
                   UserId :: snmpm:user_id(),
                   UserMod :: snmpm:snmpm_user(),
                   UserEntry :: user_entry().

Equivalent to users_entry/4.

Link to this function

users_entry(UserId, UserMod, UserData)

View Source

-spec users_entry(UserId, UserMod, UserData) -> UserEntry
               when
                   UserId :: snmpm:user_id(),
                   UserMod :: snmpm:snmpm_user(),
                   UserData :: term(),
                   UserEntry :: user_entry().

Equivalent to users_entry/4.

Link to this function

users_entry(UserId, UserMod, UserData, DefaultAgentConfig)

View Source

-spec users_entry(UserId, UserMod, UserData, DefaultAgentConfig) -> UserEntry
               when
                   UserId :: snmpm:user_id(),
                   UserMod :: snmpm:snmpm_user(),
                   UserData :: term(),
                   DefaultAgentConfig :: [snmpm:agent_config()],
                   UserEntry :: user_entry().

Create an entry for the manager users config file, users.conf.

users_entry(UserId) translates to the following call: users_entry(UserId, snmpm_user_default).

users_entry(UserId, UserMod) translates to the following call: users_entry(UserId, UserMod, undefined).

See Users for more info.

Link to this function

usm_entry(EngineID, UserName, AuthP, AuthKey, PrivP, PrivKey)

View Source

-spec usm_entry(EngineID, UserName, AuthP, AuthKey, PrivP, PrivKey) -> UsmEntry
             when
                 EngineID :: snmp:engine_id(),
                 UserName :: snmp:usm_name(),
                 AuthP :: snmp:usm_auth_protocol(),
                 AuthKey :: snmp:usm_auth_key(),
                 PrivP :: snmp:usm_priv_protocol(),
                 PrivKey :: snmp:usm_priv_key(),
                 UsmEntry :: usm_entry().

Equivalent to usm_entry/7.

Link to this function

usm_entry(EngineID, UserName, SecName, AuthP, AuthKey, PrivP, PrivKey)

View Source

-spec usm_entry(EngineID, UserName, SecName, AuthP, AuthKey, PrivP, PrivKey) -> UsmEntry
             when
                 EngineID :: snmp:engine_id(),
                 UserName :: snmp:usm_name(),
                 SecName :: snmp:sec_name(),
                 AuthP :: snmp:usm_auth_protocol(),
                 AuthKey :: snmp:usm_auth_key(),
                 PrivP :: snmp:usm_priv_protocol(),
                 PrivKey :: snmp:usm_priv_key(),
                 UsmEntry :: usm_entry().

Create an entry for the agent community config file, community.conf.

See Security data for USM for more info.

Link to this function

write_agents_config(Dir, Conf)

View Source

-spec write_agents_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [agent_entry()].

Equivalent to write_agents_config/3.

Link to this function

write_agents_config(Dir, Hdr, Conf)

View Source

-spec write_agents_config(Dir, Hdr, Conf) -> ok
                       when Dir :: snmp:dir(), Hdr :: string(), Conf :: [agent_entry()].

Write the manager agents config to the manager agents config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Agents for more info.

Link to this function

write_manager_config(Dir, Conf)

View Source

-spec write_manager_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [manager_entry()].

Equivalent to write_manager_config/3.

Link to this function

write_manager_config(Dir, Hdr, Conf)

View Source

-spec write_manager_config(Dir, Hdr, Conf) -> ok
                        when Dir :: snmp:dir(), Hdr :: string(), Conf :: [manager_entry()].

Write the manager config to the manager config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Manager Information for more info.

Link to this function

write_users_config(Dir, Conf)

View Source

-spec write_users_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [user_entry()].

Equivalent to write_users_config/3.

Link to this function

write_users_config(Dir, Hdr, Conf)

View Source

-spec write_users_config(Dir, Hdr, Conf) -> ok
                      when Dir :: snmp:dir(), Hdr :: string(), Conf :: [user_entry()].

Write the manager users config to the manager users config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Users for more info.

Link to this function

write_usm_config(Dir, Conf)

View Source

-spec write_usm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [user_entry()].

Equivalent to write_usm_config/3.

Link to this function

write_usm_config(Dir, Hdr, Conf)

View Source

-spec write_usm_config(Dir, Hdr, Conf) -> ok
                    when Dir :: snmp:dir(), Hdr :: string(), Conf :: [user_entry()].

Write the manager usm config to the manager usm config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Security data for USM for more info.

snmpm_mpd

Message Processing and Dispatch module for the SNMP manager

The module snmpm_mpd implements the version independent Message Processing and Dispatch functionality in SNMP for the manager. It is supposed to be used from a Network Interface process (Definition of Manager Net if).

Legacy API function process_msg/7 that has got separate IpAddr and PortNumber arguments still works as before for backwards compatibility reasons.

Summary

Types

logger()

A fun that handles audit trail logging.

mpd_state()

msg_data_acm()

Is an opaque data structure containing necessary security information for (incoming) v3 messages.

msg_data_cmy()

Is an opaque data structure containing necessary security information for v1 and v2 messages.

msg_data_cmyt()

Is an opaque data structure containing necessary security and transport information for v1 and v2 messages.

msg_data_v3()

Is an opaque data structure containing necessary security information for v3 messages.

Functions

generate_msg(Vsn, NoteStore, Pdu, MsgData, Log)

Generates a possibly encrypted packet to be sent to the network.

generate_response_msg(Vsn, Pdu, MsgData, Log)

Generates a possibly encrypted response packet to be sent to the network.

init(Vsns)

This function can be called from the net_if process at start-up. The options list defines which versions to use.

process_msg(Msg, Domain, Addr, State, NoteStore, Log)

Processes an incoming message. Performs authentication and decryption as necessary. The return values should be passed the manager server.

Types

Link to this type

logger()

View Source

-type logger() ::
    fun((Data ::
             binary() |
             snmp_pdus:pdu() |
             snmp_pdus:trappdu() |
             snmp_pdus:message() |
             {V3Hdr :: snmp_pdus:v3_hdr(), ScopedPDUBytes :: binary()}) ->
            snmp:void()).

A fun that handles audit trail logging.

Link to this opaque

mpd_state()

View Source

-opaque mpd_state()

Link to this opaque

msg_data_acm()

View Source

-opaque msg_data_acm()

Is an opaque data structure containing necessary security information for (incoming) v3 messages.

Link to this opaque

msg_data_cmy()

View Source

-opaque msg_data_cmy()

Is an opaque data structure containing necessary security information for v1 and v2 messages.

Link to this opaque

msg_data_cmyt()

View Source

-opaque msg_data_cmyt()

Is an opaque data structure containing necessary security and transport information for v1 and v2 messages.

Link to this opaque

msg_data_v3()

View Source

-opaque msg_data_v3()

Is an opaque data structure containing necessary security information for v3 messages.

Functions

Link to this function

generate_msg(Vsn, NoteStore, Pdu, MsgData, Log)

View Source

-spec generate_msg(Vsn, NoteStore, Pdu, MsgData, Log) -> {ok, Packet} | {discarded, Reason}
                when
                    Vsn :: snmp_pdus:version(),
                    NoteStore :: pid(),
                    Pdu :: snmp_pdus:pdu(),
                    MsgData :: msg_data_cmy() | msg_data_v3(),
                    Log :: logger(),
                    Packet :: binary(),
                    Reason :: term().

Generates a possibly encrypted packet to be sent to the network.

NoteStore is the pid/0 of the note-store process.

MsgData is the message specific data used in the SNMP message. In SNMPv1 and SNMPv2c, this message data is the community string. In SNMPv3, it is the context information.

Logger is the function used for audit trail logging.

Link to this function

generate_response_msg(Vsn, Pdu, MsgData, Log)

View Source

-spec generate_response_msg(Vsn, Pdu, MsgData, Log) ->
                         {ok, Packet} | {discarded, Reason} | {error, Reason}
                         when
                             Vsn :: snmp_pdus:version(),
                             Pdu :: snmp_pdus:pdu(),
                             MsgData :: msg_data_cmy() | msg_data_cmyt() | msg_data_v3(),
                             Log :: logger(),
                             Packet :: binary(),
                             Reason :: term().

Generates a possibly encrypted response packet to be sent to the network.

MsgData is the message specific data used in the SNMP message. This value is received from the process_msg function.

Link to this function

init(Vsns)

View Source

-spec init(Vsns) -> MPDState when Vsns :: [snmp:version()], MPDState :: mpd_state().

This function can be called from the net_if process at start-up. The options list defines which versions to use.

It also initializes some SNMP counters.

Link to this function

process_msg(Msg, Domain, Addr, State, NoteStore, Log)

View Source (since OTP 17.3)

-spec process_msg(Msg, Domain, Addr, State, NoteStore, Log) ->
               {ok, Vsn, PduV2, PduMS, MsgDataV2} |
               {ok, 'version-3', PduV3, PduMS, MsgDataV3} |
               {discarded, Reason}
               when
                   Msg :: binary(),
                   Domain :: snmpUDPDomain | snmp:tdomain(),
                   Addr :: {Ip, Port},
                   Ip :: inet:ip_address(),
                   Port :: inet:port_number(),
                   State :: mpd_state(),
                   NoteStore :: pid(),
                   Log :: logger(),
                   Vsn :: 'version-1' | 'version-2',
                   PduV2 :: snmp_pdus:pdu() | snmp_pdus:trappdu(),
                   PduV3 :: snmp_pdus:pdu(),
                   PduMS :: pos_integer(),
                   MsgDataV2 :: msg_data_cmyt(),
                   MsgDataV3 :: ok | {error, ReqId, ACM} | undefined | msg_data_acm(),
                   ReqId :: snmpm:request_id(),
                   ACM :: term(),
                   Reason :: term().

Processes an incoming message. Performs authentication and decryption as necessary. The return values should be passed the manager server.

NoteStore is the pid/0 of the note-store process.

Logger is the function used for audit trail logging.

In the case when the pdu type is report, MsgData is either ok or {error, ReqId, Reason}.

snmpm_network_interface behaviour

Behaviour module for the SNMP manager network interface.

This module defines the behaviour of the manager network interface. A snmpm_network_interface compliant module must export the following functions:

start_link/2

stop/1

send_pdu/7

inform_response/4

note_store/2

info/1

get_log_type/1

set_log_type/2

verbosity/2

The semantics of them and their exact signatures are explained below.

Legacy API function send_pdu/7 that has got separate IpAddr and PortNumber arguments still works as before for backwards compatibility reasons.

Summary

Callbacks

get_log_type(Pid)

The Audit Trail Log is managed by the network interface process. So, it is this process that has to return the actual log-type.

info(Pid)

The info returned is basically up to the implementer to decide. The implementation provided by this application provides info about memory allocation and various socket information.

inform_response(Pid, Ref, Addr, Port)

Instruct the network interface process to send the response (acknowledgment) to an inform-request.

note_store(Pid, NoteStore)

Change the pid of the note-store process. This is used when the server re-starts the note_store (e.g. after a crach).

send_pdu(Pid, Pdu, Vsn, MsgData, Domain, Addr, ExtraInfo)

Request the network interface process (Pid) to send this pdu (Pdu).

set_log_type(Pid, NewType)

The Audit Trail Log is managed by the network interface process. So, it is this process that has to do the actual changing of the type.

start_link(Server, NoteStore)

Start-link the network interface process.

stop(Pid)

Stop the network interface process.

verbosity(Pid, Verbosity)

Change the verbosity of the network interface process.

Callbacks

Link to this callback

get_log_type(Pid)

View Source

-callback get_log_type(Pid) -> {ok, LogType} | {error, Reason}
                when Pid :: pid(), LogType :: snmp:atl_type(), Reason :: term().

The Audit Trail Log is managed by the network interface process. So, it is this process that has to return the actual log-type.

Link to this callback

info(Pid)

View Source

-callback info(Pid) -> Info when Pid :: pid(), Info :: [{Key, Value}], Key :: term(), Value :: term().

The info returned is basically up to the implementer to decide. The implementation provided by this application provides info about memory allocation and various socket information.

The info returned by this function is returned together with other info collected by the manager when the info function is called (tagged with the key net_if).

Link to this callback

inform_response(Pid, Ref, Addr, Port)

View Source

-callback inform_response(Pid, Ref, Addr, Port) -> snmp:void()
                   when
                       Pid :: pid(),
                       Ref :: term(),
                       Addr :: inet:ip_address(),
                       Port :: inet:port_number().

Instruct the network interface process to send the response (acknowledgment) to an inform-request.

Ref is something that can be used to identify the inform-request, e.g. request-id of the inform-request.

Addr and Port identifies the agent, from which the inform-request originated.

Link to this callback

note_store(Pid, NoteStore)

View Source

-callback note_store(Pid, NoteStore) -> snmp:void() when Pid :: pid(), NoteStore :: pid().

Change the pid of the note-store process. This is used when the server re-starts the note_store (e.g. after a crach).

Link to this callback

send_pdu(Pid, Pdu, Vsn, MsgData, Domain, Addr, ExtraInfo)

View Source

-callback send_pdu(Pid, Pdu, Vsn, MsgData, Domain, Addr, ExtraInfo) -> snmp:void()
            when
                Pid :: pid(),
                Pdu :: snmp:pdu(),
                Vsn :: 'version-1' | 'version-2' | 'version-3',
                MsgData :: term(),
                Domain :: snmp:tdomain(),
                Addr :: {inet:ip_address(), inet:port_number()},
                ExtraInfo :: term().

Request the network interface process (Pid) to send this pdu (Pdu).

ExtraInfo is some opaque data that is passed to the net-if process. It originates from the ExtraInfo parameter in the calls to the synchronous get-request, asynchronous get-request, synchronous get-next-request, asynchronous get-next-request, synchronous set-request and asynchronous set-request functions. Whether the net-if process chooses to use this is implementation dependent. The net-if process included in this application ignores it.

Link to this callback

set_log_type(Pid, NewType)

View Source

-callback set_log_type(Pid, NewType) -> {ok, OldType} | {error, Reason}
                when
                    Pid :: pid(),
                    NewType :: snmp:atl_type(),
                    OldType :: snmp:atl_type(),
                    Reason :: term().

The Audit Trail Log is managed by the network interface process. So, it is this process that has to do the actual changing of the type.

See snmpm:set_log_type/1 for more info.

Link to this callback

start_link(Server, NoteStore)

View Source

-callback start_link(Server, NoteStore) -> {ok, Pid} | {error, Reason}
              when Server :: pid(), NoteStore :: pid(), Pid :: pid(), Reason :: term().

Start-link the network interface process.

Server is the pid of the managing process.

NoteStore is the pid of the note-store process.

Link to this callback

stop(Pid)

View Source

-callback stop(Pid) -> snmp:void() when Pid :: pid().

Stop the network interface process.

Link to this callback

verbosity(Pid, Verbosity)

View Source

-callback verbosity(Pid, Verbosity) -> snmp:void() when Pid :: pid(), Verbosity :: snmp:verbosity().

Change the verbosity of the network interface process.

snmpm_network_interface_filter behaviour

Behaviour module for the SNMP manager network-interface filter.

This module defines the behaviour of the manager network interface filter. A snmpm_network_interface_filter compliant module must export the following functions:

accept_recv/2

accept_send/2

accept_recv_pdu/3

accept_send_pdu/2

The semantics of them and their exact signatures are explained below.

The purpose of the network interface filter is to allow for filtering of messages (accept or reject) receive and send. This is done on two levels:

The first level is at the UDP entry / exit point, i.e. immediately after the receipt of the message, before any message processing is done (accept_recv) and immediately before sending the message, after all message processing is done (accept_send).

The second level is at the MPD entry / exit point, i.e. immediately after the basic message processing (accept_recv_pdu) / immediately before the basic message processing (accept_send_pdu).

Note that the network interface filter is something which is used by the network interface implementation provided by the application (snmpm_net_if and snmpm_net_if_mt). The default filter accepts all messages.

A network interface filter can e.g. be used during testing or for load regulation.

Legacy network interface filter modules used arguments on the form (IpAddr, PortNumber,...) instead of (Domain, Addr, ...), and if the SNMP manager is run without changing the configuration to use transport domains the network interface filter will still get the old arguments and work as before.

DATA TYPES

port() = integer() > 0
pdu_type() = 'get-request' | 'get-next-request' | 'get-response' |
             'set-request' | trap | 'get-bulk-request' | 'inform-request' |
             report | trappdu

See also the data types in snmpa_conf.

Summary

Types

pdu_type()

transportAddressWithPort()

transportDomain()

Callbacks

accept_recv(Domain, Addr)

Called at the reception of a message (before any processing has been done).

accept_recv_pdu(Domain, Addr, PduType)

Called after the basic message processing (MPD) has been done, but before the pdu is handed over to the server for primary processing.

accept_send(Domain, Addr)

Called before the sending of a message (after all processing has been done).

accept_send_pdu(Domain, Addr, PduType)

Called before the basic message processing (MPD) is done, when a pdu has been received from the master-agent.

Types

Link to this type

pdu_type()

View Source (not exported)

-type pdu_type() :: snmpm:pdu_type().

Link to this type

transportAddressWithPort()

View Source (not exported)

-type transportAddressWithPort() :: snmpa_conf:transportAddressWithPort().

Link to this type

transportDomain()

View Source (not exported)

-type transportDomain() :: snmpa_conf:transportDomain().

Callbacks

Link to this callback

accept_recv(Domain, Addr)

View Source

-callback accept_recv(Domain, Addr) -> boolean()
               when Domain :: transportDomain(), Addr :: transportAddressWithPort().

Called at the reception of a message (before any processing has been done).

For the message to be rejected, the function must return false.

Link to this callback

accept_recv_pdu(Domain, Addr, PduType)

View Source

-callback accept_recv_pdu(Domain, Addr, PduType) -> boolean()
                   when
                       Domain :: transportDomain(),
                       Addr :: transportAddressWithPort(),
                       PduType :: pdu_type().

Called after the basic message processing (MPD) has been done, but before the pdu is handed over to the server for primary processing.

For the pdu to be rejected, the function must return false.

Link to this callback

accept_send(Domain, Addr)

View Source

-callback accept_send(Domain, Addr) -> boolean()
               when Domain :: transportDomain(), Addr :: transportAddressWithPort().

Called before the sending of a message (after all processing has been done).

For the message to be rejected, the function must return false.

Link to this callback

accept_send_pdu(Domain, Addr, PduType)

View Source

-callback accept_send_pdu(Domain, Addr, PduType) -> boolean()
                   when
                       Domain :: transportDomain(),
                       Addr :: transportAddressWithPort(),
                       PduType :: pdu_type().

Called before the basic message processing (MPD) is done, when a pdu has been received from the master-agent.

For the message to be rejected, the function must return false.

snmpm_user behaviour

Behaviour module for the SNMP manager user.

This module defines the behaviour of the manager user. A snmpm_user compliant module must export the following functions:

handle_error/3

handle_agent/5

handle_pdu/4

handle_trap/3

handle_inform/3

handle_report/3

handle_invalid_result/2

The semantics of them and their exact signatures are explained below.

Some of the function has no defined return value (void()), they can of course return anything. But the functions that do have specified return value(s) must adhere to this. None of the functions can use exit of throw to return.

If the manager is not configured to use any particular transport domain, the behaviour handle_agent/5 will for backwards copmpatibility reasons be called with the old IpAddr and PortNumber arguments

DATA TYPES

snmp_gen_info() = {ErrorStatus :: atom(),
                   ErrorIndex  :: pos_integer(),
                   Varbinds    :: [snmp:varbind()]}
snmp_v1_trap_info() :: {Enteprise :: snmp:oid(),
                        Generic   :: integer(),
                        Spec      :: integer(),
                        Timestamp :: integer(),
                        Varbinds  :: [snmp:varbind()]}

Summary

Types

ip_address()

port_number()

snmp_gen_info()

snmp_v1_trap_info()

Callbacks

handle_agent(Domain, Address, Type, SnmpInfo, UserData)

This function is called when a message is received from an unknown agent.

handle_error(ReqId, Reason, UserData)

This function is called when the manager needs to communicate an "asynchronous" error to the user: e.g. failure to send an asynchronous message (i.e. encoding error), a received message was discarded due to security error, the manager failed to generate a response message to a received inform-request, or when receiving an unexpected PDU from an agent (could be an expired async request).

handle_inform(TargetName, SnmpInform, UserData)

Handle a inform message.

handle_invalid_result(In, Out)

If any of the other callback functions crashes (exit, throw or a plain crash) or return an invalid result (if a valid return has been specified), this function is called. The purpose is to allow the user handle this error (for instance to issue an error report).

handle_pdu(TargetName, ReqId, SnmpResponse, UserData)

Handle the reply to an asynchronous request, such as async_get, async_get_next or async_set.

handle_report(TargetName, SnmpReport, UserData)

Handle a report message.

handle_trap(TargetName, SnmpTrapInfo, UserData)

Handle a trap/notification message from an agent.

Types

Link to this type

ip_address()

View Source (not exported)

-type ip_address() :: inet:ip_address().

Link to this type

port_number()

View Source (not exported)

-type port_number() :: inet:port_number().

Link to this type

snmp_gen_info()

View Source

-type snmp_gen_info() ::
    {ErrorStatus :: atom(), ErrorIndex :: pos_integer(), Varbinds :: [snmp:varbind()]}.

Link to this type

snmp_v1_trap_info()

View Source

-type snmp_v1_trap_info() ::
    {Enteprise :: snmp:oid(),
     Generic :: integer(),
     Spec :: integer(),
     Timestamp :: integer(),
     Varbinds :: [snmp:varbind()]}.

Callbacks

Link to this callback

handle_agent(Domain, Address, Type, SnmpInfo, UserData)

View Source

-callback handle_agent(Domain :: atom(),
             Address :: term(),
             Type :: pdu | trap | inform | report,
             SnmpInfo :: snmp_gen_info() | snmp_v1_trap_info(),
             UserData :: term()) ->
                Reply ::
                    ignore |
                    {register,
                     UserId :: term(),
                     RTargetName :: snmpm:target_name(),
                     AgentConfig :: [snmpm:agent_config()]}.

This function is called when a message is received from an unknown agent.

Note that this will always be the default user that is called.

For more info about the agent_config(), see snmpm:register_agent/3.

The arguments Type and SnmpInfo relates in the following way:

pdu - SnmpPduInfo (see handle_pdu/4 for more info).

trap - SnmpTrapInfo (see handle_trap/3 for more info).

report - SnmpReportInfo (see handle_report/3 for more info).

inform - SnmpInformInfo (see handle_inform/3 for more info).

The only user which would return {register, UserId, TargetName, AgentConfig} is the default user.

Link to this callback

handle_error(ReqId, Reason, UserData)

View Source

-callback handle_error(ReqId :: netif | integer(),
             Reason ::
                 {unexpected_pdu, SnmpInfo :: snmp_gen_info()} |
                 {invalid_sec_info, SecInfo :: term(), SnmpInfo :: snmp_gen_info()} |
                 {empty_message,
                  TransportDomain :: atom(),
                  {Addr :: ip_address(), Port :: port_number()}} |
                 term(),
             UserData :: term()) ->
                snmp:void().

This function is called when the manager needs to communicate an "asynchronous" error to the user: e.g. failure to send an asynchronous message (i.e. encoding error), a received message was discarded due to security error, the manager failed to generate a response message to a received inform-request, or when receiving an unexpected PDU from an agent (could be an expired async request).

If ReqId is less then 0, it means that this information was not available to the manager (that info was never retrieved before the message was discarded).

For SnmpInfo see handle_agent below.

Note that there is a special case when the value of ReqId has the value of the atom netif. This means that the NetIF process has suffered a "fatal" error and been restarted. With possible loss of traffic!

Link to this callback

handle_inform(TargetName, SnmpInform, UserData)

View Source

-callback handle_inform(TargetName :: snmpm:target_name(),
              SnmpInform :: snmp_gen_info(),
              UserData :: term()) ->
                 Reply ::
                     ignore | no_reply | unregister |
                     {register,
                      UserId :: term(),
                      RTargetName :: snmpm:target_name(),
                      AgentConfig :: [snmpm:agent_config()]}.

Handle a inform message.

For more info about the agent_config(), see snmpm:register_agent/3.

The only user which would return {register, UserId, TargetName2, AgentConfig} is the default user.

If the inform request behaviour configuration option is set to user or {user, integer()}, the response (acknowledgment) to this inform-request will be sent when this function returns.

Link to this callback

handle_invalid_result(In, Out)

View Source (optional) (since OTP R16B03)

-callback handle_invalid_result(In, Out) -> no_return()
                         when
                             In :: {Fun :: atom(), Args :: list()},
                             Out :: {crash, CrashInfo} | {result, InvalidResult :: term()},
                             CrashInfo ::
                                 {ErrorType :: atom(),
                                  Error :: term(),
                                  Stacktrace :: erlang:stacktrace()}.

If any of the other callback functions crashes (exit, throw or a plain crash) or return an invalid result (if a valid return has been specified), this function is called. The purpose is to allow the user handle this error (for instance to issue an error report).

IN reprecents the function called (and its arguments). OUT represents the unexpected/invalid result.

Link to this callback

handle_pdu(TargetName, ReqId, SnmpResponse, UserData)

View Source

-callback handle_pdu(TargetName :: snmpm:target_name(),
           ReqId :: term(),
           SnmpResponse :: snmp_gen_info(),
           UserData :: term()) ->
              snmp:void().

Handle the reply to an asynchronous request, such as async_get, async_get_next or async_set.

It could also be a late reply to a synchronous request.

ReqId is returned by the asynchronous request function.

Link to this callback

handle_report(TargetName, SnmpReport, UserData)

View Source

-callback handle_report(TargetName :: snmpm:target_name(),
              SnmpReport :: snmp_gen_info(),
              UserData :: term()) ->
                 Reply ::
                     ignore | unregister |
                     {register,
                      UserId :: term(),
                      RTargetName :: snmpm:target_name(),
                      AgentConfig :: [snmpm:agent_config()]}.

Handle a report message.

For more info about the agent_config(), see snmpm:register_agent/3.

The only user which would return {register, UserId, TargetName2, AgentConfig} is the default user.

Link to this callback

handle_trap(TargetName, SnmpTrapInfo, UserData)

View Source

-callback handle_trap(TargetName :: snmpm:target_name(),
            SnmpTrapInfo :: snmp_gen_info() | snmp_v1_trap_info(),
            UserData :: term()) ->
               Reply ::
                   ignore | unregister |
                   {register,
                    UserId :: term(),
                    RTargetName :: snmpm:target_name(),
                    AgentConfig :: [snmpm:agent_config()]}.

Handle a trap/notification message from an agent.

For more info about the agent_config(), see snmpm:register_agent/3.

The only user which would return {register, UserId, TargetName2, agent_info()} is the default user.