1snmpa(3) Erlang Module Definition snmpa(3)
2
6 snmpa - Interface Functions to the SNMP toolkit agent
7
9 The module snmpa contains interface functions to the SNMP agent.
10
12 oid() = [byte()]
13 atl_type() = read | write | read_write
14 notification_delivery_info() = #snmpa_notification_delivery_info{}
15 The oid() type is used to represent an ASN.1 OBJECT IDENTIFIER.
18 The record snmpa_notification_delivery_info contains the following
20 fields:
21 tag = term():
23 A user defined identity representing this notification send opera‐
24 tion.
25 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 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
36 add_agent_caps(SysORID, SysORDescr) -> SysORIndex
37 Types:
39 SysORID = oid()
41 SysORDescr = string()
42 SysORIndex = integer()
43 This function can be used to add an AGENT-CAPABILITY statement
45 to the sysORTable in the agent. The table is defined in the SN‐
46 MPv2-MIB.
47 del_agent_caps(SysORIndex) -> void()
49 Types:
51 SysORIndex = integer()
53 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 get_agent_caps() -> [[SysORIndex, SysORID, SysORDescr, SysORUpTime]]
59 Types:
61 SysORIndex = integer()
63 SysORId = oid()
64 SysORDescr = string()
65 SysORUpTime = integer()
66 Returns all AGENT-CAPABILITY statements in the sysORTable in the
68 agent. This table is defined in the SNMPv2-MIB.
69 get(Agent, Vars) -> Values | {error, Reason}
71 get(Agent, Vars, Context) -> Values | {error, Reason}
72 Types:
74 Agent = pid() | atom()
76 Vars = [oid()]
77 Context = string()
78 Values = [term()]
79 Reason = {atom(), oid()}
80 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 Note that the request specific parameters (such as current_re‐
87 quest_id) are not accessible for the instrumentation functions
88 if this function is used.
89 get_next(Agent, Vars) -> Values | {error, Reason}
91 get_next(Agent, Vars, Context) -> Values | {error, Reason}
92 Types:
94 Agent = pid() | atom()
96 Vars = [oid()]
97 Context = string()
98 Values = [{oid(), term()}]
99 Reason = {atom(), oid()}
100 Performs a GET-NEXT operation on the agent. All loaded MIB ob‐
102 jects are visible in this operation. The agent calls the corre‐
103 sponding instrumentation functions just as if it was a GET re‐
104 quest coming from a manager.
105 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 backup(BackupDir) -> ok | {error, Reason}
111 backup(Agent, BackupDir) -> ok | {error, Reason}
112 Types:
114 BackupDir = string()
116 Agent = pid() | atom()
117 Reason = backup_in_progress | term()
118 Backup persistent/permanent data handled by the agent (such as
120 local-db, mib-data and vacm).
121 Data stored by mnesia is not handled.
123 BackupDir cannot be identical to DbDir.
125 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 info() -> [{Key, Value}]
132 info(Agent) -> [{Key, Value}]
133 Types:
135 Agent = pid() | atom()
137 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 load_mib(Mib) -> ok | {error, Reason}
143 load_mib(Agent, Mib) -> ok | {error, Reason}
144 Types:
146 Agent = pid() | atom()
148 MibName = string()
149 Reason = already_loaded | term()
150 Load a single Mib into an agent. The MibName is the name of the
152 Mib, including the path to where the compiled mib is found. For
153 example:
154 Dir = code:priv_dir(my_app) ++ "/mibs/",
156 snmpa:load_mib(snmp_master_agent, Dir ++ "MY-MIB").
157 load_mibs(Mibs) -> ok | {error, Reason}
160 load_mibs(Mibs, Force) -> ok | {error, Reason}
161 load_mibs(Agent, Mibs) -> ok | {error, Reason}
162 load_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
163 Types:
165 Agent = pid() | atom()
167 Mibs = [MibName]
168 Force = boolean()
169 MibName = string()
170 Reason = {'load aborted at', MibName, InternalReason}
171 InternalReason = already_loaded | term()
172 Load Mibs into an agent. If the agent cannot load all MIBs (the
174 default value of the Force argument is false), it will indicate
175 where loading was aborted. The MibName is the name of the Mib,
176 including the path to where the compiled mib is found. For exam‐
177 ple,
178 Dir = code:priv_dir(my_app) ++ "/mibs/",
180 snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).
181 If Force = true then the agent will continue attempting to load
184 each mib even after failing to load a previous mib. Use with
185 care.
186 unload_mib(Mib) -> ok | {error, Reason}
188 unload_mib(Agent, Mib) -> ok | {error, Reason}
189 Types:
191 Agent = pid() | atom()
193 MibName = string()
194 Reason = not_loaded | term()
195 Unload a single Mib from an agent.
197 unload_mibs(Mibs) -> ok | {error, Reason}
199 unload_mibs(Mibs, Force) -> ok | {error, Reason}
200 unload_mibs(Agent, Mibs) -> ok | {error, Reason}
201 unload_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
202 Types:
204 Agent = pid() | atom()
206 Mibs = [MibName]
207 Force = boolean()
208 MibName = string()
209 Reason = {'unload aborted at', MibName, InternalReason}
210 InternalReason = not_loaded | term()
211 Unload Mibs from an agent. If it cannot unload all MIBs (the de‐
213 fault value of the Force argument is false), it will indicate
214 where unloading was aborted.
215 If Force = true then the agent will continue attempting to un‐
217 load each mib even after failing to unload a previous mib. Use
218 with care.
219 which_mibs() -> Mibs
221 which_mibs(Agent) -> Mibs
222 Types:
224 Agent = pid() | atom()
226 Mibs = [{MibName, MibFile}]
227 MibName = atom()
228 MibFile = string()
229 Retrieve the list of all the mibs loaded into this agent. De‐
231 fault is the master agent.
232 whereis_mib(MibName) -> {ok, MibFile} | {error, Reason}
234 whereis_mib(Agent, MibName) -> {ok, MibFile} | {error, Reason}
235 Types:
237 Agent = pid() | atom()
239 MibName = atom()
240 MibFile = string()
241 Reason = term()
242 Get the full path to the (compiled) mib-file.
244 current_request_id() -> {value, RequestId} | false
246 current_context() -> {value, Context} | false
247 current_community() -> {value, Community} | false
248 current_address() -> {value, Address} | false
249 Types:
251 RequestId = integer()
253 Context = string()
254 Community = string()
255 Address = term()
256 Get the request-id, context, community and address of the re‐
258 quest currently being processed by the agent.
259 Note that these functions is intended to be called by the in‐
261 strumentation functions and only if they are executed in the
262 context of the agent process (e.g. it does not work if called
263 from a spawned process).
264 enum_to_int(Name, Enum) -> {value, Int} | false
266 enum_to_int(Db, Name, Enum) -> {value, Int} | false
267 Types:
269 Db = term()
271 Name = atom()
272 Enum = atom()
273 Int = int()
274 Converts the symbolic value Enum to the corresponding integer of
276 the enumerated object or type Name in a MIB. The MIB must be
277 loaded.
278 false is returned if the object or type is not defined in any
280 loaded MIB, or if it does not define the symbolic value as enu‐
281 merated.
282 Db is a reference to the symbolic store database (retrieved by a
284 call to get_symbolic_store_db/0).
285 int_to_enum(Name, Int) -> {value, Enum} | false
287 int_to_enum(Db, Name, Int) -> {value, Enum} | false
288 Types:
290 Db = term()
292 Name = atom()
293 Int = int()
294 Enum = atom()
295 Converts the integer Int to the corresponding symbolic value of
297 the enumerated object or type Name in a MIB. The MIB must be
298 loaded.
299 false is returned if the object or type is not defined in any
301 loaded MIB, or if it does not define the symbolic value as enu‐
302 merated.
303 Db is a reference to the symbolic store database (retrieved by a
305 call to get_symbolic_store_db/0).
306 name_to_oid(Name) -> {value, oid()} | false
308 name_to_oid(Db, Name) -> {value, oid()} | false
309 Types:
311 Db = term()
313 Name = atom()
314 Looks up the OBJECT IDENTIFIER of a MIB object, given the sym‐
316 bolic name. Note, the OBJECT IDENTIFIER is given for the object,
317 not for an instance.
318 false is returned if the object is not defined in any loaded
320 MIB.
321 Db is a reference to the symbolic store database (retrieved by a
323 call to get_symbolic_store_db/0).
324 oid_to_name(OID) -> {value, Name} | false
326 oid_to_name(Db, OID) -> {value, Name} | false
327 Types:
329 Db = term()
331 OID = oid()
332 Name = atom()
333 Looks up the symbolic name of a MIB object, given OBJECT IDENTI‐
335 FIER.
336 false is returned if the object is not defined in any loaded
338 MIB.
339 Db is a reference to the symbolic store database (retrieved by a
341 call to get_symbolic_store_db/0).
342 which_aliasnames() -> Result
344 Types:
346 Result = [atom()]
348 Retrieve all alias-names known to the agent.
350 which_tables() -> Result
352 Types:
354 Result = [atom()]
356 Retrieve all tables known to the agent.
358 which_transports() -> Result
360 Types:
362 Result = [{TDomain, TAddress} | {TDomain, TAddress, Kind}]
364 TDomain = transportDomainUdpIpv4 | transportDomainUdpIpv6
365 TAddress = {IpAddr, IpPort}
366 IpAddr = inet:ip_address()
367 IpPort = pos_integer()
368 Kind = req_responder | trap_sender
369 Retrieve all configured transports.
371 which_variables() -> Result
373 Types:
375 Result = [atom()]
377 Retrieve all variables known to the agent.
379 which_notifications() -> Result
381 Types:
383 Result = [{Name, MibName, Info}]
385 Name = atom()
386 MibName = atom()
387 Info = term()
388 Retrieve all notifications (and traps) known to the agent.
390 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 Types:
409 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 Converts an Audit Trail Log to a readable text file. OutFile de‐
427 faults to "./snmpa_log.txt". LogName defaults to "snmpa_log".
428 LogFile defaults to "snmpa.log".
429 The Block option indicates if the log should be blocked during
431 conversion. This could be useful when converting large logs
432 (when otherwise the log could wrap during conversion). Defaults
433 to true.
434 See snmp:log_to_txt for more info.
436 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 Types:
453 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 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 The Block option indicates if the log should be blocked during
474 conversion. This could be useful when converting large logs
475 (when otherwise the log could wrap during conversion). Defaults
476 to true.
477 See snmp:log_to_io for more info.
479 change_log_size(NewSize) -> ok | {error, Reason}
481 Types:
483 NewSize = {MaxBytes, MaxFiles}
485 MaxBytes = integer()
486 MaxFiles = integer()
487 Reason = term()
488 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 The change is permanent, as long as the log is not deleted. That
495 means, the log size is remembered across reboots.
496 set_log_type(NewType) -> {ok, OldType} | {error, Reason}
498 set_log_type(Agent, NewType) -> {ok, OldType} | {error, Reason}
499 Types:
501 NewType = OldType = atl_type()
503 Agent = pid() | atom()
504 Reason = term()
505 Changes the run-time Audit Trail log type.
507 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 This function is primarily useful in testing/debugging scenar‐
513 ios.
514 mib_of(Oid) -> {ok, MibName} | {error, Reason}
516 mib_of(Agent, Oid) -> {ok, MibName} | {error, Reason}
517 Types:
519 Agent = pid() | atom()
521 Oid = oid()
522 MibName = atom()
523 Reason = term()
524 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 me_of(Oid) -> {ok, Me} | {error, Reason}
530 me_of(Agent, Oid) -> {ok, Me} | {error, Reason}
531 Types:
533 Agent = pid() | atom()
535 Oid = oid()
536 Me = #me{}
537 Reason = term()
538 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 invalidate_mibs_cache() -> void()
544 invalidate_mibs_cache(Agent) -> void()
545 Types:
547 Agent = pid() | atom()
549 Invalidate the mib server cache.
551 The entire contents of the cache will be deleted.
553 enable_mibs_cache() -> void()
555 enable_mibs_cache(Agent) -> void()
556 Types:
558 Agent = pid() | atom()
560 Enable the mib server cache.
562 disable_mibs_cache() -> void()
564 disable_mibs_cache(Agent) -> void()
565 Types:
567 Agent = pid() | atom()
569 Disable the mib server cache.
571 which_mibs_cache_size() -> void()
573 which_mibs_cache_size(Agent) -> void()
574 Types:
576 Agent = pid() | atom()
578 Retrieve the size of the mib server cache.
580 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 Types:
590 Agent = pid() | atom()
592 Age = integer() > 0
593 GcLimit = integer() > 0 | infinity
594 NumElementsGCed = integer() >= 0
595 Reason = term()
596 Perform mib server cache gc.
598 Manually performs a mib server cache gc. This can be done re‐
600 gardless of the value of the autogc option. The NumElementsGCed
601 value indicates how many elements where actually removed from
602 the cache.
603 enable_mibs_cache_autogc() -> void()
605 enable_mibs_cache_autogc(Agent) -> void()
606 Types:
608 Agent = pid() | atom()
610 Enable automatic gc of the mib server cache.
612 disable_mibs_cache_autogc() -> void()
614 disable_mibs_cache_autogc(Agent) -> void()
615 Types:
617 Agent = pid() | atom()
619 Disable automatic gc of the mib server cache.
621 update_mibs_cache_age(NewAge) -> ok | {error, Reason}
623 update_mibs_cache_age(Agent, NewAge) -> ok | {error, Reason}
624 Types:
626 Agent = pid() | atom()
628 NewAge = integer() > 0
629 Reason = term()
630 Change the mib server cache age property.
632 update_mibs_cache_gclimit(NewGcLimit) -> ok | {error, Reason}
634 update_mibs_cache_gclimit(Agent, NewGCLimit) -> ok | {error, Reason}
635 Types:
637 Agent = pid() | atom()
639 NewGcLimit = integer() > 0 | infinity
640 Reason = term()
641 Change the mib server cache gclimit property.
643 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 | {er‐
650 ror, Reason}
651 Types:
653 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 Registers a notification filter.
665 Mod is a module implementing the snmpa_notification_filter be‐
667 haviour.
668 Data will be passed on to the filter when calling the functions
670 of the behaviour.
671 unregister_notification_filter(Id) -> ok | {error, Reason}
673 unregister_notification_filter(Agent, Id) -> ok | {error, Reason}
674 Types:
676 Agent = pid() | atom()
678 Id = filter_id()
679 filter_id() = term()
680 Unregister a notification filter.
682 which_notification_filter() -> Filters
684 which_notification_filter(Agent) -> Filters
685 Types:
687 Agent = pid() | atom()
689 Filters = [filter_id()]
690 filter_id() = term()
691 List all notification filters in an agent.
693 set_request_limit(NewLimit) -> {ok, OldLimit} | {error, Reason}
695 set_request_limit(Agent, NewLimit) -> {ok, OldLimit} | {error, Reason}
696 Types:
698 NewLimit = OldLimit = infinity | integer() >= 0
700 Agent = pid() | atom()
701 Reason = term()
702 Changes the request limit.
704 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 This function is primarily useful in load regulation scenarios.
710 register_subagent(Agent, SubTreeOid, Subagent) -> ok | {error, Reason}
712 Types:
714 Agent = pid() | atom()
716 SubTreeOid = oid()
717 SubAgent = pid()
718 Registers a sub-agent under a sub-tree of another agent.
720 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 snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1),
726 snmp_agent:register_subagent(SA1,[1,2,3], SA2).
727 SA2 will not get requests starting with object identifier
730 [1,2,3] since SA1 does not.
731 unregister_subagent(Agent, SubagentOidOrPid) -> ok | {ok, SubAgentPid}
733 | {error, Reason}
734 Types:
736 Agent = pid() | atom()
738 SubTreeOidorPid = oid() | pid()
739 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 send_notification2(Agent, Notification, SendOpts) -> void()
744 Types:
746 Agent = pid() | atom()
748 Notification = atom()
749 SendOpts = [send_option()]
750 send_option() = {receiver, receiver()} | {name, no‐
751 tify_name()} | {context, context_name()} | {varbinds,
752 varbinds()} | {local_engine_id, string()} | {extra, ex‐
753 tra_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()} | {{process_oid(), vari‐
767 able()}, value()} | {column(), row_index(), value()} |
768 variable() = aliasname() | oid()
769 aliasname() = atom()
770 process_oid() = keep (default) | truncate
771 value() = term()
772 column() = atom()
773 row_index() = [int()]
774 extra_info() = term()
775 Send the notification Notification to the management targets de‐
777 fined for notify-name (name) in the snmpNotifyTable in SNMP-NO‐
778 TIFICATION-MIB from the specified context.
779 If no name is specified (or if it is ""), the notification is
781 sent to all management targets.
782 If no context is specified, the default context, "", is used.
784 The send option receiver specifies where information about de‐
786 livery of Inform-Requests should be sent. The agent sends In‐
787 form-Requests and waits for acknowledgments from the management
788 targets. The receiver can have three values:
789 * no_receiver - No information is delivered.
791 * notification_delivery_info() - The information is delivered
793 via a function call according to this data. See the DATA
794 TYPES section above for details.
795 * {tag(), tag_receiver()} - The information is delivered ei‐
797 ther via messages or via a function call according to the
798 value of tag_receiver().
799 Delivery is done differently depending on the value of
801 tag_receiver():
802 * pid() | registered_name() - The info will be delivered in
804 the following messages:
805 * {snmp_targets, tag(), Addresses}
807 This informs the user which target addresses the notifi‐
809 cation was sent to.
810 * {snmp_notification, tag(), {got_response, Address}}
812 This informs the user that this target address acknowl‐
814 edged the notification.
815 * {snmp_notification, tag(), {no_response, Address}}
817 This informs the user that this target address did not
819 acknowledge the notification.
820 The notification is sent as an Inform-Request to each tar‐
822 get address in Addresses and if there are no targets for
823 which an Inform-Request is sent, Addresses is the empty
824 list [].
825 The tag_receiver() will first be sent the snmp_targets
827 message, and then for each address in Addresses list, one
828 of the two snmp_notification messages.
829 * {Mod, Func, Args} - The info will be delivered via the
831 function call:
832 Mod:Func([Msg | Args])
834 where Msg has the same content and purpose as the messages
836 descrived above.
837 The 'process oid' "tag" that can be provided with the variable
839 name / oids is intended to be used for oid post processing. The
840 value 'keep', which is the default, leaves the oid as is. The
841 value 'truncate', will cause the oid to be "truncated". That is,
842 any trailing ".0" will be removed.
843 Note:
845 There is a way to exclude a varbind from the notification. In
846 the normal varbinds list, providing the special value '$ignore-
847 oid' (instead of a normal value) will exclude this varbind from
848 the notification.
849 A define for this has been added to the snmp_types.hrl include
851 file, NOTIFICATION_IGNORE_VB_VALUE.
852 Note:
855 The extra info is not normally interpreted by the agent, instead
856 it is passed through to the net-if process. It is up to the im‐
857 plementor of that process to make use of this data.
858 The version of net-if provided by this application makes no use
860 of this data, with one exception: Any tuple containing the atom
861 snmpa_default_notification_extra_info may be used by the agent
862 and is therefore reserved.
863 See the net-if incoming messages for sending a trap and noti‐
865 fication for more info.
866 send_notification(Agent, Notification, Receiver)
869 send_notification(Agent, Notification, Receiver, Varbinds)
870 send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)
871 send_notification(Agent, Notification, Receiver, NotifyName, Con‐
872 textName, Varbinds) -> void()
873 send_notification(Agent, Notification, Receiver, NotifyName, Con‐
874 textName, Varbinds, LocalEngineID) -> void()
875 Types:
877 Agent = pid() | atom()
879 Notification = atom()
880 Receiver = no_receiver | {Tag, Recv} | notification_deliv‐
881 ery_info()
882 Tag = term()
883 Recv = receiver()
884 receiver() = pid() | atom() | {Mod, Func, Args}
885 Mod = atom()
886 Func = atom()
887 Args = list()
888 NotifyName = string()
889 ContextName = string()
890 Varbinds = varbinds()
891 varbinds() = [varbind()]
892 varbind() = {Variable, Value} | {Column, RowIndex, Value} |
893 {OID, Value}
894 Variable = atom()
895 Column = atom()
896 OID = oid()
897 Value = term()
898 RowIndex = [int()]
899 LocalEngineID = string()
900 Sends the notification Notification to the management targets
902 defined for NotifyName in the snmpNotifyTable in SNMP-NOTIFICA‐
903 TION-MIB from the specified context.
904 If no NotifyName is specified (or if it is ""), the notification
906 is sent to all management targets (Addresses below).
907 If no ContextName is specified, the default "" context is used.
909 The parameter Receiver specifies where information about deliv‐
911 ery of Inform-Requests should be sent. The agent sends Inform-
912 Requests and waits for acknowledgments from the managers. Re‐
913 ceiver can have three values:
914 * no_receiver - No information is delivered.
916 * notification_delivery_info() - The information is delivered
918 via a function call according to this data. See the DATA
919 TYPES section above for details.
920 * {Tag, Recv} - The information is delivered either via mes‐
922 sages or via a function call according to the value of Recv.
923 If Receiver has the value {Tag, Recv}, the delivery is done ac‐
925 cording to Recv:
926 * pid() | atom() - The info will be delivered in the following
928 messages:
929 * {snmp_targets, Tag, Addresses}
931 This inform the user which target addresses the notifica‐
933 tion was sent to.
934 * {snmp_notification, Tag, {got_response, Address}}
936 This informs the user that this target address acknowl‐
938 edged the notification.
939 * {snmp_notification, Tag, {no_response, Address}}
941 This informs the user that this target address did not ac‐
943 knowledge notification.
944 The notification is sent as an Inform-Request to each target
946 address in Addresses and if there are no targets for which
947 an Inform-Request is sent, Addresses is the empty list [].
948 The receiver will first be sent the snmp_targets message,
950 and then for each address in Addresses list, one of the two
951 snmp_notification messages.
952 * {Mod, Func, Args} - The info will be delivered via the func‐
954 tion call:
955 Mod:Func([Msg | Args])
957 where Msg has the same content and purpose as the messages
959 descrived above.
960 Address is a management target address and Addresses is a list
962 of management target addresses. They are defined as followes:
963 Addresses = [address()]
965 Address = address()
966 address() = v1_address() | v3_address()
967 v1_address() = {TDomain, TAddress}
968 v3_address() = {{TDomain, TAddress}, V3MsgData}
969 TDomain = tdoamin()
970 TAddress = taddress()
971 tdomain() = The oid of snmpUDPDomain
972 This is the only supported transport domain.
973 taddress() = [A1, A2, A3, A4, P1, P3]
974 The 4 first bytes makes up the IP-address and the last 2,
975 the UDP-port number.
976 V3MsgData = v3_msg_data()
977 v3_msg_data() = term()
978 If Receiver is a notification_delivery_info() record, then the
981 information about the notification delivery will be delivered to
982 the receiver via the callback functions defined by the snmpa_no‐
983 tification_delivery_info_receiver behaviour according to the
984 content of the notification_delivery_info() record.
985 The optional argument Varbinds defines values for the objects in
987 the notification. If no value is given for an object, the Agent
988 performs a get-operation to retrieve the value.
989 Varbinds is a list of Varbind, where each Varbind is one of:
991 * {Variable, Value}, where Variable is the symbolic name of a
993 scalar variable referred to in the notification specifica‐
994 tion.
995 * {Column, RowIndex, Value}, where Column is the symbolic name
997 of a column variable. RowIndex is a list of indices for the
998 specified element. If this is the case, the OBJECT IDENTI‐
999 FIER sent in the notification is the RowIndex appended to
1000 the OBJECT IDENTIFIER for the table column. This is the OB‐
1001 JECT IDENTIFIER which specifies the element.
1002 * {OID, Value}, where OID is the OBJECT IDENTIFIER for an in‐
1004 stance of an object, scalar variable, or column variable.
1005 For example, to specify that sysLocation should have the value
1007 "upstairs" in the notification, we could use one of:
1008 * {sysLocation, "upstairs"} or
1010 * {[1,3,6,1,2,1,1,6,0], "upstairs"} or
1012 * {?sysLocation_instance, "upstairs"} (provided that the gen‐
1014 erated .hrl file is included)
1015 If a variable in the notification is a table element, the
1017 RowIndex for the element must be given in the Varbinds list. In
1018 this case, the OBJECT IDENTIFIER sent in the notification is the
1019 OBJECT IDENTIFIER that identifies this element. This OBJECT
1020 IDENTIFIER could be used in a get operation later.
1021 This function is asynchronous, and does not return any informa‐
1023 tion. If an error occurs, user_err/2 of the error report module
1024 is called and the notification is discarded.
1025 Note:
1027 Note that the use of the LocalEngineID argument is only intended
1028 for special cases, if the agent is to "emulate" multiple En‐
1029 gineIDs! By default, the agent uses the value of SnmpEngineID
1030 (see SNMP-FRAMEWORK-MIB).
1031 ExtraInfo is not normally used in any way by the agent. It is
1034 intended to be passed along to the net-if process, which is a
1035 component that a user can implement themself. The users own net-
1036 if may then make use of ExtraInfo. The net-if provided with this
1037 application does not process ExtraInfo.
1038 There is one exception. Any tuple containing the atom snmpa_de‐
1040 fault_notification_extra_info will, in this context, be consid‐
1041 ered belonging to this application, and may be processed by the
1042 agent.
1043 discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error,
1045 Reason}
1046 discovery(TargetName, Notification, Varbinds) -> {ok, ManagerEngineID}
1047 | {error, Reason}
1048 discovery(TargetName, Notification, DiscoHandler) -> {ok, Man‐
1049 agerEngineID} | {error, Reason}
1050 discovery(TargetName, Notification, ContextName, Varbinds) -> {ok, Man‐
1051 agerEngineID} | {error, Reason}
1052 discovery(TargetName, Notification, Varbinds, DiscoHandler) -> {ok,
1053 ManagerEngineID} | {error, Reason}
1054 discovery(TargetName, Notification, ContextName, Varbinds, DiscoHan‐
1055 dler) -> {ok, ManagerEngineID} | {error, Reason}
1056 discovery(TargetName, Notification, ContextName, Varbinds, DiscoHan‐
1057 dler, ExtraInfo) -> {ok, ManagerEngineID} | {error, Reason}
1058 Types:
1060 TargetName = string()
1062 Notification = atom()
1063 ContextName = string() (defaults to "")
1064 Varbinds = varbinds()
1065 varbinds() = [varbind()]
1066 DiscoHandler = snmpa_discovery_handler()
1067 ExtraInfo = term()
1068 snmpa_discovery_handler() = Module implementing the sn‐
1069 mpa_discovery_handler behaviour
1070 ManagerEngineID = string()
1071 varbind() = {Variable, Value} | {Column, RowIndex, Value} |
1072 {OID, Value}
1073 Variable = atom()
1074 Column = atom()
1075 OID = oid()
1076 Value = term()
1077 RowIndex = [int()]
1078 Reason = term()
1079 Initiate the discovery process with the manager identified by
1081 TargetName using the notification Notification.
1082 This function is synchronous, which means that it will return
1084 when the discovery process has been completed or failed.
1085 The DiscoHandler module is used during the discovery process.
1087 See discovery handler for more info.
1088 The ExtraInfo argument is passed on to the callback functions of
1090 the DiscoHandler.
1091 Note:
1093 If we are not at security-level noAuthNoPriv, this could be com‐
1094 plicated, since the agent will then continue with stage 2, be‐
1095 fore which the usm-related updates must be done.
1096 Note:
1099 The default discovery handler will require additional actions by
1100 the caller and the discovery will not work if the security-level
1101 is higher then noAuthNoPriv.
1102 convert_config(OldConfig) -> AgentConfig
1105 Types:
1107 OldConfig = list()
1109 AgentConfig = list()
1110 This off-line utility function can be used to convert the old
1112 snmp application config (pre snmp-4.0) to the new snmp agent
1113 config (as of snmp-4.0).
1114 For information about the old config (OldConfig) see the OTP R9C
1116 documentation.
1117 For information about the current agent config (AgentConfig),
1119 see the Configuring the application chapter of the SNMP user's
1120 guide.
1121 restart_worker() -> void()
1123 restart_worker(Agent) -> void()
1124 Types:
1126 Agent = pid() | atom()
1128 Restart the worker process of a multi-threaded agent.
1130 This is a utility function, that can be useful when e.g. debug‐
1132 ging instrumentation functions.
1133 restart_set_worker() -> void()
1135 restart_set_worker(Agent) -> void()
1136 Types:
1138 Agent = pid() | atom()
1140 Restart the set worker process of a multi-threaded agent.
1142 This is a utility function, that can be useful when e.g. debug‐
1144 ging instrumentation functions.
1145 print_mib_info() -> void()
1147 Prints the content of all the (snmp) tables and variables for
1149 all mibs handled by the snmp agent.
1150 print_mib_tables() -> void()
1152 Prints the content of all the (snmp) tables for all mibs handled
1154 by the snmp agent.
1155 print_mib_variables() -> void()
1157 Prints the content of all the (snmp) variables for all mibs han‐
1159 dled by the snmp agent.
1160 verbosity(Ref,Verbosity) -> void()
1162 Types:
1164 Ref = pid() | sub_agents | master_agent | net_if | mib_server
1166 | symbolic_store | note_store | local_db
1167 Verbosity = verbosity() | {subagents, verbosity()}
1168 verbosity() = silence | info | log | debug | trace
1169 Sets verbosity for the designated process. For the lowest ver‐
1171 bosity silence, nothing is printed. The higher the verbosity,
1172 the more is printed.
1173
1175 calendar(3), erlc(1)
1176Ericsson AB snmp 5.13.5 snmpa(3)