snmpm_user(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💖 NAME 💖

snmpm_user — the behaviour module for the SNMP manager user, aka the glow-up your manager needs. It lives in the Erlang module definition manual, section 3, and yes she's iconic. 👑

🎀 DESCRIPTION 🎀

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

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

What they actually mean and their exact signatures? All explained below, keep scrolling. 🫶

Now, some of these functions have no defined return value (void()) — those ones can literally return anything, go feral. But the functions that do have specified return value(s) must adhere to them, no cap. And listen: none of the functions can use exit or throw to return. Not a vibe. 💀

One more thing: if the manager is not configured to use any particular transport domain, then handle_agent/5 will — for backwards copmpatibility reasons (their typo, not mine, we don't gatekeep) — be called with the old IpAddr and PortNumber arguments. Old-school, but make it work. ✨

🦋 DATA TYPES 🦋

ip_address() :: inet:ip_address().

port_number() :: inet:port_number().

snmp_gen_info() ::
          {ErrorStatus :: atom(),
           ErrorIndex :: pos_integer(),
           Varbinds :: [snmp:varbind()]}.

General error information — and no, it does not have to indicate an error. Chill. 💅

snmp_v1_trap_info() ::
          {Enteprise :: snmp:oid(),
           Generic :: integer(),
           Spec :: integer(),
           Timestamp :: integer(),
           Varbinds :: [snmp:varbind()]}.

Trap-related information. Trap girlie things. 🍓

🌈 CALLBACKS 🌈

✨ handle_agent(Domain, Address, Type, SnmpInfo, UserData) ✨

This one gets called when a message arrives from an unknown agent. Spooky. 👀

Note that this will always be the default user that is called. No exceptions, periodt.

For more info about the agent_config(), go peek at snmpm:register_agent/3.

The arguments Type and SnmpInfo are besties, they relate like this:

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

And the only user which would return {register, UserId, TargetName, AgentConfig} is the default user. Only them. Main character energy exclusively. 🌟

💖 handle_error(ReqId, Reason, UserData) 💖

This function is called when the manager needs to communicate an "asynchronous" error to the user, like:

  • 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 than 0, it means that this information was not available to the manager (that info was never retrieved before the message was discarded). It's giving "we lost the receipt". 😭

For SnmpInfo see handle_agent above. ⬆️

When Reason is {failed_processing_message, {securityError, SecurityError, Opts}}, the Opts proplist may contain a sec_data entry with USM security parameters from the received message. In particular, when SecurityError is usmStatsUnknownEngineIDs, the sec_data proplist contains msgAuthoritativeEngineID and msgUserName, which can be used for SNMPv3 USM EngineID discovery (RFC 3414, Section 4). Slay, security. 🔐

Note that there's a special case when the value of ReqId has the value of the atom netif. This means that the NetIF process has suffered a "fatal" error and been restarted. With possible loss of traffic! So like... be aware. 🙈

🌸 handle_inform(TargetName, SnmpInform, UserData) 🌸

Handle an inform message. You got mail, bestie. 💌

For more info about the agent_config(), see snmpm:register_agent/3.

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. So don't take forever, okay? ⏰

🎀 handle_invalid_result(In, Out) 🎀

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

IN represents the function called (and its arguments). OUT represents the unexpected/invalid result. Delulu in, delulu out, but at least you're notified. 💅

🦋 handle_pdu(TargetName, ReqId, SnmpResponse, UserData) 🦋

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. Late but present ✨ (we've all been there).

ReqId is returned by the asynchronous request function.

💜 handle_report(TargetName, SnmpReport, UserData) 💜

Handle a report message. Very "let me give you the tea" of it. ☕

For more info about the agent_config(), see snmpm:register_agent/3.

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

⭐ handle_trap(TargetName, SnmpTrapInfo, UserData) ⭐

Handle a trap/notification message from an agent. Caught in 4K. 📸

For more info about the agent_config(), see snmpm:register_agent/3.

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

and that's the whole page, bestie — you ate that 💅

Brought to you by Ericsson AB, from snmp 5.20.5 — the snmpm_user(3) page, no dates given but the vibes are timeless. 🫶✨🎀

📦 where this page comes from