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
46 SNMPv2-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 cur‐
87 rent_request_id) are not accessible for the instrumentation
88 functions 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
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 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 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 old_info_format(NewInfo) -> OldInfo
147 Types:
149 OldInfo = NewInfo = [{Key, Value}]
151 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 load_mib(Mib) -> ok | {error, Reason}
156 load_mib(Agent, Mib) -> ok | {error, Reason}
157 Types:
159 Agent = pid() | atom()
161 MibName = string()
162 Reason = already_loaded | term()
163 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 Dir = code:priv_dir(my_app) ++ "/mibs/",
169 snmpa:load_mib(snmp_master_agent, Dir ++ "MY-MIB").
170 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 Types:
178 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 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 Dir = code:priv_dir(my_app) ++ "/mibs/",
193 snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).
194 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 unload_mib(Mib) -> ok | {error, Reason}
201 unload_mib(Agent, Mib) -> ok | {error, Reason}
202 Types:
204 Agent = pid() | atom()
206 MibName = string()
207 Reason = not_loaded | term()
208 Unload a single Mib from an agent.
210 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 Types:
217 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 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 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 which_mibs() -> Mibs
234 which_mibs(Agent) -> Mibs
235 Types:
237 Agent = pid() | atom()
239 Mibs = [{MibName, MibFile}]
240 MibName = atom()
241 MibFile = string()
242 Retrieve the list of all the mibs loaded into this agent.
244 Default is the master agent.
245 whereis_mib(MibName) -> {ok, MibFile} | {error, Reason}
247 whereis_mib(Agent, MibName) -> {ok, MibFile} | {error, Reason}
248 Types:
250 Agent = pid() | atom()
252 MibName = atom()
253 MibFile = string()
254 Reason = term()
255 Get the full path to the (compiled) mib-file.
257 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 Types:
264 RequestId = integer()
266 Context = string()
267 Community = string()
268 Address = term()
269 Get the request-id, context, community and address of the
271 request currently being processed by the agent.
272 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 enum_to_int(Name, Enum) -> {value, Int} | false
279 enum_to_int(Db, Name, Enum) -> {value, Int} | false
280 Types:
282 Db = term()
284 Name = atom()
285 Enum = atom()
286 Int = int()
287 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 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 Db is a reference to the symbolic store database (retrieved by a
297 call to get_symbolic_store_db/0).
298 int_to_enum(Name, Int) -> {value, Enum} | false
300 int_to_enum(Db, Name, Int) -> {value, Enum} | false
301 Types:
303 Db = term()
305 Name = atom()
306 Int = int()
307 Enum = atom()
308 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 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 Db is a reference to the symbolic store database (retrieved by a
318 call to get_symbolic_store_db/0).
319 name_to_oid(Name) -> {value, oid()} | false
321 name_to_oid(Db, Name) -> {value, oid()} | false
322 Types:
324 Db = term()
326 Name = atom()
327 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 false is returned if the object is not defined in any loaded
333 MIB.
334 Db is a reference to the symbolic store database (retrieved by a
336 call to get_symbolic_store_db/0).
337 oid_to_name(OID) -> {value, Name} | false
339 oid_to_name(Db, OID) -> {value, Name} | false
340 Types:
342 Db = term()
344 OID = oid()
345 Name = atom()
346 Looks up the symbolic name of a MIB object, given OBJECT IDENTI‐
348 FIER.
349 false is returned if the object is not defined in any loaded
351 MIB.
352 Db is a reference to the symbolic store database (retrieved by a
354 call to get_symbolic_store_db/0).
355 which_aliasnames() -> Result
357 Types:
359 Result = [atom()]
361 Retrieve all alias-names known to the agent.
363 which_tables() -> Result
365 Types:
367 Result = [atom()]
369 Retrieve all tables known to the agent.
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 | {error, Reason}
394 log_to_txt(LogDir, Mibs, OutFile, Block | LogName) -> ok | {error, Rea‐
395 son}
396 log_to_txt(LogDir, Mibs, OutFile, LogName, Block | LogFile) -> ok |
397 {error, Reason}
398 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) ->
399 ok | {error, Reason}
400 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok
401 | {error, Reason}
402 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok
403 | {error, Reason}
404 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)
405 -> ok | {error, Reason}
406 Types:
408 LogDir = string()
410 Mibs = [MibName]
411 MibName = string()
412 Block = boolean()
413 OutFile = string()
414 LogName = string()
415 LogFile = string()
416 Start = Stop = null | calendar:datetime() | {local_time, cal‐
417 endar:datetime()} | {universal_time, calendar:datetime()}
418 Reason = disk_log_open_error() | file_open_error() | term()
419 disk_log_open_error() = {LogName, term()}
420 file_open_error() = {OutFile, term()}
421 Converts an Audit Trail Log to a readable text file. OutFile
423 defaults to "./snmpa_log.txt". LogName defaults to "snmpa_log".
424 LogFile defaults to "snmpa.log".
425 The Block option indicates if the log should be blocked during
427 conversion. This could be usefull when converting large logs
428 (when otherwise the log could wrap during conversion). Defaults
429 to true.
430 See snmp:log_to_txt for more info.
432 log_to_io(LogDir) -> ok | {error, Reason}
434 log_to_io(LogDir, Block | Mibs) -> ok | {error, Reason}
435 log_to_io(LogDir, Mibs, Block | LogName) -> ok | {error, Reason}
436 log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {error, Rea‐
437 son}
438 log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) -> ok |
439 {error, Reason}
440 log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {error,
441 Reason}
442 log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {error,
443 Reason}
444 log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok |
445 {error, Reason}
446 Types:
448 LogDir = string()
450 Mibs = [MibName]
451 MibName = string()
452 Block = boolean()
453 LogName = string()
454 LogFile = string()
455 Start = Stop = null | calendar:datetime() | {local_time, cal‐
456 endar:datetime()} | {universal_time, calendar:datetime()}
457 Reason = disk_log_open_error() | file_open_error() | term()
458 disk_log_open_error() = {LogName, term()}
459 file_open_error() = {OutFile, term()}
460 Converts an Audit Trail Log to a readable format and prints it
462 on stdio. LogName defaults to "snmpa_log". LogFile defaults to
463 "snmpa.log".
464 The Block option indicates if the log should be blocked during
466 conversion. This could be usefull when converting large logs
467 (when otherwise the log could wrap during conversion). Defaults
468 to true.
469 See snmp:log_to_io for more info.
471 change_log_size(NewSize) -> ok | {error, Reason}
473 Types:
475 NewSize = {MaxBytes, MaxFiles}
477 MaxBytes = integer()
478 MaxFiles = integer()
479 Reason = term()
480 Changes the log size of the Audit Trail Log. The application
482 must be configured to use the audit trail log function. Please
483 refer to disk_log(3) in Kernel Reference Manual for a descrip‐
484 tion of how to change the log size.
485 The change is permanent, as long as the log is not deleted. That
487 means, the log size is remembered across reboots.
488 set_log_type(NewType) -> {ok, OldType} | {error, Reason}
490 set_log_type(Agent, NewType) -> {ok, OldType} | {error, Reason}
491 Types:
493 NewType = OldType = atl_type()
495 Agent = pid() | atom()
496 Reason = term()
497 Changes the run-time Audit Trail log type.
499 Note that this has no effect on the application configuration as
501 defined by configuration files, so a node restart will revert
502 the config to whatever is in those files.
503 This function is primarily useful in testing/debugging scenar‐
505 ios.
506 mib_of(Oid) -> {ok, MibName} | {error, Reason}
508 mib_of(Agent, Oid) -> {ok, MibName} | {error, Reason}
509 Types:
511 Agent = pid() | atom()
513 Oid = oid()
514 MibName = atom()
515 Reason = term()
516 Finds the mib corresponding to the Oid. If it is a variable, the
518 Oid must be <Oid for var>.0 and if it is a table, Oid must be
519 <table>.<entry>.<col>.<any>
520 me_of(Oid) -> {ok, Me} | {error, Reason}
522 me_of(Agent, Oid) -> {ok, Me} | {error, Reason}
523 Types:
525 Agent = pid() | atom()
527 Oid = oid()
528 Me = #me{}
529 Reason = term()
530 Finds the mib entry corresponding to the Oid. If it is a vari‐
532 able, the Oid must be <Oid for var>.0 and if it is a table, Oid
533 must be <table>.<entry>.<col>.<any>
534 invalidate_mibs_cache() -> void()
536 invalidate_mibs_cache(Agent) -> void()
537 Types:
539 Agent = pid() | atom()
541 Invalidate the mib server cache.
543 The entire contents of the cache will be deleted.
545 enable_mibs_cache() -> void()
547 enable_mibs_cache(Agent) -> void()
548 Types:
550 Agent = pid() | atom()
552 Enable the mib server cache.
554 disable_mibs_cache() -> void()
556 disable_mibs_cache(Agent) -> void()
557 Types:
559 Agent = pid() | atom()
561 Disable the mib server cache.
563 which_mibs_cache_size() -> void()
565 which_mibs_cache_size(Agent) -> void()
566 Types:
568 Agent = pid() | atom()
570 Retreive the size of the mib server cache.
572 gc_mibs_cache() -> {ok, NumElementsGCed} | {error, Reason}
574 gc_mibs_cache(Agent) -> {ok, NumElementsGCed} | {error, Reason}
575 gc_mibs_cache(Age) -> {ok, NumElementsGCed} | {error, Reason}
576 gc_mibs_cache(Agent, Age) -> {ok, NumElementsGCed} | {error, Reason}
577 gc_mibs_cache(Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}
578 gc_mibs_cache(Agent, Age, GcLimit) -> {ok, NumElementsGCed} | {error,
579 Reason}
580 Types:
582 Agent = pid() | atom()
584 Age = integer() > 0
585 GcLimit = integer() > 0 | infinity
586 NumElementsGCed = integer() >= 0
587 Reason = term()
588 Perform mib server cache gc.
590 Manually performs a mib server cache gc. This can be done
592 regardless of the value of the autogc option. The NumElements‐
593 GCed value indicates how many elements where actually removed
594 from the cache.
595 enable_mibs_cache_autogc() -> void()
597 enable_mibs_cache_autogc(Agent) -> void()
598 Types:
600 Agent = pid() | atom()
602 Enable automatic gc of the mib server cache.
604 disable_mibs_cache_autogc() -> void()
606 disable_mibs_cache_autogc(Agent) -> void()
607 Types:
609 Agent = pid() | atom()
611 Disable automatic gc of the mib server cache.
613 update_mibs_cache_age(NewAge) -> ok | {error, Reason}
615 update_mibs_cache_age(Agent, NewAge) -> ok | {error, Reason}
616 Types:
618 Agent = pid() | atom()
620 NewAge = integer() > 0
621 Reason = term()
622 Change the mib server cache age property.
624 update_mibs_cache_gclimit(NewGcLimit) -> ok | {error, Reason}
626 update_mibs_cache_gclimit(Agent, NewGCLimit) -> ok | {error, Reason}
627 Types:
629 Agent = pid() | atom()
631 NewGcLimit = integer() > 0 | infinity
632 Reason = term()
633 Change the mib server cache gclimit property.
635 register_notification_filter(Id, Mod, Data) -> ok | {error, Reason}
637 register_notification_filter(Agent, Id, Mod, Data) -> ok | {error, Rea‐
638 son}
639 register_notification_filter(Id, Mod, Data, Where) -> ok | {error, Rea‐
640 son}
641 register_notification_filter(Agent, Id, Mod, Data, Where) -> ok |
642 {error, Reason}
643 Types:
645 Agent = pid() | atom()
647 Id = filter_id()
648 filter_id() = term()
649 Mod = atom()
650 Data = term()
651 Where = filter_position()
652 Reason = term()
653 filter_position() = first | last | {insert_before, fil‐
654 ter_id()} | {insert_after, filter_id()}
655 Registers a notification filter.
657 Mod is a module implementing the snmpa_notification_filter be‐
659 haviour.
660 Data will be passed on to the filter when calling the functions
662 of the behaviour.
663 unregister_notification_filter(Id) -> ok | {error, Reason}
665 unregister_notification_filter(Agent, Id) -> ok | {error, Reason}
666 Types:
668 Agent = pid() | atom()
670 Id = filter_id()
671 filter_id() = term()
672 Unregister a notification filter.
674 which_notification_filter() -> Filters
676 which_notification_filter(Agent) -> Filters
677 Types:
679 Agent = pid() | atom()
681 Filters = [filter_id()]
682 filter_id() = term()
683 List all notification filters in an agent.
685 set_request_limit(NewLimit) -> {ok, OldLimit} | {error, Reason}
687 set_request_limit(Agent, NewLimit) -> {ok, OldLimit} | {error, Reason}
688 Types:
690 NewLimit = OldLimit = infinity | integer() >= 0
692 Agent = pid() | atom()
693 Reason = term()
694 Changes the request limit.
696 Note that this has no effect on the application configuration as
698 defined by configuration files, so a node restart will revert
699 the config to whatever is in those files.
700 This function is primarily useful in load regulation scenarios.
702 register_subagent(Agent, SubTreeOid, Subagent) -> ok | {error, Reason}
704 Types:
706 Agent = pid() | atom()
708 SubTreeOid = oid()
709 SubAgent = pid()
710 Registers a sub-agent under a sub-tree of another agent.
712 It is easy to make mistakes when registering sub-agents and this
714 activity should be done carefully. For example, a strange behav‐
715 iour would result from the following configuration:
716 snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1),
718 snmp_agent:register_subagent(SA1,[1,2,3], SA2).
719 SA2 will not get requests starting with object identifier
722 [1,2,3] since SA1 does not.
723 unregister_subagent(Agent, SubagentOidOrPid) -> ok | {ok, SubAgentPid}
725 | {error, Reason}
726 Types:
728 Agent = pid() | atom()
730 SubTreeOidorPid = oid() | pid()
731 Unregister a sub-agent. If the second argument is a pid, then
733 that sub-agent will be unregistered from all trees in Agent.
734 send_notification2(Agent, Notification, SendOpts) -> void()
736 Types:
738 Agent = pid() | atom()
740 Notification = atom()
741 SendOpts = [send_option()]
742 send_option() = {receiver, receiver()} | {name,
743 notify_name()} | {context, context_name()} | {varbinds,
744 varbinds()} | {local_engine_id, string()} | {extra,
745 extra_info()}
746 receiver() = no_receiver | {tag(), tag_receiver()} | notifi‐
747 cation_delivery_info()
748 tag() = term(()
749 tag_receiver() = pid() | registered_name() | {Mod, Func,
750 Args}
751 registered_name() = atom()
752 Mod = atom()
753 Func = atom()
754 Args = list()
755 notify_name() = string()
756 context_name() = string()
757 varbinds() = [varbind()]
758 varbind() = {variable(), value()} | {column(), row_index(),
759 value()} | {oid(), value()}
760 variable() = atom()
761 value() = term()
762 column() = atom()
763 row_index() = [int()]
764 extra_info() = term()
765 Send the notification Notification to the management targets
767 defined for notify-name (name) in the snmpNotifyTable in SNMP-
768 NOTIFICATION-MIB from the specified context.
769 If no name is specified (or if it is ""), the notification is
771 sent to all management targets.
772 If no context is specified, the default context, "", is used.
774 The send option receiver specifies where information about
776 delivery of Inform-Requests should be sent. The agent sends
777 Inform-Requests and waits for acknowledgments from the manage‐
778 ment targets. The receiver can have three values:
779 * no_receiver - No information is delivered.
781 * notification_delivery_info() - The information is delivered
783 via a function call according to this data. See the DATA
784 TYPES section above for details.
785 * {tag(), tag_receiver()} - The information is delivered
787 either via messages or via a function call according to the
788 value of tag_receiver().
789 Delivery is done differently depending on the value of
791 tag_receiver():
792 * pid() | registered_name() - The info will be delivered in
794 the following messages:
795 * {snmp_targets, tag(), Addresses}
797 This informs the user which target addresses the notifi‐
799 cation was sent to.
800 * {snmp_notification, tag(), {got_response, Address}}
802 This informs the user that this target address acknowl‐
804 edged the notification.
805 * {snmp_notification, tag(), {no_response, Address}}
807 This informs the user that this target address did not
809 acknowledge the notification.
810 The notification is sent as an Inform-Request to each tar‐
812 get address in Addresses and if there are no targets for
813 which an Inform-Request is sent, Addresses is the empty
814 list [].
815 The tag_receiver() will first be sent the snmp_targets
817 message, and then for each address in Addresses list, one
818 of the two snmp_notification messages.
819 * {Mod, Func, Args} - The info will be delivered via the
821 function call:
822 Mod:Func([Msg | Args])
824 where Msg has the same content and purpose as the messages
826 descrived above.
827 Note:
829 The extra info is not normally interpreted by the agent, instead
830 it is passed through to the net-if process. It is up to the
831 implementor of that process to make use of this data.
832 The version of net-if provided by this application makes no use
834 of this data, with one exception: Any tuple containing the atom
835 snmpa_default_notification_extra_info may be used by the agent
836 and is therefor reserved.
837 See the net-if incomming messages for sending a trap and noti‐
839 fication for more info.
840 send_notification(Agent, Notification, Receiver)
843 send_notification(Agent, Notification, Receiver, Varbinds)
844 send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)
845 send_notification(Agent, Notification, Receiver, NotifyName, Con‐
846 textName, Varbinds) -> void()
847 send_notification(Agent, Notification, Receiver, NotifyName, Con‐
848 textName, Varbinds, LocalEngineID) -> void()
849 Types:
851 Agent = pid() | atom()
853 Notification = atom()
854 Receiver = no_receiver | {Tag, Recv} | notification_deliv‐
855 ery_info()
856 Tag = term()
857 Recv = receiver()
858 receiver() = pid() | atom() | {Mod, Func, Args}
859 Mod = atom()
860 Func = atom()
861 Args = list()
862 NotifyName = string()
863 ContextName = string()
864 Varbinds = varbinds()
865 varbinds() = [varbind()]
866 varbind() = {Variable, Value} | {Column, RowIndex, Value} |
867 {OID, Value}
868 Variable = atom()
869 Column = atom()
870 OID = oid()
871 Value = term()
872 RowIndex = [int()]
873 LocalEngineID = string()
874 Sends the notification Notification to the management targets
876 defined for NotifyName in the snmpNotifyTable in SNMP-NOTIFICA‐
877 TION-MIB from the specified context.
878 If no NotifyName is specified (or if it is ""), the notification
880 is sent to all management targets (Addresses below).
881 If no ContextName is specified, the default "" context is used.
883 The parameter Receiver specifies where information about deliv‐
885 ery of Inform-Requests should be sent. The agent sends Inform-
886 Requests and waits for acknowledgments from the managers.
887 Receiver can have three values:
888 * no_receiver - No information is delivered.
890 * notification_delivery_info() - The information is delivered
892 via a function call according to this data. See the DATA
893 TYPES section above for details.
894 * {Tag, Recv} - The information is delivered either via mes‐
896 sages or via a function call according to the value of Recv.
897 If Receiver has the value {Tag, Recv}, the delivery is done
899 according to Recv:
900 * pid() | atom() - The info will be delivered in the following
902 messages:
903 * {snmp_targets, Tag, Addresses}
905 This inform the user which target addresses the notifica‐
907 tion was sent to.
908 * {snmp_notification, Tag, {got_response, Address}}
910 This informs the user that this target address acknowl‐
912 edged the notification.
913 * {snmp_notification, Tag, {no_response, Address}}
915 This informs the user that this target address did not
917 acknowledge notification.
918 The notification is sent as an Inform-Request to each target
920 address in Addresses and if there are no targets for which
921 an Inform-Request is sent, Addresses is the empty list [].
922 The receiver will first be sent the snmp_targets message,
924 and then for each address in Addresses list, one of the two
925 snmp_notification messages.
926 * {Mod, Func, Args} - The info will be delivered via the func‐
928 tion call:
929 Mod:Func([Msg | Args])
931 where Msg has the same content and purpose as the messages
933 descrived above.
934 Address is a management target address and Addresses is a list
936 of management target addresses. They are defined as followes:
937 Addresses = [address()]
939 Address = address()
940 address() = v1_address() | v3_address()
941 v1_address() = {TDomain, TAddress}
942 v3_address() = {{TDomain, TAddress}, V3MsgData}
943 TDomain = tdoamin()
944 TAddress = taddress()
945 tdomain() = The oid of snmpUDPDomain
946 This is the only supported transport domain.
947 taddress() = [A1, A2, A3, A4, P1, P3]
948 The 4 first bytes makes up the IP-address and the last 2,
949 the UDP-port number.
950 V3MsgData = v3_msg_data()
951 v3_msg_data() = term()
952 If Receiver is a notification_delivery_info() record, then the
955 information about the notification delivery will be delivered to
956 the receiver via the callback functions defined by the
957 snmpa_notification_delivery_info_receiver behaviour according to
958 the content of the notification_delivery_info() record.
959 The optional argument Varbinds defines values for the objects in
961 the notification. If no value is given for an object, the Agent
962 performs a get-operation to retrieve the value.
963 Varbinds is a list of Varbind, where each Varbind is one of:
965 * {Variable, Value}, where Variable is the symbolic name of a
967 scalar variable referred to in the notification specifica‐
968 tion.
969 * {Column, RowIndex, Value}, where Column is the symbolic name
971 of a column variable. RowIndex is a list of indices for the
972 specified element. If this is the case, the OBJECT IDENTI‐
973 FIER sent in the notification is the RowIndex appended to
974 the OBJECT IDENTIFIER for the table column. This is the
975 OBJECT IDENTIFIER which specifies the element.
976 * {OID, Value}, where OID is the OBJECT IDENTIFIER for an
978 instance of an object, scalar variable, or column variable.
979 For example, to specify that sysLocation should have the value
981 "upstairs" in the notification, we could use one of:
982 * {sysLocation, "upstairs"} or
984 * {[1,3,6,1,2,1,1,6,0], "upstairs"} or
986 * {?sysLocation_instance, "upstairs"} (provided that the gen‐
988 erated .hrl file is included)
989 If a variable in the notification is a table element, the
991 RowIndex for the element must be given in the Varbinds list. In
992 this case, the OBJECT IDENTIFIER sent in the notification is the
993 OBJECT IDENTIFIER that identifies this element. This OBJECT
994 IDENTIFIER could be used in a get operation later.
995 This function is asynchronous, and does not return any informa‐
997 tion. If an error occurs, user_err/2 of the error report module
998 is called and the notification is discarded.
999 Note:
1001 Note that the use of the LocalEngineID argument is only intended
1002 for special cases, if the agent is to "emulate" multiple
1003 EngineIDs! By default, the agent uses the value of SnmpEngineID
1004 (see SNMP-FRAMEWORK-MIB).
1005 ExtraInfo is not normally used in any way by the agent. It is
1008 intended to be passed along to the net-if process, which is a
1009 component that a user can implement themself. The users own net-
1010 if may then make use of ExtraInfo. The net-if provided with this
1011 application does not process ExtraInfo.
1012 There is one exception. Any tuple containing the atom
1014 snmpa_default_notification_extra_info will, in this context, be
1015 considered belonging to this application, and may be processed
1016 by the agent.
1017 discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error,
1019 Reason}
1020 discovery(TargetName, Notification, Varbinds) -> {ok, ManagerEngineID}
1021 | {error, Reason}
1022 discovery(TargetName, Notification, DiscoHandler) -> {ok, Man‐
1023 agerEngineID} | {error, Reason}
1024 discovery(TargetName, Notification, ContextName, Varbinds) -> {ok, Man‐
1025 agerEngineID} | {error, Reason}
1026 discovery(TargetName, Notification, Varbinds, DiscoHandler) -> {ok,
1027 ManagerEngineID} | {error, Reason}
1028 discovery(TargetName, Notification, ContextName, Varbinds, DiscoHan‐
1029 dler) -> {ok, ManagerEngineID} | {error, Reason}
1030 discovery(TargetName, Notification, ContextName, Varbinds, DiscoHan‐
1031 dler, ExtraInfo) -> {ok, ManagerEngineID} | {error, Reason}
1032 Types:
1034 TargetName = string()
1036 Notification = atom()
1037 ContextName = string() (defaults to "")
1038 Varbinds = varbinds()
1039 varbinds() = [varbind()]
1040 DiscoHandler = snmpa_discovery_handler()
1041 ExtraInfo = term()
1042 snmpa_discovery_handler() = Module implementing the
1043 snmpa_discovery_handler behaviour
1044 ManagerEngineID = string()
1045 varbind() = {Variable, Value} | {Column, RowIndex, Value} |
1046 {OID, Value}
1047 Variable = atom()
1048 Column = atom()
1049 OID = oid()
1050 Value = term()
1051 RowIndex = [int()]
1052 Reason = term()
1053 Initiate the discovery process with the manager identified by
1055 TargetName using the notification Notification.
1056 This function is synchronous, which means that it will return
1058 when the discovery process has been completed or failed.
1059 The DiscoHandler module is used during the discovery process.
1061 See discovery handler for more info.
1062 The ExtraInfo argument is passed on to the callback functions of
1064 the DiscoHandler.
1065 Note:
1067 If we are not at security-level noAuthNoPriv, this could be com‐
1068 plicated, since the agent will then continue with stage 2,
1069 before which the usm-related updates must be done.
1070 Note:
1073 The default discovery handler will require additional actions by
1074 the caller and the discovery will not work if the security-level
1075 is higher then noAuthNoPriv.
1076 convert_config(OldConfig) -> AgentConfig
1079 Types:
1081 OldConfig = list()
1083 AgentConfig = list()
1084 This off-line utility function can be used to convert the old
1086 snmp application config (pre snmp-4.0) to the new snmp agent
1087 config (as of snmp-4.0).
1088 For information about the old config (OldConfig) see the OTP R9C
1090 documentation.
1091 For information about the current agent config (AgentConfig),
1093 see either the SNMP application part of the reference manual or
1094 the Configuring the application chapter of the SNMP user's
1095 guide.
1096 restart_worker() -> void()
1098 restart_worker(Agent) -> void()
1099 Types:
1101 Agent = pid() | atom()
1103 Restart the worker process of a multi-threaded agent.
1105 This is a utility function, that can be useful when e.g. debug‐
1107 ging instrumentation functions.
1108 restart_set_worker() -> void()
1110 restart_set_worker(Agent) -> void()
1111 Types:
1113 Agent = pid() | atom()
1115 Restart the set worker process of a multi-threaded agent.
1117 This is a utility function, that can be useful when e.g. debug‐
1119 ging instrumentation functions.
1120 print_mib_info() -> void()
1122 Prints the content of all the (snmp) tables and variables for
1124 all mibs handled by the snmp agent.
1125 print_mib_tables() -> void()
1127 Prints the content of all the (snmp) tables for all mibs handled
1129 by the snmp agent.
1130 print_mib_variables() -> void()
1132 Prints the content of all the (snmp) variables for all mibs han‐
1134 dled by the snmp agent.
1135 verbosity(Ref,Verbosity) -> void()
1137 Types:
1139 Ref = pid() | sub_agents | master_agent | net_if | mib_server
1141 | symbolic_store | note_store | local_db
1142 Verbosity = verbosity() | {subagents, verbosity()}
1143 verbosity() = silence | info | log | debug | trace
1144 Sets verbosity for the designated process. For the lowest ver‐
1146 bosity silence, nothing is printed. The higher the verbosity,
1147 the more is printed.
1148
1150 calendar(3), erlc(1)
1151Ericsson AB snmp 5.2.11.1 snmpa(3)