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 ap‐
56 plication.
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 | sha224 | sha256 | sha384 | sha512
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, SHA, SHA224, SHA256, SHA384 or SHA512. The key is
196 localized for EngineID.
197 octet_string_to_bits(S) -> Val
199 Types:
201 Val = bits()
203 Utility function for converting a value of type OCTET-STRING to
205 BITS.
206 bits_to_octet_string(B) -> Val
208 Types:
210 Val = octet_string()
212 Utility function for converting a value of type BITS to OCTET-
214 STRING.
215 read_mib(FileName) -> {ok, mib()} | {error, Reason}
217 Types:
219 FileName = string()
221 mib() = #mib{}
222 Reason = term()
223 Read a compiled mib.
225 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile) -> ok | {ok, Cnt} |
227 {error, Reason}
228 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) ->
229 ok | {ok, Cnt} | {error, Reason}
230 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Block |
231 Stop) -> ok | {ok, Cnt} | {error, Reason}
232 log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop, Block)
233 -> ok | {ok, Cnt} | {error, Reason}
234 Types:
236 LogDir = string()
238 Mibs = [MibName]
239 OutFile = string()
240 MibName = string()
241 LogName = string()
242 LogFile = string()
243 Start = Stop = null | datetime() | {local_time,datetime()} |
244 {universal_time,datetime()}
245 Block = boolean()
246 Cnt = {NumOK, NumERR}
247 NumOK = non_neg_integer()
248 NumERR = pos_integer()
249 Reason = term()
250 Converts an Audit Trail Log to a readable text file, where each
252 item has a trailing TAB character, and any TAB character in the
253 body of an item has been replaced by ESC TAB.
254 The function can be used on a running system, or by copying the
256 entire log directory and calling this function. SNMP must be
257 running in order to provide MIB information.
258 LogDir is the name of the directory where the audit trail log is
260 stored. Mibs is a list of Mibs to be used. The function uses the
261 information in the Mibs to convert for example object identi‐
262 fiers to their symbolic name. OutFile is the name of the gener‐
263 ated text-file. LogName is the name of the log, LogFile is the
264 name of the log file. Start is the start (first) date and time
265 from which log events will be converted and Stop is the stop
266 (last) date and time to which log events will be converted. The
267 Block argument indicates if the log should be blocked during
268 conversion. This could be useful when converting large logs
269 (when otherwise the log could wrap during conversion). Defaults
270 to true.
271 The format of an audit trail log text item is as follows:
273 Tag Addr - Community [TimeStamp] Vsn
275 PDU
276 where Tag is request, response, report, trap or inform; Addr is
278 IP:Port (or comma space separated list of such); Community is
279 the community parameter (SNMP version v1 and v2), or Se‐
280 cLevel:"AuthEngineID":"UserName" (SNMP v3); TimeStamp is a date
281 and time stamp, and Vsn is the SNMP version. PDU is a textual
282 version of the protocol data unit. There is a new line between
283 Vsn and PDU.
284 If the entire log is successfully converted, the function will
286 return ok. If one of more entries fail to convert, the function
287 will instead return {ok, {NumOK, NumERR}}, where the counters
288 indicate how many valid and erroneous entries where found. If
289 instead {error, Reason} is returned, the conversion encountered
290 a fatal error and where either never done of aborted midway.
291 log_to_io(LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error,
293 Reason}
294 log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) -> ok | {ok,
295 Cnt} | {error, Reason}
296 log_to_io(LogDir, Mibs, LogName, LogFile, Start, Block | Stop) -> ok |
297 {ok, Cnt} | {error, Reason}
298 log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop, Block) -> ok |
299 {ok, Cnt} | {error, Reason}
300 Types:
302 LogDir = string()
304 Mibs = [MibName]
305 MibName = string()
306 LogName = string()
307 LogFile = string()
308 Start = Stop = null | datetime() | {local_time,datetime()} |
309 {universal_time,datetime()}
310 Cnt = {NumOK, NumERR}
311 NumOK = non_neg_integer()
312 NumERR = pos_integer()
313 Reason = term()
314 Converts an Audit Trail Log to a readable format and prints it
316 on stdio. See log_to_txt above for more info.
317 change_log_size(LogName, NewSize) -> ok | {error, Reason}
319 Types:
321 LogName = string()
323 NewSize = {MaxBytes, MaxFiles}
324 MaxBytes = integer()
325 MaxFiles = integer()
326 Reason = term()
327 Changes the log size of the Audit Trail Log. The application
329 must be configured to use the audit trail log function. Please
330 refer to disk_log(3) in Kernel Reference Manual for a descrip‐
331 tion of how to change the log size.
332 The change is permanent, as long as the log is not deleted. That
334 means, the log size is remembered across reboots.
335 print_version_info() -> void()
337 print_version_info(Prefix) -> void()
338 Types:
340 Prefix = string() | integer()
342 Utility function(s) to produce a formatted printout of the ver‐
344 sions info generated by the versions1 function
345 This is the same as doing, e.g.:
347 {ok, V} = snmp:versions1(),
349 snmp:print_versions(V).
350 versions1() -> {ok, Info} | {error, Reason}
353 versions2() -> {ok, Info} | {error, Reason}
354 Types:
356 Info = [info()]
358 info() = term()
359 Reason = term()
360 Utility functions used to retrieve some system and application
362 info.
363 The difference between the two functions is in how they get the
365 modules to check. versions1 uses the app-file and versions2 uses
366 the function application:get_key.
367 print_versions(VersionInfo) -> void()
369 print_versions(Prefix, VersionInfo) -> void()
370 Types:
372 VersionInfo = [version_info()]
374 version_info() = term()
375 Prefix = string() | integer()
376 Utility function to produce a formatted printout of the versions
378 info generated by the versions1 and versions2 functions
379 Example:
381 {ok, V} = snmp:versions1(),
383 snmp:print_versions(V).
384 enable_trace() -> void()
387 Starts a dbg tracer that prints trace events to stdout (using
389 plain io:format after a minor formatting).
390 disable_trace() -> void()
392 Stop the tracer.
394 set_trace(Targets) -> void()
396 Types:
398 Targets = target() | targets()
400 target() = module()
401 module() = atom()
402 targets() = [target() | {target(), target_options()}]
403 target_options() = [target_option()]
404 target_option() = {return_trace, boolean()} | {scope,
405 scope()}
406 scope() = all_functions | exported_functions | func‐
407 tion_name() | {function_name(), function_arity()}
408 function_name() = atom()
409 function_arity() = integer() >= 0
410 This function is used to set up default trace on function(s) for
412 the given module or modules. The scope of the trace will be all
413 exported functions (both the call info and the return value).
414 Timestamp info will also be included.
415 reset_trace(Targets) -> void()
417 Types:
419 Targets = module() | modules()
421 modules() = [module()]
422 module() = atom()
423 This function is used to reset (disable) trace for the given
425 module(s).
426 set_trace(Targets, Opts) -> void()
428 Types:
430 Targets = target() | targets()
432 target() = module()
433 module() = atom()
434 targets() = [target() | {target(), target_options()}]
435 target_options() = [target_option()]
436 target_option() = {return_trace, boolean()} | {scope,
437 scope()}
438 scope() = all_functions | exported_functions | func‐
439 tion_name() | {function_name(), function_arity()}
440 function_name() = atom()
441 function_arity() = integer() >= 0
442 Opts = disable | trace_options()
443 trace_options() = [trace_option()]
444 trace_option() = {timestamp, boolean()} | target_option()
445 This function is used to set up trace on function(s) for the
447 given module or modules.
448 The example below sets up trace on the exported functions (de‐
450 fault) of module snmp_generic and all functions of module
451 snmp_generic_mnesia. With return values (which is default) and
452 timestamps in both cases (which is also default):
453 snmp:enable_trace(),
455 snmp:set_trace([snmp_generic,
456 {snmp_generic_mnesia, [{scope, all_functions}]}]),
457 .
458 .
459 .
460 snmp:set_trace(snmp_generic, disable),
461 .
462 .
463 .
464 snmp:disable_trace(),
465
468 calendar(3)
469Ericsson AB snmp 5.13.5 snmp(3)