.TH snmp 6 "snmp  4.11" "Ericsson AB" "ERLANG APPLICATION DEFINITION"
.SH APPLICATION
snmp \- The SNMP Application
.SH DESCRIPTION
.LP
This chapter describes the \fIsnmp\fR application in OTP\&. The SNMP application provides the following services:
.RS 2
.TP 2
*
a multilingual extensible SNMP agent
.TP 2
*
a SNMP manager
.TP 2
*
a MIB compiler
.RE

.SH CONFIGURATION
.LP
The following configuration parameters are defined for the SNMP application\&. Refer to application(3) for more information about configuration parameters\&. 
.LP
The snmp part of the config file specifying the configuration parameters is basically the following tuple:

.nf
      {snmp, snmp_components_config()}
    
.fi
.LP
A minimal config file for starting a node with both a manager and an agent:

.nf
      [{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"}]}]}]}
        ]
       }
      ]\&.
    
.fi
.LP
Each snmp component has it\&'s own set of configuration parameters, even though some of the types are common to both components\&. 

.nf
      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()}        |  
                       {versions,         versions()}         |  
                       {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_module,          def_user_module()  | 
                         {def_user_data,            def_user_data()}
    
.fi
.LP
Agent specific config options and types:
.RS 2
.TP 4
.B
\fIagent_type() = master | sub <optional>\fR:
If \fImaster\fR, one master agent is started\&. Otherwise, no agents are started\&. 
.RS 4
.LP

.LP
Default is \fImaster\fR\&.
.RE
.TP 4
.B
\fImulti_threaded() = bool() <optional>\fR:
If \fItrue\fR, the agent is multi-threaded, with one thread for each get request\&. 
.RS 4
.LP

.LP
Default is \fIfalse\fR\&.
.RE
.TP 4
.B
\fIdb_dir() = string() <mandatory>\fR:
Defines where the SNMP agent internal db files are stored\&.
.TP 4
.B
\fIlocal_db() = [local_db_opt()] <optional>\fR:
\fIlocal_db_opt() = {repair, agent_repair()} | {auto_save, agent_auto_save()} | {verbosity, verbosity()}\fR
.RS 4
.LP

.LP
Defines options specific for the SNMP agent local database\&.
.LP

.LP
For defaults see the options in \fIlocal_db_opt()\fR\&.
.RE
.TP 4
.B
\fIagent_repair() = false | true | force <optional>\fR:
When starting snmpa_local_db it always tries to open an existing database\&. If \fIfalse\fR, and some errors occur, a new database is created instead\&. If \fItrue\fR, an existing file will be repaired\&. If \fIforce\fR, the table will be repaired even if it was properly closed\&. 
.RS 4
.LP

.LP
Default is \fItrue\fR\&.
.RE
.TP 4
.B
\fIagent_auto_save() = integer() | infinity <optional>\fR:
The auto save interval\&. The table is flushed to disk whenever not accessed for this amount of time\&.
.RS 4
.LP

.LP
Default is \fI5000\fR\&.
.RE
.TP 4
.B
\fIagent_net_if() = [agent_net_if_opt()] <optional>\fR:
\fIagent_net_if_opt() = {module, agent_net_if_module()} | {verbosity, verbosity()} | {options, agent_net_if_options()}\fR
.RS 4
.LP

.LP
Defines options specific for the SNMP agent network interface entity\&. 
.LP

.LP
For defaults see the options in \fIagent_net_if_opt()\fR\&.
.RE
.TP 4
.B
\fIagent_net_if_module() = atom() <optional>\fR:
Module which handles the network interface part for the SNMP agent\&. Must implement the snmpa_network_interface behaviour\&.
.RS 4
.LP

.LP
Default is \fIsnmpa_net_if\fR\&.
.RE
.TP 4
.B
\fIagent_net_if_options() = [agent_net_if_option()] <optional>\fR:
\fIagent_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()}\fR
.RS 4
.LP

.LP
These options are actually specific to the used module\&. The ones shown here are applicable to the default \fIagent_net_if_module()\fR\&.
.LP

.LP
For defaults see the options in \fIagent_net_if_option()\fR\&.
.RE
.TP 4
.B
\fIreq_limit() = integer() | infinity <optional>\fR:
Max number of simultaneous requests handled by the agent\&.
.RS 4
.LP

.LP
Default is \fIinfinity\fR\&.
.RE
.TP 4
.B
\fIagent_net_if_filter_options() = [agent_net_if_filter_option()] <optional>\fR:
\fIagent_net_if_filter_option() = {module, agent_net_if_filter_module()}\fR
.RS 4
.LP

.LP
These options are actually specific to the used module\&. The ones shown here are applicable to the default \fIagent_net_if_filter_module()\fR\&.
.LP

.LP
For defaults see the options in \fIagent_net_if_filter_option()\fR\&.
.RE
.TP 4
.B
\fIagent_net_if_filter_module() = atom() <optional>\fR:
Module which handles the network interface filter part for the SNMP agent\&. Must implement the snmpa_network_interface_filter behaviour\&.
.RS 4
.LP

.LP
Default is \fIsnmpa_net_if_filter\fR\&.
.RE
.TP 4
.B
\fIagent_mibs() = [string()] <optional>\fR:
Specifies a list of MIBs (including path) that defines which MIBs are initially loaded into the SNMP master agent\&. 
.RS 4
.LP

.LP
Note that the following mibs will always be loaded:
.LP

.RS 2
.TP 2
*
version v1: \fISTANDARD-MIB\fR
.TP 2
*
version v2: \fISNMPv2\fR
.TP 2
*
version v3: \fISNMPv2\fR, \fISNMP-FRAMEWORK-MIB\fR and \fISNMP-MPD-MIB\fR
.RE
.LP

.LP
Default is \fI[]\fR\&.
.RE
.TP 4
.B
\fImib_storage() = ets | {ets, Dir} | {ets, Dir, Action} | dets | {dets, Dir} | {dets, Dir, Action} | mnesia | {mnesia, Nodes} | {mnesia, Nodes, Action} <optional>\fR:
Specifies how info retrieved from the mibs will be stored\&.
.RS 4
.LP

.LP
If \fImib_storage\fR is \fI{ets, Dir}\fR, the table will also be stored on file\&. If \fIDir\fR is \fIdefault\fR, then \fIdb_dir\fR will be used\&.
.LP

.LP
If \fImib_storage\fR is \fIdets\fR or if \fIDir\fR is \fIdefault\fR, then \fIdb_dir\fR will be used for \fIDir\fR\&.
.LP

.LP
If \fImib_storage\fR is \fImnesia\fR then \fIerlang:nodes()\fR will be used for \fINodes\fR\&.
.LP

.LP
Default is \fIets\fR\&. 
.LP

.LP
\fIDir = default | string()\fR\&. Dir is the directory where the files will be stored\&. If \fIdefault\fR, then \fIdb_dir\fR will be used\&.
.LP

.LP
\fINodes = visible | connected | [node()]\fR\&. \fINodes = visible\fR is translated to \fIerlang:nodes(visible)\fR\&. \fINodes = connected\fR is translated to \fIerlang:nodes(connected)\fR\&. If \fINodes = []\fR then the own node is assumed\&.
.LP

.LP
\fIAction = clear | keep\fR\&. Default is \fIkeep\fR\&. \fIAction\fR is used to specify what shall be done if the mnesia/dets table already exist\&.
.RE
.TP 4
.B
\fImib_server() = [mib_server_opt()] <optional>\fR:
\fImib_server_opt() = {mibentry_override, mibentry_override()} | {trapentry_override, trapentry_override()} | {verbosity, verbosity()}\fR
.RS 4
.LP

.LP
Defines options specific for the SNMP agent mib server\&. 
.LP

.LP
For defaults see the options in \fImib_server_opt()\fR\&.
.RE
.TP 4
.B
\fImibentry_override() = bool() <optional>\fR:
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\&.
.RS 4
.LP

.LP
Default is \fIfalse\fR\&.
.RE
.TP 4
.B
\fItrapentry_override() = bool() <optional>\fR:
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\&.
.RS 4
.LP

.LP
Default is \fIfalse\fR\&.
.RE
.TP 4
.B
\fIerror_report_mod() = atom() <optional>\fR:
Defines an error report module, implementing the snmpa_error_report behaviour\&. Two modules are provided with the toolkit: \fIsnmpa_error_logger\fR and \fIsnmpa_error_io\fR\&.
.RS 4
.LP

.LP
Default is \fIsnmpa_error_logger\fR\&.
.RE
.TP 4
.B
\fIsymbolic_store() = [symbolic_store_opt()]\fR:
\fIsymbolic_store_opt() = {verbosity, verbosity()}\fR
.RS 4
.LP

.LP
Defines options specific for the SNMP agent symbolic store\&. 
.LP

.LP
For defaults see the options in \fIsymbolic_store_opt()\fR\&.
.RE
.TP 4
.B
\fItarget_cache() = [target_cache_opt()]\fR:
\fItarget_cache_opt() = {verbosity, verbosity()}\fR
.RS 4
.LP

.LP
Defines options specific for the SNMP agent target cache\&. 
.LP

.LP
For defaults see the options in \fItarget_cache_opt()\fR\&.
.RE
.TP 4
.B
\fIagent_config() = [agent_config_opt()] <mandatory>\fR:
\fIagent_config_opt() = {dir, agent_config_dir()} | {force_load, force_load()} | {verbosity, verbosity()}\fR
.RS 4
.LP

.LP
Defines specific config related options for the SNMP agent\&. 
.LP

.LP
For defaults see the options in \fIagent_config_opt()\fR\&.
.RE
.TP 4
.B
\fIagent_config_dir = dir() <mandatory>\fR:
Defines where the SNMP agent configuration files are stored\&.
.TP 4
.B
\fIforce_load() = bool() <optional>\fR:
If \fItrue\fR the configuration files are re-read during start-up, and the contents of the configuration database ignored\&. Thus, if \fItrue\fR, changes to the configuration database are lost upon reboot of the agent\&. 
.RS 4
.LP

.LP
Default is \fIfalse\fR\&.
.RE
.RE
.LP
Manager specific config options and types:
.RS 2
.TP 4
.B
\fIserver() = [server_opt()] <optional>\fR:
\fIserver_opt() = {timeout, server_timeout()} | {verbosity, verbosity()}\fR
.RS 4
.LP

.LP
Specifies the options for the manager server process\&.
.LP

.LP
Default is \fIsilence\fR\&.
.RE
.TP 4
.B
\fIserver_timeout() = integer() <optional>\fR:
Asynchroneous 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 \fIbest before\fR time has been passed\&. This cleanup will be performed at regular intervals, defined by the \fIserver_timeout()\fR time\&. The information will have an \fIbest before\fR time, defined by the \fIExpire\fR time given when calling the request function (see ag, agn and as)\&.
.RS 4
.LP

.LP
Time in milli-seconds\&.
.LP

.LP
Default is \fI30000\fR\&.
.RE
.TP 4
.B
\fImanager_config() = [manager_config_opt()] <mandatory>\fR:
\fImanager_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()}\fR
.RS 4
.LP

.LP
Defines specific config related options for the SNMP manager\&. 
.LP

.LP
For defaults see the options in \fImanager_config_opt()\fR\&.
.RE
.TP 4
.B
\fImanager_config_dir = dir() <mandatory>\fR:
Defines where the SNMP manager configuration files are stored\&.
.TP 4
.B
\fImanager_db_dir = dir() <mandatory>\fR:
Defines where the SNMP manager store persistent data\&.
.TP 4
.B
\fImanager_repair() = false | true | force <optional>\fR:
Defines the repair option for the persistent database (if and how the table is repaired when opened)\&. 
.RS 4
.LP

.LP
Default is \fItrue\fR\&.
.RE
.TP 4
.B
\fImanager_auto_save() = integer() | infinity <optional>\fR:
The auto save interval\&. The table is flushed to disk whenever not accessed for this amount of time\&.
.RS 4
.LP

.LP
Default is \fI5000\fR\&.
.RE
.TP 4
.B
\fImanager_irb() = auto | user | {user, integer()} <optional>\fR:
This option defines how the manager will handle the sending of response (acknowledgment) to received inform-requests\&. 
.RS 4
.LP

.RS 2
.TP 2
*
\fIauto\fR - The manager will autonomously send response (acknowledgment> to inform-request messages\&.
.TP 2
*
\fI{user, integer()}\fR - 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\&.
.TP 2
*
\fIuser\fR - Same as \fI{user, integer()}\fR, except that the default time, 15 seconds (15000), is used\&.
.RE
.LP

.LP
See snmpm_network_interface, handle_inform and definition of the manager net if for more info\&.
.LP

.LP
Default is \fIauto\fR\&.
.RE
.TP 4
.B
\fImanager_mibs() = [string()] <optional>\fR:
Specifies a list of MIBs (including path) and defines which MIBs are initially loaded into the SNMP manager\&. 
.RS 4
.LP

.LP
Default is \fI[]\fR\&.
.RE
.TP 4
.B
\fImanager_net_if() = [manager_net_if_opt()] <optional>\fR:
\fImanager_net_if_opt() = {module, manager_net_if_module()} | {verbosity, verbosity()} | {options, manager_net_if_options()}\fR
.RS 4
.LP

.LP
Defines options specific for the SNMP manager network interface entity\&. 
.LP

.LP
For defaults see the options in \fImanager_net_if_opt()\fR\&.
.RE
.TP 4
.B
\fImanager_net_if_options() = [manager_net_if_option()] <optional>\fR:
\fImanager_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()} | {recbuf, recbuf()} | {no_reuse, no_reuse()}\fR
.RS 4
.LP

.LP
These options are actually specific to the used module\&. The ones shown here are applicable to the default \fImanager_net_if_module()\fR\&.
.LP

.LP
For defaults see the options in \fImanager_net_if_option()\fR\&.
.RE
.TP 4
.B
\fImanager_net_if_module() = atom() <optional>\fR:
Module which handles the network interface part for the SNMP manager\&. Must implement the snmpm_network_interface behaviour\&.
.RS 4
.LP

.LP
Default is \fIsnmpm_net_if\fR\&.
.RE
.TP 4
.B
\fIdef_user_module() = atom() <optional>\fR:
The module implementing the default user\&. See the snmpm_user behaviour\&.
.RS 4
.LP

.LP
Default is \fIsnmpm_user_default\fR\&.
.RE
.TP 4
.B
\fIdef_user_data() = term() <optional>\fR:
Data for the default user\&. Passed to the user module when calling the callback functions\&.
.RS 4
.LP

.LP
Default is \fIundefined\fR\&.
.RE
.RE
.LP
Common config types:
.RS 2
.TP 4
.B
\fIrestart_type() = permanent | transient | temporary\fR:
See supervisor documentation for more info\&.
.RS 4
.LP

.LP
Default is \fIpermanent\fR for the agent and \fItransient\fR for the manager\&.
.RE
.TP 4
.B
\fIdb_init_error() = terminate | create\fR:
Defines what to do if the agent or manager is unable to open an existing database file\&. \fIterminate\fR means that the agent/manager will terminate and \fIcreate\fR means that the agent/manager will remove the faulty file(s) and create new ones\&.
.RS 4
.LP

.LP
Default is \fIterminate\fR\&.
.RE
.TP 4
.B
\fIpriority() = atom() <optional>\fR:
Defines the Erlang priority for all SNMP processes\&.
.RS 4
.LP

.LP
Default is \fInormal\fR\&.
.RE
.TP 4
.B
\fIversions() = [version()] <optional>\fR:
\fIversion() = v1 | v2 | v3\fR
.RS 4
.LP

.LP
Which SNMP versions shall be accepted/used\&.
.LP

.LP
Default is \fI[v1, v2, v3]\fR\&.
.RE
.TP 4
.B
\fIverbosity() = silence | info | log | debug | trace <optional>\fR:
Verbosity for a SNMP process\&. This specifies now much debug info is printed\&.
.RS 4
.LP

.LP
Default is \fIsilence\fR\&.
.RE
.TP 4
.B
\fIbind_to() = bool() <optional>\fR:
If \fItrue\fR, net_if binds to the IP address\&. If \fIfalse\fR, net_if listens on any IP address on the host where it is running\&. 
.RS 4
.LP

.LP
Default is \fIfalse\fR\&.
.RE
.TP 4
.B
\fIno_reuse() = bool() <optional>\fR:
If \fItrue\fR, net_if does not specify that the IP and port address should be reusable\&. If \fIfalse\fR, the address is set to reusable\&. 
.RS 4
.LP

.LP
Default is \fIfalse\fR\&.
.RE
.TP 4
.B
\fIrecbuf() = integer() <optional>\fR:
Receive buffer size\&. 
.RS 4
.LP

.LP
Default value is defined by \fIgen_udp\fR\&.
.RE
.TP 4
.B
\fIsndbuf() = integer() <optional>\fR:
Send buffer size\&. 
.RS 4
.LP

.LP
Default value is defined by \fIgen_udp\fR\&.
.RE
.TP 4
.B
\fInote_store() = [note_store_opt()] <optional>\fR:
\fInote_store_opt() = {timeout, note_store_timeout()} | {verbosity, verbosity()}\fR
.RS 4
.LP

.LP
Specifies the start-up verbosity for the SNMP note store\&.
.LP

.LP
For defaults see the options in \fInote_store_opt()\fR\&.
.RE
.TP 4
.B
\fInote_store_timeout() = integer() <optional>\fR:
Note cleanup time\&. When storing a note in the note store, each note is given lifetime\&. Every \fItimeout\fR the note_store process performs a GC to remove the expired note\&'s\&. Time in milli-seconds\&.
.RS 4
.LP

.LP
Default is \fI30000\fR\&.
.RE
.TP 4
.B
\fIaudit_trail_log() = [audit_trail_log_opt()] <optional>\fR:
\fIaudit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} | {size, atl_size()} | {repair, atl_repair()}\fR
.RS 4
.LP

.LP
If present, this option specifies the options for the audit trail logging\&. The \fIdisk_log\fR module is used to maintain a wrap log\&. If present, the \fIdir\fR and \fIsize\fR options are mandatory\&.
.LP

.LP
If not present, audit trail logging is not used\&.
.RE
.TP 4
.B
\fIatl_type() = read | write | read_write <optional>\fR:
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\&. 
.RS 4
.LP

.LP
For the agent:
.LP

.RS 2
.TP 2
*
If \fIwrite\fR is specified, only set requests are logged\&.
.TP 2
*
If \fIread\fR is specified, only get requests are logged\&.
.TP 2
*
If \fIread_write\fR, all requests are logged\&.
.RE
.LP

.LP
For the manager:
.LP

.RS 2
.TP 2
*
If \fIwrite\fR is specified, only sent messages are logged\&.
.TP 2
*
If \fIread\fR is specified, only received messages are logged\&.
.TP 2
*
If \fIread_write\fR, both outgoing and incoming messages are logged\&.
.RE
.LP

.LP
Default is \fIread_write\fR\&.
.RE
.TP 4
.B
\fIatl_dir = dir() <mandatory>\fR:
Specifies where the audit trail log should be stored\&.
.RS 4
.LP

.LP
If \fIaudit_trail_log\fR specifies that logging should take place, this parameter \fImust\fR be defined\&.
.RE
.TP 4
.B
\fIatl_size() = {integer(), integer()} <mandatory>\fR:
Specifies the size of the audit trail log\&. This parameter is sent to \fIdisk_log\fR\&. 
.RS 4
.LP

.LP
If \fIaudit_trail_log\fR specifies that logging should take place, this parameter \fImust\fR be defined\&.
.RE
.TP 4
.B
\fIatl_repair() = true | false | truncate | snmp_repair <optional>\fR:
Specifies if and how the audit trail log shall be repaired when opened\&. Unless this parameter has the value \fIsnmp_repair\fR it is sent to \fIdisk_log\fR\&. If, on the other hand, the value is \fIsnmp_repair\fR, snmp attempts to handle certain faults on it\&'s own\&. And even if it cannot repair the file, it does not truncate it directly, but instead \fImoves it aside\fR for later off-line analysis\&.
.RS 4
.LP

.LP
Default is \fItrue\fR\&.
.RE
.RE
.SH SEE ALSO
.LP
application(3), disk_log(3)