snmpa(3erl)

📦
version 25.3.2.8 · 4 versions
, in ubuntu noble

💅 snmpa 💅

okay bestie, this is snmpa, straight from the Erlang Module Definition — literally the interface functions to the SNMP toolkit agent. group-chat voice on, facts intact. 🫶

🌸 NAME 🌸

snmpa — Interface Functions to the SNMP toolkit agent 💖

🦋 DESCRIPTION 🦋

The module snmpa contains interface functions to the SNMP agent. That's the whole vibe. no cap, it's the agent-side toolkit API. ✨

🎀 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. iconic little byte list.

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. slay.

💜 del_agent_caps(SysORIndex) -> void() 💜

Types:

SysORIndex = integer()

This function can be used to delete an AGENT-CAPABILITY statement from 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.

heads up, bestie: 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.

heads up again: 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. no cap, it's a one-at-a-time situation.

🔍 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()]

…and it hands back every alias-name the agent knows about — the whole list, nothing held back 💖

🎀 which_tables() — the table tour

which_tables() -> Result

Types:

Result = [atom()]

Gives you every table the agent knows about. Every. Single. One. ✨

🚀 which_transports() — where the packets actually live

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

Spills the tea on all the configured transports 🫶 Heads up that an entry can come back as plain {TDomain, TAddress} or with a Kind riding along — req_responder or trap_sender — so you know exactly what that transport's job is 💅

🌸 which_variables() — the variable roll call

which_variables() -> Result

Types:

Result = [atom()]

Retrieves every variable the agent knows about. Your faves, all in one list 😌

🦋 which_notifications() — traps AND notifications, bestie

which_notifications() -> Result

Types:

Result = [{Name, MibName, Info}]
Name = atom()
MibName = atom()
Info = term()

Retrieves all the notifications (and traps) the agent knows about — each one tagged with its Name, the MibName it came from, and an Info term 👑

💅 log_to_txt() — audit log, but make it readable

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()}

Takes an Audit Trail Log and converts it into a readable text file 😌 Basically glow-up for raw log data ✨

Defaults, because they matter: OutFile defaults to "./snmpa_log.txt", LogName defaults to "snmpa_log", and LogFile defaults to "snmpa.log" 🎀

The Block option says whether the log should be blocked during conversion. Lowkey useful when you're converting big logs — otherwise the log could wrap mid-conversion and that's giving chaos 😭. It defaults to true.

See snmp:log_to_txt for more info, bestie 📖

🌈 log_to_io() — same energy, but straight to stdio

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 into a readable format and prints it right on stdio — no file, just vibes 🫶 LogName defaults to "snmpa_log" and LogFile defaults to "snmpa.log".

Same Block situation as above: it decides whether the log gets blocked during conversion, which is handy for chunky logs (otherwise the log could wrap while you're converting). Defaults to true ✨

See snmp:log_to_io for more info 💖

🔥 change_log_size() — bigger log, more room

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 has to be configured to use the audit trail log function first — no shortcuts. For the whole story on changing log size, go read disk_log(3erl) in the Kernel Reference Manual, iykyk 📚

The change is permanent, as long as the log isn't deleted. Meaning: the log size is remembered across reboots. It's giving main character energy that never forgets 👑

💜 set_log_type() — swap the runtime log type

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 ✨

Heads up: this has no effect on the application configuration as defined by configuration files — so a node restart will revert the config to whatever's in those files 😭

This function is primarily useful in testing/debugging scenarios. Debug queen behaviour only 🙈

🧚 mib_of() — which MIB owns this OID?

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 that corresponds to the Oid 🌸 Format rules, don't skip 'em: if it's a variable, the Oid must be <Oid for var>.0, and if it's a table, the Oid must be <table>.<entry>.<col>.<any> 💅

🍓 me_of() — gimme the actual mib entry

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 that corresponds to the Oid 🎀 Same OID rules as mib_of(): variable → Oid must be <Oid for var>.0; table → Oid must be <table>.<entry>.<col>.<any> ✨

🌟 invalidate_mibs_cache() — nuke the cache

invalidate_mibs_cache() -> void()
invalidate_mibs_cache(Agent) -> void()

Types:

Agent = pid() | atom()

Invalidates the mib server cache 💀

The entire contents of the cache will be deleted. All of it. Gone. No cap 😭

🫶 enable_mibs_cache() — cache is so back

enable_mibs_cache() -> void()
enable_mibs_cache(Agent) -> void()

Types:

Agent = pid() | atom()

Enables the mib server cache ✨ We love a comeback story.

🙈 disable_mibs_cache() — cache is cancelled

disable_mibs_cache() -> void()
disable_mibs_cache(Agent) -> void()

Types:

Agent = pid() | atom()

Disables the mib server cache. Not me turning the cache off 💅

⭐ which_mibs_cache_size() — how big is the cache rn

which_mibs_cache_size() -> void()
which_mibs_cache_size(Agent) -> void()

Types:

Agent = pid() | atom()

Retrieves the size of the mib server cache 🎀 Numbers, bestie, we love numbers.

🧹 gc_mibs_cache() — manual garbage collection girlie

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 — and yes you can do this regardless of the value of the autogc option 🔥 The NumElementsGCed value tells you how many elements actually got removed from the cache ✨

🌸 enable_mibs_cache_autogc() — let it clean itself

enable_mibs_cache_autogc() -> void()
enable_mibs_cache_autogc(Agent) -> void()

Types:

Agent = pid() | atom()

Enables automatic gc of the mib server cache. Set it and forget it 😌

🌈 disable_mibs_cache_autogc() — I'll clean it myself

disable_mibs_cache_autogc() -> void()
disable_mibs_cache_autogc(Agent) -> void()

Types:

Agent = pid() | atom()

Disables automatic gc of the mib server cache. You are the gc now 👑

🦋 update_mibs_cache_age() — new age, who dis

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()

Changes the mib server cache age property 🎀

💜 update_mibs_cache_gclimit() — set that gc ceiling

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()

Changes the mib server cache gclimit property ✨ (infinity counts as a valid value, so go off.)

🎀 register_notification_filter() — filter the notifications

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 gets passed on to the filter whenever the functions of the behaviour are called — so it's your little payload bestie ✨

🧚 unregister_notification_filter() — bye filter

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()

Unregisters a notification filter 🌸 It's giving closure.

⭐ which_notification_filter() — who's filtering rn

which_notification_filter() -> Filters
which_notification_filter(Agent) -> Filters

Types:

Agent = pid() | atom()
Filters = [filter_id()]
filter_id() = term()

Lists all notification filters in an agent 👑 Collector's edition.

💖 set_request_limit — the literal limit-setter

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()

okay so this one changes the request limit. That's it. That's the whole vibe. 💅

Note bestie: 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. So don't think you can set it and forget it — the config files are giving main character energy on restart. 😭

This function is primarily useful in load regulation scenarios. Slay for load regulation, honestly. ⚖️✨

🦋 register_subagent — sub-agent adoption era

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. Cute, right? But listen: it is easy to make mistakes when registering sub-agents, and this activity should be done carefully. No cap. 🫶

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).

In that situation, SA2 will not get requests starting with object identifier [1,2,3] since SA1 does not. And that's the tea. 🍵💀

🌸 unregister_subagent — breaking up with a sub-agent

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. So it's giving "clean break, no lingering situationship" energy. 💔✨

🎀 send_notification2 — the deluxe notification sender

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. Basically: notification goes out, and the MIB table knows where it's supposed to land. 💌

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. Silence. Peace. 🧘
  • 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 described 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 — the classic notification sender

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. The MIB table is basically the group chat admin here. 👑

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. No updates, no drama. 🙈
  • 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 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 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 described above.

Address is a management target address and Addresses is a list of management target addresses. They are defined as follows:

…and the type block wraps up like this, bestie:

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 info about the notification delivery gets delivered to the receiver through the callback functions defined by the snmpa_notification_delivery_info_receiver behaviour, according to what’s inside 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. No cap.

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, bestie: 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 overloads, aka the “go find the manager” era

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. Periodt.

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. That’s the caveat, bestie — highkey do not ignore it. 😭

🛠️ 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). It’s giving “glow-up but for config files.” 💅

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()

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. Slay, debug era. 🔥

🔁 restart_set_worker() -> void() / restart_set_worker(Agent) -> void()

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. Same utility energy, different worker. 🎀

Prints the content of all the (snmp) tables and variables for all mibs handled by the snmp agent. It’s literally a whole MIB info dump, bestie. 🌸

Prints the content of all the (snmp) tables for all mibs handled by the snmp agent.

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. So if you want less yapping, choose silence; if you want the full group-chat transcript, go higher. 🙈

👀 SEE ALSO 👀

That’s the whole page, bestie! 💖 Footer tea: Ericsson AB, snmp 5.13.5, snmpa(3erl) — source/version/page realness, no cap. 🫶✨

📦 where this page comes from