1ct_snmp(3)                 Erlang Module Definition                 ct_snmp(3)
2
3
4

NAME

6       ct_snmp - Common Test user interface module for the SNMP application.
7

DESCRIPTION

9       Common Test user interface module for the SNMP application.
10
11       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
23       Configurable SNMP Manager and Agent Parameters:
24
25       Manager configuration:
26
27         [{start_manager, boolean()}:
28           Optional. Default is true.
29
30         {users, [{user_name(), [call_back_module(), user_data()]}]}:
31           Optional.
32
33         {usm_users, [{usm_user_name(), [usm_config()]}]}:
34           Optional. SNMPv3 only.
35
36         {managed_agents,[{agent_name(),       [user_name(),       agent_ip(),
37         agent_port(), [agent_config()]]}]}:
38           managed_agents is optional.
39
40         {max_msg_size, integer()}:
41           Optional. Default is 484.
42
43         {mgr_port, integer()}:
44           Optional. Default is 5000.
45
46         {engine _id, string()}:
47           Optional. Default is "mgrEngine".
48
49       Agent configuration:
50
51         {start_agent, boolean()}:
52           Optional. Default is false.
53
54         {agent_sysname, string()}:
55           Optional. Default is "ct_test".
56
57         {agent_manager_ip, manager_ip()}:
58           Optional. Default is localhost.
59
60         {agent_vsns, list()}:
61           Optional. Default is [v2].
62
63         {agent_trap_udp, integer()}:
64           Optional. Default is 5000.
65
66         {agent_udp, integer()}:
67           Optional. Default is 4000.
68
69         {agent_notify_type, atom()}:
70           Optional. Default is trap.
71
72         {agent_sec_type, sec_type()}:
73           Optional. Default is none.
74
75         {agent_passwd, string()}:
76           Optional. Default is "".
77
78         {agent_engine_id, string()}:
79           Optional. Default is "agentEngine".
80
81         {agent_max_msg_size, string()}:
82           Optional. Default is 484.
83
84       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
94         {agent_contexts, [term()] | {data_dir_file, rel_path()}}:
95           Optional.
96
97         {agent_community, [term()] | {data_dir_file, rel_path()}}:
98           Optional.
99
100         {agent_sysinfo, [term()] | {data_dir_file, rel_path()}}:
101           Optional.
102
103         {agent_vacm, [term()] | {data_dir_file, rel_path()}}:
104           Optional.
105
106         {agent_usm, [term()] | {data_dir_file, rel_path()}}:
107           Optional.
108
109         {agent_notify_def, [term()] | {data_dir_file, rel_path()}}:
110           Optional.
111
112         {agent_target_address_def, [term()] | {data_dir_file, rel_path()}}:
113           Optional.
114
115         {agent_target_param_def, [term()] | {data_dir_file, rel_path()}}:
116           Optional.
117
118       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
122        suite() -> [{require, snmp_mgr_agent, snmp}].
123
124       or
125
126        ct:require(snmp_mgr_agent, snmp).
127
128       Notice that USM users are needed for SNMPv3 configuration and  are  not
129       to be confused with users.
130
131       SNMP  traps,  inform, and report messages are handled by the user call‐
132       back module. For details, see the SNMP application.
133
134       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
138        Oid = ?erlNodeEntry ++ [?erlNodeName, 1]
139
140       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
146        {snmp_app, [{manager, [snmp_app_manager_params()]},
147                    {agent, [snmp_app_agent_params()]}]}.
148
149       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

DATA TYPES

157       agent_config() = {Item, Value}
158
159       agent_ip() = ip()
160
161       agent_name() = atom()
162
163       agent_port() = integer()
164
165       call_back_module() = atom()
166
167       error_index() = integer()
168
169       error_status() = noError | atom()
170
171       ip() = string() | {integer(), integer(), integer(), integer()}
172
173       manager_ip() = ip()
174
175       oid() = [byte()]
176
177       oids() = [oid()]
178
179       rel_path() = string()
180
181       sec_type() = none | minimum | semi
182
183       snmp_app_agent_params() = term()
184
185       snmp_app_manager_params() = term()
186
187       snmpreply() = {error_status(), error_index(), varbinds()}
188
189       user_data() = term()
190
191       user_name() = atom()
192
193       usm_config() = {Item, Value}
194
195       usm_user_name() = string()
196
197       value_type() = o('OBJECT IDENTIFIER') | i('INTEGER') | u('Unsigned32') | g('Unsigned32') | s('OCTET STRING')
198
199       var_and_val() = {oid(), value_type(), value()}
200
201       varbind() = term()
202
203       varbinds() = [varbind()]
204
205       varsandvals() = [var_and_val()]
206
207              These data types are described in the documentation for the SNMP
208              application.
209

EXPORTS

211       get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
212
213              Types:
214
215                 Agent = agent_name()
216                 Oids = oids()
217                 MgrAgentConfName = atom()
218                 SnmpReply = snmpreply()
219
220              Issues a synchronous SNMP get next request.
221
222       get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
223
224              Types:
225
226                 Agent = agent_name()
227                 Oids = oids()
228                 MgrAgentConfName = atom()
229                 SnmpReply = snmpreply()
230
231              Issues a synchronous SNMP get request.
232
233       load_mibs(Mibs) -> ok | {error, Reason}
234
235              Types:
236
237                 Mibs = [MibName]
238                 MibName = string()
239                 Reason = term()
240
241              Loads the MIBs into agent snmp_master_agent.
242
243       register_agents(MgrAgentConfName, ManagedAgents) -> ok |  {error,  Rea‐
244       son}
245
246              Types:
247
248                 MgrAgentConfName = atom()
249                 ManagedAgents = [agent()]
250                 Reason = term()
251
252              Explicitly  instructs  the  manager to handle this agent. Corre‐
253              sponds to making an entry in agents.conf.
254
255              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
259       register_users(MgrAgentConfName, Users) -> ok | {error, Reason}
260
261              Types:
262
263                 MgrAgentConfName = atom()
264                 Users = [user()]
265                 Reason = term()
266
267              Registers the manager entity (=user)  responsible  for  specific
268              agent(s). Corresponds to making an entry in users.conf.
269
270              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
274       register_usm_users(MgrAgentConfName, UsmUsers) -> ok | {error, Reason}
275
276              Types:
277
278                 MgrAgentConfName = atom()
279                 UsmUsers = [usm_user()]
280                 Reason = term()
281
282              Explicitly instructs the manager to handle this USM user. Corre‐
283              sponds to making an entry in usm.conf.
284
285              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
289       set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]
290
291              Types:
292
293                 Config = [{Key, Value}]
294                 Agent = agent_name()
295                 OldVarsAndVals = varsandvals()
296                 NewVarsAndVals = varsandvals()
297
298              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
305       set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply
306
307              Types:
308
309                 Agent = agent_name()
310                 Oids = oids()
311                 MgrAgentConfName = atom()
312                 Config = [{Key, Value}]
313                 SnmpReply = snmpreply()
314
315              Issues a synchronous SNMP set request.
316
317       start(Config, MgrAgentConfName) -> ok
318
319              Equivalent   to  ct_snmp:start(Config,  MgrAgentConfName,  unde‐
320              fined).
321
322       start(Config, MgrAgentConfName, SnmpAppConfName) -> ok
323
324              Types:
325
326                 Config = [{Key, Value}]
327                 Key = atom()
328                 Value = term()
329                 MgrAgentConfName = atom()
330                 SnmpConfName = atom()
331
332              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
339              The    agent    started   is   called   snmp_master_agent.   Use
340              ct_snmp:load_mibs/1 to load MIBs into the agent.
341
342              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
347       stop(Config) -> ok
348
349              Types:
350
351                 Config = [{Key, Value}]
352                 Key = atom()
353                 Value = term()
354
355              Stops  the SNMP manager and/or agent, and removes all files cre‐
356              ated.
357
358       unload_mibs(Mibs) -> ok | {error, Reason}
359
360              Types:
361
362                 Mibs = [MibName]
363                 MibName = string()
364                 Reason = term()
365
366              Unloads the MIBs from agent snmp_master_agent.
367
368       unregister_agents(MgrAgentConfName) -> ok
369
370              Types:
371
372                 MgrAgentConfName = atom()
373                 Reason = term()
374
375              Unregisters all managed agents.
376
377       unregister_agents(MgrAgentConfName, ManagedAgents) -> ok
378
379              Types:
380
381                 MgrAgentConfName = atom()
382                 ManagedAgents = [agent_name()]
383                 Reason = term()
384
385              Unregisters the specified managed agents.
386
387       unregister_users(MgrAgentConfName) -> ok
388
389              Types:
390
391                 MgrAgentConfName = atom()
392                 Reason = term()
393
394              Unregisters all users.
395
396       unregister_users(MgrAgentConfName, Users) -> ok
397
398              Types:
399
400                 MgrAgentConfName = atom()
401                 Users = [user_name()]
402                 Reason = term()
403
404              Unregisters the specified users.
405
406       unregister_usm_users(MgrAgentConfName) -> ok
407
408              Types:
409
410                 MgrAgentConfName = atom()
411                 Reason = term()
412
413              Unregisters all USM users.
414
415       unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok
416
417              Types:
418
419                 MgrAgentConfName = atom()
420                 UsmUsers = [usm_user_name()]
421                 Reason = term()
422
423              Unregisters the specified USM users.
424
425
426
427Ericsson AB                   common_test 1.23.3                    ct_snmp(3)
Impressum