.TH ct_snmp 3erl "common_test 1.26.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
ct_snmp \- Common Test user interface module for the SNMP application.
.SH DESCRIPTION
.LP
\fICommon Test\fR\& user interface module for the \fISNMP\fR\& application\&.
.LP
The purpose of this module is to simplify SNMP configuration for the test case writer\&. Many test cases can use default values for common operations and then no SNMP configuration files need to be supplied\&. When it is necessary to change particular configuration parameters, a subset of the relevant SNMP configuration files can be passed to \fIct_snmp\fR\& by \fICommon Test\fR\& configuration files\&. For more specialized configuration parameters, a simple SNMP configuration file can be placed in the test suite data directory\&. To simplify the test suite, \fICommon Test\fR\& keeps track of some of the SNMP manager information\&. This way the test suite does not have to handle as many input parameters as if it had to interface wthe OTP SNMP manager directly\&.
.LP
\fIConfigurable SNMP Manager and Agent Parameters:\fR\&
.LP
Manager configuration:
.RS 2
.TP 2
.B
\fI[{start_manager, boolean()}\fR\&:
Optional\&. Default is \fItrue\fR\&\&.
.TP 2
.B
\fI{users, [{user_name(), [call_back_module(), user_data()]}]}\fR\&:
Optional\&.
.TP 2
.B
\fI{usm_users, [{usm_user_name(), [usm_config()]}]}\fR\&:
Optional\&. SNMPv3 only\&.
.TP 2
.B
\fI{managed_agents,[{agent_name(), [user_name(), agent_ip(), agent_port(), [agent_config()]]}]}\fR\&:
\fImanaged_agents\fR\& is optional\&.
.TP 2
.B
\fI{max_msg_size, integer()}\fR\&:
Optional\&. Default is \fI484\fR\&\&.
.TP 2
.B
\fI{mgr_port, integer()}\fR\&:
Optional\&. Default is \fI5000\fR\&\&.
.TP 2
.B
\fI{engine _id, string()}\fR\&:
Optional\&. Default is \fI"mgrEngine"\fR\&\&.
.RE
.LP
Agent configuration:
.RS 2
.TP 2
.B
\fI{start_agent, boolean()}\fR\&:
Optional\&. Default is \fIfalse\fR\&\&.
.TP 2
.B
\fI{agent_sysname, string()}\fR\&:
Optional\&. Default is \fI"ct_test"\fR\&\&.
.TP 2
.B
\fI{agent_manager_ip, manager_ip()}\fR\&:
Optional\&. Default is \fIlocalhost\fR\&\&.
.TP 2
.B
\fI{agent_vsns, list()}\fR\&:
Optional\&. Default is \fI[v2]\fR\&\&.
.TP 2
.B
\fI{agent_trap_udp, integer()}\fR\&:
Optional\&. Default is \fI5000\fR\&\&.
.TP 2
.B
\fI{agent_udp, integer()}\fR\&:
Optional\&. Default is \fI4000\fR\&\&.
.TP 2
.B
\fI{agent_notify_type, atom()}\fR\&:
Optional\&. Default is \fItrap\fR\&\&.
.TP 2
.B
\fI{agent_sec_type, sec_type()}\fR\&:
Optional\&. Default is \fInone\fR\&\&.
.TP 2
.B
\fI{agent_passwd, string()}\fR\&:
Optional\&. Default is \fI""\fR\&\&.
.TP 2
.B
\fI{agent_engine_id, string()}\fR\&:
Optional\&. Default is \fI"agentEngine"\fR\&\&.
.TP 2
.B
\fI{agent_max_msg_size, string()}\fR\&:
Optional\&. Default is \fI484\fR\&\&.
.RE
.LP
The following parameters represents the SNMP configuration files \fIcontext\&.conf\fR\&, \fIstandard\&.conf\fR\&, \fIcommunity\&.conf\fR\&, \fIvacm\&.conf\fR\&, \fIusm\&.conf\fR\&, \fInotify\&.conf\fR\&, \fItarget_addr\&.conf\fR\&, and \fItarget_params\&.conf\fR\&\&. Notice that all values in \fIagent\&.conf\fR\& can be modified by the parameters listed above\&. All these configuration files have default values set by the \fISNMP\fR\& application\&. These values can be overridden by suppling a list of valid configuration values or a file located in the test suites data directory, which can produce a list of valid configuration values if you apply function \fIfile:consult/1\fR\& to the file\&.
.RS 2
.TP 2
.B
\fI{agent_contexts, [term()] | {data_dir_file, rel_path()}}\fR\&:
Optional\&.
.TP 2
.B
\fI{agent_community, [term()] | {data_dir_file, rel_path()}}\fR\&:
Optional\&.
.TP 2
.B
\fI{agent_sysinfo, [term()] | {data_dir_file, rel_path()}}\fR\&:
Optional\&.
.TP 2
.B
\fI{agent_vacm, [term()] | {data_dir_file, rel_path()}}\fR\&:
Optional\&.
.TP 2
.B
\fI{agent_usm, [term()] | {data_dir_file, rel_path()}}\fR\&:
Optional\&.
.TP 2
.B
\fI{agent_notify_def, [term()] | {data_dir_file, rel_path()}}\fR\&:
Optional\&.
.TP 2
.B
\fI{agent_target_address_def, [term()] | {data_dir_file, rel_path()}}\fR\&:
Optional\&.
.TP 2
.B
\fI{agent_target_param_def, [term()] | {data_dir_file, rel_path()}}\fR\&:
Optional\&.
.RE
.LP
Parameter \fIMgrAgentConfName\fR\& in the functions is to be a name you allocate in your test suite using a \fIrequire\fR\& statement\&. Example (where \fIMgrAgentConfName = snmp_mgr_agent\fR\&):
.LP
.nf

 suite() -> [{require, snmp_mgr_agent, snmp}].
.fi
.LP
or
.LP
.nf

 ct:require(snmp_mgr_agent, snmp).
.fi
.LP
Notice that USM users are needed for SNMPv3 configuration and are not to be confused with users\&.
.LP
SNMP traps, inform, and report messages are handled by the user callback module\&. For details, see the \fISNMP\fR\& application\&.
.LP
It is recommended to use the \fI\&.hrl\fR\& files created by the Erlang/OTP MIB compiler to define the Object Identifiers (OIDs)\&. For example, to get the Erlang node name from \fIerlNodeTable\fR\& in the OTP-MIB:
.LP
.nf

 Oid = ?erlNodeEntry ++ [?erlNodeName, 1]
.fi
.LP
Furthermore, values can be set for \fISNMP\fR\& application configuration parameters, \fIconfig\fR\&, \fIserver\fR\&, \fInet_if\fR\&, and so on (for a list of valid parameters and types, see the \fIUser\&'s Guide for the SNMP application\fR\&)\&. This is done by defining a configuration data variable on the following form:
.LP
.nf

 {snmp_app, [{manager, [snmp_app_manager_params()]},
             {agent, [snmp_app_agent_params()]}]}.
.fi
.LP
A name for the data must be allocated in the suite using \fIrequire\fR\& (see the example above)\&. Pass this name as argument \fISnmpAppConfName\fR\& to \fIct_snmp:start/3\fR\&\&. \fIct_snmp\fR\& specifies default values for some \fISNMP\fR\& application configuration parameters (such as \fI{verbosity,trace}\fR\& for parameter \fIconfig\fR\&)\&. This set of defaults is merged with the parameters specified by the user\&. The user values override \fIct_snmp\fR\& defaults\&.
.SH DATA TYPES
.nf

.B
agent_config() = {Item, Value}
.br
.fi
.nf

.B
agent_ip() = ip()
.br
.fi
.nf

.B
agent_name() = atom()
.br
.fi
.nf

.B
agent_port() = integer()
.br
.fi
.nf

.B
call_back_module() = atom()
.br
.fi
.nf

.B
error_index() = integer()
.br
.fi
.nf

.B
error_status() = noError | atom()
.br
.fi
.nf

.B
ip() = string() | {integer(), integer(), integer(), integer()}
.br
.fi
.nf

.B
manager_ip() = ip()
.br
.fi
.nf

.B
oid() = [byte()]
.br
.fi
.nf

.B
oids() = [oid()]
.br
.fi
.nf

.B
rel_path() = string()
.br
.fi
.nf

.B
sec_type() = none | minimum | semi
.br
.fi
.nf

.B
snmp_app_agent_params() = term()
.br
.fi
.nf

.B
snmp_app_manager_params() = term()
.br
.fi
.nf

.B
snmpreply() = {error_status(), error_index(), varbinds()}
.br
.fi
.nf

.B
user_data() = term()
.br
.fi
.nf

.B
user_name() = atom()
.br
.fi
.nf

.B
usm_config() = {Item, Value}
.br
.fi
.nf

.B
usm_user_name() = string()
.br
.fi
.nf

.B
value_type() = o(\&'OBJECT IDENTIFIER\&') | i(\&'INTEGER\&') | u(\&'Unsigned32\&') | g(\&'Unsigned32\&') | s(\&'OCTET STRING\&')
.br
.fi
.nf

.B
var_and_val() = {oid(), value_type(), value()}
.br
.fi
.nf

.B
varbind() = term()
.br
.fi
.nf

.B
varbinds() = [varbind()]
.br
.fi
.nf

.B
varsandvals() = [var_and_val()]
.br
.fi
.RS
.LP
These data types are described in the documentation for the \fISNMP\fR\& application\&.
.RE

.SH EXPORTS
.LP
.B
get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
.br
.RS
.LP
Types:

.RS 3
Agent = agent_name()
.br
Oids = oids()
.br
MgrAgentConfName = atom()
.br
SnmpReply = snmpreply()
.br
.RE
.RE
.RS
.LP
Issues a synchronous SNMP \fIget next\fR\& request\&.
.RE

.LP
.B
get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
.br
.RS
.LP
Types:

.RS 3
Agent = agent_name()
.br
Oids = oids()
.br
MgrAgentConfName = atom()
.br
SnmpReply = snmpreply()
.br
.RE
.RE
.RS
.LP
Issues a synchronous SNMP \fIget\fR\& request\&.
.RE

.LP
.B
load_mibs(Mibs) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Mibs = [MibName]
.br
MibName = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Loads the MIBs into agent \fIsnmp_master_agent\fR\&\&.
.RE

.LP
.B
register_agents(MgrAgentConfName, ManagedAgents) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
ManagedAgents = [agent()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Explicitly instructs the manager to handle this agent\&. Corresponds to making an entry in \fIagents\&.conf\fR\&\&.
.LP
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\&.
.RE

.LP
.B
register_users(MgrAgentConfName, Users) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
Users = [user()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Registers the manager entity (=user) responsible for specific agent(s)\&. Corresponds to making an entry in \fIusers\&.conf\fR\&\&.
.LP
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\&.
.RE

.LP
.B
register_usm_users(MgrAgentConfName, UsmUsers) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
UsmUsers = [usm_user()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Explicitly instructs the manager to handle this USM user\&. Corresponds to making an entry in \fIusm\&.conf\fR\&\&.
.LP
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\&.
.RE

.LP
.B
set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]
.br
.RS
.LP
Types:

.RS 3
Config = [{Key, Value}]
.br
Agent = agent_name()
.br
OldVarsAndVals = varsandvals()
.br
NewVarsAndVals = varsandvals()
.br
.RE
.RE
.RS
.LP
Returns a list of all successful \fIset\fR\& requests performed in the test case in reverse order\&. The list contains the involved user and agent, the value before \fIset\fR\&, and the new value\&. This is intended to simplify the cleanup in function \fIend_per_testcase\fR\&, that is, the undoing of the \fIset\fR\& requests and their possible side-effects\&.
.RE

.LP
.B
set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply
.br
.RS
.LP
Types:

.RS 3
Agent = agent_name()
.br
Oids = oids()
.br
MgrAgentConfName = atom()
.br
Config = [{Key, Value}]
.br
SnmpReply = snmpreply()
.br
.RE
.RE
.RS
.LP
Issues a synchronous SNMP \fIset\fR\& request\&.
.RE

.LP
.B
start(Config, MgrAgentConfName) -> ok
.br
.RS
.LP
Equivalent to \fIct_snmp:start(Config, MgrAgentConfName, undefined)\fR\&\&.
.RE

.LP
.B
start(Config, MgrAgentConfName, SnmpAppConfName) -> ok
.br
.RS
.LP
Types:

.RS 3
Config = [{Key, Value}]
.br
Key = atom()
.br
Value = term()
.br
MgrAgentConfName = atom()
.br
SnmpConfName = atom()
.br
.RE
.RE
.RS
.LP
Starts an SNMP manager and/or agent\&. In the manager case, registrations of users and agents, as specified by the configuration \fIMgrAgentConfName\fR\&, are performed\&. When using SNMPv3, called USM users are also registered\&. Users, \fIusm_users\fR\&, and managed agents can also be registered later using \fIct_snmp:register_users/2\fR\&, \fIct_snmp:register_agents/2\fR\&, and \fIct_snmp:register_usm_users/2\fR\&\&.
.LP
The agent started is called \fIsnmp_master_agent\fR\&\&. Use \fIct_snmp:load_mibs/1\fR\& to load MIBs into the agent\&.
.LP
With \fISnmpAppConfName\fR\& SNMP applications can be configured with parameters \fIconfig\fR\&, \fImibs\fR\&, \fInet_if\fR\&, and so on\&. The values are merged with (and possibly override) default values set by \fIct_snmp\fR\&\&.
.RE

.LP
.B
stop(Config) -> ok
.br
.RS
.LP
Types:

.RS 3
Config = [{Key, Value}]
.br
Key = atom()
.br
Value = term()
.br
.RE
.RE
.RS
.LP
Stops the SNMP manager and/or agent, and removes all files created\&.
.RE

.LP
.B
unload_mibs(Mibs) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Mibs = [MibName]
.br
MibName = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Unloads the MIBs from agent \fIsnmp_master_agent\fR\&\&.
.RE

.LP
.B
unregister_agents(MgrAgentConfName) -> ok
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Unregisters all managed agents\&.
.RE

.LP
.B
unregister_agents(MgrAgentConfName, ManagedAgents) -> ok
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
ManagedAgents = [agent_name()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Unregisters the specified managed agents\&.
.RE

.LP
.B
unregister_users(MgrAgentConfName) -> ok
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Unregisters all users\&.
.RE

.LP
.B
unregister_users(MgrAgentConfName, Users) -> ok
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
Users = [user_name()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Unregisters the specified users\&.
.RE

.LP
.B
unregister_usm_users(MgrAgentConfName) -> ok
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Unregisters all USM users\&.
.RE

.LP
.B
unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok
.br
.RS
.LP
Types:

.RS 3
MgrAgentConfName = atom()
.br
UsmUsers = [usm_user_name()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Unregisters the specified USM users\&.
.RE