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

NAME

6       snmp - Interface functions to the SNMP toolkit
7

DESCRIPTION

9       The module snmp contains interface functions to the SNMP toolkit.
10

COMMON DATA TYPES

12       The following data-types are used in the functions below:
13
14         * datetime() = {date(), time()}
15
16           See calendar for more info.
17

EXPORTS

19       config() -> ok | {error, Reason}
20
21              A  simple  interactive  configuration tool. Simple configuration
22              files can be generated, but more  complex  configurations  still
23              have to be edited manually.
24
25              The  tool  is  a textual based tool that asks some questions and
26              generates sys.config and *.conf files.
27
28              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
32              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
36       start() -> ok | {error, Reason}
37       start(Type) -> ok | {error, Reason}
38
39              Types:
40
41                 Type = start_type()
42
43              Starts the SNMP application.
44
45              See application for more info.
46
47       start_agent() -> ok | {error, Reason}
48       start_agent(Type) -> ok | {error, Reason}
49
50              Types:
51
52                 Type = start_type()
53
54              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
58              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
64              The default value for Type is normal.
65
66       start_manager() -> ok | {error, Reason}
67       start_manager(Type) -> ok | {error, Reason}
68
69              Types:
70
71                 Type = start_type()
72
73              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
77              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
83              The default value for Type is normal.
84
85       date_and_time() -> DateAndTime
86
87              Types:
88
89                 DateAndTime = [int()]
90
91              Returns current date and time as the data type  DateAndTime,  as
92              specified in RFC1903. This is an OCTET STRING.
93
94       date_and_time_to_universal_time_dst(DateAndTime) -> [utc()]
95
96              Types:
97
98                 DateAndTime = [int()]
99                 utc() = {{Y,Mo,D},{H,M,S}}
100
101              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
105       date_and_time_to_string(DateAndTime) -> string()
106       date_and_time_to_string(DateAndTime, Validate) -> string()
107
108              Types:
109
110                 DateAndTime = [int()]
111                 Validate = fun(Kind, Data) -> boolean()
112
113              Converts  a DateAndTime list to a printable string, according to
114              the DISPLAY-HINT definition in RFC2579.
115
116              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
122       date_and_time_to_string2(DateAndTime) -> string()
123
124              Types:
125
126                 DateAndTime = [int()]
127
128              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
133       local_time_to_date_and_time_dst(Local) -> [DateAndTime]
134
135              Types:
136
137                 Local = {{Y,Mo,D},{H,M,S}}
138                 DateAndTime = [int()]
139
140              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
144       universal_time_to_date_and_time(UTC) -> DateAndTime
145
146              Types:
147
148                 UTC = {{Y,Mo,D},{H,M,S}}
149                 DateAndTime = [int()]
150
151              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
154       validate_date_and_time(DateAndTime) -> bool()
155       validate_date_and_time(DateAndTime, Validate) -> bool()
156
157              Types:
158
159                 DateAndTime = term()
160                 Validate = fun(Kind, Data) -> boolean()
161
162              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
166              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
171                        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
183
184       passwd2localized_key(Alg, Passwd, EngineID) -> Key
185
186              Types:
187
188                 Alg = algorithm()
189                 algorithm() = md5 | sha
190                 Passwd = string()
191                 EngineID = string()
192                 Key = list()
193
194              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
197       octet_string_to_bits(S) -> Val
198
199              Types:
200
201                 Val = bits()
202
203              Utility function for converting a value of type OCTET-STRING  to
204              BITS.
205
206       bits_to_octet_string(B) -> Val
207
208              Types:
209
210                 Val = octet_string()
211
212              Utility  function  for converting a value of type BITS to OCTET-
213              STRING.
214
215       read_mib(FileName) -> {ok, mib()} | {error, Reason}
216
217              Types:
218
219                 FileName = string()
220                 mib() = #mib{}
221                 Reason = term()
222
223              Read a compiled mib.
224
225       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
234              Types:
235
236                 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
250              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
254              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
258              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
271              The format of an audit trail log text item is as follows:
272
273              Tag Addr - Community [TimeStamp] Vsn
274              PDU
275
276              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
284              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
291       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
300              Types:
301
302                 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
314              Converts an Audit Trail Log to a readable format and  prints  it
315              on stdio. See log_to_txt above for more info.
316
317       change_log_size(LogName, NewSize) -> ok | {error, Reason}
318
319              Types:
320
321                 LogName = string()
322                 NewSize = {MaxBytes, MaxFiles}
323                 MaxBytes = integer()
324                 MaxFiles = integer()
325                 Reason = term()
326
327              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
332              The change is permanent, as long as the log is not deleted. That
333              means, the log size is remembered across reboots.
334
335       print_version_info() -> void()
336       print_version_info(Prefix) -> void()
337
338              Types:
339
340                 Prefix = string() | integer()
341
342              Utility  function(s) to produce a formatted printout of the ver‐
343              sions info generated by the versions1 function
344
345              This is the same as doing, e.g.:
346
347                         {ok, V} = snmp:versions1(),
348                         snmp:print_versions(V).
349
350
351       versions1() -> {ok, Info} | {error, Reason}
352       versions2() -> {ok, Info} | {error, Reason}
353
354              Types:
355
356                 Info = [info()]
357                 info() = term()
358                 Reason = term()
359
360              Utility functions used to retrieve some system  and  application
361              info.
362
363              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
367       print_versions(VersionInfo) -> void()
368       print_versions(Prefix, VersionInfo) -> void()
369
370              Types:
371
372                 VersionInfo = [version_info()]
373                 version_info() = term()
374                 Prefix = string() | integer()
375
376              Utility function to produce a formatted printout of the versions
377              info generated by the versions1 and versions2 functions
378
379              Example:
380
381                         {ok, V} = snmp:versions1(),
382                         snmp:print_versions(V).
383
384
385       enable_trace() -> void()
386
387              Starts a dbg tracer that prints trace events  to  stdout  (using
388              plain io:format after a minor formatting).
389
390       disable_trace() -> void()
391
392              Stop the tracer.
393
394       set_trace(Targets) -> void()
395
396              Types:
397
398                 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
410              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
415       reset_trace(Targets) -> void()
416
417              Types:
418
419                 Targets = module() | modules()
420                 modules() = [module()]
421                 module() = atom()
422
423              This function is used to reset (disable)  trace  for  the  given
424              module(s).
425
426       set_trace(Targets, Opts) -> void()
427
428              Types:
429
430                 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
445              This  function  is  used  to set up trace on function(s) for the
446              given module or modules.
447
448              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
453                     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
465

SEE ALSO

467       calendar(3)
468
469
470
471Ericsson AB                        snmp 5.5                            snmp(3)
Impressum