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 therefor 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 | 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
333
334       unregister_usm_user(EngineID, UserName) -> ok | {error, Reason}
335
336              Types:
337
338                 EngineID = string()
339                 UserName = string()
340                 Reason = term()
341
342              Unregister this USM user.
343
344       usm_user_info(EngineID, UserName, Item) -> {ok, Val} | {error, Reason}
345
346              Types:
347
348                 EngineID = string()
349                 UsmName = string()
350                 Item = sec_name | auth | auth_key | priv | priv_key
351                 Reason = term()
352
353              Retrieve usm user config.
354
355       update_usm_user_info(EngineID, UserName, Item, Val)  ->  ok  |  {error,
356       Reason}
357
358              Types:
359
360                 EngineID = string()
361                 UsmName = string()
362                 Item = sec_name | auth | auth_key | priv | priv_key
363                 Val = term()
364                 Reason = term()
365
366              Update usm user config.
367
368       which_usm_users() -> UsmUsers
369
370              Types:
371
372                 UsmUsers = [{EngineID,UserName}]
373                 EngineID = string()
374                 UsmName = string()
375
376              Get a list of all registered usm users.
377
378       which_usm_users(EngineID) -> UsmUsers
379
380              Types:
381
382                 UsmUsers = [UserName]
383                 UserName = string()
384
385              Get a list of all registered usm users with engine-id EngineID.
386
387       sync_get2(UserId,  TargetName,  Oids)  ->  {ok, SnmpReply, Remaining} |
388       {error, Reason}
389       sync_get2(UserId, TargetName, Oids, SendOpts) ->  {ok,  SnmpReply,  Re‐
390       maining} | {error, Reason}
391
392              Types:
393
394                 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}   |   {in‐
406                 valid_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
415              Synchronous get-request.
416
417              Remaining  is the remaining time of the given (or default) time‐
418              out time.
419
420              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
425              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
433              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
438              For SnmpInfo, see the user callback function handle_report.
439
440       async_get2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
441       async_get2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error,
442       Reason}
443
444              Types:
445
446                 UserId = term()
447                 TargetName = target_name()
448                 Oids = [oid()]
449                 SendOpts = send_opts()
450                 send_opts() = [send_opt()]
451                 send_opt() = {context, string()} | {timeout, pos_integer()} |
452                 {extra, term()}  |  {community,  community()}  |  {sec_model,
453                 sec_model()}    |    {sec_name,   string()}   |   {sec_level,
454                 sec_level()} | {max_message_size, pos_integer()}
455                 ReqId = term()
456                 Reason = term()
457
458              Asynchronous get-request.
459
460              The reply, if it arrives, will be delivered to the user  through
461              a call to the snmpm_user callback function handle_pdu.
462
463              The  send  option  timeout specifies for how long the request is
464              valid (after which the manager is free to delete it).
465
466              The send option extra specifies an opaque data structure  passed
467              on  to  the  net-if process. The net-if process included in this
468              application makes, with one exception, no use of this  info,  so
469              the  only  use  for it in such a option (when using the built in
470              net-if) would be tracing. The one usage exception is: Any  tuple
471              with  snmpm_extra_info_tag  as its first element is reserved for
472              internal use.
473
474              Some  of  the  send  options  (community,  sec_model,  sec_name,
475              sec_level  and  max_message_size) are override options. That is,
476              for this request, they override any configuration done when  the
477              agent was registered.
478
479       sync_get_next2(UserId,  TargetName, Oids) -> {ok, SnmpReply, Remaining}
480       | {error, Reason}
481       sync_get_next2(UserId, TargetName, Oids, SendOpts) ->  {ok,  SnmpReply,
482       Remaining} | {error, Reason}
483
484              Types:
485
486                 UserId = term()
487                 TargetName = target_name()
488                 Oids = [oid()]
489                 SendOpts = send_opts()
490                 send_opts() = [send_opt()]
491                 send_opt() = {context, string()} | {timeout, pos_integer()} |
492                 {extra, term()}  |  {community,  community()}  |  {sec_model,
493                 sec_model()}    |    {sec_name,   string()}   |   {sec_level,
494                 sec_level()} | {max_message_size, pos_integer()}
495                 SnmpReply = snmp_reply()
496                 Remaining = integer()
497                 Reason  =   {send_failed,   ReqId,   ActualReason}   |   {in‐
498                 valid_sec_info, SecInfo, SnmpInfo} | term()
499                 ReqId = term()
500                 ActualReason = term()
501                 SecInfo = [sec_info()]
502                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
503                 sec_tag() = atom()
504                 ExpectedValue = ReceivedValue = term()
505                 SnmpInfo = term()
506
507              Synchronous get-next-request.
508
509              Remaining  is the remaining time of the given (or default) time‐
510              out time.
511
512              When Reason is {send_failed,  ...}  it  means  that  the  net_if
513              process failed to send the message. This could happen because of
514              any number of reasons, i.e. encoding error. ActualReason is  the
515              actual reason in this case.
516
517              The  send option extra specifies an opaque data structure passed
518              on to the net-if process. The net-if process  included  in  this
519              application  makes,  with one exception, no use of this info, so
520              the only use for it in such a option (when using  the  built  in
521              net-if)  would be tracing. The one usage exception is: Any tuple
522              with snmpm_extra_info_tag as its first element is  reserved  for
523              internal use.
524
525              Some  of  the  send  options  (community,  sec_model,  sec_name,
526              sec_level and max_message_size) are override options.  That  is,
527              for  this request, they override any configuration done when the
528              agent was registered.
529
530              For SnmpInfo, see the user callback function handle_report.
531
532       async_get_next2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Rea‐
533       son}
534       async_get_next2(UserId,  TargetName,  Oids,  SendOpts) -> {ok, ReqId} |
535       {error, Reason}
536
537              Types:
538
539                 UserId = term()
540                 TargetName = target_name()
541                 Oids = [oid()]
542                 send_opt() = {context, string()} | {timeout, pos_integer()} |
543                 {extra,  term()}  |  {community,  community()}  | {sec_model,
544                 sec_model()}   |   {sec_name,   string()}    |    {sec_level,
545                 sec_level()} | {max_message_size, pos_integer()}
546                 ReqId = integer()
547                 Reason = term()
548
549              Asynchronous get-next-request.
550
551              The  reply  will  be delivered to the user through a call to the
552              snmpm_user callback function handle_pdu.
553
554              The send option timeout specifies for how long  the  request  is
555              valid (after which the manager is free to delete it).
556
557              The  send option extra specifies an opaque data structure passed
558              on to the net-if process. The net-if process  included  in  this
559              application  makes,  with one exception, no use of this info, so
560              the only use for it in such a option (when using  the  built  in
561              net-if)  would be tracing. The one usage exception is: Any tuple
562              with snmpm_extra_info_tag as its first element is  reserved  for
563              internal use.
564
565              Some  of  the  send  options  (community,  sec_model,  sec_name,
566              sec_level and max_message_size) are override options.  That  is,
567              for  this request, they override any configuration done when the
568              agent was registered.
569
570       sync_set2(UserId, TargetName, VarsAndVals) -> {ok,  SnmpReply,  Remain‐
571       ing} | {error, Reason}
572       sync_set2(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, SnmpReply,
573       Remaining} | {error, Reason}
574
575              Types:
576
577                 UserId = term()
578                 TargetName = target_name()
579                 VarsAndVals = vars_and_vals()
580                 SendOpts = send_opts()
581                 send_opts() = [send_opt()]
582                 send_opt() = {context, string()} | {timeout, pos_integer()} |
583                 {extra,  term()}  |  {community,  community()}  | {sec_model,
584                 sec_model()}   |   {sec_name,   string()}    |    {sec_level,
585                 sec_level()} | {max_message_size, pos_integer()}
586                 SnmpReply = snmp_reply()
587                 Remaining = integer()
588                 Reason   =   {send_failed,   ReqId,   ActualReason}   |  {in‐
589                 valid_sec_info, SecInfo, SnmpInfo} | term()
590                 ReqId = term()
591                 ActualReason = term()
592                 SecInfo = [sec_info()]
593                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
594                 sec_tag() = atom()
595                 ExpectedValue = ReceivedValue = term()
596                 SnmpInfo = term()
597
598              Synchronous set-request.
599
600              Remaining is the remaining time of the given (or default)  time‐
601              out time.
602
603              When  Reason  is  {send_failed,  ...}  it  means that the net_if
604              process failed to send the message. This could happen because of
605              any  number of reasons, i.e. encoding error. ActualReason is the
606              actual reason in this case.
607
608              When var_and_val() is {oid(), value()}, the manager makes an ed‐
609              ucated guess based on the loaded mibs.
610
611              The  send option extra specifies an opaque data structure passed
612              on to the net-if process. The net-if process  included  in  this
613              application  makes,  with one exception, no use of this info, so
614              the only use for it in such a option (when using  the  built  in
615              net-if)  would be tracing. The one usage exception is: Any tuple
616              with snmpm_extra_info_tag as its first element is  reserved  for
617              internal use.
618
619              Some  of  the  send  options  (community,  sec_model,  sec_name,
620              sec_level and max_message_size) are override options.  That  is,
621              for  this request, they override any configuration done when the
622              agent was registered.
623
624              For SnmpInfo, see the user callback function handle_report.
625
626       async_set2(UserId, TargetName, VarsAndVals) -> {ok,  ReqId}  |  {error,
627       Reason}
628       async_set2(UserId,  TargetName, VarsAndVals, SendOpts) -> {ok, ReqId} |
629       {error, Reason}
630
631              Types:
632
633                 UserId = term()
634                 TargetName = target_name()
635                 VarsAndVals = vars_and_vals()
636                 SendOpts = send_opts()
637                 send_opts() = [send_opt()]
638                 send_opt() = {context, string()} | {timeout, pos_integer()} |
639                 {extra,  term()}  |  {community,  community()}  | {sec_model,
640                 sec_model()}   |   {sec_name,   string()}    |    {sec_level,
641                 sec_level()} | {max_message_size, pos_integer()}
642                 ReqId = term()
643                 Reason = term()
644
645              Asynchronous set-request.
646
647              The  reply  will  be delivered to the user through a call to the
648              snmpm_user callback function handle_pdu.
649
650              The send option timeout specifies for how long  the  request  is
651              valid (after which the manager is free to delete it).
652
653              When var_and_val() is {oid(), value()}, the manager makes an ed‐
654              ucated guess based on the loaded mibs.
655
656              The send option extra specifies an opaque data structure  passed
657              on  to  the  net-if process. The net-if process included in this
658              application makes, with one exception, no use of this  info,  so
659              the  only  use  for it in such a option (when using the built in
660              net-if) would be tracing. The one usage exception is: Any  tuple
661              with  snmpm_extra_info_tag  as its first element is reserved for
662              internal use.
663
664              Some  of  the  send  options  (community,  sec_model,  sec_name,
665              sec_level  and  max_message_size) are override options. That is,
666              for this request, they override any configuration done when  the
667              agent was registered.
668
669       sync_get_bulk2(UserId,  TragetName,  NonRep, MaxRep, Oids) -> {ok, Snm‐
670       pReply, Remaining} | {error, Reason}
671       sync_get_bulk2(UserId, TragetName, NonRep, MaxRep, Oids,  SendOpts)  ->
672       {ok, SnmpReply, Remaining} | {error, Reason}
673
674              Types:
675
676                 UserId = term()
677                 TargetName = target_name()
678                 NonRep = integer()
679                 MaxRep = integer()
680                 Oids = [oid()]
681                 SendOpts = send_opts()
682                 send_opts() = [send_opt()]
683                 send_opt() = {context, string()} | {timeout, pos_integer()} |
684                 {extra, term()}  |  {community,  community()}  |  {sec_model,
685                 sec_model()}    |    {sec_name,   string()}   |   {sec_level,
686                 sec_level()} | {max_message_size, pos_integer()}
687                 SnmpReply = snmp_reply()
688                 Remaining = integer()
689                 Reason  =   {send_failed,   ReqId,   ActualReason}   |   {in‐
690                 valid_sec_info, SecInfo, SnmpInfo} | term()
691                 ReqId = term()
692                 ActualReason = term()
693                 SecInfo = [sec_info()]
694                 sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}
695                 sec_tag() = atom()
696                 ExpectedValue = ReceivedValue = term()
697                 SnmpInfo = term()
698
699              Synchronous get-bulk-request (See RFC1905).
700
701              Remaining  is the remaining time of the given (or default) time‐
702              out time.
703
704              When Reason is {send_failed,  ...}  it  means  that  the  net_if
705              process failed to send the message. This could happen because of
706              any number of reasons, i.e. encoding error. ActualReason is  the
707              actual reason in this case.
708
709              The  send option extra specifies an opaque data structure passed
710              on to the net-if process. The net-if process  included  in  this
711              application  makes,  with one exception, no use of this info, so
712              the only use for it in such a option (when using  the  built  in
713              net-if)  would be tracing. The one usage exception is: Any tuple
714              with snmpm_extra_info_tag as its first element is  reserved  for
715              internal use.
716
717              Some  of  the  send  options  (community,  sec_model,  sec_name,
718              sec_level and max_message_size) are override options.  That  is,
719              for  this request, they override any configuration done when the
720              agent was registered.
721
722              For SnmpInfo, see the user callback function handle_report.
723
724       async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) ->  {ok,  Re‐
725       qId} | {error, Reason}
726       async_get_bulk2(UserId,  TargetName, NonRep, MaxRep, Oids, SendOpts) ->
727       {ok, ReqId} | {error, Reason}
728
729              Types:
730
731                 UserId = term()
732                 TargetName = target_name()
733                 NonRep = integer()
734                 MaxRep = integer()
735                 Oids = [oid()]
736                 SendOpts = send_opts()
737                 send_opts() = [send_opt()]
738                 send_opt() = {context, string()} | {timeout, pos_integer()} |
739                 {extra,  term()}  |  {community,  community()}  | {sec_model,
740                 sec_model()}   |   {sec_name,   string()}    |    {sec_level,
741                 sec_level()} | {max_message_size, pos_integer()}
742                 ReqId = integer()
743                 Reason = term()
744
745              Asynchronous get-bulk-request (See RFC1905).
746
747              The  reply  will  be delivered to the user through a call to the
748              snmpm_user callback function handle_pdu.
749
750              The send option timeout specifies for how long  the  request  is
751              valid (after which the manager is free to delete it).
752
753              The  send option extra specifies an opaque data structure passed
754              on to the net-if process. The net-if process  included  in  this
755              application makes no use of this info, so the only use for it in
756              such a configuration (when using the built in net-if)  would  be
757              tracing.
758
759              Some  of  the  send  options  (community,  sec_model,  sec_name,
760              sec_level and max_message_size) are override options.  That  is,
761              for  this request, they override any configuration done when the
762              agent was registered.
763
764       cancel_async_request(UserId, ReqId) -> ok | {error, Reason}
765
766              Types:
767
768                 UserId = term()
769                 ReqId = term()
770                 Reason = term()
771
772              Cancel a previous asynchronous request.
773
774       log_to_txt(LogDir)
775       log_to_txt(LogDir, Block | Mibs)
776       log_to_txt(LogDir, Mibs, Block | OutFile) -> ok | {ok, Cnt}  |  {error,
777       Reason}
778       log_to_txt(LogDir,  Mibs, OutFile, Block | LogName) -> ok | {ok, Cnt} |
779       {error, Reason}
780       log_to_txt(LogDir, Mibs, OutFile, LogName, Block |  LogFile)  ->  ok  |
781       {ok, Cnt} | {error, Reason}
782       log_to_txt(LogDir,  Mibs,  OutFile, LogName, LogFile, Block | Start) ->
783       ok | {ok, Cnt} | {error, Reason}
784       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok
785       | {ok, Cnt} | {error, Reason}
786       log_to_txt(LogDir,  Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok
787       | {ok, Cnt} | {error, Reason}
788       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)
789       -> ok | {ok, Cnt} | {error, Reason}
790
791              Types:
792
793                 LogDir = string()
794                 Mibs = [MibName]
795                 MibName = string()
796                 Block = boolean()
797                 OutFile = string()
798                 LogName = string()
799                 LogFile = string()
800                 Start = Stop = null | calendar:datetime() | {local_time, cal‐
801                 endar:datetime()} | {universal_time, calendar:datetime()}
802                 Cnt = {NumOK, NumERR}
803                 NumOK = non_neg_integer()
804                 NumERR = pos_integer()
805                 Reason = disk_log_open_error() | file_open_error() | term()
806                 disk_log_open_error() = {LogName, term()}
807                 file_open_error() = {OutFile, term()}
808
809              Converts an Audit Trail Log to a readable text file. OutFile de‐
810              faults  to  "./snmpm_log.txt".  LogName defaults to "snmpm_log".
811              LogFile defaults to "snmpm.log".
812
813              The Block argument indicates if the log should be blocked during
814              conversion.  This  could  be  usefull when converting large logs
815              (when otherwise the log could wrap during conversion).  Defaults
816              to true.
817
818              See snmp:log_to_txt for more info.
819
820       log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
821       log_to_io(LogDir, Block | Mibs) -> ok | {ok, Cnt} | {error, Reason}
822       log_to_io(LogDir, Mibs) -> ok | {error, Reason}
823       log_to_io(LogDir,  Mibs,  Block  | LogName) -> ok | {ok, Cnt} | {error,
824       Reason}
825       log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {ok,  Cnt}  |
826       {error, Reason}
827       log_to_io(LogDir,  Mibs,  LogName, LogFile, Block | Start) -> ok | {ok,
828       Cnt} | {error, Reason}
829       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) ->  ok  |  {ok,
830       Cnt} | {error, Reason}
831       log_to_io(LogDir,  Mibs,  LogName,  LogFile,  Start, Stop) -> ok | {ok,
832       Cnt} | {error, Reason}
833       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) ->  ok  |
834       {ok, Cnt} | {error, Reason}
835
836              Types:
837
838                 LogDir = string()
839                 Mibs = [MibName]
840                 MibName = string()
841                 Block = boolean()
842                 LogName = string()
843                 LogFile = string()
844                 Start = Stop = null | calendar:datetime() | {local_time, cal‐
845                 endar:datetime()} | {universal_time, calendar:datetime()}
846                 Cnt = {NumOK, NumERR}
847                 NumOK = non_neg_integer()
848                 NumERR = pos_integer()
849                 Reason = disk_log_open_error() | file_open_error() | term()
850                 disk_log_open_error() = {LogName, term()}
851                 file_open_error() = {OutFile, term()}
852
853              Converts an Audit Trail Log to a readable format and  prints  it
854              on  stdio.  LogName defaults to "snmpm_log". LogFile defaults to
855              "snmpm.log".
856
857              The Block argument indicates if the log should be blocked during
858              conversion.  This  could  be  usefull when converting large logs
859              (when otherwise the log could wrap during conversion).  Defaults
860              to true.
861
862              See snmp:log_to_io for more info.
863
864       change_log_size(NewSize) -> ok | {error, Reason}
865
866              Types:
867
868                 NewSize = {MaxBytes, MaxFiles}
869                 MaxBytes = integer()
870                 MaxFiles = integer()
871                 Reason = term()
872
873              Changes  the  log  size  of the Audit Trail Log. The application
874              must be configured to use the audit trail log  function.  Please
875              refer  to  disk_log(3) in Kernel Reference Manual for a descrip‐
876              tion of how to change the log size.
877
878              The change is permanent, as long as the log is not deleted. That
879              means, the log size is remembered across reboots.
880
881       set_log_type(NewType) -> {ok, OldType} | {error, Reason}
882
883              Types:
884
885                 NewType = OldType = atl_type()
886                 Reason = term()
887
888              Changes the run-time Audit Trail log type.
889
890              Note that this has no effect on the application configuration as
891              defined by configuration files, so a node  restart  will  revert
892              the config to whatever is in those files.
893
894              This  function  is primarily useful in testing/debugging scenar‐
895              ios.
896
897       load_mib(Mib) -> ok | {error, Reason}
898
899              Types:
900
901                 Mib = MibName
902                 MibName = string()
903                 Reason = term()
904
905              Load a Mib into the manager. The MibName is the name of the Mib,
906              including the path to where the compiled mib is found. For exam‐
907              ple,
908
909                        Dir = code:priv_dir(my_app) ++ "/mibs/",
910                        snmpm:load_mib(Dir ++ "MY-MIB").
911
912
913       unload_mib(Mib) -> ok | {error, Reason}
914
915              Types:
916
917                 Mib = MibName
918                 MibName = string()
919                 Reason = term()
920
921              Unload a Mib from the manager. The MibName is the  name  of  the
922              Mib,  including the path to where the compiled mib is found. For
923              example,
924
925                        Dir = code:priv_dir(my_app) ++ "/mibs/",
926                        snmpm:unload_mib(Dir ++ "MY-MIB").
927
928
929       which_mibs() -> Mibs
930
931              Types:
932
933                 Mibs = [{MibName, MibFile}]
934                 MibName = atom()
935                 MibFile = string()
936
937              Get a list of all the mib's loaded into the manager.
938
939       name_to_oid(Name) -> {ok, Oids} | {error, Reason}
940
941              Types:
942
943                 Name = atom()
944                 Oids = [oid()]
945
946              Transform a alias-name to its oid.
947
948              Note that an alias-name is only unique within the mib,  so  when
949              loading several mib's into a manager, there might be several in‐
950              stances of the same aliasname.
951
952       oid_to_name(Oid) -> {ok, Name} | {error, Reason}
953
954              Types:
955
956                 Oid = oid()
957                 Name = atom()
958                 Reason = term()
959
960              Transform a oid to its aliasname.
961
962       oid_to_type(Oid) -> {ok, Type} | {error, Reason}
963
964              Types:
965
966                 Oid = oid()
967                 Type = atom()
968                 Reason = term()
969
970              Retreive the type (asn1 bertype) of an oid.
971
972       backup(BackupDir) -> ok | {error, Reason}
973
974              Types:
975
976                 BackupDir = string()
977
978              Backup persistent data handled by the manager.
979
980              BackupDir cannot be identical to DbDir.
981
982       info() -> [{Key, Value}]
983
984              Types:
985
986                 Key = atom()
987                 Value = term()
988
989              Returns a list (a dictionary) containing information  about  the
990              manager. Information includes statistics counters, miscellaneous
991              info about each process (e.g. memory allocation), and so on.
992
993       verbosity(Ref, Verbosity) -> void()
994
995              Types:
996
997                 Ref = server | config | net_if | note_store | all
998                 Verbosity = verbosity()
999                 verbosity() = silence | info | log | debug | trace
1000
1001              Sets verbosity for the designated process. For the  lowest  ver‐
1002              bosity  silence,  nothing  is printed. The higher the verbosity,
1003              the more is printed.
1004
1005       restart(Ref) -> void()
1006
1007              Types:
1008
1009                 Ref = net_if
1010
1011              Restart the indicated process (Ref). Note that its  not  without
1012              risk  to  restart  a  process,  and should therefor be used with
1013              care.
1014
1015       format_reason(Reason) -> string()
1016       format_reason(Prefix, Reason) -> string()
1017
1018              Types:
1019
1020                 Reason = term()
1021                 Prefix = integer() | string()
1022
1023              This utility function is used  to  create  a  formatted  (pretty
1024              printable) string of the error reason received from either:
1025
1026                * The  Reason returned value if any of the sync/async get/get-
1027                  next/set/get-bulk functions returns {error, Reason}
1028
1029                * The Reason parameter in the handle_error user callback func‐
1030                  tion.
1031
1032              Prefix should either be an indention string (e.g. a list of spa‐
1033              ces) or a positive integer (which will be used to create the in‐
1034              dention string of that length).
1035
1036
1037
1038Ericsson AB                       snmp 5.10.1                         snmpm(3)
Impressum