From 68d7535fe0cccd50622884f704edeb9d8bb47430 Mon Sep 17 00:00:00 2001 From: tmanevik Date: Fri, 18 Dec 2015 12:21:32 +0100 Subject: Common Test: Editorial changes 3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reference Manual files from Pär Wennstad added --- lib/common_test/doc/src/ct_snmp.xml | 524 ++++++++++++++++++++++++++++++++++++ 1 file changed, 524 insertions(+) create mode 100644 lib/common_test/doc/src/ct_snmp.xml (limited to 'lib/common_test/doc/src/ct_snmp.xml') diff --git a/lib/common_test/doc/src/ct_snmp.xml b/lib/common_test/doc/src/ct_snmp.xml new file mode 100644 index 0000000000..60f1d600e0 --- /dev/null +++ b/lib/common_test/doc/src/ct_snmp.xml @@ -0,0 +1,524 @@ + + + + +
+ + 20102012 + Ericsson AB. All Rights Reserved. + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + + ct_snmp + + + + + + + A + ct_snmp.xml +
+ ct_snmp + Common Test user interface module for the SNMP application. + + + +

Common Test user interface module for the SNMP + application.

+ +

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 + ct_snmp by Common Test 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, Common Test 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.

+ +

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.

 + {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.

 + + +

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. Notice that + all values in agent.conf can be modified by the parameters + listed above. All these configuration files have default values set 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 directory, which can produce a list of valid configuration + values if you apply function 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.

 + + +

Parameter MgrAgentConfName in the functions is to be a name + you allocate in your test suite using a require statement. + Example (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 are + not to be confused with users.

+ +

SNMP traps, inform, and report messages are handled by the user + callback module. For details, 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, values can be set for SNMP application configuration + parameters, config, server, net_if, and so on (for + a list of valid parameters and types, see the User's Guide for + the SNMP application). This is + done 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 (see the example above). Pass this name as argument + SnmpAppConfName to + ct_snmp:start/3. + ct_snmp specifies default values for some SNMP application + configuration parameters (such as {verbosity,trace} for parameter + config). This set of defaults is merged with the parameters + specified by the user. The user values override ct_snmp + defaults.

+ + + +
+ Data Types + + + agent_config() = {Item, Value} + + 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, Value} + + usm_user_name() = string() + + value_type() = o('OBJECT IDENTIFIER') | i('INTEGER') | u('Unsigned32') | g('Unsigned32') | s('OCTET STRING') + + var_and_val() = {oid(), value_type(), value()} + + varbind() = term() + + varbinds() = [varbind()] + + varsandvals() = [var_and_val()] + + +

These data types are described in the documentation for + the SNMP application.

+
+ + + + get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply + Issues a synchronous SNMP get next request. + + Agent = agent_name() + Oids = oids() + MgrAgentConfName = atom() + SnmpReply = snmpreply() + + +

Issues a synchronous SNMP get next request.

+ + + + + get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply + Issues a synchronous SNMP get request. + + Agent = agent_name() + Oids = oids() + MgrAgentConfName = atom() + SnmpReply = snmpreply() + + +

Issues a synchronous SNMP get request.

+ + + + + load_mibs(Mibs) -> ok | {error, Reason} + Loads the MIBs into agent snmp_master_agent. + + Mibs = [MibName] + MibName = string() + Reason = term() + + +

Loads the MIBs into agent snmp_master_agent.

+ + + + + register_agents(MgrAgentConfName, ManagedAgents) -> ok | {error, Reason} + Explicitly instructs the manager to handle this + agent. + + MgrAgentConfName = atom() + ManagedAgents = [agent()] + Reason = term() + + +

Explicitly instructs the manager to handle this agent. 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.

+ + + + + register_users(MgrAgentConfName, Users) -> ok | {error, Reason} + Registers the manager entity (=user) responsible for specific + agent(s). + + MgrAgentConfName = atom() + Users = [user()] + Reason = term() + + +

Registers the manager entity (=user) responsible for specific + agent(s). Corresponds to making an entry in users.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.

+ + + + + register_usm_users(MgrAgentConfName, UsmUsers) -> ok | {error, Reason} + Explicitly instructs the manager to handle this USM user. + + MgrAgentConfName = atom() + UsmUsers = [usm_user()] + 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.

+ + + + + set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}] + Returns a list of all successful set requests performed in the + test case in reverse order. + + Config = [{Key, Value}] + 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.

+ + + + + set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply + Issues a synchronous SNMP set request. + + Agent = agent_name() + Oids = oids() + MgrAgentConfName = atom() + Config = [{Key, Value}] + SnmpReply = snmpreply() + + +

Issues a synchronous SNMP set request.

+ + + + + start(Config, MgrAgentConfName) -> ok + Equivalent to start(Config, MgrAgentConfName, + undefined). + +

Equivalent to + ct_snmp:start(Config, MgrAgentConfName, + undefined).

+ + + + + start(Config, MgrAgentConfName, SnmpAppConfName) -> ok + Starts an SNMP manager and/or agent. + + Config = [{Key, Value}] + Key = atom() + Value = term() + MgrAgentConfName = atom() + SnmpConfName = atom() + + +

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.

+ + + + + stop(Config) -> ok + Stops the SNMP manager and/or agent, and removes all files + created. + + Config = [{Key, Value}] + Key = atom() + Value = term() + + +

Stops the SNMP manager and/or agent, and removes all files + created.

+ + + + + unload_mibs(Mibs) -> ok | {error, Reason} + Unloads the MIBs from agent snmp_master_agent. + + Mibs = [MibName] + MibName = string() + Reason = term() + + +

Unloads the MIBs from agent snmp_master_agent.

+ + + + + unregister_agents(MgrAgentConfName) -> ok + Unregisters all managed agents. + + MgrAgentConfName = atom() + Reason = term() + + +

Unregisters all managed agents.

+ + + + + unregister_agents(MgrAgentConfName, ManagedAgents) -> ok + Unregisters the specified managed agents. + + MgrAgentConfName = atom() + ManagedAgents = [agent_name()] + Reason = term() + + +

Unregisters the specified managed agents.

+ + + + + unregister_users(MgrAgentConfName) -> ok + Unregisters all users. + + MgrAgentConfName = atom() + Reason = term() + + +

Unregisters all users.

+ + + + + unregister_users(MgrAgentConfName, Users) -> ok + Unregisters the specified users. + + MgrAgentConfName = atom() + Users = [user_name()] + Reason = term() + + +

Unregisters the specified users.

+ + + + + unregister_usm_users(MgrAgentConfName) -> ok + Unregisters all USM users. + + MgrAgentConfName = atom() + Reason = term() + + +

Unregisters all USM users.

+ + + + + unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok + Unregisters the specified USM users. + + MgrAgentConfName = atom() + UsmUsers = [usm_user_name()] + Reason = term() + + +

Unregisters the specified USM users.

+ + + + + + + -- cgit v1.2.3