1ct_snmp(3) Erlang Module Definition ct_snmp(3)
2
6 ct_snmp - Common Test user interface module for the SNMP application.
7
9 Common Test user interface module for the SNMP application.
10 The purpose of this module is to simplify SNMP configuration for the
12 test case writer. Many test cases can use default values for common op‐
13 erations and then no SNMP configuration files need to be supplied. When
14 it is necessary to change particular configuration parameters, a subset
15 of the relevant SNMP configuration files can be passed to ct_snmp by
16 Common Test configuration files. For more specialized configuration pa‐
17 rameters, a simple SNMP configuration file can be placed in the test
18 suite data directory. To simplify the test suite, Common Test keeps
19 track of some of the SNMP manager information. This way the test suite
20 does not have to handle as many input parameters as if it had to inter‐
21 face wthe OTP SNMP manager directly.
22 Configurable SNMP Manager and Agent Parameters:
24 Manager configuration:
26 [{start_manager, boolean()}:
28 Optional. Default is true.
29 {users, [{user_name(), [call_back_module(), user_data()]}]}:
31 Optional.
32 {usm_users, [{usm_user_name(), [usm_config()]}]}:
34 Optional. SNMPv3 only.
35 {managed_agents,[{agent_name(), [user_name(), agent_ip(),
37 agent_port(), [agent_config()]]}]}:
38 managed_agents is optional.
39 {max_msg_size, integer()}:
41 Optional. Default is 484.
42 {mgr_port, integer()}:
44 Optional. Default is 5000.
45 {engine _id, string()}:
47 Optional. Default is "mgrEngine".
48 Agent configuration:
50 {start_agent, boolean()}:
52 Optional. Default is false.
53 {agent_sysname, string()}:
55 Optional. Default is "ct_test".
56 {agent_manager_ip, manager_ip()}:
58 Optional. Default is localhost.
59 {agent_vsns, list()}:
61 Optional. Default is [v2].
62 {agent_trap_udp, integer()}:
64 Optional. Default is 5000.
65 {agent_udp, integer()}:
67 Optional. Default is 4000.
68 {agent_notify_type, atom()}:
70 Optional. Default is trap.
71 {agent_sec_type, sec_type()}:
73 Optional. Default is none.
74 {agent_passwd, string()}:
76 Optional. Default is "".
77 {agent_engine_id, string()}:
79 Optional. Default is "agentEngine".
80 {agent_max_msg_size, string()}:
82 Optional. Default is 484.
83 The following parameters represents the SNMP configuration files con‐
85 text.conf, standard.conf, community.conf, vacm.conf, usm.conf, no‐
86 tify.conf, target_addr.conf, and target_params.conf. Notice that all
87 values in agent.conf can be modified by the parameters listed above.
88 All these configuration files have default values set by the SNMP ap‐
89 plication. These values can be overridden by suppling a list of valid
90 configuration values or a file located in the test suites data direc‐
91 tory, which can produce a list of valid configuration values if you ap‐
92 ply function file:consult/1 to the file.
93 {agent_contexts, [term()] | {data_dir_file, rel_path()}}:
95 Optional.
96 {agent_community, [term()] | {data_dir_file, rel_path()}}:
98 Optional.
99 {agent_sysinfo, [term()] | {data_dir_file, rel_path()}}:
101 Optional.
102 {agent_vacm, [term()] | {data_dir_file, rel_path()}}:
104 Optional.
105 {agent_usm, [term()] | {data_dir_file, rel_path()}}:
107 Optional.
108 {agent_notify_def, [term()] | {data_dir_file, rel_path()}}:
110 Optional.
111 {agent_target_address_def, [term()] | {data_dir_file, rel_path()}}:
113 Optional.
114 {agent_target_param_def, [term()] | {data_dir_file, rel_path()}}:
116 Optional.
117 Parameter MgrAgentConfName in the functions is to be a name you allo‐
119 cate in your test suite using a require statement. Example (where MgrA‐
120 gentConfName = snmp_mgr_agent):
121 suite() -> [{require, snmp_mgr_agent, snmp}].
123 or
125 ct:require(snmp_mgr_agent, snmp).
127 Notice that USM users are needed for SNMPv3 configuration and are not
129 to be confused with users.
130 SNMP traps, inform, and report messages are handled by the user call‐
132 back module. For details, see the SNMP application.
133 It is recommended to use the .hrl files created by the Erlang/OTP MIB
135 compiler to define the Object Identifiers (OIDs). For example, to get
136 the Erlang node name from erlNodeTable in the OTP-MIB:
137 Oid = ?erlNodeEntry ++ [?erlNodeName, 1]
139 Furthermore, values can be set for SNMP application configuration pa‐
141 rameters, config, server, net_if, and so on (for a list of valid param‐
142 eters and types, see the User's Guide for the SNMP application). This
143 is done by defining a configuration data variable on the following
144 form:
145 {snmp_app, [{manager, [snmp_app_manager_params()]},
147 {agent, [snmp_app_agent_params()]}]}.
148 A name for the data must be allocated in the suite using require (see
150 the example above). Pass this name as argument SnmpAppConfName to
151 ct_snmp:start/3. ct_snmp specifies default values for some SNMP appli‐
152 cation configuration parameters (such as {verbosity,trace} for parame‐
153 ter config). This set of defaults is merged with the parameters speci‐
154 fied by the user. The user values override ct_snmp defaults.
155
157 agent_config() = {Item, Value}
158 agent_ip() = ip()
160 agent_name() = atom()
162 agent_port() = integer()
164 call_back_module() = atom()
166 error_index() = integer()
168 error_status() = noError | atom()
170 ip() = string() | {integer(), integer(), integer(), integer()}
172 manager_ip() = ip()
174 oid() = [byte()]
176 oids() = [oid()]
178 rel_path() = string()
180 sec_type() = none | minimum | semi
182 snmp_app_agent_params() = term()
184 snmp_app_manager_params() = term()
186 snmpreply() = {error_status(), error_index(), varbinds()}
188 user_data() = term()
190 user_name() = atom()
192 usm_config() = {Item, Value}
194 usm_user_name() = string()
196 value_type() = o('OBJECT IDENTIFIER') | i('INTEGER') | u('Unsigned32') | g('Unsigned32') | s('OCTET STRING')
198 var_and_val() = {oid(), value_type(), value()}
200 varbind() = term()
202 varbinds() = [varbind()]
204 varsandvals() = [var_and_val()]
206 These data types are described in the documentation for the SNMP
208 application.
209
211 get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
212 Types:
214 Agent = agent_name()
216 Oids = oids()
217 MgrAgentConfName = atom()
218 SnmpReply = snmpreply()
219 Issues a synchronous SNMP get next request.
221 get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
223 Types:
225 Agent = agent_name()
227 Oids = oids()
228 MgrAgentConfName = atom()
229 SnmpReply = snmpreply()
230 Issues a synchronous SNMP get request.
232 load_mibs(Mibs) -> ok | {error, Reason}
234 Types:
236 Mibs = [MibName]
238 MibName = string()
239 Reason = term()
240 Loads the MIBs into agent snmp_master_agent.
242 register_agents(MgrAgentConfName, ManagedAgents) -> ok | {error, Rea‐
244 son}
245 Types:
247 MgrAgentConfName = atom()
249 ManagedAgents = [agent()]
250 Reason = term()
251 Explicitly instructs the manager to handle this agent. Corre‐
253 sponds to making an entry in agents.conf.
254 This function tries to register the specified managed agents,
256 without checking if any of them exist. To change a registered
257 managed agent, the agent must first be unregistered.
258 register_users(MgrAgentConfName, Users) -> ok | {error, Reason}
260 Types:
262 MgrAgentConfName = atom()
264 Users = [user()]
265 Reason = term()
266 Registers the manager entity (=user) responsible for specific
268 agent(s). Corresponds to making an entry in users.conf.
269 This function tries to register the specified users, without
271 checking if any of them exist. To change a registered user, the
272 user must first be unregistered.
273 register_usm_users(MgrAgentConfName, UsmUsers) -> ok | {error, Reason}
275 Types:
277 MgrAgentConfName = atom()
279 UsmUsers = [usm_user()]
280 Reason = term()
281 Explicitly instructs the manager to handle this USM user. Corre‐
283 sponds to making an entry in usm.conf.
284 This function tries to register the specified users, without
286 checking if any of them exist. To change a registered user, the
287 user must first be unregistered.
288 set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]
290 Types:
292 Config = [{Key, Value}]
294 Agent = agent_name()
295 OldVarsAndVals = varsandvals()
296 NewVarsAndVals = varsandvals()
297 Returns a list of all successful set requests performed in the
299 test case in reverse order. The list contains the involved user
300 and agent, the value before set, and the new value. This is in‐
301 tended to simplify the cleanup in function end_per_testcase,
302 that is, the undoing of the set requests and their possible
303 side-effects.
304 set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply
306 Types:
308 Agent = agent_name()
310 Oids = oids()
311 MgrAgentConfName = atom()
312 Config = [{Key, Value}]
313 SnmpReply = snmpreply()
314 Issues a synchronous SNMP set request.
316 start(Config, MgrAgentConfName) -> ok
318 Equivalent to ct_snmp:start(Config, MgrAgentConfName, unde‐
320 fined).
321 start(Config, MgrAgentConfName, SnmpAppConfName) -> ok
323 Types:
325 Config = [{Key, Value}]
327 Key = atom()
328 Value = term()
329 MgrAgentConfName = atom()
330 SnmpConfName = atom()
331 Starts an SNMP manager and/or agent. In the manager case, regis‐
333 trations of users and agents, as specified by the configuration
334 MgrAgentConfName, are performed. When using SNMPv3, called USM
335 users are also registered. Users, usm_users, and managed agents
336 can also be registered later using ct_snmp:register_users/2,
337 ct_snmp:register_agents/2, and ct_snmp:register_usm_users/2.
338 The agent started is called snmp_master_agent. Use
340 ct_snmp:load_mibs/1 to load MIBs into the agent.
341 With SnmpAppConfName SNMP applications can be configured with
343 parameters config, mibs, net_if, and so on. The values are
344 merged with (and possibly override) default values set by
345 ct_snmp.
346 stop(Config) -> ok
348 Types:
350 Config = [{Key, Value}]
352 Key = atom()
353 Value = term()
354 Stops the SNMP manager and/or agent, and removes all files cre‐
356 ated.
357 unload_mibs(Mibs) -> ok | {error, Reason}
359 Types:
361 Mibs = [MibName]
363 MibName = string()
364 Reason = term()
365 Unloads the MIBs from agent snmp_master_agent.
367 unregister_agents(MgrAgentConfName) -> ok
369 Types:
371 MgrAgentConfName = atom()
373 Reason = term()
374 Unregisters all managed agents.
376 unregister_agents(MgrAgentConfName, ManagedAgents) -> ok
378 Types:
380 MgrAgentConfName = atom()
382 ManagedAgents = [agent_name()]
383 Reason = term()
384 Unregisters the specified managed agents.
386 unregister_users(MgrAgentConfName) -> ok
388 Types:
390 MgrAgentConfName = atom()
392 Reason = term()
393 Unregisters all users.
395 unregister_users(MgrAgentConfName, Users) -> ok
397 Types:
399 MgrAgentConfName = atom()
401 Users = [user_name()]
402 Reason = term()
403 Unregisters the specified users.
405 unregister_usm_users(MgrAgentConfName) -> ok
407 Types:
409 MgrAgentConfName = atom()
411 Reason = term()
412 Unregisters all USM users.
414 unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok
416 Types:
418 MgrAgentConfName = atom()
420 UsmUsers = [usm_user_name()]
421 Reason = term()
422 Unregisters the specified USM users.
424Ericsson AB common_test 1.23.3 ct_snmp(3)