1snmp(7)                  Erlang Application Definition                 snmp(7)
2
3
4

NAME

6       snmp - The SNMP Application
7

DESCRIPTION

9       This  chapter  describes the snmp application in OTP. The SNMP applica‐
10       tion provides the following services:
11
12         * a multilingual extensible SNMP agent
13
14         * a SNMP manager
15
16         * a MIB compiler
17

CONFIGURATION

19       The following configuration parameters are defined for the SNMP  appli‐
20       cation.  Refer  to application(3) for more information about configura‐
21       tion parameters.
22
23       The snmp part of the config file specifying the  configuration  parame‐
24       ters is basically the following tuple:
25
26             {snmp, snmp_components_config()}
27
28
29       A  minimal  config  file for starting a node with both a manager and an
30       agent:
31
32             [{snmp,
33               [{agent, [{db_dir, "/tmp/snmp/agent/db"},
34                         {config, [{dir, "/tmp/snmp/agent/conf"}]}]},
35                {manager, [{config, [{dir, "/tmp/snmp/manager/conf"},
36                                     {db_dir, "/tmp/snmp/manager/db"}]}]}]}
37               ]
38              }
39             ].
40
41
42       Each snmp component has its own set of configuration  parameters,  even
43       though some of the types are common to both components.
44
45             snmp_components_config() -> [snmp_component_config()]
46             snmp_component_config() -> {agent, agent_options()} | {manager, manager_options()}
47             agent_options() = [agent_option()]
48             agent_option() = {restart_type,     restart_type()}     |
49                              {agent_type,       agent_type()}       |
50                              {agent_verbosity,  verbosity()}        |
51                              {discovery,        agent_discovery()}  |
52                              {versions,         versions()}         |
53                              {gb_max_vbs,       gb_max_vbs()}       |
54                              {priority,         priority()}         |
55                              {multi_threaded,   multi_threaded()}   |
56                              {db_dir,           db_dir()}           |
57                              {db_init_error,    db_init_error()}    |
58                              {local_db,         local_db()}         |
59                              {net_if,           agent_net_if()}     |
60                              {mibs,             mibs()}             |
61                              {mib_storage,      mib_storage()}      |
62                              {mib_server,       mib_server()}       |
63                              {audit_trail_log,  audit_trail_log()}  |
64                              {error_report_mod, error_report_mod()} |
65                              {note_store,       note_store()}       |
66                              {symbolic_store,   symbolic_store()}   |
67                              {target_cache,     target_cache()}     |
68                              {config,           agent_config()}
69             manager_options() = [manager_option()]
70             manager_option() = {restart_type,             restart_type()}    |
71                                {net_if,                   manager_net_if()}  |
72                                {server,                   server()}          |
73                                {note_store,               note_store()}      |
74                                {config,                   manager_config()}  |
75                                {inform_request_behaviour, manager_irb()}     |
76                                {mibs,                     manager_mibs()}    |
77                                {priority,                 priority()}        |
78                                {audit_trail_log,          audit_trail_log()} |
79                                {versions,                 versions()}        |
80                                {def_user_mod,             def_user_module()  |
81                                {def_user_data,            def_user_data()}
82
83
84       Agent specific config options and types:
85
86         agent_type() = master | sub <optional>:
87           If  master,  one  master agent is started. Otherwise, no agents are
88           started.
89
90           Default is master.
91
92         agent_discovery() = [agent_discovery_opt()] <optional>:
93           agent_discovery_opt()  =  {terminating,   agent_terminating_discov‐
94           ery_opts()} | {originating, agent_originating_discovery_opts()}
95
96           The terminating options effects discovery initiated by a manager.
97
98           The originating options effects discovery initiated by this agent.
99
100           For defaults see the options in agent_discovery_opt().
101
102         agent_terminating_discovery_opts()    =    [agent_terminating_discov‐
103         ery_opt()] <optional>:
104           agent_terminating_discovery_opt() = {enable, boolean()} |  {stage2,
105           discovery | plain} | {trigger_username, string()}
106
107           These  are  options  effecting  discovery terminating in this agent
108           (i.e. initiated by a manager).
109
110           The default values for the terminating discovery options are:
111
112           * enable: true
113
114           * stage2: discovery
115
116           * trigger_username: ""
117
118         agent_originating_discovery_opts()    =    [agent_originating_discov‐
119         ery_opt()] <optional>:
120           agent_originating_discovery_opt() = {enable, boolean()}
121
122           These are options effecting discovery originating in this agent.
123
124           The default values for the originating discovery options are:
125
126           * enable: true
127
128         multi_threaded() = bool() <optional>:
129           If  true, the agent is multi-threaded, with one thread for each get
130           request.
131
132           Default is false.
133
134         db_dir() = string() <mandatory>:
135           Defines where the SNMP agent internal db files are stored.
136
137         gb_max_vbs() = pos_integer() | infinity <optional>:
138           Defines the maximum  number  of  varbinds  allowed  in  a  Get-BULK
139           response.
140
141           Default is 1000.
142
143         local_db() = [local_db_opt()] <optional>:
144           local_db_opt()    =    {repair,   agent_repair()}   |   {auto_save,
145           agent_auto_save()} | {verbosity, verbosity()}
146
147           Defines options specific for the SNMP agent local database.
148
149           For defaults see the options in local_db_opt().
150
151         agent_repair() = false | true | force <optional>:
152           When starting snmpa_local_db it always tries to  open  an  existing
153           database.  If  false, and some errors occur, a new database is cre‐
154           ated instead. If true, an existing file will be repaired. If force,
155           the table will be repaired even if it was properly closed.
156
157           Default is true.
158
159         agent_auto_save() = integer() | infinity <optional>:
160           The  auto  save interval. The table is flushed to disk whenever not
161           accessed for this amount of time.
162
163           Default is 5000.
164
165         agent_net_if() = [agent_net_if_opt()] <optional>:
166           agent_net_if_opt() = {module, agent_net_if_module()} |  {verbosity,
167           verbosity()} | {options, agent_net_if_options()}
168
169           Defines  options  specific  for  the  SNMP  agent network interface
170           entity.
171
172           For defaults see the options in agent_net_if_opt().
173
174         agent_net_if_module() = atom() <optional>:
175           Module which handles the network interface part for the SNMP agent.
176           Must implement the snmpa_network_interface behaviour.
177
178           Default is snmpa_net_if.
179
180         agent_net_if_options() = [agent_net_if_option()] <optional>:
181           agent_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()} |
182           {recbuf,  recbuf()}  |   {no_reuse,   no_reuse()}   |   {req_limit,
183           req_limit()} | {filter, agent_net_if_filter_options()}
184
185           These  options  are  actually specific to the used module. The ones
186           shown here are applicable to the default agent_net_if_module().
187
188           For defaults see the options in agent_net_if_option().
189
190         req_limit() = integer() | infinity <optional>:
191           Max number of simultaneous requests handled by the agent.
192
193           Default is infinity.
194
195         agent_net_if_filter_options()    =     [agent_net_if_filter_option()]
196         <optional>:
197           agent_net_if_filter_option()  =  {module,  agent_net_if_filter_mod‐
198           ule()}
199
200           These options are actually specific to the used  module.  The  ones
201           shown  here  are applicable to the default agent_net_if_filter_mod‐
202           ule().
203
204           For defaults see the options in agent_net_if_filter_option().
205
206         agent_net_if_filter_module() = atom() <optional>:
207           Module which handles the network interface filter part for the SNMP
208           agent. Must implement the snmpa_network_interface_filter behaviour.
209
210           Default is snmpa_net_if_filter.
211
212         agent_mibs() = [string()] <optional>:
213           Specifies  a  list of MIBs (including path) that defines which MIBs
214           are initially loaded into the SNMP master agent.
215
216           Note that the following mibs will always be loaded:
217
218           * version v1: STANDARD-MIB
219
220           * version v2: SNMPv2
221
222           * version v3: SNMPv2, SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB
223
224           Default is [].
225
226         mib_storage() = [mib_storage_opt()] <optional>:
227           mib_storage_opt()  =  {module,  mib_storage_module()}  |  {options,
228           mib_storage_options()}
229
230           This  option specifies how basic mib data is stored. This option is
231           used by two parts of the snmp agent: The mib-server  and  the  sym‐
232           bolic-store.
233
234           Default is [{module, snmpa_mib_storage_ets}].
235
236         mib_storage_module()  =  snmpa_mib_data_ets  |  snmpa_mib_data_dets |
237         snmpa_mib_data_mnesia | module():
238           Defines the mib storage module of the SNMP agent as defined by  the
239           snmpa_mib_storage behaviour.
240
241           Several  entities  (mib-server via the its data module and the sym‐
242           bolic-store) of the snmp agent uses this for  storage  of  miscela‐
243           neous mib related data retrieved while loading a mib.
244
245           There   are   several  implementations  provided  with  the  agent:
246           snmpa_mib_storage_ets, snmpa_mib_storage_dets  and  snmpa_mib_stor‐
247           age_mnesia.
248
249           Default module is snmpa_mib_storage_ets.
250
251         mib_storage_options() = list() <optional>:
252           This  is  implementattion depended. That is, it depends on the mod‐
253           ule. For each module a specific set of options are valid.  For  the
254           module provided with the app, these options are supported:
255
256           * snmpa_mib_storage_ets:   {dir,  filename()}  |  {action,  keep  |
257             clear}, {checksum, boolean()}
258
259             * dir - If present, points to a directory where a file  to  which
260               all data in the ets table is "synced".
261
262               Also, when a table is opened this file is read, if it exists.
263
264               By default, this will not be used.
265
266             * action  -  Specifies  the  behaviour  when  a non-empty file is
267               found: Keep its content or clear it out.
268
269               Default is keep.
270
271             * checksum - Defines if the file is checksummed or not.
272
273               Default is false.
274
275           * snmpa_mib_storage_dets:  {dir,  filename()}  |  {action,  keep  |
276             clear},  {auto_save,  default | pos_integer()} | {repair, force |
277             boolean()}
278
279             * dir - This mandatory option points  to  a  directory  where  to
280               place the file of a dets table.
281
282             * action  -  Specifies  the  behaviour  when  a non-empty file is
283               found: Keep its content or clear it out.
284
285               Default is keep.
286
287             * auto_save - Defines the dets auto-save frequency.
288
289               Default is default.
290
291             * repair - Defines the dets repair behaviour.
292
293               Default is false.
294
295           * snmpa_mib_storage_mnesia:  {action,  keep   |   clear},   {nodes,
296             [node()]}
297
298             * action  -  Specifies  the  behaviour  when a non-empty, already
299               existing, table: Keep its content or clear it out.
300
301               Default is keep.
302
303             * nodes - A list of node names (or an atom describing a  list  of
304               nodes)  defining where to open the table. Its up to the user to
305               ensure that mnesia is actually running on the specified nodes.
306
307               The following distinct values are recognised:
308
309               * [] - Translated into a list of the own node: [node()]
310
311               * all - erlang:nodes()
312
313               * visible - erlang:nodes(visible)
314
315               * connected - erlang:nodes(connected)
316
317               * db_nodes - mnesia:system_info(db_nodes)
318
319               Default is the result of the call: erlang:nodes().
320
321         mib_server() = [mib_server_opt()] <optional>:
322           mib_server_opt()  =  {mibentry_override,   mibentry_override()}   |
323           {trapentry_override,   trapentry_override()}   |  {verbosity,  ver‐
324           bosity()}    |    {cache,     mibs_cache()}     |     {data_module,
325           mib_server_data_module()}
326
327           Defines options specific for the SNMP agent mib server.
328
329           For defaults see the options in mib_server_opt().
330
331         mibentry_override() = bool() <optional>:
332           If  this value is false, then when loading a mib each mib- entry is
333           checked prior to installation of the mib. The purpose of the  check
334           is to prevent that the same symbolic mibentry name is used for dif‐
335           ferent oid's.
336
337           Default is false.
338
339         trapentry_override() = bool() <optional>:
340           If this value is false, then  when  loading  a  mib  each  trap  is
341           checked  prior to installation of the mib. The purpose of the check
342           is to prevent that the same symbolic trap name is used for  differ‐
343           ent trap's.
344
345           Default is false.
346
347         mib_server_data_module() = snmpa_mib_data_tttn | module() <optional>:
348           Defines  the  backend  data  module of the SNMP agent mib-server as
349           defined by the snmpa_mib_data behaviour.
350
351           At present only the default module  is  provided  with  the  agent,
352           snmpa_mib_data_tttn.
353
354           Default module is snmpa_mib_data_tttn.
355
356         mibs_cache() = bool() | mibs_cache_opts() <optional>:
357           Shall the agent utilize the mib server lookup cache or not.
358
359           Default is true (in which case the mibs_cache_opts() default values
360           apply).
361
362         mibs_cache_opts() = [mibs_cache_opt()] <optional>:
363           mibs_cache_opt()  =  {autogc,  mibs_cache_autogc()}   |   {gclimit,
364           mibs_cache_gclimit()} | {age, mibs_cache_age()}
365
366           Defines options specific for the SNMP agent mib server cache.
367
368           For defaults see the options in mibs_cache_opt().
369
370         mibs_cache_autogc() = bool() <optional>:
371           Defines  if  the mib server shall perform cache gc automatically or
372           leave it to the user (see gc_mibs_cache/0,1,2,3).
373
374           Default is true.
375
376         mibs_cache_age() = integer() > 0 <optional>:
377           Defines how old the entries in the cache will be allowed to  become
378           before they are GC'ed (assuming GC is performed). Each entry in the
379           cache is "touched" whenever it is accessed.
380
381           The age is defined in milliseconds.
382
383           Default is 10 timutes.
384
385         mibs_cache_gclimit() = integer() > 0 | infinity <optional>:
386           When performing a GC, this is the max number of cache entries  that
387           will be deleted from the cache.
388
389           The reason for having this limit is that if the cache is large, the
390           GC can potentially take a long time,  during  which  the  agent  is
391           locked.
392
393           Default is 100.
394
395         error_report_mod() = atom() <optional>:
396           Defines an error report module, implementing the snmpa_error_report
397           behaviour.   Two   modules   are   provided   with   the   toolkit:
398           snmpa_error_logger and snmpa_error_io.
399
400           Default is snmpa_error_logger.
401
402         symbolic_store() = [symbolic_store_opt()]:
403           symbolic_store_opt() = {verbosity, verbosity()}
404
405           Defines options specific for the SNMP agent symbolic store.
406
407           For defaults see the options in symbolic_store_opt().
408
409         target_cache() = [target_cache_opt()]:
410           target_cache_opt() = {verbosity, verbosity()}
411
412           Defines options specific for the SNMP agent target cache.
413
414           For defaults see the options in target_cache_opt().
415
416         agent_config() = [agent_config_opt()] <mandatory>:
417           agent_config_opt()   =  {dir,  agent_config_dir()}  |  {force_load,
418           force_load()} | {verbosity, verbosity()}
419
420           Defines specific config related options for the SNMP agent.
421
422           For defaults see the options in agent_config_opt().
423
424         agent_config_dir = dir() <mandatory>:
425           Defines where the SNMP agent configuration files are stored.
426
427         force_load() = bool() <optional>:
428           If true the configuration files are re-read  during  start-up,  and
429           the  contents of the configuration database ignored. Thus, if true,
430           changes to the configuration database are lost upon reboot  of  the
431           agent.
432
433           Default is false.
434
435       Manager specific config options and types:
436
437         server() = [server_opt()] <optional>:
438           server_opt()  =  {timeout,  server_timeout()}  |  {verbosity,  ver‐
439           bosity()}
440
441           Specifies the options for the manager server process.
442
443           Default is silence.
444
445         server_timeout() = integer() <optional>:
446           Asynchronous request cleanup time. For every requests, some info is
447           stored  internally,  in order to be able to deliver the reply (when
448           it arrives) to the proper destination. If the reply  arrives,  this
449           info  will be deleted. But if there is no reply (in time), the info
450           has to be deleted after the best before time has been passed.  This
451           cleanup  will  be  performed  at  regular intervals, defined by the
452           server_timeout() time. The information will  have  an  best  before
453           time,  defined  by  the  Expire time given when calling the request
454           function (see async_get, async_get_next and async_set).
455
456           Time in milli-seconds.
457
458           Default is 30000.
459
460         manager_config() = [manager_config_opt()] <mandatory>:
461           manager_config_opt() = {dir, manager_config_dir()} | {db_dir,  man‐
462           ager_db_dir()}  |  {db_init_error, db_init_error()} | {repair, man‐
463           ager_repair()} |  {auto_save,  manager_auto_save()}  |  {verbosity,
464           verbosity()}
465
466           Defines specific config related options for the SNMP manager.
467
468           For defaults see the options in manager_config_opt().
469
470         manager_config_dir = dir() <mandatory>:
471           Defines where the SNMP manager configuration files are stored.
472
473         manager_db_dir = dir() <mandatory>:
474           Defines where the SNMP manager store persistent data.
475
476         manager_repair() = false | true | force <optional>:
477           Defines  the  repair option for the persistent database (if and how
478           the table is repaired when opened).
479
480           Default is true.
481
482         manager_auto_save() = integer() | infinity <optional>:
483           The auto save interval. The table is flushed to disk  whenever  not
484           accessed for this amount of time.
485
486           Default is 5000.
487
488         manager_irb() = auto | user | {user, integer()} <optional>:
489           This  option  defines  how  the  manager will handle the sending of
490           response (acknowledgment) to received inform-requests.
491
492           * auto - The manager will autonomously send  response  (acknowledg‐
493             ment> to inform-request messages.
494
495           * {user,  integer()}  - The manager will send response (acknowledg‐
496             ment) to inform-request messages when the handle_inform  function
497             completes.  The  integer  is the time, in milli-seconds, that the
498             manager will consider the stored inform-request info valid.
499
500           * user - Same as {user, integer()}, except that the  default  time,
501             15 seconds (15000), is used.
502
503           See  snmpm_network_interface,  handle_inform  and definition of the
504           manager net if for more info.
505
506           Default is auto.
507
508         manager_mibs() = [string()] <optional>:
509           Specifies a list of MIBs (including path) and  defines  which  MIBs
510           are initially loaded into the SNMP manager.
511
512           Default is [].
513
514         manager_net_if() = [manager_net_if_opt()] <optional>:
515           manager_net_if_opt()  =  {module,  manager_net_if_module()} | {ver‐
516           bosity, verbosity()} | {options, manager_net_if_options()}
517
518           Defines options specific for the  SNMP  manager  network  interface
519           entity.
520
521           For defaults see the options in manager_net_if_opt().
522
523         manager_net_if_options() = [manager_net_if_option()] <optional>:
524           manager_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()}
525           | {recbuf, recbuf()}  |  {no_reuse,  no_reuse()}  |  {filter,  man‐
526           ager_net_if_filter_options()}
527
528           These  options  are  actually specific to the used module. The ones
529           shown here are applicable to the default manager_net_if_module().
530
531           For defaults see the options in manager_net_if_option().
532
533         manager_net_if_module() = atom() <optional>:
534           The module which handles the network interface part  for  the  SNMP
535           manager. It must implement the snmpm_network_interface behaviour.
536
537           Default is snmpm_net_if.
538
539         manager_net_if_filter_options()   =  [manager_net_if_filter_option()]
540         <optional>:
541           manager_net_if_filter_option()   =   {module,   manager_net_if_fil‐
542           ter_module()}
543
544           These  options  are  actually specific to the used module. The ones
545           shown here are applicable to the default manager_net_if_filter_mod‐
546           ule().
547
548           For defaults see the options in manager_net_if_filter_option().
549
550         manager_net_if_filter_module() = atom() <optional>:
551           Module which handles the network interface filter part for the SNMP
552           manager. Must implement the  snmpm_network_interface_filter  behav‐
553           iour.
554
555           Default is snmpm_net_if_filter.
556
557         def_user_module() = atom() <optional>:
558           The module implementing the default user. See the snmpm_user behav‐
559           iour.
560
561           Default is snmpm_user_default.
562
563         def_user_data() = term() <optional>:
564           Data for the default user. Passed to the user module  when  calling
565           the callback functions.
566
567           Default is undefined.
568
569       Common config types:
570
571         restart_type() = permanent | transient | temporary:
572           See supervisor documentation for more info.
573
574           Default is permanent for the agent and transient for the manager.
575
576         db_init_error() = terminate | create | create_db_and_dir:
577           Defines  what  to  do  if the agent or manager is unable to open an
578           existing database file. terminate means that the agent/manager will
579           terminate  and  create means that the agent/manager will remove the
580           faulty file(s) and create new  ones,  and  create_db_and_dir  means
581           that the agent/manager will create the database file along with any
582           missing parent directories for the database file.
583
584           Default is terminate.
585
586         priority() = atom() <optional>:
587           Defines the Erlang priority for all SNMP processes.
588
589           Default is normal.
590
591         versions() = [version()] <optional>:
592           version() = v1 | v2 | v3
593
594           Which SNMP versions shall be accepted/used.
595
596           Default is [v1,v2,v3].
597
598         verbosity() = silence | info | log | debug | trace <optional>:
599           Verbosity for a SNMP process. This specifies now much debug info is
600           printed.
601
602           Default is silence.
603
604         bind_to() = bool() <optional>:
605           If  true,  net_if binds to the IP address. If false, net_if listens
606           on any IP address on the host where it is running.
607
608           Default is false.
609
610         no_reuse() = bool() <optional>:
611           If true, net_if does not specify  that  the  IP  and  port  address
612           should be reusable. If false, the address is set to reusable.
613
614           Default is false.
615
616         recbuf() = integer() <optional>:
617           Receive buffer size.
618
619           Default value is defined by gen_udp.
620
621         sndbuf() = integer() <optional>:
622           Send buffer size.
623
624           Default value is defined by gen_udp.
625
626         note_store() = [note_store_opt()] <optional>:
627           note_store_opt()  =  {timeout,  note_store_timeout()} | {verbosity,
628           verbosity()}
629
630           Specifies the start-up verbosity for the SNMP note store.
631
632           For defaults see the options in note_store_opt().
633
634         note_store_timeout() = integer() <optional>:
635           Note cleanup time. When storing a note in the note store, each note
636           is  given lifetime. Every timeout the note_store process performs a
637           GC to remove the expired note's. Time in milli-seconds.
638
639           Default is 30000.
640
641         audit_trail_log() = [audit_trail_log_opt()] <optional>:
642           audit_trail_log_opt() = {type, atl_type()}  |  {dir,  atl_dir()}  |
643           {size, atl_size()} | {repair, atl_repair()} | {seqno, atl_seqno()}
644
645           If  present,  this option specifies the options for the audit trail
646           logging. The disk_log module is used to maintain  a  wrap  log.  If
647           present, the dir and size options are mandatory.
648
649           If not present, audit trail logging is not used.
650
651         atl_type() = read | write | read_write <optional>:
652           Specifies  what  type  of  an  audit  trail log should be used. The
653           effect of the type is actually different for the the agent and  the
654           manager.
655
656           For the agent:
657
658           * If write is specified, only set requests are logged.
659
660           * If read is specified, only get requests are logged.
661
662           * If read_write, all requests are logged.
663
664           For the manager:
665
666           * If write is specified, only sent messages are logged.
667
668           * If read is specified, only received messages are logged.
669
670           * If read_write, both outgoing and incoming messages are logged.
671
672           Default is read_write.
673
674         atl_dir = dir() <mandatory>:
675           Specifies where the audit trail log should be stored.
676
677           If  audit_trail_log  specifies that logging should take place, this
678           parameter must be defined.
679
680         atl_size() = {integer(), integer()} <mandatory>:
681           Specifies the size of the audit trail log. This parameter  is  sent
682           to disk_log.
683
684           If  audit_trail_log  specifies that logging should take place, this
685           parameter must be defined.
686
687         atl_repair() = true | false | truncate | snmp_repair <optional>:
688           Specifies if and how the audit trail log  shall  be  repaired  when
689           opened.  Unless this parameter has the value snmp_repair it is sent
690           to disk_log. If, on the other hand, the value is snmp_repair,  snmp
691           attempts to handle certain faults on its own. And even if it cannot
692           repair the file, it does not  truncate  it  directly,  but  instead
693           moves it aside for later off-line analysis.
694
695           Default is true.
696
697         atl_seqno() = true | false <optional>:
698           Specifies  if  the  audit trail log entries will be (sequence) num‐
699           bered or not. The range of the sequence numbers  are  according  to
700           RFC 5424, i.e. 1 through 2147483647.
701
702           Default is false.
703

SEE ALSO

705       application(3), disk_log(3)
706
707
708
709Ericsson AB                       snmp 5.2.12                          snmp(7)
Impressum