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

NAME

6       snmpa - Interface Functions to the SNMP toolkit agent
7

DESCRIPTION

9       The module snmpa contains interface functions to the SNMP agent.
10

DATA TYPES

12       oid() = [byte()]
13       atl_type() = read | write | read_write
14       notification_delivery_info() = #snmpa_notification_delivery_info{}
15
16
17       The oid() type is used to represent an ASN.1 OBJECT IDENTIFIER.
18
19       The  record  snmpa_notification_delivery_info  contains  the  following
20       fields:
21
22         tag = term():
23           A user defined identity representing this notification send  opera‐
24           tion.
25
26         mod = module():
27           A module implementing the snmpa_notification_delivery_info_receiver
28           behaviour. The info functions of this module will be called at var‐
29           ious stages of delivery.
30
31         extra = term():
32           This  is  any  extra  info the user wants to have supplied when the
33           functions in the callback module is called.
34

EXPORTS

36       add_agent_caps(SysORID, SysORDescr) -> SysORIndex
37
38              Types:
39
40                 SysORID = oid()
41                 SysORDescr = string()
42                 SysORIndex = integer()
43
44              This function can be used to add an  AGENT-CAPABILITY  statement
45              to  the  sysORTable  in  the  agent. The table is defined in the
46              SNMPv2-MIB.
47
48       del_agent_caps(SysORIndex) -> void()
49
50              Types:
51
52                 SysORIndex = integer()
53
54              This function can be used to delete an  AGENT-CAPABILITY  state‐
55              ment  to  the  sysORTable in the agent. This table is defined in
56              the SNMPv2-MIB.
57
58       get_agent_caps() -> [[SysORIndex, SysORID, SysORDescr, SysORUpTime]]
59
60              Types:
61
62                 SysORIndex = integer()
63                 SysORId = oid()
64                 SysORDescr = string()
65                 SysORUpTime = integer()
66
67              Returns all AGENT-CAPABILITY statements in the sysORTable in the
68              agent. This table is defined in the SNMPv2-MIB.
69
70       get(Agent, Vars) -> Values | {error, Reason}
71       get(Agent, Vars, Context) -> Values | {error, Reason}
72
73              Types:
74
75                 Agent = pid() | atom()
76                 Vars = [oid()]
77                 Context = string()
78                 Values = [term()]
79                 Reason = {atom(), oid()}
80
81              Performs  a  GET  operation on the agent. All loaded MIB objects
82              are visible in this operation. The agent calls the corresponding
83              instrumentation functions just as if it was a GET request coming
84              from a manager.
85
86              Note  that  the  request  specific  parameters  (such  as   cur‐
87              rent_request_id)  are  not  accessible  for  the instrumentation
88              functions if this function is used.
89
90       get_next(Agent, Vars) -> Values | {error, Reason}
91       get_next(Agent, Vars, Context) -> Values | {error, Reason}
92
93              Types:
94
95                 Agent = pid() | atom()
96                 Vars = [oid()]
97                 Context = string()
98                 Values = [{oid(), term()}]
99                 Reason = {atom(), oid()}
100
101              Performs a GET-NEXT operation  on  the  agent.  All  loaded  MIB
102              objects  are visible in this operation. The agent calls the cor‐
103              responding instrumentation functions just as if  it  was  a  GET
104              request coming from a manager.
105
106              Note  that  the  request specific parameters (such as snmpa:cur‐
107              rent_request_id/0 are not  accessible  for  the  instrumentation
108              functions if this function is used.
109
110       backup(BackupDir) -> ok | {error, Reason}
111       backup(Agent, BackupDir) -> ok | {error, Reason}
112
113              Types:
114
115                 BackupDir = string()
116                 Agent = pid() | atom()
117                 Reason = backup_in_progress | term()
118
119              Backup  persistent/permanent  data handled by the agent (such as
120              local-db, mib-data and vacm).
121
122              Data stored by mnesia is not handled.
123
124              BackupDir cannot be identical to DbDir.
125
126              Simultaneous backup calls are not allowed. That is, two  differ‐
127              ent processes cannot simultaneously successfully call this func‐
128              tion. One of them will be first, and succeed.  The  second  will
129              fail with the error reason backup_in_progress.
130
131       info() -> [{Key, Value}]
132       info(Agent) -> [{Key, Value}]
133
134              Types:
135
136                 Agent = pid() | atom()
137
138              Returns  a  list (a dictionary) containing information about the
139              agent. Information includes loaded MIBs, registered  sub-agents,
140              some information about the memory allocation.
141
142              As  of  version  4.4 the format of the info has been changed. To
143              convert the info to the old  format,  call  the  old_info_format
144              function.
145
146       old_info_format(NewInfo) -> OldInfo
147
148              Types:
149
150                 OldInfo = NewInfo = [{Key, Value}]
151
152              As  of version 4.4 the format of the info has been changed. This
153              function is used to convert to the old (pre-4.4) info format.
154
155       load_mib(Mib) -> ok | {error, Reason}
156       load_mib(Agent, Mib) -> ok | {error, Reason}
157
158              Types:
159
160                 Agent = pid() | atom()
161                 MibName = string()
162                 Reason = already_loaded | term()
163
164              Load a single Mib into an agent. The MibName is the name of  the
165              Mib,  including the path to where the compiled mib is found. For
166              example:
167
168                        Dir = code:priv_dir(my_app) ++ "/mibs/",
169                        snmpa:load_mib(snmp_master_agent, Dir ++ "MY-MIB").
170
171
172       load_mibs(Mibs) -> ok | {error, Reason}
173       load_mibs(Mibs, Force) -> ok | {error, Reason}
174       load_mibs(Agent, Mibs) -> ok | {error, Reason}
175       load_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
176
177              Types:
178
179                 Agent = pid() | atom()
180                 Mibs = [MibName]
181                 Force = boolean()
182                 MibName = string()
183                 Reason = {'load aborted at', MibName, InternalReason}
184                 InternalReason = already_loaded | term()
185
186              Load Mibs into an agent. If the agent cannot load all MIBs  (the
187              default  value of the Force argument is false), it will indicate
188              where loading was aborted. The MibName is the name of  the  Mib,
189              including the path to where the compiled mib is found. For exam‐
190              ple,
191
192                        Dir = code:priv_dir(my_app) ++ "/mibs/",
193                        snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).
194
195
196              If Force = true then the agent will continue attempting to  load
197              each  mib  even  after  failing to load a previous mib. Use with
198              care.
199
200       unload_mib(Mib) -> ok | {error, Reason}
201       unload_mib(Agent, Mib) -> ok | {error, Reason}
202
203              Types:
204
205                 Agent = pid() | atom()
206                 MibName = string()
207                 Reason = not_loaded | term()
208
209              Unload a single Mib from an agent.
210
211       unload_mibs(Mibs) -> ok | {error, Reason}
212       unload_mibs(Mibs, Force) -> ok | {error, Reason}
213       unload_mibs(Agent, Mibs) -> ok | {error, Reason}
214       unload_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
215
216              Types:
217
218                 Agent = pid() | atom()
219                 Mibs = [MibName]
220                 Force = boolean()
221                 MibName = string()
222                 Reason = {'unload aborted at', MibName, InternalReason}
223                 InternalReason = not_loaded | term()
224
225              Unload Mibs from an agent. If it cannot  unload  all  MIBs  (the
226              default  value of the Force argument is false), it will indicate
227              where unloading was aborted.
228
229              If Force = true then  the  agent  will  continue  attempting  to
230              unload each mib even after failing to unload a previous mib. Use
231              with care.
232
233       which_mibs() -> Mibs
234       which_mibs(Agent) -> Mibs
235
236              Types:
237
238                 Agent = pid() | atom()
239                 Mibs = [{MibName, MibFile}]
240                 MibName = atom()
241                 MibFile = string()
242
243              Retrieve the list of  all  the  mibs  loaded  into  this  agent.
244              Default is the master agent.
245
246       whereis_mib(MibName) -> {ok, MibFile} | {error, Reason}
247       whereis_mib(Agent, MibName) -> {ok, MibFile} | {error, Reason}
248
249              Types:
250
251                 Agent = pid() | atom()
252                 MibName = atom()
253                 MibFile = string()
254                 Reason = term()
255
256              Get the full path to the (compiled) mib-file.
257
258       current_request_id() -> {value, RequestId} | false
259       current_context() -> {value, Context} | false
260       current_community() -> {value, Community} | false
261       current_address() -> {value, Address} | false
262
263              Types:
264
265                 RequestId = integer()
266                 Context = string()
267                 Community = string()
268                 Address = term()
269
270              Get  the  request-id,  context,  community  and  address  of the
271              request currently being processed by the agent.
272
273              Note that these functions  is  intended  to  be  called  by  the
274              instrumentation  functions  and only if they are executed in the
275              context of the agent process (e.g. it does not  work  if  called
276              from a spawned process).
277
278       enum_to_int(Name, Enum) -> {value, Int} | false
279       enum_to_int(Db, Name, Enum) -> {value, Int} | false
280
281              Types:
282
283                 Db = term()
284                 Name = atom()
285                 Enum = atom()
286                 Int = int()
287
288              Converts the symbolic value Enum to the corresponding integer of
289              the enumerated object or type Name in a MIB.  The  MIB  must  be
290              loaded.
291
292              false  is  returned  if the object or type is not defined in any
293              loaded MIB, or if it does not define the symbolic value as  enu‐
294              merated.
295
296              Db is a reference to the symbolic store database (retrieved by a
297              call to get_symbolic_store_db/0).
298
299       int_to_enum(Name, Int) -> {value, Enum} | false
300       int_to_enum(Db, Name, Int) -> {value, Enum} | false
301
302              Types:
303
304                 Db = term()
305                 Name = atom()
306                 Int = int()
307                 Enum = atom()
308
309              Converts the integer Int to the corresponding symbolic value  of
310              the  enumerated  object  or  type Name in a MIB. The MIB must be
311              loaded.
312
313              false is returned if the object or type is not  defined  in  any
314              loaded  MIB, or if it does not define the symbolic value as enu‐
315              merated.
316
317              Db is a reference to the symbolic store database (retrieved by a
318              call to get_symbolic_store_db/0).
319
320       name_to_oid(Name) -> {value, oid()} | false
321       name_to_oid(Db, Name) -> {value, oid()} | false
322
323              Types:
324
325                 Db = term()
326                 Name = atom()
327
328              Looks  up  the OBJECT IDENTIFIER of a MIB object, given the sym‐
329              bolic name. Note, the OBJECT IDENTIFIER is given for the object,
330              not for an instance.
331
332              false  is  returned  if  the object is not defined in any loaded
333              MIB.
334
335              Db is a reference to the symbolic store database (retrieved by a
336              call to get_symbolic_store_db/0).
337
338       oid_to_name(OID) -> {value, Name} | false
339       oid_to_name(Db, OID) -> {value, Name} | false
340
341              Types:
342
343                 Db = term()
344                 OID = oid()
345                 Name = atom()
346
347              Looks up the symbolic name of a MIB object, given OBJECT IDENTI‐
348              FIER.
349
350              false is returned if the object is not  defined  in  any  loaded
351              MIB.
352
353              Db is a reference to the symbolic store database (retrieved by a
354              call to get_symbolic_store_db/0).
355
356       which_aliasnames() -> Result
357
358              Types:
359
360                 Result = [atom()]
361
362              Retrieve all alias-names known to the agent.
363
364       which_tables() -> Result
365
366              Types:
367
368                 Result = [atom()]
369
370              Retrieve all tables known to the agent.
371
372       which_variables() -> Result
373
374              Types:
375
376                 Result = [atom()]
377
378              Retrieve all variables known to the agent.
379
380       which_notifications() -> Result
381
382              Types:
383
384                 Result = [{Name, MibName, Info}]
385                 Name = atom()
386                 MibName = atom()
387                 Info = term()
388
389              Retrieve all notifications (and traps) known to the agent.
390
391       log_to_txt(LogDir)
392       log_to_txt(LogDir, Block | Mibs)
393       log_to_txt(LogDir, Mibs, Block | OutFile) -> ok | {ok, Cnt}  |  {error,
394       Reason}
395       log_to_txt(LogDir,  Mibs, OutFile, Block | LogName) -> ok | {ok, Cnt} |
396       {error, Reason}
397       log_to_txt(LogDir, Mibs, OutFile, LogName, Block |  LogFile)  ->  ok  |
398       {ok, Cnt} | {error, Reason}
399       log_to_txt(LogDir,  Mibs,  OutFile, LogName, LogFile, Block | Start) ->
400       ok | {ok, Cnt} | {error, Reason}
401       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok
402       | {ok, Cnt} | {error, Reason}
403       log_to_txt(LogDir,  Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok
404       | {ok, Cnt} | {error, Reason}
405       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)
406       -> ok | {ok, Cnt} | {error, Reason}
407
408              Types:
409
410                 LogDir = string()
411                 Mibs = [MibName]
412                 MibName = string()
413                 Block = boolean()
414                 OutFile = string()
415                 LogName = string()
416                 LogFile = string()
417                 Start = Stop = null | calendar:datetime() | {local_time, cal‐
418                 endar:datetime()} | {universal_time, calendar:datetime()}
419                 Cnt = {NumOK, NumERR}
420                 NumOK = non_neg_integer()
421                 NumERR = pos_integer()
422                 Reason = disk_log_open_error() | file_open_error() | term()
423                 disk_log_open_error() = {LogName, term()}
424                 file_open_error() = {OutFile, term()}
425
426              Converts an Audit Trail Log to a  readable  text  file.  OutFile
427              defaults  to "./snmpa_log.txt". LogName defaults to "snmpa_log".
428              LogFile defaults to "snmpa.log".
429
430              The Block option indicates if the log should be  blocked  during
431              conversion.  This  could  be  usefull when converting large logs
432              (when otherwise the log could wrap during conversion).  Defaults
433              to true.
434
435              See snmp:log_to_txt for more info.
436
437       log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
438       log_to_io(LogDir, Block | Mibs) -> ok | {ok, Cnt} | {error, Reason}
439       log_to_io(LogDir,  Mibs,  Block  | LogName) -> ok | {ok, Cnt} | {error,
440       Reason}
441       log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {ok,  Cnt}  |
442       {error, Reason}
443       log_to_io(LogDir,  Mibs,  LogName, LogFile, Block | Start) -> ok | {ok,
444       Cnt} | {error, Reason}
445       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) ->  ok  |  {ok,
446       Cnt} | {error, Reason}
447       log_to_io(LogDir,  Mibs,  LogName,  LogFile,  Start, Stop) -> ok | {ok,
448       Cnt} | {error, Reason}
449       log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) ->  ok  |
450       {ok, Cnt} | {error, Reason}
451
452              Types:
453
454                 LogDir = string()
455                 Mibs = [MibName]
456                 MibName = string()
457                 Block = boolean()
458                 LogName = string()
459                 LogFile = string()
460                 Start = Stop = null | calendar:datetime() | {local_time, cal‐
461                 endar:datetime()} | {universal_time, calendar:datetime()}
462                 Cnt = {NumOK, NumERR}
463                 NumOK = non_neg_integer()
464                 NumERR = pos_integer()
465                 Reason = disk_log_open_error() | file_open_error() | term()
466                 disk_log_open_error() = {LogName, term()}
467                 file_open_error() = {OutFile, term()}
468
469              Converts an Audit Trail Log to a readable format and  prints  it
470              on  stdio.  LogName defaults to "snmpa_log". LogFile defaults to
471              "snmpa.log".
472
473              The Block option indicates if the log should be  blocked  during
474              conversion.  This  could  be  usefull when converting large logs
475              (when otherwise the log could wrap during conversion).  Defaults
476              to true.
477
478              See snmp:log_to_io for more info.
479
480       change_log_size(NewSize) -> ok | {error, Reason}
481
482              Types:
483
484                 NewSize = {MaxBytes, MaxFiles}
485                 MaxBytes = integer()
486                 MaxFiles = integer()
487                 Reason = term()
488
489              Changes  the  log  size  of the Audit Trail Log. The application
490              must be configured to use the audit trail log  function.  Please
491              refer  to  disk_log(3) in Kernel Reference Manual for a descrip‐
492              tion of how to change the log size.
493
494              The change is permanent, as long as the log is not deleted. That
495              means, the log size is remembered across reboots.
496
497       set_log_type(NewType) -> {ok, OldType} | {error, Reason}
498       set_log_type(Agent, NewType) -> {ok, OldType} | {error, Reason}
499
500              Types:
501
502                 NewType = OldType = atl_type()
503                 Agent = pid() | atom()
504                 Reason = term()
505
506              Changes the run-time Audit Trail log type.
507
508              Note that this has no effect on the application configuration as
509              defined by configuration files, so a node  restart  will  revert
510              the config to whatever is in those files.
511
512              This  function  is primarily useful in testing/debugging scenar‐
513              ios.
514
515       mib_of(Oid) -> {ok, MibName} | {error, Reason}
516       mib_of(Agent, Oid) -> {ok, MibName} | {error, Reason}
517
518              Types:
519
520                 Agent = pid() | atom()
521                 Oid = oid()
522                 MibName = atom()
523                 Reason = term()
524
525              Finds the mib corresponding to the Oid. If it is a variable, the
526              Oid  must  be  <Oid for var>.0 and if it is a table, Oid must be
527              <table>.<entry>.<col>.<any>
528
529       me_of(Oid) -> {ok, Me} | {error, Reason}
530       me_of(Agent, Oid) -> {ok, Me} | {error, Reason}
531
532              Types:
533
534                 Agent = pid() | atom()
535                 Oid = oid()
536                 Me = #me{}
537                 Reason = term()
538
539              Finds the mib entry corresponding to the Oid. If it is  a  vari‐
540              able,  the Oid must be <Oid for var>.0 and if it is a table, Oid
541              must be <table>.<entry>.<col>.<any>
542
543       invalidate_mibs_cache() -> void()
544       invalidate_mibs_cache(Agent) -> void()
545
546              Types:
547
548                 Agent = pid() | atom()
549
550              Invalidate the mib server cache.
551
552              The entire contents of the cache will be deleted.
553
554       enable_mibs_cache() -> void()
555       enable_mibs_cache(Agent) -> void()
556
557              Types:
558
559                 Agent = pid() | atom()
560
561              Enable the mib server cache.
562
563       disable_mibs_cache() -> void()
564       disable_mibs_cache(Agent) -> void()
565
566              Types:
567
568                 Agent = pid() | atom()
569
570              Disable the mib server cache.
571
572       which_mibs_cache_size() -> void()
573       which_mibs_cache_size(Agent) -> void()
574
575              Types:
576
577                 Agent = pid() | atom()
578
579              Retreive the size of the mib server cache.
580
581       gc_mibs_cache() -> {ok, NumElementsGCed} | {error, Reason}
582       gc_mibs_cache(Agent) -> {ok, NumElementsGCed} | {error, Reason}
583       gc_mibs_cache(Age) -> {ok, NumElementsGCed} | {error, Reason}
584       gc_mibs_cache(Agent, Age) -> {ok, NumElementsGCed} | {error, Reason}
585       gc_mibs_cache(Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}
586       gc_mibs_cache(Agent, Age, GcLimit) -> {ok, NumElementsGCed}  |  {error,
587       Reason}
588
589              Types:
590
591                 Agent = pid() | atom()
592                 Age = integer() > 0
593                 GcLimit = integer() > 0 | infinity
594                 NumElementsGCed = integer() >= 0
595                 Reason = term()
596
597              Perform mib server cache gc.
598
599              Manually  performs  a  mib  server  cache  gc.  This can be done
600              regardless of the value of the autogc option.  The  NumElements‐
601              GCed  value  indicates  how many elements where actually removed
602              from the cache.
603
604       enable_mibs_cache_autogc() -> void()
605       enable_mibs_cache_autogc(Agent) -> void()
606
607              Types:
608
609                 Agent = pid() | atom()
610
611              Enable automatic gc of the mib server cache.
612
613       disable_mibs_cache_autogc() -> void()
614       disable_mibs_cache_autogc(Agent) -> void()
615
616              Types:
617
618                 Agent = pid() | atom()
619
620              Disable automatic gc of the mib server cache.
621
622       update_mibs_cache_age(NewAge) -> ok | {error, Reason}
623       update_mibs_cache_age(Agent, NewAge) -> ok | {error, Reason}
624
625              Types:
626
627                 Agent = pid() | atom()
628                 NewAge = integer() > 0
629                 Reason = term()
630
631              Change the mib server cache age property.
632
633       update_mibs_cache_gclimit(NewGcLimit) -> ok | {error, Reason}
634       update_mibs_cache_gclimit(Agent, NewGCLimit) -> ok | {error, Reason}
635
636              Types:
637
638                 Agent = pid() | atom()
639                 NewGcLimit = integer() > 0 | infinity
640                 Reason = term()
641
642              Change the mib server cache gclimit property.
643
644       register_notification_filter(Id, Mod, Data) -> ok | {error, Reason}
645       register_notification_filter(Agent, Id, Mod, Data) -> ok | {error, Rea‐
646       son}
647       register_notification_filter(Id, Mod, Data, Where) -> ok | {error, Rea‐
648       son}
649       register_notification_filter(Agent, Id,  Mod,  Data,  Where)  ->  ok  |
650       {error, Reason}
651
652              Types:
653
654                 Agent = pid() | atom()
655                 Id = filter_id()
656                 filter_id() = term()
657                 Mod = atom()
658                 Data = term()
659                 Where = filter_position()
660                 Reason = term()
661                 filter_position()  =  first  |  last  |  {insert_before, fil‐
662                 ter_id()} | {insert_after, filter_id()}
663
664              Registers a notification filter.
665
666              Mod is a module implementing the  snmpa_notification_filter  be‐
667              haviour.
668
669              Data  will be passed on to the filter when calling the functions
670              of the behaviour.
671
672       unregister_notification_filter(Id) -> ok | {error, Reason}
673       unregister_notification_filter(Agent, Id) -> ok | {error, Reason}
674
675              Types:
676
677                 Agent = pid() | atom()
678                 Id = filter_id()
679                 filter_id() = term()
680
681              Unregister a notification filter.
682
683       which_notification_filter() -> Filters
684       which_notification_filter(Agent) -> Filters
685
686              Types:
687
688                 Agent = pid() | atom()
689                 Filters = [filter_id()]
690                 filter_id() = term()
691
692              List all notification filters in an agent.
693
694       set_request_limit(NewLimit) -> {ok, OldLimit} | {error, Reason}
695       set_request_limit(Agent, NewLimit) -> {ok, OldLimit} | {error, Reason}
696
697              Types:
698
699                 NewLimit = OldLimit = infinity | integer() >= 0
700                 Agent = pid() | atom()
701                 Reason = term()
702
703              Changes the request limit.
704
705              Note that this has no effect on the application configuration as
706              defined  by  configuration  files, so a node restart will revert
707              the config to whatever is in those files.
708
709              This function is primarily useful in load regulation scenarios.
710
711       register_subagent(Agent, SubTreeOid, Subagent) -> ok | {error, Reason}
712
713              Types:
714
715                 Agent = pid() | atom()
716                 SubTreeOid = oid()
717                 SubAgent = pid()
718
719              Registers a sub-agent under a sub-tree of another agent.
720
721              It is easy to make mistakes when registering sub-agents and this
722              activity should be done carefully. For example, a strange behav‐
723              iour would result from the following configuration:
724
725              snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1),
726              snmp_agent:register_subagent(SA1,[1,2,3], SA2).
727
728
729              SA2 will  not  get  requests  starting  with  object  identifier
730              [1,2,3] since SA1 does not.
731
732       unregister_subagent(Agent,  SubagentOidOrPid) -> ok | {ok, SubAgentPid}
733       | {error, Reason}
734
735              Types:
736
737                 Agent = pid() | atom()
738                 SubTreeOidorPid = oid() | pid()
739
740              Unregister a sub-agent. If the second argument is  a  pid,  then
741              that sub-agent will be unregistered from all trees in Agent.
742
743       send_notification2(Agent, Notification, SendOpts) -> void()
744
745              Types:
746
747                 Agent = pid() | atom()
748                 Notification = atom()
749                 SendOpts = [send_option()]
750                 send_option()    =    {receiver,    receiver()}    |   {name,
751                 notify_name()}  |  {context,  context_name()}  |   {varbinds,
752                 varbinds()}   |   {local_engine_id,   string()}   |   {extra,
753                 extra_info()}
754                 receiver() = no_receiver | {tag(), tag_receiver()} |  notifi‐
755                 cation_delivery_info()
756                 tag() = term(()
757                 tag_receiver()  =  pid()  |  registered_name()  | {Mod, Func,
758                 Args}
759                 registered_name() = atom()
760                 Mod = atom()
761                 Func = atom()
762                 Args = list()
763                 notify_name() = string()
764                 context_name() = string()
765                 varbinds() = [varbind()]
766                 varbind() = {variable(), value()} |  {column(),  row_index(),
767                 value()} | {oid(), value()}
768                 variable() = atom()
769                 value() = term()
770                 column() = atom()
771                 row_index() = [int()]
772                 extra_info() = term()
773
774              Send  the  notification  Notification  to the management targets
775              defined for notify-name (name) in the snmpNotifyTable  in  SNMP-
776              NOTIFICATION-MIB from the specified context.
777
778              If  no  name  is specified (or if it is ""), the notification is
779              sent to all management targets.
780
781              If no context is specified, the default context, "", is used.
782
783              The send  option  receiver  specifies  where  information  about
784              delivery  of  Inform-Requests  should  be  sent. The agent sends
785              Inform-Requests and waits for acknowledgments from  the  manage‐
786              ment targets. The receiver can have three values:
787
788                * no_receiver - No information is delivered.
789
790                * notification_delivery_info()  - The information is delivered
791                  via a function call according to this  data.  See  the  DATA
792                  TYPES section above for details.
793
794                * {tag(),  tag_receiver()}  -  The  information  is  delivered
795                  either via messages or via a function call according to  the
796                  value of tag_receiver().
797
798                  Delivery  is  done  differently  depending  on  the value of
799                  tag_receiver():
800
801                  * pid() | registered_name() - The info will be delivered  in
802                    the following messages:
803
804                    * {snmp_targets, tag(), Addresses}
805
806                      This informs the user which target addresses the notifi‐
807                      cation was sent to.
808
809                    * {snmp_notification, tag(), {got_response, Address}}
810
811                      This informs the user that this target address  acknowl‐
812                      edged the notification.
813
814                    * {snmp_notification, tag(), {no_response, Address}}
815
816                      This  informs  the user that this target address did not
817                      acknowledge the notification.
818
819                    The notification is sent as an Inform-Request to each tar‐
820                    get  address  in Addresses and if there are no targets for
821                    which an Inform-Request is sent, Addresses  is  the  empty
822                    list [].
823
824                    The  tag_receiver()  will  first  be sent the snmp_targets
825                    message, and then for each address in Addresses list,  one
826                    of the two snmp_notification messages.
827
828                  * {Mod,  Func,  Args}  -  The info will be delivered via the
829                    function call:
830
831                    Mod:Func([Msg | Args])
832
833                    where Msg has the same content and purpose as the messages
834                    descrived above.
835
836          Note:
837              The extra info is not normally interpreted by the agent, instead
838              it is passed through to the net-if process.  It  is  up  to  the
839              implementor of that process to make use of this data.
840
841              The  version of net-if provided by this application makes no use
842              of this data, with one exception: Any tuple containing the  atom
843              snmpa_default_notification_extra_info  may  be used by the agent
844              and is therefor reserved.
845
846              See the net-if incomming messages for sending a  trap and  noti‐
847              fication for more info.
848
849
850       send_notification(Agent, Notification, Receiver)
851       send_notification(Agent, Notification, Receiver, Varbinds)
852       send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)
853       send_notification(Agent,   Notification,   Receiver,  NotifyName,  Con‐
854       textName, Varbinds) -> void()
855       send_notification(Agent,  Notification,  Receiver,   NotifyName,   Con‐
856       textName, Varbinds, LocalEngineID) -> void()
857
858              Types:
859
860                 Agent = pid() | atom()
861                 Notification = atom()
862                 Receiver  =  no_receiver  | {Tag, Recv} | notification_deliv‐
863                 ery_info()
864                 Tag = term()
865                 Recv = receiver()
866                 receiver() = pid() | atom() | {Mod, Func, Args}
867                 Mod = atom()
868                 Func = atom()
869                 Args = list()
870                 NotifyName = string()
871                 ContextName = string()
872                 Varbinds = varbinds()
873                 varbinds() = [varbind()]
874                 varbind() = {Variable, Value} | {Column, RowIndex,  Value}  |
875                 {OID, Value}
876                 Variable = atom()
877                 Column = atom()
878                 OID = oid()
879                 Value = term()
880                 RowIndex = [int()]
881                 LocalEngineID = string()
882
883              Sends  the  notification  Notification to the management targets
884              defined for NotifyName in the snmpNotifyTable in  SNMP-NOTIFICA‐
885              TION-MIB from the specified context.
886
887              If no NotifyName is specified (or if it is ""), the notification
888              is sent to all management targets (Addresses below).
889
890              If no ContextName is specified, the default "" context is used.
891
892              The parameter Receiver specifies where information about  deliv‐
893              ery  of  Inform-Requests should be sent. The agent sends Inform-
894              Requests  and  waits  for  acknowledgments  from  the  managers.
895              Receiver can have three values:
896
897                * no_receiver - No information is delivered.
898
899                * notification_delivery_info()  - The information is delivered
900                  via a function call according to this  data.  See  the  DATA
901                  TYPES section above for details.
902
903                * {Tag,  Recv}  - The information is delivered either via mes‐
904                  sages or via a function call according to the value of Recv.
905
906              If Receiver has the value {Tag,  Recv},  the  delivery  is  done
907              according to Recv:
908
909                * pid() | atom() - The info will be delivered in the following
910                  messages:
911
912                  * {snmp_targets, Tag, Addresses}
913
914                    This inform the user which target addresses the  notifica‐
915                    tion was sent to.
916
917                  * {snmp_notification, Tag, {got_response, Address}}
918
919                    This  informs  the  user that this target address acknowl‐
920                    edged the notification.
921
922                  * {snmp_notification, Tag, {no_response, Address}}
923
924                    This informs the user that this  target  address  did  not
925                    acknowledge notification.
926
927                  The notification is sent as an Inform-Request to each target
928                  address in Addresses and if there are no targets  for  which
929                  an Inform-Request is sent, Addresses is the empty list [].
930
931                  The  receiver  will  first be sent the snmp_targets message,
932                  and then for each address in Addresses list, one of the  two
933                  snmp_notification messages.
934
935                * {Mod, Func, Args} - The info will be delivered via the func‐
936                  tion call:
937
938                  Mod:Func([Msg | Args])
939
940                  where Msg has the same content and purpose as  the  messages
941                  descrived above.
942
943              Address  is  a management target address and Addresses is a list
944              of management target addresses. They are defined as followes:
945
946                      Addresses  = [address()]
947                      Address    = address()
948                      address()  = v1_address() | v3_address()
949                      v1_address() = {TDomain, TAddress}
950                      v3_address() = {{TDomain, TAddress}, V3MsgData}
951                      TDomain    = tdoamin()
952                      TAddress   = taddress()
953                      tdomain()  = The oid of snmpUDPDomain
954                                   This is the only supported transport domain.
955                      taddress() = [A1, A2, A3, A4, P1, P3]
956                                   The 4 first bytes makes up the IP-address and the last 2,
957                                   the UDP-port number.
958                      V3MsgData  = v3_msg_data()
959                      v3_msg_data() = term()
960
961
962              If Receiver is a notification_delivery_info() record,  then  the
963              information about the notification delivery will be delivered to
964              the  receiver  via  the  callback  functions  defined   by   the
965              snmpa_notification_delivery_info_receiver behaviour according to
966              the content of the notification_delivery_info() record.
967
968              The optional argument Varbinds defines values for the objects in
969              the  notification. If no value is given for an object, the Agent
970              performs a get-operation to retrieve the value.
971
972              Varbinds is a list of Varbind, where each Varbind is one of:
973
974                * {Variable, Value}, where Variable is the symbolic name of  a
975                  scalar  variable  referred to in the notification specifica‐
976                  tion.
977
978                * {Column, RowIndex, Value}, where Column is the symbolic name
979                  of  a column variable. RowIndex is a list of indices for the
980                  specified element. If this is the case, the  OBJECT  IDENTI‐
981                  FIER  sent  in  the notification is the RowIndex appended to
982                  the OBJECT IDENTIFIER for the  table  column.  This  is  the
983                  OBJECT IDENTIFIER which specifies the element.
984
985                * {OID,  Value},  where  OID  is  the OBJECT IDENTIFIER for an
986                  instance of an object, scalar variable, or column variable.
987
988              For example, to specify that sysLocation should have  the  value
989              "upstairs" in the notification, we could use one of:
990
991                * {sysLocation, "upstairs"} or
992
993                * {[1,3,6,1,2,1,1,6,0], "upstairs"} or
994
995                * {?sysLocation_instance,  "upstairs"} (provided that the gen‐
996                  erated .hrl file is included)
997
998              If a variable in  the  notification  is  a  table  element,  the
999              RowIndex  for the element must be given in the Varbinds list. In
1000              this case, the OBJECT IDENTIFIER sent in the notification is the
1001              OBJECT  IDENTIFIER  that  identifies  this  element. This OBJECT
1002              IDENTIFIER could be used in a get operation later.
1003
1004              This function is asynchronous, and does not return any  informa‐
1005              tion.  If an error occurs, user_err/2 of the error report module
1006              is called and the notification is discarded.
1007
1008          Note:
1009              Note that the use of the LocalEngineID argument is only intended
1010              for  special  cases,  if  the  agent  is  to  "emulate" multiple
1011              EngineIDs! By default, the agent uses the value of  SnmpEngineID
1012              (see SNMP-FRAMEWORK-MIB).
1013
1014
1015              ExtraInfo  is  not  normally used in any way by the agent. It is
1016              intended to be passed along to the net-if process,  which  is  a
1017              component that a user can implement themself. The users own net-
1018              if may then make use of ExtraInfo. The net-if provided with this
1019              application does not process ExtraInfo.
1020
1021              There   is   one   exception.  Any  tuple  containing  the  atom
1022              snmpa_default_notification_extra_info will, in this context,  be
1023              considered  belonging  to this application, and may be processed
1024              by the agent.
1025
1026       discovery(TargetName, Notification) -> {ok, ManagerEngineID} |  {error,
1027       Reason}
1028       discovery(TargetName,  Notification, Varbinds) -> {ok, ManagerEngineID}
1029       | {error, Reason}
1030       discovery(TargetName,  Notification,   DiscoHandler)   ->   {ok,   Man‐
1031       agerEngineID} | {error, Reason}
1032       discovery(TargetName, Notification, ContextName, Varbinds) -> {ok, Man‐
1033       agerEngineID} | {error, Reason}
1034       discovery(TargetName, Notification,  Varbinds,  DiscoHandler)  ->  {ok,
1035       ManagerEngineID} | {error, Reason}
1036       discovery(TargetName,  Notification,  ContextName,  Varbinds, DiscoHan‐
1037       dler) -> {ok, ManagerEngineID} | {error, Reason}
1038       discovery(TargetName, Notification,  ContextName,  Varbinds,  DiscoHan‐
1039       dler, ExtraInfo) -> {ok, ManagerEngineID} | {error, Reason}
1040
1041              Types:
1042
1043                 TargetName = string()
1044                 Notification = atom()
1045                 ContextName = string() (defaults to "")
1046                 Varbinds = varbinds()
1047                 varbinds() = [varbind()]
1048                 DiscoHandler = snmpa_discovery_handler()
1049                 ExtraInfo = term()
1050                 snmpa_discovery_handler()    =    Module   implementing   the
1051                 snmpa_discovery_handler behaviour
1052                 ManagerEngineID = string()
1053                 varbind() = {Variable, Value} | {Column, RowIndex,  Value}  |
1054                 {OID, Value}
1055                 Variable = atom()
1056                 Column = atom()
1057                 OID = oid()
1058                 Value = term()
1059                 RowIndex = [int()]
1060                 Reason = term()
1061
1062              Initiate  the  discovery  process with the manager identified by
1063              TargetName using the notification Notification.
1064
1065              This function is synchronous, which means that  it  will  return
1066              when the discovery process has been completed or failed.
1067
1068              The  DiscoHandler  module  is used during the discovery process.
1069              See discovery handler for more info.
1070
1071              The ExtraInfo argument is passed on to the callback functions of
1072              the DiscoHandler.
1073
1074          Note:
1075              If we are not at security-level noAuthNoPriv, this could be com‐
1076              plicated, since the agent  will  then  continue  with  stage  2,
1077              before which the usm-related updates must be done.
1078
1079
1080          Note:
1081              The default discovery handler will require additional actions by
1082              the caller and the discovery will not work if the security-level
1083              is higher then noAuthNoPriv.
1084
1085
1086       convert_config(OldConfig) -> AgentConfig
1087
1088              Types:
1089
1090                 OldConfig = list()
1091                 AgentConfig = list()
1092
1093              This  off-line  utility  function can be used to convert the old
1094              snmp application config (pre snmp-4.0) to  the  new  snmp  agent
1095              config (as of snmp-4.0).
1096
1097              For information about the old config (OldConfig) see the OTP R9C
1098              documentation.
1099
1100              For information about the current  agent  config  (AgentConfig),
1101              see  either the SNMP application part of the reference manual or
1102              the Configuring the  application  chapter  of  the  SNMP  user's
1103              guide.
1104
1105       restart_worker() -> void()
1106       restart_worker(Agent) -> void()
1107
1108              Types:
1109
1110                 Agent = pid() | atom()
1111
1112              Restart the worker process of a multi-threaded agent.
1113
1114              This  is a utility function, that can be useful when e.g. debug‐
1115              ging instrumentation functions.
1116
1117       restart_set_worker() -> void()
1118       restart_set_worker(Agent) -> void()
1119
1120              Types:
1121
1122                 Agent = pid() | atom()
1123
1124              Restart the set worker process of a multi-threaded agent.
1125
1126              This is a utility function, that can be useful when e.g.  debug‐
1127              ging instrumentation functions.
1128
1129       print_mib_info() -> void()
1130
1131              Prints  the  content  of all the (snmp) tables and variables for
1132              all mibs handled by the snmp agent.
1133
1134       print_mib_tables() -> void()
1135
1136              Prints the content of all the (snmp) tables for all mibs handled
1137              by the snmp agent.
1138
1139       print_mib_variables() -> void()
1140
1141              Prints the content of all the (snmp) variables for all mibs han‐
1142              dled by the snmp agent.
1143
1144       verbosity(Ref,Verbosity) -> void()
1145
1146              Types:
1147
1148                 Ref = pid() | sub_agents | master_agent | net_if | mib_server
1149                 | symbolic_store | note_store | local_db
1150                 Verbosity = verbosity() | {subagents, verbosity()}
1151                 verbosity() = silence | info | log | debug | trace
1152
1153              Sets  verbosity  for the designated process. For the lowest ver‐
1154              bosity silence, nothing is printed. The  higher  the  verbosity,
1155              the more is printed.
1156

SEE ALSO

1158       calendar(3), erlc(1)
1159
1160
1161
1162Ericsson AB                       snmp 5.2.12                         snmpa(3)
Impressum