Provided by: erlang-manpages_22.0.7+dfsg-1_all bug

NAME

       snmp - Interface functions to the SNMP toolkit

DESCRIPTION

       The module snmp contains interface functions to the SNMP toolkit.

COMMON DATA TYPES

       The following data-types are used in the functions below:

         * datetime() = {date(), time()}

           See calendar for more info.

EXPORTS

       config() -> ok | {error, Reason}

              A  simple  interactive  configuration  tool.  Simple  configuration  files  can  be
              generated, but more complex configurations still have to be edited manually.

              The tool is a textual based tool that asks some questions and generates  sys.config
              and *.conf files.

              Note  that  if the application shall support version 3, then the crypto app must be
              started before running this function (password generation).

              Note also that some of the configuration files for the agent and manager share  the
              same names. This means that they have to be stored in different directories!

       start() -> ok | {error, Reason}
       start(Type) -> ok | {error, Reason}

              Types:

                 Type = start_type()

              Starts the SNMP application.

              See application for more info.

       start_agent() -> ok | {error, Reason}
       start_agent(Type) -> ok | {error, Reason}

              Types:

                 Type = start_type()

              The  SNMP application consists of several entities, of which the agent is one. This
              function starts the agent entity of the application.

              Note that the only way to actually start the agent in this way is to add the  agent
              related  config after starting the application (e.g it cannot be part of the normal
              application config; sys.config). This is done by calling: application:set_env(snmp,
              agent, Conf).

              The default value for Type is normal.

       start_manager() -> ok | {error, Reason}
       start_manager(Type) -> ok | {error, Reason}

              Types:

                 Type = start_type()

              The  SNMP  application  consists  of several entities, of which the manager is one.
              This function starts the manager entity of the application.

              Note that the only way to actually start the manager in this  way  is  to  add  the
              manager related config after starting the application (e.g it cannot be part of the
              normal   application   config;   sys.config).   This   is    done    by    calling:
              application:set_env(snmp, manager, Conf).

              The default value for Type is normal.

       date_and_time() -> DateAndTime

              Types:

                 DateAndTime = [int()]

              Returns  current  date  and  time  as  the  data  type DateAndTime, as specified in
              RFC1903. This is an OCTET STRING.

       date_and_time_to_universal_time_dst(DateAndTime) -> [utc()]

              Types:

                 DateAndTime = [int()]
                 utc() = {{Y,Mo,D},{H,M,S}}

              Converts a DateAndTime list to a list of possible universal time(s). The  universal
              time value on the same format as defined in calendar(3erl).

       date_and_time_to_string(DateAndTime) -> string()
       date_and_time_to_string(DateAndTime, Validate) -> string()

              Types:

                 DateAndTime = [int()]
                 Validate = fun(Kind, Data) -> boolean()

              Converts  a  DateAndTime  list to a printable string, according to the DISPLAY-HINT
              definition in RFC2579.

              The validation fun, Validate, allows  for  a  more  "flexible"  validation  of  the
              DateAndTime  argument. Whenever the data is found to not follow RFC2579, the fun is
              called to allow a more "lax" validation. See the validate_date_and_time/2  function
              for more info on the Validate fun.

       date_and_time_to_string2(DateAndTime) -> string()

              Types:

                 DateAndTime = [int()]

              Converts  a  DateAndTime  list to a printable string, according to the DISPLAY-HINT
              definition in RFC2579, with the extension that it also  allows  the  values  "hours
              from UTC" = 14 together with "minutes from UTC" = 0.

       local_time_to_date_and_time_dst(Local) -> [DateAndTime]

              Types:

                 Local = {{Y,Mo,D},{H,M,S}}
                 DateAndTime = [int()]

              Converts  a  local  time value to a list of possible DateAndTime list(s). The local
              time value on the same format as defined in calendar(3erl).

       universal_time_to_date_and_time(UTC) -> DateAndTime

              Types:

                 UTC = {{Y,Mo,D},{H,M,S}}
                 DateAndTime = [int()]

              Converts a universal time value to a DateAndTime list. The universal time value  on
              the same format as defined in calendar(3erl).

       validate_date_and_time(DateAndTime) -> bool()
       validate_date_and_time(DateAndTime, Validate) -> bool()

              Types:

                 DateAndTime = term()
                 Validate = fun(Kind, Data) -> boolean()

              Checks if DateAndTime is a correct DateAndTime value, as specified in RFC2579. This
              function can be used in instrumentation functions to validate a DateAndTime value.

              The validation fun, Validate, allows  for  a  more  "flexible"  validation  of  the
              DateAndTime  argument. Whenever the data is found to not follow RFC2579, the fun is
              called to allow a more "lax" validation. The input to the validation fun looks like
              this:

                        Kind             Data
                        --------------   ----------------------
                        year             {Year1, Year2}
                        month            Month
                        day              Day
                        hour             Hour
                        minute           Minute
                        seconds          Seconds
                        deci_seconds     DeciSeconds
                        diff             [Sign, Hour, Minute]
                        valid_date       {Year, Month, Day}

       passwd2localized_key(Alg, Passwd, EngineID) -> Key

              Types:

                 Alg = algorithm()
                 algorithm() = md5 | sha
                 Passwd = string()
                 EngineID = string()
                 Key = list()

              Generates  a key that can be used as an authentication or privacy key using MD5 och
              SHA. The key is localized for EngineID.

       octet_string_to_bits(S) -> Val

              Types:

                 Val = bits()

              Utility function for converting a value of type OCTET-STRING to BITS.

       bits_to_octet_string(B) -> Val

              Types:

                 Val = octet_string()

              Utility function for converting a value of type BITS to OCTET-STRING.

       read_mib(FileName) -> {ok, mib()} | {error, Reason}

              Types:

                 FileName = string()
                 mib() = #mib{}
                 Reason = term()

              Read a compiled mib.

       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) -> ok  |  {ok,  Cnt}  |
       {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Block | Stop) -> ok | {ok, Cnt}
       | {error, Reason}
       log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop, Block) -> ok | {ok,  Cnt}
       | {error, Reason}

              Types:

                 LogDir = string()
                 Mibs = [MibName]
                 OutFile = string()
                 MibName = string()
                 LogName = string()
                 LogFile = string()
                 Start    =    Stop   =   null   |   datetime()   |   {local_time,datetime()}   |
                 {universal_time,datetime()}
                 Block = boolean()
                 Cnt = {NumOK, NumERR}
                 NumOK = non_neg_integer()
                 NumERR = pos_integer()
                 Reason = term()

              Converts an Audit Trail Log to a readable text file, where each item has a trailing
              TAB  character,  and  any TAB character in the body of an item has been replaced by
              ESC TAB.

              The function can be used on  a  running  system,  or  by  copying  the  entire  log
              directory  and  calling this function. SNMP must be running in order to provide MIB
              information.

              LogDir is the name of the directory where the audit trail log is stored. Mibs is  a
              list  of  Mibs to be used. The function uses the information in the Mibs to convert
              for example object identifiers to their symbolic name. OutFile is the name  of  the
              generated text-file. LogName is the name of the log, LogFile is the name of the log
              file. Start is the start (first) date and  time  from  which  log  events  will  be
              converted  and  Stop  is  the stop (last) date and time to which log events will be
              converted. The Block argument  indicates  if  the  log  should  be  blocked  during
              conversion.  This  could  be usefull when converting large logs (when otherwise the
              log could wrap during conversion). Defaults to true.

              The format of an audit trail log text item is as follows:

              Tag Addr - Community [TimeStamp] Vsn
              PDU

              where Tag is request, response, report, trap or inform; Addr is IP:Port  (or  comma
              space  separated  list of such); Community is the community parameter (SNMP version
              v1 and v2), or SecLevel:"AuthEngineID":"UserName" (SNMP v3); TimeStamp  is  a  date
              and  time  stamp,  and  Vsn  is  the  SNMP version. PDU is a textual version of the
              protocol data unit. There is a new line between Vsn and PDU.

              If the entire log is successfully converted, the function will return ok. If one of
              more  entries  fail  to  convert,  the  function  will  instead return {ok, {NumOK,
              NumERR}}, where the counters indicate how many valid and  erroneous  entries  where
              found.  If  instead {error, Reason} is returned, the conversion encountered a fatal
              error and where either never done of aborted midway.

       log_to_io(LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) ->  ok  |  {ok,  Cnt}  |  {error,
       Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Start, Block | Stop) -> ok | {ok, Cnt} | {error,
       Reason}
       log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop, Block) -> ok | {ok, Cnt} |  {error,
       Reason}

              Types:

                 LogDir = string()
                 Mibs = [MibName]
                 MibName = string()
                 LogName = string()
                 LogFile = string()
                 Start    =    Stop   =   null   |   datetime()   |   {local_time,datetime()}   |
                 {universal_time,datetime()}
                 Cnt = {NumOK, NumERR}
                 NumOK = non_neg_integer()
                 NumERR = pos_integer()
                 Reason = term()

              Converts an Audit Trail Log to a readable  format  and  prints  it  on  stdio.  See
              log_to_txt above for more info.

       change_log_size(LogName, NewSize) -> ok | {error, Reason}

              Types:

                 LogName = string()
                 NewSize = {MaxBytes, MaxFiles}
                 MaxBytes = integer()
                 MaxFiles = integer()
                 Reason = term()

              Changes  the log size of the Audit Trail Log. The application must be configured to
              use the audit  trail  log  function.  Please  refer  to  disk_log(3erl)  in  Kernel
              Reference Manual for a description of how to change the log size.

              The  change  is  permanent,  as long as the log is not deleted. That means, the log
              size is remembered across reboots.

       print_version_info() -> void()
       print_version_info(Prefix) -> void()

              Types:

                 Prefix = string() | integer()

              Utility function(s) to produce a formatted printout of the versions info  generated
              by the versions1 function

              This is the same as doing, e.g.:

                         {ok, V} = snmp:versions1(),
                         snmp:print_versions(V).

       versions1() -> {ok, Info} | {error, Reason}
       versions2() -> {ok, Info} | {error, Reason}

              Types:

                 Info = [info()]
                 info() = term()
                 Reason = term()

              Utility functions used to retrieve some system and application info.

              The  difference  between the two functions is in how they get the modules to check.
              versions1 uses the app-file and versions2 uses the function application:get_key.

       print_versions(VersionInfo) -> void()
       print_versions(Prefix, VersionInfo) -> void()

              Types:

                 VersionInfo = [version_info()]
                 version_info() = term()
                 Prefix = string() | integer()

              Utility function to produce a formatted printout of the versions info generated  by
              the versions1 and versions2 functions

              Example:

                         {ok, V} = snmp:versions1(),
                         snmp:print_versions(V).

       enable_trace() -> void()

              Starts a dbg tracer that prints trace events to stdout (using plain io:format after
              a minor formatting).

       disable_trace() -> void()

              Stop the tracer.

       set_trace(Targets) -> void()

              Types:

                 Targets = target() | targets()
                 target() = module()
                 module() = atom()
                 targets() = [target() | {target(), target_options()}]
                 target_options() = [target_option()]
                 target_option() = {return_trace, boolean()} | {scope, scope()}
                 scope()   =   all_functions   |   exported_functions   |    function_name()    |
                 {function_name(), function_arity()}
                 function_name() = atom()
                 function_arity() = integer() >= 0

              This  function  is used to set up default trace on function(s) for the given module
              or modules. The scope of the trace will be all exported functions  (both  the  call
              info and the return value). Timestamp info will also be included.

       reset_trace(Targets) -> void()

              Types:

                 Targets = module() | modules()
                 modules() = [module()]
                 module() = atom()

              This function is used to reset (disable) trace for the given module(s).

       set_trace(Targets, Opts) -> void()

              Types:

                 Targets = target() | targets()
                 target() = module()
                 module() = atom()
                 targets() = [target() | {target(), target_options()}]
                 target_options() = [target_option()]
                 target_option() = {return_trace, boolean()} | {scope, scope()}
                 scope()    =    all_functions   |   exported_functions   |   function_name()   |
                 {function_name(), function_arity()}
                 function_name() = atom()
                 function_arity() = integer() >= 0
                 Opts = disable | trace_options()
                 trace_options() = [trace_option()]
                 trace_option() = {timestamp, boolean()} | target_option()

              This function is used to set up trace  on  function(s)  for  the  given  module  or
              modules.

              The  example  below  sets  up  trace  on the exported functions (default) of module
              snmp_generic and all functions of module snmp_generic_mnesia.  With  return  values
              (which is default) and timestamps in both cases (which is also default):

                     snmp:enable_trace(),
                     snmp:set_trace([snmp_generic,
                                        {snmp_generic_mnesia, [{scope, all_functions}]}]),
                     .
                     .
                     .
                        snmp:set_trace(snmp_generic, disable),
                     .
                     .
                     .
                     snmp:disable_trace(),

SEE ALSO

       calendar(3erl)