Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
snmp(3)			   Erlang Module Definition		       snmp(3)

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	(pass-
	      word 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 ap-
	      plication.

	      Note that	the only way to	actually start the agent in  this  way
	      is  to  add the agent related config after starting the applica-
	      tion (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 applica-
	      tion (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(3).

       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" vali-
	      dation  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(3).

       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 uni-
	      versal time value	on the same format as defined in calendar(3).

       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	speci-
	      fied  in	RFC2579.  This function	can be used in instrumentation
	      functions	to validate a DateAndTime value.

	      The validation fun, Validate, allows for a more "flexible" vali-
	      dation  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 | sha224 | sha256 | sha384 | sha512
		 Passwd	= string()
		 EngineID = string()
		 Key = list()

	      Generates	a key that can be used as an authentication or privacy
	      key using	MD5, SHA, SHA224, SHA256, SHA384 or SHA512. 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  identi-
	      fiers  to	their symbolic name. OutFile is	the name of the	gener-
	      ated 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 Se-
	      cLevel:"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(3) in Kernel Reference Manual for  a  descrip-
	      tion 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  ver-
	      sions 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  |	 func-
		 tion_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  |	 func-
		 tion_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 (de-
	      fault) 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(3)

Ericsson AB			   snmp	5.11			       snmp(3)

NAME | DESCRIPTION | COMMON DATA TYPES | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=snmp&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help