snmp_user_based_sm_mib(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

✨ NAME ✨

snmp_user_based_sm_mib — the Instrumentation Functions for SNMP-USER-BASED-SM-MIB, bestie 💅

💖 DESCRIPTION 💖

okay so picture this: the module snmp_user_based_sm_mib is the one that implements the instrumentation functions for the SNMP-USER-BASED-SM-MIB, plus it's also got the functions you use to configure the database. two jobs, zero complaints, she's a multitasker 💖

also important, no cap: authentication has been extended according to RFC 7860 (SNMP-USM-HMAC-SHA2-MIB). so that's a thing now. slay.

the configuration files? they're described in the SNMP User's Manual. go read it, it's giving required reading 📚

🦋 DATA TYPES 🦋

auth_key() :: snmp:octet_string().

the size/length of the list depends on the auth protocol, and yes you have to get this right or it simply will not work:

  • Size any for usmNoAuthProtocol
  • Size 16 for usmHMACMD5AuthProtocol
  • Size 20 for usmHMACSHAAuthProtocol
  • Size 28 for usmHMAC128SHA224AuthProtocol
  • Size 32 for usmHMAC192SHA256AuthProtocol
  • Size 48 for usmHMAC256SHA384AuthProtocol
  • Size 64 for usmHMAC384SHA512AuthProtocol

auth_protocol()

auth_protocol() ::
          usmNoAuthProtocol | usmHMACMD5AuthProtocol |
          usmHMACSHAAuthProtocol | usmHMAC128SHA224AuthProtocol |
          usmHMAC192SH256AuthProtocol | usmHMAC256SHA384AuthProtocol |
          usmHMAC384SHA512AuthProtocol.

NOTE: "An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be authenticated, and if so, the type of authentication protocol which is used."

NOTE: some of the entries of this type are actually defined by the SNMP-USM-HMAC-SHA2-MIB mib. plot twist 🫶

it's an AutonomousType btw.

clone_from() :: zeroDotZero | snmp:row_pointer().

NOTE: "A pointer to another conceptual row in this usmUserTable. The user in this other conceptual row is called the clone-from user."

it's a RowPointer ✨

key_change() :: snmp:octet_string().

NOTE: "Every definition of an object with this syntax must identify a protocol P, a secret key K, and a hash algorithm H that produces output of L octets."

OCTET STRING 🎀

name() :: snmp_framework_mib:admin_string().

NOTE: "A human readable string representing the name of the user. This is the (User-based Security) Model dependent security ID."

SnmpAdminString (SIZE(1..32)) — yes the 1..32 matters, don't get cute with it 💀

priv_key() :: snmp:octet_string().

the size/length of the list depends on the priv protocol:

  • Size any for usmNoPrivProtocol
  • Size 16 for usmDESPrivProtocol
  • Size 16 for usmAesCfb128Protocol

priv_protocol() ::

usmNoPrivProtocol | usmDESPrivProtocol | usmAesCfb128Protocol.

NOTE: "An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be protected from disclosure, and if so, the type of privacy protocol which is used."

NOTE: some of the entries of this tyype are actually defined by the SNMP-USM-AES-MIB mib. (yes that typo is the original's, we keep it, it's iconic now)

it's an AutonomousType 💜

public() :: string().

OCTET STRING (SIZE(0..32)) 🌈

usm_entry() ::

usm_entry() ::
          {EngineID :: snmp_framework_mib:engine_id(),
           UserName :: name(),
           SecName :: snmp_framework_mib:admin_string(),
           Clone :: clone_from(),
           AuthP :: auth_protocol(),
           AuthKeyC :: key_change(),
           OwnAuthKeyC :: key_change(),
           PrivP :: priv_protocol(),
           PrivKeyC :: key_change(),
           OwnPrivKeyC :: key_change(),
           Public :: public(),
           AuthKey :: auth_key(),
           PrivKey :: priv_key()}.

look at all those fields, she's got range 👑

🎀 FUNCTIONS 🎀

add_user(EngineID, Name, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey) -> {ok, Key} | {error, Reason}

when
    EngineID :: snmp_framework_mib:engine_id(),
    Name :: name(),
    SecName :: snmp_framework_mib:admin_string(),
    Clone :: clone_from(),
    AuthP :: auth_protocol(),
    AuthKeyC :: key_change(),
    OwnAuthKeyC :: key_change(),
    PrivP :: priv_protocol(),
    PrivKeyC :: key_change(),
    OwnPrivKeyC :: key_change(),
    Public :: public(),
    AuthKey :: auth_key(),
    PrivKey :: priv_key(),
    Key :: term(),
    Reason :: term().

adds a USM security data (user) to the agent config. it's the exact equivalent of writing one line in the usm.conf file. one function call, one line, same vibe fr fr ✨

configure(ConfDir) -> snmp:void() when ConfDir :: string()

this one gets called from the supervisor at system start-up. main character entrance, basically.

it inserts all the data in the configuration files into the database and destroys all old rows with StorageType volatile. the rows created from the configuration file will have StorageType nonVolatile.

all snmp counters are set to zero. fresh start, clean slate, we love to see it 💅

if an error is found in the configuration file, it gets reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error. so yeah, that's the fail state, know it, respect it 😭

ConfDir is a string which points to the directory where the configuration files are found.

the configuration file read is: usm.conf. 🌸

delete_user(Key) -> ok | {error, Reason}

when Key :: term(), Reason :: term().

deletes a USM security data (user) from the agent config. bye bestie, we'll miss you 🦋

reconfigure(ConfDir) -> snmp:void() when ConfDir :: string()

inserts all the data in the configuration files into the database and destroys all old data — and yes, that includes the rows with StorageType nonVolatile. she's thorough, no mercy 💀

so the rows created from the configuration file will have StorageType nonVolatile.

thus, the data in the SNMP-USER-BASED-SM-MIB, after this function has been called, is the data from the configuration files. periodt.

all snmp counters are set to zero. again. it's a whole reset.

if an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

the configuration file read is: usm.conf. same file, different energy 🫶

okay that's the whole page, go forth and configure your USM users responsibly. mwah 💖

this little love letter was brought to you by Ericsson AB, running on snmp 5.20.5, and it lives at snmp_user_based_sm_mib(3). bye bestie, stay authenticated ✨💅🎀

📦 where this page comes from