1SNMP(7) Erlang Application Definition SNMP(7)
2
6 SNMP - The SNMP Application
7
9 This chapter describes the snmp application in OTP. The SNMP applica‐
10 tion provides the following services:
11 * a multilingual extensible SNMP agent
13 * a SNMP manager
15 * a MIB compiler
17
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 The snmp part of the config file specifying the configuration parame‐
24 ters is basically the following tuple:
25 {snmp, snmp_components_config()}
27 A minimal config file for starting a node with both a manager and an
30 agent:
31 [{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 Each snmp component has its own set of configuration parameters, even
43 though some of the types are common to both components.
44 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 Agent specific config options and types:
85 agent_type() = master | sub <optional>:
87 If master, one master agent is started. Otherwise, no agents are
88 started.
89 Default is master.
91 agent_discovery() = [agent_discovery_opt()] <optional>:
93 agent_discovery_opt() = {terminating, agent_terminating_discov‐
94 ery_opts()} | {originating, agent_originating_discovery_opts()}
95 The terminating options effects discovery initiated by a manager.
97 The originating options effects discovery initiated by this agent.
99 For defaults see the options in agent_discovery_opt().
101 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 These are options effecting discovery terminating in this agent
108 (i.e. initiated by a manager).
109 The default values for the terminating discovery options are:
111 * enable: true
113 * stage2: discovery
115 * trigger_username: ""
117 agent_originating_discovery_opts() = [agent_originating_discov‐
119 ery_opt()] <optional>:
120 agent_originating_discovery_opt() = {enable, boolean()}
121 These are options effecting discovery originating in this agent.
123 The default values for the originating discovery options are:
125 * enable: true
127 multi_threaded() = bool() <optional>:
129 If true, the agent is multi-threaded, with one thread for each get
130 request.
131 Default is false.
133 db_dir() = string() <mandatory>:
135 Defines where the SNMP agent internal db files are stored.
136 gb_max_vbs() = pos_integer() | infinity <optional>:
138 Defines the maximum number of varbinds allowed in a Get-BULK
139 response.
140 Default is 1000.
142 local_db() = [local_db_opt()] <optional>:
144 local_db_opt() = {repair, agent_repair()} | {auto_save,
145 agent_auto_save()} | {verbosity, verbosity()}
146 Defines options specific for the SNMP agent local database.
148 For defaults see the options in local_db_opt().
150 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 Default is true.
158 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 Default is 5000.
164 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 Defines options specific for the SNMP agent network interface
170 entity.
171 For defaults see the options in agent_net_if_opt().
173 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 Default is snmpa_net_if.
179 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 {extra_sock_opts, extra_socket_options()}
185 These options are actually specific to the used module. The ones
187 shown here are applicable to the default agent_net_if_module().
188 For defaults see the options in agent_net_if_option().
190 req_limit() = integer() | infinity <optional>:
192 Max number of simultaneous requests handled by the agent.
193 Default is infinity.
195 agent_net_if_filter_options() = [agent_net_if_filter_option()]
197 <optional>:
198 agent_net_if_filter_option() = {module, agent_net_if_filter_mod‐
199 ule()}
200 These options are actually specific to the used module. The ones
202 shown here are applicable to the default agent_net_if_filter_mod‐
203 ule().
204 For defaults see the options in agent_net_if_filter_option().
206 agent_net_if_filter_module() = atom() <optional>:
208 Module which handles the network interface filter part for the SNMP
209 agent. Must implement the snmpa_network_interface_filter behaviour.
210 Default is snmpa_net_if_filter.
212 agent_mibs() = [string()] <optional>:
214 Specifies a list of MIBs (including path) that defines which MIBs
215 are initially loaded into the SNMP master agent.
216 Note that the following mibs will always be loaded:
218 * version v1: STANDARD-MIB
220 * version v2: SNMPv2
222 * version v3: SNMPv2, SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB
224 Default is [].
226 mib_storage() = [mib_storage_opt()] <optional>:
228 mib_storage_opt() = {module, mib_storage_module()} | {options,
229 mib_storage_options()}
230 This option specifies how basic mib data is stored. This option is
232 used by two parts of the snmp agent: The mib-server and the sym‐
233 bolic-store.
234 Default is [{module, snmpa_mib_storage_ets}].
236 mib_storage_module() = snmpa_mib_data_ets | snmpa_mib_data_dets |
238 snmpa_mib_data_mnesia | module():
239 Defines the mib storage module of the SNMP agent as defined by the
240 snmpa_mib_storage behaviour.
241 Several entities (mib-server via the its data module and the sym‐
243 bolic-store) of the snmp agent uses this for storage of miscela‐
244 neous mib related data retrieved while loading a mib.
245 There are several implementations provided with the agent:
247 snmpa_mib_storage_ets, snmpa_mib_storage_dets and snmpa_mib_stor‐
248 age_mnesia.
249 Default module is snmpa_mib_storage_ets.
251 mib_storage_options() = list() <optional>:
253 This is implementattion depended. That is, it depends on the mod‐
254 ule. For each module a specific set of options are valid. For the
255 module provided with the app, these options are supported:
256 * snmpa_mib_storage_ets: {dir, filename()} | {action, keep |
258 clear}, {checksum, boolean()}
259 * dir - If present, points to a directory where a file to which
261 all data in the ets table is "synced".
262 Also, when a table is opened this file is read, if it exists.
264 By default, this will not be used.
266 * action - Specifies the behaviour when a non-empty file is
268 found: Keep its content or clear it out.
269 Default is keep.
271 * checksum - Defines if the file is checksummed or not.
273 Default is false.
275 * snmpa_mib_storage_dets: {dir, filename()} | {action, keep |
277 clear}, {auto_save, default | pos_integer()} | {repair, force |
278 boolean()}
279 * dir - This mandatory option points to a directory where to
281 place the file of a dets table.
282 * action - Specifies the behaviour when a non-empty file is
284 found: Keep its content or clear it out.
285 Default is keep.
287 * auto_save - Defines the dets auto-save frequency.
289 Default is default.
291 * repair - Defines the dets repair behaviour.
293 Default is false.
295 * snmpa_mib_storage_mnesia: {action, keep | clear}, {nodes,
297 [node()]}
298 * action - Specifies the behaviour when a non-empty, already
300 existing, table: Keep its content or clear it out.
301 Default is keep.
303 * nodes - A list of node names (or an atom describing a list of
305 nodes) defining where to open the table. Its up to the user to
306 ensure that mnesia is actually running on the specified nodes.
307 The following distinct values are recognised:
309 * [] - Translated into a list of the own node: [node()]
311 * all - erlang:nodes()
313 * visible - erlang:nodes(visible)
315 * connected - erlang:nodes(connected)
317 * db_nodes - mnesia:system_info(db_nodes)
319 Default is the result of the call: erlang:nodes().
321 mib_server() = [mib_server_opt()] <optional>:
323 mib_server_opt() = {mibentry_override, mibentry_override()} |
324 {trapentry_override, trapentry_override()} | {verbosity, ver‐
325 bosity()} | {cache, mibs_cache()} | {data_module,
326 mib_server_data_module()}
327 Defines options specific for the SNMP agent mib server.
329 For defaults see the options in mib_server_opt().
331 mibentry_override() = bool() <optional>:
333 If this value is false, then when loading a mib each mib- entry is
334 checked prior to installation of the mib. The purpose of the check
335 is to prevent that the same symbolic mibentry name is used for dif‐
336 ferent oid's.
337 Default is false.
339 trapentry_override() = bool() <optional>:
341 If this value is false, then when loading a mib each trap is
342 checked prior to installation of the mib. The purpose of the check
343 is to prevent that the same symbolic trap name is used for differ‐
344 ent trap's.
345 Default is false.
347 mib_server_data_module() = snmpa_mib_data_tttn | module() <optional>:
349 Defines the backend data module of the SNMP agent mib-server as
350 defined by the snmpa_mib_data behaviour.
351 At present only the default module is provided with the agent,
353 snmpa_mib_data_tttn.
354 Default module is snmpa_mib_data_tttn.
356 mibs_cache() = bool() | mibs_cache_opts() <optional>:
358 Shall the agent utilize the mib server lookup cache or not.
359 Default is true (in which case the mibs_cache_opts() default values
361 apply).
362 mibs_cache_opts() = [mibs_cache_opt()] <optional>:
364 mibs_cache_opt() = {autogc, mibs_cache_autogc()} | {gclimit,
365 mibs_cache_gclimit()} | {age, mibs_cache_age()}
366 Defines options specific for the SNMP agent mib server cache.
368 For defaults see the options in mibs_cache_opt().
370 mibs_cache_autogc() = bool() <optional>:
372 Defines if the mib server shall perform cache gc automatically or
373 leave it to the user (see gc_mibs_cache/0,1,2,3).
374 Default is true.
376 mibs_cache_age() = integer() > 0 <optional>:
378 Defines how old the entries in the cache will be allowed to become
379 before they are GC'ed (assuming GC is performed). Each entry in the
380 cache is "touched" whenever it is accessed.
381 The age is defined in milliseconds.
383 Default is 10 timutes.
385 mibs_cache_gclimit() = integer() > 0 | infinity <optional>:
387 When performing a GC, this is the max number of cache entries that
388 will be deleted from the cache.
389 The reason for having this limit is that if the cache is large, the
391 GC can potentially take a long time, during which the agent is
392 locked.
393 Default is 100.
395 error_report_mod() = atom() <optional>:
397 Defines an error report module, implementing the snmpa_error_report
398 behaviour. Two modules are provided with the toolkit:
399 snmpa_error_logger and snmpa_error_io.
400 Default is snmpa_error_logger.
402 symbolic_store() = [symbolic_store_opt()]:
404 symbolic_store_opt() = {verbosity, verbosity()}
405 Defines options specific for the SNMP agent symbolic store.
407 For defaults see the options in symbolic_store_opt().
409 target_cache() = [target_cache_opt()]:
411 target_cache_opt() = {verbosity, verbosity()}
412 Defines options specific for the SNMP agent target cache.
414 For defaults see the options in target_cache_opt().
416 agent_config() = [agent_config_opt()] <mandatory>:
418 agent_config_opt() = {dir, agent_config_dir()} | {force_load,
419 force_load()} | {verbosity, verbosity()}
420 Defines specific config related options for the SNMP agent.
422 For defaults see the options in agent_config_opt().
424 agent_config_dir = dir() <mandatory>:
426 Defines where the SNMP agent configuration files are stored.
427 force_load() = bool() <optional>:
429 If true the configuration files are re-read during start-up, and
430 the contents of the configuration database ignored. Thus, if true,
431 changes to the configuration database are lost upon reboot of the
432 agent.
433 Default is false.
435 Manager specific config options and types:
437 server() = [server_opt()] <optional>:
439 server_opt() = {timeout, server_timeout()} | {verbosity, ver‐
440 bosity()} | {cbproxy, server_cbproxy()} | {netif_sup, server_nis()}
441 Specifies the options for the manager server process.
443 Default is silence.
445 server_timeout() = integer() <optional>:
447 Asynchronous request cleanup time. For every requests, some info is
448 stored internally, in order to be able to deliver the reply (when
449 it arrives) to the proper destination. If the reply arrives, this
450 info will be deleted. But if there is no reply (in time), the info
451 has to be deleted after the best before time has been passed. This
452 cleanup will be performed at regular intervals, defined by the
453 server_timeout() time. The information will have an best before
454 time, defined by the Expire time given when calling the request
455 function (see async_get, async_get_next and async_set).
456 Time in milli-seconds.
458 Default is 30000.
460 server_cbproxy() = temporary (default) | permanent <optional>:
462 This option specifies how the server will handle callback calls.
463 temporary (default):
465 A temporary process will be created for each callback call.
466 permanent:
468 With this the server will create a permanent (named) process that
469 in effect serializes all callback calls.
470 Default is temporary.
472 server_nis() = none (default) | {PingTO, PongTO} <optional>:
474 This option specifies if the server should actively supervise the
475 net-if process. Note that this will only work if the used net-if
476 process actually supports the protocol. See snmpm_network_interface
477 behaviour for more info.
478 none (default):
480 No active supervision of the net-if process.
481 {PingTO :: pos_integer(), PongTO :: pos_integer()}:
483 The PingTO time specifies the between a successful ping (or
484 start) and the time when a ping message is to be sent to the net-
485 if process (basically the time between ping).
486 The PongTO time specifies how long time the net-if process has to
488 respond to a ping message, with a pong message. Its starts count‐
489 ing when the ping message has been sent.
490 Both times are in milli seconds.
492 Default is none.
494 manager_config() = [manager_config_opt()] <mandatory>:
496 manager_config_opt() = {dir, manager_config_dir()} | {db_dir, man‐
497 ager_db_dir()} | {db_init_error, db_init_error()} | {repair, man‐
498 ager_repair()} | {auto_save, manager_auto_save()} | {verbosity,
499 verbosity()}
500 Defines specific config related options for the SNMP manager.
502 For defaults see the options in manager_config_opt().
504 manager_config_dir = dir() <mandatory>:
506 Defines where the SNMP manager configuration files are stored.
507 manager_db_dir = dir() <mandatory>:
509 Defines where the SNMP manager store persistent data.
510 manager_repair() = false | true | force <optional>:
512 Defines the repair option for the persistent database (if and how
513 the table is repaired when opened).
514 Default is true.
516 manager_auto_save() = integer() | infinity <optional>:
518 The auto save interval. The table is flushed to disk whenever not
519 accessed for this amount of time.
520 Default is 5000.
522 manager_irb() = auto | user | {user, integer()} <optional>:
524 This option defines how the manager will handle the sending of
525 response (acknowledgment) to received inform-requests.
526 * auto - The manager will autonomously send response (acknowledg‐
528 ment> to inform-request messages.
529 * {user, integer()} - The manager will send response (acknowledg‐
531 ment) to inform-request messages when the handle_inform function
532 completes. The integer is the time, in milli-seconds, that the
533 manager will consider the stored inform-request info valid.
534 * user - Same as {user, integer()}, except that the default time,
536 15 seconds (15000), is used.
537 See snmpm_network_interface, handle_inform and definition of the
539 manager net if for more info.
540 Default is auto.
542 manager_mibs() = [string()] <optional>:
544 Specifies a list of MIBs (including path) and defines which MIBs
545 are initially loaded into the SNMP manager.
546 Default is [].
548 manager_net_if() = [manager_net_if_opt()] <optional>:
550 manager_net_if_opt() = {module, manager_net_if_module()} | {ver‐
551 bosity, verbosity()} | {options, manager_net_if_options()}
552 Defines options specific for the SNMP manager network interface
554 entity.
555 For defaults see the options in manager_net_if_opt().
557 manager_net_if_options() = [manager_net_if_option()] <optional>:
559 manager_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()}
560 | {recbuf, recbuf()} | {no_reuse, no_reuse()} | {filter, man‐
561 ager_net_if_filter_options()} | {extra_sock_opts,
562 extra_socket_options()}
563 These options are actually specific to the used module. The ones
565 shown here are applicable to the default manager_net_if_module().
566 For defaults see the options in manager_net_if_option().
568 manager_net_if_module() = atom() <optional>:
570 The module which handles the network interface part for the SNMP
571 manager. It must implement the snmpm_network_interface behaviour.
572 Default is snmpm_net_if.
574 manager_net_if_filter_options() = [manager_net_if_filter_option()]
576 <optional>:
577 manager_net_if_filter_option() = {module, manager_net_if_fil‐
578 ter_module()}
579 These options are actually specific to the used module. The ones
581 shown here are applicable to the default manager_net_if_filter_mod‐
582 ule().
583 For defaults see the options in manager_net_if_filter_option().
585 manager_net_if_filter_module() = atom() <optional>:
587 Module which handles the network interface filter part for the SNMP
588 manager. Must implement the snmpm_network_interface_filter behav‐
589 iour.
590 Default is snmpm_net_if_filter.
592 def_user_module() = atom() <optional>:
594 The module implementing the default user. See the snmpm_user behav‐
595 iour.
596 Default is snmpm_user_default.
598 def_user_data() = term() <optional>:
600 Data for the default user. Passed to the user module when calling
601 the callback functions.
602 Default is undefined.
604 Common config types:
606 restart_type() = permanent | transient | temporary:
608 See supervisor documentation for more info.
609 Default is permanent for the agent and transient for the manager.
611 db_init_error() = terminate | create | create_db_and_dir:
613 Defines what to do if the agent or manager is unable to open an
614 existing database file. terminate means that the agent/manager will
615 terminate and create means that the agent/manager will remove the
616 faulty file(s) and create new ones, and create_db_and_dir means
617 that the agent/manager will create the database file along with any
618 missing parent directories for the database file.
619 Default is terminate.
621 priority() = atom() <optional>:
623 Defines the Erlang priority for all SNMP processes.
624 Default is normal.
626 versions() = [version()] <optional>:
628 version() = v1 | v2 | v3
629 Which SNMP versions shall be accepted/used.
631 Default is [v1,v2,v3].
633 verbosity() = silence | info | log | debug | trace <optional>:
635 Verbosity for a SNMP process. This specifies now much debug info is
636 printed.
637 Default is silence.
639 bind_to() = bool() <optional>:
641 If true, net_if binds to the IP address. If false, net_if listens
642 on any IP address on the host where it is running.
643 Default is false.
645 no_reuse() = bool() <optional>:
647 If true, net_if does not specify that the IP and port address
648 should be reusable. If false, the address is set to reusable.
649 Default is false.
651 recbuf() = integer() <optional>:
653 Receive buffer size.
654 Default value is defined by gen_udp.
656 sndbuf() = integer() <optional>:
658 Send buffer size.
659 Default value is defined by gen_udp.
661 extra_socket_options() = list() <optional>:
663 A list of arbitrary socket options.
664 This list is not inspected by snmp (other then checking that its a
666 list). Its the users responsibility to ensure that these are valid
667 options and does not conflict with the "normal" options.
668 Default is [].
670 note_store() = [note_store_opt()] <optional>:
672 note_store_opt() = {timeout, note_store_timeout()} | {verbosity,
673 verbosity()}
674 Specifies the start-up verbosity for the SNMP note store.
676 For defaults see the options in note_store_opt().
678 note_store_timeout() = integer() <optional>:
680 Note cleanup time. When storing a note in the note store, each note
681 is given lifetime. Every timeout the note_store process performs a
682 GC to remove the expired note's. Time in milli-seconds.
683 Default is 30000.
685 audit_trail_log() = [audit_trail_log_opt()] <optional>:
687 audit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} |
688 {size, atl_size()} | {repair, atl_repair()} | {seqno, atl_seqno()}
689 If present, this option specifies the options for the audit trail
691 logging. The disk_log module is used to maintain a wrap log. If
692 present, the dir and size options are mandatory.
693 If not present, audit trail logging is not used.
695 atl_type() = read | write | read_write <optional>:
697 Specifies what type of an audit trail log should be used. The
698 effect of the type is actually different for the the agent and the
699 manager.
700 For the agent:
702 * If write is specified, only set requests are logged.
704 * If read is specified, only get requests are logged.
706 * If read_write, all requests are logged.
708 For the manager:
710 * If write is specified, only sent messages are logged.
712 * If read is specified, only received messages are logged.
714 * If read_write, both outgoing and incoming messages are logged.
716 Default is read_write.
718 atl_dir = dir() <mandatory>:
720 Specifies where the audit trail log should be stored.
721 If audit_trail_log specifies that logging should take place, this
723 parameter must be defined.
724 atl_size() = {integer(), integer()} <mandatory>:
726 Specifies the size of the audit trail log. This parameter is sent
727 to disk_log.
728 If audit_trail_log specifies that logging should take place, this
730 parameter must be defined.
731 atl_repair() = true | false | truncate | snmp_repair <optional>:
733 Specifies if and how the audit trail log shall be repaired when
734 opened. Unless this parameter has the value snmp_repair it is sent
735 to disk_log. If, on the other hand, the value is snmp_repair, snmp
736 attempts to handle certain faults on its own. And even if it cannot
737 repair the file, it does not truncate it directly, but instead
738 moves it aside for later off-line analysis.
739 Default is true.
741 atl_seqno() = true | false <optional>:
743 Specifies if the audit trail log entries will be (sequence) num‐
744 bered or not. The range of the sequence numbers are according to
745 RFC 5424, i.e. 1 through 2147483647.
746 Default is false.
748
750 application(3), disk_log(3)
751Ericsson AB snmp 5.5 SNMP(7)