ct_snmp(3)

✨ NAME ✨

okay so ct_snmp — it's the Common Test user interface module for the SNMP application 💅 (this is an Erlang module definition btw, just so we're clear, bestie 🫶)

---

🌸 DESCRIPTION 🌸

so like, the whole point of this module is to make SNMP configuration so much less of a chore for whoever's writing the test cases. Most test cases can just vibe with the default values for the common operations and then — boom — no SNMP configuration files even need to be supplied. Iconic. ✨

But when you do need to change particular configuration parameters, you can pass a subset of the relevant SNMP configuration files to ct_snmp through Common Test configuration files. And for the extra-specialized configuration parameters? Just drop a simple SNMP configuration file in the test suite data directory. Easy. 🎀

To keep your test suite simple, Common Test keeps track of some of the SNMP manager information. That way your test suite doesn't have to juggle as many input parameters as it would if it had to interface with the OTP SNMP manager directly. Less work, same slay. 👑

🧚 Configurable SNMP Manager and Agent Parameters 🧚

💜 Manager configuration 💜

• {start_manager, boolean()} — optional. Default is true.
• {users, [{user_name(), [call_back_module(), user_data()]}]} — optional.
• {usm_users, [{usm_user_name(), [usm_config()]}]} — optional. SNMPv3 only, bestie, don't forget.
• {managed_agents,[{agent_name(), [user_name(), agent_ip(), agent_port(), [agent_config()]]}]} — managed_agents is optional.
• {max_msg_size, integer()} — optional. Default is 484.
• {mgr_port, integer()} — optional. Default is 5000.
• {engine _id, string()} — optional. Default is "mgrEngine".

🦋 Agent configuration 🦋

• {start_agent, boolean()} — optional. Default is false.
• {agent_sysname, string()} — optional. Default is "ct_test".
• {agent_manager_ip, manager_ip()} — optional. Default is localhost.
• {agent_vsns, list()} — optional. Default is [v2].
• {agent_trap_udp, integer()} — optional. Default is 5000.
• {agent_udp, integer()} — optional. Default is 4000.
• {agent_notify_type, atom()} — optional. Default is trap.
• {agent_sec_type, sec_type()} — optional. Default is none.
• {agent_passwd, string()} — optional. Default is "".
• {agent_engine_id, string()} — optional. Default is "agentEngine".
• {agent_max_msg_size, string()} — optional. Default is 484.

---

k so the next batch of parameters? They represent the SNMP configuration files context.conf, standard.conf, community.conf, vacm.conf, usm.conf, notify.conf, target_addr.conf, and target_params.conf — and heads up 👀, all values in agent.conf can be modified by the parameters listed above. Every one of these configuration files has default values set by the SNMP application. You can override those values by supplying either a list of valid configuration values, or a file that lives in the test suites data directory — and that file can produce a list of valid configuration values if you apply the function file:consult/1 to it. cute, right? 💖

• {agent_contexts, [term()] | {data_dir_file, rel_path()}} — optional.
• {agent_community, [term()] | {data_dir_file, rel_path()}} — optional.
• {agent_sysinfo, [term()] | {data_dir_file, rel_path()}} — optional.
• {agent_vacm, [term()] | {data_dir_file, rel_path()}} — optional.
• {agent_usm, [term()] | {data_dir_file, rel_path()}} — optional.
• {agent_notify_def, [term()] | {data_dir_file, rel_path()}} — optional.
• {agent_target_address_def, [term()] | {data_dir_file, rel_path()}} — optional.
• {agent_target_param_def, [term()] | {data_dir_file, rel_path()}} — optional.

---

okay, now the parameter MgrAgentConfName in the functions — that's a name you allocate in your test suite using a require statement. example time (where MgrAgentConfName = snmp_mgr_agent):

suite() -> [{require, snmp_mgr_agent, snmp}].

or

ct:require(snmp_mgr_agent, snmp).

⚠️ notice that USM users are needed for SNMPv3 configuration, and they are not to be confused with users. two different besties, two different vibes. don't mix them up 💀

SNMP traps, inform, and report messages are handled by the user callback module. for the deets, see the SNMP application. 🍓

It is recommended to use the .hrl files created by the Erlang/OTP MIB compiler to define the Object Identifiers (OIDs). for example, to get the Erlang node name from erlNodeTable in the OTP-MIB:

Oid = ?erlNodeEntry ++ [?erlNodeName, 1]

---

Furthermore (love that word ✨), values can be set for SNMP application configuration parameters, config, server, net_if, and so on — for the full list of valid parameters and types, see the User's Guide for the SNMP application. You do this by defining a configuration data variable on the following form:

{snmp_app, [{manager, [snmp_app_manager_params()]},
            {agent, [snmp_app_agent_params()]}]}.

A name for the data must be allocated in the suite using require (peep the example above 👆). Pass this name as argument SnmpAppConfName to ct_snmp:start/3. And here's the tea: ct_snmp specifies default values for some SNMP application configuration parameters (such as {verbosity,trace} for parameter config). This set of defaults gets merged with the parameters specified by the user — and the user values override the ct_snmp defaults. user stays winning, periodt. 👑

---

💫 DATA TYPES 💫

• agent_config() :: {Item :: term(), Value :: term()}.
• agent_ip() :: ip().
• agent_name() :: atom().
• agent_port() :: integer().
• call_back_module() :: atom().
• error_index() :: integer().
• error_status() :: noError | atom().
• ip() :: string() | {integer(), integer(), integer(), integer()}.
• manager_ip() :: ip().
• oid() :: [byte()].
• oids() :: [oid()].
• rel_path() :: string().
• sec_type() :: none | minimum | semi.
• snmp_app_agent_params() :: term().
• snmp_app_manager_params() :: term().
• snmpreply() :: {error_status(), error_index(), varbinds()}.
• user_data() :: term().
• user_name() :: atom().
• usm_config() :: {Item :: term(), Value :: term()}.
• usm_user_name() :: string().
• value_type() :: o | i | u | g | s.
• var_and_val() :: {oid(), value_type(), term()}.
• varbind() :: term().
• varbinds() :: [varbind()].
• varsandvals() :: [var_and_val()].

These data types are described in the documentation for the SNMP application 🫶📚

---

✨ FUNCTIONS ✨

Bestie, this is the whole function roster. Every single one, no crumbs left behind. 💅

---

get_next_values 🦋

get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
                         when
                             Agent :: agent_name(),
                             Oids :: oids(),
                             MgrAgentConfName :: atom(),
                             SnmpReply :: snmpreply().

Slides a synchronous SNMP get next request into the group chat. It's giving "next OID please, bestie" energy. ✨

get_values 🌸

get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
                    when
                        Agent :: agent_name(),
                        Oids :: oids(),
                        MgrAgentConfName :: atom(),
                        SnmpReply :: snmpreply().

Issues a synchronous SNMP get request. Classic "hand over these OID values" move. No cap.

load_mibs 💖

load_mibs(Mibs) -> ok | {error, Reason}
                   when
                       Mibs :: [MibName],
                       MibName :: string(),
                       Reason ::
                           {'load aborted at', MibName, InternalReason},
                       InternalReason :: already_loaded | term().

Loads the MIBs into the agent called snmp_master_agent. If it's already loaded, it can throw already_loaded back at you. Rude but valid. 😭

register_agents 🫶

register_agents(MgrAgentConfName, ManagedAgents) ->
                         ok | {error, Reason}
                         when
                             MgrAgentConfName :: atom(),
                             ManagedAgents ::
                                 [{AgentName,
                                   [Uid | AgentIp | AgentUdpPort |
                                    AgentConf]}],
                             AgentName :: agent_name(),
                             Uid :: snmpm:user_id(),
                             AgentIp :: agent_ip(),
                             AgentUdpPort :: inet:port_number(),
                             AgentConf :: [agent_config()],
                             Reason :: term().

Explicitly instructs the manager to handle this agent, like a very direct "you're on the roster now" text. Corresponds to making an entry in agents.conf.

This function tries to register the specified managed agents, without checking if any of them exist. To change a registered managed agent, the agent must first be unregistered. No sneaky edits, okay? 🙈

register_users 💜

register_users(MgrAgentConfName, Users) -> ok | {error, Reason}
                        when
                            MgrAgentConfName :: atom(),
                            Users :: [{Id, [Module | Data]}],
                            Id :: snmpm:user_id(),
                            Module :: user_name(),
                            Data :: user_data(),
                            Reason :: term().

Registers the manager entity (=user) responsible for specific agent(s). Corresponds to making an entry in users.conf.

Same no-checking energy: it tries to register the specified users without checking if any of them exist. To change a registered user, the user must first be unregistered. Periodt. 💅

register_usm_users 🧚

register_usm_users(MgrAgentConfName, UsmUsers) ->
                            ok | {error, Reason}
                            when
                                MgrAgentConfName :: atom(),
                                UsmUsers :: [{UsmUserName, UsmConfig}],
                                UsmUserName :: usm_user_name(),
                                UsmConfig :: [usm_config()],
                                Reason :: term().

Explicitly instructs the manager to handle this USM user. Corresponds to making an entry in usm.conf.

This function tries to register the specified users, without checking if any of them exist. To change a registered user, the user must first be unregistered. We love a consistent rule. 💜

set_info ⭐

set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]
                  when
                      Config :: proplists:proplist(),
                      Agent :: agent_name(),
                      OldVarsAndVals :: varsandvals(),
                      NewVarsAndVals :: varsandvals().

Returns a list of all successful set requests performed in the test case in reverse order. The list contains the involved user and agent, the value before set, and the new value.

This is intended to simplify the cleanup in function end_per_testcase, that is, the undoing of the set requests and their possible side-effects. Very "let me put that back where I found it" of it. ✨

set_values 🔥

set_values(Agent, VarsAndVals, MgrAgentConfName, Config) ->
                    SnmpReply
                    when
                        Agent :: agent_name(),
                        VarsAndVals :: varsandvals(),
                        MgrAgentConfName :: atom(),
                        Config :: proplists:proplist(),
                        SnmpReply :: snmpreply().

Issues a synchronous SNMP set request. Set it and forget it? No bestie, it's synchronous. 👑

start 🌈

start(Config, MgrAgentConfName, SnmpAppConfName) ->
               ok | {error, Reason}
               when
                   Config :: proplists:proplist(),
                   MgrAgentConfName :: atom(),
                   SnmpAppConfName :: atom(),
                   Reason :: term().

Starts an SNMP manager and/or agent. In the manager case, registrations of users and agents, as specified by the configuration MgrAgentConfName, are performed. When using SNMPv3, called USM users are also registered. Users, usm_users, and managed agents can also be registered later using ct_snmp:register_users/2, ct_snmp:register_agents/2, and ct_snmp:register_usm_users/2.

The agent started is called snmp_master_agent. Use ct_snmp:load_mibs/1 to load MIBs into the agent.

With SnmpAppConfName SNMP applications can be configured with parameters config, mibs, net_if, and so on. The values are merged with (and possibly override) default values set by ct_snmp. Main character setup energy. 💖

stop 🧹

stop(Config) -> ok when Config :: proplists:proplist().

Stops the SNMP manager and/or agent, and removes all files created. Bye bye, cleanup era. 🎀

unload_mibs 🍓

unload_mibs(Mibs) -> ok | {error, Reason}
                     when
                         Mibs :: [MibName],
                         MibName :: string(),
                         Reason ::
                             {'unload aborted at', MibName,
                              InternalReason},
                         InternalReason :: not_loaded | term().

Unloads the MIBs from agent snmp_master_agent. Like taking them out of the snack basket. If they weren't loaded, not_loaded can show up. 🙈

unregister_agents/1 🌸

unregister_agents(MgrAgentConfName) -> ok
                           when MgrAgentConfName :: atom().

Unregisters all managed agents. Clean slate, bestie.

unregister_agents/2 🌸

unregister_agents(MgrAgentConfName, ManagedAgents) -> ok
                           when
                               MgrAgentConfName :: atom(),
                               ManagedAgents :: [agent_name()].

Unregisters the specified managed agents. You pick, they go. 💅

unregister_users/1 🦋

unregister_users(MgrAgentConfName) -> ok
                          when MgrAgentConfName :: atom().

Unregisters all users. Bye besties. 🫶

unregister_users/2 🦋

unregister_users(MgrAgentConfName, Users) -> ok
                          when
                              MgrAgentConfName :: atom(),
                              Users :: [snmpm:user_id()].

Unregisters the specified users. Selective goodbye energy. ✨

unregister_usm_users/1 💜

unregister_usm_users(MgrAgentConfName) -> ok
                              when MgrAgentConfName :: atom().

Unregisters all USM users. Whole squad out. 💜

unregister_usm_users/2 💜

unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok
                              when
                                  MgrAgentConfName :: atom(),
                                  UsmUsers :: [usm_user_name()].

Unregisters the specified USM users. You choose, they unregister. Posh. 🎀

---

That's the entire FUNCTIONS section, bestie. Page footer cuteness: Ericsson AB made it, it's from common_test 1.31.1, and this page is ct_snmp(3). Stay slay. 💖✨