.TH ct_snmp 3 "common_test  1.3.2" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
ct_snmp \- Common Test specific layer on top of the OTPs snmp\&.
.SH DESCRIPTION
.LP
Common Test specific layer on top of the OTPs snmp
.LP
Application to make snmp configuration easier for the test case writer\&. Many test cases can use default values for everything and then no snmp-configuration files needs to be supplied at all\&. When it is necessary to change some configuration it can be done for the subset of snmp-configuration files that are relevant, and still all this can be put in to the common-test configuration file or for the more specialized configuration parameters a "simple snmp-configuration file" can be placed in the test suites data directory\&. ct_snmp will also perform a type check on all supplied configuration\&. In the manager case the common_test application also will keep track of some manager information so that the test case write does not have to keep track of as much input parameters as if using the OTPs snmp manager directly\&.
.LP
The following parameters are configurable 

.nf
   {snmp,
          %%% Manager config
          [{start_manager, boolean()}    % Optional - default is true
          {users, [{user_name(), [call_back_module(), user_data()]}]}, %% Optional
          {usm_users, [{usm_user_name(), usm_config()}]},%% Optional - snmp v3 only
          % managed_agents is optional
          {managed_agents,[{agent_name(), [user_name(), agent_ip(), agent_port(), [agent_config()]]}]},
          {max_msg_size, integer()},     % Optional - default is 484
          {mgr_port, integer()},         % Optional - default is 5000
          {engine _id, string()},        % Optional - default is "mgrEngine"
  
          %%% Agent config
          {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
  
          %% The following parameters represents the snmp configuration files
          %% context\&.conf, standard\&.conf, community\&.conf, vacm\&.conf,
          %% usm\&.conf, notify\&.conf, target_addr\&.conf and target_params\&.conf\&.
          %% Note all values in agent\&.conf can be altered by the parametes
          %% above\&. All these configuration files have default values set
          %% up by the snmp application\&. These values can be overridden by
          %% suppling a list of valid configuration values or a file located
          %% in the test suites data dir that can produce a list
          %% of valid configuration values if you apply file:consult/1 to the
          %% file\&.
          {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
         ]}\&.
   
.fi
.LP
The \fIConfName\fR parameter in the functions should be the name you allocated in your test suite using \fIrequire\fR statement\&. Example:

.nf
 suite() -> [{require, ConfName,{snmp,[users, managed_agents]}}]\&.
.fi
.LP
or

.nf
  ct:require(ConfName,{snmp,[users, managed_agents]})\&.
.fi
.LP
Note that Usm users are needed for snmp v3 configuration and are not to be confused with users\&.
.LP
Snmp traps, inform and report messages are handled by the user callback module\&. For more information about this see the snmp application\&. 
.LP
Note: It is recommended to use the \&.hrl-files created by the Erlang/OTP mib-compiler to define the oids\&. Ex for the getting the erlang node name from the erlNodeTable in the OTP-MIB 

.nf
Oid = ?erlNodeEntry ++ [?erlNodeName, 1] 
.fi

.SH DATA TYPES
.RS 2
.TP 4
.B
\fIagent_config() = {Item, Value}\fR:

.TP 4
.B
\fIagent_ip() = ip()\fR:

.TP 4
.B
\fIagent_name() = atom()\fR:

.TP 4
.B
\fIagent_port() = integer()\fR:

.TP 4
.B
\fIcall_back_module() = atom()\fR:

.TP 4
.B
\fIerror_index() = integer()\fR:

.TP 4
.B
\fIerror_status() = noError | atom()\fR:

.TP 4
.B
\fIip() = string() | {integer(), integer(), integer(), integer()}\fR:

.TP 4
.B
\fImanager_ip() = ip()\fR:

.TP 4
.B
\fIoid() = [byte()]\fR:

.TP 4
.B
\fIoids() = [oid()]\fR:

.TP 4
.B
\fIrel_path() = string()\fR:

.TP 4
.B
\fIsec_type() = none | minimum | semi\fR:

.TP 4
.B
\fIsnmpreply() = {error_status(), error_index(), varbinds()}\fR:

.TP 4
.B
\fIuser_data() = term()\fR:

.TP 4
.B
\fIuser_name() = atom()\fR:

.TP 4
.B
\fIusm_config() = string()\fR:

.TP 4
.B
\fIusm_user_name() = string()\fR:

.TP 4
.B
\fIvalue_type() = o(\&'OBJECT IDENTIFIER\&') | i(\&'INTEGER\&') | u(\&'Unsigned32\&') | g(\&'Unsigned32\&') | s(\&'OCTET STRING\&')\fR:

.TP 4
.B
\fIvar_and_val() = {oid(), value_type(), value()}\fR:

.TP 4
.B
\fIvarbind() = term()\fR:

.TP 4
.B
\fIvarbinds() = [varbind()]\fR:

.TP 4
.B
\fIvarsandvals() = [var_and_val()]\fR:

.RE
.SH EXPORTS
.LP
.B
get_next_values(Agent, Oids, ConfName) -> SnmpReply
.br
.RS
.TP
Types
Agent = agent_name()
.br
Oids = oids()
.br
ConfName = atom()
.br
SnmpReply = snmpreply()
.br
.RE
.RS
.LP
Issues a synchronous snmp get next request\&.
.RE
.LP
.B
get_values(Agent, Oids, ConfName) -> SnmpReply
.br
.RS
.TP
Types
Agent = agent_name()
.br
Oids = oids()
.br
ConfName = atom()
.br
SnmpReply = snmpreply()
.br
.RE
.RS
.LP
Issues a synchronous snmp get request\&.
.RE
.LP
.B
load_mibs(Mibs) -> ok | {error, Reason}
.br
.RS
.TP
Types
Mibs = [MibName]
.br
MibName = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Load the mibs into the agent \&'snmp_master_agent\&'\&.
.RE
.LP
.B
register_agents(ConfName, ManagedAgents) -> ok | {error, Reason}
.br
.RS
.TP
Types
ConfName = atom()
.br
ManagedAgents = [agent()]
.br
Reason = term()
.br
.RE
.RS
.LP
Explicitly instruct the manager to handle this agent\&. Corresponds to making an entry in agents\&.conf
.RE
.LP
.B
register_users(ConfName, Users) -> ok | {error, Reason}
.br
.RS
.TP
Types
ConfName = atom()
.br
Users = [user()]
.br
Reason = term()
.br
.RE
.RS
.LP
Register the manager entity (=user) responsible for specific agent(s)\&. Corresponds to making an entry in users\&.conf
.RE
.LP
.B
register_usm_users(ConfName, UsmUsers) -> ok | {error, Reason}
.br
.RS
.TP
Types
ConfName = atom()
.br
UsmUsers = [usm_user()]
.br
Reason = term()
.br
.RE
.RS
.LP
Explicitly instruct the manager to handle this USM user\&. Corresponds to making an entry in usm\&.conf
.RE
.LP
.B
set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]
.br
.RS
.TP
Types
Config = [{Key, Value}]
.br
Agent = agent_name()
.br
OldVarsAndVals = varsandvals()
.br
NewVarsAndVals = varsandvals()
.br
.RE
.RS
.LP
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 prior to the set and the new value\&. This is intended to facilitate the clean up in the end_per_testcase function i\&.e\&. the undoing of the set requests and its possible side-effects\&.
.RE
.LP
.B
set_values(Agent, VarsAndVals, ConfName, Config) -> SnmpReply
.br
.RS
.TP
Types
Agent = agent_name()
.br
Oids = oids()
.br
ConfName = atom()
.br
Config = [{Key, Value}]
.br
SnmpReply = snmpreply()
.br
.RE
.RS
.LP
Issues a synchronous snmp set request\&.
.RE
.LP
.B
start(Config, ConfName) -> ok
.br
.RS
.TP
Types
Config = [{Key, Value}]
.br
Key = atom()
.br
Value = term()
.br
ConfName = atom()
.br
.RE
.RS
.LP
Starts an snmp manager and/or agent\&. In the manager case also registrations of users and agents as specified by the configuration <ConfName> will be performed\&. When using snmp v3 also so called usm users will be registered\&. Note that users, usm_users and managed agents may also be registerd at a later time using ct_snmp:register_users/2, ct_snmp:register_agents/2, and ct_snmp:register_usm_users/2\&. The agent started will be called snmp_master_agent\&. Use ct_snmp:load_mibs to load mibs into the agent\&.
.RE
.LP
.B
stop(Config) -> ok
.br
.RS
.TP
Types
Config = [{Key, Value}]
.br
Key = atom()
.br
Value = term()
.br
ConfName = atom()
.br
.RE
.RS
.LP
Stops the snmp manager and/or agent removes all files created\&.
.RE
.LP
.B
unregister_agents(ConfName) -> ok | {error, Reason}
.br
.RS
.TP
Types
ConfName = atom()
.br
Reason = term()
.br
.RE
.RS
.LP
Removes information added when calling register_agents/2\&.
.RE
.LP
.B
unregister_users(ConfName) -> ok | {error, Reason}
.br
.RS
.TP
Types
ConfName = atom()
.br
Reason = term()
.br
.RE
.RS
.LP
Removes information added when calling register_users/2\&.
.RE
.LP
.B
update_usm_users(ConfName, UsmUsers) -> ok | {error, Reason}
.br
.RS
.TP
Types
ConfName = atom()
.br
UsmUsers = usm_users()
.br
Reason = term()
.br
.RE
.RS
.LP
Alters information added when calling register_usm_users/2\&.
.RE