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 ap‐
56              plication.
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 | sha224 | sha256 | sha384 | sha512
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, SHA, SHA224, SHA256, SHA384 or SHA512. The key is
196              localized for EngineID.
197
198       octet_string_to_bits(S) -> Val
199
200              Types:
201
202                 Val = bits()
203
204              Utility  function for converting a value of type OCTET-STRING to
205              BITS.
206
207       bits_to_octet_string(B) -> Val
208
209              Types:
210
211                 Val = octet_string()
212
213              Utility function for converting a value of type BITS  to  OCTET-
214              STRING.
215
216       read_mib(FileName) -> {ok, mib()} | {error, Reason}
217
218              Types:
219
220                 FileName = string()
221                 mib() = #mib{}
222                 Reason = term()
223
224              Read a compiled mib.
225
226       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
235              Types:
236
237                 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
251              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
255              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
259              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
272              The format of an audit trail log text item is as follows:
273
274              Tag Addr - Community [TimeStamp] Vsn
275              PDU
276
277              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
285              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
292       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
301              Types:
302
303                 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
315              Converts  an  Audit Trail Log to a readable format and prints it
316              on stdio. See log_to_txt above for more info.
317
318       change_log_size(LogName, NewSize) -> ok | {error, Reason}
319
320              Types:
321
322                 LogName = string()
323                 NewSize = {MaxBytes, MaxFiles}
324                 MaxBytes = integer()
325                 MaxFiles = integer()
326                 Reason = term()
327
328              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
333              The change is permanent, as long as the log is not deleted. That
334              means, the log size is remembered across reboots.
335
336       print_version_info() -> void()
337       print_version_info(Prefix) -> void()
338
339              Types:
340
341                 Prefix = string() | integer()
342
343              Utility function(s) to produce a formatted printout of the  ver‐
344              sions info generated by the versions1 function
345
346              This is the same as doing, e.g.:
347
348                         {ok, V} = snmp:versions1(),
349                         snmp:print_versions(V).
350
351
352       versions1() -> {ok, Info} | {error, Reason}
353       versions2() -> {ok, Info} | {error, Reason}
354
355              Types:
356
357                 Info = [info()]
358                 info() = term()
359                 Reason = term()
360
361              Utility  functions  used to retrieve some system and application
362              info.
363
364              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
368       print_versions(VersionInfo) -> void()
369       print_versions(Prefix, VersionInfo) -> void()
370
371              Types:
372
373                 VersionInfo = [version_info()]
374                 version_info() = term()
375                 Prefix = string() | integer()
376
377              Utility function to produce a formatted printout of the versions
378              info generated by the versions1 and versions2 functions
379
380              Example:
381
382                         {ok, V} = snmp:versions1(),
383                         snmp:print_versions(V).
384
385
386       enable_trace() -> void()
387
388              Starts  a  dbg  tracer that prints trace events to stdout (using
389              plain io:format after a minor formatting).
390
391       disable_trace() -> void()
392
393              Stop the tracer.
394
395       set_trace(Targets) -> void()
396
397              Types:
398
399                 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
411              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
416       reset_trace(Targets) -> void()
417
418              Types:
419
420                 Targets = module() | modules()
421                 modules() = [module()]
422                 module() = atom()
423
424              This  function  is  used  to reset (disable) trace for the given
425              module(s).
426
427       set_trace(Targets, Opts) -> void()
428
429              Types:
430
431                 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
446              This function is used to set up trace  on  function(s)  for  the
447              given module or modules.
448
449              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
454                     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
466

SEE ALSO

468       calendar(3)
469
470
471
472Ericsson AB                       snmp 5.13.5                          snmp(3)
Impressum