1snmpm(3)                   Erlang Module Definition                   snmpm(3)
2
3
4

NAME

6       snmpm - Interface functions to the SNMP toolkit manager
7

DESCRIPTION

9       The module snmpm contains interface functions to the SNMP manager.
10

COMMON DATA TYPES

12       The following data types are used in the functions below:
13
14       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
40
41       See also the  data types in snmpa_conf.
42

EXPORTS

44       monitor() -> Ref
45
46              Types:
47
48                 Ref = reference()
49
50              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
54       demonitor(Ref) -> void()
55
56              Types:
57
58                 Ref = reference()
59
60              Turn off monitoring of the SNMP manager.
61
62       notify_started(Timeout) -> Pid
63
64              Types:
65
66                 Timeout = integer()
67                 Pid = pid()
68
69              Request  a  notification  (message)  when  the  SNMP manager has
70              started.
71
72              The Timeout is the time the request is valid. The value  has  to
73              be greater then zero.
74
75              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
81              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
85                * 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 therefore has to wait for it to start.
88
89                * When  the SNMP manager has crashed, the dependent client ap‐
90                  plication has to wait for the SNMP manager to  be  restarted
91                  before it can reconnect.
92
93              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
97              This function is used in conjunction with the monitor function.
98
99       cancel_notify_started(Pid) -> void()
100
101              Types:
102
103                 Pid = pid()
104
105              Cancel a previous request to be notified of SNMP manager start.
106
107       register_user(Id, Module, Data) -> ok | {error, Reason}
108       register_user(Id,  Module,  Data,  DefaultAgentConfig)  -> ok | {error,
109       Reason}
110
111              Types:
112
113                 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
124              Register  the  manager  entity  (=user) responsible for specific
125              agent(s).
126
127              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
133              The argument DefaultAgentConfig is used as default  values  when
134              this user register agents.
135
136              The type of Val depends on Item:
137
138              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
146
147       register_user_monitor(Id, Module, Data) -> ok | {error, Reason}
148       register_user_monitor(Id,  Module,  Data,  DefaultAgentConfig)  -> ok |
149       {error, Reason}
150
151              Types:
152
153                 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
164              Register  the  monitored  manager entity (=user) responsible for
165              specific agent(s).
166
167              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
172              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
178              The  argument  DefaultAgentConfig is used as default values when
179              this user register agents.
180
181              The type of Val depends on Item:
182
183              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
191
192       unregister_user(Id) -> ok | {error, Reason}
193
194              Types:
195
196                 Id = term()
197
198              Unregister the user.
199
200       which_users() -> Users
201
202              Types:
203
204                 Users = [UserId]
205                 UserId = term()
206
207              Get a list of the identities of all registered users.
208
209       register_agent(UserId, TargetName, Config) -> ok | {error, Reason}
210
211              Types:
212
213                 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
223              Explicitly instruct the  manager  to  handle  this  agent,  with
224              UserId as the responsible user.
225
226              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
232              TargetName  is  a  non-empty  string,  uniquely  identifying the
233              agent.
234
235              The type of Val depends on Item:
236
237              [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
249
250              Note that if no tdomain is given, the default value,  transport‐
251              DomainUdpIpv4, is used.
252
253              Note that if no port is given and if taddress does not contain a
254              port number, the default value is used.
255
256       unregister_agent(UserId, TargetName) -> ok | {error, Reason}
257
258              Types:
259
260                 UserId = term()
261                 TargetName = target_name()
262
263              Unregister the agent.
264
265       agent_info(TargetName, Item) -> {ok, Val} | {error, Reason}
266
267              Types:
268
269                 TargetName = target_name()
270                 Item = atom()
271                 Reason = term()
272
273              Retrieve agent config.
274
275       update_agent_info(UserId, TargetName, Info) -> ok | {error, Reason}
276       update_agent_info(UserId, TargetName, Item, Val) -> ok |  {error,  Rea‐
277       son}
278
279              Types:
280
281                 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
290              Update  agent config. The function update_agent_info/3 should be
291              used when several values needs to be updated atomically.
292
293              See function register_agent for more info  about  what  kind  of
294              items are allowed.
295
296       which_agents() -> Agents
297       which_agents(UserId) -> Agents
298
299              Types:
300
301                 UserId = term()
302                 Agents = [TargetName]
303                 TargetName = target_name()
304
305              Get  a list of all registered agents or all agents registered by
306              a specific user.
307
308       register_usm_user(EngineID, UserName, Conf) -> ok | {error, Reason}
309
310              Types:
311
312                 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
320              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
324              The type of Val depends on Item:
325
326              sec_name = string()
327              auth = usmNoAuthProtocol | usmHMACMD5AuthProtocol | usmHMACSHAAuthProtocol | usmHMAC128SHA224AuthProtocol | usmHMAC192SH256AuthProtocol | usmHMAC256SHA384AuthProtocol | usmHMAC384SHA512AuthProtocol
328              auth_key = [integer()]   (length 16 if auth = usmHMACMD5AuthProtocol,
329                                        length 20 if auth = usmHMACSHAAuthProtocol,
330                                        length 28 if auth = usmHMAC128SHA224AuthProtocol,
331                                        length 32 if auth = usmHMAC192SHA256AuthProtocol,
332                                        length 48 if auth = usmHMAC256SHA384AuthProtocol,
333                                        length 64 if auth = usmHMAC384SHA512AuthProtocol)
334              priv = usmNoPrivProtocol | usmDESPrivProtocol | usmAesCfb128Protocol
335              priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb128Protocol).
336
337
338       unregister_usm_user(EngineID, UserName) -> ok | {error, Reason}
339
340              Types:
341
342                 EngineID = string()
343                 UserName = string()
344                 Reason = term()
345
346              Unregister this USM user.
347
348       usm_user_info(EngineID, UserName, Item) -> {ok, Val} | {error, Reason}
349
350              Types:
351
352                 EngineID = string()
353                 UsmName = string()
354                 Item = sec_name | auth | auth_key | priv | priv_key
355                 Reason = term()
356
357              Retrieve usm user config.
358
359       update_usm_user_info(EngineID, UserName, Item, Val)  ->  ok  |  {error,
360       Reason}
361
362              Types:
363
364                 EngineID = string()
365                 UsmName = string()
366                 Item = sec_name | auth | auth_key | priv | priv_key
367                 Val = term()
368                 Reason = term()
369
370              Update usm user config.
371
372       which_usm_users() -> UsmUsers
373
374              Types:
375
376                 UsmUsers = [{EngineID,UserName}]
377                 EngineID = string()
378                 UsmName = string()
379
380              Get a list of all registered usm users.
381
382       which_usm_users(EngineID) -> UsmUsers
383
384              Types:
385
386                 UsmUsers = [UserName]
387                 UserName = string()
388
389              Get a list of all registered usm users with engine-id EngineID.
390
391       sync_get2(UserId,  TargetName,  Oids)  ->  {ok, SnmpReply, Remaining} |
392       {error, Reason}
393       sync_get2(UserId, TargetName, Oids, SendOpts) ->  {ok,  SnmpReply,  Re‐
394       maining} | {error, Reason}
395
396              Types:
397
398                 UserId = term()
399                 TargetName = target_name()
400                 Oids = [oid()]
401                 SendOpts = send_opts()
402                 send_opts() = [send_opt()]
403                 send_opt() = {context, string()} | {timeout, pos_integer()} |
404                 {extra, term()}  |  {community,  community()}  |  {sec_model,
405                 sec_model()}    |    {sec_name,   string()}   |   {sec_level,
406                 sec_level()} | {max_message_size, pos_integer()}
407                 SnmpReply = snmp_reply()
408                 Remaining = integer()
409                 Reason  =   {send_failed,   ReqId,   ActualReason}   |   {in‐
410                 valid_sec_info, SecInfo, SnmpInfo} | term()
411                 ReqId = term()
412                 ActualReason = term()
413                 SecInfo = [sec_info()]
414                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
415                 sec_tag() = atom()
416                 ExpectedValue = ReceivedValue = term()
417                 SnmpInfo = term()
418
419              Synchronous get-request.
420
421              Remaining  is the remaining time of the given (or default) time‐
422              out time.
423
424              When Reason is {send_failed,  ...}  it  means  that  the  net_if
425              process failed to send the message. This could happen because of
426              any number of reasons, i.e. encoding error. ActualReason is  the
427              actual reason in this case.
428
429              The  send option extra specifies an opaque data structure passed
430              on to the net-if process. The net-if process  included  in  this
431              application  makes,  with one exception, no use of this info, so
432              the only use for it in such a option (when using  the  built  in
433              net-if)  would be tracing. The one usage exception is: Any tuple
434              with snmpm_extra_info_tag as its first element is  reserved  for
435              internal use.
436
437              Some  of  the  send  options  (community,  sec_model,  sec_name,
438              sec_level and max_message_size) are override options.  That  is,
439              for  this request, they override any configuration done when the
440              agent was registered.
441
442              For SnmpInfo, see the user callback function handle_report.
443
444       async_get2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
445       async_get2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error,
446       Reason}
447
448              Types:
449
450                 UserId = term()
451                 TargetName = target_name()
452                 Oids = [oid()]
453                 SendOpts = send_opts()
454                 send_opts() = [send_opt()]
455                 send_opt() = {context, string()} | {timeout, pos_integer()} |
456                 {extra, term()}  |  {community,  community()}  |  {sec_model,
457                 sec_model()}    |    {sec_name,   string()}   |   {sec_level,
458                 sec_level()} | {max_message_size, pos_integer()}
459                 ReqId = term()
460                 Reason = term()
461
462              Asynchronous get-request.
463
464              The reply, if it arrives, will be delivered to the user  through
465              a call to the snmpm_user callback function handle_pdu.
466
467              The  send  option  timeout specifies for how long the request is
468              valid (after which the manager is free to delete it).
469
470              The send option extra specifies an opaque data structure  passed
471              on  to  the  net-if process. The net-if process included in this
472              application makes, with one exception, no use of this  info,  so
473              the  only  use  for it in such a option (when using the built in
474              net-if) would be tracing. The one usage exception is: Any  tuple
475              with  snmpm_extra_info_tag  as its first element is reserved for
476              internal use.
477
478              Some  of  the  send  options  (community,  sec_model,  sec_name,
479              sec_level  and  max_message_size) are override options. That is,
480              for this request, they override any configuration done when  the
481              agent was registered.
482
483       sync_get_next2(UserId,  TargetName, Oids) -> {ok, SnmpReply, Remaining}
484       | {error, Reason}
485       sync_get_next2(UserId, TargetName, Oids, SendOpts) ->  {ok,  SnmpReply,
486       Remaining} | {error, Reason}
487
488              Types:
489
490                 UserId = term()
491                 TargetName = target_name()
492                 Oids = [oid()]
493                 SendOpts = send_opts()
494                 send_opts() = [send_opt()]
495                 send_opt() = {context, string()} | {timeout, pos_integer()} |
496                 {extra, term()}  |  {community,  community()}  |  {sec_model,
497                 sec_model()}    |    {sec_name,   string()}   |   {sec_level,
498                 sec_level()} | {max_message_size, pos_integer()}
499                 SnmpReply = snmp_reply()
500                 Remaining = integer()
501                 Reason  =   {send_failed,   ReqId,   ActualReason}   |   {in‐
502                 valid_sec_info, SecInfo, SnmpInfo} | term()
503                 ReqId = term()
504                 ActualReason = term()
505                 SecInfo = [sec_info()]
506                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
507                 sec_tag() = atom()
508                 ExpectedValue = ReceivedValue = term()
509                 SnmpInfo = term()
510
511              Synchronous get-next-request.
512
513              Remaining  is the remaining time of the given (or default) time‐
514              out time.
515
516              When Reason is {send_failed,  ...}  it  means  that  the  net_if
517              process failed to send the message. This could happen because of
518              any number of reasons, i.e. encoding error. ActualReason is  the
519              actual reason in this case.
520
521              The  send option extra specifies an opaque data structure passed
522              on to the net-if process. The net-if process  included  in  this
523              application  makes,  with one exception, no use of this info, so
524              the only use for it in such a option (when using  the  built  in
525              net-if)  would be tracing. The one usage exception is: Any tuple
526              with snmpm_extra_info_tag as its first element is  reserved  for
527              internal use.
528
529              Some  of  the  send  options  (community,  sec_model,  sec_name,
530              sec_level and max_message_size) are override options.  That  is,
531              for  this request, they override any configuration done when the
532              agent was registered.
533
534              For SnmpInfo, see the user callback function handle_report.
535
536       async_get_next2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Rea‐
537       son}
538       async_get_next2(UserId,  TargetName,  Oids,  SendOpts) -> {ok, ReqId} |
539       {error, Reason}
540
541              Types:
542
543                 UserId = term()
544                 TargetName = target_name()
545                 Oids = [oid()]
546                 send_opt() = {context, string()} | {timeout, pos_integer()} |
547                 {extra,  term()}  |  {community,  community()}  | {sec_model,
548                 sec_model()}   |   {sec_name,   string()}    |    {sec_level,
549                 sec_level()} | {max_message_size, pos_integer()}
550                 ReqId = integer()
551                 Reason = term()
552
553              Asynchronous get-next-request.
554
555              The  reply  will  be delivered to the user through a call to the
556              snmpm_user callback function handle_pdu.
557
558              The send option timeout specifies for how long  the  request  is
559              valid (after which the manager is free to delete it).
560
561              The  send option extra specifies an opaque data structure passed
562              on to the net-if process. The net-if process  included  in  this
563              application  makes,  with one exception, no use of this info, so
564              the only use for it in such a option (when using  the  built  in
565              net-if)  would be tracing. The one usage exception is: Any tuple
566              with snmpm_extra_info_tag as its first element is  reserved  for
567              internal use.
568
569              Some  of  the  send  options  (community,  sec_model,  sec_name,
570              sec_level and max_message_size) are override options.  That  is,
571              for  this request, they override any configuration done when the
572              agent was registered.
573
574       sync_set2(UserId, TargetName, VarsAndVals) -> {ok,  SnmpReply,  Remain‐
575       ing} | {error, Reason}
576       sync_set2(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, SnmpReply,
577       Remaining} | {error, Reason}
578
579              Types:
580
581                 UserId = term()
582                 TargetName = target_name()
583                 VarsAndVals = vars_and_vals()
584                 SendOpts = send_opts()
585                 send_opts() = [send_opt()]
586                 send_opt() = {context, string()} | {timeout, pos_integer()} |
587                 {extra,  term()}  |  {community,  community()}  | {sec_model,
588                 sec_model()}   |   {sec_name,   string()}    |    {sec_level,
589                 sec_level()} | {max_message_size, pos_integer()}
590                 SnmpReply = snmp_reply()
591                 Remaining = integer()
592                 Reason   =   {send_failed,   ReqId,   ActualReason}   |  {in‐
593                 valid_sec_info, SecInfo, SnmpInfo} | term()
594                 ReqId = term()
595                 ActualReason = term()
596                 SecInfo = [sec_info()]
597                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
598                 sec_tag() = atom()
599                 ExpectedValue = ReceivedValue = term()
600                 SnmpInfo = term()
601
602              Synchronous set-request.
603
604              Remaining is the remaining time of the given (or default)  time‐
605              out time.
606
607              When  Reason  is  {send_failed,  ...}  it  means that the net_if
608              process failed to send the message. This could happen because of
609              any  number of reasons, i.e. encoding error. ActualReason is the
610              actual reason in this case.
611
612              When var_and_val() is {oid(), value()}, the manager makes an ed‐
613              ucated guess based on the loaded mibs.
614
615              The  send option extra specifies an opaque data structure passed
616              on to the net-if process. The net-if process  included  in  this
617              application  makes,  with one exception, no use of this info, so
618              the only use for it in such a option (when using  the  built  in
619              net-if)  would be tracing. The one usage exception is: Any tuple
620              with snmpm_extra_info_tag as its first element is  reserved  for
621              internal use.
622
623              Some  of  the  send  options  (community,  sec_model,  sec_name,
624              sec_level and max_message_size) are override options.  That  is,
625              for  this request, they override any configuration done when the
626              agent was registered.
627
628              For SnmpInfo, see the user callback function handle_report.
629
630       async_set2(UserId, TargetName, VarsAndVals) -> {ok,  ReqId}  |  {error,
631       Reason}
632       async_set2(UserId,  TargetName, VarsAndVals, SendOpts) -> {ok, ReqId} |
633       {error, Reason}
634
635              Types:
636
637                 UserId = term()
638                 TargetName = target_name()
639                 VarsAndVals = vars_and_vals()
640                 SendOpts = send_opts()
641                 send_opts() = [send_opt()]
642                 send_opt() = {context, string()} | {timeout, pos_integer()} |
643                 {extra,  term()}  |  {community,  community()}  | {sec_model,
644                 sec_model()}   |   {sec_name,   string()}    |    {sec_level,
645                 sec_level()} | {max_message_size, pos_integer()}
646                 ReqId = term()
647                 Reason = term()
648
649              Asynchronous set-request.
650
651              The  reply  will  be delivered to the user through a call to the
652              snmpm_user callback function handle_pdu.
653
654              The send option timeout specifies for how long  the  request  is
655              valid (after which the manager is free to delete it).
656
657              When var_and_val() is {oid(), value()}, the manager makes an ed‐
658              ucated guess based on the loaded mibs.
659
660              The send option extra specifies an opaque data structure  passed
661              on  to  the  net-if process. The net-if process included in this
662              application makes, with one exception, no use of this  info,  so
663              the  only  use  for it in such a option (when using the built in
664              net-if) would be tracing. The one usage exception is: Any  tuple
665              with  snmpm_extra_info_tag  as its first element is reserved for
666              internal use.
667
668              Some  of  the  send  options  (community,  sec_model,  sec_name,
669              sec_level  and  max_message_size) are override options. That is,
670              for this request, they override any configuration done when  the
671              agent was registered.
672
673       sync_get_bulk2(UserId,  TragetName,  NonRep, MaxRep, Oids) -> {ok, Snm‐
674       pReply, Remaining} | {error, Reason}
675       sync_get_bulk2(UserId, TragetName, NonRep, MaxRep, Oids,  SendOpts)  ->
676       {ok, SnmpReply, Remaining} | {error, Reason}
677
678              Types:
679
680                 UserId = term()
681                 TargetName = target_name()
682                 NonRep = integer()
683                 MaxRep = integer()
684                 Oids = [oid()]
685                 SendOpts = send_opts()
686                 send_opts() = [send_opt()]
687                 send_opt() = {context, string()} | {timeout, pos_integer()} |
688                 {extra, term()}  |  {community,  community()}  |  {sec_model,
689                 sec_model()}    |    {sec_name,   string()}   |   {sec_level,
690                 sec_level()} | {max_message_size, pos_integer()}
691                 SnmpReply = snmp_reply()
692                 Remaining = integer()
693                 Reason  =   {send_failed,   ReqId,   ActualReason}   |   {in‐
694                 valid_sec_info, SecInfo, SnmpInfo} | term()
695                 ReqId = term()
696                 ActualReason = term()
697                 SecInfo = [sec_info()]
698                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
699                 sec_tag() = atom()
700                 ExpectedValue = ReceivedValue = term()
701                 SnmpInfo = term()
702
703              Synchronous get-bulk-request (See RFC1905).
704
705              Remaining  is the remaining time of the given (or default) time‐
706              out time.
707
708              When Reason is {send_failed,  ...}  it  means  that  the  net_if
709              process failed to send the message. This could happen because of
710              any number of reasons, i.e. encoding error. ActualReason is  the
711              actual reason in this case.
712
713              The  send option extra specifies an opaque data structure passed
714              on to the net-if process. The net-if process  included  in  this
715              application  makes,  with one exception, no use of this info, so
716              the only use for it in such a option (when using  the  built  in
717              net-if)  would be tracing. The one usage exception is: Any tuple
718              with snmpm_extra_info_tag as its first element is  reserved  for
719              internal use.
720
721              Some  of  the  send  options  (community,  sec_model,  sec_name,
722              sec_level and max_message_size) are override options.  That  is,
723              for  this request, they override any configuration done when the
724              agent was registered.
725
726              For SnmpInfo, see the user callback function handle_report.
727
728       async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) ->  {ok,  Re‐
729       qId} | {error, Reason}
730       async_get_bulk2(UserId,  TargetName, NonRep, MaxRep, Oids, SendOpts) ->
731       {ok, ReqId} | {error, Reason}
732
733              Types:
734
735                 UserId = term()
736                 TargetName = target_name()
737                 NonRep = integer()
738                 MaxRep = integer()
739                 Oids = [oid()]
740                 SendOpts = send_opts()
741                 send_opts() = [send_opt()]
742                 send_opt() = {context, string()} | {timeout, pos_integer()} |
743                 {extra,  term()}  |  {community,  community()}  | {sec_model,
744                 sec_model()}   |   {sec_name,   string()}    |    {sec_level,
745                 sec_level()} | {max_message_size, pos_integer()}
746                 ReqId = integer()
747                 Reason = term()
748
749              Asynchronous get-bulk-request (See RFC1905).
750
751              The  reply  will  be delivered to the user through a call to the
752              snmpm_user callback function handle_pdu.
753
754              The send option timeout specifies for how long  the  request  is
755              valid (after which the manager is free to delete it).
756
757              The  send option extra specifies an opaque data structure passed
758              on to the net-if process. The net-if process  included  in  this
759              application makes no use of this info, so the only use for it in
760              such a configuration (when using the built in net-if)  would  be
761              tracing.
762
763              Some  of  the  send  options  (community,  sec_model,  sec_name,
764              sec_level and max_message_size) are override options.  That  is,
765              for  this request, they override any configuration done when the
766              agent was registered.
767
768       cancel_async_request(UserId, ReqId) -> ok | {error, Reason}
769
770              Types:
771
772                 UserId = term()
773                 ReqId = term()
774                 Reason = term()
775
776              Cancel a previous asynchronous request.
777
778       log_to_txt(LogDir)
779       log_to_txt(LogDir, Block | Mibs)
780       log_to_txt(LogDir, Mibs, Block | OutFile) -> ok | {ok, Cnt}  |  {error,
781       Reason}
782       log_to_txt(LogDir,  Mibs, OutFile, Block | LogName) -> ok | {ok, Cnt} |
783       {error, Reason}
784       log_to_txt(LogDir, Mibs, OutFile, LogName, Block |  LogFile)  ->  ok  |
785       {ok, Cnt} | {error, Reason}
786       log_to_txt(LogDir,  Mibs,  OutFile, LogName, LogFile, Block | Start) ->
787       ok | {ok, Cnt} | {error, Reason}
788       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok
789       | {ok, Cnt} | {error, Reason}
790       log_to_txt(LogDir,  Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok
791       | {ok, Cnt} | {error, Reason}
792       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)
793       -> ok | {ok, Cnt} | {error, Reason}
794
795              Types:
796
797                 LogDir = string()
798                 Mibs = [MibName]
799                 MibName = string()
800                 Block = boolean()
801                 OutFile = string()
802                 LogName = string()
803                 LogFile = string()
804                 Start = Stop = null | calendar:datetime() | {local_time, cal‐
805                 endar:datetime()} | {universal_time, calendar:datetime()}
806                 Cnt = {NumOK, NumERR}
807                 NumOK = non_neg_integer()
808                 NumERR = pos_integer()
809                 Reason = disk_log_open_error() | file_open_error() | term()
810                 disk_log_open_error() = {LogName, term()}
811                 file_open_error() = {OutFile, term()}
812
813              Converts an Audit Trail Log to a readable text file. OutFile de‐
814              faults  to  "./snmpm_log.txt".  LogName defaults to "snmpm_log".
815              LogFile defaults to "snmpm.log".
816
817              The Block argument indicates if the log should be blocked during
818              conversion.  This  could  be  useful  when converting large logs
819              (when otherwise the log could wrap during conversion).  Defaults
820              to true.
821
822              See snmp:log_to_txt for more info.
823
824       log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
825       log_to_io(LogDir, Block | Mibs) -> ok | {ok, Cnt} | {error, Reason}
826       log_to_io(LogDir, Mibs) -> ok | {error, Reason}
827       log_to_io(LogDir,  Mibs,  Block  | LogName) -> ok | {ok, Cnt} | {error,
828       Reason}
829       log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {ok,  Cnt}  |
830       {error, Reason}
831       log_to_io(LogDir,  Mibs,  LogName, LogFile, Block | Start) -> ok | {ok,
832       Cnt} | {error, Reason}
833       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) ->  ok  |  {ok,
834       Cnt} | {error, Reason}
835       log_to_io(LogDir,  Mibs,  LogName,  LogFile,  Start, Stop) -> ok | {ok,
836       Cnt} | {error, Reason}
837       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) ->  ok  |
838       {ok, Cnt} | {error, Reason}
839
840              Types:
841
842                 LogDir = string()
843                 Mibs = [MibName]
844                 MibName = string()
845                 Block = boolean()
846                 LogName = string()
847                 LogFile = string()
848                 Start = Stop = null | calendar:datetime() | {local_time, cal‐
849                 endar:datetime()} | {universal_time, calendar:datetime()}
850                 Cnt = {NumOK, NumERR}
851                 NumOK = non_neg_integer()
852                 NumERR = pos_integer()
853                 Reason = disk_log_open_error() | file_open_error() | term()
854                 disk_log_open_error() = {LogName, term()}
855                 file_open_error() = {OutFile, term()}
856
857              Converts an Audit Trail Log to a readable format and  prints  it
858              on  stdio.  LogName defaults to "snmpm_log". LogFile defaults to
859              "snmpm.log".
860
861              The Block argument indicates if the log should be blocked during
862              conversion.  This  could  be  useful  when converting large logs
863              (when otherwise the log could wrap during conversion).  Defaults
864              to true.
865
866              See snmp:log_to_io for more info.
867
868       change_log_size(NewSize) -> ok | {error, Reason}
869
870              Types:
871
872                 NewSize = {MaxBytes, MaxFiles}
873                 MaxBytes = integer()
874                 MaxFiles = integer()
875                 Reason = term()
876
877              Changes  the  log  size  of the Audit Trail Log. The application
878              must be configured to use the audit trail log  function.  Please
879              refer  to  disk_log(3) in Kernel Reference Manual for a descrip‐
880              tion of how to change the log size.
881
882              The change is permanent, as long as the log is not deleted. That
883              means, the log size is remembered across reboots.
884
885       set_log_type(NewType) -> {ok, OldType} | {error, Reason}
886
887              Types:
888
889                 NewType = OldType = atl_type()
890                 Reason = term()
891
892              Changes the run-time Audit Trail log type.
893
894              Note that this has no effect on the application configuration as
895              defined by configuration files, so a node  restart  will  revert
896              the config to whatever is in those files.
897
898              This  function  is primarily useful in testing/debugging scenar‐
899              ios.
900
901       load_mib(Mib) -> ok | {error, Reason}
902
903              Types:
904
905                 Mib = MibName
906                 MibName = string()
907                 Reason = term()
908
909              Load a Mib into the manager. The MibName is the name of the Mib,
910              including the path to where the compiled mib is found. For exam‐
911              ple,
912
913                        Dir = code:priv_dir(my_app) ++ "/mibs/",
914                        snmpm:load_mib(Dir ++ "MY-MIB").
915
916
917       unload_mib(Mib) -> ok | {error, Reason}
918
919              Types:
920
921                 Mib = MibName
922                 MibName = string()
923                 Reason = term()
924
925              Unload a Mib from the manager. The MibName is the  name  of  the
926              Mib,  including the path to where the compiled mib is found. For
927              example,
928
929                        Dir = code:priv_dir(my_app) ++ "/mibs/",
930                        snmpm:unload_mib(Dir ++ "MY-MIB").
931
932
933       which_mibs() -> Mibs
934
935              Types:
936
937                 Mibs = [{MibName, MibFile}]
938                 MibName = atom()
939                 MibFile = string()
940
941              Get a list of all the mib's loaded into the manager.
942
943       name_to_oid(Name) -> {ok, Oids} | {error, Reason}
944
945              Types:
946
947                 Name = atom()
948                 Oids = [oid()]
949
950              Transform a alias-name to its oid.
951
952              Note that an alias-name is only unique within the mib,  so  when
953              loading several mib's into a manager, there might be several in‐
954              stances of the same aliasname.
955
956       oid_to_name(Oid) -> {ok, Name} | {error, Reason}
957
958              Types:
959
960                 Oid = oid()
961                 Name = atom()
962                 Reason = term()
963
964              Transform a oid to its aliasname.
965
966       oid_to_type(Oid) -> {ok, Type} | {error, Reason}
967
968              Types:
969
970                 Oid = oid()
971                 Type = atom()
972                 Reason = term()
973
974              Retrieve the type (asn1 bertype) of an oid.
975
976       backup(BackupDir) -> ok | {error, Reason}
977
978              Types:
979
980                 BackupDir = string()
981
982              Backup persistent data handled by the manager.
983
984              BackupDir cannot be identical to DbDir.
985
986       info() -> [{Key, Value}]
987
988              Types:
989
990                 Key = atom()
991                 Value = term()
992
993              Returns a list (a dictionary) containing information  about  the
994              manager. Information includes statistics counters, miscellaneous
995              info about each process (e.g. memory allocation), and so on.
996
997       verbosity(Ref, Verbosity) -> void()
998
999              Types:
1000
1001                 Ref = server | config | net_if | note_store | all
1002                 Verbosity = verbosity()
1003                 verbosity() = silence | info | log | debug | trace
1004
1005              Sets verbosity for the designated process. For the  lowest  ver‐
1006              bosity  silence,  nothing  is printed. The higher the verbosity,
1007              the more is printed.
1008
1009       restart(Ref) -> void()
1010
1011              Types:
1012
1013                 Ref = net_if
1014
1015              Restart the indicated process (Ref). Note that its  not  without
1016              risk  to  restart  a  process, and should therefore be used with
1017              care.
1018
1019       format_reason(Reason) -> string()
1020       format_reason(Prefix, Reason) -> string()
1021
1022              Types:
1023
1024                 Reason = term()
1025                 Prefix = integer() | string()
1026
1027              This utility function is used  to  create  a  formatted  (pretty
1028              printable) string of the error reason received from either:
1029
1030                * The  Reason returned value if any of the sync/async get/get-
1031                  next/set/get-bulk functions returns {error, Reason}
1032
1033                * The Reason parameter in the handle_error user callback func‐
1034                  tion.
1035
1036              Prefix  should  either  be an indentation string (e.g. a list of
1037              spaces) or a positive integer (which will be used to create  the
1038              indentation string of that length).
1039
1040
1041
1042Ericsson AB                       snmp 5.13.5                         snmpm(3)
Impressum