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 | {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
427 defaults 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 usefull 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 usefull 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 Retreive 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
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 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 |
650 {error, 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,
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()} | {{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
777 defined for notify-name (name) in the snmpNotifyTable in SNMP-
778 NOTIFICATION-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
786 delivery of Inform-Requests should be sent. The agent sends
787 Inform-Requests and waits for acknowledgments from the manage‐
788 ment 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
797 either 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 indended 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
857 implementor 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 therefor reserved.
863 See the net-if incomming 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.
913 Receiver 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
925 according 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
943 acknowledge 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
983 snmpa_notification_delivery_info_receiver behaviour according to
984 the 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
1001 OBJECT IDENTIFIER which specifies the element.
1002 * {OID, Value}, where OID is the OBJECT IDENTIFIER for an
1004 instance 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
1029 EngineIDs! 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
1040 snmpa_default_notification_extra_info will, in this context, be
1041 considered belonging to this application, and may be processed
1042 by the 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
1069 snmpa_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,
1095 before 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.5 snmpa(3)