1snmpm(3) Erlang Module Definition snmpm(3)
2
6 snmpm - Interface functions to the SNMP toolkit manager
7
9 The module snmpm contains interface functions to the SNMP manager.
10
12 The following data types are used in the functions below:
13 oid() = [byte()] - The oid() type is used to represent an ASN.1 OBJECT IDENTIFIER
15 snmp_reply() = {error_status(), error_index(), varbinds()}
16 error_status() = noError | atom()
17 error_index() = integer()
18 varbinds() = [varbind()]
19 atl_type() = read | write | read_write
20 target_name() = string() - Is a unique *non-empty* string
21 vars_and_vals() = [var_and_val()]
22 var_and_val() = {oid(), value_type(), value()} | {oid(), value()}
23 value_type() = o ('OBJECT IDENTIFIER') |
24 i ('INTEGER') |
25 u ('Unsigned32') |
26 g ('Unsigned32') |
27 s ('OCTET SRING') |
28 b ('BITS') |
29 ip ('IpAddress') |
30 op ('Opaque') |
31 c32 ('Counter32') |
32 c64 ('Counter64') |
33 tt ('TimeTicks')
34 value() = term()
35 community() = string()
36 sec_model() = any | v1 | v2c | usm
37 sec_name() = string()
38 sec_level() = noAuthNoPriv | authNoPriv | authPriv
39 See also the data types in snmpa_conf.
42
44 monitor() -> Ref
45 Types:
47 Ref = reference()
49 Monitor the SNMP manager. In case of a crash, the calling (moni‐
51 toring) process will get a 'DOWN' message (see the erlang module
52 for more info).
53 demonitor(Ref) -> void()
55 Types:
57 Ref = reference()
59 Turn off monitoring of the SNMP manager.
61 notify_started(Timeout) -> Pid
63 Types:
65 Timeout = integer()
67 Pid = pid()
68 Request a notification (message) when the SNMP manager has
70 started.
71 The Timeout is the time the request is valid. The value has to
73 be greater then zero.
74 The Pid is the process handling the supervision of the SNMP man‐
76 ager start. When the manager has started a completion message
77 will be sent to the client from this process: {snmpm_started,
78 Pid}. If the SNMP manager was not started in time, a timeout
79 message will be sent to the client: {snmpm_start_timeout, Pid}.
80 A client application that is dependent on the SNMP manager will
82 use this function in order to be notified of when the manager
83 has started. There are two situations when this is useful:
84 * During the start of a system, when a client application
86 could start prior to the SNMP manager but is dependent upon
87 it, and therefor has to wait for it to start.
88 * When the SNMP manager has crashed, the dependent client
90 application has to wait for the SNMP manager to be restarted
91 before it can reconnect.
92 The function returns the pid() of a handler process, that does
94 the supervision on behalf of the client application. Note that
95 the client application is linked to this handler.
96 This function is used in conjunction with the monitor function.
98 cancel_notify_started(Pid) -> void()
100 Types:
102 Pid = pid()
104 Cancel a previous request to be notified of SNMP manager start.
106 register_user(Id, Module, Data) -> ok | {error, Reason}
108 register_user(Id, Module, Data, DefaultAgentConfig) -> ok | {error,
109 Reason}
110 Types:
112 Id = term()
114 Module = snmpm_user()
115 Data = term()
116 DefaultAgentConfig = [default_agent_config()]
117 default_agent_config() = {Item, Val}
118 Item = community | timeout | max_message_size | version |
119 sec_model | sec_name | sec_level
120 Val = term()
121 Reason = term()
122 snmpm_user() = Module implementing the snmpm_user behaviour
123 Register the manager entity (=user) responsible for specific
125 agent(s).
126 Module is the callback module (snmpm_user behaviour) which will
128 be called whenever something happens (detected agent, incoming
129 reply or incoming trap/notification). Note that this could have
130 already been done as a consequence of the node config. (see
131 users.conf).
132 The argument DefaultAgentConfig is used as default values when
134 this user register agents.
135 The type of Val depends on Item:
137 community = string()
139 timeout = integer() | snmp_timer()
140 max_message_size = integer()
141 version = v1 | v2 | v3
142 sec_model = any | v1 | v2c | usm
143 sec_name = string()
144 sec_level = noAuthNoPriv | authNoPriv | authPriv
145 register_user_monitor(Id, Module, Data) -> ok | {error, Reason}
148 register_user_monitor(Id, Module, Data, DefaultAgentConfig) -> ok |
149 {error, Reason}
150 Types:
152 Id = term()
154 Module = snmpm_user()
155 DefaultAgentConfig = [default_agent_config()]
156 default_agent_config() = {Item, Val}
157 Item = community | timeout | max_message_size | version |
158 sec_model | sec_name | sec_level
159 Val = term()
160 Data = term()
161 Reason = term()
162 snmpm_user() = Module implementing the snmpm_user behaviour
163 Register the monitored manager entity (=user) responsible for
165 specific agent(s).
166 The process performing the registration will be monitored. Which
168 means that if that process should die, all agents registered by
169 that user process will be unregistered. All outstanding requests
170 will be canceled.
171 Module is the callback module (snmpm_user behaviour) which will
173 be called whenever something happens (detected agent, incoming
174 reply or incoming trap/notification). Note that this could have
175 already been done as a consequence of the node config. (see
176 users.conf).
177 The argument DefaultAgentConfig is used as default values when
179 this user register agents.
180 The type of Val depends on Item:
182 community = string()
184 timeout = integer() | snmp_timer()
185 max_message_size = integer()
186 version = v1 | v2 | v3
187 sec_model = any | v1 | v2c | usm
188 sec_name = string()
189 sec_level = noAuthNoPriv | authNoPriv | authPriv
190 unregister_user(Id) -> ok | {error, Reason}
193 Types:
195 Id = term()
197 Unregister the user.
199 which_users() -> Users
201 Types:
203 Users = [UserId]
205 UserId = term()
206 Get a list of the identities of all registered users.
208 register_agent(UserId, TargetName, Config) -> ok | {error, Reason}
210 Types:
212 UserId = term()
214 TargetName = target_name()
215 Config = [agent_config()]
216 agent_config() = {Item, Val}
217 Item = engine_id | address | port | community | timeout |
218 max_message_size | version | sec_model | sec_name | sec_level
219 | tdomain
220 Val = term()
221 Reason = term()
222 Explicitly instruct the manager to handle this agent, with
224 UserId as the responsible user.
225 Called to instruct the manager that this agent shall be handled.
227 This function is used when the user knows in advance which
228 agents the manager shall handle. Note that there is an alternate
229 way to do the same thing: Add the agent to the manager config
230 files (see agents.conf).
231 TargetName is a non-empty string, uniquely identifying the
233 agent.
234 The type of Val depends on Item:
236 [mandatory] engine_id = string()
238 [mandatory] tadress = transportAddress() % Depends on tdomain
239 [optional] port = inet:port_number()
240 [optional] tdomain = transportDomain()
241 [optional] community = string()
242 [optional] timeout = integer() | snmp_timer()
243 [optional] max_message_size = integer()
244 [optional] version = v1 | v2 | v3
245 [optional] sec_model = any | v1 | v2c | usm
246 [optional] sec_name = string()
247 [optional] sec_level = noAuthNoPriv | authNoPriv | authPriv
248 Note that if no tdomain is given, the default value, transport‐
251 DomainUdpIpv4, is used.
252 Note that if no port is given and if taddress does not contain a
254 port number, the default value is used.
255 unregister_agent(UserId, TargetName) -> ok | {error, Reason}
257 Types:
259 UserId = term()
261 TargetName = target_name()
262 Unregister the agent.
264 agent_info(TargetName, Item) -> {ok, Val} | {error, Reason}
266 Types:
268 TargetName = target_name()
270 Item = atom()
271 Reason = term()
272 Retrieve agent config.
274 update_agent_info(UserId, TargetName, Info) -> ok | {error, Reason}
276 update_agent_info(UserId, TargetName, Item, Val) -> ok | {error, Rea‐
277 son}
278 Types:
280 UserId = term()
282 TargetName = target_name()
283 Info = [{item(), item_value()}]
284 Item = item()
285 item() = atom()
286 Val = item_value()
287 item_value() = term()
288 Reason = term()
289 Update agent config. The function update_agent_info/3 should be
291 used when several values needs to be updated atomically.
292 See function register_agent for more info about what kind of
294 items are allowed.
295 which_agents() -> Agents
297 which_agents(UserId) -> Agents
298 Types:
300 UserId = term()
302 Agents = [TargetName]
303 TargetName = target_name()
304 Get a list of all registered agents or all agents registered by
306 a specific user.
307 register_usm_user(EngineID, UserName, Conf) -> ok | {error, Reason}
309 Types:
311 EngineID = string()
313 UserName = string()
314 Conf = [usm_config()]
315 usm_config() = {Item, Val}
316 Item = sec_name | auth | auth_key | priv | priv_key
317 Val = term()
318 Reason = term()
319 Explicitly instruct the manager to handle this USM user. Note
321 that there is an alternate way to do the same thing: Add the usm
322 user to the manager config files (see usm.conf).
323 The type of Val depends on Item:
325 sec_name = string()
327 auth = usmNoAuthProtocol | usmHMACMD5AuthProtocol | usmHMACSHAAuthProtocoltimeout
328 auth_key = [integer()] (length 16 if auth = usmHMACMD5AuthProtocol,
329 length 20 if auth = usmHMACSHAAuthProtocol)
330 priv = usmNoPrivProtocol | usmDESPrivProtocol | usmAesCfb128Protocol
331 priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb128Protocol).
332 unregister_usm_user(EngineID, UserName) -> ok | {error, Reason}
335 Types:
337 EngineID = string()
339 UserName = string()
340 Reason = term()
341 Unregister this USM user.
343 usm_user_info(EngineID, UserName, Item) -> {ok, Val} | {error, Reason}
345 Types:
347 EngineID = string()
349 UsmName = string()
350 Item = sec_name | auth | auth_key | priv | priv_key
351 Reason = term()
352 Retrieve usm user config.
354 update_usm_user_info(EngineID, UserName, Item, Val) -> ok | {error,
356 Reason}
357 Types:
359 EngineID = string()
361 UsmName = string()
362 Item = sec_name | auth | auth_key | priv | priv_key
363 Val = term()
364 Reason = term()
365 Update usm user config.
367 which_usm_users() -> UsmUsers
369 Types:
371 UsmUsers = [{EngineID,UserName}]
373 EngineID = string()
374 UsmName = string()
375 Get a list of all registered usm users.
377 which_usm_users(EngineID) -> UsmUsers
379 Types:
381 UsmUsers = [UserName]
383 UserName = string()
384 Get a list of all registered usm users with engine-id EngineID.
386 sync_get2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} |
388 {error, Reason}
389 sync_get2(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply,
390 Remaining} | {error, Reason}
391 Types:
393 UserId = term()
395 TargetName = target_name()
396 Oids = [oid()]
397 SendOpts = send_opts()
398 send_opts() = [send_opt()]
399 send_opt() = {context, string()} | {timeout, pos_integer()} |
400 {extra, term()} | {community, community()} | {sec_model,
401 sec_model()} | {sec_name, string()} | {sec_level,
402 sec_level()} | {max_message_size, pos_integer()}
403 SnmpReply = snmp_reply()
404 Remaining = integer()
405 Reason = {send_failed, ReqId, ActualReason} |
406 {invalid_sec_info, SecInfo, SnmpInfo} | term()
407 ReqId = term()
408 ActualReason = term()
409 SecInfo = [sec_info()]
410 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
411 sec_tag() = atom()
412 ExpectedValue = ReceivedValue = term()
413 SnmpInfo = term()
414 Synchronous get-request.
416 Remaining is the remaining time of the given (or default) time‐
418 out time.
419 When Reason is {send_failed, ...} it means that the net_if
421 process failed to send the message. This could happen because of
422 any number of reasons, i.e. encoding error. ActualReason is the
423 actual reason in this case.
424 The send option extra specifies an opaque data structure passed
426 on to the net-if process. The net-if process included in this
427 application makes, with one exception, no use of this info, so
428 the only use for it in such a option (when using the built in
429 net-if) would be tracing. The one usage exception is: Any tuple
430 with snmpm_extra_info_tag as its first element is reserved for
431 internal use.
432 Some of the send options (community, sec_model, sec_name,
434 sec_level and max_message_size) are override options. That is,
435 for this request, they override any configuration done when the
436 agent was registered.
437 For SnmpInfo, see the user callback function handle_report.
439 sync_get(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} |
441 {error, Reason}
442 sync_get(UserId, TargetName, ContextName, Oids) -> {ok, SnmpReply,
443 Remaining} | {error, Reason}
444 sync_get(UserId, TargetName, Oids, Timeout) -> {ok, SnmpReply, Remain‐
445 ing} | {error, Reason}
446 sync_get(UserId, TargetName, ContextName, Oids, Timeout) -> {ok, Snm‐
447 pReply, Remaining} | {error, Reason}
448 sync_get(UserId, TargetName, ContextName, Oids, Timeout, ExtraInfo) ->
449 {ok, SnmpReply, Remaining} | {error, Reason}
450 Types:
452 UserId = term()
454 TargetName = target_name()
455 ContextName = string()
456 Oids = [oid()]
457 Timeout = integer()
458 ExtraInfo = term()
459 SnmpReply = snmp_reply()
460 Remaining = integer()
461 Reason = {send_failed, ReqId, R} | {invalid_sec_info,
462 SecInfo, SnmpInfo} | term()
463 R = term()
464 SecInfo = [sec_info()]
465 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
466 sec_tag() = atom()
467 ExpectedValue = ReceivedValue = term()
468 SnmpInfo = term()
469 Synchronous get-request.
471 Remaining is the remaining time of the given or default timeout
473 time.
474 When Reason is {send_failed, ...} it means that the net_if
476 process failed to send the message. This could happen because of
477 any number of reasons, i.e. encoding error. R is the actual rea‐
478 son in this case.
479 ExtraInfo is an opaque data structure passed on to the net-if
481 process. The net-if process included in this application makes,
482 with one exception, no use of this info, so the only use for it
483 in such a configuration (when using the built in net-if) would
484 be tracing. The one usage exception is: Any tuple with
485 snmpm_extra_info_tag as its first element is reserved for inter‐
486 nal use.
487 For SnmpInfo, see the user callback function handle_report.
489 async_get2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
491 async_get2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error,
492 Reason}
493 Types:
495 UserId = term()
497 TargetName = target_name()
498 Oids = [oid()]
499 SendOpts = send_opts()
500 send_opts() = [send_opt()]
501 send_opt() = {context, string()} | {timeout, pos_integer()} |
502 {extra, term()} | {community, community()} | {sec_model,
503 sec_model()} | {sec_name, string()} | {sec_level,
504 sec_level()} | {max_message_size, pos_integer()}
505 ReqId = term()
506 Reason = term()
507 Asynchronous get-request.
509 The reply, if it arrives, will be delivered to the user through
511 a call to the snmpm_user callback function handle_pdu.
512 The send option timeout specifies for how long the request is
514 valid (after which the manager is free to delete it).
515 The send option extra specifies an opaque data structure passed
517 on to the net-if process. The net-if process included in this
518 application makes, with one exception, no use of this info, so
519 the only use for it in such a option (when using the built in
520 net-if) would be tracing. The one usage exception is: Any tuple
521 with snmpm_extra_info_tag as its first element is reserved for
522 internal use.
523 Some of the send options (community, sec_model, sec_name,
525 sec_level and max_message_size) are override options. That is,
526 for this request, they override any configuration done when the
527 agent was registered.
528 async_get(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
530 async_get(UserId, TargetName, ContextName, Oids) -> {ok, ReqId} |
531 {error, Reason}
532 async_get(UserId, TargetName, Oids, Expire) -> {ok, ReqId} | {error,
533 Reason}
534 async_get(UserId, TargetName, ContextName, Oids, Expire) -> {ok, ReqId}
535 | {error, Reason}
536 async_get(UserId, TargetName, ContextName, Oids, Expire, ExtraInfo) ->
537 {ok, ReqId} | {error, Reason}
538 Types:
540 UserId = term()
542 TargetName = target_name()
543 ContextName = string()
544 Oids = [oid()]
545 Expire = integer()
546 ExtraInfo = term()
547 ReqId = term()
548 Reason = term()
549 Asynchronous get-request.
551 The reply, if it arrives, will be delivered to the user through
553 a call to the snmpm_user callback function handle_pdu.
554 The Expire time indicates for how long the request is valid
556 (after which the manager is free to delete it).
557 ExtraInfo is an opaque data structure passed on to the net-if
559 process. The net-if process included in this application makes,
560 with one exception, no use of this info, so the only use for it
561 in such a configuration (when using the built in net-if) would
562 be tracing. The one usage exception is: Any tuple with
563 snmpm_extra_info_tag as its first element is reserved for inter‐
564 nal use.
565 sync_get_next2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining}
567 | {error, Reason}
568 sync_get_next2(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply,
569 Remaining} | {error, Reason}
570 Types:
572 UserId = term()
574 TargetName = target_name()
575 Oids = [oid()]
576 SendOpts = send_opts()
577 send_opts() = [send_opt()]
578 send_opt() = {context, string()} | {timeout, pos_integer()} |
579 {extra, term()} | {community, community()} | {sec_model,
580 sec_model()} | {sec_name, string()} | {sec_level,
581 sec_level()} | {max_message_size, pos_integer()}
582 SnmpReply = snmp_reply()
583 Remaining = integer()
584 Reason = {send_failed, ReqId, ActualReason} |
585 {invalid_sec_info, SecInfo, SnmpInfo} | term()
586 ReqId = term()
587 ActualReason = term()
588 SecInfo = [sec_info()]
589 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
590 sec_tag() = atom()
591 ExpectedValue = ReceivedValue = term()
592 SnmpInfo = term()
593 Synchronous get-next-request.
595 Remaining is the remaining time of the given (or default) time‐
597 out time.
598 When Reason is {send_failed, ...} it means that the net_if
600 process failed to send the message. This could happen because of
601 any number of reasons, i.e. encoding error. ActualReason is the
602 actual reason in this case.
603 The send option extra specifies an opaque data structure passed
605 on to the net-if process. The net-if process included in this
606 application makes, with one exception, no use of this info, so
607 the only use for it in such a option (when using the built in
608 net-if) would be tracing. The one usage exception is: Any tuple
609 with snmpm_extra_info_tag as its first element is reserved for
610 internal use.
611 Some of the send options (community, sec_model, sec_name,
613 sec_level and max_message_size) are override options. That is,
614 for this request, they override any configuration done when the
615 agent was registered.
616 For SnmpInfo, see the user callback function handle_report.
618 sync_get_next(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} |
620 {error, Reason}
621 sync_get_next(UserId, TargetName, ContextName, Oids) -> {ok, SnmpReply,
622 Remaining} | {error, Reason}
623 sync_get_next(UserId, TargetName, Oids, Timeout) -> {ok, SnmpReply,
624 Remaining} | {error, Reason}
625 sync_get_next(UserId, TargetName, ContextName, Oids, Timeout) -> {ok,
626 SnmpReply, Remaining} | {error, Reason}
627 sync_get_next(UserId, TargetName, ContextName, Oids, Timeout,
628 ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason}
629 Types:
631 UserId = term()
633 TargetName = target_name()
634 ContextName = string()
635 Oids = [oid()]
636 Timeout = integer()
637 ExtraInfo = term()
638 SnmpReply = snmp_reply()
639 Remaining = integer()
640 Reason = {send_failed, ReqId, R} | {invalid_sec_info,
641 SecInfo, SnmpInfo} | term()
642 R = term()
643 Synchronous get-next-request.
645 Remaining time of the given or default timeout time.
647 When Reason is {send_failed, ...} it means that the net_if
649 process failed to send the message. This could happen because of
650 any number of reasons, i.e. encoding error. R is the actual rea‐
651 son in this case.
652 ExtraInfo is an opaque data structure passed on to the net-if
654 process. The net-if process included in this application makes,
655 with one exception, no use of this info, so the only use for it
656 in such a configuration (when using the built in net-if) would
657 be tracing. The one usage exception is: Any tuple with
658 snmpm_extra_info_tag as its first element is reserved for inter‐
659 nal use.
660 async_get_next2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Rea‐
662 son}
663 async_get_next2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} |
664 {error, Reason}
665 Types:
667 UserId = term()
669 TargetName = target_name()
670 Oids = [oid()]
671 send_opt() = {context, string()} | {timeout, pos_integer()} |
672 {extra, term()} | {community, community()} | {sec_model,
673 sec_model()} | {sec_name, string()} | {sec_level,
674 sec_level()} | {max_message_size, pos_integer()}
675 ReqId = integer()
676 Reason = term()
677 Asynchronous get-next-request.
679 The reply will be delivered to the user through a call to the
681 snmpm_user callback function handle_pdu.
682 The send option timeout specifies for how long the request is
684 valid (after which the manager is free to delete it).
685 The send option extra specifies an opaque data structure passed
687 on to the net-if process. The net-if process included in this
688 application makes, with one exception, no use of this info, so
689 the only use for it in such a option (when using the built in
690 net-if) would be tracing. The one usage exception is: Any tuple
691 with snmpm_extra_info_tag as its first element is reserved for
692 internal use.
693 Some of the send options (community, sec_model, sec_name,
695 sec_level and max_message_size) are override options. That is,
696 for this request, they override any configuration done when the
697 agent was registered.
698 async_get_next(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Rea‐
700 son}
701 async_get_next(UserId, TargetName, ContextName, Oids) -> {ok, ReqId} |
702 {error, Reason}
703 async_get_next(UserId, TargetName, Oids, Expire) -> {ok, ReqId} |
704 {error, Reason}
705 async_get_next(UserId, TargetName, ContextName, Oids, Expire) -> {ok,
706 ReqId} | {error, Reason}
707 async_get_next(UserId, TargetName, ContextName, Oids, Expire,
708 ExtraInfo) -> {ok, ReqId} | {error, Reason}
709 Types:
711 UserId = term()
713 TargetName = target_name()
714 ContextName = string()
715 Oids = [oid()]
716 Expire = integer()
717 ExtraInfo = term()
718 ReqId = integer()
719 Reason = term()
720 Asynchronous get-next-request.
722 The reply will be delivered to the user through a call to the
724 snmpm_user callback function handle_pdu.
725 The Expire time indicates for how long the request is valid
727 (after which the manager is free to delete it).
728 ExtraInfo is an opaque data structure passed on to the net-if
730 process. The net-if process included in this application makes,
731 with one exception, no use of this info, so the only use for it
732 in such a configuration (when using the built in net-if) would
733 be tracing. The one usage exception is: Any tuple with
734 snmpm_extra_info_tag as its first element is reserved for inter‐
735 nal use.
736 sync_set2(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remain‐
738 ing} | {error, Reason}
739 sync_set2(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, SnmpReply,
740 Remaining} | {error, Reason}
741 Types:
743 UserId = term()
745 TargetName = target_name()
746 VarsAndVals = vars_and_vals()
747 SendOpts = send_opts()
748 send_opts() = [send_opt()]
749 send_opt() = {context, string()} | {timeout, pos_integer()} |
750 {extra, term()} | {community, community()} | {sec_model,
751 sec_model()} | {sec_name, string()} | {sec_level,
752 sec_level()} | {max_message_size, pos_integer()}
753 SnmpReply = snmp_reply()
754 Remaining = integer()
755 Reason = {send_failed, ReqId, ActualReason} |
756 {invalid_sec_info, SecInfo, SnmpInfo} | term()
757 ReqId = term()
758 ActualReason = term()
759 SecInfo = [sec_info()]
760 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
761 sec_tag() = atom()
762 ExpectedValue = ReceivedValue = term()
763 SnmpInfo = term()
764 Synchronous set-request.
766 Remaining is the remaining time of the given (or default) time‐
768 out time.
769 When Reason is {send_failed, ...} it means that the net_if
771 process failed to send the message. This could happen because of
772 any number of reasons, i.e. encoding error. ActualReason is the
773 actual reason in this case.
774 When var_and_val() is {oid(), value()}, the manager makes an
776 educated guess based on the loaded mibs.
777 The send option extra specifies an opaque data structure passed
779 on to the net-if process. The net-if process included in this
780 application makes, with one exception, no use of this info, so
781 the only use for it in such a option (when using the built in
782 net-if) would be tracing. The one usage exception is: Any tuple
783 with snmpm_extra_info_tag as its first element is reserved for
784 internal use.
785 Some of the send options (community, sec_model, sec_name,
787 sec_level and max_message_size) are override options. That is,
788 for this request, they override any configuration done when the
789 agent was registered.
790 For SnmpInfo, see the user callback function handle_report.
792 sync_set(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining}
794 | {error, Reason}
795 sync_set(UserId, TargetName, ContextName, VarsAndVals) -> {ok, SnmpRe‐
796 ply, Remaining} | {error, Reason}
797 sync_set(UserId, TargetName, VarsAndVals, Timeout) -> {ok, SnmpReply,
798 Remaining} | {error, Reason}
799 sync_set(UserId, TargetName, ContextName, VarsAndVals, Timeout) -> {ok,
800 SnmpReply, Remaining} | {error, Reason}
801 sync_set(UserId, TargetName, ContextName, VarsAndVals, Timeout,
802 ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason}
803 Types:
805 UserId = term()
807 TargetName = target_name()
808 ContextName = string()
809 VarsAndVals = vars_and_vals()
810 Timeout = integer()
811 ExtraInfo = term()
812 SnmpReply = snmp_reply()
813 Remaining = integer()
814 Reason = {send_failed, ReqId, ActualReason} |
815 {invalid_sec_info, SecInfo, SnmpInfo} | term()
816 ActualReason = term()
817 Synchronous set-request.
819 Remaining time of the given or default timeout time.
821 When Reason is {send_failed, ...} it means that the net_if
823 process failed to send the message. This could happen because of
824 any number of reasons, i.e. encoding error. R is the actual rea‐
825 son in this case.
826 When var_and_val() is {oid(), value()}, the manager makes an
828 educated guess based on the loaded mibs.
829 ExtraInfo is an opaque data structure passed on to the net-if
831 process. The net-if process included in this application makes,
832 with one exception, no use of this info, so the only use for it
833 in such a configuration (when using the built in net-if) would
834 be tracing. The one usage exception is: Any tuple with
835 snmpm_extra_info_tag as its first element is reserved for inter‐
836 nal use.
837 async_set2(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error,
839 Reason}
840 async_set2(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, ReqId} |
841 {error, Reason}
842 Types:
844 UserId = term()
846 TargetName = target_name()
847 VarsAndVals = vars_and_vals()
848 SendOpts = send_opts()
849 send_opts() = [send_opt()]
850 send_opt() = {context, string()} | {timeout, pos_integer()} |
851 {extra, term()} | {community, community()} | {sec_model,
852 sec_model()} | {sec_name, string()} | {sec_level,
853 sec_level()} | {max_message_size, pos_integer()}
854 ReqId = term()
855 Reason = term()
856 Asynchronous set-request.
858 The reply will be delivered to the user through a call to the
860 snmpm_user callback function handle_pdu.
861 The send option timeout specifies for how long the request is
863 valid (after which the manager is free to delete it).
864 When var_and_val() is {oid(), value()}, the manager makes an
866 educated guess based on the loaded mibs.
867 The send option extra specifies an opaque data structure passed
869 on to the net-if process. The net-if process included in this
870 application makes, with one exception, no use of this info, so
871 the only use for it in such a option (when using the built in
872 net-if) would be tracing. The one usage exception is: Any tuple
873 with snmpm_extra_info_tag as its first element is reserved for
874 internal use.
875 Some of the send options (community, sec_model, sec_name,
877 sec_level and max_message_size) are override options. That is,
878 for this request, they override any configuration done when the
879 agent was registered.
880 async_set(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error,
882 Reason}
883 async_set(UserId, TargetName, ContextName, VarsAndVals) -> {ok, ReqId}
884 | {error, Reason}
885 async_set(UserId, TargetName, VarsAndVals, Expire) -> {ok, ReqId} |
886 {error, Reason}
887 async_set(UserId, TargetName, ContextName, VarsAndVals, Expire) -> {ok,
888 ReqId} | {error, Reason}
889 async_set(UserId, TargetName, ContextName, VarsAndVals, Expire,
890 ExtraInfo) -> {ok, ReqId} | {error, Reason}
891 Types:
893 UserId = term()
895 TargetName = target_name()
896 VarsAndVals = vars_and_vals()
897 Expire = integer()
898 ExtraInfo = term()
899 ReqId = term()
900 Reason = term()
901 Asynchronous set-request.
903 The reply will be delivered to the user through a call to the
905 snmpm_user callback function handle_pdu.
906 The Expire time indicates for how long the request is valid
908 (after which the manager is free to delete it).
909 When var_and_val() is {oid(), value()}, the manager makes an
911 educated guess based on the loaded mibs.
912 ExtraInfo is an opaque data structure passed on to the net-if
914 process. The net-if process included in this application makes,
915 with one exception, no use of this info, so the only use for it
916 in such a configuration (when using the built in net-if) would
917 be tracing. The one usage exception is: Any tuple with
918 snmpm_extra_info_tag as its first element is reserved for inter‐
919 nal use.
920 sync_get_bulk2(UserId, TragetName, NonRep, MaxRep, Oids) -> {ok, Snm‐
922 pReply, Remaining} | {error, Reason}
923 sync_get_bulk2(UserId, TragetName, NonRep, MaxRep, Oids, SendOpts) ->
924 {ok, SnmpReply, Remaining} | {error, Reason}
925 Types:
927 UserId = term()
929 TargetName = target_name()
930 NonRep = integer()
931 MaxRep = integer()
932 Oids = [oid()]
933 SendOpts = send_opts()
934 send_opts() = [send_opt()]
935 send_opt() = {context, string()} | {timeout, pos_integer()} |
936 {extra, term()} | {community, community()} | {sec_model,
937 sec_model()} | {sec_name, string()} | {sec_level,
938 sec_level()} | {max_message_size, pos_integer()}
939 SnmpReply = snmp_reply()
940 Remaining = integer()
941 Reason = {send_failed, ReqId, ActualReason} |
942 {invalid_sec_info, SecInfo, SnmpInfo} | term()
943 ReqId = term()
944 ActualReason = term()
945 SecInfo = [sec_info()]
946 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
947 sec_tag() = atom()
948 ExpectedValue = ReceivedValue = term()
949 SnmpInfo = term()
950 Synchronous get-bulk-request (See RFC1905).
952 Remaining is the remaining time of the given (or default) time‐
954 out time.
955 When Reason is {send_failed, ...} it means that the net_if
957 process failed to send the message. This could happen because of
958 any number of reasons, i.e. encoding error. ActualReason is the
959 actual reason in this case.
960 The send option extra specifies an opaque data structure passed
962 on to the net-if process. The net-if process included in this
963 application makes, with one exception, no use of this info, so
964 the only use for it in such a option (when using the built in
965 net-if) would be tracing. The one usage exception is: Any tuple
966 with snmpm_extra_info_tag as its first element is reserved for
967 internal use.
968 Some of the send options (community, sec_model, sec_name,
970 sec_level and max_message_size) are override options. That is,
971 for this request, they override any configuration done when the
972 agent was registered.
973 For SnmpInfo, see the user callback function handle_report.
975 sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids) -> {ok, SnmpRe‐
977 ply, Remaining} | {error, Reason}
978 sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids) ->
979 {ok, SnmpReply, Remaining} | {error, Reason}
980 sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids, Timeout) ->
981 {ok, SnmpReply, Remaining} | {error, Reason}
982 sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids,
983 Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}
984 sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids,
985 Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason}
986 Types:
988 UserId = term()
990 TargetName = target_name()
991 NonRep = integer()
992 MaxRep = integer()
993 ContextName = string()
994 Oids = [oid()]
995 Timeout = integer()
996 ExtraInfo = term()
997 SnmpReply = snmp_reply()
998 Remaining = integer()
999 Reason = {send_failed, ReqId, R} | {invalid_sec_info,
1000 SecInfo, SnmpInfo} | term()
1001 Synchronous get-bulk-request (See RFC1905).
1003 Remaining time of the given or default timeout time.
1005 When Reason is {send_failed, ...} it means that the net_if
1007 process failed to send the message. This could happen because of
1008 any number of reasons, i.e. encoding error. R is the actual rea‐
1009 son in this case.
1010 ExtraInfo is an opaque data structure passed on to the net-if
1012 process. The net-if process included in this application makes,
1013 with one exception, no use of this info, so the only use for it
1014 in such a configuration (when using the built in net-if) would
1015 be tracing. The one usage exception is: Any tuple with
1016 snmpm_extra_info_tag as its first element is reserved for inter‐
1017 nal use.
1018 async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok,
1020 ReqId} | {error, Reason}
1021 async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts) ->
1022 {ok, ReqId} | {error, Reason}
1023 Types:
1025 UserId = term()
1027 TargetName = target_name()
1028 NonRep = integer()
1029 MaxRep = integer()
1030 Oids = [oid()]
1031 SendOpts = send_opts()
1032 send_opts() = [send_opt()]
1033 send_opt() = {context, string()} | {timeout, pos_integer()} |
1034 {extra, term()} | {community, community()} | {sec_model,
1035 sec_model()} | {sec_name, string()} | {sec_level,
1036 sec_level()} | {max_message_size, pos_integer()}
1037 ReqId = integer()
1038 Reason = term()
1039 Asynchronous get-bulk-request (See RFC1905).
1041 The reply will be delivered to the user through a call to the
1043 snmpm_user callback function handle_pdu.
1044 The send option timeout specifies for how long the request is
1046 valid (after which the manager is free to delete it).
1047 The send option extra specifies an opaque data structure passed
1049 on to the net-if process. The net-if process included in this
1050 application makes no use of this info, so the only use for it in
1051 such a configuration (when using the built in net-if) would be
1052 tracing.
1053 Some of the send options (community, sec_model, sec_name,
1055 sec_level and max_message_size) are override options. That is,
1056 for this request, they override any configuration done when the
1057 agent was registered.
1058 async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId}
1060 | {error, Reason}
1061 async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids)
1062 -> {ok, ReqId} | {error, Reason}
1063 async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids, Expire) ->
1064 {ok, ReqId} | {error, Reason}
1065 async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids,
1066 Expire) -> {ok, ReqId} | {error, Reason}
1067 async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids,
1068 Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason}
1069 Types:
1071 UserId = term()
1073 TargetName = target_name()
1074 NonRep = integer()
1075 MaxRep = integer()
1076 ContextName = string()
1077 Oids = [oid()]
1078 Expire = integer()
1079 ExtraInfo = term()
1080 ReqId = integer()
1081 Reason = term()
1082 Asynchronous get-bulk-request (See RFC1905).
1084 The reply will be delivered to the user through a call to the
1086 snmpm_user callback function handle_pdu.
1087 The Expire time indicates for how long the request is valid
1089 (after which the manager is free to delete it).
1090 ExtraInfo is an opaque data structure passed on to the net-if
1092 process. The net-if process included in this application makes,
1093 with one exception, no use of this info, so the only use for it
1094 in such a configuration (when using the built in net-if) would
1095 be tracing. The one usage exception is: Any tuple with
1096 snmpm_extra_info_tag as its first element is reserved for inter‐
1097 nal use.
1098 cancel_async_request(UserId, ReqId) -> ok | {error, Reason}
1100 Types:
1102 UserId = term()
1104 ReqId = term()
1105 Reason = term()
1106 Cancel a previous asynchronous request.
1108 log_to_txt(LogDir)
1110 log_to_txt(LogDir, Block | Mibs)
1111 log_to_txt(LogDir, Mibs, Block | OutFile) -> ok | {error, Reason}
1112 log_to_txt(LogDir, Mibs, OutFile, Block | LogName) -> ok | {error, Rea‐
1113 son}
1114 log_to_txt(LogDir, Mibs, OutFile, LogName, Block | LogFile) -> ok |
1115 {error, Reason}
1116 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) ->
1117 ok | {error, Reason}
1118 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok
1119 | {error, Reason}
1120 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok
1121 | {error, Reason}
1122 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)
1123 -> ok | {error, Reason}
1124 Types:
1126 LogDir = string()
1128 Mibs = [MibName]
1129 MibName = string()
1130 Block = boolean()
1131 OutFile = string()
1132 LogName = string()
1133 LogFile = string()
1134 Start = Stop = null | calendar:datetime() | {local_time, cal‐
1135 endar:datetime()} | {universal_time, calendar:datetime()}
1136 Reason = disk_log_open_error() | file_open_error() | term()
1137 disk_log_open_error() = {LogName, term()}
1138 file_open_error() = {OutFile, term()}
1139 Converts an Audit Trail Log to a readable text file. OutFile
1141 defaults to "./snmpm_log.txt". LogName defaults to "snmpm_log".
1142 LogFile defaults to "snmpm.log".
1143 The Block argument indicates if the log should be blocked during
1145 conversion. This could be usefull when converting large logs
1146 (when otherwise the log could wrap during conversion). Defaults
1147 to true.
1148 See snmp:log_to_txt for more info.
1150 log_to_io(LogDir) -> ok | {error, Reason}
1152 log_to_io(LogDir, Block | Mibs) -> ok | {error, Reason}
1153 log_to_io(LogDir, Mibs) -> ok | {error, Reason}
1154 log_to_io(LogDir, Mibs, Block | LogName) -> ok | {error, Reason}
1155 log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {error, Rea‐
1156 son}
1157 log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) -> ok |
1158 {error, Reason}
1159 log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {error,
1160 Reason}
1161 log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {error,
1162 Reason}
1163 log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok |
1164 {error, Reason}
1165 Types:
1167 LogDir = string()
1169 Mibs = [MibName]
1170 MibName = string()
1171 Block = boolean()
1172 LogName = string()
1173 LogFile = string()
1174 Start = Stop = null | calendar:datetime() | {local_time, cal‐
1175 endar:datetime()} | {universal_time, calendar:datetime()}
1176 Reason = disk_log_open_error() | file_open_error() | term()
1177 disk_log_open_error() = {LogName, term()}
1178 file_open_error() = {OutFile, term()}
1179 Converts an Audit Trail Log to a readable format and prints it
1181 on stdio. LogName defaults to "snmpm_log". LogFile defaults to
1182 "snmpm.log".
1183 The Block argument indicates if the log should be blocked during
1185 conversion. This could be usefull when converting large logs
1186 (when otherwise the log could wrap during conversion). Defaults
1187 to true.
1188 See snmp:log_to_io for more info.
1190 change_log_size(NewSize) -> ok | {error, Reason}
1192 Types:
1194 NewSize = {MaxBytes, MaxFiles}
1196 MaxBytes = integer()
1197 MaxFiles = integer()
1198 Reason = term()
1199 Changes the log size of the Audit Trail Log. The application
1201 must be configured to use the audit trail log function. Please
1202 refer to disk_log(3) in Kernel Reference Manual for a descrip‐
1203 tion of how to change the log size.
1204 The change is permanent, as long as the log is not deleted. That
1206 means, the log size is remembered across reboots.
1207 set_log_type(NewType) -> {ok, OldType} | {error, Reason}
1209 Types:
1211 NewType = OldType = atl_type()
1213 Reason = term()
1214 Changes the run-time Audit Trail log type.
1216 Note that this has no effect on the application configuration as
1218 defined by configuration files, so a node restart will revert
1219 the config to whatever is in those files.
1220 This function is primarily useful in testing/debugging scenar‐
1222 ios.
1223 load_mib(Mib) -> ok | {error, Reason}
1225 Types:
1227 Mib = MibName
1229 MibName = string()
1230 Reason = term()
1231 Load a Mib into the manager. The MibName is the name of the Mib,
1233 including the path to where the compiled mib is found. For exam‐
1234 ple,
1235 Dir = code:priv_dir(my_app) ++ "/mibs/",
1237 snmpm:load_mib(Dir ++ "MY-MIB").
1238 unload_mib(Mib) -> ok | {error, Reason}
1241 Types:
1243 Mib = MibName
1245 MibName = string()
1246 Reason = term()
1247 Unload a Mib from the manager. The MibName is the name of the
1249 Mib, including the path to where the compiled mib is found. For
1250 example,
1251 Dir = code:priv_dir(my_app) ++ "/mibs/",
1253 snmpm:unload_mib(Dir ++ "MY-MIB").
1254 which_mibs() -> Mibs
1257 Types:
1259 Mibs = [{MibName, MibFile}]
1261 MibName = atom()
1262 MibFile = string()
1263 Get a list of all the mib's loaded into the manager.
1265 name_to_oid(Name) -> {ok, Oids} | {error, Reason}
1267 Types:
1269 Name = atom()
1271 Oids = [oid()]
1272 Transform a alias-name to its oid.
1274 Note that an alias-name is only unique within the mib, so when
1276 loading several mib's into a manager, there might be several
1277 instances of the same aliasname.
1278 oid_to_name(Oid) -> {ok, Name} | {error, Reason}
1280 Types:
1282 Oid = oid()
1284 Name = atom()
1285 Reason = term()
1286 Transform a oid to its aliasname.
1288 oid_to_type(Oid) -> {ok, Type} | {error, Reason}
1290 Types:
1292 Oid = oid()
1294 Type = atom()
1295 Reason = term()
1296 Retreive the type (asn1 bertype) of an oid.
1298 backup(BackupDir) -> ok | {error, Reason}
1300 Types:
1302 BackupDir = string()
1304 Backup persistent data handled by the manager.
1306 BackupDir cannot be identical to DbDir.
1308 info() -> [{Key, Value}]
1310 Types:
1312 Key = atom()
1314 Value = term()
1315 Returns a list (a dictionary) containing information about the
1317 manager. Information includes statistics counters, miscellaneous
1318 info about each process (e.g. memory allocation), and so on.
1319 verbosity(Ref, Verbosity) -> void()
1321 Types:
1323 Ref = server | config | net_if | note_store | all
1325 Verbosity = verbosity()
1326 verbosity() = silence | info | log | debug | trace
1327 Sets verbosity for the designated process. For the lowest ver‐
1329 bosity silence, nothing is printed. The higher the verbosity,
1330 the more is printed.
1331 format_reason(Reason) -> string()
1333 format_reason(Prefix, Reason) -> string()
1334 Types:
1336 Reason = term()
1338 Prefix = integer() | string()
1339 This utility function is used to create a formatted (pretty
1341 printable) string of the error reason received from either:
1342 * The Reason returned value if any of the sync/async get/get-
1344 next/set/get-bulk functions returns {error, Reason}
1345 * The Reason parameter in the handle_error user callback func‐
1347 tion.
1348 Prefix should either be an indention string (e.g. a list of spa‐
1350 ces) or a positive integer (which will be used to create the
1351 indention string of that length).
1352Ericsson AB snmp 5.2.11.1 snmpm(3)