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
13 operations and then no SNMP configuration files need to be supplied.
14 When it is necessary to change particular configuration parameters, a
15 subset of the relevant SNMP configuration files can be passed to
16 ct_snmp by Common Test configuration files. For more specialized con‐
17 figuration parameters, a simple SNMP configuration file can be placed
18 in the test suite data directory. To simplify the test suite, Common
19 Test keeps track of some of the SNMP manager information. This way the
20 test suite does not have to handle as many input parameters as if it
21 had to interface 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,
86 notify.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
89 application. 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
92 apply 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
141 parameters, config, server, net_if, and so on (for a list of valid
142 parameters and types, see the User's Guide for the SNMP application).
143 This 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():
161 agent_name() = atom():
164 agent_port() = integer():
167 call_back_module() = atom():
170 error_index() = integer():
173 error_status() = noError | atom():
176 ip() = string() | {integer(), integer(), integer(), integer()}:
179 manager_ip() = ip():
182 oid() = [byte()]:
185 oids() = [oid()]:
188 rel_path() = string():
191 sec_type() = none | minimum | semi:
194 snmp_app_agent_params() = term():
197 snmp_app_manager_params() = term():
200 snmpreply() = {error_status(), error_index(), varbinds()}:
203 user_data() = term():
206 user_name() = atom():
209 usm_config() = {Item, Value}:
212 usm_user_name() = string():
215 value_type() = o('OBJECT IDENTIFIER') | i('INTEGER') |
218 u('Unsigned32') | g('Unsigned32') | s('OCTET STRING'):
219 var_and_val() = {oid(), value_type(), value()}:
222 varbind() = term():
225 varbinds() = [varbind()]:
228 varsandvals() = [var_and_val()]:
231 These data types are described in the documentation for the SNMP appli‐
234 cation.
235
237 get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
238 Types:
240 Agent = agent_name()
242 Oids = oids()
243 MgrAgentConfName = atom()
244 SnmpReply = snmpreply()
245 Issues a synchronous SNMP get next request.
247 get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
249 Types:
251 Agent = agent_name()
253 Oids = oids()
254 MgrAgentConfName = atom()
255 SnmpReply = snmpreply()
256 Issues a synchronous SNMP get request.
258 load_mibs(Mibs) -> ok | {error, Reason}
260 Types:
262 Mibs = [MibName]
264 MibName = string()
265 Reason = term()
266 Loads the MIBs into agent snmp_master_agent.
268 register_agents(MgrAgentConfName, ManagedAgents) -> ok | {error, Rea‐
270 son}
271 Types:
273 MgrAgentConfName = atom()
275 ManagedAgents = [agent()]
276 Reason = term()
277 Explicitly instructs the manager to handle this agent. Corre‐
279 sponds to making an entry in agents.conf.
280 This function tries to register the specified managed agents,
282 without checking if any of them exist. To change a registered
283 managed agent, the agent must first be unregistered.
284 register_users(MgrAgentConfName, Users) -> ok | {error, Reason}
286 Types:
288 MgrAgentConfName = atom()
290 Users = [user()]
291 Reason = term()
292 Registers the manager entity (=user) responsible for specific
294 agent(s). Corresponds to making an entry in users.conf.
295 This function tries to register the specified users, without
297 checking if any of them exist. To change a registered user, the
298 user must first be unregistered.
299 register_usm_users(MgrAgentConfName, UsmUsers) -> ok | {error, Reason}
301 Types:
303 MgrAgentConfName = atom()
305 UsmUsers = [usm_user()]
306 Reason = term()
307 Explicitly instructs the manager to handle this USM user. Corre‐
309 sponds to making an entry in usm.conf.
310 This function tries to register the specified users, without
312 checking if any of them exist. To change a registered user, the
313 user must first be unregistered.
314 set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]
316 Types:
318 Config = [{Key, Value}]
320 Agent = agent_name()
321 OldVarsAndVals = varsandvals()
322 NewVarsAndVals = varsandvals()
323 Returns a list of all successful set requests performed in the
325 test case in reverse order. The list contains the involved user
326 and agent, the value before set, and the new value. This is
327 intended to simplify the cleanup in function end_per_testcase,
328 that is, the undoing of the set requests and their possible
329 side-effects.
330 set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply
332 Types:
334 Agent = agent_name()
336 Oids = oids()
337 MgrAgentConfName = atom()
338 Config = [{Key, Value}]
339 SnmpReply = snmpreply()
340 Issues a synchronous SNMP set request.
342 start(Config, MgrAgentConfName) -> ok
344 Equivalent to ct_snmp:start(Config, MgrAgentConfName, unde‐
346 fined).
347 start(Config, MgrAgentConfName, SnmpAppConfName) -> ok
349 Types:
351 Config = [{Key, Value}]
353 Key = atom()
354 Value = term()
355 MgrAgentConfName = atom()
356 SnmpConfName = atom()
357 Starts an SNMP manager and/or agent. In the manager case, regis‐
359 trations of users and agents, as specified by the configuration
360 MgrAgentConfName, are performed. When using SNMPv3, called USM
361 users are also registered. Users, usm_users, and managed agents
362 can also be registered later using ct_snmp:register_users/2,
363 ct_snmp:register_agents/2, and ct_snmp:register_usm_users/2.
364 The agent started is called snmp_master_agent. Use
366 ct_snmp:load_mibs/1 to load MIBs into the agent.
367 With SnmpAppConfName SNMP applications can be configured with
369 parameters config, mibs, net_if, and so on. The values are
370 merged with (and possibly override) default values set by
371 ct_snmp.
372 stop(Config) -> ok
374 Types:
376 Config = [{Key, Value}]
378 Key = atom()
379 Value = term()
380 Stops the SNMP manager and/or agent, and removes all files cre‐
382 ated.
383 unload_mibs(Mibs) -> ok | {error, Reason}
385 Types:
387 Mibs = [MibName]
389 MibName = string()
390 Reason = term()
391 Unloads the MIBs from agent snmp_master_agent.
393 unregister_agents(MgrAgentConfName) -> ok
395 Types:
397 MgrAgentConfName = atom()
399 Reason = term()
400 Unregisters all managed agents.
402 unregister_agents(MgrAgentConfName, ManagedAgents) -> ok
404 Types:
406 MgrAgentConfName = atom()
408 ManagedAgents = [agent_name()]
409 Reason = term()
410 Unregisters the specified managed agents.
412 unregister_users(MgrAgentConfName) -> ok
414 Types:
416 MgrAgentConfName = atom()
418 Reason = term()
419 Unregisters all users.
421 unregister_users(MgrAgentConfName, Users) -> ok
423 Types:
425 MgrAgentConfName = atom()
427 Users = [user_name()]
428 Reason = term()
429 Unregisters the specified users.
431 unregister_usm_users(MgrAgentConfName) -> ok
433 Types:
435 MgrAgentConfName = atom()
437 Reason = term()
438 Unregisters all USM users.
440 unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok
442 Types:
444 MgrAgentConfName = atom()
446 UsmUsers = [usm_user_name()]
447 Reason = term()
448 Unregisters the specified USM users.
450Ericsson AB common_test 1.18 ct_snmp(3)