1snmp(3) Erlang Module Definition snmp(3)
2
6 snmp - Interface functions to the SNMP toolkit
7
9 The module snmp contains interface functions to the SNMP toolkit.
10
12 The following data-types are used in the functions below:
13 * datetime() = {date(), time()}
15 See calendar for more info.
17
19 config() -> ok | {error, Reason}
20 A simple interactive configuration tool. Simple configuration
22 files can be generated, but more complex configurations still
23 have to be edited manually.
24 The tool is a textual based tool that asks some questions and
26 generates sys.config and *.conf files.
27 Note that if the application shall support version 3, then the
29 crypto app must be started before running this function (pass‐
30 word generation).
31 Note also that some of the configuration files for the agent and
33 manager share the same names. This means that they have to be
34 stored in different directories!
35 start() -> ok | {error, Reason}
37 start(Type) -> ok | {error, Reason}
38 Types:
40 Type = start_type()
42 Starts the SNMP application.
44 See application for more info.
46 start_agent() -> ok | {error, Reason}
48 start_agent(Type) -> ok | {error, Reason}
49 Types:
51 Type = start_type()
53 The SNMP application consists of several entities, of which the
55 agent is one. This function starts the agent entity of the
56 application.
57 Note that the only way to actually start the agent in this way
59 is to add the agent related config after starting the applica‐
60 tion (e.g it cannot be part of the normal application config;
61 sys.config). This is done by calling: application:set_env(snmp,
62 agent, Conf).
63 The default value for Type is normal.
65 start_manager() -> ok | {error, Reason}
67 start_manager(Type) -> ok | {error, Reason}
68 Types:
70 Type = start_type()
72 The SNMP application consists of several entities, of which the
74 manager is one. This function starts the manager entity of the
75 application.
76 Note that the only way to actually start the manager in this way
78 is to add the manager related config after starting the applica‐
79 tion (e.g it cannot be part of the normal application config;
80 sys.config). This is done by calling: application:set_env(snmp,
81 manager, Conf).
82 The default value for Type is normal.
84 date_and_time() -> DateAndTime
86 Types:
88 DateAndTime = [int()]
90 Returns current date and time as the data type DateAndTime, as
92 specified in RFC1903. This is an OCTET STRING.
93 date_and_time_to_universal_time_dst(DateAndTime) -> [utc()]
95 Types:
97 DateAndTime = [int()]
99 utc() = {{Y,Mo,D},{H,M,S}}
100 Converts a DateAndTime list to a list of possible universal
102 time(s). The universal time value on the same format as defined
103 in calendar(3).
104 date_and_time_to_string(DateAndTime) -> string()
106 date_and_time_to_string(DateAndTime, Validate) -> string()
107 Types:
109 DateAndTime = [int()]
111 Validate = fun(Kind, Data) -> boolean()
112 Converts a DateAndTime list to a printable string, according to
114 the DISPLAY-HINT definition in RFC2579.
115 The validation fun, Validate, allows for a more "flexible" vali‐
117 dation of the DateAndTime argument. Whenever the data is found
118 to not follow RFC2579, the fun is called to allow a more "lax"
119 validation. See the validate_date_and_time/2 function for more
120 info on the Validate fun.
121 date_and_time_to_string2(DateAndTime) -> string()
123 Types:
125 DateAndTime = [int()]
127 Converts a DateAndTime list to a printable string, according to
129 the DISPLAY-HINT definition in RFC2579, with the extension that
130 it also allows the values "hours from UTC" = 14 together with
131 "minutes from UTC" = 0.
132 local_time_to_date_and_time_dst(Local) -> [DateAndTime]
134 Types:
136 Local = {{Y,Mo,D},{H,M,S}}
138 DateAndTime = [int()]
139 Converts a local time value to a list of possible DateAndTime
141 list(s). The local time value on the same format as defined in
142 calendar(3).
143 universal_time_to_date_and_time(UTC) -> DateAndTime
145 Types:
147 UTC = {{Y,Mo,D},{H,M,S}}
149 DateAndTime = [int()]
150 Converts a universal time value to a DateAndTime list. The uni‐
152 versal time value on the same format as defined in calendar(3).
153 validate_date_and_time(DateAndTime) -> bool()
155 validate_date_and_time(DateAndTime, Validate) -> bool()
156 Types:
158 DateAndTime = term()
160 Validate = fun(Kind, Data) -> boolean()
161 Checks if DateAndTime is a correct DateAndTime value, as speci‐
163 fied in RFC2579. This function can be used in instrumentation
164 functions to validate a DateAndTime value.
165 The validation fun, Validate, allows for a more "flexible" vali‐
167 dation of the DateAndTime argument. Whenever the data is found
168 to not follow RFC2579, the fun is called to allow a more "lax"
169 validation. The input to the validation fun looks like this:
170 Kind Data
172 -------------- ----------------------
173 year {Year1, Year2}
174 month Month
175 day Day
176 hour Hour
177 minute Minute
178 seconds Seconds
179 deci_seconds DeciSeconds
180 diff [Sign, Hour, Minute]
181 valid_date {Year, Month, Day}
182 passwd2localized_key(Alg, Passwd, EngineID) -> Key
185 Types:
187 Alg = algorithm()
189 algorithm() = md5 | sha
190 Passwd = string()
191 EngineID = string()
192 Key = list()
193 Generates a key that can be used as an authentication or privacy
195 key using MD5 och SHA. The key is localized for EngineID.
196 octet_string_to_bits(S) -> Val
198 Types:
200 Val = bits()
202 Utility function for converting a value of type OCTET-STRING to
204 BITS.
205 bits_to_octet_string(B) -> Val
207 Types:
209 Val = octet_string()
211 Utility function for converting a value of type BITS to OCTET-
213 STRING.
214 read_mib(FileName) -> {ok, mib()} | {error, Reason}
216 Types:
218 FileName = string()
220 mib() = #mib{}
221 Reason = term()
222 Read a compiled mib.
224 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile) -> ok | {ok, Cnt} |
226 {error, Reason}
227 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) ->
228 ok | {ok, Cnt} | {error, Reason}
229 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Block |
230 Stop) -> ok | {ok, Cnt} | {error, Reason}
231 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop, Block)
232 -> ok | {ok, Cnt} | {error, Reason}
233 Types:
235 LogDir = string()
237 Mibs = [MibName]
238 OutFile = string()
239 MibName = string()
240 LogName = string()
241 LogFile = string()
242 Start = Stop = null | datetime() | {local_time,datetime()} |
243 {universal_time,datetime()}
244 Block = boolean()
245 Cnt = {NumOK, NumERR}
246 NumOK = non_neg_integer()
247 NumERR = pos_integer()
248 Reason = term()
249 Converts an Audit Trail Log to a readable text file, where each
251 item has a trailing TAB character, and any TAB character in the
252 body of an item has been replaced by ESC TAB.
253 The function can be used on a running system, or by copying the
255 entire log directory and calling this function. SNMP must be
256 running in order to provide MIB information.
257 LogDir is the name of the directory where the audit trail log is
259 stored. Mibs is a list of Mibs to be used. The function uses the
260 information in the Mibs to convert for example object identi‐
261 fiers to their symbolic name. OutFile is the name of the gener‐
262 ated text-file. LogName is the name of the log, LogFile is the
263 name of the log file. Start is the start (first) date and time
264 from which log events will be converted and Stop is the stop
265 (last) date and time to which log events will be converted. The
266 Block argument indicates if the log should be blocked during
267 conversion. This could be usefull when converting large logs
268 (when otherwise the log could wrap during conversion). Defaults
269 to true.
270 The format of an audit trail log text item is as follows:
272 Tag Addr - Community [TimeStamp] Vsn
274 PDU
275 where Tag is request, response, report, trap or inform; Addr is
277 IP:Port (or comma space separated list of such); Community is
278 the community parameter (SNMP version v1 and v2), or
279 SecLevel:"AuthEngineID":"UserName" (SNMP v3); TimeStamp is a
280 date and time stamp, and Vsn is the SNMP version. PDU is a tex‐
281 tual version of the protocol data unit. There is a new line
282 between Vsn and PDU.
283 If the entire log is successfully converted, the function will
285 return ok. If one of more entries fail to convert, the function
286 will instead return {ok, {NumOK, NumERR}}, where the counters
287 indicate how many valid and erroneous entries where found. If
288 instead {error, Reason} is returned, the conversion encountered
289 a fatal error and where either never done of aborted midway.
290 log_to_io(LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error,
292 Reason}
293 log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) -> ok | {ok,
294 Cnt} | {error, Reason}
295 log_to_io(LogDir, Mibs, LogName, LogFile, Start, Block | Stop) -> ok |
296 {ok, Cnt} | {error, Reason}
297 log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop, Block) -> ok |
298 {ok, Cnt} | {error, Reason}
299 Types:
301 LogDir = string()
303 Mibs = [MibName]
304 MibName = string()
305 LogName = string()
306 LogFile = string()
307 Start = Stop = null | datetime() | {local_time,datetime()} |
308 {universal_time,datetime()}
309 Cnt = {NumOK, NumERR}
310 NumOK = non_neg_integer()
311 NumERR = pos_integer()
312 Reason = term()
313 Converts an Audit Trail Log to a readable format and prints it
315 on stdio. See log_to_txt above for more info.
316 change_log_size(LogName, NewSize) -> ok | {error, Reason}
318 Types:
320 LogName = string()
322 NewSize = {MaxBytes, MaxFiles}
323 MaxBytes = integer()
324 MaxFiles = integer()
325 Reason = term()
326 Changes the log size of the Audit Trail Log. The application
328 must be configured to use the audit trail log function. Please
329 refer to disk_log(3) in Kernel Reference Manual for a descrip‐
330 tion of how to change the log size.
331 The change is permanent, as long as the log is not deleted. That
333 means, the log size is remembered across reboots.
334 print_version_info() -> void()
336 print_version_info(Prefix) -> void()
337 Types:
339 Prefix = string() | integer()
341 Utility function(s) to produce a formatted printout of the ver‐
343 sions info generated by the versions1 function
344 This is the same as doing, e.g.:
346 {ok, V} = snmp:versions1(),
348 snmp:print_versions(V).
349 versions1() -> {ok, Info} | {error, Reason}
352 versions2() -> {ok, Info} | {error, Reason}
353 Types:
355 Info = [info()]
357 info() = term()
358 Reason = term()
359 Utility functions used to retrieve some system and application
361 info.
362 The difference between the two functions is in how they get the
364 modules to check. versions1 uses the app-file and versions2 uses
365 the function application:get_key.
366 print_versions(VersionInfo) -> void()
368 print_versions(Prefix, VersionInfo) -> void()
369 Types:
371 VersionInfo = [version_info()]
373 version_info() = term()
374 Prefix = string() | integer()
375 Utility function to produce a formatted printout of the versions
377 info generated by the versions1 and versions2 functions
378 Example:
380 {ok, V} = snmp:versions1(),
382 snmp:print_versions(V).
383 enable_trace() -> void()
386 Starts a dbg tracer that prints trace events to stdout (using
388 plain io:format after a minor formatting).
389 disable_trace() -> void()
391 Stop the tracer.
393 set_trace(Targets) -> void()
395 Types:
397 Targets = target() | targets()
399 target() = module()
400 module() = atom()
401 targets() = [target() | {target(), target_options()}]
402 target_options() = [target_option()]
403 target_option() = {return_trace, boolean()} | {scope,
404 scope()}
405 scope() = all_functions | exported_functions | func‐
406 tion_name() | {function_name(), function_arity()}
407 function_name() = atom()
408 function_arity() = integer() >= 0
409 This function is used to set up default trace on function(s) for
411 the given module or modules. The scope of the trace will be all
412 exported functions (both the call info and the return value).
413 Timestamp info will also be included.
414 reset_trace(Targets) -> void()
416 Types:
418 Targets = module() | modules()
420 modules() = [module()]
421 module() = atom()
422 This function is used to reset (disable) trace for the given
424 module(s).
425 set_trace(Targets, Opts) -> void()
427 Types:
429 Targets = target() | targets()
431 target() = module()
432 module() = atom()
433 targets() = [target() | {target(), target_options()}]
434 target_options() = [target_option()]
435 target_option() = {return_trace, boolean()} | {scope,
436 scope()}
437 scope() = all_functions | exported_functions | func‐
438 tion_name() | {function_name(), function_arity()}
439 function_name() = atom()
440 function_arity() = integer() >= 0
441 Opts = disable | trace_options()
442 trace_options() = [trace_option()]
443 trace_option() = {timestamp, boolean()} | target_option()
444 This function is used to set up trace on function(s) for the
446 given module or modules.
447 The example below sets up trace on the exported functions
449 (default) of module snmp_generic and all functions of module
450 snmp_generic_mnesia. With return values (which is default) and
451 timestamps in both cases (which is also default):
452 snmp:enable_trace(),
454 snmp:set_trace([snmp_generic,
455 {snmp_generic_mnesia, [{scope, all_functions}]}]),
456 .
457 .
458 .
459 snmp:set_trace(snmp_generic, disable),
460 .
461 .
462 .
463 snmp:disable_trace(),
464
467 calendar(3)
468Ericsson AB snmp 5.5 snmp(3)