--- name: "snmpa" section: "3erl" platform: "linux" package: "erlang-manpages" version: "1:25.2.3+dfsg-1+deb12u4" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/snmpa" --- # snmpa(3erl) Interface Functions to the SNMP toolkit agent ## NAME snmpa - Interface Functions to the SNMP toolkit agent ## DESCRIPTION The module *snmpa* contains interface functions to the SNMP agent. ## DATA TYPES ``` oid() = [byte()] atl_type() = read | write | read_write notification_delivery_info() = #snmpa_notification_delivery_info{} ``` The *oid()* type is used to represent an ASN.1 OBJECT IDENTIFIER. The record *snmpa\_notification\_delivery\_info* contains the following fields: - ***tag = term()*:** A user defined identity representing this notification send operation. - ***mod = module()*:** A module implementing the snmpa\_notification\_delivery\_info\_receiver behaviour. The info functions of this module will be called at various stages of delivery. - ***extra = term()*:** This is any extra info the user wants to have supplied when the functions in the callback module is called. ## EXPORTS **add\_agent\_caps(SysORID, SysORDescr) -\> SysORIndex**\ Types: SysORID = oid()\ SysORDescr = string()\ SysORIndex = integer()\ This function can be used to add an AGENT-CAPABILITY statement to the sysORTable in the agent. The table is defined in the SNMPv2-MIB. **del\_agent\_caps(SysORIndex) -\> void()**\ Types: SysORIndex = integer()\ This function can be used to delete an AGENT-CAPABILITY statement to the sysORTable in the agent. This table is defined in the SNMPv2-MIB. **get\_agent\_caps() -\> \[\[SysORIndex, SysORID, SysORDescr, SysORUpTime\]\]**\ Types: SysORIndex = integer()\ SysORId = oid()\ SysORDescr = string()\ SysORUpTime = integer()\ Returns all AGENT-CAPABILITY statements in the sysORTable in the agent. This table is defined in the SNMPv2-MIB. **get(Agent, Vars) -\> Values \| {error, Reason}**\ **get(Agent, Vars, Context) -\> Values \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Vars = \[oid()\]\ Context = string()\ Values = \[term()\]\ Reason = {atom(), oid()}\ Performs a GET operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager. Note that the request specific parameters (such as current\_request\_id) are not accessible for the instrumentation functions if this function is used. **get\_next(Agent, Vars) -\> Values \| {error, Reason}**\ **get\_next(Agent, Vars, Context) -\> Values \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Vars = \[oid()\]\ Context = string()\ Values = \[{oid(), term()}\]\ Reason = {atom(), oid()}\ Performs a GET-NEXT operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager. Note that the request specific parameters (such as *snmpa:current\_request\_id/0* are not accessible for the instrumentation functions if this function is used. **backup(BackupDir) -\> ok \| {error, Reason}**\ **backup(Agent, BackupDir) -\> ok \| {error, Reason}**\ Types: BackupDir = string()\ Agent = pid() \| atom()\ Reason = backup\_in\_progress \| term()\ Backup persistent/permanent data handled by the agent (such as local-db, mib-data and vacm). Data stored by mnesia is not handled. BackupDir cannot be identical to DbDir. Simultaneous backup calls are *not* allowed. That is, two different processes cannot simultaneously successfully call this function. One of them will be first, and succeed. The second will fail with the error reason *backup\_in\_progress*. **info() -\> \[{Key, Value}\]**\ **info(Agent) -\> \[{Key, Value}\]**\ Types: Agent = pid() \| atom()\ Returns a list (a dictionary) containing information about the agent. Information includes loaded MIBs, registered sub-agents, some information about the memory allocation. **load\_mib(Mib) -\> ok \| {error, Reason}**\ **load\_mib(Agent, Mib) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ MibName = string()\ Reason = already\_loaded \| term()\ Load a single *Mib* into an agent. The *MibName* is the name of the Mib, including the path to where the compiled mib is found. For example: ``` Dir = code:priv_dir(my_app) ++ "/mibs/", snmpa:load_mib(snmp_master_agent, Dir ++ "MY-MIB"). ``` **load\_mibs(Mibs) -\> ok \| {error, Reason}**\ **load\_mibs(Mibs, Force) -\> ok \| {error, Reason}**\ **load\_mibs(Agent, Mibs) -\> ok \| {error, Reason}**\ **load\_mibs(Agent, Mibs, Force) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Mibs = \[MibName\]\ Force = boolean()\ MibName = string()\ Reason = {'load aborted at', MibName, InternalReason}\ InternalReason = already\_loaded \| term()\ Load *Mibs* into an agent. If the agent cannot load all MIBs (the default value of the *Force* argument is *false*), it will indicate where loading was aborted. The *MibName* is the name of the Mib, including the path to where the compiled mib is found. For example, ``` Dir = code:priv_dir(my_app) ++ "/mibs/", snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]). ``` If *Force = true* then the agent will continue attempting to load each mib even after failing to load a previous mib. Use with care. **unload\_mib(Mib) -\> ok \| {error, Reason}**\ **unload\_mib(Agent, Mib) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ MibName = string()\ Reason = not\_loaded \| term()\ Unload a single *Mib* from an agent. **unload\_mibs(Mibs) -\> ok \| {error, Reason}**\ **unload\_mibs(Mibs, Force) -\> ok \| {error, Reason}**\ **unload\_mibs(Agent, Mibs) -\> ok \| {error, Reason}**\ **unload\_mibs(Agent, Mibs, Force) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Mibs = \[MibName\]\ Force = boolean()\ MibName = string()\ Reason = {'unload aborted at', MibName, InternalReason}\ InternalReason = not\_loaded \| term()\ Unload *Mibs* from an agent. If it cannot unload all MIBs (the default value of the *Force* argument is *false*), it will indicate where unloading was aborted. If *Force = true* then the agent will continue attempting to unload each mib even after failing to unload a previous mib. Use with care. **which\_mibs() -\> Mibs**\ **which\_mibs(Agent) -\> Mibs**\ Types: Agent = pid() \| atom()\ Mibs = \[{MibName, MibFile}\]\ MibName = atom()\ MibFile = string()\ Retrieve the list of all the mibs loaded into this agent. Default is the master agent. **whereis\_mib(MibName) -\> {ok, MibFile} \| {error, Reason}**\ **whereis\_mib(Agent, MibName) -\> {ok, MibFile} \| {error, Reason}**\ Types: Agent = pid() \| atom()\ MibName = atom()\ MibFile = string()\ Reason = term()\ Get the full path to the (compiled) mib-file. **current\_request\_id() -\> {value, RequestId} \| false**\ **current\_context() -\> {value, Context} \| false**\ **current\_community() -\> {value, Community} \| false**\ **current\_address() -\> {value, Address} \| false**\ Types: RequestId = integer()\ Context = string()\ Community = string()\ Address = term()\ Get the request-id, context, community and address of the request currently being processed by the agent. Note that these functions is intended to be called by the instrumentation functions and *only* if they are executed in the context of the agent process (e.g. it does not work if called from a spawned process). **enum\_to\_int(Name, Enum) -\> {value, Int} \| false**\ **enum\_to\_int(Db, Name, Enum) -\> {value, Int} \| false**\ Types: Db = term()\ Name = atom()\ Enum = atom()\ Int = int()\ Converts the symbolic value *Enum* to the corresponding integer of the enumerated object or type *Name* in a MIB. The MIB must be loaded. *false* is returned if the object or type is not defined in any loaded MIB, or if it does not define the symbolic value as enumerated. *Db* is a reference to the symbolic store database (retrieved by a call to *get\_symbolic\_store\_db/0*). **int\_to\_enum(Name, Int) -\> {value, Enum} \| false**\ **int\_to\_enum(Db, Name, Int) -\> {value, Enum} \| false**\ Types: Db = term()\ Name = atom()\ Int = int()\ Enum = atom()\ Converts the integer *Int* to the corresponding symbolic value of the enumerated object or type *Name* in a MIB. The MIB must be loaded. *false* is returned if the object or type is not defined in any loaded MIB, or if it does not define the symbolic value as enumerated. *Db* is a reference to the symbolic store database (retrieved by a call to *get\_symbolic\_store\_db/0*). **name\_to\_oid(Name) -\> {value, oid()} \| false**\ **name\_to\_oid(Db, Name) -\> {value, oid()} \| false**\ Types: Db = term()\ Name = atom()\ Looks up the OBJECT IDENTIFIER of a MIB object, given the symbolic name. Note, the OBJECT IDENTIFIER is given for the object, not for an instance. *false* is returned if the object is not defined in any loaded MIB. *Db* is a reference to the symbolic store database (retrieved by a call to *get\_symbolic\_store\_db/0*). **oid\_to\_name(OID) -\> {value, Name} \| false**\ **oid\_to\_name(Db, OID) -\> {value, Name} \| false**\ Types: Db = term()\ OID = oid()\ Name = atom()\ Looks up the symbolic name of a MIB object, given OBJECT IDENTIFIER. *false* is returned if the object is not defined in any loaded MIB. *Db* is a reference to the symbolic store database (retrieved by a call to *get\_symbolic\_store\_db/0*). **which\_aliasnames() -\> Result**\ Types: Result = \[atom()\]\ Retrieve all alias-names known to the agent. **which\_tables() -\> Result**\ Types: Result = \[atom()\]\ Retrieve all tables known to the agent. **which\_transports() -\> Result**\ Types: Result = \[{TDomain, TAddress} \| {TDomain, TAddress, Kind}\]\ TDomain = transportDomainUdpIpv4 \| transportDomainUdpIpv6\ TAddress = {IpAddr, IpPort}\ IpAddr = inet:ip\_address()\ IpPort = pos\_integer()\ Kind = req\_responder \| trap\_sender\ Retrieve all configured transports. **which\_variables() -\> Result**\ Types: Result = \[atom()\]\ Retrieve all variables known to the agent. **which\_notifications() -\> Result**\ Types: Result = \[{Name, MibName, Info}\]\ Name = atom()\ MibName = atom()\ Info = term()\ Retrieve all notifications (and traps) known to the agent. **log\_to\_txt(LogDir)**\ **log\_to\_txt(LogDir, Block \| Mibs)**\ **log\_to\_txt(LogDir, Mibs, Block \| OutFile) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_txt(LogDir, Mibs, OutFile, Block \| LogName) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_txt(LogDir, Mibs, OutFile, LogName, Block \| LogFile) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block \| Start) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) -\> ok \| {ok, Cnt} \| {error, Reason}**\ Types: LogDir = string()\ Mibs = \[MibName\]\ MibName = string()\ Block = boolean()\ OutFile = string()\ LogName = string()\ LogFile = string()\ Start = Stop = null \| calendar:datetime() \| {local\_time, calendar:datetime()} \| {universal\_time, calendar:datetime()} \ Cnt = {NumOK, NumERR}\ NumOK = non\_neg\_integer()\ NumERR = pos\_integer()\ Reason = disk\_log\_open\_error() \| file\_open\_error() \| term()\ disk\_log\_open\_error() = {LogName, term()}\ file\_open\_error() = {OutFile, term()}\ Converts an Audit Trail Log to a readable text file. *OutFile* defaults to "./snmpa\_log.txt". *LogName* defaults to "snmpa\_log". *LogFile* defaults to "snmpa.log". The *Block* option indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to *true*. See snmp:log\_to\_txt for more info. **log\_to\_io(LogDir) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_io(LogDir, Block \| Mibs) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_io(LogDir, Mibs, Block \| LogName) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_io(LogDir, Mibs, LogName, Block \| LogFile) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_io(LogDir, Mibs, LogName, LogFile, Block \| Start) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_io(LogDir, Mibs, LogName, LogFile, Block, Start) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_io(LogDir, Mibs, LogName, LogFile, Start, Stop) -\> ok \| {ok, Cnt} \| {error, Reason}**\ **log\_to\_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -\> ok \| {ok, Cnt} \| {error, Reason}**\ Types: LogDir = string()\ Mibs = \[MibName\]\ MibName = string()\ Block = boolean()\ LogName = string()\ LogFile = string()\ Start = Stop = null \| calendar:datetime() \| {local\_time, calendar:datetime()} \| {universal\_time, calendar:datetime()} \ Cnt = {NumOK, NumERR}\ NumOK = non\_neg\_integer()\ NumERR = pos\_integer()\ Reason = disk\_log\_open\_error() \| file\_open\_error() \| term()\ disk\_log\_open\_error() = {LogName, term()}\ file\_open\_error() = {OutFile, term()}\ Converts an Audit Trail Log to a readable format and prints it on stdio. *LogName* defaults to "snmpa\_log". *LogFile* defaults to "snmpa.log". The *Block* option indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to *true*. See snmp:log\_to\_io for more info. **change\_log\_size(NewSize) -\> ok \| {error, Reason}**\ Types: NewSize = {MaxBytes, MaxFiles}\ MaxBytes = integer()\ MaxFiles = integer()\ Reason = term()\ Changes the log size of the Audit Trail Log. The application must be configured to use the audit trail log function. Please refer to [disk\_log(3erl)](/disk_log/3erl.md) in Kernel Reference Manual for a description of how to change the log size. The change is permanent, as long as the log is not deleted. That means, the log size is remembered across reboots. **set\_log\_type(NewType) -\> {ok, OldType} \| {error, Reason}**\ **set\_log\_type(Agent, NewType) -\> {ok, OldType} \| {error, Reason}**\ Types: NewType = OldType = atl\_type()\ Agent = pid() \| atom()\ Reason = term()\ Changes the run-time Audit Trail log type. Note that this has no effect on the application configuration as defined by configuration files, so a node restart will revert the config to whatever is in those files. This function is primarily useful in testing/debugging scenarios. **mib\_of(Oid) -\> {ok, MibName} \| {error, Reason}**\ **mib\_of(Agent, Oid) -\> {ok, MibName} \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Oid = oid()\ MibName = atom()\ Reason = term()\ Finds the mib corresponding to the *Oid*. If it is a variable, the Oid must be \.0 and if it is a table, Oid must be \.\.\.\ **me\_of(Oid) -\> {ok, Me} \| {error, Reason}**\ **me\_of(Agent, Oid) -\> {ok, Me} \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Oid = oid()\ Me = #me{}\ Reason = term()\ Finds the mib entry corresponding to the *Oid*. If it is a variable, the Oid must be \.0 and if it is a table, Oid must be \.\.\.\ **invalidate\_mibs\_cache() -\> void()**\ **invalidate\_mibs\_cache(Agent) -\> void()**\ Types: Agent = pid() \| atom()\ Invalidate the mib server cache. The entire contents of the cache will be deleted. **enable\_mibs\_cache() -\> void()**\ **enable\_mibs\_cache(Agent) -\> void()**\ Types: Agent = pid() \| atom()\ Enable the mib server cache. **disable\_mibs\_cache() -\> void()**\ **disable\_mibs\_cache(Agent) -\> void()**\ Types: Agent = pid() \| atom()\ Disable the mib server cache. **which\_mibs\_cache\_size() -\> void()**\ **which\_mibs\_cache\_size(Agent) -\> void()**\ Types: Agent = pid() \| atom()\ Retrieve the size of the mib server cache. **gc\_mibs\_cache() -\> {ok, NumElementsGCed} \| {error, Reason}**\ **gc\_mibs\_cache(Agent) -\> {ok, NumElementsGCed} \| {error, Reason}**\ **gc\_mibs\_cache(Age) -\> {ok, NumElementsGCed} \| {error, Reason}**\ **gc\_mibs\_cache(Agent, Age) -\> {ok, NumElementsGCed} \| {error, Reason}**\ **gc\_mibs\_cache(Age, GcLimit) -\> {ok, NumElementsGCed} \| {error, Reason}**\ **gc\_mibs\_cache(Agent, Age, GcLimit) -\> {ok, NumElementsGCed} \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Age = integer() \> 0\ GcLimit = integer() \> 0 \| infinity\ NumElementsGCed = integer() \>= 0\ Reason = term()\ Perform mib server cache gc. Manually performs a mib server cache gc. This can be done regardless of the value of the *autogc* option. The *NumElementsGCed* value indicates how many elements where actually removed from the cache. **enable\_mibs\_cache\_autogc() -\> void()**\ **enable\_mibs\_cache\_autogc(Agent) -\> void()**\ Types: Agent = pid() \| atom()\ Enable automatic gc of the mib server cache. **disable\_mibs\_cache\_autogc() -\> void()**\ **disable\_mibs\_cache\_autogc(Agent) -\> void()**\ Types: Agent = pid() \| atom()\ Disable automatic gc of the mib server cache. **update\_mibs\_cache\_age(NewAge) -\> ok \| {error, Reason}**\ **update\_mibs\_cache\_age(Agent, NewAge) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ NewAge = integer() \> 0\ Reason = term()\ Change the mib server cache *age* property. **update\_mibs\_cache\_gclimit(NewGcLimit) -\> ok \| {error, Reason}**\ **update\_mibs\_cache\_gclimit(Agent, NewGCLimit) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ NewGcLimit = integer() \> 0 \| infinity\ Reason = term()\ Change the mib server cache *gclimit* property. **register\_notification\_filter(Id, Mod, Data) -\> ok \| {error, Reason}**\ **register\_notification\_filter(Agent, Id, Mod, Data) -\> ok \| {error, Reason}**\ **register\_notification\_filter(Id, Mod, Data, Where) -\> ok \| {error, Reason}**\ **register\_notification\_filter(Agent, Id, Mod, Data, Where) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Id = filter\_id()\ filter\_id() = term()\ Mod = atom()\ Data = term()\ Where = filter\_position()\ Reason = term()\ filter\_position() = first \| last \| {insert\_before, filter\_id()} \| {insert\_after, filter\_id()} \ Registers a notification filter. *Mod* is a module implementing the *snmpa\_notification\_filter* behaviour. *Data* will be passed on to the filter when calling the functions of the behaviour. **unregister\_notification\_filter(Id) -\> ok \| {error, Reason}**\ **unregister\_notification\_filter(Agent, Id) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ Id = filter\_id()\ filter\_id() = term()\ Unregister a notification filter. **which\_notification\_filter() -\> Filters**\ **which\_notification\_filter(Agent) -\> Filters**\ Types: Agent = pid() \| atom()\ Filters = \[filter\_id()\]\ filter\_id() = term()\ List all notification filters in an agent. **set\_request\_limit(NewLimit) -\> {ok, OldLimit} \| {error, Reason}**\ **set\_request\_limit(Agent, NewLimit) -\> {ok, OldLimit} \| {error, Reason}**\ Types: NewLimit = OldLimit = infinity \| integer() \>= 0\ Agent = pid() \| atom()\ Reason = term()\ Changes the request limit. Note that this has no effect on the application configuration as defined by configuration files, so a node restart will revert the config to whatever is in those files. This function is primarily useful in load regulation scenarios. **register\_subagent(Agent, SubTreeOid, Subagent) -\> ok \| {error, Reason}**\ Types: Agent = pid() \| atom()\ SubTreeOid = oid()\ SubAgent = pid()\ Registers a sub-agent under a sub-tree of another agent. It is easy to make mistakes when registering sub-agents and this activity should be done carefully. For example, a strange behaviour would result from the following configuration: ``` snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1), snmp_agent:register_subagent(SA1,[1,2,3], SA2). ``` *SA2* will not get requests starting with object identifier *\[1,2,3\]* since *SA1* does not. **unregister\_subagent(Agent, SubagentOidOrPid) -\> ok \| {ok, SubAgentPid} \| {error, Reason}**\ Types: Agent = pid() \| atom()\ SubTreeOidorPid = oid() \| pid()\ Unregister a sub-agent. If the second argument is a pid, then that sub-agent will be unregistered from all trees in *Agent*. **send\_notification2(Agent, Notification, SendOpts) -\> void()**\ Types: Agent = pid() \| atom()\ Notification = atom()\ SendOpts = \[send\_option()\]\ send\_option() = {receiver, receiver()} \| {name, notify\_name()} \| {context, context\_name()} \| {varbinds, varbinds()} \| {local\_engine\_id, string()} \| {extra, extra\_info()}\ receiver() = no\_receiver \| {tag(), tag\_receiver()} \| notification\_delivery\_info()\ tag() = term(()\ tag\_receiver() = pid() \| registered\_name() \| {Mod, Func, Args}\ registered\_name() = atom()\ Mod = atom()\ Func = atom()\ Args = list()\ notify\_name() = string()\ context\_name() = string()\ varbinds() = \[varbind()\]\ varbind() = {variable(), value()} \| {{process\_oid(), variable()}, value()} \| {column(), row\_index(), value()} \|\ variable() = aliasname() \| oid()\ aliasname() = atom()\ process\_oid() = keep (default) \| truncate\ value() = term()\ column() = atom()\ row\_index() = \[int()\]\ extra\_info() = term()\ Send the notification *Notification* to the management targets defined for notify-name (*name*) in the *snmpNotifyTable* in SNMP-NOTIFICATION-MIB from the specified *context*. If no *name* is specified (or if it is *""*), the notification is sent to all management targets. If no *context* is specified, the default context, *""*, is used. The send option *receiver* specifies where information about delivery of Inform-Requests should be sent. The agent sends Inform-Requests and waits for acknowledgments from the management targets. The *receiver* can have three values: - \* *no\_receiver* - No information is delivered. - \* *notification\_delivery\_info()* - The information is delivered via a function call according to this data. See the DATA TYPES section above for details. - \* *{tag(), tag\_receiver()}* - The information is delivered either via messages or via a function call according to the value of *tag\_receiver()*. Delivery is done differently depending on the value of *tag\_receiver()*: - \* *pid() \| registered\_name()* - The info will be delivered in the following messages: - \* *{snmp\_targets, tag(), Addresses}* This informs the user which target addresses the notification was sent to. - \* *{snmp\_notification, tag(), {got\_response, Address}}* This informs the user that this target address acknowledged the notification. - \* *{snmp\_notification, tag(), {no\_response, Address}}* This informs the user that this target address did not acknowledge the notification. The notification is sent as an Inform-Request to each target address in *Addresses* and if there are no targets for which an Inform-Request is sent, *Addresses* is the empty list *\[\]*. The *tag\_receiver()* will first be sent the *snmp\_targets* message, and then for each address in *Addresses* list, one of the two *snmp\_notification* messages. - \* *{Mod, Func, Args}* - The info will be delivered via the function call: *Mod:Func(\[Msg \| Args\])* where *Msg* has the same content and purpose as the messages descrived above. The 'process oid' "tag" that can be provided with the variable name / oids is intended to be used for oid post processing. The value '*keep*', which is the default, leaves the oid as is. The value '*truncate*', will cause the oid to be "truncated". That is, any trailing ".0" will be removed. **Note:** There is a way to exclude a varbind from the notification. In the normal *varbinds* list, providing the special value *'$ignore-oid'* (instead of a normal value) will exclude this varbind from the notification. A define for this has been added to the *snmp\_types.hrl* include file, *NOTIFICATION\_IGNORE\_VB\_VALUE*. **Note:** The *extra* info is not normally interpreted by the agent, instead it is passed through to the net-if process. It is up to the implementor of that process to make use of this data. The version of net-if provided by this application makes no use of this data, with one exception: Any tuple containing the atom *snmpa\_default\_notification\_extra\_info* may be used by the agent and is therefore *reserved*. See the net-if incoming messages for sending a trap and notification for more info. **send\_notification(Agent, Notification, Receiver)**\ **send\_notification(Agent, Notification, Receiver, Varbinds)**\ **send\_notification(Agent, Notification, Receiver, NotifyName, Varbinds)**\ **send\_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds) -\> void()** \ **send\_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds, LocalEngineID) -\> void()** \ Types: Agent = pid() \| atom()\ Notification = atom()\ Receiver = no\_receiver \| {Tag, Recv} \| notification\_delivery\_info()\ Tag = term()\ Recv = receiver()\ receiver() = pid() \| atom() \| {Mod, Func, Args}\ Mod = atom()\ Func = atom()\ Args = list()\ NotifyName = string()\ ContextName = string()\ Varbinds = varbinds()\ varbinds() = \[varbind()\]\ varbind() = {Variable, Value} \| {Column, RowIndex, Value} \| {OID, Value}\ Variable = atom()\ Column = atom()\ OID = oid()\ Value = term()\ RowIndex = \[int()\]\ LocalEngineID = string()\ Sends the notification *Notification* to the management targets defined for *NotifyName* in the *snmpNotifyTable* in SNMP-NOTIFICATION-MIB from the specified context. If no *NotifyName* is specified (or if it is *""*), the notification is sent to all management targets (*Addresses* below). If no *ContextName* is specified, the default *""* context is used. The parameter *Receiver* specifies where information about delivery of Inform-Requests should be sent. The agent sends Inform-Requests and waits for acknowledgments from the managers. *Receiver* can have three values: - \* *no\_receiver* - No information is delivered. - \* *notification\_delivery\_info()* - The information is delivered via a function call according to this data. See the DATA TYPES section above for details. - \* *{Tag, Recv}* - The information is delivered either via messages or via a function call according to the value of *Recv*. If *Receiver* has the value *{Tag, Recv}*, the delivery is done according to *Recv*: - \* *pid() \| atom()* - The info will be delivered in the following messages: - \* *{snmp\_targets, Tag, Addresses}* This inform the user which target addresses the notification was sent to. - \* *{snmp\_notification, Tag, {got\_response, Address}}* This informs the user that this target address acknowledged the notification. - \* *{snmp\_notification, Tag, {no\_response, Address}}* This informs the user that this target address did not acknowledge notification. The notification is sent as an Inform-Request to each target address in *Addresses* and if there are no targets for which an Inform-Request is sent, *Addresses* is the empty list *\[\]*. The *receiver* will first be sent the *snmp\_targets* message, and then for each address in *Addresses* list, one of the two *snmp\_notification* messages. - \* *{Mod, Func, Args}* - The info will be delivered via the function call: *Mod:Func(\[Msg \| Args\])* where *Msg* has the same content and purpose as the messages descrived above. *Address* is a management target address and *Addresses* is a list of management target addresses. They are defined as followes: ``` Addresses = [address()] Address = address() address() = v1_address() | v3_address() v1_address() = {TDomain, TAddress} v3_address() = {{TDomain, TAddress}, V3MsgData} TDomain = tdoamin() TAddress = taddress() tdomain() = The oid of snmpUDPDomain This is the only supported transport domain. taddress() = [A1, A2, A3, A4, P1, P3] The 4 first bytes makes up the IP-address and the last 2, the UDP-port number. V3MsgData = v3_msg_data() v3_msg_data() = term() ``` If *Receiver* is a *notification\_delivery\_info()* record, then the information about the notification delivery will be delivered to the *receiver* via the callback functions defined by the snmpa\_notification\_delivery\_info\_receiver behaviour according to the content of the *notification\_delivery\_info()* record. The optional argument *Varbinds* defines values for the objects in the notification. If no value is given for an object, the *Agent* performs a get-operation to retrieve the value. *Varbinds* is a list of *Varbind*, where each *Varbind* is one of: - \* *{Variable, Value}*, where *Variable* is the symbolic name of a scalar variable referred to in the notification specification. - \* *{Column, RowIndex, Value}*, where *Column* is the symbolic name of a column variable. *RowIndex* is a list of indices for the specified element. If this is the case, the OBJECT IDENTIFIER sent in the notification is the *RowIndex* appended to the OBJECT IDENTIFIER for the table column. This is the OBJECT IDENTIFIER which specifies the element. - \* *{OID, Value}*, where *OID* is the OBJECT IDENTIFIER for an instance of an object, scalar variable, or column variable. For example, to specify that *sysLocation* should have the value *"upstairs"* in the notification, we could use one of: - \* *{sysLocation, "upstairs"}* or - \* *{\[1,3,6,1,2,1,1,6,0\], "upstairs"}* or - \* *{?sysLocation\_instance, "upstairs"}* (provided that the generated *.hrl* file is included) If a variable in the notification is a table element, the *RowIndex* for the element must be given in the *Varbinds* list. In this case, the OBJECT IDENTIFIER sent in the notification is the OBJECT IDENTIFIER that identifies this element. This OBJECT IDENTIFIER could be used in a get operation later. This function is asynchronous, and does not return any information. If an error occurs, *user\_err/2* of the error report module is called and the notification is discarded. **Note:** Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of *SnmpEngineID* (see SNMP-FRAMEWORK-MIB). *ExtraInfo* is not normally used in any way by the agent. It is intended to be passed along to the net-if process, which is a component that a user can implement themself. The users own net-if may then make use of ExtraInfo. The net-if provided with this application does not process ExtraInfo. There is one exception. *Any* tuple containing the atom *snmpa\_default\_notification\_extra\_info* will, in this context, be considered belonging to this application, and may be processed by the agent. **discovery(TargetName, Notification) -\> {ok, ManagerEngineID} \| {error, Reason}**\ **discovery(TargetName, Notification, Varbinds) -\> {ok, ManagerEngineID} \| {error, Reason}**\ **discovery(TargetName, Notification, DiscoHandler) -\> {ok, ManagerEngineID} \| {error, Reason}**\ **discovery(TargetName, Notification, ContextName, Varbinds) -\> {ok, ManagerEngineID} \| {error, Reason}**\ **discovery(TargetName, Notification, Varbinds, DiscoHandler) -\> {ok, ManagerEngineID} \| {error, Reason}**\ **discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler) -\> {ok, ManagerEngineID} \| {error, Reason}**\ **discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler, ExtraInfo) -\> {ok, ManagerEngineID} \| {error, Reason}**\ Types: TargetName = string()\ Notification = atom()\ ContextName = string() (defaults to "")\ Varbinds = varbinds()\ varbinds() = \[varbind()\]\ DiscoHandler = snmpa\_discovery\_handler()\ ExtraInfo = term()\ snmpa\_discovery\_handler() = Module implementing the snmpa\_discovery\_handler behaviour\ ManagerEngineID = string()\ varbind() = {Variable, Value} \| {Column, RowIndex, Value} \| {OID, Value}\ Variable = atom()\ Column = atom()\ OID = oid()\ Value = term()\ RowIndex = \[int()\]\ Reason = term()\ Initiate the discovery process with the manager identified by *TargetName* using the notification *Notification*. This function is synchronous, which means that it will return when the discovery process has been completed or failed. The *DiscoHandler* module is used during the discovery process. See discovery handler for more info. The *ExtraInfo* argument is passed on to the callback functions of the *DiscoHandler*. **Note:** If we are not at security-level *noAuthNoPriv*, this could be complicated, since the agent will then continue with stage 2, before which the usm-related updates must be done. **Note:** The default discovery handler will require additional actions by the caller and the discovery will not work if the security-level is higher then *noAuthNoPriv*. **convert\_config(OldConfig) -\> AgentConfig**\ Types: OldConfig = list()\ AgentConfig = list()\ This off-line utility function can be used to convert the old snmp application config (pre snmp-4.0) to the new snmp agent config (as of snmp-4.0). For information about the old config (*OldConfig*) see the OTP R9C documentation. For information about the current agent config (*AgentConfig*), see the Configuring the application chapter of the SNMP user's guide. **restart\_worker() -\> void()**\ **restart\_worker(Agent) -\> void()**\ Types: Agent = pid() \| atom()\ Restart the worker process of a multi-threaded agent. This is a utility function, that can be useful when e.g. debugging instrumentation functions. **restart\_set\_worker() -\> void()**\ **restart\_set\_worker(Agent) -\> void()**\ Types: Agent = pid() \| atom()\ Restart the set worker process of a multi-threaded agent. This is a utility function, that can be useful when e.g. debugging instrumentation functions. **print\_mib\_info() -\> void()**\ Prints the content of all the (snmp) tables and variables for all mibs handled by the snmp agent. **print\_mib\_tables() -\> void()**\ Prints the content of all the (snmp) tables for all mibs handled by the snmp agent. **print\_mib\_variables() -\> void()**\ Prints the content of all the (snmp) variables for all mibs handled by the snmp agent. **verbosity(Ref,Verbosity) -\> void()**\ Types: Ref = pid() \| sub\_agents \| master\_agent \| net\_if \| mib\_server \| symbolic\_store \| note\_store \| local\_db\ Verbosity = verbosity() \| {subagents, verbosity()}\ verbosity() = silence \| info \| log \| debug \| trace \ Sets verbosity for the designated process. For the lowest verbosity *silence*, nothing is printed. The higher the verbosity, the more is printed. ## SEE ALSO [calendar(3erl)](/calendar/3erl.md), [erlc(1)](/erlc/1.md)