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 These options are actually specific to the used module. The ones
186 shown here are applicable to the default agent_net_if_module().
187 For defaults see the options in agent_net_if_option().
189 req_limit() = integer() | infinity <optional>:
191 Max number of simultaneous requests handled by the agent.
192 Default is infinity.
194 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 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 For defaults see the options in agent_net_if_filter_option().
205 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 Default is snmpa_net_if_filter.
211 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 Note that the following mibs will always be loaded:
217 * version v1: STANDARD-MIB
219 * version v2: SNMPv2
221 * version v3: SNMPv2, SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB
223 Default is [].
225 mib_storage() = [mib_storage_opt()] <optional>:
227 mib_storage_opt() = {module, mib_storage_module()} | {options,
228 mib_storage_options()}
229 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 Default is [{module, snmpa_mib_storage_ets}].
235 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 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 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 Default module is snmpa_mib_storage_ets.
250 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 * snmpa_mib_storage_ets: {dir, filename()} | {action, keep |
257 clear}, {checksum, boolean()}
258 * dir - If present, points to a directory where a file to which
260 all data in the ets table is "synced".
261 Also, when a table is opened this file is read, if it exists.
263 By default, this will not be used.
265 * action - Specifies the behaviour when a non-empty file is
267 found: Keep its content or clear it out.
268 Default is keep.
270 * checksum - Defines if the file is checksummed or not.
272 Default is false.
274 * snmpa_mib_storage_dets: {dir, filename()} | {action, keep |
276 clear}, {auto_save, default | pos_integer()} | {repair, force |
277 boolean()}
278 * dir - This mandatory option points to a directory where to
280 place the file of a dets table.
281 * action - Specifies the behaviour when a non-empty file is
283 found: Keep its content or clear it out.
284 Default is keep.
286 * auto_save - Defines the dets auto-save frequency.
288 Default is default.
290 * repair - Defines the dets repair behaviour.
292 Default is false.
294 * snmpa_mib_storage_mnesia: {action, keep | clear}, {nodes,
296 [node()]}
297 * action - Specifies the behaviour when a non-empty, already
299 existing, table: Keep its content or clear it out.
300 Default is keep.
302 * 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 The following distinct values are recognised:
308 * [] - Translated into a list of the own node: [node()]
310 * all - erlang:nodes()
312 * visible - erlang:nodes(visible)
314 * connected - erlang:nodes(connected)
316 * db_nodes - mnesia:system_info(db_nodes)
318 Default is the result of the call: erlang:nodes().
320 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 Defines options specific for the SNMP agent mib server.
328 For defaults see the options in mib_server_opt().
330 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 Default is false.
338 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 Default is false.
346 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 At present only the default module is provided with the agent,
352 snmpa_mib_data_tttn.
353 Default module is snmpa_mib_data_tttn.
355 mibs_cache() = bool() | mibs_cache_opts() <optional>:
357 Shall the agent utilize the mib server lookup cache or not.
358 Default is true (in which case the mibs_cache_opts() default values
360 apply).
361 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 Defines options specific for the SNMP agent mib server cache.
367 For defaults see the options in mibs_cache_opt().
369 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 Default is true.
375 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 The age is defined in milliseconds.
382 Default is 10 timutes.
384 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 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 Default is 100.
394 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 Default is snmpa_error_logger.
401 symbolic_store() = [symbolic_store_opt()]:
403 symbolic_store_opt() = {verbosity, verbosity()}
404 Defines options specific for the SNMP agent symbolic store.
406 For defaults see the options in symbolic_store_opt().
408 target_cache() = [target_cache_opt()]:
410 target_cache_opt() = {verbosity, verbosity()}
411 Defines options specific for the SNMP agent target cache.
413 For defaults see the options in target_cache_opt().
415 agent_config() = [agent_config_opt()] <mandatory>:
417 agent_config_opt() = {dir, agent_config_dir()} | {force_load,
418 force_load()} | {verbosity, verbosity()}
419 Defines specific config related options for the SNMP agent.
421 For defaults see the options in agent_config_opt().
423 agent_config_dir = dir() <mandatory>:
425 Defines where the SNMP agent configuration files are stored.
426 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 Default is false.
434 Manager specific config options and types:
436 server() = [server_opt()] <optional>:
438 server_opt() = {timeout, server_timeout()} | {verbosity, ver‐
439 bosity()}
440 Specifies the options for the manager server process.
442 Default is silence.
444 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 Time in milli-seconds.
457 Default is 30000.
459 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 Defines specific config related options for the SNMP manager.
467 For defaults see the options in manager_config_opt().
469 manager_config_dir = dir() <mandatory>:
471 Defines where the SNMP manager configuration files are stored.
472 manager_db_dir = dir() <mandatory>:
474 Defines where the SNMP manager store persistent data.
475 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 Default is true.
481 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 Default is 5000.
487 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 * auto - The manager will autonomously send response (acknowledg‐
493 ment> to inform-request messages.
494 * {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 * user - Same as {user, integer()}, except that the default time,
501 15 seconds (15000), is used.
502 See snmpm_network_interface, handle_inform and definition of the
504 manager net if for more info.
505 Default is auto.
507 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 Default is [].
513 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 Defines options specific for the SNMP manager network interface
519 entity.
520 For defaults see the options in manager_net_if_opt().
522 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 These options are actually specific to the used module. The ones
529 shown here are applicable to the default manager_net_if_module().
530 For defaults see the options in manager_net_if_option().
532 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 Default is snmpm_net_if.
538 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 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 For defaults see the options in manager_net_if_filter_option().
549 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 Default is snmpm_net_if_filter.
556 def_user_module() = atom() <optional>:
558 The module implementing the default user. See the snmpm_user behav‐
559 iour.
560 Default is snmpm_user_default.
562 def_user_data() = term() <optional>:
564 Data for the default user. Passed to the user module when calling
565 the callback functions.
566 Default is undefined.
568 Common config types:
570 restart_type() = permanent | transient | temporary:
572 See supervisor documentation for more info.
573 Default is permanent for the agent and transient for the manager.
575 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 Default is terminate.
585 priority() = atom() <optional>:
587 Defines the Erlang priority for all SNMP processes.
588 Default is normal.
590 versions() = [version()] <optional>:
592 version() = v1 | v2 | v3
593 Which SNMP versions shall be accepted/used.
595 Default is [v1,v2,v3].
597 verbosity() = silence | info | log | debug | trace <optional>:
599 Verbosity for a SNMP process. This specifies now much debug info is
600 printed.
601 Default is silence.
603 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 Default is false.
609 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 Default is false.
615 recbuf() = integer() <optional>:
617 Receive buffer size.
618 Default value is defined by gen_udp.
620 sndbuf() = integer() <optional>:
622 Send buffer size.
623 Default value is defined by gen_udp.
625 note_store() = [note_store_opt()] <optional>:
627 note_store_opt() = {timeout, note_store_timeout()} | {verbosity,
628 verbosity()}
629 Specifies the start-up verbosity for the SNMP note store.
631 For defaults see the options in note_store_opt().
633 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 Default is 30000.
640 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 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 If not present, audit trail logging is not used.
650 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 For the agent:
657 * If write is specified, only set requests are logged.
659 * If read is specified, only get requests are logged.
661 * If read_write, all requests are logged.
663 For the manager:
665 * If write is specified, only sent messages are logged.
667 * If read is specified, only received messages are logged.
669 * If read_write, both outgoing and incoming messages are logged.
671 Default is read_write.
673 atl_dir = dir() <mandatory>:
675 Specifies where the audit trail log should be stored.
676 If audit_trail_log specifies that logging should take place, this
678 parameter must be defined.
679 atl_size() = {integer(), integer()} <mandatory>:
681 Specifies the size of the audit trail log. This parameter is sent
682 to disk_log.
683 If audit_trail_log specifies that logging should take place, this
685 parameter must be defined.
686 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 Default is true.
696 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 Default is false.
703
705 application(3), disk_log(3)
706Ericsson AB snmp 5.2.12 snmp(7)