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
		 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 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.2.12			       snmp(3)
NAME | DESCRIPTION | COMMON DATA TYPES | EXPORTS | SEE ALSO

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

home | help