Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Thursday, June 13, 2019
 
 

snmp (7erl)

Name

snmp - The SNMP Application

Synopsis

Please see following description for synopsis

Description

Erlang Application Definition                                          snmp(7)



NAME
       snmp - The SNMP Application

DESCRIPTION
       This  chapter  describes the snmp application in OTP. The SNMP applica-
       tion 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  appli-
       cation.  Refer  to application(3) for more information about configura-
       tion parameters.

       The snmp part of the config file specifying the  configuration  parame-
       ters 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_discov-
           ery_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_discov-
         ery_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_discov-
         ery_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() <optional>:
           If  true, the agent is multi-threaded, with one thread for each get
           request.

           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 cre-
           ated 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()}

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

           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_mod-
           ule()}

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

           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_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  sym-
           bolic-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 sym-
           bolic-store) of the snmp agent uses this for  storage  of  miscela-
           neous 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_stor-
           age_mnesia.

           Default module is snmpa_mib_storage_ets.

         mib_storage_options() = list() <optional>:
           This  is  implementattion depended. That is, it depends on the mod-
           ule. 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,  ver-
           bosity()}    |    {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 dif-
           ferent 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  differ-
           ent 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() = integer() > 0 | infinity <optional>:
           When performing a GC, this is the max number of cache entries  that
           will be deleted from the cache.

           The reason for having this limit is that if the cache is large, the
           GC can potentially take a long time,  during  which  the  agent  is
           locked.

           Default is 100.

         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,  ver-
           bosity()}

           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.

         manager_config() = [manager_config_opt()] <mandatory>:
           manager_config_opt() = {dir, manager_config_dir()} | {db_dir,  man-
           ager_db_dir()}  |  {db_init_error, db_init_error()} | {repair, man-
           ager_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  (acknowledg-
             ment> to inform-request messages.

           * {user,  integer()}  - The manager will send response (acknowledg-
             ment) 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()} | {ver-
           bosity, 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,  man-
           ager_net_if_filter_options()}

           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_fil-
           ter_module()}

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

           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  behav-
           iour.

           Default is snmpm_net_if_filter.

         def_user_module() = atom() <optional>:
           The module implementing the default user. See the snmpm_user behav-
           iour.

           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.

         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) num-
           bered 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)



Ericsson AB                       snmp 5.2.11                          snmp(7)