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 | {ok, Cnt} | {error,
1112 Reason}
1113 log_to_txt(LogDir, Mibs, OutFile, Block | LogName) -> ok | {ok, Cnt} |
1114 {error, Reason}
1115 log_to_txt(LogDir, Mibs, OutFile, LogName, Block | LogFile) -> ok |
1116 {ok, Cnt} | {error, Reason}
1117 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) ->
1118 ok | {ok, Cnt} | {error, Reason}
1119 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok
1120 | {ok, Cnt} | {error, Reason}
1121 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok
1122 | {ok, Cnt} | {error, Reason}
1123 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)
1124 -> ok | {ok, Cnt} | {error, Reason}
1125 Types:
1127 LogDir = string()
1129 Mibs = [MibName]
1130 MibName = string()
1131 Block = boolean()
1132 OutFile = string()
1133 LogName = string()
1134 LogFile = string()
1135 Start = Stop = null | calendar:datetime() | {local_time, cal‐
1136 endar:datetime()} | {universal_time, calendar:datetime()}
1137 Cnt = {NumOK, NumERR}
1138 NumOK = non_neg_integer()
1139 NumERR = pos_integer()
1140 Reason = disk_log_open_error() | file_open_error() | term()
1141 disk_log_open_error() = {LogName, term()}
1142 file_open_error() = {OutFile, term()}
1143 Converts an Audit Trail Log to a readable text file. OutFile
1145 defaults to "./snmpm_log.txt". LogName defaults to "snmpm_log".
1146 LogFile defaults to "snmpm.log".
1147 The Block argument indicates if the log should be blocked during
1149 conversion. This could be usefull when converting large logs
1150 (when otherwise the log could wrap during conversion). Defaults
1151 to true.
1152 See snmp:log_to_txt for more info.
1154 log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
1156 log_to_io(LogDir, Block | Mibs) -> ok | {ok, Cnt} | {error, Reason}
1157 log_to_io(LogDir, Mibs) -> ok | {error, Reason}
1158 log_to_io(LogDir, Mibs, Block | LogName) -> ok | {ok, Cnt} | {error,
1159 Reason}
1160 log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {ok, Cnt} |
1161 {error, Reason}
1162 log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) -> ok | {ok,
1163 Cnt} | {error, Reason}
1164 log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {ok,
1165 Cnt} | {error, Reason}
1166 log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok,
1167 Cnt} | {error, Reason}
1168 log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok |
1169 {ok, Cnt} | {error, Reason}
1170 Types:
1172 LogDir = string()
1174 Mibs = [MibName]
1175 MibName = string()
1176 Block = boolean()
1177 LogName = string()
1178 LogFile = string()
1179 Start = Stop = null | calendar:datetime() | {local_time, cal‐
1180 endar:datetime()} | {universal_time, calendar:datetime()}
1181 Cnt = {NumOK, NumERR}
1182 NumOK = non_neg_integer()
1183 NumERR = pos_integer()
1184 Reason = disk_log_open_error() | file_open_error() | term()
1185 disk_log_open_error() = {LogName, term()}
1186 file_open_error() = {OutFile, term()}
1187 Converts an Audit Trail Log to a readable format and prints it
1189 on stdio. LogName defaults to "snmpm_log". LogFile defaults to
1190 "snmpm.log".
1191 The Block argument indicates if the log should be blocked during
1193 conversion. This could be usefull when converting large logs
1194 (when otherwise the log could wrap during conversion). Defaults
1195 to true.
1196 See snmp:log_to_io for more info.
1198 change_log_size(NewSize) -> ok | {error, Reason}
1200 Types:
1202 NewSize = {MaxBytes, MaxFiles}
1204 MaxBytes = integer()
1205 MaxFiles = integer()
1206 Reason = term()
1207 Changes the log size of the Audit Trail Log. The application
1209 must be configured to use the audit trail log function. Please
1210 refer to disk_log(3) in Kernel Reference Manual for a descrip‐
1211 tion of how to change the log size.
1212 The change is permanent, as long as the log is not deleted. That
1214 means, the log size is remembered across reboots.
1215 set_log_type(NewType) -> {ok, OldType} | {error, Reason}
1217 Types:
1219 NewType = OldType = atl_type()
1221 Reason = term()
1222 Changes the run-time Audit Trail log type.
1224 Note that this has no effect on the application configuration as
1226 defined by configuration files, so a node restart will revert
1227 the config to whatever is in those files.
1228 This function is primarily useful in testing/debugging scenar‐
1230 ios.
1231 load_mib(Mib) -> ok | {error, Reason}
1233 Types:
1235 Mib = MibName
1237 MibName = string()
1238 Reason = term()
1239 Load a Mib into the manager. The MibName is the name of the Mib,
1241 including the path to where the compiled mib is found. For exam‐
1242 ple,
1243 Dir = code:priv_dir(my_app) ++ "/mibs/",
1245 snmpm:load_mib(Dir ++ "MY-MIB").
1246 unload_mib(Mib) -> ok | {error, Reason}
1249 Types:
1251 Mib = MibName
1253 MibName = string()
1254 Reason = term()
1255 Unload a Mib from the manager. The MibName is the name of the
1257 Mib, including the path to where the compiled mib is found. For
1258 example,
1259 Dir = code:priv_dir(my_app) ++ "/mibs/",
1261 snmpm:unload_mib(Dir ++ "MY-MIB").
1262 which_mibs() -> Mibs
1265 Types:
1267 Mibs = [{MibName, MibFile}]
1269 MibName = atom()
1270 MibFile = string()
1271 Get a list of all the mib's loaded into the manager.
1273 name_to_oid(Name) -> {ok, Oids} | {error, Reason}
1275 Types:
1277 Name = atom()
1279 Oids = [oid()]
1280 Transform a alias-name to its oid.
1282 Note that an alias-name is only unique within the mib, so when
1284 loading several mib's into a manager, there might be several
1285 instances of the same aliasname.
1286 oid_to_name(Oid) -> {ok, Name} | {error, Reason}
1288 Types:
1290 Oid = oid()
1292 Name = atom()
1293 Reason = term()
1294 Transform a oid to its aliasname.
1296 oid_to_type(Oid) -> {ok, Type} | {error, Reason}
1298 Types:
1300 Oid = oid()
1302 Type = atom()
1303 Reason = term()
1304 Retreive the type (asn1 bertype) of an oid.
1306 backup(BackupDir) -> ok | {error, Reason}
1308 Types:
1310 BackupDir = string()
1312 Backup persistent data handled by the manager.
1314 BackupDir cannot be identical to DbDir.
1316 info() -> [{Key, Value}]
1318 Types:
1320 Key = atom()
1322 Value = term()
1323 Returns a list (a dictionary) containing information about the
1325 manager. Information includes statistics counters, miscellaneous
1326 info about each process (e.g. memory allocation), and so on.
1327 verbosity(Ref, Verbosity) -> void()
1329 Types:
1331 Ref = server | config | net_if | note_store | all
1333 Verbosity = verbosity()
1334 verbosity() = silence | info | log | debug | trace
1335 Sets verbosity for the designated process. For the lowest ver‐
1337 bosity silence, nothing is printed. The higher the verbosity,
1338 the more is printed.
1339 restart(Ref) -> void()
1341 Types:
1343 Ref = net_if
1345 Restart the indicated process (Ref). Note that its not without
1347 risk to restart a process, and should therefor be used with
1348 care.
1349 format_reason(Reason) -> string()
1351 format_reason(Prefix, Reason) -> string()
1352 Types:
1354 Reason = term()
1356 Prefix = integer() | string()
1357 This utility function is used to create a formatted (pretty
1359 printable) string of the error reason received from either:
1360 * The Reason returned value if any of the sync/async get/get-
1362 next/set/get-bulk functions returns {error, Reason}
1363 * The Reason parameter in the handle_error user callback func‐
1365 tion.
1366 Prefix should either be an indention string (e.g. a list of spa‐
1368 ces) or a positive integer (which will be used to create the
1369 indention string of that length).
1370Ericsson AB snmp 5.5 snmpm(3)