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()}
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 manager_config() = [manager_config_opt()] <mandatory>:
462 manager_config_opt() = {dir, manager_config_dir()} | {db_dir, man‐
463 ager_db_dir()} | {db_init_error, db_init_error()} | {repair, man‐
464 ager_repair()} | {auto_save, manager_auto_save()} | {verbosity,
465 verbosity()}
466 Defines specific config related options for the SNMP manager.
468 For defaults see the options in manager_config_opt().
470 manager_config_dir = dir() <mandatory>:
472 Defines where the SNMP manager configuration files are stored.
473 manager_db_dir = dir() <mandatory>:
475 Defines where the SNMP manager store persistent data.
476 manager_repair() = false | true | force <optional>:
478 Defines the repair option for the persistent database (if and how
479 the table is repaired when opened).
480 Default is true.
482 manager_auto_save() = integer() | infinity <optional>:
484 The auto save interval. The table is flushed to disk whenever not
485 accessed for this amount of time.
486 Default is 5000.
488 manager_irb() = auto | user | {user, integer()} <optional>:
490 This option defines how the manager will handle the sending of
491 response (acknowledgment) to received inform-requests.
492 * auto - The manager will autonomously send response (acknowledg‐
494 ment> to inform-request messages.
495 * {user, integer()} - The manager will send response (acknowledg‐
497 ment) to inform-request messages when the handle_inform function
498 completes. The integer is the time, in milli-seconds, that the
499 manager will consider the stored inform-request info valid.
500 * user - Same as {user, integer()}, except that the default time,
502 15 seconds (15000), is used.
503 See snmpm_network_interface, handle_inform and definition of the
505 manager net if for more info.
506 Default is auto.
508 manager_mibs() = [string()] <optional>:
510 Specifies a list of MIBs (including path) and defines which MIBs
511 are initially loaded into the SNMP manager.
512 Default is [].
514 manager_net_if() = [manager_net_if_opt()] <optional>:
516 manager_net_if_opt() = {module, manager_net_if_module()} | {ver‐
517 bosity, verbosity()} | {options, manager_net_if_options()}
518 Defines options specific for the SNMP manager network interface
520 entity.
521 For defaults see the options in manager_net_if_opt().
523 manager_net_if_options() = [manager_net_if_option()] <optional>:
525 manager_net_if_option() = {bind_to, bind_to()} | {sndbuf, sndbuf()}
526 | {recbuf, recbuf()} | {no_reuse, no_reuse()} | {filter, man‐
527 ager_net_if_filter_options()} | {extra_sock_opts,
528 extra_socket_options()}
529 These options are actually specific to the used module. The ones
531 shown here are applicable to the default manager_net_if_module().
532 For defaults see the options in manager_net_if_option().
534 manager_net_if_module() = atom() <optional>:
536 The module which handles the network interface part for the SNMP
537 manager. It must implement the snmpm_network_interface behaviour.
538 Default is snmpm_net_if.
540 manager_net_if_filter_options() = [manager_net_if_filter_option()]
542 <optional>:
543 manager_net_if_filter_option() = {module, manager_net_if_fil‐
544 ter_module()}
545 These options are actually specific to the used module. The ones
547 shown here are applicable to the default manager_net_if_filter_mod‐
548 ule().
549 For defaults see the options in manager_net_if_filter_option().
551 manager_net_if_filter_module() = atom() <optional>:
553 Module which handles the network interface filter part for the SNMP
554 manager. Must implement the snmpm_network_interface_filter behav‐
555 iour.
556 Default is snmpm_net_if_filter.
558 def_user_module() = atom() <optional>:
560 The module implementing the default user. See the snmpm_user behav‐
561 iour.
562 Default is snmpm_user_default.
564 def_user_data() = term() <optional>:
566 Data for the default user. Passed to the user module when calling
567 the callback functions.
568 Default is undefined.
570 Common config types:
572 restart_type() = permanent | transient | temporary:
574 See supervisor documentation for more info.
575 Default is permanent for the agent and transient for the manager.
577 db_init_error() = terminate | create | create_db_and_dir:
579 Defines what to do if the agent or manager is unable to open an
580 existing database file. terminate means that the agent/manager will
581 terminate and create means that the agent/manager will remove the
582 faulty file(s) and create new ones, and create_db_and_dir means
583 that the agent/manager will create the database file along with any
584 missing parent directories for the database file.
585 Default is terminate.
587 priority() = atom() <optional>:
589 Defines the Erlang priority for all SNMP processes.
590 Default is normal.
592 versions() = [version()] <optional>:
594 version() = v1 | v2 | v3
595 Which SNMP versions shall be accepted/used.
597 Default is [v1,v2,v3].
599 verbosity() = silence | info | log | debug | trace <optional>:
601 Verbosity for a SNMP process. This specifies now much debug info is
602 printed.
603 Default is silence.
605 bind_to() = bool() <optional>:
607 If true, net_if binds to the IP address. If false, net_if listens
608 on any IP address on the host where it is running.
609 Default is false.
611 no_reuse() = bool() <optional>:
613 If true, net_if does not specify that the IP and port address
614 should be reusable. If false, the address is set to reusable.
615 Default is false.
617 recbuf() = integer() <optional>:
619 Receive buffer size.
620 Default value is defined by gen_udp.
622 sndbuf() = integer() <optional>:
624 Send buffer size.
625 Default value is defined by gen_udp.
627 extra_socket_options() = list() <optional>:
629 A list of arbitrary socket options.
630 This list is not inspected by snmp (other then checking that its a
632 list). Its the users responsibility to ensure that these are valid
633 options and does not conflict with the "normal" options.
634 Default is [].
636 note_store() = [note_store_opt()] <optional>:
638 note_store_opt() = {timeout, note_store_timeout()} | {verbosity,
639 verbosity()}
640 Specifies the start-up verbosity for the SNMP note store.
642 For defaults see the options in note_store_opt().
644 note_store_timeout() = integer() <optional>:
646 Note cleanup time. When storing a note in the note store, each note
647 is given lifetime. Every timeout the note_store process performs a
648 GC to remove the expired note's. Time in milli-seconds.
649 Default is 30000.
651 audit_trail_log() = [audit_trail_log_opt()] <optional>:
653 audit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} |
654 {size, atl_size()} | {repair, atl_repair()} | {seqno, atl_seqno()}
655 If present, this option specifies the options for the audit trail
657 logging. The disk_log module is used to maintain a wrap log. If
658 present, the dir and size options are mandatory.
659 If not present, audit trail logging is not used.
661 atl_type() = read | write | read_write <optional>:
663 Specifies what type of an audit trail log should be used. The
664 effect of the type is actually different for the the agent and the
665 manager.
666 For the agent:
668 * If write is specified, only set requests are logged.
670 * If read is specified, only get requests are logged.
672 * If read_write, all requests are logged.
674 For the manager:
676 * If write is specified, only sent messages are logged.
678 * If read is specified, only received messages are logged.
680 * If read_write, both outgoing and incoming messages are logged.
682 Default is read_write.
684 atl_dir = dir() <mandatory>:
686 Specifies where the audit trail log should be stored.
687 If audit_trail_log specifies that logging should take place, this
689 parameter must be defined.
690 atl_size() = {integer(), integer()} <mandatory>:
692 Specifies the size of the audit trail log. This parameter is sent
693 to disk_log.
694 If audit_trail_log specifies that logging should take place, this
696 parameter must be defined.
697 atl_repair() = true | false | truncate | snmp_repair <optional>:
699 Specifies if and how the audit trail log shall be repaired when
700 opened. Unless this parameter has the value snmp_repair it is sent
701 to disk_log. If, on the other hand, the value is snmp_repair, snmp
702 attempts to handle certain faults on its own. And even if it cannot
703 repair the file, it does not truncate it directly, but instead
704 moves it aside for later off-line analysis.
705 Default is true.
707 atl_seqno() = true | false <optional>:
709 Specifies if the audit trail log entries will be (sequence) num‐
710 bered or not. The range of the sequence numbers are according to
711 RFC 5424, i.e. 1 through 2147483647.
712 Default is false.
714
716 application(3), disk_log(3)
717Ericsson AB snmp 5.4.3 snmp(7)