Search documentation of snmp

# SNMP Application

View Source

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

← Previous Page API Reference
Next Page → SNMP Release Notes