snmpm_user(3erl)

💖 NAME 💖

Bestie, welcome to snmpm_user — an Erlang module definition and literally the behaviour module for the SNMP manager user. This page is snmpm_user(3erl), and it’s giving manager-user behaviour main character energy. 💅✨

✨ DESCRIPTION ✨

Okay so this module defines the behaviour of the manager user. A snmpm_user compliant module must export these functions, no cap:

• handle_error/3
• handle_agent/4
• handle_pdu/4
• handle_trap/3
• handle_inform/3
• handle_report/3
• handle_invalid_result/2

The semantics of them and their exact signatures are explained below. 🫶

Some callbacks have no defined return value (void()) — they can of course return anything. But the functions that do have specified return value(s) must adhere to this. Also: none of the functions can use exit or throw to return. Periodt.

One special-case tea: if the manager isn’t configured to use any particular transport domain, the behaviour handle_agent/4 will — for backwards copmpatibility reasons, keeping the original spelling because lore — be called with the old IpAddr and PortNumber arguments. 💅

🦋 DATA TYPES 🦋

Here are the type definitions, literal and exact — type code is not the place to freestyle:

snmp_gen_info() = {ErrorStatus :: atom(),
                   ErrorIndex  :: pos_integer(),
                   Varbinds    :: [snmp:varbind()]}
snmp_v1_trap_info() :: {Enteprise :: snmp:oid(),
                        Generic   :: integer(),
                        Spec      :: integer(),
                        Timestamp :: integer(),
                        Varbinds  :: [snmp:varbind()]}

👑 EXPORTS 👑

Callback roll call! Each one gets its signature, its types, and the full tea. Don’t skip the “boring” bits — they’re load-bearing. 🔥

✨ handle_error(ReqId, Reason, UserData) -> void() ✨

Types:

ReqId = netif | integer()
Reason = {unexpected_pdu, SnmpInfo} | {invalid_sec_info,
SecInfo, SnmpInfo} | {empty_message, Addr, Port} | term()
SnmpInfo = snmp_gen_info()
SecInfo = term()
Addr = ip_address()
Port = integer()
UserData = term()

This function is called when the manager needs to communicate an “asynchronous” error to the user: e.g. failure to send an asynchronous message (i.e. encoding error), a received message was discarded due to security error, the manager failed to generate a response message to a received inform-request, or when receiving an unexpected PDU from an agent (could be an expired async request). 😭

If ReqId is less then 0, it means that this information was not available to the manager (that info was never retrieved before the message was discarded).

For SnmpInfo, see handle_agent below.

⚠️ Special case alert: when the value of ReqId has the value of the atom netif, that means the NetIF process has suffered a “fatal” error and been restarted. With possible loss of traffic! This is not a cute little glitch. 💀

✨ handle_agent(Domain, Addr, Type, SnmpInfo, UserData) -> Reply ✨

Types:

Domain = transportDomainUdpIpv4 | transportDomainUdpIpv6
Addr = {inet:ip_address(), inet:port_number()}
Type = pdu | trap | report | inform
SnmpInfo = SnmpPduInfo | SnmpTrapInfo | SnmpReportInfo |
SnmpInformInfo
SnmpPduInfo = snmp_gen_info()
SnmpTrapInfo = snmp_v1_trap_info()
SnmpReportInfo = snmp_gen_info()
SnmpInformInfo = snmp_gen_info()
UserData = term()
Reply = ignore | {register, UserId, TargetName, AgentConfig}
UserId = term()
TargetName = target_name()
AgentConfig = [agent_config()]

This function is called when a message is received from an unknown agent. Note that this will always be the default user that is called. For more info about the agent_config(), see register_agent.

The arguments Type and SnmpInfo relate in the following way:

• pdu — SnmpPduInfo (see handle_pdu for more info).
• trap — SnmpTrapInfo (see handle_trap for more info).
• report — SnmpReportInfo (see handle_report for more info).
• inform — SnmpInformInfo (see handle_inform for more info).

The only user which would return {register, UserId, TargetName, AgentConfig} is the default user. That’s the rule, bestie. 🫶

✨ handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> void() ✨

Types:

TargetName = target_name()
ReqId = term()
SnmpPduInfo = snmp_gen_info()
UserData = term()

Handle the reply to an asynchronous request, such as async_get, async_get_next or async_set.

It could also be a late reply to a synchronous request. We love a delayed plot twist.

ReqId is returned by the asynchronous request function.

✨ handle_trap(TargetName, SnmpTrapInfo, UserData) -> Reply ✨

Types:

TargetName = TargetName2 = target_name()
SnmpTrapInfo = snmp_v1_trap_info() | snmp_gen_info()
UserData = term()
Reply = ignore | unregister | {register, UserId, TargetName2,
AgentConfig}
UserId = term()
AgentConfig = [agent_config()]

Handle a trap/notification message from an agent. 🎀

For more info about the agent_config(), see register_agent.

The only user which would return {register, UserId, TargetName2, agent_info()} is the default user.

✨ handle_inform(TargetName, SnmpInformInfo, UserData) -> Reply ✨

Types:

TargetName = TargetName2 = target_name()
SnmpInformInfo = snmp_gen_info()
UserData = term()
Reply = ignore | no_reply | unregister | {register, UserId,
TargetName2, AgentConfig}
UserId = term()
AgentConfig = [agent_config()]

Handle a inform message. 💌

For more info about the agent_config(), see register_agent.

The only user which would return {register, UserId, TargetName2, AgentConfig} is the default user.

If the inform request behaviour configuration option is set to user or {user, integer()}, the response (acknowledgment) to this inform-request will be sent when this function returns. Timing is everything. ⏱️

✨ handle_report(TargetName, SnmpReportInfo, UserData) -> Reply ✨

Types:

TargetName = TargetName2 = target_name()
Addr = ip_address()
Port = integer()
SnmpReportInfo = snmp_gen_info()
UserData = term()
Reply = ignore | unregister | {register, UserId, TargetName2,
AgentConfig}
UserId = term()
AgentConfig = [agent_config()]

Handle a report message. 📣

For more info about the agent_config(), see register_agent.

The only user which would return {register, UserId, TargetName2, AgentConfig} is the default user.

✨ handle_invalid_result(IN, OUT) -> void() ✨

Types:

IN = {Func, Args}
Func = atom()
Args = list()
OUT = {crash, CrashInfo} | {result, InvalidResult}
CrashInfo = {ErrorType, Error, Stacktrace}
ErrorType = atom()
Error = term()
Stacktrace = list()
InvalidResult = term()

If any of the other callback functions crashes (exit, throw or a plain crash) or return an invalid result (if a valid return has been specified), this function is called. The purpose is to allow the user handle this error (for instance to issue an error report). 🚨

IN reprecents the function called (and its arguments). OUT represents the unexpected/invalid result.

---

xoxo, Ericsson AB 💖 — that footer energy is snmp 5.13.5 on snmpm_user(3erl), with the date exactly as the footer gives it (which is to say, not printed). Stay iconic, bestie. 🎀🦋 No cap, read the types.