snmp

v5.20.2

snmp

Interface functions to the SNMP toolkit

The module snmp contains interface functions to the SNMP toolkit.

See Also

calendar(3)

Summary

Types

algorithm()

asn1_type()

atl_type()

bits()

The Erlang representation of the SNMP BITS (pseudo) data type.

column()

community()

context_name()

date_and_time_validator()

The input to the validator fun looks like this

date_and_time_validator_kind()

dir()

A string, that is a file path to a directory.

engine_id()

error_index()

0 is used when error status is noError and when error status is an actual error; error index is pos_integer/0.

error_status()

We should really specify all of these, but they are so numerous... Also, normally all you need to know is that 'noError' is ok and everything else is an error.

ivarbind()

log_size()

This is basically a copy of the dlog_size().

log_time()

me()

mib()

mib_name()

mms()

notification()

octet()

octet_string()

oid()

Represent an ASN.1 OBJECT IDENTIFIER.

pdu()

pdu_type()

rfc1903_date_and_time()

The data type DateAndTime, an OCTET STRING, as specified in RFC1903.

row_index()

Denotes the last part of the OID which specifies the index of the row in the table (see RFC1212, 4.1.6 for more information about INDEX).

row_pointer()

sec_level()

sec_model()

sec_name()

snmp_timer()

table_info()

taddress()

tdomain()

time_interval()

trap()

trappdu()

usm_auth_key()

usm_auth_protocol()

usm_name()

usm_priv_key()

usm_priv_protocol()

varbind()

variable_info()

verbosity()

For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

version()

void()

The type is used when a functions return is to be ignored.

Functions

bits_to_octet_string(B)

Utility function for converting a value of type BITS to OCTET-STRING, according to RFC1906, section 8.

change_log_size(LogName, NewSize)

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 description of how to change the log size.

config()

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

date_and_time()

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

date_and_time_to_string2(DAT)

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.

date_and_time_to_string(DAT)

Equivalent to date_and_time_to_string/2.

date_and_time_to_string(DAT, Validate)

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

date_and_time_to_universal_time_dst(DAT)

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).

disable_trace()

Stop the tracer.

enable_trace()

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

local_time_to_date_and_time_dst(Local)

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).

log_to_io(LogDir, Mibs, LogName, LogFile)

Equivalent to log_to_io/7.

log_to_io/5

Equivalent to log_to_io/7.

log_to_io/6

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

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

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile)

Equivalent to log_to_txt/8.

log_to_txt/6

Equivalent to log_to_txt/8.

log_to_txt/7

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

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.

octet_string_to_bits(S)

Utility function for converting a value of type OCTET-STRING to BITS, according to RFC1906, section 8.

passwd2localized_key(Algorithm, Passwd, EngineID)

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.

print_version_info()

Equivalent to print_version_info/1.

print_version_info(Prefix)

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

print_versions(Versions)

Equivalent to print_versions/2.

print_versions(Prefix, Versions)

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

read_mib(FileName)

Read a compiled mib.

reset_trace(Targets)

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

set_trace(Targets)

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.

set_trace(Targets, TraceOpts)

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

start()

Equivalent to start/1.

start(Type)

Starts the SNMP application.

start_agent()

Equivalent to start_agent/1.

start_agent(Type)

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

start_manager()

Equivalent to start_manager/1.

start_manager(Type)

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

stop()

Stops the SNMP application.

universal_time_to_date_and_time(UTC)

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

validate_date_and_time(DateAndTime)

Equivalent to validate_date_and_time/2.

validate_date_and_time(DateAndTime, Validate)

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.

versions1()

Equivalent to versions2/0.

versions2()

Utility functions used to retrieve some system and application info.

Types

algorithm()

(not exported)

-type algorithm() :: md5 | sha | sha224 | sha256 | sha384 | sha512.

asn1_type()

-type asn1_type() ::
          #asn1_type{bertype :: term(),
                     lo :: term(),
                     hi :: term(),
                     assocList :: term(),
                     imported :: term(),
                     aliasname :: term(),
                     implied :: term(),
                     display_hint :: term()}.

atl_type()

-type atl_type() :: read | write | read_write.

bits()

-type bits() :: integer().

The Erlang representation of the SNMP BITS (pseudo) data type.

column()

-type column() :: pos_integer().

community()

-type community() :: snmp_community_mib:name().

context_name()

-type context_name() :: snmp_community_mib:context_name().

date_and_time_validator()

-type date_and_time_validator() ::
          fun((Kind :: date_and_time_validator_kind(), Data :: term()) -> boolean()).

The input to the validator 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}

date_and_time_validator_kind()

-type date_and_time_validator_kind() ::
          year | month | day | hour | minute | seconds | deci_seconds | diff | valid_date.

dir()

-type dir() :: string().

A string, that is a file path to a directory.

engine_id()

-type engine_id() :: snmp_framework_mib:engine_id().

error_index()

-type error_index() :: non_neg_integer().

0 is used when error status is noError and when error status is an actual error; error index is pos_integer/0.

error_status()

-type error_status() :: noError | atom().

We should really specify all of these, but they are so numerous... Also, normally all you need to know is that 'noError' is ok and everything else is an error.

ivarbind()

-type ivarbind() :: #ivarbind{status :: term(), mibentry :: term(), varbind :: term()}.

log_size()

-type log_size() ::
          infinity | pos_integer() | {MaxNoBytes :: pos_integer(), MaxNoFiles :: pos_integer()}.

This is basically a copy of the dlog_size().

log_time()

-type log_time() ::
          calendar:datetime() |
          {local_time, calendar:datetime()} |
          {universal_time, calendar:datetime()}.

me()

-type me() ::
          #me{oid :: term(),
              entrytype :: term(),
              aliasname :: term(),
              asn1_type :: term(),
              access :: term(),
              mfa :: term(),
              imported :: term(),
              assocList :: term(),
              description :: term(),
              units :: term()}.

mib()

-type mib() ::
          #mib{misc :: term(),
               mib_format_version :: term(),
               name :: term(),
               module_identity :: term(),
               mes :: term(),
               asn1_types :: term(),
               traps :: term(),
               variable_infos :: term(),
               table_infos :: term(),
               imports :: term()}.

mib_name()

-type mib_name() :: string().

mms()

-type mms() :: snmp_framework_mib:max_message_size().

notification()

-type notification() ::
          #notification{trapname :: term(), oid :: term(), oidobjects :: term(), description :: term()}.

octet()

-type octet() :: 0..255.

octet_string()

-type octet_string() :: [octet()].

oid()

-type oid() :: [non_neg_integer()].

Represent an ASN.1 OBJECT IDENTIFIER.

pdu()

-type pdu() ::
          #pdu{type :: term(),
               request_id :: term(),
               error_status :: term(),
               error_index :: term(),
               varbinds :: term()}.

pdu_type()

-type pdu_type() :: snmp_pdus:pdu_type().

rfc1903_date_and_time()

-type rfc1903_date_and_time() :: octet_string().

The data type DateAndTime, an OCTET STRING, as specified in RFC1903.

row_index()

-type row_index() :: oid().

Denotes the last part of the OID which specifies the index of the row in the table (see RFC1212, 4.1.6 for more information about INDEX).

row_pointer()

-type row_pointer() :: oid().

Note

"Represents a pointer to a conceptual row. The value is the name of the instance of the first accessible columnar object in the conceptual row."

OBJECT IDENTIFIER

Defined by SNMPv2-TC.

sec_level()

-type sec_level() :: snmp_framework_mib:security_level().

sec_model()

-type sec_model() :: snmp_framework_mib:security_model().

sec_name()

-type sec_name() :: snmp_framework_mib:admin_string().

snmp_timer()

-type snmp_timer() ::
          #snmp_incr_timer{wait_for :: term(), factor :: term(), incr :: term(), max_retries :: term()}.

table_info()

-type table_info() ::
          #table_info{nbr_of_cols :: term(),
                      defvals :: term(),
                      status_col :: term(),
                      not_accessible :: term(),
                      index_types :: term(),
                      first_accessible :: term(),
                      first_own_index :: term()}.

taddress()

-type taddress() :: snmpa_conf:transportAddress().

tdomain()

-type tdomain() :: transportDomainUdpIpv4 | transportDomainUdpIpv6.

time_interval()

-type time_interval() :: 0..2147483647.

Note

"A period of time, measured in units of 0.01 seconds."

INTEGER (0..2147483647)

Defined by SNMPv2-TC.

trap()

-type trap() ::
          #trap{trapname :: term(),
                enterpriseoid :: term(),
                specificcode :: term(),
                oidobjects :: term(),
                description :: term()}.

trappdu()

-type trappdu() ::
          #trappdu{enterprise :: term(),
                   agent_addr :: term(),
                   generic_trap :: term(),
                   specific_trap :: term(),
                   time_stamp :: term(),
                   varbinds :: term()}.

usm_auth_key()

-type usm_auth_key() :: snmp_user_based_sm_mib:auth_key().

usm_auth_protocol()

-type usm_auth_protocol() :: snmp_user_based_sm_mib:auth_protocol().

usm_name()

-type usm_name() :: snmp_user_based_sm_mib:name().

usm_priv_key()

-type usm_priv_key() :: snmp_user_based_sm_mib:priv_key().

usm_priv_protocol()

-type usm_priv_protocol() :: snmp_user_based_sm_mib:priv_protocol().

varbind()

-type varbind() :: #varbind{oid :: term(), variabletype :: term(), value :: term(), org_index :: term()}.

variable_info()

-type variable_info() :: #variable_info{defval :: term()}.

verbosity()

-type verbosity() :: silence | info | log | debug | trace.

For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

version()

-type version() :: v1 | v2 | v3.

void()

-type void() :: term().

The type is used when a functions return is to be ignored.

Functions

bits_to_octet_string(B)

-spec bits_to_octet_string(B) -> octet_string() when B :: bits().

Utility function for converting a value of type BITS to OCTET-STRING, according to RFC1906, section 8.

change_log_size(LogName, NewSize)

-spec change_log_size(LogName, NewSize) -> ok | {error, Reason}
                         when LogName :: string(), NewSize :: log_size(), 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 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.

config()

-spec config() -> ok | {error, Reason} when Reason :: term().

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!

date_and_time()

-spec date_and_time() -> DateAndTime when DateAndTime :: rfc1903_date_and_time().

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

date_and_time_to_string2(DAT)

-spec date_and_time_to_string2(DAT) -> string() when DAT :: rfc1903_date_and_time().

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.

date_and_time_to_string(DAT)

-spec date_and_time_to_string(DAT) -> string() when DAT :: rfc1903_date_and_time().

Equivalent to date_and_time_to_string/2.

date_and_time_to_string(DAT, Validate)

-spec date_and_time_to_string(DAT, Validate) -> string()
                                 when
                                     DAT :: rfc1903_date_and_time(),
                                     Validate :: date_and_time_validator().

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_universal_time_dst(DAT)

-spec date_and_time_to_universal_time_dst(DAT) -> UTCs
                                             when
                                                 DAT :: rfc1903_date_and_time(),
                                                 UTCs :: [calendar:datetime1970()].

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).

disable_trace()

-spec disable_trace() -> void().

Stop the tracer.

enable_trace()

-spec enable_trace() -> void().

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

local_time_to_date_and_time_dst(Local)

-spec local_time_to_date_and_time_dst(Local) -> DATs
                                         when
                                             Local :: calendar:datetime1970(),
                                             DATs :: [rfc1903_date_and_time()].

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).

log_to_io(LogDir, Mibs, LogName, LogFile)

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/5

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName, LogFile, Start) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Start :: null | log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/6

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Start :: null | log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Start :: null | log_time(),
                       Stop :: null | log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

(since OTP R16B03)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Start :: null | log_time(),
                       Stop :: null | log_time(),
                       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/8 for more info.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
                    when
                        LogDir :: string(),
                        Mibs :: [mib_name()],
                        OutFile :: string(),
                        LogName :: string(),
                        LogFile :: string(),
                        Cnt :: {NumOK, NumERR},
                        NumOK :: non_neg_integer(),
                        NumERR :: pos_integer(),
                        Reason :: term().

Equivalent to log_to_txt/8.

log_to_txt/6

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block) -> ok | {ok, Cnt} | {error, Reason}
                    when
                        LogDir :: string(),
                        Mibs :: [mib_name()],
                        OutFile :: string(),
                        LogName :: string(),
                        LogFile :: string(),
                        Block :: boolean(),
                        Cnt :: {NumOK, NumERR},
                        NumOK :: non_neg_integer(),
                        NumERR :: pos_integer(),
                        Reason :: term();
                (LogDir, Mibs, OutFile, LogName, LogFile, Start) -> ok | {ok, Cnt} | {error, Reason}
                    when
                        LogDir :: string(),
                        Mibs :: [mib_name()],
                        OutFile :: string(),
                        LogName :: string(),
                        LogFile :: string(),
                        Start :: null | log_time(),
                        Cnt :: {NumOK, NumERR},
                        NumOK :: non_neg_integer(),
                        NumERR :: pos_integer(),
                        Reason :: term().

Equivalent to log_to_txt/8.

log_to_txt/7

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) ->
                    ok | {ok, Cnt} | {error, Reason}
                    when
                        LogDir :: string(),
                        Mibs :: [mib_name()],
                        OutFile :: string(),
                        LogName :: string(),
                        LogFile :: string(),
                        Block :: boolean(),
                        Start :: null | log_time(),
                        Cnt :: {NumOK, NumERR},
                        NumOK :: non_neg_integer(),
                        NumERR :: pos_integer(),
                        Reason :: term();
                (LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) ->
                    ok | {ok, Cnt} | {error, Reason}
                    when
                        LogDir :: string(),
                        Mibs :: [mib_name()],
                        OutFile :: string(),
                        LogName :: string(),
                        LogFile :: string(),
                        Start :: null | log_time(),
                        Stop :: null | log_time(),
                        Cnt :: {NumOK, NumERR},
                        NumOK :: non_neg_integer(),
                        NumERR :: pos_integer(),
                        Reason :: term().

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

(since OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) ->
                    ok | {ok, Cnt} | {error, Reason}
                    when
                        LogDir :: string(),
                        Mibs :: [mib_name()],
                        OutFile :: string(),
                        LogName :: string(),
                        LogFile :: string(),
                        Block :: boolean(),
                        Start :: null | log_time(),
                        Stop :: null | log_time(),
                        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 useful 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.

octet_string_to_bits(S)

-spec octet_string_to_bits(S) -> bits() when S :: octet_string().

Utility function for converting a value of type OCTET-STRING to BITS, according to RFC1906, section 8.

passwd2localized_key(Algorithm, Passwd, EngineID)

-spec passwd2localized_key(Algorithm, Passwd, EngineID) -> Key
                              when
                                  Algorithm :: algorithm(),
                                  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.

print_version_info()

-spec print_version_info() -> void().

Equivalent to print_version_info/1.

print_version_info(Prefix)

-spec print_version_info(Prefix) -> void() when Prefix :: string() | non_neg_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).

print_versions(Versions)

-spec print_versions(Versions) -> void() when Versions :: [VersionInfo], VersionInfo :: term().

Equivalent to print_versions/2.

print_versions(Prefix, Versions)

-spec print_versions(Prefix, Versions) -> void()
                        when
                            Prefix :: string() | non_neg_integer(),
                            Versions :: [VersionInfo],
                            VersionInfo :: term().

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).

read_mib(FileName)

-spec read_mib(FileName) -> {ok, Mib} | {error, Reason}
                  when FileName :: string(), Mib :: mib(), Reason :: term().

Read a compiled mib.

reset_trace(Targets)

-spec reset_trace(Targets) -> void() when Targets :: module() | [module()].

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

set_trace(Targets)

-spec set_trace(Targets) -> void()
                   when
                       Targets :: module() | [module() | {module(), [TargetOpt]}],
                       TargetOpt :: {return_trace, boolean()} | {scope, Scope},
                       Scope ::
                           all_functions | exported_functions | FunctionName |
                           {FunctionName, FunctionArity},
                       FunctionName :: atom(),
                       FunctionArity :: non_neg_integer().

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.

set_trace(Targets, TraceOpts)

-spec set_trace(Targets, TraceOpts) -> void()
                   when
                       Targets :: module() | [module() | {module(), [TargetOpt]}],
                       TargetOpt :: {return_trace, boolean()} | {scope, Scope},
                       Scope ::
                           all_functions | exported_functions | FunctionName |
                           {FunctionName, FunctionArity},
                       FunctionName :: atom(),
                       FunctionArity :: non_neg_integer(),
                       TraceOpts :: disable | [TraceOpt],
                       TraceOpt :: {timestamp, boolean()} | TargetOpt.

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(),

start()

-spec start() -> ok | {error, Reason} when Reason :: term().

Equivalent to start/1.

start(Type)

-spec start(Type) -> ok | {error, Reason}
               when Type :: p | permanent | tr | transient | te | temporary, Reason :: term().

Starts the SNMP application.

See application for more info.

start_agent()

-spec start_agent() -> ok | {error, Reason} when Reason :: term().

Equivalent to start_agent/1.

start_agent(Type)

-spec start_agent(Type) -> ok | {error, Reason} when Type :: application:start_type(), Reason :: term().

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()

-spec start_manager() -> ok | {error, Reason} when Reason :: term().

Equivalent to start_manager/1.

start_manager(Type)

-spec start_manager(Type) -> ok | {error, Reason}
                       when Type :: application:start_type(), Reason :: term().

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.

stop()

(since OTP 27.0)

-spec stop() -> ok | {error, Reason} when Reason :: term().

Stops the SNMP application.

See application for more info.

This function has existed for long time, but not had a proper since tag, so to simplify we set the since tag to when it was documented.

universal_time_to_date_and_time(UTC)

-spec universal_time_to_date_and_time(UTC) -> DateAndTime
                                         when
                                             UTC :: calendar:datetime(),
                                             DateAndTime :: rfc1903_date_and_time().

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

validate_date_and_time(DateAndTime)

-spec validate_date_and_time(DateAndTime) -> boolean() when DateAndTime :: rfc1903_date_and_time().

Equivalent to validate_date_and_time/2.

validate_date_and_time(DateAndTime, Validate)

-spec validate_date_and_time(DateAndTime, Validate) -> boolean()
                                when
                                    DateAndTime :: rfc1903_date_and_time(),
                                    Validate :: date_and_time_validator().

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.

versions1()

-spec versions1() -> {ok, VersionsInfo} | {error, Reason}
                   when VersionsInfo :: [VersionInfo], VersionInfo :: term(), Reason :: term().

Equivalent to versions2/0.

versions2()

-spec versions2() -> {ok, VersionsInfo} | {error, Reason}
                   when VersionsInfo :: [VersionInfo], VersionInfo :: 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.

snmp_community_mib

Instrumentation Functions for SNMP-COMMUNITY-MIB

The module snmp_community_mib implements the instrumentation functions for the SNMP-COMMUNITY-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Types

context_name()

A human readable string.

index()

SnmpAdminString (SIZE(1..32))

name()

OCTET STRING (SIZE(1..64))

security_name()

SnmpAdminString

transport_tag()

SnmpTagValue

Functions

add_community(Idx, CommName, SecName, CtxName, TransportTag)

Equivalent to add_community/6.

add_community(Idx, CommName, SecName, EngineId, CtxName, TransportTag)

Adds a community to the agent config. Equivalent to one line in the community.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_community(Key)

Delete a community from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Types

context_name()

-type context_name() :: snmp_framework_mib:admin_string().

A human readable string.

SnmpAdminString

index()

-type index() :: snmp_framework_mib:admin_string().

SnmpAdminString (SIZE(1..32))

name()

-type name() :: string().

OCTET STRING (SIZE(1..64))

security_name()

-type security_name() :: snmp_framework_mib:admin_string().

SnmpAdminString

transport_tag()

-type transport_tag() :: snmp_target_mib:tag_value().

SnmpTagValue

Functions

add_community(Idx, CommName, SecName, CtxName, TransportTag)

-spec add_community(Idx, CommName, SecName, CtxName, TransportTag) -> {ok, Key} | {error, Reason}
                       when
                           Idx :: index(),
                           CommName :: name(),
                           SecName :: security_name(),
                           CtxName :: context_name(),
                           TransportTag :: transport_tag(),
                           Key :: term(),
                           Reason :: term().

Equivalent to add_community/6.

add_community(Idx, CommName, SecName, EngineId, CtxName, TransportTag)

(since OTP R14B03)

-spec add_community(Idx, CommName, SecName, EngineId, CtxName, TransportTag) ->
                       {ok, Key} | {error, Reason}
                       when
                           Idx :: index(),
                           CommName :: name(),
                           SecName :: security_name(),
                           EngineId :: snmp_framework_mib:engine_id(),
                           CtxName :: context_name(),
                           TransportTag :: transport_tag(),
                           Key :: term(),
                           Reason :: term().

Adds a community to the agent config. Equivalent to one line in the community.conf file.

With the EngineId argument it is possible to override the configured engine-id (SNMP-FRAMEWORK-MIB).

configure(ConfDir)

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error, report module and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: community.conf.

delete_community(Key)

-spec delete_community(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a community from the agent config.

reconfigure(ConfDir)

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-COMMUNITY-MIB, after this function has been called, is from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: community.conf.

snmp_framework_mib

Instrumentation Functions for SNMP-FRAMEWORK-MIB

The module snmp_framework_mib implements instrumentation functions for the SNMP-FRAMEWORK-MIB, and functions for initializing and configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Types

admin_string()

OCTET STRING (SIZE(0..255))

engine_id()

OCTET STRING (SIZE(5..32))

max_message_size()

message_processing_model()

security_level()

security_model()

Functions

add_context(Ctx)

Adds a context to the agent config. Equivalent to one line in the context.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_context(Key)

Delete a context from the agent config.

init()

This function is called from the supervisor at system start-up.

Types

admin_string()

-type admin_string() :: string().

OCTET STRING (SIZE(0..255))

engine_id()

-type engine_id() :: string().

OCTET STRING (SIZE(5..32))

max_message_size()

-type max_message_size() :: 484..2147483647.

Note

"The maximum length in octets of an SNMP message which this SNMP engine can send or receive and process, determined as the minimum of the maximum message size values supported among all of the transports available to and supported by the engine."

INTEGER (484..2147483647)

message_processing_model()

-type message_processing_model() :: v1 | v2c | v3.

Note

"As of this writing, there are several values of messageProcessingModel defined for use with SNMP. They are as follows: "

                        0  reserved for SNMPv1
                        1  reserved for SNMPv2c
                        2  reserved for SNMPv2u and SNMPv2*
                        3  reserved for SNMPv3

INTEGER(0 .. 2147483647)

security_level()

-type security_level() :: noAuthNoPriv | authNoPriv | authPriv.

Note

"A Level of Security at which SNMP messages can be sent or with which operations are being processed; in particular, one of: "

                      noAuthNoPriv - without authentication and
                                     without privacy,
                      authNoPriv   - with authentication but
                                     without privacy,
                      authPriv     - with authentication and
                                     with privacy.

"These three values are ordered such that noAuthNoPriv is less than authNoPriv and authNoPriv is less than authPriv."

INTEGER { noAuthNoPriv(1), authNoPriv(2), authPriv(3) }

security_model()

-type security_model() :: any | v1 | v2c | usm.

Note

"As of this writing, there are several values of securityModel defined for use with SNMP or reserved for use with supporting MIB objects. They are as follows: "

                        0  reserved for 'any'
                        1  reserved for SNMPv1
                        2  reserved for SNMPv2c
                        3  User-Based Security Model (USM)

INTEGER(0 .. 2147483647)

Functions

add_context(Ctx)

-spec add_context(Ctx) -> {ok, Key} | {error, Reason}
                     when Ctx :: string(), Key :: term(), Reason :: term().

Adds a context to the agent config. Equivalent to one line in the context.conf file.

configure(ConfDir)

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old data.

Thus, the data in the SNMP-FRAMEWORK-MIB, after this function has been called, is from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: context.conf.

delete_context(Key)

-spec delete_context(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a context from the agent config.

init()

-spec init() -> snmp:void().

This function is called from the supervisor at system start-up.

Creates the necessary objects in the database if they do not exist. It does not destroy any old values.

snmp_generic

Generic Functions for Implementing SNMP Objects in a Database

The module snmp_generic contains generic functions for implementing tables (and variables) using the SNMP built-in database or Mnesia. These default functions are used if no instrumentation function is provided for a managed object in a MIB. Sometimes, it might be necessary to customize the behaviour of the default functions. For example, in some situations a trap should be sent if a row is deleted or modified, or some hardware is to be informed, when information is changed.

The overall structure is shown in the following figure:

         +---------------+
         |   SNMP Agent  |
         +- - - - - - - -+
         |      MIB      |
         +---------------+
                 |
         Association file       (associates a MIB object with
                 |               snmp_generic:table_funct
                 |               snmp_generic:variable_func)
+--------------------------------------+
|           snmp_generic               |  Support for get-next,
|                                      |  RowStatus operations
+----------------------+---------------+
|    snmpa_local_db    |    Mnesia     |  Database
+--------------+-------+---------------+
|     dets     |  ets  |
| (persistent) |       |
+--------------+-------+

Each function takes the argument NameDb, which is a tuple {Name, Db}, to identify which database the functions should use. Name is the symbolic name of the managed object as defined in the MIB, and Db is either volatile, persistent, or mnesia. If it is mnesia, all variables are stored in the Mnesia table snmp_variables which must be a table with two attributes (not a Mnesia SNMP table). The SNMP tables are stored in Mnesia tables with the same names as the SNMP tables. All functions assume that a Mnesia table exists with the correct name and attributes. It is the programmer's responsibility to ensure this. Specifically, if variables are stored in Mnesia, the table snmp_variables must be created by the programmer. The record definition for this table is defined in the file snmp/include/snmp_types.hrl.

If an instrumentation function in the association file for a variable myVar does not have a name when compiling an MIB, the compiler generates an entry.

{myVar, {snmp_generic, variable_func, [{myVar, Db]}}.

And for a table:

{myTable, {snmp_generic, table_func, [{myTable, Db]}}.

Example

The following example shows an implementation of a table which is stored in Mnesia, but with some checks performed at set-request operations.

myTable_func(new, NameDb) ->   % pass unchanged
  snmp_generic:table_func(new, NameDb).

myTable_func(delete, NameDb) ->   % pass unchanged
  snmp_generic:table_func(delete, NameDb).

%% change row
myTable_func(is_set_ok, RowIndex, Cols, NameDb) ->
  case snmp_generic:table_func(is_set_ok, RowIndex,
                               Cols, NameDb) of
    {noError, 0} ->
      myApplication:is_set_ok(RowIndex, Cols);
    Err ->
      Err
  end;

myTable_func(set, RowIndex, Cols, NameDb) ->
  case snmp_generic:table_func(set, RowIndex, Cols,
                               NameDb),
    {noError, 0} ->
      % Now the row is updated, tell the application
      myApplication:update(RowIndex, Cols);
    Err ->
      Err
  end;

myTable_func(Op, RowIndex, Cols, NameDb) ->   % pass unchanged
  snmp_generic:table_func(Op, RowIndex, Cols, NameDb).

The .funcs file would look like:

{myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.

Summary

Types

column()

columns()

Is a list of column numbers in the case of a get operation, and a list of column numbers and values in the case of a set operation.

table_info_item()

For an ordinary table, the types will be the following

Functions

get_index_types(Name)

Gets the index types of Name

get_status_col(Name, Cols)

Gets the value of the status column from Cols.

get_table_info/2

Get a specific table info item or, if Item has the value 'all', a two tuple list (property list) is instead returned with all the items and their respctive values of the given table.

table_func(Op, NameDb)

This is the default instrumentation function for tables.

table_func(Op, RowIndex, Cols, NameDb)

This is the default instrumentation function for tables.

table_get_elements(NameDb, RowIndex, Cols)

Returns a list with values for all columns in Cols. If a column is undefined, its value is noinit.

table_next(NameDb, RestOid)

Finds the indices of the next row in the table. RestOid does not have to specify an existing row.

table_row_exists(NameDb, RowIndex)

Checks if a row in a table exists.

table_set_elements(NameDb, RowIndex, Cols)

Sets the elements in Cols to the row specified by RowIndex. No checks are performed on the new values.

variable_func/2

This is the default instrumentation function for variables.

variable_func/3

This is the default instrumentation function for variables with operations; is_set_ok | set | undo.

variable_get(Name)

Gets the value of a variable.

variable_set(Name, Value)

Sets a new value to a variable. The variable is created if it does not exist. No checks are made on the type of the new value.

Types

column()

-type column() :: pos_integer().

columns()

-type columns() :: [column()] | [{column(), Value :: term()}].

Is a list of column numbers in the case of a get operation, and a list of column numbers and values in the case of a set operation.

table_info_item()

(not exported)

-type table_info_item() ::
          nbr_of_cols | defvals | status_col | not_accessible | index_types | first_accessible |
          first_own_index.

For an ordinary table, the types will be the following:

nbr_of_cols - Number of columns.

Value type: pos_integer()

defvals - A list of default values, ordered by column.

Value type: [{Col :: pos_integer(), DefVal :: term()}]

status_col - Column number of the status column.

Value type: pos_integer()

not_accessible - A sorted list of columns (> first_accessible) that are 'not-accessible'.

Value type: [pos_integer()]

index_types - A list of asn1_type() for the index columns, ordered by column number or an "augment"-tuple (see below).

Value type: [asn1_type()]

first_accessible - The first accessible column.

Value type: pos_integer()

first_own_index - Column number of the first own index. Will be 0 if there is no such index for this table.

Value type: non_neg_integer()

For a augmented table, it will instead look like this:

index_types - Value type: {augments, {atom(), asn1_type()}}

nbr_of_cols - Value type: pos_integer()

not_accessible - Value type: [pos_integer()]

first_accessible - Value type: pos_integer()

Functions

get_index_types(Name)

-spec get_index_types(Name) -> IndexTypes
                         when Name :: snmpa:name() | snmpa:name_db(), IndexTypes :: [snmp:asn1_type()].

Gets the index types of Name

This function can be used in instrumentation functions to retrieve the index types part of the table info.

get_status_col(Name, Cols)

-spec get_status_col(Name, Cols) -> false | {value, StatusCol}
                        when
                            Name :: snmpa:name() | snmpa:name_db(),
                            Cols :: columns(),
                            StatusCol :: term().

Gets the value of the status column from Cols.

This function can be used in instrumentation functions for is_set_ok, undo or set to check if the status column of a table is modified.

get_table_info/2

(since OTP R15B01)

-spec get_table_info(Name, Item :: nbr_of_cols) -> Result
                        when Name :: snmpa:name() | snmpa:name_db(), Result :: pos_integer();
                    (Name, Item :: defvals) -> Result
                        when
                            Name :: snmpa:name() | snmpa:name_db(),
                            Result :: [{Col, DefVal}],
                            Col :: pos_integer(),
                            DefVal :: term();
                    (Name, Item :: status_col) -> Result
                        when Name :: snmpa:name() | snmpa:name_db(), Result :: pos_integer();
                    (Name, Item :: not_accessible) -> Result
                        when Name :: snmpa:name() | snmpa:name_db(), Result :: [pos_integer()];
                    (Name, Item :: index_types) -> Result
                        when Name :: snmpa:name() | snmpa:name_db(), Result :: [snmp:asn1_type()];
                    (Name, Item :: first_accessible) -> Result
                        when Name :: snmpa:name() | snmpa:name_db(), Result :: pos_integer();
                    (Name, Item :: first_own_index) -> Result
                        when Name :: snmpa:name() | snmpa:name_db(), Result :: non_neg_integer();
                    (Name, Item :: all) -> Result
                        when
                            Name :: snmpa:name() | snmpa:name_db(),
                            Result :: [{table_info_item(), term()}].

Get a specific table info item or, if Item has the value 'all', a two tuple list (property list) is instead returned with all the items and their respctive values of the given table.

This function can be used in instrumentation functions to retrieve a given part of the table info.

table_func(Op, NameDb)

-spec table_func(Op, NameDb) -> Return
                    when Op :: new | delete, NameDb :: snmpa:name_db(), Return :: term().

This is the default instrumentation function for tables.

The new operation creates the table if it does not exist, but only if the database is the SNMP internal db.

The delete operation does not delete the table from the database since unloading an MIB does not necessarily mean that the table should be destroyed.

If it is possible for a manager to create or delete rows in the table, there must be a RowStatus column for is_set_ok, set and undo to work properly.

The function returns according to the specification of an instrumentation function.

table_func(Op, RowIndex, Cols, NameDb)

-spec table_func(Op, RowIndex, Cols, NameDb) -> Return
                    when
                        Op :: get | get_next | is_set_ok | set | undo,
                        RowIndex :: snmp:row_index(),
                        Cols :: columns(),
                        NameDb :: snmpa:name_db(),
                        Return :: term().

This is the default instrumentation function for tables.

The is_set_ok operation checks that a row which is to be modified or deleted exists, and that a row which is to be created does not exist.

The undo operation does nothing.

The set operation checks if it has enough information to make the row change its status from notReady to notInService (when a row has been been set to createAndWait). If a row is set to createAndWait, columns without a value are set to noinit. If Mnesia is used, the set functionality is handled within a transaction.

If it is possible for a manager to create or delete rows in the table, there must be a RowStatus column for is_set_ok, set and undo to work properly.

The function returns according to the specification of an instrumentation function.

table_get_elements(NameDb, RowIndex, Cols)

-spec table_get_elements(NameDb, RowIndex, Cols) -> Values
                            when
                                NameDb :: snmpa:name_db(),
                                RowIndex :: snmp:row_index(),
                                Cols :: columns(),
                                Values :: [noinit | Value],
                                Value :: term().

Returns a list with values for all columns in Cols. If a column is undefined, its value is noinit.

table_next(NameDb, RestOid)

-spec table_next(NameDb, RestOid) -> Result
                    when
                        NameDb :: snmpa:name_db(),
                        RestOid :: [integer()],
                        Result :: RowIndex | endOfTable,
                        RowIndex :: snmp:row_index().

Finds the indices of the next row in the table. RestOid does not have to specify an existing row.

table_row_exists(NameDb, RowIndex)

-spec table_row_exists(NameDb, RowIndex) -> Result
                          when
                              NameDb :: snmpa:name_db(),
                              RowIndex :: snmp:row_index(),
                              Result :: boolean().

Checks if a row in a table exists.

table_set_elements(NameDb, RowIndex, Cols)

-spec table_set_elements(NameDb, RowIndex, Columns) -> Result
                            when
                                NameDb :: snmpa:name_db(),
                                RowIndex :: snmp:row_index(),
                                Columns :: [{Column, Value}],
                                Column :: column(),
                                Value :: term(),
                                Result :: boolean().

Sets the elements in Cols to the row specified by RowIndex. No checks are performed on the new values.

If the Mnesia database is used, this function calls mnesia:write to store the values. This means that this function must be called from within a transaction (mnesia:transaction/1).

variable_func/2

-spec variable_func(Op :: new, Name) -> Result
                       when Name :: snmpa:name() | snmpa:name_db(), Result :: ok | boolean();
                   (Op :: delete, Name) -> Result
                       when Name :: snmpa:name() | snmpa:name_db(), Result :: ok;
                   (Op :: get, Name) -> Result
                       when
                           Name :: snmpa:name() | snmpa:name_db(),
                           Result :: {value, Value} | genErr,
                           Value :: term().

This is the default instrumentation function for variables.

The new opeation creates a new variable in the database with a default value as defined in the MIB, or a zero value (depending on the type).

The delete function does not delete the variable from the database.

The function returns according to the specification of an instrumentation function.

variable_func/3

-spec variable_func(Op :: is_set_ok, Value, Name) -> Result
                       when Value :: term(), Name :: snmpa:name() | snmpa:name_db(), Result :: noError;
                   (Op :: set, Value, Name) -> Result
                       when
                           Value :: term(),
                           Name :: snmpa:name() | snmpa:name_db(),
                           Result :: noError | commitFailed;
                   (Op :: undo, Value, Name) -> Result
                       when Value :: term(), Name :: snmpa:name() | snmpa:name_db(), Result :: noError.

This is the default instrumentation function for variables with operations; is_set_ok | set | undo.

The is_set_ok operation does nothing.

The set operation return noError if successful or commitFailed otherwise.

The undo operation does nothing.

The function returns according to the specification of an instrumentation function.

variable_get(Name)

-spec variable_get(Name) -> {value, Value} | undefined
                      when Name :: snmpa:name() | snmpa:name_db(), Value :: term().

Gets the value of a variable.

variable_set(Name, Value)

-spec variable_set(Name, Value) -> boolean()
                      when Name :: snmpa:name() | snmpa:name_db(), Value :: term().

Sets a new value to a variable. The variable is created if it does not exist. No checks are made on the type of the new value.

Returns false if the NameDb argument is incorrectly specified, otherwise true.

snmp_index

Abstract Data Type for SNMP Indexing

The module snmp_index implements an Abstract Data Type (ADT) for an SNMP index structure for SNMP tables. It is implemented as an ets table of the ordered_set data-type, which means that all operations are O(log n). In the table, the key is an ASN.1 OBJECT IDENTIFIER.

This index is used to separate the implementation of the SNMP ordering from the actual implementation of the table. The SNMP ordering, that is implementation of GET NEXT, is implemented in this module.

For example, suppose there is an SNMP table, which is best implemented in Erlang as one process per SNMP table row. Suppose further that the INDEX in the SNMP table is an OCTET STRING. The index structure would be created as follows:

snmp_index:new(string)

For each new process we create, we insert an item in an snmp_index structure:

new_process(Name, SnmpIndex) ->
  Pid = start_process(),
  NewSnmpIndex =
    snmp_index:insert(SnmpIndex, Name, Pid),
  <...>

With this structure, we can now map an OBJECT IDENTIFIER in e.g. a GET NEXT request, to the correct process:

get_next_pid(Oid, SnmpIndex) ->
  {ok, {_, Pid}} = snmp_index:get_next(SnmpIndex, Oid),
  Pid.

Warnings

Warning

All API functions that update the index return a NewIndex term. This is for backward compatibility with a previous implementation that used a B+ tree written purely in Erlang for the index. The NewIndex return value can now be ignored. The return value is now the unchanged table identifier for the ets table.

The implementation using ets tables introduces a semantic incompatibility with older implementations. In those older implementations, using pure Erlang terms, the index was garbage collected like any other Erlang term and did not have to be deleted when discarded. An ets table is deleted only when the process creating it explicitly deletes it or when the creating process terminates.

A new interface delete/1 is now added to handle the case when a process wants to discard an index table (i.e. to build a completely new). Any application using transient snmp indexes has to be modified to handle this.

As an snmp adaption usually keeps the index for the whole of the systems lifetime, this is rarely a problem.

Summary

Types

index()

This type denotes an snmp index structure.

key()

This type correlates to the key_types/0 type. If the key_types/0 is a single atom, the corresponding key/0 is a single type as well, but if the key_types/0 is a tuple, key/0 must be a tuple of the same size.

key_spec()

key_types()

This type is used when creating the index structure, and the key/0 type is used when inserting and deleting items from the structure.

type_spec()

Functions

delete(Index)

Deletes a complete index structure (i.e. the ets table holding the index). The index can no longer be referenced after this call. See the warning note above.

delete(Index, Key)

Deletes a key and its value from the index structure. Returns a new structure.

get(Index, KeyOid)

Gets the item with key KeyOid. Could be used from within an SNMP instrumentation function.

get_last(Index)

Gets the last item in the index structure.

get_next(Index, KeyOid)

Gets the next item in the SNMP lexicographic ordering, after KeyOid in the index structure. KeyOid does not have to refer to an existing item in the index.

insert(Index, Key, Value)

Inserts a new key value tuple into the index structure. If an item with the same key already exists, the new Value overwrites the old value.

key_to_oid(Index, Key)

Converts Key to an OBJECT IDENTIFIER.

new(KeyTypes)

Create an new anonymous snmp index structure.

new(KeyTypes, Name)

Creates a new named snmp index structure.

Types

index()

-opaque index()

This type denotes an snmp index structure.

key()

-type key() :: key_spec() | tuple().

This type correlates to the key_types/0 type. If the key_types/0 is a single atom, the corresponding key/0 is a single type as well, but if the key_types/0 is a tuple, key/0 must be a tuple of the same size.

In the example above, valid keys could be {"hi", "mom"} and {"no", "thanks"}, whereas "hi", {"hi", 42} and {"hello", "there"} would be invalid.

There is no way to propely describe this type in the erlang type language, which is why tuple/0 was used above. The proper definition looks like:

key() = key_spec() | {key_spec(), key_spec(), ...}

key_spec()

-type key_spec() :: string() | integer().

key_types()

-type key_types() :: type_spec() | tuple().

This type is used when creating the index structure, and the key/0 type is used when inserting and deleting items from the structure.

If the INDEX column is of type INTEGER, or derived from INTEGER, the corresponding type should be integer. If it is a variable length type (e.g. OBJECT IDENTIFIER, OCTET STRING), the corresponding type should be string. Finally, if the type is of variable length, but with a fixed size restriction (e.g. IpAddress), the corresponding type should be fix_string.

There is no way to propely describe this type in the erlang type language, which is why tuple/0 was used above. The proper definition looks like:

key_types = type_spec() | {type_spec(), type_spec(), ...}

type_spec()

-type type_spec() :: fix_string | string | integer.

Functions

delete(Index)

-spec delete(Index) -> true when Index :: index().

Deletes a complete index structure (i.e. the ets table holding the index). The index can no longer be referenced after this call. See the warning note above.

delete(Index, Key)

-spec delete(Index, Key) -> NewIndex when Index :: index(), Key :: key(), NewIndex :: index().

Deletes a key and its value from the index structure. Returns a new structure.

get(Index, KeyOid)

-spec get(Index, KeyOid) -> {ok, {KeyOid, Value}} | undefined
             when Index :: index(), KeyOid :: snmp:oid(), Value :: term().

Gets the item with key KeyOid. Could be used from within an SNMP instrumentation function.

get_last(Index)

-spec get_last(Index) -> {ok, {KeyOid, Value}} | undefined
                  when Index :: index(), KeyOid :: snmp:oid(), Value :: term().

Gets the last item in the index structure.

get_next(Index, KeyOid)

-spec get_next(Index, KeyOid) -> {ok, {NextKeyOid, Value}} | undefined
                  when Index :: index(), KeyOid :: snmp:oid(), NextKeyOid :: snmp:oid(), Value :: term().

Gets the next item in the SNMP lexicographic ordering, after KeyOid in the index structure. KeyOid does not have to refer to an existing item in the index.

insert(Index, Key, Value)

-spec insert(Index, Key, Value) -> NewIndex
                when Index :: index(), Key :: key(), Value :: term(), NewIndex :: index().

Inserts a new key value tuple into the index structure. If an item with the same key already exists, the new Value overwrites the old value.

key_to_oid(Index, Key)

-spec key_to_oid(Index, Key) -> KeyOid when Index :: index(), Key :: key(), KeyOid :: snmp:oid().

Converts Key to an OBJECT IDENTIFIER.

new(KeyTypes)

-spec new(KeyTypes) -> Index when KeyTypes :: key_types(), Index :: index().

Create an new anonymous snmp index structure.

new(KeyTypes, Name)

(since OTP 27.0)

-spec new(KeyTypes, Name) -> Index when KeyTypes :: key_types(), Name :: atom(), Index :: index().

Creates a new named snmp index structure.

snmp_notification_mib

Instrumentation Functions for SNMP-NOTIFICATION-MIB

The module snmp_notification_mib implements the instrumentation functions for the SNMP-NOTIFICATION-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Types

notify_name()

SnmpAdminString (SIZE(1..32))

notify_tag()

notify_type()

Functions

add_notify(Name, Tag, Type)

Adds a notify definition to the agent config. Equivalent to one line in the notify.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_notify(Key)

Delete a notify definition from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Types

notify_name()

-type notify_name() :: snmp_framework_mib:admin_string().

SnmpAdminString (SIZE(1..32))

notify_tag()

-type notify_tag() :: snmp_target_mib:tag_value().

notify_type()

-type notify_type() :: trap | inform.

Functions

add_notify(Name, Tag, Type)

-spec add_notify(Name, Tag, Type) -> {ok, Key} | {error, Reason}
                    when
                        Name :: notify_name(),
                        Tag :: notify_tag(),
                        Type :: notify_type(),
                        Key :: term(),
                        Reason :: term().

Adds a notify definition to the agent config. Equivalent to one line in the notify.conf file.

configure(ConfDir)

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: notify.conf.

delete_notify(Key)

-spec delete_notify(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a notify definition from the agent config.

reconfigure(ConfDir)

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-NOTIFICATION-MIB, after this function has been called, is from the configuration files.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: notify.conf.

snmp_pdus

Encode and Decode Functions for SNMP PDUs

RFC1157, RFC1905 and/or RFC2272 should be studied carefully before using this module, snmp_pdus.

The module snmp_pdus contains functions for encoding and decoding of SNMP protocol data units (PDUs). In short, this module converts a list of bytes to Erlang record representations and vice versa. The record definitions can be found in the file snmp/include/snmp_types.hrl. If snmpv3 is used, the module that includes snmp_types.hrl must define the constant SNMP_USE_V3 before the header file is included. Example:

-define(SNMP_USE_V3, true).
-include_lib("snmp/include/snmp_types.hrl").

Encoding and decoding must be done explicitly when writing your own Net if process.

Summary

Types

message()

The message is version dependent. 'vsn_hdr' is either a community string (v1 and v2) or a 'v3_hdr' record (v3). 'data' is either a PDU (v1 and v2c) or a (possibly encrypted) 'scopedPdu'.

msg_id()

msg_security_model()

pdu()

pdu_type()

scoped_pdu()

trappdu()

usm_security_parameters()

v3_hdr()

version()

Functions

dec_message(Bytes)

Decodes a list of bytes into an SNMP Message. Note, if there is a v3 message, the msgSecurityParameters are not decoded. They must be explicitly decoded by a call to a security model specific decoding function, e.g. dec_usm_security_parameters/1. Also note, if the scopedPDU is encrypted, the OCTET STRING encoded encryptedPDU will be present in the data field.

dec_message_only(Bytes)

Decodes a list of bytes into an SNMP Message, but does not decode the data part of the Message. That means, data is still a list of bytes, normally an encoded PDU (v1 and V2) or an encoded and possibly encrypted scopedPDU (v3).

dec_pdu(Bytes)

Decodes a list of bytes into an SNMP Pdu.

dec_scoped_pdu(Bytes)

Decodes a list of bytes into an SNMP ScopedPdu.

dec_scoped_pdu_data(Bytes)

Decodes a list of bytes into either a scoped pdu record, or - if the scoped pdu was encrypted - to a list of bytes.

dec_usm_security_parameters(Bytes)

Decodes a list of bytes into an SNMP UsmSecurityParameters.

enc_message(Message)

Encodes a message record to a list of bytes.

enc_message_only(Message)

Message is a record where the data field is assumed to be encoded (a list of bytes). If there is a v1 or v2 message, the data field is an encoded PDU, and if there is a v3 message, data is an encoded and possibly encrypted scopedPDU.

enc_pdu(Pdu)

Encodes an SNMP Pdu into a list of bytes.

enc_scoped_pdu(ScopedPdu)

Encodes an SNMP ScopedPdu into a list of bytes, which can be encrypted, and after encryption, encoded with a call to enc_encrypted_scoped_pdu/1; or it can be used as the data field in a message record, which then can be encoded with enc_message_only/1.

enc_usm_security_parameters(UsmSecParams)

Encodes SNMP UsmSecurityParameters into a list of bytes.

Types

message()

-type message() :: #message{version :: term(), vsn_hdr :: term(), data :: term()}.

The message is version dependent. 'vsn_hdr' is either a community string (v1 and v2) or a 'v3_hdr' record (v3). 'data' is either a PDU (v1 and v2c) or a (possibly encrypted) 'scopedPdu'.

msg_id()

-type msg_id() :: 0..2147483647.

msg_security_model()

-type msg_security_model() :: 0..2147483647.

pdu()

-type pdu() ::
          #pdu{type :: term(),
               request_id :: term(),
               error_status :: term(),
               error_index :: term(),
               varbinds :: term()}.

pdu_type()

-type pdu_type() ::
          'get-request' | 'get-next-request' | 'get-bulk-request' | 'get-response' | 'set-request' |
          'inform-request' | 'snmpv2-trap' | report.

scoped_pdu()

-type scoped_pdu() :: #scopedPdu{contextEngineID :: term(), contextName :: term(), data :: term()}.

trappdu()

-type trappdu() ::
          #trappdu{enterprise :: term(),
                   agent_addr :: term(),
                   generic_trap :: term(),
                   specific_trap :: term(),
                   time_stamp :: term(),
                   varbinds :: term()}.

usm_security_parameters()

-type usm_security_parameters() ::
          #usmSecurityParameters{msgAuthoritativeEngineID :: term(),
                                 msgAuthoritativeEngineBoots :: term(),
                                 msgAuthoritativeEngineTime :: term(),
                                 msgUserName :: term(),
                                 msgAuthenticationParameters :: term(),
                                 msgPrivacyParameters :: term()}.

v3_hdr()

-type v3_hdr() ::
          #v3_hdr{msgID :: term(),
                  msgMaxSize :: term(),
                  msgFlags :: term(),
                  msgSecurityModel :: term(),
                  msgSecurityParameters :: term(),
                  hdr_size :: term()}.

version()

-type version() :: 'version-1' | 'version-2' | 'version-3'.

Functions

dec_message(Bytes)

-spec dec_message(Bytes) -> Message when Bytes :: [byte()], Message :: message().

Decodes a list of bytes into an SNMP Message. Note, if there is a v3 message, the msgSecurityParameters are not decoded. They must be explicitly decoded by a call to a security model specific decoding function, e.g. dec_usm_security_parameters/1. Also note, if the scopedPDU is encrypted, the OCTET STRING encoded encryptedPDU will be present in the data field.

dec_message_only(Bytes)

-spec dec_message_only(Bytes) -> Message when Bytes :: [byte()], Message :: message().

Decodes a list of bytes into an SNMP Message, but does not decode the data part of the Message. That means, data is still a list of bytes, normally an encoded PDU (v1 and V2) or an encoded and possibly encrypted scopedPDU (v3).

dec_pdu(Bytes)

-spec dec_pdu(Bytes) -> Pdu when Bytes :: [byte()], Pdu :: trappdu() | pdu().

Decodes a list of bytes into an SNMP Pdu.

dec_scoped_pdu(Bytes)

-spec dec_scoped_pdu(Bytes) -> ScopedPDU when Bytes :: [byte()], ScopedPDU :: scoped_pdu().

Decodes a list of bytes into an SNMP ScopedPdu.

dec_scoped_pdu_data(Bytes)

-spec dec_scoped_pdu_data(Bytes) -> ScopedPduData
                             when
                                 Bytes :: [byte()],
                                 ScopedPduData :: scoped_pdu() | EncryptedPDU,
                                 EncryptedPDU :: [byte()].

Decodes a list of bytes into either a scoped pdu record, or - if the scoped pdu was encrypted - to a list of bytes.

dec_usm_security_parameters(Bytes)

-spec dec_usm_security_parameters(Bytes) -> UsmSecParams
                                     when Bytes :: [byte()], UsmSecParams :: usm_security_parameters().

Decodes a list of bytes into an SNMP UsmSecurityParameters.

enc_message(Message)

-spec enc_message(Message) -> Bytes when Message :: message(), Bytes :: [byte()].

Encodes a message record to a list of bytes.

enc_message_only(Message)

-spec enc_message_only(Message) -> Bytes when Message :: message(), Bytes :: [byte()].

Message is a record where the data field is assumed to be encoded (a list of bytes). If there is a v1 or v2 message, the data field is an encoded PDU, and if there is a v3 message, data is an encoded and possibly encrypted scopedPDU.

enc_pdu(Pdu)

-spec enc_pdu(Pdu) -> Bytes when Pdu :: pdu(), Bytes :: [byte()].

Encodes an SNMP Pdu into a list of bytes.

enc_scoped_pdu(ScopedPdu)

-spec enc_scoped_pdu(ScopedPdu) -> Bytes when ScopedPdu :: scoped_pdu(), Bytes :: [byte()].

Encodes an SNMP ScopedPdu into a list of bytes, which can be encrypted, and after encryption, encoded with a call to enc_encrypted_scoped_pdu/1; or it can be used as the data field in a message record, which then can be encoded with enc_message_only/1.

enc_usm_security_parameters(UsmSecParams)

-spec enc_usm_security_parameters(UsmSecParams) -> Bytes
                                     when UsmSecParams :: usm_security_parameters(), Bytes :: [byte()].

Encodes SNMP UsmSecurityParameters into a list of bytes.

snmp_standard_mib

Instrumentation Functions for STANDARD-MIB and SNMPv2-MIB

The module snmp_standard_mib implements the instrumentation functions for the STANDARD-MIB and SNMPv2-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Functions

configure(ConfDir)

This function is called from the supervisor at system start-up.

inc(Name)

Equivalent to inc/2.

inc(Name, N)

Increments a variable in the MIB with N, or one if N is not specified.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

reset()

Resets all snmp counters to 0.

sys_up_time()

Gets the system up time in hundredth of a second.

Functions

configure(ConfDir)

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: standard.conf.

inc(Name)

-spec inc(Name) -> snmp:void() when Name :: atom().

Equivalent to inc/2.

inc(Name, N)

-spec inc(Name, N) -> snmp:void() when Name :: atom(), N :: integer().

Increments a variable in the MIB with N, or one if N is not specified.

reconfigure(ConfDir)

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-STANDARD-MIB and SNMPv2-MIB, after this function has been called, is from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: standard.conf.

reset()

-spec reset() -> snmp:void().

Resets all snmp counters to 0.

sys_up_time()

-spec sys_up_time() -> Time when Time :: integer().

Gets the system up time in hundredth of a second.

snmp_target_mib

Instrumentation Functions for SNMP-TARGET-MIB

The module snmp_target_mib implements the instrumentation functions for the SNMP-TARGET-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Legacy API functions add_addr/10 that does not specify transport domain, and add_addr/11 that has got separate IpAddr and PortNumber arguments still work as before for backwards compatibility reasons.

DATA TYPES

See the data types in snmpa_conf.

Summary

Types

mms()

name()

params()

retry_count()

tag_list()

tag_value()

tmask()

Functions

add_addr/10

Adds a target address definition to the agent config. Equivalent to one line in the target_addr.conf file.

add_params(Name, MPModel, SecModel, SecName, SecLevel)

Adds a target parameter definition to the agent config. Equivalent to one line in the target_params.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_addr(Key)

Delete a target address definition from the agent config.

delete_params(Key)

Delete a target parameter definition from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

set_target_engine_id(TargetAddrName, EngineId)

Changes the engine id for a target in the snmpTargetAddrTable. If notifications are sent as Inform requests to a target, its engine id must be set.

Types

mms()

-type mms() :: 484..65535.

Note

"The maximum message size value associated with an entry in the snmpTargetAddrTable.".

Integer32 (484..65535)

name()

-type name() :: snmp_framework_mib:admin_string().

Note

"The locally arbitrary, but unique identifier associated with this snmpTargetAddrEntry."

SnmpAdminString (SIZE(1..32))

params()

-type params() :: snmp_framework_mib:admin_string().

Note

"The value of this object identifies an entry in the snmpTargetParamsTable."

SnmpAdminString (SIZE(1..32))

retry_count()

-type retry_count() :: 0..255.

Note

"This object specifies a default number of retries to be attempted when a response is not received for a generated message."

Integer32 (0..255)

tag_list()

-type tag_list() :: string().

Note

"An octet string containing a list of tag values. Tag values are preferably in human-readable form."

"To facilitate internationalization, this information is represented using the ISO/IEC IS 10646-1 character set, encoded as an octet string using the UTF-8 character encoding scheme described in RFC 2279."

OCTET STRING (SIZE (0..255))

tag_value()

-type tag_value() :: string().

Note

"An octet string containing a tag value. Tag values are preferably in human-readable form."

OCTET STRING (SIZE (0..255))

tmask()

-type tmask() :: snmpa_conf:transportAddressMask().

Note

"The mask value associated with an entry in the snmpTargetAddrTable. The value of this object must have the same length as the corresponding instance of snmpTargetAddrTAddress, or must have length 0."

OCTET STRING (SIZE (0..255))

Functions

add_addr/10

-spec add_addr(Name, TDomain, TAddr, Timeout, Retry, TagList, Params, EngineId, TMask, MMS) ->
                  {ok, Key} | {error, Reason}
                  when
                      Name :: name(),
                      TDomain :: snmpa_conf:transportDomain(),
                      TAddr :: snmpa_conf:transportAddress(),
                      Timeout :: snmp:time_interval(),
                      Retry :: integer(),
                      TagList :: tag_list(),
                      Params :: params(),
                      EngineId :: snmp_framework_mib:engine_id(),
                      TMask :: tmask(),
                      MMS :: snmp_framework_mib:max_message_size(),
                      Key :: term(),
                      Reason :: term();
              (Name, Ip, Port, Timeout, Retry, TagList, Params, EngineId, TMask, MMS) ->
                  {ok, Key} | {error, Reason}
                  when
                      Name :: name(),
                      Ip :: snmpa_conf:transportAddressWithoutPort(),
                      Port :: inet:port_number(),
                      Timeout :: snmp:time_interval(),
                      Retry :: integer(),
                      TagList :: tag_list(),
                      Params :: params(),
                      EngineId :: snmp_framework_mib:engine_id(),
                      TMask :: tmask(),
                      MMS :: snmp_framework_mib:max_message_size(),
                      Key :: term(),
                      Reason :: term().

Adds a target address definition to the agent config. Equivalent to one line in the target_addr.conf file.

add_params(Name, MPModel, SecModel, SecName, SecLevel)

-spec add_params(Name, MPModel, SecModel, SecName, SecLevel) -> {ok, Key} | {error, Reason}
                    when
                        Name :: name(),
                        MPModel :: snmp_framework_mib:message_processing_model(),
                        SecModel :: snmp_framework_mib:security_model(),
                        SecName :: snmp_framework_mib:admin_string(),
                        SecLevel :: snmp_framework_mib:security_level(),
                        Key :: term(),
                        Reason :: term().

Adds a target parameter definition to the agent config. Equivalent to one line in the target_params.conf file.

configure(ConfDir)

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration files read are: target_addr.conf and target_params.conf.

delete_addr(Key)

-spec delete_addr(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a target address definition from the agent config.

delete_params(Key)

-spec delete_params(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a target parameter definition from the agent config.

reconfigure(ConfDir)

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-TARGET-MIB, after this function has been called, is the data from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the , and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration files read are: target_addr.conf and target_params.conf.

set_target_engine_id(TargetAddrName, EngineId)

-spec set_target_engine_id(TargetAddrName, EngineId) -> boolean()
                              when TargetAddrName :: name(), EngineId :: snmp_framework_mib:engine_id().

Changes the engine id for a target in the snmpTargetAddrTable. If notifications are sent as Inform requests to a target, its engine id must be set.

snmp_user_based_sm_mib

Instrumentation Functions for SNMP-USER-BASED-SM-MIB

The module snmp_user_based_sm_mib implements the instrumentation functions for the SNMP-USER-BASED-SM-MIB, and functions for configuring the database.

Note that authentication has been extended according to RFC 7860 (SNMP-USM-HMAC-SHA2-MIB).

The configuration files are described in the SNMP User's Manual.

Summary

Types

auth_key()

The size/length of the list depends on auth protocol

auth_protocol()

clone_from()

key_change()

name()

priv_key()

The size/length of the list depends on priv protocol

priv_protocol()

public()

OCTET STRING (SIZE(0..32))

usm_entry()

Functions

add_user(EngineID, Name, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey)

Adds a USM security data (user) to the agent config. Equivalent to one line in the usm.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_user(Key)

Delete a USM security data (user) from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Types

auth_key()

-type auth_key() :: snmp:octet_string().

The size/length of the list depends on auth protocol:

               Size any for usmNoAuthProtocol
               Size 16  for usmHMACMD5AuthProtocol
               Size 20  for usmHMACSHAAuthProtocol
               Size 28  for usmHMAC128SHA224AuthProtocol
               Size 32  for usmHMAC192SHA256AuthProtocol
               Size 48  for usmHMAC256SHA384AuthProtocol
	       Size 64  for usmHMAC384SHA512AuthProtocol

auth_protocol()

-type auth_protocol() ::
          usmNoAuthProtocol | usmHMACMD5AuthProtocol | usmHMACSHAAuthProtocol |
          usmHMAC128SHA224AuthProtocol | usmHMAC192SH256AuthProtocol | usmHMAC256SHA384AuthProtocol |
          usmHMAC384SHA512AuthProtocol.

Note

"An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be authenticated, and if so, the type of authentication protocol which is used."

Note

Some of the entries of this type are actually defined by the SNMP-USM-HMAC-SHA2-MIB mib.

AutonomousType

clone_from()

-type clone_from() :: zeroDotZero | snmp:row_pointer().

Note

"A pointer to another conceptual row in this usmUserTable. The user in this other conceptual row is called the clone-from user."

RowPointer

key_change()

-type key_change() :: snmp:octet_string().

Note

"Every definition of an object with this syntax must identify a protocol P, a secret key K, and a hash algorithm H that produces output of L octets."

OCTET STRING

name()

-type name() :: snmp_framework_mib:admin_string().

Note

"A human readable string representing the name of the user. This is the (User-based Security) Model dependent security ID."

SnmpAdminString (SIZE(1..32))

priv_key()

-type priv_key() :: snmp:octet_string().

The size/length of the list depends on priv protocol:

	       Size any for usmNoPrivProtocol
               Size 16  for usmDESPrivProtocol
               Size 16  for usmAesCfb128Protocol

priv_protocol()

-type priv_protocol() :: usmNoPrivProtocol | usmDESPrivProtocol | usmAesCfb128Protocol.

Note

"An indication of whether messages sent on behalf of this user to/from the SNMP engine identified by usmUserEngineID, can be protected from disclosure, and if so, the type of privacy protocol which is used."

Note

Some of the entries of this tyype are actually defined by the SNMP-USM-AES-MIB mib.

AutonomousType

public()

-type public() :: string().

OCTET STRING (SIZE(0..32))

usm_entry()

-type usm_entry() ::
          {EngineID :: snmp_framework_mib:engine_id(),
           UserName :: name(),
           SecName :: snmp_framework_mib:admin_string(),
           Clone :: clone_from(),
           AuthP :: auth_protocol(),
           AuthKeyC :: key_change(),
           OwnAuthKeyC :: key_change(),
           PrivP :: priv_protocol(),
           PrivKeyC :: key_change(),
           OwnPrivKeyC :: key_change(),
           Public :: public(),
           AuthKey :: auth_key(),
           PrivKey :: priv_key()}.

Functions

add_user(EngineID, Name, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey)

-spec add_user(EngineID, Name, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC,
               OwnPrivKeyC, Public, AuthKey, PrivKey) ->
                  {ok, Key} | {error, Reason}
                  when
                      EngineID :: snmp_framework_mib:engine_id(),
                      Name :: name(),
                      SecName :: snmp_framework_mib:admin_string(),
                      Clone :: clone_from(),
                      AuthP :: auth_protocol(),
                      AuthKeyC :: key_change(),
                      OwnAuthKeyC :: key_change(),
                      PrivP :: priv_protocol(),
                      PrivKeyC :: key_change(),
                      OwnPrivKeyC :: key_change(),
                      Public :: public(),
                      AuthKey :: auth_key(),
                      PrivKey :: priv_key(),
                      Key :: term(),
                      Reason :: term().

Adds a USM security data (user) to the agent config. Equivalent to one line in the usm.conf file.

configure(ConfDir)

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: usm.conf.

delete_user(Key)

-spec delete_user(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a USM security data (user) from the agent config.

reconfigure(ConfDir)

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-USER-BASED-SM-MIB, after this function has been called, is the data from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: usm.conf.

snmp_view_based_acm_mib

Instrumentation Functions for SNMP-VIEW-BASED-ACM-MIB

The module snmp_view_based_acm_mib implements the instrumentation functions for the SNMP-VIEW-BASED-ACM-MIB, and functions for configuring the database.

The configuration files are described in the SNMP User's Manual.

Summary

Types

access_notify_view_name()

access_read_view_name()

access_write_view_name()

context_match()

context_prefix()

SnmpAdminString (SIZE(0..32))

group_name()

internal_view_mask()

internal_view_mask_element()

internal_view_type()

mibview()

security_name()

view_mask()

The bit mask which, in combination with the corresponding instance of vacmViewTreeFamilySubtree, defines a family of view subtrees.

view_name()

view_type()

Does the corresponding instances of subtree and mask define a family of view subtrees which are included in or excluded from the MIB view.

Functions

add_access(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV)

Adds a access definition to the agent config. Equivalent to one vacmAccess-line in the vacm.conf file.

add_sec2group(SecModel, SecName, GroupName)

Adds a security to group definition to the agent config. Equivalent to one vacmSecurityToGroup-line in the vacm.conf file.

add_view_tree_fam(ViewName, SubTree, Status, Mask)

Adds a view tree family definition to the agent config. Equivalent to one vacmViewTreeFamily-line in the vacm.conf file.

configure(ConfDir)

This function is called from the supervisor at system start-up.

delete_access(Key)

Delete a access definition from the agent config.

delete_sec2group(Key)

Delete a security to group definition from the agent config.

delete_view_tree_fam(Key)

Delete a view tree family definition from the agent config.

reconfigure(ConfDir)

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Types

access_notify_view_name()

-type access_notify_view_name() :: snmp_framework_mib:admin_string().

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes access for notifications."

SnmpAdminString (SIZE(0..32))

access_read_view_name()

-type access_read_view_name() :: snmp_framework_mib:admin_string().

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes read access."

SnmpAdminString (SIZE(0..32))

access_write_view_name()

-type access_write_view_name() :: snmp_framework_mib:admin_string().

Note

"The value of an instance of this object identifies the MIB view of the SNMP context to which this conceptual row authorizes write access."

SnmpAdminString (SIZE(0..32))

context_match()

-type context_match() :: exact | prefix.

	  exact  - exact match of prefix and contextName
          prefix - Only match to the prefix

INTEGER { exact (1), prefix (2) }

context_prefix()

-type context_prefix() :: snmp_framework_mib:admin_string().

SnmpAdminString (SIZE(0..32))

group_name()

-type group_name() :: snmp_framework_mib:admin_string().

Note

"The name of the group to which this entry (e.g., the combination of securityModel and securityName) belongs."

SnmpAdminString (SIZE(1..32))

internal_view_mask()

-type internal_view_mask() :: null | [internal_view_mask_element()].

internal_view_mask_element()

-type internal_view_mask_element() :: 0 | 1.

internal_view_type()

-type internal_view_type() :: 1 | 2.

mibview()

-type mibview() :: [{SubTree :: snmp:oid(), Mask :: internal_view_mask(), Type :: internal_view_type()}].

security_name()

-type security_name() :: snmp_framework_mib:admin_string().

Note

"The securityName for the principal, represented in a Security Model independent format."

SnmpAdminString (SIZE(1..32))

view_mask()

-type view_mask() :: [0 | 1].

The bit mask which, in combination with the corresponding instance of vacmViewTreeFamilySubtree, defines a family of view subtrees.

A '1' indicates that an exact match must occur, a '0' indicates 'wild card' (any sub-identifier value matches).

Note

Note that in the "external" format, each bit of each octet is represented by a "bit" in this list. That is, each octet "contains" 8 bits; so at most 8*16 = 128 bits in total.

OCTET STRING (SIZE (0..16))

view_name()

-type view_name() :: snmp_framework_mib:admin_string().

Note

"The human readable name for a family of view subtrees."

SnmpAdminString (SIZE(1..32))

view_type()

-type view_type() :: included | excluded.

Does the corresponding instances of subtree and mask define a family of view subtrees which are included in or excluded from the MIB view.

INTEGER { included(1), excluded(2) }

Functions

add_access(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV)

-spec add_access(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV) ->
                    {ok, Key} | {error, Reason}
                    when
                        GroupName :: group_name(),
                        Prefix :: context_prefix(),
                        SecModel :: snmp_framework_mib:security_model(),
                        SecLevel :: snmp_framework_mib:security_level(),
                        Match :: context_match(),
                        RV :: access_read_view_name(),
                        WV :: access_write_view_name(),
                        NV :: access_notify_view_name(),
                        Key :: term(),
                        Reason :: term().

Adds a access definition to the agent config. Equivalent to one vacmAccess-line in the vacm.conf file.

add_sec2group(SecModel, SecName, GroupName)

-spec add_sec2group(SecModel, SecName, GroupName) -> {ok, Key} | {error, Reason}
                       when
                           SecModel :: snmp_framework_mib:security_model(),
                           SecName :: security_name(),
                           GroupName :: group_name(),
                           Key :: term(),
                           Reason :: term().

Adds a security to group definition to the agent config. Equivalent to one vacmSecurityToGroup-line in the vacm.conf file.

add_view_tree_fam(ViewName, SubTree, Status, Mask)

-spec add_view_tree_fam(ViewName, SubTree, Status, Mask) -> {ok, Key} | {error, Reason}
                           when
                               ViewName :: view_name(),
                               SubTree :: snmp:oid(),
                               Status :: view_type(),
                               Mask :: null | view_mask(),
                               Key :: term(),
                               Reason :: term().

Adds a view tree family definition to the agent config. Equivalent to one vacmViewTreeFamily-line in the vacm.conf file.

configure(ConfDir)

-spec configure(ConfDir) -> snmp:void() when ConfDir :: string().

This function is called from the supervisor at system start-up.

Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile. The rows created from the configuration file will have StorageType nonVolatile.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: vacm.conf.

delete_access(Key)

-spec delete_access(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a access definition from the agent config.

delete_sec2group(Key)

-spec delete_sec2group(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a security to group definition from the agent config.

delete_view_tree_fam(Key)

-spec delete_view_tree_fam(Key) -> ok | {error, Reason} when Key :: term(), Reason :: term().

Delete a view tree family definition from the agent config.

reconfigure(ConfDir)

-spec reconfigure(ConfDir) -> snmp:void() when ConfDir :: string().

Inserts all data in the configuration files into the database and destroys all old data, including the rows with StorageType nonVolatile. The rows created from the configuration file will have StorageType nonVolatile.

Thus, the data in the SNMP-VIEW-BASED-ACM-MIB, after this function has been called, is the data from the configuration files.

All snmp counters are set to zero.

If an error is found in the configuration file, it is reported using the function config_err/2 of the error report module, and the function fails with the reason configuration_error.

ConfDir is a string which points to the directory where the configuration files are found.

The configuration file read is: vacm.conf.

snmpa

Interface Functions to the SNMP toolkit agent

The module snmpa contains interface functions to the SNMP agent.

Summary

Types

db()

discovery_handler()

Module implementing the snmpa_discovery_handler behaviour.

me()

mib_storage()

mib_storage_module()

mib_storage_opt()

mib_storage_options()

name()

name_db()

nfilter_id()

nfilter_position()

notification_delivery_info()

How shall (notification) delivery info be reported.

pdu_type()

table_name()

transport_kind()

variable_name()

Functions

add_agent_caps(Oid, Descr)

This function can be used to add an AGENT-CAPABILITY statement to the sysORTable in the agent. The table is defined in the SNMPv2-MIB.

backup(BackupDir)

Equivalent to backup/2.

backup(Agent, BackupDir)

Backup persistent/permanent data handled by the agent (such as local-db, mib-data and vacm).

change_log_size(NewSize)

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 description of how to change the log size.

convert_config(OldConfig)

This off-line utility function can be used to convert the old snmp application config (pre snmp-4.0) to the new snmp agent config (as of snmp-4.0).

current_address()

Get the address of the request currently being processed by the agent.

current_community()

Get the community of the request currently being processed by the agent.

current_context()

Get the context of the request currently being processed by the agent.

current_request_id()

Get the request-id of the request currently being processed by the agent.

del_agent_caps(Index)

This function can be used to delete an AGENT-CAPABILITY statement to the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

disable_mibs_cache()

Equivalent to disable_mibs_cache/1.

disable_mibs_cache(Agent)

Disable the mib server cache.

disable_mibs_cache_autogc()

Equivalent to disable_mibs_cache_autogc/1.

disable_mibs_cache_autogc(Agent)

Disable automatic gc of the mib server cache.

discovery(TargetName, Notification)

Equivalent to discovery/6.

discovery/3

Equivalent to discovery/6.

discovery/4

Equivalent to discovery/6.

discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler)

Equivalent to discovery/6.

discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler, ExtraInfo)

Initiate the discovery process with the manager identified by TargetName using the notification Notification.

enable_mibs_cache()

Equivalent to enable_mibs_cache/1.

enable_mibs_cache(Agent)

Enable the mib server cache.

enable_mibs_cache_autogc()

Equivalent to enable_mibs_cache_autogc/1.

enable_mibs_cache_autogc(Agent)

Enable automatic gc of the mib server cache.

enum_to_int(Name, Enum)

Equivalent to enum_to_int/3.

enum_to_int(Db, Name, Enum)

Converts the symbolic value Enum to the corresponding integer of the enumerated object or type Name in a MIB. The MIB must be loaded.

gc_mibs_cache()

Equivalent to gc_mibs_cache/3.

gc_mibs_cache/1

Equivalent to gc_mibs_cache/3.

gc_mibs_cache/2

Equivalent to gc_mibs_cache/3.

gc_mibs_cache(Agent, Age, GcLimit)

Perform mib server cache gc.

get(Agent, Vars)

Equivalent to get/3.

get(Agent, Vars, Context)

Performs a GET operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

get_agent_caps()

Returns all AGENT-CAPABILITY statements in the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

get_next(Agent, Vars)

Equivalent to get_next/3.

get_next(Agent, Vars, Context)

Performs a GET-NEXT operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

info()

Equivalent to info/1.

info(Agent)

Returns a list (a dictionary) containing information about the agent. Information includes loaded MIBs, registered sub-agents, some information about the memory allocation.

int_to_enum(Name, Int)

Equivalent to int_to_enum/3.

int_to_enum(Db, Name, Int)

Converts the integer Int to the corresponding symbolic value of the enumerated object or type Name in a MIB. The MIB must be loaded.

invalidate_mibs_cache()

Equivalent to invalidate_mibs_cache/1.

invalidate_mibs_cache(Agent)

Invalidate the mib server cache.

load_mib(Mib)

Equivalent to load_mib/2.

load_mib(Agent, Mib)

Load a single Mib into an agent. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example

load_mibs(Mibs)

Equivalent to load_mibs/3.

load_mibs/2

Equivalent to load_mibs/3.

load_mibs(Agent, Mibs, Force)

Load Mibs into an agent. If the agent cannot load all MIBs (the default value of the Force argument is false), it will indicate where loading was aborted. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

log_to_io(LogDir)

Equivalent to log_to_io/7.

log_to_io/2

Equivalent to log_to_io/7.

log_to_io/3

Equivalent to log_to_io/7.

log_to_io/4

Equivalent to log_to_io/7.

log_to_io/5

Equivalent to log_to_io/7.

log_to_io/6

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable format and prints it on stdio. LogName defaults to "snmpa_log". LogFile defaults to "snmpa.log".

log_to_txt(LogDir)

Equivalent to log_to_txt/8.

log_to_txt/2

Equivalent to log_to_txt/8.

log_to_txt/3

Equivalent to log_to_txt/8.

log_to_txt/4

Equivalent to log_to_txt/8.

log_to_txt/5

Equivalent to log_to_txt/8.

log_to_txt/6

Equivalent to log_to_txt/8.

log_to_txt/7

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable text file. OutFile defaults to "./snmpa_log.txt". LogName defaults to "snmpa_log". LogFile defaults to "snmpa.log".

me_of(Oid)

Equivalent to me_of/2.

me_of(Agent, Oid)

Finds the mib entry corresponding to the Oid.

mib_of(Oid)

Equivalent to mib_of/2.

mib_of(Agent, Oid)

Finds the mib corresponding to the Oid.

name_to_oid(Name)

Equivalent to name_to_oid/2.

name_to_oid(Db, Name)

Looks up the OBJECT IDENTIFIER of a MIB object, given the symbolic name. Note, the OBJECT IDENTIFIER is given for the object, not for an instance.

oid_to_name(Oid)

Equivalent to oid_to_name/2.

oid_to_name(Db, Oid)

Looks up the symbolic name of a MIB object, given OBJECT IDENTIFIER.

print_mib_info()

Prints the content of all the (snmp) tables and variables for all mibs handled by the snmp agent.

print_mib_tables()

Prints the content of all the (snmp) tables for all mibs handled by the snmp agent.

print_mib_variables()

Prints the content of all the (snmp) variables for all mibs handled by the snmp agent.

register_notification_filter(Id, Mod, Data)

Equivalent to register_notification_filter/5.

register_notification_filter/4

Accepted type specifications are

register_notification_filter(Agent, Id, Mod, Data, Where)

Registers a notification filter.

register_subagent(Agent, SubTree, SubAgent)

Registers a sub-agent under a sub-tree of another agent.

restart_set_worker()

Equivalent to restart_set_worker/1.

restart_set_worker(Agent)

Restart the set worker process of a multi-threaded agent.

restart_worker()

Equivalent to restart_worker/1.

restart_worker(Agent)

Restart the worker process of a multi-threaded agent.

send_notification2(Agent, Notification, SendOpts)

Send the notification Notification to the management targets defined for notify-name (name) in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context.

send_notification(Agent, Notification, Receiver)

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, Varbinds)

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds)

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds, LocalEngineID)

Sends the notification Notification to the management targets defined for NotifyName in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context.

set_log_type(NewType)

Equivalent to set_log_type/2.

set_log_type(Agent, NewType)

Changes the run-time Audit Trail log type.

set_request_limit(NewLimit)

Equivalent to set_request_limit/2.

set_request_limit(Agent, NewLimit)

Changes the request limit.

unload_mib(Mib)

Equivalent to unload_mib/2.

unload_mib(Agent, Mib)

Unload a single Mib from an agent.

unload_mibs(Mibs)

Equivalent to unload_mibs/3.

unload_mibs/2

Equivalent to unload_mibs/3.

unload_mibs(Agent, Mibs, Force)

Unload Mibs from an agent. If it cannot unload all MIBs (the default value of the Force argument is false), it will indicate where unloading was aborted.

unregister_notification_filter(Id)

Equivalent to unregister_notification_filter/2.

unregister_notification_filter(Agent, Id)

Unregister a notification filter.

unregister_subagent(Agent, SubAgentOidOrPid)

Unregister a sub-agent. If the second argument is a pid, then that sub-agent will be unregistered from all trees in Agent.

update_mibs_cache_age(Age)

Equivalent to update_mibs_cache_age/2.

update_mibs_cache_age(Agent, Age)

Change the mib server cache age property.

update_mibs_cache_gclimit(GcLimit)

Equivalent to update_mibs_cache_gclimit/2.

update_mibs_cache_gclimit(Agent, GcLimit)

Change the mib server cache gclimit property.

verbosity(Target, Verbosity)

Sets 'verbosity' for the indicated process(s)

whereis_mib(MibName)

Equivalent to whereis_mib/2.

whereis_mib(Agent, MibName)

Get the full path to the (compiled) mib-file.

which_aliasnames()

Retrieve all alias-names known to the agent.

which_mibs()

Equivalent to which_mibs/1.

which_mibs(Agent)

Retrieve the list of all the mibs loaded into this agent. Default is the master agent.

which_mibs_cache_size()

Equivalent to which_mibs_cache_size/1.

which_mibs_cache_size(Agent)

Retrieve the size of the mib server cache.

which_notification_filter()

Equivalent to which_notification_filter/1.

which_notification_filter(Agent)

List all notification filters in an agent.

which_notifications()

Retrieve all notifications (and traps) known to the agent.

which_tables()

Retrieve all tables known to the agent.

which_transports()

Retrieve all configured transports.

which_variables()

Retrieve all variables known to the agent.

Types

db()

-type db() :: volatile | persistent | mnesia.

discovery_handler()

-type discovery_handler() :: module().

Module implementing the snmpa_discovery_handler behaviour.

me()

-type me() :: snmp:me().

mib_storage()

-type mib_storage() :: [mib_storage_opt()].

mib_storage_module()

-type mib_storage_module() :: atom().

mib_storage_opt()

-type mib_storage_opt() :: {module, mib_storage_module()} | {options, mib_storage_options()}.

mib_storage_options()

-type mib_storage_options() :: list().

name()

-type name() :: table_name() | variable_name().

name_db()

-type name_db() :: {name(), db()}.

nfilter_id()

-type nfilter_id() :: term().

nfilter_position()

-type nfilter_position() :: first | last | {insert_before, nfilter_id()} | {insert_after, nfilter_id()}.

notification_delivery_info()

-type notification_delivery_info() ::
          snmpa_notification_delivery_info_receiver:notification_delivery_info().

How shall (notification) delivery info be reported.

pdu_type()

-type pdu_type() :: snmp:pdu_type().

table_name()

-type table_name() :: atom().

transport_kind()

-type transport_kind() :: req_responder | trap_sender.

variable_name()

-type variable_name() :: atom().

Functions

add_agent_caps(Oid, Descr)

-spec add_agent_caps(Oid, Descr) -> Index when Oid :: snmp:oid(), Descr :: string(), Index :: integer().

This function can be used to add an AGENT-CAPABILITY statement to the sysORTable in the agent. The table is defined in the SNMPv2-MIB.

backup(BackupDir)

-spec backup(BackupDir) -> ok | {error, Reason}
                when BackupDir :: string(), Reason :: backup_in_progress | term().

Equivalent to backup/2.

backup(Agent, BackupDir)

-spec backup(Agent, BackupDir) -> ok | {error, Reason}
                when
                    Agent :: pid() | AgentName,
                    AgentName :: atom(),
                    BackupDir :: string(),
                    Reason :: backup_in_progress | term().

Backup persistent/permanent data handled by the agent (such as local-db, mib-data and vacm).

Data stored by mnesia is not handled.

BackupDir cannot be identical to DbDir.

Simultaneous backup calls are not allowed. That is, two different processes cannot simultaneously successfully call this function. One of them will be first, and succeed. The second will fail with the error reason backup_in_progress.

change_log_size(NewSize)

-spec change_log_size(NewSize) -> ok | {error, Reason} when NewSize :: snmp:log_size(), 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 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.

convert_config(OldConfig)

-spec convert_config(OldConfig) -> NewConfig when OldConfig :: list(), NewConfig :: list().

This off-line utility function can be used to convert the old snmp application config (pre snmp-4.0) to the new snmp agent config (as of snmp-4.0).

For information about the old config (OldConfig) see the OTP R9C documentation.

For information about the current agent config (AgentConfig), see the Configuring the application chapter of the SNMP user's guide.

current_address()

-spec current_address() -> {value, Address} | false when Address :: term().

Get the address of the request currently being processed by the agent.

Note that this function is intended to be called by the instrumentation functions and only if it is executed in the context of the agent process (e.g. it does not work if called from a spawned process).

current_community()

-spec current_community() -> {value, Community} | false when Community :: snmp_community_mib:name().

Get the community of the request currently being processed by the agent.

Note that this function is intended to be called by the instrumentation functions and only if it is executed in the context of the agent process (e.g. it does not work if called from a spawned process).

current_context()

-spec current_context() -> {value, Context} | false when Context :: snmp_community_mib:context_name().

Get the context of the request currently being processed by the agent.

Note that this function is intended to be called by the instrumentation functions and only if it is executed in the context of the agent process (e.g. it does not work if called from a spawned process).

current_request_id()

-spec current_request_id() -> {value, RequestId} | false when RequestId :: integer().

Get the request-id of the request currently being processed by the agent.

Note that this function is intended to be called by the instrumentation functions and only if it is executed in the context of the agent process (e.g. it does not work if called from a spawned process).

del_agent_caps(Index)

-spec del_agent_caps(Index) -> snmp:void() when Index :: integer().

This function can be used to delete an AGENT-CAPABILITY statement to the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

disable_mibs_cache()

-spec disable_mibs_cache() -> snmp:void().

Equivalent to disable_mibs_cache/1.

disable_mibs_cache(Agent)

-spec disable_mibs_cache(Agent) -> snmp:void() when Agent :: pid() | AgentName, AgentName :: atom().

Disable the mib server cache.

disable_mibs_cache_autogc()

-spec disable_mibs_cache_autogc() -> snmp:void().

Equivalent to disable_mibs_cache_autogc/1.

disable_mibs_cache_autogc(Agent)

-spec disable_mibs_cache_autogc(Agent) -> snmp:void()
                                   when Agent :: pid() | AgentName, AgentName :: atom().

Disable automatic gc of the mib server cache.

discovery(TargetName, Notification)

-spec discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error, Reason}
                   when
                       TargetName :: string(),
                       Notification :: atom(),
                       ManagerEngineID :: snmp_framework_mib:engine_id(),
                       Reason :: term().

Equivalent to discovery/6.

discovery/3

-spec discovery(TargetName, Notification, Varbinds) -> {ok, ManagerEngineID} | {error, Reason}
                   when
                       TargetName :: string(),
                       Notification :: atom(),
                       Varbinds :: [Varbind],
                       Varbind ::
                           {Variable :: atom(), Value} |
                           {OID :: snmp:oid(), Value} |
                           {Column :: atom(), RowIndex :: snmp:row_index(), Value},
                       Value :: term(),
                       ManagerEngineID :: snmp_framework_mib:engine_id(),
                       Reason :: term();
               (TargetName, Notification, ContextName) -> {ok, ManagerEngineID} | {error, Reason}
                   when
                       TargetName :: string(),
                       Notification :: atom(),
                       ContextName :: snmp_community_mib:context_name(),
                       ManagerEngineID :: snmp_framework_mib:engine_id(),
                       Reason :: term().

Equivalent to discovery/6.

discovery/4

-spec discovery(TargetName, Notification, ContextName, Varbinds) ->
                   {ok, ManagerEngineID} | {error, Reason}
                   when
                       TargetName :: string(),
                       Notification :: atom(),
                       ContextName :: snmp_community_mib:context_name(),
                       Varbinds :: [Varbind],
                       Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                       Variable :: atom(),
                       Column :: atom(),
                       RowIndex :: snmp:row_index(),
                       OID :: snmp:oid(),
                       Value :: term(),
                       ManagerEngineID :: snmp_framework_mib:engine_id(),
                       Reason :: term();
               (TargetName, Notification, Varbinds, DiscoHandler) ->
                   {ok, ManagerEngineID} | {error, Reason}
                   when
                       TargetName :: string(),
                       Notification :: atom(),
                       Varbinds :: [Varbind],
                       Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                       Variable :: atom(),
                       Column :: atom(),
                       RowIndex :: snmp:row_index(),
                       OID :: snmp:oid(),
                       Value :: term(),
                       DiscoHandler :: discovery_handler(),
                       ManagerEngineID :: snmp_framework_mib:engine_id(),
                       Reason :: term().

Equivalent to discovery/6.

discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler)

-spec discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler) ->
                   {ok, ManagerEngineID} | {error, Reason}
                   when
                       TargetName :: string(),
                       Notification :: atom(),
                       ContextName :: snmp_community_mib:context_name(),
                       Varbinds :: [Varbind],
                       Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                       Variable :: atom(),
                       Column :: atom(),
                       RowIndex :: snmp:row_index(),
                       OID :: snmp:oid(),
                       Value :: term(),
                       DiscoHandler :: discovery_handler(),
                       ManagerEngineID :: snmp_framework_mib:engine_id(),
                       Reason :: term().

Equivalent to discovery/6.

discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler, ExtraInfo)

-spec discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler, ExtraInfo) ->
                   {ok, ManagerEngineID} | {error, Reason}
                   when
                       TargetName :: string(),
                       Notification :: atom(),
                       ContextName :: snmp_community_mib:context_name(),
                       Varbinds :: [Varbind],
                       Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {OID, Value},
                       Variable :: atom(),
                       Column :: atom(),
                       RowIndex :: snmp:row_index(),
                       OID :: snmp:oid(),
                       Value :: term(),
                       DiscoHandler :: discovery_handler(),
                       ExtraInfo :: term(),
                       ManagerEngineID :: snmp_framework_mib:engine_id(),
                       Reason :: term().

Initiate the discovery process with the manager identified by TargetName using the notification Notification.

This function is synchronous, which means that it will return when the discovery process has been completed or failed.

The DiscoHandler module is used during the discovery process. See discovery handler for more info.

The ExtraInfo argument is passed on to the callback functions of the DiscoHandler.

Note

If we are not at security-level noAuthNoPriv, this could be complicated, since the agent will then continue with stage 2, before which the usm-related updates must be done.

Note

The default discovery handler will require additional actions by the caller and the discovery will not work if the security-level is higher then noAuthNoPriv.

enable_mibs_cache()

-spec enable_mibs_cache() -> snmp:void().

Equivalent to enable_mibs_cache/1.

enable_mibs_cache(Agent)

-spec enable_mibs_cache(Agent) -> snmp:void() when Agent :: pid() | AgentName, AgentName :: atom().

Enable the mib server cache.

enable_mibs_cache_autogc()

-spec enable_mibs_cache_autogc() -> snmp:void().

Equivalent to enable_mibs_cache_autogc/1.

enable_mibs_cache_autogc(Agent)

-spec enable_mibs_cache_autogc(Agent) -> snmp:void()
                                  when Agent :: pid() | AgentName, AgentName :: atom().

Enable automatic gc of the mib server cache.

enum_to_int(Name, Enum)

-spec enum_to_int(Name, Enum) -> {value, Int} | false
                     when Name :: atom(), Enum :: atom(), Int :: integer().

Equivalent to enum_to_int/3.

enum_to_int(Db, Name, Enum)

-spec enum_to_int(Db, Name, Enum) -> {value, Int} | false
                     when Db :: term(), Name :: atom(), Enum :: atom(), Int :: integer().

Converts the symbolic value Enum to the corresponding integer of the enumerated object or type Name in a MIB. The MIB must be loaded.

false is returned if the object or type is not defined in any loaded MIB, or if it does not define the symbolic value as enumerated.

Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0).

gc_mibs_cache()

-spec gc_mibs_cache() -> {ok, NumElementsGCed} | {error, Reason}
                       when NumElementsGCed :: non_neg_integer(), Reason :: term().

Equivalent to gc_mibs_cache/3.

gc_mibs_cache/1

-spec gc_mibs_cache(Agent) -> {ok, NumElementsGCed} | {error, Reason}
                       when
                           Agent :: pid() | AgentName,
                           AgentName :: atom(),
                           NumElementsGCed :: non_neg_integer(),
                           Reason :: term();
                   (Age) -> {ok, NumElementsGCed} | {error, Reason}
                       when Age :: pos_integer(), NumElementsGCed :: non_neg_integer(), Reason :: term().

Equivalent to gc_mibs_cache/3.

gc_mibs_cache/2

-spec gc_mibs_cache(Agent, Age) -> {ok, NumElementsGCed} | {error, Reason}
                       when
                           Agent :: pid() | AgentName,
                           AgentName :: atom(),
                           Age :: pos_integer(),
                           NumElementsGCed :: non_neg_integer(),
                           Reason :: term();
                   (Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}
                       when
                           Age :: pos_integer(),
                           GcLimit :: pos_integer() | infinity,
                           NumElementsGCed :: non_neg_integer(),
                           Reason :: term().

Equivalent to gc_mibs_cache/3.

gc_mibs_cache(Agent, Age, GcLimit)

-spec gc_mibs_cache(Agent, Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}
                       when
                           Agent :: pid() | AgentName,
                           AgentName :: atom(),
                           Age :: pos_integer(),
                           GcLimit :: pos_integer() | infinity,
                           NumElementsGCed :: non_neg_integer(),
                           Reason :: term().

Perform mib server cache gc.

Manually performs a mib server cache gc. This can be done regardless of the value of the autogc option. The NumElementsGCed value indicates how many elements where actually removed from the cache.

get(Agent, Vars)

-spec get(Agent, Vars) -> Values | {error, Reason}
             when
                 Agent :: pid() | AgentName,
                 AgentName :: atom(),
                 Vars :: [snmp:oid()],
                 Values :: [term()],
                 Reason :: term().

Equivalent to get/3.

get(Agent, Vars, Context)

-spec get(Agent, Vars, Context) -> Values | {error, Reason}
             when
                 Agent :: pid() | AgentName,
                 AgentName :: atom(),
                 Vars :: [snmp:oid()],
                 Context :: snmp_community_mib:context_name(),
                 Values :: [term()],
                 Reason :: term().

Performs a GET operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

Note that the request specific parameters (such as current_request_id/0) are not accessible for the instrumentation functions if this function is used.

get_agent_caps()

-spec get_agent_caps() -> Caps
                        when
                            Caps :: [[Cap]],
                            Cap :: SysORIndex | SysORID | SysORDescr | SysORUpTime,
                            SysORIndex :: integer(),
                            SysORID :: snmp:oid(),
                            SysORDescr :: string(),
                            SysORUpTime :: integer().

Returns all AGENT-CAPABILITY statements in the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

Note that the Erlang type language do not permit us to properly describe what this function returns. The exact return is:

[[SysORIndex, SysORID, SysORDescr, SysORUpTime]]

get_next(Agent, Vars)

-spec get_next(Agent, Vars) -> Values | {error, Reason}
                  when
                      Agent :: pid() | AgentName,
                      AgentName :: atom(),
                      Vars :: [snmp:oid()],
                      Values :: [{snmp:oid(), term()}],
                      Reason :: term().

Equivalent to get_next/3.

get_next(Agent, Vars, Context)

-spec get_next(Agent, Vars, Context) -> Values | {error, Reason}
                  when
                      Agent :: pid() | AgentName,
                      AgentName :: atom(),
                      Vars :: [snmp:oid()],
                      Context :: snmp_community_mib:context_name(),
                      Values :: [{snmp:oid(), term()}],
                      Reason :: {atom(), snmp:oid()}.

Performs a GET-NEXT operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

Note that the request specific parameters (such as snmpa:current_request_id/0 are not accessible for the instrumentation functions if this function is used.

info()

-spec info() -> Info when Info :: [{Key, Value}], Key :: term(), Value :: term().

Equivalent to info/1.

info(Agent)

-spec info(Agent) -> Info
              when
                  Agent :: pid() | AgentName,
                  AgentName :: atom(),
                  Info :: [{Key, Value}],
                  Key :: term(),
                  Value :: term().

Returns a list (a dictionary) containing information about the agent. Information includes loaded MIBs, registered sub-agents, some information about the memory allocation.

int_to_enum(Name, Int)

-spec int_to_enum(Name, Int) -> {value, Enum} | false
                     when Name :: atom(), Int :: integer(), Enum :: atom().

Equivalent to int_to_enum/3.

int_to_enum(Db, Name, Int)

-spec int_to_enum(Db, Name, Int) -> {value, Enum} | false
                     when Db :: term(), Name :: atom(), Int :: integer(), Enum :: atom().

Converts the integer Int to the corresponding symbolic value of the enumerated object or type Name in a MIB. The MIB must be loaded.

false is returned if the object or type is not defined in any loaded MIB, or if it does not define the symbolic value as enumerated.

Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0).

invalidate_mibs_cache()

-spec invalidate_mibs_cache() -> snmp:void().

Equivalent to invalidate_mibs_cache/1.

invalidate_mibs_cache(Agent)

-spec invalidate_mibs_cache(Agent) -> snmp:void() when Agent :: pid() | AgentName, AgentName :: atom().

Invalidate the mib server cache.

The entire contents of the cache will be deleted.

load_mib(Mib)

(since OTP R16B02)

-spec load_mib(Mib) -> ok | {error, Reason} when Mib :: string(), Reason :: already_loaded | term().

Equivalent to load_mib/2.

load_mib(Agent, Mib)

(since OTP R16B02)

-spec load_mib(Agent, Mib) -> ok | {error, Reason}
                  when
                      Agent :: pid() | AgentName,
                      AgentName :: atom(),
                      Mib :: string(),
                      Reason :: already_loaded | term().

Load a single Mib into an agent. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example:

          Dir = code:priv_dir(my_app) ++ "/mibs/",
          snmpa:load_mib(snmp_master_agent, Dir ++ "MY-MIB").

load_mibs(Mibs)

-spec load_mibs(Mibs) -> ok | {error, Reason}
                   when
                       Mibs :: [MibName],
                       MibName :: string(),
                       Reason :: {'load aborted at', MibName, InternalReason},
                       InternalReason :: already_loaded | term().

Equivalent to load_mibs/3.

load_mibs/2

-spec load_mibs(Agent, Mibs) -> ok | {error, Reason}
                   when
                       Agent :: pid() | AgentName,
                       AgentName :: atom(),
                       Mibs :: [MibName],
                       MibName :: string(),
                       Reason :: {'load aborted at', MibName, InternalReason},
                       InternalReason :: already_loaded | term();
               (Mibs, Force) -> ok | {error, Reason}
                   when
                       Mibs :: [MibName],
                       MibName :: string(),
                       Force :: boolean(),
                       Reason :: {'load aborted at', MibName, InternalReason},
                       InternalReason :: already_loaded | term().

Equivalent to load_mibs/3.

load_mibs(Agent, Mibs, Force)

(since OTP R16B02)

-spec load_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
                   when
                       Agent :: pid() | AgentName,
                       AgentName :: atom(),
                       Mibs :: [MibName],
                       MibName :: string(),
                       Force :: boolean(),
                       Reason :: {'load aborted at', MibName, InternalReason},
                       InternalReason :: already_loaded | term().

Load Mibs into an agent. If the agent cannot load all MIBs (the default value of the Force argument is false), it will indicate where loading was aborted. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

          Dir = code:priv_dir(my_app) ++ "/mibs/",
          snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).

If Force = true then the agent will continue attempting to load each mib even after failing to load a previous mib. Use with care.

log_to_io(LogDir)

(since OTP R15B01)

-spec log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/2

(since OTP R15B01)

-spec log_to_io(LogDir, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/3

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/4

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/5

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName, LogFile, Start) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Start :: null | snmp:log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/6

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Start :: null | snmp:log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Start :: null | snmp:log_time(),
                       Stop :: null | snmp:log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

(since OTP R16B03)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: string(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Start :: null | snmp:log_time(),
                       Stop :: null | snmp:log_time(),
                       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. LogName defaults to "snmpa_log". LogFile defaults to "snmpa.log".

The Block option indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

See snmp:log_to_io/7 for more info.

log_to_txt(LogDir)

(since OTP R15B01)

-spec log_to_txt(LogDir) -> snmp:void() when LogDir :: snmp:dir().

Equivalent to log_to_txt/8.

log_to_txt/2

-spec log_to_txt(LogDir, Block) -> snmp:void() when LogDir :: snmp:dir(), Block :: boolean();
                (LogDir, Mibs) -> snmp:void() when LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()].

Equivalent to log_to_txt/8.

log_to_txt/3

-spec log_to_txt(LogDir, Mibs, Block) -> snmp:void()
                    when LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()], Block :: boolean();
                (LogDir, Mibs, OutFile) -> snmp:void()
                    when LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()], OutFile :: file:filename().

Equivalent to log_to_txt/8.

log_to_txt/4

-spec log_to_txt(LogDir, Mibs, OutFile, Block) -> snmp:void()
                    when
                        LogDir :: snmp:dir(),
                        Mibs :: [snmp:mib_name()],
                        OutFile :: file:filename(),
                        Block :: boolean();
                (LogDir, Mibs, OutFile, LogName) -> snmp:void()
                    when
                        LogDir :: snmp:dir(),
                        Mibs :: [snmp:mib_name()],
                        OutFile :: file:filename(),
                        LogName :: string().

Equivalent to log_to_txt/8.

log_to_txt/5

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, Block) -> snmp:void()
                    when
                        LogDir :: snmp:dir(),
                        Mibs :: [snmp:mib_name()],
                        OutFile :: file:filename(),
                        LogName :: string(),
                        Block :: boolean();
                (LogDir, Mibs, OutFile, LogName, LogFile) -> snmp:void()
                    when
                        LogDir :: snmp:dir(),
                        Mibs :: [snmp:mib_name()],
                        OutFile :: file:filename(),
                        LogName :: string(),
                        LogFile :: string().

Equivalent to log_to_txt/8.

log_to_txt/6

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) -> snmp:void()
                    when
                        LogDir :: snmp:dir(),
                        Mibs :: [snmp:mib_name()],
                        OutFile :: file:filename(),
                        LogName :: string(),
                        LogFile :: string(),
                        Block :: boolean(),
                        Start :: null | snmp:log_time().

Equivalent to log_to_txt/8.

log_to_txt/7

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> snmp:void()
                    when
                        LogDir :: snmp:dir(),
                        Mibs :: [snmp:mib_name()],
                        OutFile :: file:filename(),
                        LogName :: string(),
                        LogFile :: string(),
                        Block :: boolean(),
                        Start :: null | snmp:log_time();
                (LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> snmp:void()
                    when
                        LogDir :: snmp:dir(),
                        Mibs :: [snmp:mib_name()],
                        OutFile :: file:filename(),
                        LogName :: string(),
                        LogFile :: string(),
                        Start :: null | snmp:log_time(),
                        Stop :: null | snmp:log_time().

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

(since OTP R16B03)

-spec log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) -> snmp:void()
                    when
                        LogDir :: snmp:dir(),
                        Mibs :: [snmp:mib_name()],
                        OutFile :: file:filename(),
                        LogName :: string(),
                        LogFile :: string(),
                        Block :: boolean(),
                        Start :: null | snmp:log_time(),
                        Stop :: null | snmp:log_time().

Converts an Audit Trail Log to a readable text file. OutFile defaults to "./snmpa_log.txt". LogName defaults to "snmpa_log". LogFile defaults to "snmpa.log".

The Block option indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

See snmp:log_to_txt/8 for more info.

me_of(Oid)

-spec me_of(Oid) -> {ok, Me} | {error, Reason} when Oid :: snmp:oid(), Me :: snmp:me(), Reason :: term().

Equivalent to me_of/2.

me_of(Agent, Oid)

-spec me_of(Agent, Oid) -> {ok, Me} | {error, Reason}
               when
                   Agent :: pid() | AgentName,
                   AgentName :: atom(),
                   Oid :: snmp:oid(),
                   Me :: snmp:me(),
                   Reason :: term().

Finds the mib entry corresponding to the Oid.

If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be <table>.<entry>.<col>.<any>

mib_of(Oid)

-spec mib_of(Oid) -> {ok, MibName} | {error, Reason}
                when Oid :: snmp:oid(), MibName :: atom(), Reason :: term().

Equivalent to mib_of/2.

mib_of(Agent, Oid)

-spec mib_of(Agent, Oid) -> {ok, MibName} | {error, Reason}
                when
                    Agent :: pid() | AgentName,
                    AgentName :: atom(),
                    Oid :: snmp:oid(),
                    MibName :: atom(),
                    Reason :: term().

Finds the mib corresponding to the Oid.

If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be <table>.<entry>.<col>.<any>.

name_to_oid(Name)

-spec name_to_oid(Name) -> {value, Oid} | false when Name :: atom(), Oid :: snmp:oid().

Equivalent to name_to_oid/2.

name_to_oid(Db, Name)

-spec name_to_oid(Db, Name) -> {value, Oid} | false when Db :: term(), Name :: atom(), Oid :: snmp:oid().

Looks up the OBJECT IDENTIFIER of a MIB object, given the symbolic name. Note, the OBJECT IDENTIFIER is given for the object, not for an instance.

false is returned if the object is not defined in any loaded MIB.

Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0).

oid_to_name(Oid)

-spec oid_to_name(Oid) -> {value, Name} | false when Oid :: snmp:oid(), Name :: atom().

Equivalent to oid_to_name/2.

oid_to_name(Db, Oid)

-spec oid_to_name(Db, Oid) -> {value, Name} | false when Db :: term(), Oid :: snmp:oid(), Name :: atom().

Looks up the symbolic name of a MIB object, given OBJECT IDENTIFIER.

false is returned if the object is not defined in any loaded MIB.

Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0).

print_mib_info()

(since OTP R14B02)

-spec print_mib_info() -> snmp:void().

Prints the content of all the (snmp) tables and variables for all mibs handled by the snmp agent.

print_mib_tables()

(since OTP R14B02)

-spec print_mib_tables() -> snmp:void().

Prints the content of all the (snmp) tables for all mibs handled by the snmp agent.

print_mib_variables()

(since OTP R14B02)

-spec print_mib_variables() -> snmp:void().

Prints the content of all the (snmp) variables for all mibs handled by the snmp agent.

register_notification_filter(Id, Mod, Data)

-spec register_notification_filter(Id, Mod, Data) -> ok | {error, Reason}
                                      when
                                          Id :: nfilter_id(),
                                          Mod :: module(),
                                          Data :: term(),
                                          Reason :: term().

Equivalent to register_notification_filter/5.

register_notification_filter/4

-spec register_notification_filter(Agent | Id, Id | Mod, Mod | Data, Data | Where) ->
                                      ok | {error, Reason}
                                      when
                                          Agent :: pid() | AgentName,
                                          AgentName :: atom(),
                                          Id :: nfilter_id(),
                                          Mod :: module(),
                                          Data :: term(),
                                          Where :: nfilter_position(),
                                          Reason :: term().

Accepted type specifications are:

-spec register_notification_filter(Agent, Id, Mod, Data) -> ok | {error, Reason}.
-spec register_notification_filter(Id, Mod, Data, Where) -> ok | {error, Reason}.

register_notification_filter(Agent, Id, Mod, Data, Where)

-spec register_notification_filter(Agent, Id, Mod, Data, Where) -> ok | {error, Reason}
                                      when
                                          Agent :: pid() | AgentName,
                                          AgentName :: atom(),
                                          Id :: nfilter_id(),
                                          Mod :: module(),
                                          Data :: term(),
                                          Where :: nfilter_position(),
                                          Reason :: term().

Registers a notification filter.

Mod is a module implementing the snmpa_notification_filter behaviour.

Data will be passed on to the filter when calling the functions of the behaviour.

register_subagent(Agent, SubTree, SubAgent)

-spec register_subagent(Agent, SubTree, SubAgent) -> ok | {error, Reason}
                           when
                               Agent :: pid() | AgentName,
                               AgentName :: atom(),
                               SubTree :: snmp:oid(),
                               SubAgent :: pid(),
                               Reason :: term().

Registers a sub-agent under a sub-tree of another agent.

It is easy to make mistakes when registering sub-agents and this activity should be done carefully. For example, a strange behaviour would result from the following configuration:

snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1),
snmp_agent:register_subagent(SA1,[1,2,3], SA2).

SA2 will not get requests starting with object identifier [1,2,3] since SA1 does not.

restart_set_worker()

-spec restart_set_worker() -> snmp:void().

Equivalent to restart_set_worker/1.

restart_set_worker(Agent)

-spec restart_set_worker(Agent) -> snmp:void() when Agent :: pid | AgentName, AgentName :: atom().

Restart the set worker process of a multi-threaded agent.

This is a utility function, that can be useful when e.g. debugging instrumentation functions.

restart_worker()

-spec restart_worker() -> snmp:void().

Equivalent to restart_worker/1.

restart_worker(Agent)

-spec restart_worker(Agent) -> snmp:void() when Agent :: pid | AgentName, AgentName :: atom().

Restart the worker process of a multi-threaded agent.

This is a utility function, that can be useful when e.g. debugging instrumentation functions.

send_notification2(Agent, Notification, SendOpts)

(since OTP R14B03)

-spec send_notification2(Agent, Notification, SendOpts) -> snmp:void()
                            when
                                Agent :: pid() | AgentName,
                                AgentName :: atom(),
                                Notification :: atom(),
                                SendOpts :: [SendOpt],
                                SendOpt ::
                                    {receiver, Receiver} |
                                    {name, snmp_notification_mib:notify_name()} |
                                    {context, snmp_community_mib:context_name()} |
                                    {varbinds, [Varbind]} |
                                    {local_engine_id, snmp_framework_mib:engine_id()} |
                                    {extra, term()},
                                Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                                Tag :: term(),
                                Recv :: pid() | atom() | MFA,
                                MFA :: {Mod, Func, Args},
                                Mod :: module(),
                                Func :: atom(),
                                Args :: list(),
                                Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                                Variable :: atom(),
                                Column :: atom(),
                                RowIndex :: snmp:row_index(),
                                Oid :: snmp:oid(),
                                Value :: term().

Send the notification Notification to the management targets defined for notify-name (name) in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context.

If no name is specified (or if it is ""), the notification is sent to all management targets.

If no context is specified, the default context, "", is used.

The send option receiver specifies where information about delivery of Inform-Requests should be sent. The agent sends Inform-Requests and waits for acknowledgments from the management targets. The receiver can have three values:

no_receiver - No information is delivered.

notification_delivery_info/0 - The information is delivered via a function call according to this data.

{tag(), tag_receiver()} - The information is delivered either via messages or via a function call according to the value of tag_receiver().

Delivery is done differently depending on the value of tag_receiver():

pid() | registered_name() - The info will be delivered in the following messages:

{snmp_targets, tag(), Addresses}

This informs the user which target addresses the notification was sent to.

{snmp_notification, tag(), {got_response, Address}}

This informs the user that this target address acknowledged the notification.

{snmp_notification, tag(), {no_response, Address}}

This informs the user that this target address did not acknowledge the notification.

The notification is sent as an Inform-Request to each target address in Addresses and if there are no targets for which an Inform-Request is sent, Addresses is the empty list [].

The tag_receiver() will first be sent the snmp_targets message, and then for each address in Addresses list, one of the two snmp_notification messages.

{Mod, Func, Args} - The info will be delivered via the function call:

Mod:Func([Msg | Args])

where Msg has the same content and purpose as the messages descrived above.

The 'process oid' "tag" that can be provided with the variable name / oids is intended to be used for oid post processing. The value 'keep', which is the default, leaves the oid as is. The value 'truncate', will cause the oid to be "truncated". That is, any trailing ".0" will be removed.

Note

There is a way to exclude a varbind from the notification. In the normal varbinds list, providing the special value '$ignore-oid' (instead of a normal value) will exclude this varbind from the notification.

A define for this has been added to the snmp_types.hrl include file, NOTIFICATION_IGNORE_VB_VALUE.

Note

The extra info is not normally interpreted by the agent, instead it is passed through to the net-if process. It is up to the implementor of that process to make use of this data.

The version of net-if provided by this application makes no use of this data, with one exception: Any tuple containing the atom snmpa_default_notification_extra_info may be used by the agent and is therefore reserved.

See the net-if incoming messages for sending a trap and notification for more info.

send_notification(Agent, Notification, Receiver)

-spec send_notification(Agent, Notification, Receiver) -> snmp:void()
                           when
                               Agent :: pid() | AgentName,
                               AgentName :: atom(),
                               Notification :: atom(),
                               Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                               Tag :: term(),
                               Recv :: pid() | atom() | MFA,
                               MFA :: {Mod, Func, Args},
                               Mod :: module(),
                               Func :: atom(),
                               Args :: list().

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, Varbinds)

-spec send_notification(Agent, Notification, Receiver, Varbinds) -> snmp:void()
                           when
                               Agent :: pid() | AgentName,
                               AgentName :: atom(),
                               Notification :: atom(),
                               Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                               Tag :: term(),
                               Recv :: pid() | atom() | MFA,
                               MFA :: {Mod, Func, Args},
                               Mod :: module(),
                               Func :: atom(),
                               Args :: list(),
                               Varbinds :: [Varbind],
                               Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                               Variable :: atom(),
                               Column :: atom(),
                               RowIndex :: snmp:row_index(),
                               Oid :: snmp:oid(),
                               Value :: term().

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)

-spec send_notification(Agent, Notification, Receiver, NotifyName, Varbinds) -> snmp:void()
                           when
                               Agent :: pid() | AgentName,
                               AgentName :: atom(),
                               Notification :: atom(),
                               Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                               Tag :: term(),
                               Recv :: pid() | atom() | MFA,
                               MFA :: {Mod, Func, Args},
                               Mod :: module(),
                               Func :: atom(),
                               Args :: list(),
                               NotifyName :: snmp_notification_mib:notify_name(),
                               Varbinds :: [Varbind],
                               Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                               Variable :: atom(),
                               Column :: atom(),
                               RowIndex :: snmp:row_index(),
                               Oid :: snmp:oid(),
                               Value :: term().

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds)

-spec send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds) -> snmp:void()
                           when
                               Agent :: pid() | AgentName,
                               AgentName :: atom(),
                               Notification :: atom(),
                               Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                               Tag :: term(),
                               Recv :: pid() | atom() | MFA,
                               MFA :: {Mod, Func, Args},
                               Mod :: module(),
                               Func :: atom(),
                               Args :: list(),
                               NotifyName :: snmp_notification_mib:notify_name(),
                               ContextName :: snmp_community_mib:context_name(),
                               Varbinds :: [Varbind],
                               Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                               Variable :: atom(),
                               Column :: atom(),
                               RowIndex :: snmp:row_index(),
                               Oid :: snmp:oid(),
                               Value :: term().

Equivalent to send_notification/7.

send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds, LocalEngineID)

(since OTP R14B)

-spec send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds, LocalEngineID) ->
                           snmp:void()
                           when
                               Agent :: pid() | AgentName,
                               AgentName :: atom(),
                               Notification :: atom(),
                               Receiver :: no_receiver | {Tag, Recv} | notification_delivery_info(),
                               Tag :: term(),
                               Recv :: pid() | atom() | MFA,
                               MFA :: {Mod, Func, Args},
                               Mod :: module(),
                               Func :: atom(),
                               Args :: list(),
                               NotifyName :: snmp_notification_mib:notify_name(),
                               ContextName :: snmp_community_mib:context_name(),
                               Varbinds :: [Varbind],
                               Varbind :: {Variable, Value} | {Column, RowIndex, Value} | {Oid, Value},
                               Variable :: atom(),
                               Column :: atom(),
                               RowIndex :: snmp:row_index(),
                               Oid :: snmp:oid(),
                               Value :: term(),
                               LocalEngineID :: snmp_framework_mib:engine_id().

Sends the notification Notification to the management targets defined for NotifyName in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context.

If no NotifyName is specified (or if it is ""), the notification is sent to all management targets (Addresses below).

If no ContextName is specified, the default "" context is used.

The parameter Receiver specifies where information about delivery of Inform-Requests should be sent. The agent sends Inform-Requests and waits for acknowledgments from the managers. Receiver can have three values:

no_receiver - No information is delivered.

notification_delivery_info/0 - The information is delivered via a function call according to this data.

{Tag, Recv} - The information is delivered either via messages or via a function call according to the value of Recv.

If Receiver has the value {Tag, Recv}, the delivery is done according to Recv:

pid() | atom() - The info will be delivered in the following messages:

{snmp_targets, Tag, Addresses}

This inform the user which target addresses the notification was sent to.

{snmp_notification, Tag, {got_response, Address}}

This informs the user that this target address acknowledged the notification.

{snmp_notification, Tag, {no_response, Address}}

This informs the user that this target address did not acknowledge notification.

The notification is sent as an Inform-Request to each target address in Addresses and if there are no targets for which an Inform-Request is sent, Addresses is the empty list [].

The receiver will first be sent the snmp_targets message, and then for each address in Addresses list, one of the two snmp_notification messages.

{Mod, Func, Args} - The info will be delivered via the function call:

Mod:Func([Msg | Args])

where Msg has the same content and purpose as the messages descrived above.

Address is a management target address and Addresses is a list of management target addresses. They are defined as followes:

        Addresses  = [address()]
        Address    = address()
        address()  = v1_address() | v3_address()
        v1_address() = {TDomain, TAddress}
        v3_address() = {{TDomain, TAddress}, V3MsgData}
        TDomain    = tdoamin()
        TAddress   = taddress()
        tdomain()  = The oid of snmpUDPDomain
                     This is the only supported transport domain.
        taddress() = [A1, A2, A3, A4, P1, P3]
                     The 4 first bytes makes up the IP-address and the last 2,
                     the UDP-port number.
        V3MsgData  = v3_msg_data()
        v3_msg_data() = term()

If Receiver is a notification_delivery_info/0 record, then the information about the notification delivery will be delivered to the receiver via the callback functions defined by the snmpa_notification_delivery_info_receiver behaviour according to the content of the notification_delivery_info/0 record.

The optional argument Varbinds defines values for the objects in the notification. If no value is given for an object, the Agent performs a get-operation to retrieve the value.

Varbinds is a list of Varbind, where each Varbind is one of:

{Variable, Value}, where Variable is the symbolic name of a scalar variable referred to in the notification specification.

{Column, RowIndex, Value}, where Column is the symbolic name of a column variable. RowIndex is a list of indices for the specified element. If this is the case, the OBJECT IDENTIFIER sent in the notification is the RowIndex appended to the OBJECT IDENTIFIER for the table column. This is the OBJECT IDENTIFIER which specifies the element.

{OID, Value}, where OID is the OBJECT IDENTIFIER for an instance of an object, scalar variable, or column variable.

For example, to specify that sysLocation should have the value "upstairs" in the notification, we could use one of:

{sysLocation, "upstairs"} or

{[1,3,6,1,2,1,1,6,0], "upstairs"} or

{?sysLocation_instance, "upstairs"} (provided that the generated .hrl file is included)

If a variable in the notification is a table element, the RowIndex for the element must be given in the Varbinds list. In this case, the OBJECT IDENTIFIER sent in the notification is the OBJECT IDENTIFIER that identifies this element. This OBJECT IDENTIFIER could be used in a get operation later.

This function is asynchronous, and does not return any information. If an error occurs, user_err/2 of the error report module is called and the notification is discarded.

Note

Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

ExtraInfo is not normally used in any way by the agent. It is intended to be passed along to the net-if process, which is a component that a user can implement themself. The users own net-if may then make use of ExtraInfo. The net-if provided with this application does not process ExtraInfo.

There is one exception. Any tuple containing the atom snmpa_default_notification_extra_info will, in this context, be considered belonging to this application, and may be processed by the agent.

set_log_type(NewType)

-spec set_log_type(NewType) -> {ok, OldType} | {error, Reason}
                      when NewType :: snmp:atl_type(), OldType :: snmp:atl_type(), Reason :: term().

Equivalent to set_log_type/2.

set_log_type(Agent, NewType)

-spec set_log_type(Agent, NewType) -> {ok, OldType} | {error, Reason}
                      when
                          Agent :: pid() | AgentName,
                          AgentName :: atom(),
                          NewType :: snmp:atl_type(),
                          OldType :: snmp:atl_type(),
                          Reason :: term().

Changes the run-time Audit Trail log type.

Note that this has no effect on the application configuration as defined by configuration files, so a node restart will revert the config to whatever is in those files.

This function is primarily useful in testing/debugging scenarios.

set_request_limit(NewLimit)

-spec set_request_limit(NewLimit) -> {ok, OldLimit} | {error, Reason}
                           when
                               NewLimit :: infinity | non_neg_integer(),
                               OldLimit :: infinity | non_neg_integer(),
                               Reason :: term().

Equivalent to set_request_limit/2.

set_request_limit(Agent, NewLimit)

-spec set_request_limit(Agent, NewLimit) -> {ok, OldLimit} | {error, Reason}
                           when
                               Agent :: pid() | AgentName,
                               AgentName :: atom(),
                               NewLimit :: infinity | non_neg_integer(),
                               OldLimit :: infinity | non_neg_integer(),
                               Reason :: term().

Changes the request limit.

Note that this has no effect on the application configuration as defined by configuration files, so a node restart will revert the config to whatever is in those files.

This function is primarily useful in load regulation scenarios.

unload_mib(Mib)

(since OTP R16B02)

-spec unload_mib(Mib) -> ok | {error, Reason} when Mib :: string(), Reason :: not_loaded | term().

Equivalent to unload_mib/2.

unload_mib(Agent, Mib)

(since OTP R16B02)

-spec unload_mib(Agent, Mib) -> ok | {error, Reason}
                    when
                        Agent :: pid() | AgentName,
                        AgentName :: atom(),
                        Mib :: string(),
                        Reason :: not_loaded | term().

Unload a single Mib from an agent.

unload_mibs(Mibs)

-spec unload_mibs(Mibs) -> ok | {error, Reason}
                     when
                         Mibs :: [MibName],
                         MibName :: string(),
                         Reason :: {'unload aborted at', MibName, InternalReason},
                         InternalReason :: not_loaded | term().

Equivalent to unload_mibs/3.

unload_mibs/2

-spec unload_mibs(Agent, Mibs) -> ok | {error, Reason}
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         Mibs :: [MibName],
                         MibName :: string(),
                         Reason :: {'unload aborted at', MibName, InternalReason},
                         InternalReason :: not_loaded | term();
                 (Mibs, Force) -> ok | {error, Reason}
                     when
                         Mibs :: [MibName],
                         MibName :: string(),
                         Force :: boolean(),
                         Reason :: {'unload aborted at', MibName, InternalReason},
                         InternalReason :: not_loaded | term().

Equivalent to unload_mibs/3.

unload_mibs(Agent, Mibs, Force)

(since OTP R16B02)

-spec unload_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         Mibs :: [MibName],
                         MibName :: string(),
                         Force :: boolean(),
                         Reason :: {'unload aborted at', MibName, InternalReason},
                         InternalReason :: not_loaded | term().

Unload Mibs from an agent. If it cannot unload all MIBs (the default value of the Force argument is false), it will indicate where unloading was aborted.

If Force = true then the agent will continue attempting to unload each mib even after failing to unload a previous mib. Use with care.

unregister_notification_filter(Id)

-spec unregister_notification_filter(Id) -> ok | {error, Reason}
                                        when Id :: nfilter_id(), Reason :: term().

Equivalent to unregister_notification_filter/2.

unregister_notification_filter(Agent, Id)

-spec unregister_notification_filter(Agent, Id) -> ok | {error, Reason}
                                        when
                                            Agent :: pid() | AgentName,
                                            AgentName :: atom(),
                                            Id :: nfilter_id(),
                                            Reason :: term().

Unregister a notification filter.

unregister_subagent(Agent, SubAgentOidOrPid)

-spec unregister_subagent(Agent, SubAgentOidOrPid) -> ok | {error, Reason}
                             when
                                 Agent :: pid() | AgentName,
                                 AgentName :: atom(),
                                 SubAgentOidOrPid :: snmp:oid() | pid(),
                                 Reason :: term().

Unregister a sub-agent. If the second argument is a pid, then that sub-agent will be unregistered from all trees in Agent.

update_mibs_cache_age(Age)

-spec update_mibs_cache_age(Age) -> ok | {error, Reason} when Age :: pos_integer(), Reason :: term().

Equivalent to update_mibs_cache_age/2.

update_mibs_cache_age(Agent, Age)

-spec update_mibs_cache_age(Agent, Age) -> ok | {error, Reason}
                               when
                                   Agent :: pid() | AgentName,
                                   AgentName :: atom(),
                                   Age :: pos_integer(),
                                   Reason :: term().

Change the mib server cache age property.

update_mibs_cache_gclimit(GcLimit)

-spec update_mibs_cache_gclimit(GcLimit) -> ok | {error, Reason}
                                   when GcLimit :: pos_integer(), Reason :: term().

Equivalent to update_mibs_cache_gclimit/2.

update_mibs_cache_gclimit(Agent, GcLimit)

-spec update_mibs_cache_gclimit(Agent, GcLimit) -> ok | {error, Reason}
                                   when
                                       Agent :: pid() | AgentName,
                                       AgentName :: atom(),
                                       GcLimit :: pos_integer(),
                                       Reason :: term().

Change the mib server cache gclimit property.

verbosity(Target, Verbosity)

-spec verbosity(Target, Verbosity) -> snmp:void()
                   when
                       Target :: all | LogicalName | PidOrAgentName,
                       LogicalName :: net_if | note_store | mib_server | symbolic_store | local_db,
                       PidOrAgentName :: pid() | master_agent | atom(),
                       Verbosity :: SNMPVerb | SubAgent,
                       SNMPVerb :: snmp:verbosity(),
                       SubAgent :: {subagents, snmp:verbosity()}.

Sets 'verbosity' for the indicated process(s):

all - Sets verbosity for all the agent processes; net_if, note_store, mib_server, symbolic_store, local_db and master_agent (and sub-agents).

net_if - Sets verbosity for the net-if process.

note_store - Sets verbosity for the note store process.

mib_server - Sets verbosity for the mib server process.

symbolic_store - Sets verbosity for the symbolic store process.

local_db - Sets verbosity for the local-db process.

master_agent | pid() when Verbosity = {subagents, snmp:verbosity()} - Sets verbosity for all sub-agent(s) controlled by this (master) agent.

master_agent | pid() | atom() - Sets verbosity for the agent process.

The following text documents expected input-output relations

If Target :: all | net_if | note_store | mib_server | symbolic_store | local_db, then Verbosity :: snmp:verbosity().

If Target :: master_agent, then Verbosity :: {subagents, snmp:verbosity()}

If `Target :: pid() | atom()`,
then `Verbosity :: snmp:verbosity() | {subagents, snmp:verbosity()}`.

whereis_mib(MibName)

-spec whereis_mib(MibName) -> {ok, MibFile} | {error, Reason}
                     when MibName :: atom(), MibFile :: string(), Reason :: term().

Equivalent to whereis_mib/2.

whereis_mib(Agent, MibName)

-spec whereis_mib(Agent, MibName) -> {ok, MibFile} | {error, Reason}
                     when
                         Agent :: pid() | AgentName,
                         AgentName :: atom(),
                         MibName :: atom(),
                         MibFile :: string(),
                         Reason :: term().

Get the full path to the (compiled) mib-file.

which_aliasnames()

-spec which_aliasnames() -> AliasNames when AliasNames :: [AliasName], AliasName :: atom().

Retrieve all alias-names known to the agent.

which_mibs()

-spec which_mibs() -> Mibs when Mibs :: [{MibName, MibFile}], MibName :: atom(), MibFile :: string().

Equivalent to which_mibs/1.

which_mibs(Agent)

-spec which_mibs(Agent) -> Mibs
                    when
                        Agent :: pid() | AgentName,
                        AgentName :: atom(),
                        Mibs :: [{MibName, MibFile}],
                        MibName :: atom(),
                        MibFile :: string().

Retrieve the list of all the mibs loaded into this agent. Default is the master agent.

which_mibs_cache_size()

(since OTP R14B)

-spec which_mibs_cache_size() -> {ok, Size} | {error, Reason}
                               when Size :: non_neg_integer(), Reason :: term().

Equivalent to which_mibs_cache_size/1.

which_mibs_cache_size(Agent)

(since OTP R14B)

-spec which_mibs_cache_size(Agent) -> {ok, Size} | {error, Reason}
                               when
                                   Agent :: pid() | AgentName,
                                   AgentName :: atom(),
                                   Size :: non_neg_integer(),
                                   Reason :: term().

Retrieve the size of the mib server cache.

which_notification_filter()

-spec which_notification_filter() -> Filters when Filters :: [FilterId], FilterId :: nfilter_id().

Equivalent to which_notification_filter/1.

which_notification_filter(Agent)

-spec which_notification_filter(Agent) -> Filters
                                   when
                                       Agent :: pid() | AgentName,
                                       AgentName :: atom(),
                                       Filters :: [FilterId],
                                       FilterId :: nfilter_id().

List all notification filters in an agent.

which_notifications()

-spec which_notifications() -> Notifications
                             when
                                 Notifications :: [{Name, MibName, Info}],
                                 Name :: atom(),
                                 MibName :: atom(),
                                 Info :: term().

Retrieve all notifications (and traps) known to the agent.

which_tables()

-spec which_tables() -> Tables when Tables :: [Table], Table :: atom().

Retrieve all tables known to the agent.

which_transports()

(since OTP 23.3)

-spec which_transports() -> Transports
                          when
                              Transports :: [Transport],
                              Transport :: {TDomain, TAddress} | {TDomain, TAddress, Kind},
                              TDomain :: snmp:tdomain(),
                              TAddress :: {IpAddr, IpPort},
                              IpAddr :: inet:ip_address(),
                              IpPort :: inet:port_number(),
                              Kind :: transport_kind().

Retrieve all configured transports.

which_variables()

-spec which_variables() -> Variables when Variables :: [Variable], Variable :: atom().

Retrieve all variables known to the agent.

snmpa_conf

Utility functions for handling the agent config files.

The module snmpa_conf contains various utility functions to use for manipulating (write/read/append) the config files of the SNMP agent.

Summary

Types

agent_entry()

An opaque term that represents an entry in the 'agent' config.

community_entry()

An opaque term that represents an entry in the 'community' (agent) config.

context_entry()

An opaque term that represents an entry in the 'context' (agent) config.

extended_transport_address()

intAgentTransport()

ip_address()

notify_entry()

An opaque term that represents an entry in the 'notify' (agent) config.

port_info()

Port number 0 (zero) cannot be specified directly (it is used internally). Instead the atom 'system' should be used.

range()

Min < Max

ranges()

snmp_ip_address()

standard_entry()

An opaque term that represents an entry in the 'standard' (agent) config.

target_addr_entry()

An opaque term that represents an entry in the 'target address' (agent) config.

target_params_entry()

An opaque term that represents an entry in the 'target parameters' (agent) config.

transport_address()

transport_opts()

transportAddress()

transportAddressIPv4()

transportAddressIPv4WithoutPort()

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

transportAddressIPv4WithPort()

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

transportAddressIPv6()

transportAddressIPv6WithoutPort()

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

transportAddressIPv6WithPort()

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

transportAddressMask()

transportAddressWithoutPort()

transportAddressWithPort()

transportDomain()

usm_entry()

An opaque term that represents an entry in the 'user based sm' (agent) config.

vacm_acc_entry()

An opaque term that represents an (access) entry in the 'vacm access' (agent) config.

vacm_entry()

An basically opaque term that represents an entry in the 'view based acm' (agent) config.

vacm_s2g_entry()

An opaque term that represents an (security to group) entry in the 'vacm security to group' (agent) config.

vacm_vtf_entry()

An opaque term that represents an (tree family) entry in the 'vacm tree family' (agent) config.

word()

Functions

agent_entry(Tag, Val)

Create an entry for the agent config file, agent.conf.

append_agent_config(Dir, Conf)

Append the config to the current agent config file.

append_community_config(Dir, Conf)

Append the community config to the current agent community config file.

append_context_config(Dir, Conf)

Append the context config to the current agent context config file.

append_notify_config(Dir, Conf)

Append the notify config to the current agent notify config file.

append_standard_config(Dir, Conf)

Append the standard config to the current agent standard config file.

append_target_addr_config(Dir, Conf)

Append the target_addr config to the current agent target_addr config file.

append_target_params_config(Dir, Conf)

Append the target_params config to the current agent target_params config file.

append_usm_config(Dir, Conf)

Append the usm config to the current agent usm config file.

append_vacm_config(Dir, Conf)

Append the vacm config to the current agent vacm config file.

community_entry(CommIndex)

Create an entry for the agent community config file, community.conf.

community_entry(CommIndex, CommName, SecName, CtxName, TransportTag)

Create an entry for the agent community config file, community.conf.

context_entry(Ctx)

Create an entry for the agent context config file, context.conf.

notify_entry(Name, Tag, Type)

Create an entry for the agent notify config file, notify.conf.

read_agent_config(Dir)

Read the current agent config file.

read_community_config(Dir)

Read the current agent community config file.

read_context_config(Dir)

Read the current agent context config file.

read_notify_config(Dir)

Read the current agent notify config file.

read_standard_config(Dir)

Read the current agent standard config file.

read_target_addr_config(Dir)

Read the current agent target_addr config file.

read_target_params_config(Dir)

Read the current agent target_params config file.

read_usm_config(Dir)

Read the current agent usm config file.

read_vacm_config(Dir)

Read the current agent vacm config file.

standard_entry(Tag, Val)

Create an entry for the agent standard config file, standard.conf.

target_addr_entry/6

Create an entry for the agent target_addr config file, target_addr.conf.

target_addr_entry/7

Create an entry for the agent target_addr config file, target_addr.conf.

target_addr_entry/8

Create an entry for the agent target_addr config file, target_addr.conf.

target_addr_entry(Name, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize)

Create an entry for the agent target_addr config file, target_addr.conf.

target_params_entry(Name, Vsn)

Create an entry for the agent target_params config file, target_params.conf.

target_params_entry(Name, Vsn, SecName, SecLevel)

Create an entry for the agent target_params config file, target_params.conf.

target_params_entry(Name, MPModel, SecModel, SecName, SecLevel)

Create an entry for the agent target_params config file, target_params.conf.

usm_entry(EngineID)

Create an entry for the agent usm config file, usm.conf.

usm_entry(EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey)

Create an entry for the agent usm config file, usm.conf.

vacm_acc_entry(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV)

Create an (access) entry for the agent vacm config file, vacm.conf.

vacm_s2g_entry(SecModel, SecName, GroupName)

Create an (security to group) entry for the agent vacm config file, vacm.conf.

vacm_vtf_entry(ViewName, ViewSubtree)

Create an (view tree family) entry for the agent vacm config file, vacm.conf.

vacm_vtf_entry(ViewName, ViewSubtree, ViewType, ViewMask)

Create an (view tree family) entry for the agent vacm config file, vacm.conf.

write_agent_config(Dir, Conf)

Equivalent to write_agent_config/3.

write_agent_config(Dir, Hdr, Conf)

Write the agent config to the agent config file.

write_community_config(Dir, Conf)

Equivalent to write_community_config/3.

write_community_config(Dir, Hdr, Conf)

Write the agent community config to the agent community config file.

write_context_config(Dir, Conf)

Equivalent to write_context_config/3.

write_context_config(Dir, Hdr, Conf)

Write the agent context config to the agent context config file.

write_notify_config(Dir, Conf)

Equivalent to write_notify_config/3.

write_notify_config(Dir, Hdr, Conf)

Write the agent notify config to the agent notify config file.

write_standard_config(Dir, Conf)

Equivalent to write_standard_config/3.

write_standard_config(Dir, Hdr, Conf)

Write the agent standard config to the agent standard config file.

write_target_addr_config(Dir, Conf)

Equivalent to write_target_addr_config/3.

write_target_addr_config(Dir, Hdr, Conf)

Write the agent target_addr config to the agent target_addr config file.

write_target_params_config(Dir, Conf)

Equivalent to write_target_params_config/3.

write_target_params_config(Dir, Hdr, Conf)

Write the agent target_params config to the agent target_params config file.

write_usm_config(Dir, Conf)

Equivalent to write_usm_config/3.

write_usm_config(Dir, Hdr, Conf)

Write the agent usm config to the agent usm config file.

write_vacm_config(Dir, Conf)

Equivalent to write_vacm_config/3.

write_vacm_config(Dir, Hdr, Conf)

Write the agent vacm config to the agent vacm config file.

Types

agent_entry()

-opaque agent_entry()

An opaque term that represents an entry in the 'agent' config.

community_entry()

-opaque community_entry()

An opaque term that represents an entry in the 'community' (agent) config.

context_entry()

-opaque context_entry()

An opaque term that represents an entry in the 'context' (agent) config.

extended_transport_address()

-type extended_transport_address() :: {inet:ip_address(), port_info()}.

intAgentTransport()

-type intAgentTransport() ::
          {transportDomain(), transport_address()} |
          {transportDomain(), extended_transport_address(), snmpa:transport_kind()} |
          {transportDomain(), extended_transport_address(), transport_opts()} |
          {transportDomain(), extended_transport_address(), snmpa:transport_kind(), transport_opts()}.

ip_address()

(not exported)

-type ip_address() :: inet:ip_address() | snmp_ip_address().

notify_entry()

-opaque notify_entry()

An opaque term that represents an entry in the 'notify' (agent) config.

port_info()

-type port_info() :: inet:port_number() | system | range() | ranges().

Port number 0 (zero) cannot be specified directly (it is used internally). Instead the atom 'system' should be used.

range()

-type range() :: {Min :: inet:port_number(), Max :: inet:port_number()}.

Min < Max

ranges()

-type ranges() :: [inet:port_number() | range()].

snmp_ip_address()

(not exported)

-type snmp_ip_address() :: [non_neg_integer()].

standard_entry()

-opaque standard_entry()

An opaque term that represents an entry in the 'standard' (agent) config.

target_addr_entry()

-opaque target_addr_entry()

An opaque term that represents an entry in the 'target address' (agent) config.

target_params_entry()

-opaque target_params_entry()

An opaque term that represents an entry in the 'target parameters' (agent) config.

transport_address()

-type transport_address() :: {ip_address(), inet:port_number()} | ip_address().

transport_opts()

(not exported)

-type transport_opts() :: list().

transportAddress()

-type transportAddress() :: transportAddressIPv4() | transportAddressIPv6().

transportAddressIPv4()

(not exported)

-type transportAddressIPv4() :: transportAddressIPv4WithPort() | transportAddressIPv4WithoutPort().

transportAddressIPv4WithoutPort()

(not exported)

-type transportAddressIPv4WithoutPort() :: inet:ip4_address() | [byte()].

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

The list variant, 4 bytes for address:

[byte() x 4]

transportAddressIPv4WithPort()

(not exported)

-type transportAddressIPv4WithPort() ::
          {transportAddressIPv4WithoutPort(), inet:port_number()} | [byte()].

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

The list variant, 4 bytes for address + 2 bytes for port:

[byte() x 4, byte() x 2]

transportAddressIPv6()

(not exported)

-type transportAddressIPv6() :: transportAddressIPv6WithPort() | transportAddressIPv6WithoutPort().

transportAddressIPv6WithoutPort()

(not exported)

-type transportAddressIPv6WithoutPort() :: inet:ip6_address() | [word()] | [byte()].

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

First list variant, 8 words for address:

[word() x 8]

Second list variant, 16 bytes for address:

[byte() x 16]

transportAddressIPv6WithPort()

(not exported)

-type transportAddressIPv6WithPort() ::
          {transportAddressIPv6WithoutPort(), inet:port_number()} |
          [word() | inet:port_number()] |
          [word() | byte()] |
          [byte()].

Because of limitations of the Erlang type language we cannot define this type in detail. Instead, we describe it here.

First list variant, 8 words for address + 1 word for port:

[word() x 8, inet:port_number()]

Second list variant, 8 words for address + 2 bytes for port:

[word() x 8, byte() x 2]

Third list variant, 16 bytes for address + 2 bytes for port:

[byte() x 16, byte() x 2]

transportAddressMask()

-type transportAddressMask() :: [] | transportAddressWithPort().

transportAddressWithoutPort()

-type transportAddressWithoutPort() ::
          transportAddressIPv4WithoutPort() | transportAddressIPv6WithoutPort().

transportAddressWithPort()

-type transportAddressWithPort() :: transportAddressIPv4WithPort() | transportAddressIPv6WithPort().

transportDomain()

-type transportDomain() :: snmp:tdomain().

usm_entry()

-opaque usm_entry()

An opaque term that represents an entry in the 'user based sm' (agent) config.

vacm_acc_entry()

-opaque vacm_acc_entry()

An opaque term that represents an (access) entry in the 'vacm access' (agent) config.

vacm_entry()

-type vacm_entry() :: vacm_s2g_entry() | vacm_acc_entry() | vacm_vtf_entry().

An basically opaque term that represents an entry in the 'view based acm' (agent) config.

vacm_s2g_entry()

-opaque vacm_s2g_entry()

An opaque term that represents an (security to group) entry in the 'vacm security to group' (agent) config.

vacm_vtf_entry()

-opaque vacm_vtf_entry()

An opaque term that represents an (tree family) entry in the 'vacm tree family' (agent) config.

word()

(not exported)

-type word() :: 0..65535.

Functions

agent_entry(Tag, Val)

-spec agent_entry(Tag, Val) -> AgentEntry
                     when
                         Tag ::
                             intAgentTransports | intAgentUDPPort | snmpEngineMaxMessageSize |
                             snmpEngineID,
                         Val :: term(),
                         AgentEntry :: agent_entry().

Create an entry for the agent config file, agent.conf.

The type of Val depends on the value of Tag:

intAgentTransports: [snmpa_conf:intAgentTransport() ] <mandatory>

intAgentUDPPort:inet:port_number() <optional>

snmpEngineMaxMessageSize:snmp_framework_mib:max_message_size() <mandatory>

snmpEngineID:snmp_framework_mib:engine_id() <mandatory>

See Agent Information for more info.

append_agent_config(Dir, Conf)

-spec append_agent_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [agent_entry()].

Append the config to the current agent config file.

Dir is the path to the directory where to store the config file.

See Agent Information for more info.

append_community_config(Dir, Conf)

-spec append_community_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [community_entry()].

Append the community config to the current agent community config file.

Dir is the path to the directory where to store the config file.

See Community for more info.

append_context_config(Dir, Conf)

-spec append_context_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [context_entry()].

Append the context config to the current agent context config file.

Dir is the path to the directory where to store the config file.

See Contexts for more info.

append_notify_config(Dir, Conf)

-spec append_notify_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [notify_entry()].

Append the notify config to the current agent notify config file.

Dir is the path to the directory where to store the config file.

See Notify Definitions for more info.

append_standard_config(Dir, Conf)

-spec append_standard_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [standard_entry()].

Append the standard config to the current agent standard config file.

Dir is the path to the directory where to store the config file.

See System Information for more info.

append_target_addr_config(Dir, Conf)

-spec append_target_addr_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [target_addr_entry()].

Append the target_addr config to the current agent target_addr config file.

Dir is the path to the directory where to store the config file.

See Target Address Definitions for more info.

append_target_params_config(Dir, Conf)

-spec append_target_params_config(Dir, Conf) -> ok
                                     when Dir :: snmp:dir(), Conf :: [target_params_entry()].

Append the target_params config to the current agent target_params config file.

Dir is the path to the directory where to store the config file.

See Target Parameters Definitions for more info.

append_usm_config(Dir, Conf)

-spec append_usm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [usm_entry()].

Append the usm config to the current agent usm config file.

Dir is the path to the directory where to store the config file.

See Security data for USM for more info.

append_vacm_config(Dir, Conf)

-spec append_vacm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [vacm_entry()].

Append the vacm config to the current agent vacm config file.

Dir is the path to the directory where to store the config file.

See MIB Views for VACM for more info.

community_entry(CommIndex)

-spec community_entry(CommIndex) -> CommunityEntry
                         when
                             CommIndex :: snmp_framework_mib:admin_string(),
                             CommunityEntry :: community_entry().

Create an entry for the agent community config file, community.conf.

CommunityIndex must be a non-empty string.

This function only accepts the following values of CommIndex:

"public" - Translates to the following call:

community_entry(CommunityIndex, CommunityIndex, "initial", "", "").

"all-rights" - Translates to the following call:

community_entry(CommunityIndex, CommunityIndex, CommunityIndex, "", "").

See Community for more info.

community_entry(CommIndex, CommName, SecName, CtxName, TransportTag)

-spec community_entry(CommIndex, CommName, SecName, CtxName, TransportTag) -> CommunityEntry
                         when
                             CommIndex :: snmp_community_mib:index(),
                             CommName :: snmp_community_mib:name(),
                             SecName :: snmp_community_mib:security_name(),
                             CtxName :: snmp_community_mib:context_name(),
                             TransportTag :: snmp_community_mib:transport_tag(),
                             CommunityEntry :: community_entry().

Create an entry for the agent community config file, community.conf.

CommunityIndex must be a non-empty string.

See Community for more info.

context_entry(Ctx)

-spec context_entry(Ctx) -> ContextEntry
                       when Ctx :: snmp_community_mib:context_name(), ContextEntry :: context_entry().

Create an entry for the agent context config file, context.conf.

See Contexts for more info.

notify_entry(Name, Tag, Type)

-spec notify_entry(Name, Tag, Type) -> NotifyEntry
                      when
                          Name :: snmp_notification_mib:notify_name(),
                          Tag :: snmp_notification_mib:notify_tag(),
                          Type :: snmp_notification_mib:notify_type(),
                          NotifyEntry :: notify_entry().

Create an entry for the agent notify config file, notify.conf.

Name must be a non-empty string.

See Notify Definitions for more info.

read_agent_config(Dir)

-spec read_agent_config(Dir) -> {ok, Conf} | {error, Reason}
                           when Dir :: snmp:dir(), Conf :: [agent_entry()], Reason :: term().

Read the current agent config file.

Dir is the path to the directory where to store the config file.

See Agent Information for more info.

read_community_config(Dir)

-spec read_community_config(Dir) -> {ok, Conf} | {error, Reason}
                               when Dir :: snmp:dir(), Conf :: [community_entry()], Reason :: term().

Read the current agent community config file.

Dir is the path to the directory where to store the config file.

See Communities for more info.

read_context_config(Dir)

-spec read_context_config(Dir) -> {ok, Conf} | {error, Reason}
                             when Dir :: snmp:dir(), Conf :: [context_entry()], Reason :: term().

Read the current agent context config file.

Dir is the path to the directory where to store the config file.

See Contexts for more info.

read_notify_config(Dir)

-spec read_notify_config(Dir) -> {ok, Conf} | {error, Reason}
                            when Dir :: snmp:dir(), Conf :: [notify_entry()], Reason :: term().

Read the current agent notify config file.

Dir is the path to the directory where to store the config file.

See Notify Definitions for more info.

read_standard_config(Dir)

-spec read_standard_config(Dir) -> {ok, Conf} | {error, Reason}
                              when Dir :: snmp:dir(), Conf :: [standard_entry()], Reason :: term().

Read the current agent standard config file.

Dir is the path to the directory where to store the config file.

See System Information for more info.

read_target_addr_config(Dir)

-spec read_target_addr_config(Dir) -> {ok, Conf} | {error, Reason}
                                 when Dir :: snmp:dir(), Conf :: [target_addr_entry()], Reason :: term().

Read the current agent target_addr config file.

Dir is the path to the directory where to store the config file.

See Target Address Definitions for more info.

read_target_params_config(Dir)

-spec read_target_params_config(Dir) -> {ok, Conf} | {error, Reason}
                                   when
                                       Dir :: snmp:dir(),
                                       Conf :: [target_params_entry()],
                                       Reason :: term().

Read the current agent target_params config file.

Dir is the path to the directory where to store the config file.

See Target Parameters Definitions for more info.

read_usm_config(Dir)

-spec read_usm_config(Dir) -> {ok, Conf} | {error, Reason}
                         when Dir :: snmp:dir(), Conf :: [usm_entry()], Reason :: term().

Read the current agent usm config file.

Dir is the path to the directory where to store the config file.

See Security data for USM for more info.

read_vacm_config(Dir)

-spec read_vacm_config(Dir) -> {ok, Conf} | {error, Reason}
                          when Dir :: snmp:dir(), Conf :: [vacm_entry()], Reason :: term().

Read the current agent vacm config file.

Dir is the path to the directory where to store the config file.

See MIB Views for VACM for more info.

standard_entry(Tag, Val)

-spec standard_entry(Tag, Val) -> StandardEntry
                        when
                            Tag ::
                                sysDescr | sysObjectID | sysContact | sysName | sysLocation |
                                sysServices | snmpEnableAuthenTraps,
                            Val :: term(),
                            StandardEntry :: standard_entry().

Create an entry for the agent standard config file, standard.conf.

The type of Val depends on the value of Tag:

sysDescr:string() <mandatory> - DisplayString (SIZE(0..255))

sysObjectID:snmp:oid() <mandatory> - OBJECT IDENTIFIER

sysContact:string() <mandatory> - DisplayString (SIZE(0..255))

sysName:string() <mandatory> - DisplayString (SIZE(0..255))

sysLocation:string() <mandatory> - DisplayString (SIZE(0..255))

sysLocation:non_neg_integer() <mandatory> - "A value which indicates the set of services that this entity primarily offers."

INTEGER (0..127)

snmpEnableAuthenTraps:enabled | disabled <mandatory> - INTEGER { enabled(1), disabled(2) }

See System Information for more info.

target_addr_entry/6

-spec target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId) -> TargetAddrEntry
                           when
                               Name :: snmp_target_mib:name(),
                               Domain :: transportDomain(),
                               Addr :: transportAddress(),
                               TagList :: snmp_target_mib:tag_list(),
                               ParamsName :: snmp_target_mib:params(),
                               EngineId :: snmp_framework_mib:engine_id(),
                               TargetAddrEntry :: target_addr_entry();
                       (Name, IP, TagList, ParamsName, EngineId, TMask) -> TargetAddrEntry
                           when
                               Name :: snmp_target_mib:name(),
                               IP :: inet:ip_address(),
                               TagList :: snmp_target_mib:tag_list(),
                               ParamsName :: snmp_target_mib:params(),
                               EngineId :: snmp_framework_mib:engine_id(),
                               TMask :: snmp_target_mib:tmask(),
                               TargetAddrEntry :: target_addr_entry().

Create an entry for the agent target_addr config file, target_addr.conf.

Name must be a non-empty string.

target_addr_entry/6 (1) translates to the following call: target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, []).

target_addr_entry/6 (2) translates to the following call (with Domain and Addr built from IP and the default port number): target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask, 2048).

See Target Address Definitions for more info.

target_addr_entry/7

(since OTP 17.3)

-spec target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask) -> TargetAddrEntry
                           when
                               Name :: snmp_target_mib:name(),
                               Domain :: transportDomain(),
                               Addr :: transportAddress(),
                               TagList :: snmp_target_mib:tag_list(),
                               ParamsName :: snmp_target_mib:params(),
                               EngineId :: snmp_framework_mib:engine_id(),
                               TMask :: snmp_target_mib:tmask(),
                               TargetAddrEntry :: target_addr_entry();
                       (Name, IP, Port, TagList, ParamsName, EngineId, TMask) -> TargetAddrEntry
                           when
                               Name :: snmp_target_mib:name(),
                               IP :: inet:ip_address(),
                               Port :: inet:port_number(),
                               TagList :: snmp_target_mib:tag_list(),
                               ParamsName :: snmp_target_mib:params(),
                               EngineId :: snmp_framework_mib:engine_id(),
                               TMask :: snmp_target_mib:tmask(),
                               TargetAddrEntry :: target_addr_entry().

Create an entry for the agent target_addr config file, target_addr.conf.

Name must be a non-empty string.

target_addr_entry/7 (1) translates to the following call: target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask, 2048).

target_addr_entry/7 (2) translates to the following call (with Domain and Addr built from IP and Port): target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask, 2048).

See Target Address Definitions for more info.

target_addr_entry/8

-spec target_addr_entry(Name, Domain, Addr, TagList, ParamsName, EngineId, TMask, MaxMessageSize) ->
                           TargetAddrEntry
                           when
                               Name :: snmp_target_mib:name(),
                               Domain :: transportDomain(),
                               Addr :: transportAddress(),
                               TagList :: snmp_target_mib:tag_list(),
                               ParamsName :: snmp_target_mib:params(),
                               EngineId :: snmp_framework_mib:engine_id(),
                               TMask :: snmp_target_mib:tmask(),
                               MaxMessageSize :: snmp_target_mib:mms(),
                               TargetAddrEntry :: target_addr_entry();
                       (Name, IP, Port, TagList, ParamsName, EngineId, TMask, MaxMessageSize) ->
                           TargetAddrEntry
                           when
                               Name :: snmp_target_mib:name(),
                               IP :: inet:ip_address(),
                               Port :: inet:port_number(),
                               TagList :: snmp_target_mib:tag_list(),
                               ParamsName :: snmp_target_mib:params(),
                               EngineId :: snmp_framework_mib:engine_id(),
                               TMask :: snmp_target_mib:tmask(),
                               MaxMessageSize :: snmp_target_mib:mms(),
                               TargetAddrEntry :: target_addr_entry().

Create an entry for the agent target_addr config file, target_addr.conf.

Name must be a non-empty string.

target_addr_entry/8 (1) translates to the following call: target_addr_entry(Name, Domain, Addr, 1500, 3, TagList, ParamsName, EngineId, TMask, MaxMessageSize).

target_addr_entry/8 (2) translates to the following call (with Domain and Addr built from IP and Port): target_addr_entry(Name, Domain, Addr, 1500, 3, TagList, ParamsName, EngineId, TMask, MaxMessageSize).

See Target Address Definitions for more info.

target_addr_entry(Name, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize)

-spec target_addr_entry(Name, Domain, Addr, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask,
                        MaxMessageSize) ->
                           TargetAddrEntry
                           when
                               Name :: snmp_target_mib:name(),
                               Domain :: transportDomain(),
                               Addr :: transportAddress(),
                               Timeout :: snmp:time_interval(),
                               RetryCount :: snmp_target_mib:retry_count(),
                               TagList :: snmp_target_mib:tag_list(),
                               ParamsName :: snmp_framework_mib:admin_string(),
                               EngineId :: snmp_framework_mib:engine_id(),
                               TMask :: snmp_target_mib:tmask(),
                               MaxMessageSize :: snmp_target_mib:mms(),
                               TargetAddrEntry :: target_addr_entry().

Create an entry for the agent target_addr config file, target_addr.conf.

Name must be a non-empty string.

See Target Address Definitions for more info.

target_params_entry(Name, Vsn)

-spec target_params_entry(Name, Vsn) -> TargetParamsEntry
                             when
                                 Name :: snmp_target_mib:name(),
                                 Vsn :: snmp:version(),
                                 TargetParamsEntry :: target_params_entry().

Create an entry for the agent target_params config file, target_params.conf.

Name must be a non-empty string.

target_params_entry/2 translates to the following call:

	  target_params_entry(Name, Vsn, "initial", noAuthNoPriv)

See Target Parameters Definitions for more info.

target_params_entry(Name, Vsn, SecName, SecLevel)

-spec target_params_entry(Name, Vsn, SecName, SecLevel) -> TargetParamsEntry
                             when
                                 Name :: snmp_target_mib:name(),
                                 Vsn :: snmp:version(),
                                 SecName :: snmp_framework_mib:admin_string(),
                                 SecLevel :: snmp_framework_mib:security_level(),
                                 TargetParamsEntry :: target_params_entry().

Create an entry for the agent target_params config file, target_params.conf.

Name must be a non-empty string.

Vsn translates into MPModel and SecModel as follows:

	  Vsn = v1 => MPModel = v1,  SecModel = v1
	  Vsn = v2 => MPModel = v2c, SecModel = v2c
	  Vsn = v3 => MPModel = v3,  SecModel = usm

target_params_entry/4 translates to the following call:

	  target_params_entry(Name, MPModel, SecModel, SecName, SecLevel)

Where MPModel and SecModel is mapped from Vsn, see above.

See Target Parameters Definitions for more info.

target_params_entry(Name, MPModel, SecModel, SecName, SecLevel)

-spec target_params_entry(Name, MPModel, SecModel, SecName, SecLevel) -> TargetParamsEntry
                             when
                                 Name :: snmp_target_mib:name(),
                                 MPModel :: snmp_framework_mib:message_processing_model(),
                                 SecModel :: snmp_framework_mib:security_model(),
                                 SecName :: snmp_framework_mib:admin_string(),
                                 SecLevel :: snmp_framework_mib:security_level(),
                                 TargetParamsEntry :: target_params_entry().

Create an entry for the agent target_params config file, target_params.conf.

Name must be a non-empty string.

See Target Parameters Definitions for more info.

usm_entry(EngineID)

-spec usm_entry(EngineID) -> UsmEntry
                   when EngineID :: snmp_framework_mib:engine_id(), UsmEntry :: usm_entry().

Create an entry for the agent usm config file, usm.conf.

usm_entry/1 translates to the following call:

	  usm_entry(EngineID,
	            "initial", "initial", zeroDotZero,
		    usmNoAuthProtocol, "", "",
		    usmNoPrivProtocol, "", "",
		    "", "", "").

See Security data for USM for more info.

usm_entry(EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey)

-spec usm_entry(EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC,
                OwnPrivKeyC, Public, AuthKey, PrivKey) ->
                   UsmEntry
                   when
                       EngineID :: snmp_framework_mib:engine_id(),
                       UserName :: snmp_user_based_sm_mib:name(),
                       SecName :: snmp_framework_mib:admin_string(),
                       Clone :: snmp_user_based_sm_mib:clone_from(),
                       AuthP :: snmp_user_based_sm_mib:auth_protocol(),
                       AuthKeyC :: snmp_user_based_sm_mib:key_change(),
                       OwnAuthKeyC :: snmp_user_based_sm_mib:key_change(),
                       PrivP :: snmp_user_based_sm_mib:priv_protocol(),
                       PrivKeyC :: snmp_user_based_sm_mib:key_change(),
                       OwnPrivKeyC :: snmp_user_based_sm_mib:key_change(),
                       Public :: snmp_user_based_sm_mib:public(),
                       AuthKey :: snmp_user_based_sm_mib:auth_key(),
                       PrivKey :: snmp_user_based_sm_mib:priv_key(),
                       UsmEntry :: usm_entry().

Create an entry for the agent usm config file, usm.conf.

See Security data for USM for more info.

vacm_acc_entry(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV)

-spec vacm_acc_entry(GroupName, Prefix, SecModel, SecLevel, Match, RV, WV, NV) -> VacmAccEntry
                        when
                            GroupName :: snmp_framework_mib:admin_string(),
                            Prefix :: snmp_view_based_acm_mib:context_prefix(),
                            SecModel :: snmp_framework_mib:security_model(),
                            SecLevel :: snmp_framework_mib:security_level(),
                            Match :: snmp_view_based_acm_mib:context_match(),
                            RV :: snmp_framework_mib:admin_string(),
                            WV :: snmp_framework_mib:admin_string(),
                            NV :: snmp_framework_mib:admin_string(),
                            VacmAccEntry :: vacm_acc_entry().

Create an (access) entry for the agent vacm config file, vacm.conf.

See MIB Views for VACM for more info.

vacm_s2g_entry(SecModel, SecName, GroupName)

-spec vacm_s2g_entry(SecModel, SecName, GroupName) -> VacmS2GEntry
                        when
                            SecModel :: snmp_framework_mib:security_model(),
                            SecName :: snmp_view_based_acm_mib:security_name(),
                            GroupName :: snmp_framework_mib:admin_string(),
                            VacmS2GEntry :: vacm_s2g_entry().

Create an (security to group) entry for the agent vacm config file, vacm.conf.

See MIB Views for VACM for more info.

vacm_vtf_entry(ViewName, ViewSubtree)

-spec vacm_vtf_entry(ViewName, ViewSubtree) -> VacmVtfEntry
                        when
                            ViewName :: snmp_framework_mib:admin_string(),
                            ViewSubtree :: snmp:oid(),
                            VacmVtfEntry :: VacmVtfEntry.

Create an (view tree family) entry for the agent vacm config file, vacm.conf.

vacm_vtf_entry/2 translates to the following call:

	  vacm_vtf_entry(ViewIndex, ViewSubtree, included, null).

See MIB Views for VACM for more info.

vacm_vtf_entry(ViewName, ViewSubtree, ViewType, ViewMask)

-spec vacm_vtf_entry(ViewName, ViewSubtree, ViewType, ViewMask) -> VacmVtfEntry
                        when
                            ViewName :: snmp_framework_mib:admin_string(),
                            ViewSubtree :: snmp:oid(),
                            ViewType :: snmp_view_based_acm_mib:view_type(),
                            ViewMask :: null | snmp_view_based_acm_mib:view_mask(),
                            VacmVtfEntry :: VacmVtfEntry.

Create an (view tree family) entry for the agent vacm config file, vacm.conf.

See MIB Views for VACM for more info.

write_agent_config(Dir, Conf)

-spec write_agent_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [agent_entry()].

Equivalent to write_agent_config/3.

write_agent_config(Dir, Hdr, Conf)

-spec write_agent_config(Dir, Hdr, Conf) -> ok
                            when Dir :: snmp:dir(), Hdr :: string(), Conf :: [agent_entry()].

Write the agent config to the agent config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Agent Information for more info.

write_community_config(Dir, Conf)

-spec write_community_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [community_entry()].

Equivalent to write_community_config/3.

write_community_config(Dir, Hdr, Conf)

-spec write_community_config(Dir, Hdr, Conf) -> ok
                                when Dir :: snmp:dir(), Hdr :: string(), Conf :: [community_entry()].

Write the agent community config to the agent community config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Community for more info.

write_context_config(Dir, Conf)

-spec write_context_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [context_entry()].

Equivalent to write_context_config/3.

write_context_config(Dir, Hdr, Conf)

-spec write_context_config(Dir, Hdr, Conf) -> ok
                              when Dir :: snmp:dir(), Hdr :: string(), Conf :: [context_entry()].

Write the agent context config to the agent context config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Contexts for more info.

write_notify_config(Dir, Conf)

-spec write_notify_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [notify_entry()].

Equivalent to write_notify_config/3.

write_notify_config(Dir, Hdr, Conf)

-spec write_notify_config(Dir, Hdr, Conf) -> ok
                             when Dir :: snmp:dir(), Hdr :: string(), Conf :: [notify_entry()].

Write the agent notify config to the agent notify config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Notify Definitions for more info.

write_standard_config(Dir, Conf)

-spec write_standard_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [standard_entry()].

Equivalent to write_standard_config/3.

write_standard_config(Dir, Hdr, Conf)

-spec write_standard_config(Dir, Hdr, Conf) -> ok
                               when Dir :: snmp:dir(), Hdr :: string(), Conf :: [standard_entry()].

Write the agent standard config to the agent standard config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See System Information for more info.

write_target_addr_config(Dir, Conf)

-spec write_target_addr_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [target_addr_entry()].

Equivalent to write_target_addr_config/3.

write_target_addr_config(Dir, Hdr, Conf)

-spec write_target_addr_config(Dir, Hdr, Conf) -> ok
                                  when Dir :: snmp:dir(), Hdr :: string(), Conf :: [target_addr_entry()].

Write the agent target_addr config to the agent target_addr config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Target Address Definitions for more info.

write_target_params_config(Dir, Conf)

-spec write_target_params_config(Dir, Conf) -> ok
                                    when Dir :: snmp:dir(), Conf :: [target_params_entry()].

Equivalent to write_target_params_config/3.

write_target_params_config(Dir, Hdr, Conf)

-spec write_target_params_config(Dir, Hdr, Conf) -> ok
                                    when
                                        Dir :: snmp:dir(),
                                        Hdr :: string(),
                                        Conf :: [target_params_entry()].

Write the agent target_params config to the agent target_params config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Target Parameters Definitions for more info.

write_usm_config(Dir, Conf)

-spec write_usm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [usm_entry()].

Equivalent to write_usm_config/3.

write_usm_config(Dir, Hdr, Conf)

-spec write_usm_config(Dir, Hdr, Conf) -> ok
                          when Dir :: snmp:dir(), Hdr :: string(), Conf :: [usm_entry()].

Write the agent usm config to the agent usm config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Security data for USM for more info.

write_vacm_config(Dir, Conf)

-spec write_vacm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [vacm_entry()].

Equivalent to write_vacm_config/3.

write_vacm_config(Dir, Hdr, Conf)

-spec write_vacm_config(Dir, Hdr, Conf) -> ok
                           when Dir :: snmp:dir(), Hdr :: string(), Conf :: [vacm_entry()].

Write the agent vacm config to the agent vacm config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See MIB Views for VACM for more info.

snmpa_discovery_handler behaviour

Behaviour module for the SNMP agent discovery handler.

This module defines the behaviour of the agent discovery handler. A snmpa_discovery_handler compliant module must export the following functions:

stage1_finish/3

The semantics of them and their exact signatures are explained below.

Summary

Callbacks

stage1_finish(TargetName, ManagerEngineID, ExtraInfo)

This function is called at the end of stage 1 of the discovery process. It should return either the atom ignore or {ok, usm_entry() | [usm_entry()]}. See usm_entry() and usm_entry/1,3 for more info.

Callbacks

stage1_finish(TargetName, ManagerEngineID, ExtraInfo)

-callback stage1_finish(TargetName, ManagerEngineID, ExtraInfo) ->
                           ignore | {ok, UsmEntry | [UsmEntry]} | {ok, UsmEntry | [UsmEntry], NewExtraInfo}
                           when
                               TargetName :: snmp_target_mib:name(),
                               ManagerEngineID :: snmp_framework_mib:engine_id(),
                               ExtraInfo :: term(),
                               UsmEntry :: snmp_user_based_sm_mib:usm_entry(),
                               NewExtraInfo :: term().

This function is called at the end of stage 1 of the discovery process. It should return either the atom ignore or {ok, usm_entry() | [usm_entry()]}. See usm_entry() and usm_entry/1,3 for more info.

If the function returns ignore, then it is assumed that either:

The caller (of the discovery function) will make the needed updates later.

The callback function itself did the updates.

In either case, the agent will do nothing, but return the retrieved ManagerEngineID (see snmpa:discovery/6 for more info) and possible continue with stage 2 of the discovery process.

The ExtraInfo argument is passed on from the snmpa:discovery/6 function.

This function may return an updated NewExtraInfo that will be used in subsequent calls to the callback functions. Intended for future use.

The purpose of this function is to generate the usm- related security data needed for usm processing in the agent. Specifically, updating the usmUserTable.

When an usm_entry() tuple (or a list of such tuples) is returned, this data is then added to the usmUserTable by the (master-) agent.

When an usm_entry() tuple (or a list of such tuples) is returned, this data is then added to the usmUserTable by the (master-) agent.

Note

Note that the function does not check if this entry already exists.

Note

Note that this function is executed in the context of the master-agent process.

snmpa_error

Functions for Reporting SNMP Errors

The module snmpa_error contains two callback functions which are called if an error occurs at different times during agent operation. These functions in turn calls the corresponding function in the configured error report module, which implements the actual report functionality.

Two simple implementation(s) is provided with the toolkit; the modules snmpa_error_logger which is the default and snmpa_error_io.

The error report module is configured using the directive error_report_mod, see configuration parameters.

Summary

Functions

config_err(Format, Args)

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

user_err(Format, Args)

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Functions

config_err(Format, Args)

-spec config_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

Format and Args are as in io:format(Format, Args).

user_err(Format, Args)

-spec user_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Format and Args are as in io:format(Format, Args).

snmpa_error_io

Functions for Reporting SNMP Errors on stdio

The module snmpa_error_io implements the snmp_error_report behaviour (see snmpa_error_report) containing two callback functions which are called in order to report SNMP errors.

This module provides a simple mechanism for reporting SNMP errors. Errors are written to stdout using the io module. It is provided as an simple example.

This module needs to be explicitly configured, see snmpa_error and configuration parameters.

Summary

Functions

config_err(Format, Args)

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

user_err(Format, Args)

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Functions

config_err(Format, Args)

-spec config_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

Format and Args are as in io:format(Format, Args).

user_err(Format, Args)

-spec user_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Format and Args are as in io:format(Format, Args).

snmpa_error_logger

Functions for Reporting SNMP Errors through the error_logger

The module snmpa_error_logger implements the snmpa_error_report behaviour (see snmpa_error_report) containing two callback functions which are called in order to report SNMP errors.

This module provides a simple mechanism for reporting SNMP errors. Errors are sent to the error_logger after a size check. Messages are truncated after 1024 chars. It is provided as an example.

This module is the default error report module, but can be explicitly configured, see snmpa_error and configuration parameters.

See Also

error_logger(3)

Summary

Functions

config_err(Format, Args)

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

user_err(Format, Args)

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Functions

config_err(Format, Args)

-spec config_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

Format and Args are as in io:format(Format, Args).

user_err(Format, Args)

-spec user_err(Format, Args) -> snmp:void() when Format :: string(), Args :: list().

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Format and Args are as in io:format(Format, Args).

snmpa_error_report behaviour

Behaviour module for reporting SNMP agent errors

This module defines the behaviour of the agent error reporting. A snmpa_error_report compliant module must export the following functions:

config_err/2

user_err/2

The semantics of them and their exact signatures are explained below.

Summary

Callbacks

config_err(Format, Args)

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

user_err(Format, Args)

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Callbacks

config_err(Format, Args)

-callback config_err(Format, Args) -> snmp:void() when Format :: string(), Args :: [term()].

The function is called if an error occurs during the configuration phase, for example if a syntax error is found in a configuration file.

Format and Args are as in io:format(Format, Args).

user_err(Format, Args)

-callback user_err(Format, Args) -> snmp:void() when Format :: string(), Args :: [term()].

The function is called if a user related error occurs at run-time, for example if a user defined instrumentation function returns erroneous.

Format and Args are as in io:format(Format, Args).

snmpa_local_db

The SNMP built-in database

The module snmpa_local_db contains functions for implementing tables (and variables) using the SNMP built-in database. The database exists in two instances, one volatile and one persistent. The volatile database is implemented with ets. The persistent database is implemented with dets.

There is a scaling problem with this database.

Insertions and deletions are inefficient for large tables.

This problem is best solved by using Mnesia instead.

The following functions describe the interface to snmpa_local_db. Each function has a Mnesia equivalent. The argument NameDb is a tuple {Name, Db} where Name is the symbolic name of the managed object (as defined in the MIB), and Db is either volatile or persistent. mnesia is not possible since all these functions are snmpa_local_db specific.

Common Data Types

In the functions defined below, the following limitation applies:

Db = volatile | persistent

See Also

ets(3), dets(3), snmp_generic(3)

Summary

Functions

dump()

This function can be used to manually dump the database to file.

match(Table, Pattern)

Performs an ets/dets matching on the table.

print()

Equivalent to print/2.

print(Table)

Equivalent to print/2.

print(Table, Db)

Prints the contents of the database on screen. This is useful for debugging since the STANDARD-MIB and OTP-SNMPEA-MIB (and maybe your own MIBs) are stored in snmpa_local_db.

table_create(Table)

Creates a table. If the table already exist, the old copy is destroyed.

table_create_row(Table, RowIndex, Row)

Creates a row in a table. Row is a tuple with values for all columns, including the index columns.

table_delete(Table)

Deletes a table.

table_delete_row(Table, RowIndex)

Deletes the row in the table.

table_exists(Table)

Checks if a table exists.

table_get_element(Table, RowIndex, Col)

Get a column value (element) from a row of the table.

table_get_row(Table, RowIndex)

Row is a tuple with values for all columns, including the index columns.

table_set_elements(Table, RowIndex, Cols)

Update the specified columnar objects of the row of this table.

Functions

dump()

-spec dump() -> ok | {error, Reason} when Reason :: term().

This function can be used to manually dump the database to file.

match(Table, Pattern)

-spec match(Table, Pattern) -> [Match]
               when
                   Table :: snmpa:name_db() | snmpa:name(),
                   Pattern :: ets:match_pattern(),
                   Match :: term().

Performs an ets/dets matching on the table.

See ets:match/2 for a description of Pattern and the return values.

print()

-spec print() -> term().

Equivalent to print/2.

print(Table)

-spec print(Table) -> term() when Table :: snmpa:name().

Equivalent to print/2.

print(Table, Db)

-spec print(Table, Db) -> term() when Table :: snmpa:name(), Db :: volatile | persistent.

Prints the contents of the database on screen. This is useful for debugging since the STANDARD-MIB and OTP-SNMPEA-MIB (and maybe your own MIBs) are stored in snmpa_local_db.

Table is an atom for a table in the database. When no name is supplied, the whole database is shown.

Note that these functions does not actually print, using io:format/2, instead they (just) return the information. If executed in a shell, the information will then be displayed (probably truncated) there.

A better use would be:

	  io:format("~p~n", [snmpa_local_db:print()]).

table_create(Table)

-spec table_create(Table) -> boolean() when Table :: snmpa:name_db() | snmpa:name().

Creates a table. If the table already exist, the old copy is destroyed.

Returns false if the NameDb argument is incorrectly specified, true otherwise.

Database (only table name specified) defaults to volatile.

table_create_row(Table, RowIndex, Row)

-spec table_create_row(Table, RowIndex, Row) -> boolean()
                          when
                              Table :: snmpa:name_db() | snmpa:name(),
                              RowIndex :: snmp:row_index(),
                              Row :: tuple().

Creates a row in a table. Row is a tuple with values for all columns, including the index columns.

Database (only table name specified) defaults to volatile.

table_delete(Table)

-spec table_delete(Table) -> true when Table :: snmpa:name_db() | snmpa:name().

Deletes a table.

Database (only table name specified) defaults to volatile.

table_delete_row(Table, RowIndex)

-spec table_delete_row(Table, RowIndex) -> boolean()
                          when Table :: snmpa:name_db() | snmpa:name(), RowIndex :: snmp:row_index().

Deletes the row in the table.

Database (only table name specified) defaults to volatile.

table_exists(Table)

-spec table_exists(Table) -> boolean() when Table :: snmpa:name_db() | snmpa:name().

Checks if a table exists.

Database (only table name specified) defaults to volatile.

table_get_element(Table, RowIndex, Col)

(since OTP 27.0)

-spec table_get_element(Table, RowIndex, Col) -> {value, Value} | undefined
                           when
                               Table :: snmpa:name_db() | snmpa:name(),
                               RowIndex :: snmp:row_index(),
                               Col :: snmp:column(),
                               Value :: term().

Get a column value (element) from a row of the table.

Database (only table name specified) defaults to volatile.

This function has existed for long time, but not had a proper since tag, so to simplify we set the since tag to when it was documented.

table_get_row(Table, RowIndex)

-spec table_get_row(Table, RowIndex) -> Row | undefined
                       when
                           Table :: snmpa:name_db() | snmpa:name(),
                           RowIndex :: snmp:row_index(),
                           Row :: tuple().

Row is a tuple with values for all columns, including the index columns.

Database (only table name specified) defaults to volatile.

table_set_elements(Table, RowIndex, Cols)

(since OTP 27.0)

-spec table_set_elements(Table, RowIndex, Cols) -> boolean()
                            when
                                Table :: snmpa:name_db() | snmpa:name(),
                                RowIndex :: snmp:row_index(),
                                Cols :: [{Col, Value}],
                                Col :: snmp:column(),
                                Value :: term().

Update the specified columnar objects of the row of this table.

Database (only table name specified) defaults to volatile.

This function has existed for long time, but not had a proper since tag, so to simplify we set the since tag to when it was documented.

snmpa_mib_data behaviour

Behaviour module for the SNMP agent mib-server data module.

This module defines the behaviour of the SNMP agent mib-server data module. A snmpa_mib_data compliant module must export the following functions:

new/1

close/1

sync/1

load_mib/4

unload_mib/4

lookup/2

next/3

register_subagent/3

unregister_subagent/2

which_mib/2

which_mibs/1

whereis_mib/2

dump/2

info/1

backup/2

code_change/4

The semantics of them and their exact signatures are explained below.

Note that the data extracted from the imported (loaded) mibs are stored partly by the mib-server and partly by the symbolic-store server. See the default mib-server data module, snmpa_mib_data_tttn for details.

Summary

Types

filename()

mib_view()

mib_view_elem()

mib_view_inclusion()

mib_view_mask()

Callbacks

backup(State, BackupDir)

Perform a backup of the mib-server data.

close(State)

Close the mib-storage.

code_change(Direction, Vsn, Extra, State)

Perform a code-change (upgrade or downgrade).

dump(State, Destination)

Dump the mib-server data to stdio (Destination = io) or the specified file.

info(State)

Retrieve misc info for the mib data.

load_mib(State, FileName, MeOverride, TeOverride)

Load the mib specified by the Filename argument into the mib-server. The MeOverride and TeOverride arguments specifies how the mib-server shall handle duplicate mib- and trap- entries.

lookup(State, Oid)

Find the mib-entry corresponding to the Oid. If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be

new(MibStorage)

Create a new mib-server data instance.

next(State, Oid, MibView)

Finds the lexicographically next oid.

register_subagent(State, Oid, Pid)

Register the subagent, process, handling part of the mib-tree.

sync(State)

Synchronize (write to disc, if possible) the mib-server data. This depends on the mib_storage option, and will only have an effect if the mib-storage option has an actual disc component (such as dets, or ets with a file).

unload_mib(State, Filename)

unload_mib(State, FileName, MeOverride, TeOverride)

Unload the mib specified by the Filename argument from the mib-server. The MeOverride and TeOverride arguments specifies how the mib-server shall handle duplicate mib- and trap- entries.

unregister_subagent(State, PidOrOid)

Unregister the subagent, handling part of the mib-tree, as specified by the oid() or pid/0 (PidOrOid).

whereis_mib(State, MibName)

Retrieve the mib file for the mib.

which_mib(State, Oid)

Retrieve the mib-file to which an given oid() belongs.

which_mibs(State)

Retrieve all loaded mib-files.

Types

filename()

(not exported) (since OTP R16B01)

-type filename() :: file:filename().

mib_view()

(since OTP R16B01)

-type mib_view() :: [mib_view_elem()].

mib_view_elem()

(since OTP R16B01)

-type mib_view_elem() ::
          {SubTree :: snmp:oid(), Mask :: [non_neg_integer()], Inclusion :: mib_view_inclusion()}.

mib_view_inclusion()

(since OTP R16B01)

-type mib_view_inclusion() :: 1 | 2.

mib_view_mask()

(since OTP R16B01)

-type mib_view_mask() :: [non_neg_integer()].

Callbacks

backup(State, BackupDir)

(since OTP R16B01)

-callback backup(State :: term(), BackupDir :: string()) -> ok | {error, Reason :: term()}.

Perform a backup of the mib-server data.

Note that its implementation dependent (and also dependent on mib-storage is used) if a backup is possible.

close(State)

(since OTP R16B01)

-callback close(State :: term()) -> ok.

Close the mib-storage.

code_change(Direction, Vsn, Extra, State)

(since OTP R16B01)

-callback code_change(Direction :: up | down, Vsn :: term(), Extra :: term(), State :: term()) ->
                         NewState :: term().

Perform a code-change (upgrade or downgrade).

See gen_server for more info regarding the Vsn and Extra arguments.

dump(State, Destination)

(since OTP R16B01)

-callback dump(State :: term(), Destination :: io | filename()) -> ok | {error, Reason :: term()}.

Dump the mib-server data to stdio (Destination = io) or the specified file.

info(State)

(since OTP R16B01)

-callback info(State :: term()) -> list().

Retrieve misc info for the mib data.

This is a utility function used to inspect, for instance, memory usage, in a simple way.

load_mib(State, FileName, MeOverride, TeOverride)

(since OTP R16B01)

-callback load_mib(State :: term(),
                   FileName :: filename(),
                   MeOverride :: boolean(),
                   TeOverride :: boolean()) ->
                      {ok, NewState :: term()} | {error, Reason :: already_loaded | term()}.

Load the mib specified by the Filename argument into the mib-server. The MeOverride and TeOverride arguments specifies how the mib-server shall handle duplicate mib- and trap- entries.

lookup(State, Oid)

(since OTP R16B01)

-callback lookup(State :: term(), Oid :: snmp:oid()) ->
                    {false, Reason :: term()} |
                    {variable, MibEntry :: snmpa:me()} |
                    {table_column, MibEntry :: snmpa:me(), TableEntryOid :: snmp:oid()} |
                    {subagent, SubAgentPid :: pid(), SAOid :: snmp:oid()}.

Find the mib-entry corresponding to the Oid. If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be

new(MibStorage)

(since OTP R16B01)

-callback new(MibStorage :: snmpa:mib_storage()) -> State :: term().

Create a new mib-server data instance.

next(State, Oid, MibView)

(since OTP R16B01)

-callback next(State :: term(), Oid :: snmp:oid(), MibView :: mib_view()) ->
                  endOfView | false |
                  {subagent, SubAgentPid :: pid(), SAOid :: snmp:oid()} |
                  {variable, MibEntry :: snmpa:me(), VarOid :: snmp:oid()} |
                  {table, TableOid :: snmp:oid(), TableRestOid :: snmp:oid(), MibEntry :: snmpa:me()}.

Finds the lexicographically next oid.

register_subagent(State, Oid, Pid)

(since OTP R16B01)

-callback register_subagent(State :: term(), Oid :: snmp:oid(), Pid :: pid()) ->
                               {ok, NewState :: term()} | {error, Reason :: term()}.

Register the subagent, process, handling part of the mib-tree.

sync(State)

(since OTP R16B01)

-callback sync(State :: term()) -> ok.

Synchronize (write to disc, if possible) the mib-server data. This depends on the mib_storage option, and will only have an effect if the mib-storage option has an actual disc component (such as dets, or ets with a file).

unload_mib(State, Filename)

(since OTP R16B01) (optional)

-callback unload_mib(State, Filename) -> {ok, NewState} | {error, Reason}
                        when
                            State :: term(),
                            Filename :: filename(),
                            NewState :: term(),
                            Reason :: not_loaded | term().

unload_mib(State, FileName, MeOverride, TeOverride)

(since OTP R16B01)

-callback unload_mib(State :: term(),
                     FileName :: filename(),
                     MeOverride :: boolean(),
                     TeOverride :: boolean()) ->
                        {ok, NewState :: term()} | {error, Reason :: not_loaded | term()}.

Unload the mib specified by the Filename argument from the mib-server. The MeOverride and TeOverride arguments specifies how the mib-server shall handle duplicate mib- and trap- entries.

unregister_subagent(State, PidOrOid)

(since OTP R16B01)

-callback unregister_subagent(State :: term(), PidOrOid :: pid() | snmp:oid()) ->
                                 {ok, NewState :: term()} |
                                 {ok, NewState :: term(), Pid :: pid()} |
                                 {error, Reason :: term()}.

Unregister the subagent, handling part of the mib-tree, as specified by the oid() or pid/0 (PidOrOid).

When unregister the subagent using an oid(), the pid/0 of the process handling the sub-tree is also returned.

whereis_mib(State, MibName)

(since OTP R16B01)

-callback whereis_mib(State :: term(), MibName :: atom()) ->
                         {ok, Filename :: filename()} | {error, Reason :: term()}.

Retrieve the mib file for the mib.

which_mib(State, Oid)

(since OTP R16B01)

-callback which_mib(State :: term(), Oid :: snmp:oid()) -> {ok, Mib :: string()} | {error, Reason :: term()}.

Retrieve the mib-file to which an given oid() belongs.

which_mibs(State)

(since OTP R16B01)

-callback which_mibs(State :: term()) -> [{MibName :: atom(), Filename :: filename()}].

Retrieve all loaded mib-files.

snmpa_mib_storage behaviour

Behaviour module for the SNMP agent mib storage.

This module defines the behaviour of the SNMP agent mib storage.

The mib storage is used by the agent to store internal mib- related information. The mib storage module is used by several entities, not just the mib-server.

A snmpa_mib_storage compliant module must export the following functions:

open/5

close/1

read/2

write/2

delete/1

delete/2

match_object/2

match_delete/2

tab2list/1

info/1

info/2

sync/1

backup/2

The semantics of them and their exact signatures are explained below.

Summary

Types

mib_storage_fields()

mib_storage_table_id()

mib_storage_table_type()

Callbacks

backup(TabId, Dir)

Perform a backup of the mib-storage table.

close(TabId)

Close the mib-storage table.

delete(TabId)

Delete an entire mib-storage table.

delete(TabId, Key)

Delete a record from the mib-storage table.

info(TabId)

Retrieve implementation dependent mib-storage table information.

info(TabId, Item)

match_delete(TabId, Pattern)

Search the mib-storage table for record that match the specified pattern and then delete them. The records deleted are also returned.

match_object(TabId, Pattern)

Search the mib-storage table for record that match the specified pattern.

open(Name, RecName, Fields, Type, Options)

Create or open a mib storage table.

read(TabId, Key)

Read a record from the mib-storage table.

sync(TabId)

Synchronize the mib-storage table.

tab2list(TabId)

Return all records in the mib-storage table in the form of a list.

write(TabId, Record)

Write a record to the mib-storage table.

Types

mib_storage_fields()

(since OTP R16B01)

-type mib_storage_fields() :: [atom()].

mib_storage_table_id()

(since OTP R16B01)

-type mib_storage_table_id() :: term().

mib_storage_table_type()

(since OTP R16B01)

-type mib_storage_table_type() :: set | bag.

Callbacks

backup(TabId, Dir)

(since OTP R16B01)

-callback backup(TabId :: mib_storage_table_id(), Dir :: file:filename()) -> ok | {error, Reason :: term()}.

Perform a backup of the mib-storage table.

What this means, if anything, is implementation dependent.

close(TabId)

(since OTP R16B01)

-callback close(TabId :: mib_storage_table_id()) -> term().

Close the mib-storage table.

delete(TabId)

(since OTP R16B01)

-callback delete(TabId :: mib_storage_table_id()) -> snmp:void().

Delete an entire mib-storage table.

delete(TabId, Key)

(since OTP R16B01)

-callback delete(TabId :: mib_storage_table_id(), Key :: term()) -> ok | {error, Reason :: term()}.

Delete a record from the mib-storage table.

info(TabId)

(since OTP R16B01)

-callback info(TabId :: mib_storage_table_id()) -> Info :: term().

Retrieve implementation dependent mib-storage table information.

info(TabId, Item)

(since OTP R16B01)

-callback info(TabId :: mib_storage_table_id(), Item :: atom()) -> Info :: term().

match_delete(TabId, Pattern)

(since OTP R16B01)

-callback match_delete(TabId :: mib_storage_table_id(), Pattern :: ets:match_pattern()) ->
                          Recs :: [tuple()] | {error, Reason :: term()}.

Search the mib-storage table for record that match the specified pattern and then delete them. The records deleted are also returned.

match_object(TabId, Pattern)

(since OTP R16B01)

-callback match_object(TabId :: mib_storage_table_id(), Pattern :: ets:match_pattern()) ->
                          Recs :: [tuple()] | {error, Reason :: term()}.

Search the mib-storage table for record that match the specified pattern.

open(Name, RecName, Fields, Type, Options)

(since OTP R16B01)

-callback open(Name :: atom(),
               RecName :: atom(),
               Fields :: mib_storage_fields(),
               Type :: mib_storage_table_type(),
               Options :: list()) ->
                  {ok, TabId :: mib_storage_table_id()} | {error, Reason :: term()}.

Create or open a mib storage table.

Note that the RecordName and Fields arguments my not be used in all implementations (they are actually only needed for mnesia-based implementations).

Note also that the Options argument comes from the options config option of the mib-storage config option, and is passed on as is.

read(TabId, Key)

(since OTP R16B01)

-callback read(TabId :: mib_storage_table_id(), Key :: term()) -> false | {value, Record :: tuple()}.

Read a record from the mib-storage table.

sync(TabId)

(since OTP R16B01)

-callback sync(TabId :: mib_storage_table_id()) -> snmp:void().

Synchronize the mib-storage table.

What this means, if anything, is implementation dependent.

tab2list(TabId)

(since OTP R16B01)

-callback tab2list(TabId :: mib_storage_table_id()) -> [tuple()].

Return all records in the mib-storage table in the form of a list.

write(TabId, Record)

(since OTP R16B01)

-callback write(TabId :: mib_storage_table_id(), Record :: tuple()) -> ok | {error, Reason :: term()}.

Write a record to the mib-storage table.

snmpa_mpd

Message Processing and Dispatch module for the SNMP agent

The module snmpa_mpd implements the version independent Message Processing and Dispatch functionality in SNMP for the agent. It is supposed to be used from a Network Interface process (Definition of Agent Net if).

DATA TYPES

For more information, see the data types in snmpa_conf.

Summary

Types

acm_data()

This is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent (by the net-if process).

acm_data_cmy()

This is the message specific data used in the SNMPv1 and SNMPv2c message.

acm_data_v3()

This is the message specific data used in the SNMPv3 message.

logger()

A fun that handles audit trail logging.

mpd_state()

msg_data()

This is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent (by the net-if process).

msg_data_cmy()

This is the message specific data used in the SNMP message. In SNMPv1 and SNMPv2c, this message data is the community string.

msg_data_ctx()

This is the message specific data used in the SNMP message. In SNMPv3, it is the context information.

Functions

discarded_pdu(Variable)

Increments the variable associated with a discarded pdu. This function can be used when the net_if process receives a discarded_pdu message from the agent.

generate_msg(Vsn, NoteStore, Pdu, MsgData, To)

Equivalent to generate_msg/6.

generate_msg(Vsn, NoteStore, Pdu, MsgData, LocalEngineID, To)

Generates a possibly encrypted request packet to be sent to the network.

generate_response_msg(Vsn, RePdu, Type, ACMData, Log)

Equivalent to generate_response_msg/6.

generate_response_msg(Vsn, RePdu, Type, ACMData, LocalEngineID, Log)

Generates a possibly encrypted response packet to be sent to the network. Type is the #pdu.type of the original request.

init(Vsns)

This function can be called from the net_if process at start-up. The options list defines which versions to use.

process_packet(Packet, From, State, NoteStore, Log)

Equivalent to process_packet/6.

process_packet/6

Processes an incoming packet. Performs authentication and decryption as necessary. The return values should be passed to the agent.

process_taddrs(InDests)

Transforms addresses from internal MIB format to one more useful to Agent Net if.

Types

acm_data()

-type acm_data() :: acm_data_cmy() | acm_data_v3().

This is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent (by the net-if process).

acm_data_cmy()

-opaque acm_data_cmy()

This is the message specific data used in the SNMPv1 and SNMPv2c message.

acm_data_v3()

-opaque acm_data_v3()

This is the message specific data used in the SNMPv3 message.

logger()

-type logger() ::
          fun((Type :: snmp_pdus:pdu_type(),
               Data :: binary() | {V3Hdr :: snmp_pdus:v3_hdr(), ScopedPDUBytes :: binary()}) ->
                  snmp:void()).

A fun that handles audit trail logging.

mpd_state()

-opaque mpd_state()

msg_data()

-type msg_data() :: msg_data_cmy() | msg_data_ctx().

This is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent (by the net-if process).

msg_data_cmy()

-opaque msg_data_cmy()

This is the message specific data used in the SNMP message. In SNMPv1 and SNMPv2c, this message data is the community string.

msg_data_ctx()

-opaque msg_data_ctx()

This is the message specific data used in the SNMP message. In SNMPv3, it is the context information.

Functions

discarded_pdu(Variable)

-spec discarded_pdu(Variable) -> snmp:void() when Variable :: snmpa:name() | false.

Increments the variable associated with a discarded pdu. This function can be used when the net_if process receives a discarded_pdu message from the agent.

generate_msg(Vsn, NoteStore, Pdu, MsgData, To)

(since OTP R14B)

-spec generate_msg(Vsn, NoteStore, Pdu, MsgData, To) -> {ok, PacketsAndAddresses} | {discarded, Reason}
                      when
                          Vsn :: snmp_pdus:version(),
                          NoteStore :: pid(),
                          Pdu :: snmp_pdus:pdu(),
                          MsgData :: msg_data(),
                          To :: [{Domain, Address}],
                          PacketsAndAddresses :: [{Domain, Address, Packet}],
                          Domain :: snmpa_conf:transportDomain(),
                          Address :: snmpa_conf:transportAddress(),
                          Packet :: binary(),
                          Reason :: term().

Equivalent to generate_msg/6.

generate_msg(Vsn, NoteStore, Pdu, MsgData, LocalEngineID, To)

(since OTP R14B)

-spec generate_msg(Vsn, NoteStore, Pdu, MsgData, LocalEngineID, To) ->
                      {ok, PacketsAndAddresses} | {discarded, Reason}
                      when
                          Vsn :: snmp_pdus:version(),
                          NoteStore :: pid(),
                          Pdu :: snmp_pdus:pdu(),
                          MsgData :: msg_data(),
                          LocalEngineID :: snmp_framework_mib:engine_id(),
                          To :: [DestAddr],
                          DestAddr :: {Domain, Address} | {{Domain, Address}, SecData},
                          SecData :: term(),
                          PacketsAndAddresses :: [{Domain, Address, Packet}],
                          Domain :: snmpa_conf:transportDomain(),
                          Address :: snmpa_conf:transportAddress(),
                          Packet :: binary(),
                          Reason :: term().

Generates a possibly encrypted request packet to be sent to the network.

MsgData is the message specific data used in the SNMP message. This value is received in a send_pdu or send_pdu_req message from the agent. In SNMPv1 and SNMPv2c, this message data is the community string. In SNMPv3, it is the context information.

To is a list of destination addresses and their corresponding security parameters. This value is received in the same message from the agent and then transformed through process_taddrs before passed to this function.

Note

Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

generate_response_msg(Vsn, RePdu, Type, ACMData, Log)

(since OTP R14B)

-spec generate_response_msg(Vsn, RePdu, Type, ACMData, Log) -> {ok, Packet} | {discarded, Reason}
                               when
                                   Vsn :: snmp_pdus:version(),
                                   RePdu :: snmp_pdus:pdu(),
                                   Type :: snmp_pdus:pdu_type(),
                                   ACMData :: acm_data(),
                                   Log :: logger(),
                                   Packet :: binary(),
                                   Reason :: term().

Equivalent to generate_response_msg/6.

generate_response_msg(Vsn, RePdu, Type, ACMData, LocalEngineID, Log)

(since OTP R14B)

-spec generate_response_msg(Vsn, RePdu, Type, ACMData, LocalEngineID, Log) ->
                               {ok, Packet} | {discarded, Reason}
                               when
                                   Vsn :: snmp_pdus:version(),
                                   RePdu :: snmp_pdus:pdu(),
                                   Type :: snmp_pdus:pdu_type(),
                                   ACMData :: acm_data(),
                                   LocalEngineID :: snmp_framework_mib:engine_id(),
                                   Log :: logger(),
                                   Packet :: binary(),
                                   Reason :: term().

Generates a possibly encrypted response packet to be sent to the network. Type is the #pdu.type of the original request.

Note

Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

init(Vsns)

-spec init(Vsns) -> MPDState when Vsns :: [snmp:version()], MPDState :: mpd_state().

This function can be called from the net_if process at start-up. The options list defines which versions to use.

It also initializes some SNMP counters.

process_packet(Packet, From, State, NoteStore, Log)

(since OTP 17.3)

-spec process_packet(Packet, From, State, NoteStore, Log) ->
                        {ok, Vsn, Pdu, PduMS, ACMData} | {discarded, Reason} | {discovery, DiscoPacket}
                        when
                            Packet :: binary(),
                            From :: {TDomain, TAddress},
                            TDomain :: snmpa_conf:transportDomain(),
                            TAddress :: {IpAddr, IpPort},
                            IpAddr :: inet:ip_address(),
                            IpPort :: inet:port_number(),
                            State :: mpd_state(),
                            NoteStore :: pid(),
                            Log :: logger(),
                            Vsn :: snmp_pdus:version(),
                            Pdu :: snmp_pdus:pdu(),
                            PduMS :: pos_integer(),
                            ACMData :: acm_data(),
                            Reason :: term(),
                            DiscoPacket :: binary().

Equivalent to process_packet/6.

process_packet/6

(since OTP R14B)

-spec process_packet(Packet, TDomain, TAddress, State, NoteStore, Log) ->
                        {ok, Vsn, Pdu, PduMS, ACMData} | {discarded, Reason} | {discovery, DiscoPacket}
                        when
                            Packet :: binary(),
                            TDomain :: snmpa_conf:transportDomain(),
                            TAddress :: {IpAddr, IpPort},
                            IpAddr :: inet:ip_address(),
                            IpPort :: inet:port_number(),
                            State :: mpd_state(),
                            NoteStore :: pid(),
                            Log :: logger(),
                            Vsn :: snmp_pdus:version(),
                            Pdu :: snmp_pdus:pdu(),
                            PduMS :: pos_integer(),
                            ACMData :: acm_data(),
                            Reason :: term(),
                            DiscoPacket :: binary();
                    (Packet, From, LocalEngineID, State, NoteStore, Log) ->
                        {ok, Vsn, Pdu, PduMS, ACMData} | {discarded, Reason} | {discovery, DiscoPacket}
                        when
                            Packet :: binary(),
                            From :: {TDomain, TAddress},
                            TDomain :: snmpa_conf:transportDomain(),
                            TAddress :: {IpAddr, IpPort},
                            IpAddr :: inet:ip_address(),
                            IpPort :: inet:port_number(),
                            LocalEngineID :: snmp_framework_mib:engine_id(),
                            State :: mpd_state(),
                            NoteStore :: pid(),
                            Log :: logger(),
                            Vsn :: snmp_pdus:version(),
                            Pdu :: snmp_pdus:pdu(),
                            PduMS :: pos_integer(),
                            ACMData :: acm_data(),
                            Reason :: term(),
                            DiscoPacket :: binary().

Processes an incoming packet. Performs authentication and decryption as necessary. The return values should be passed to the agent.

Note

Note that the use of the LocalEngineID argument is only intended for special cases, if the agent is to "emulate" multiple EngineIDs! By default, the agent uses the value of SnmpEngineID (see SNMP-FRAMEWORK-MIB).

process_taddrs(InDests)

(since OTP 17.3)

-spec process_taddrs(InDests) -> OutDests
                        when
                            InDests :: [InDest],
                            InDest :: {{InDomain, InAddress}, SecData} | {InDomain, InAddress},
                            InDomain :: term(),
                            InAddress :: term(),
                            SecData :: term(),
                            OutDests :: [OutDest],
                            OutDest :: {{OutDomain, OutAddress}, SecData} | {OutDomain, OutAddress},
                            OutDomain :: snmpa_conf:transportDomain(),
                            OutAddress :: snmpa_conf:transportAddress().

Transforms addresses from internal MIB format to one more useful to Agent Net if.

See also generate_msg.

snmpa_network_interface behaviour

Behaviour module for the SNMP agent network interface.

This module defines the behaviour of the agent network interface. A snmpa_network_interface compliant module must export the following functions:

start_link/4

info/1

get_log_type/1

set_log_type/2

verbosity/2

The semantics of them and their exact signatures are explained below.

But this is not enough. There is also a set of mandatory messages which the network interface entity must be able to receive and be able to send. This is described in chapter snmp_agent_netif.

Summary

Callbacks

get_log_type(Pid)

The Audit Trail Log is managed by the network interface process. So, it is this process that has to retrieve the actual log-type.

get_request_limit(Pid)

The request limit is the number of simultaneous requests the agent will accept. This function retrieve the current value.

info(Pid)

The info returned is basically up to the implementer to decide. This implementation provided by the application provides info about memory allocation and various socket information.

set_log_type(Pid, NewType)

The Audit Trail Log is managed by the network interface process. So, it is this process that has to do the actual changing of the type.

set_request_limit(Pid, NewLimit)

The request limit is the number of simultaneous requests the agent will accept. This function sets a new value.

start_link(Prio, NoteStore, MasterAgent, Opts)

Start-link the network interface process.

verbosity(Pid, Verbosity)

Change the verbosity of a running network interface process.

Callbacks

get_log_type(Pid)

-callback get_log_type(Pid) -> {ok, LogType} | {error, Reason}
                          when Pid :: pid(), LogType :: snmp:atl_type(), Reason :: term().

The Audit Trail Log is managed by the network interface process. So, it is this process that has to retrieve the actual log-type.

get_request_limit(Pid)

(since OTP 27.0)

-callback get_request_limit(Pid) -> {ok, Limit} when Pid :: pid(), Limit :: non_neg_integer() | infinity.

The request limit is the number of simultaneous requests the agent will accept. This function retrieve the current value.

info(Pid)

-callback info(Pid) -> Info when Pid :: pid(), Info :: [{Key, Value}], Key :: term(), Value :: term().

The info returned is basically up to the implementer to decide. This implementation provided by the application provides info about memory allocation and various socket information.

The info returned by this function is returned together with other info collected by the agent when the info/1 function is called (tagged with with the key net_if).

set_log_type(Pid, NewType)

-callback set_log_type(Pid, NewType) -> {ok, OldType} | {error, Reason}
                          when
                              Pid :: pid(),
                              NewType :: snmp:atl_type(),
                              OldType :: snmp:atl_type(),
                              Reason :: term().

The Audit Trail Log is managed by the network interface process. So, it is this process that has to do the actual changing of the type.

See snmpa:set_log_type/2 for more info.

set_request_limit(Pid, NewLimit)

(since OTP 27.0)

-callback set_request_limit(Pid, NewLimit) -> {ok, OldLimit}
                               when
                                   Pid :: pid(),
                                   NewLimit :: non_neg_integer() | infinity,
                                   OldLimit :: non_neg_integer() | infinity.

The request limit is the number of simultaneous requests the agent will accept. This function sets a new value.

start_link(Prio, NoteStore, MasterAgent, Opts)

-callback start_link(Prio, NoteStore, MasterAgent, Opts) -> {ok, Pid} | {error, Reason}
                        when
                            Prio :: low | normal | high,
                            NoteStore :: pid(),
                            MasterAgent :: pid(),
                            Opts :: [Option],
                            Option :: {verbosity, snmp:verbosity()} | {versions, [snmp:version()]} | term(),
                            Pid :: pid(),
                            Reason :: term().

Start-link the network interface process.

NoteStore is the pid of the note-store process and MasterAgent is the pid of the master-agent process.

Opts is an (basically) implementation dependent list of options to the network interface process. There are however a number of options which must be handled: versions and verbosity.

verbosity(Pid, Verbosity)

-callback verbosity(Pid, Verbosity) -> snmp:void() when Pid :: pid(), Verbosity :: snmp:verbosity().

Change the verbosity of a running network interface process.

snmpa_network_interface_filter behaviour

Behaviour module for the SNMP agent network-interface filter.

This module defines the behaviour of the agent network interface filter. A snmpa_network_interface_filter compliant module must export the following functions:

accept_recv/2

accept_send/2

accept_recv_pdu/3

accept_send_pdu/2

The semantics of them and their exact signatures are explained below.

The purpose of the network interface filter is to allow for filtering of messages (accept or reject) receive and send. This is done on two levels:

The first level is at the transport entry / exit point, i.e. immediately after the receipt of the message before any message processing is done (accept_recv) and immediately before sending the message after all message processing is done (accept_send).

The second level is at the MPD entry / exit point, i.e. immediately after the basic message processing (accept_recv_pdu) / immediately before the basic message processing (accept_send_pdu).

Note that the network interface filter is something which is used by the network interface implementation provided by the application (snmpa_net_if). The default filter accepts all messages.

A network interface filter can e.g. be used during testing or for load regulation. If the intended use is load regulation, see also req_limit and the function register_notification_filter.

Legacy network interface filter modules used arguments on the form (IpAddr, PortNumber,...) instead of (Domain, Addr, ...), and if the SNMP agent is run without changing the configuration to use transport domains the network interface filter will still get the old arguments and work as before.

See also the data types in snmpa_conf.

Summary

Types

pdu_type()

transportAddressWithPort()

transportDomain()

Callbacks

accept_recv(Domain, Addr)

Called at the reception of a message (before any processing has been done).

accept_recv_pdu(Domain, Addr, PduType)

Called after the basic message processing (MPD) has been done, but before the pdu is handed over to the master-agent for primary processing.

accept_send(Domain, Addr)

Called before the sending of a message (after all processing has been done).

accept_send_pdu(Targets, PduType)

Called before the basic message processing (MPD) is done, when a pdu has been received from the master-agent.

Types

pdu_type()

(not exported)

-type pdu_type() :: snmpa:pdu_type().

transportAddressWithPort()

(not exported)

-type transportAddressWithPort() :: snmpa_conf:transportAddressWithPort().

transportDomain()

(not exported)

-type transportDomain() :: snmpa_conf:transportDomain().

Callbacks

accept_recv(Domain, Addr)

-callback accept_recv(Domain, Addr) -> boolean()
                         when Domain :: transportDomain(), Addr :: transportAddressWithPort().

Called at the reception of a message (before any processing has been done).

For the message to be discarded, the function must return false.

accept_recv_pdu(Domain, Addr, PduType)

-callback accept_recv_pdu(Domain, Addr, PduType) -> boolean()
                             when
                                 Domain :: transportDomain(),
                                 Addr :: transportAddressWithPort(),
                                 PduType :: pdu_type().

Called after the basic message processing (MPD) has been done, but before the pdu is handed over to the master-agent for primary processing.

For the pdu to be discarded, the function must return false.

accept_send(Domain, Addr)

-callback accept_send(Domain, Addr) -> boolean()
                         when Domain :: transportDomain(), Addr :: transportAddressWithPort().

Called before the sending of a message (after all processing has been done).

For the message to be discarded, the function must return false.

accept_send_pdu(Targets, PduType)

-callback accept_send_pdu(Targets, PduType) -> Reply
                             when
                                 Targets :: [Target],
                                 Target :: {Domain, Addr},
                                 Domain :: transportDomain(),
                                 Addr :: transportAddressWithPort(),
                                 PduType :: pdu_type(),
                                 Reply :: boolean() | NewTargets,
                                 NewTargets :: Targets.

Called before the basic message processing (MPD) is done, when a pdu has been received from the master-agent.

For the message to be discarded all together, the function must return false.

Note that it is possible for this function to filter out targets (but not to add its own) by returning an updated Targets list (NewTargets).

snmpa_notification_delivery_info_receiver behaviour

Behaviour module for the SNMP agent notification delivery information receiver.

This module defines the behaviour of the notification delivery information receiver.

When the user sends a notification (see snmpa:send_notification2/3), the user can (optionally) choose to receive delivery information (was the message received and acknowledged by the target(s)). This behaviour describes a way for the user to get such (delivery) information.

A snmpa_notification_delivery_info_receiver compliant module must export the following functions:

delivery_targets/3

delivery_info/4

The semantics of them and their exact signatures are explained below.

Legacy notification delivery information receiver modules used a target argument of the form {IpAddr, PortNumber} instead of {Domain, Addr}, and if the SNMP Agent is run without changing the configuration to use transport domains the notification delivery information receiver will still get the old arguments and work as before.

Summary

Types

notification_delivery_info()

How shall (notification) delivery info be reported.

transportAddressWithPort()

transportDomain()

Callbacks

delivery_info(Tag, Targets, DeliveryResult, Extra)

Inform about delivery result.

delivery_targets(Tag, Targets, Extra)

Inform about target addresses.

Types

notification_delivery_info()

-type notification_delivery_info() ::
          #snmpa_notification_delivery_info{tag :: term(), mod :: term(), extra :: term()}.

How shall (notification) delivery info be reported.

This record defines the info related to inform delivery info. That is, when sending an inform, info about the delivery (such if it was acknowledged) will be delivered using the info in this record.

The delivery will be performed according to:

	Mod:delivery_targets(Tag, Addresses, Extra)
	Mod:delivery_info(Tag, Address, DeliveryResult, Extra)

The Extra is any term, provided by the user.

The fields of this record has the following meaning:

tag = term() - Value selected by the user to identify this sending

mod = module() - A module implementing the snmpa_notification_delivery_info_receiver behaviour.

extra = term() - This is any extra info the user wants to have supplied when the functions in the callback module is called. Provided when calling the send function.

transportAddressWithPort()

(not exported)

-type transportAddressWithPort() :: snmpa_conf:transportAddressWithPort().

transportDomain()

(not exported)

-type transportDomain() :: snmpa_conf:transportDomain().

Callbacks

delivery_info(Tag, Targets, DeliveryResult, Extra)

-callback delivery_info(Tag, Targets, DeliveryResult, Extra) -> snmp:void()
                           when
                               Tag :: term(),
                               Targets :: [Target],
                               Target :: {transportDomain(), transportAddressWithPort()},
                               DeliveryResult :: no_response | got_response,
                               Extra :: term().

Inform about delivery result.

This function is called for each target in the Targets argument of the delivery_targets/3 function, see above.

The purpose is to inform the receiver of the result of the delivery (was the notification acknowledged or not) for each target.

delivery_targets(Tag, Targets, Extra)

-callback delivery_targets(Tag, Targets, Extra) -> snmp:void()
                              when
                                  Tag :: term(),
                                  Targets :: [Target],
                                  Target :: {transportDomain(), transportAddressWithPort()},
                                  Extra :: term().

Inform about target addresses.

This is the first function called when a notification delivery is in progress. It informs the receiver which targets will get the notification. The result of the delivery will be provided via successive calls to delivery_info/4 function, see below.

snmpa_notification_filter behaviour

Behaviour module for the SNMP agent notification filters.

This module defines the behaviour of the agent notification filters. A snmpa_notification_filter compliant module must export the following functions:

handle_notification/2

The semantics of them and their exact signatures are explained below.

The purpose of notification filters is to allow for modification and/or suppression of a notification.

A misbehaving filter will be removed.

Summary

Types

notification()

trap()

Callbacks

handle_notification(Notif, Data)

Handle a notification to be sent. The filter can either accept the notification as is, return send, modify the notification, return {send, NewNotif} or suppress the notification, return dont_send.

Types

notification()

(not exported)

-type notification() :: term().

trap()

(not exported)

-type trap() :: term().

Callbacks

handle_notification(Notif, Data)

-callback handle_notification(Notif, Data) -> Reply
                                 when
                                     Notif :: notification() | trap(),
                                     Data :: term(),
                                     Reply :: send | {send, NewNotif} | dont_send,
                                     NewNotif :: notification() | trap().

Handle a notification to be sent. The filter can either accept the notification as is, return send, modify the notification, return {send, NewNotif} or suppress the notification, return dont_send.

Data is supplied at filter registration time, see snmpa:register_notification_filter/5.

snmpa_supervisor

A supervisor for the SNMP agent Processes

This is the top supervisor for the agent part of the SNMP application. There is always one supervisor at each node with an SNMP agent (master agent or sub-agent).

Summary

Functions

start_master_sup(Opts)

Starts a supervisor for the SNMP agent system. The supervisor starts all involved SNMP processes, including the master agent. Sub-agents should be started by calling start_subagent/3.

start_sub_agent(ParentAgent, Subtree, Mibs)

Starts a sub-agent on the node where the function is called. The snmpa_supervisor must be running.

start_sub_sup(Opts)

Starts a supervisor for the SNMP agent system without a master agent. The supervisor starts all involved SNMP agent processes, but no agent processes. Sub-agents should be started by calling start_sub_agent/3.

stop_sub_agent(SubAgentPid)

Stops the sub-agent on the node where the function is called. The snmpa_supervisor must be running.

Functions

start_master_sup(Opts)

-spec start_master_sup(Opts) -> {ok, Pid} | {error, Reason}
                          when
                              Opts :: [Opt],
                              Opt :: {db_dir, string()} | {config, ConfOpts} | {atom(), term()},
                              ConfOpts :: [ConfOpt],
                              ConfOpt :: {dir, string()} | {atom(), term()},
                              Pid :: pid(),
                              Reason :: {already_started, Pid} | term().

Starts a supervisor for the SNMP agent system. The supervisor starts all involved SNMP processes, including the master agent. Sub-agents should be started by calling start_subagent/3.

db_dir is mandatory.

dir in config is mandatory.

See snmp config for a description of the options.

start_sub_agent(ParentAgent, Subtree, Mibs)

-spec start_sub_agent(ParentAgent, Subtree, Mibs) -> {ok, Pid} | {error, Reason}
                         when
                             ParentAgent :: pid(),
                             Subtree :: snmp:oid(),
                             Mibs :: [MibName],
                             MibName :: string(),
                             Pid :: pid(),
                             Reason :: term().

Starts a sub-agent on the node where the function is called. The snmpa_supervisor must be running.

If the supervisor is not running, the function fails with the reason badarg.

start_sub_sup(Opts)

-spec start_sub_sup(Opts) -> {ok, Pid} | {error, Reason}
                       when
                           Opts :: [Opt],
                           Opt :: {db_dir, snmp:dir()} | {atom(), term()},
                           Pid :: pid(),
                           Reason :: {already_started, Pid} | term().

Starts a supervisor for the SNMP agent system without a master agent. The supervisor starts all involved SNMP agent processes, but no agent processes. Sub-agents should be started by calling start_sub_agent/3.

db_dir is mandatory.

See configuration parameters for a description of the options.

stop_sub_agent(SubAgentPid)

-spec stop_sub_agent(SubAgentPid) -> ok | no_such_child when SubAgentPid :: pid().

Stops the sub-agent on the node where the function is called. The snmpa_supervisor must be running.

If the supervisor is not running, the function fails with the reason badarg.

snmpc

Interface Functions to the SNMP toolkit MIB compiler

The module snmpc contains interface functions to the SNMP toolkit MIB compiler.

See Also

erlc(1)

snmpc(command)

Summary

Functions

compile/1

Equivalent to compile/2.

compile(FileName, Options)

Compiles the specified MIB file <FileName>.mib. The compiled file BinFileName is called <FileName>.bin.

is_consistent(FileNames)

Checks for multiple usage of object identifiers and traps between MIBs.

mib_to_hrl(MibName)

Generates a .hrl file with definitions of Erlang constants for the objects in the MIB. The .hrl file is called <MibName>.hrl. The MIB must be compiled, and present in the current directory.

Functions

compile/1

-spec compile(AtomFileNames | FileName) -> {ok, BinFileName} | {error, Reason}
                 when
                     AtomFileNames :: [atom()],
                     FileName :: string(),
                     BinFileName :: string(),
                     Reason :: term().

Equivalent to compile/2.

compile(FileName, Options)

-spec compile(FileName, Options) -> {ok, BinFileName} | {error, Reason}
                 when
                     FileName :: string(),
                     Options :: [Option],
                     Option ::
                         agent_capabilities |
                         {db, volatile | persistent | mnesia} |
                         {deprecated, boolean()} |
                         description |
                         {group_check, boolean()} |
                         {i, [snmp:dir()]} |
                         {il, [snmp:dir()]} |
                         imports |
                         {module, module()} |
                         module_identity | module_compliance | no_defs |
                         {outdir, snmp:dir()} |
                         reference | relaxed_row_name_assign_check |
                         {verbosity, snmp:verbosity()} |
                         {warnings, boolean()} |
                         {warnings_as_errors, boolean()},
                     BinFileName :: string(),
                     Reason :: term().

Compiles the specified MIB file <FileName>.mib. The compiled file BinFileName is called <FileName>.bin.

The option agent_capabilities, if present, specifies that the AGENT-CAPABILITIES statement of the MIB shall be included (with a mib-entry record) in the compiled mib. The mib-entry record of the agent-capabilitie will contain reference and modules part(s) this info in the assocList field).

The option db specifies which database should be used for the default instrumentation.

Default is volatile.

The option deprecated specifies if a deprecated definition should be kept or not. If the option is false the MIB compiler will ignore all deprecated definitions.

Default is true.

The option description specifies if the text of the DESCRIPTION field will be included or not.

By default it is not included, but if this option is present it will be.

The option group_check specifies whether the mib compiler should check the OBJECT-GROUP macro and the NOTIFICATION-GROUP macro for correctness or not.

Default is true.

The option i specifies the path to search for imported (compiled) MIB files. The directories should be strings with a trailing directory delimiter.

Default is ["./"].

The option il (include_lib) also specifies a list of directories to search for imported MIBs. It assumes that the first element in the directory name corresponds to an OTP application. The compiler will find the current installed version. For example, the value ["snmp/mibs/"] will be replaced by ["snmp-3.1.1/mibs/"] (or what the current version may be in the system). The current directory and the <snmp-home>/priv/mibs/ are always listed last in the include path.

The option imports, if present, specifies that the IMPORT statement of the MIB shall be included in the compiled mib.

The option module, if present, specifies the name of a module which implements all instrumentation functions for the MIB.

The name of all instrumentation functions must be the same as the corresponding managed object it implements.

The option module_identity, if present, specifies that the info part of the MODULE-IDENTITY statement of the MIB shall be included in the compiled mib.

The option module_compliance, if present, specifies that the MODULE-COMPLIANCE statement of the MIB shall be included (with a mib-entry record) in the compiled mib. The mib-entry record of the module-compliance will contain reference and module part(s) this info in the assocList field).

The option no_defs, if present, specifies that if a managed object does not have an instrumentation function, the default instrumentation function should NOT be used, instead this is reported as an error, and the compilation aborts.

The option reference specifies if the text of the REFERENCE field, when found in a table definition, will be included or not.

By default it is not included, but if this option is present it will be. The reference text will be placed in the allocList field of the mib-entry record (#me{}) for the table.

The option relaxed_row_name_assign_check, if present, specifies that the row name assign check shall not be done strictly according to the SMI (which allows only the value 1). With this option, all values greater than zero is allowed (>= 1). This means that the error will be converted to a warning.

By default it is not included, but if this option is present it will be.

The option verbosity specifies the verbosity of the SNMP mib compiler. I.e. if warning, info, log, debug and trace messages shall be shown.

Default is silence.

Note that if the option warnings is true and the option verbosity is silence, warning messages will still be shown.

The option warnings specifies whether warning messages should be shown.

Default is true.

The option warnings_as_errors, if present, specifies whether warnings should be treated as errors.

The MIB compiler understands both SMIv1 and SMIv2 MIBs. It uses the MODULE-IDENTITY statement to determine if the MIB is version 1 or 2.

The MIB compiler can also be invoked from the OS command line by these two commands; erlc and snmpc.

erlc - erlc recognizes the extension .mib, and invokes the SNMP MIB compiler for files with that extension. The options db, group_check, deprecated, description, verbosity, imports and module_identity have to be specified to erlc using the syntax +term.

See erlc(1) for details.

snmpc - snmpc is an escript that provides a more traditional interface to the MIB compiler.

See snmpc(command) for details.

is_consistent(FileNames)

-spec is_consistent(FileNames) -> ok | {error, Reason}
                       when FileNames :: [MibName], MibName :: string(), Reason :: term().

Checks for multiple usage of object identifiers and traps between MIBs.

mib_to_hrl(MibName)

-spec mib_to_hrl(MibName) -> Result
                    when MibName :: string(), Result :: ok | {error, Reason}, Reason :: term().

Generates a .hrl file with definitions of Erlang constants for the objects in the MIB. The .hrl file is called <MibName>.hrl. The MIB must be compiled, and present in the current directory.

The mib_to_hrl generator can be invoked from the OS command line by using the command erlc. erlc recognizes the extension .bin, and invokes this function for files with that extension.

snmpm

Interface functions to the SNMP toolkit manager

The module snmpm contains interface functions to the SNMP manager.

Summary

Types

agent_config()

agent_config_item()

Value type depend on the item according to

pdu_type()

register_timeout()

The time to complete a (agent) registration.

request_id()

Is a unique term that identifies a request.

snmp_reply()

snmpm_user()

Module implementing the snmpm_user behaviour.

target_name()

Is a unique non-empty string.

user_id()

Is a unique term that identifies a user.

usm_config_item()

Value type depend on the item according to

value_type()

var_and_val()

Functions

agent_info(TargetName, Item)

Retrieve agent config.

async_get2(UserId, TargetName, Oids)

Equivalent to async_get2/4.

async_get2(UserId, TargetName, Oids, SendOpts)

Asynchronous get-request.

async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids)

Equivalent to async_get_bulk2/6.

async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts)

Asynchronous get-bulk-request (See RFC1905).

async_get_next2(UserId, TargetName, Oids)

Equivalent to async_get_next2/4.

async_get_next2(UserId, TargetName, Oids, SendOpts)

Asynchronous get-next-request.

async_set2(UserId, TargetName, VarsAndVals)

Equivalent to async_set2/4.

async_set2(UserId, TargetName, VarsAndVals, SendOpts)

Asynchronous set-request.

backup(BackupDir)

Backup persistent data handled by the manager.

cancel_async_request(UserId, ReqId)

Cancel a previous asynchronous request.

cancel_notify_started(Pid)

Cancel a previous request to be notified of SNMP manager start.

change_log_size(NewSize)

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 description of how to change the log size.

demonitor(Ref)

Turn off monitoring of the SNMP manager.

format_reason(Reason)

Equivalent to format_reason/2.

format_reason(Prefix, Reason)

This utility function is used to create a formatted (pretty printable) string of the error reason received from either

info()

Returns a list (a dictionary) containing information about the manager. Information includes statistics counters, miscellaneous info about each process (e.g. memory allocation), and so on.

load_mib(MibName)

Load a Mib into the manager. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

log_to_io(LogDir)

Equivalent to log_to_io/7.

log_to_io/2

Equivalent to log_to_io/7.

log_to_io/3

Equivalent to log_to_io/7.

log_to_io/4

Equivalent to log_to_io/7.

log_to_io/5

Equivalent to log_to_io/7.

log_to_io/6

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable format and prints it on stdio. LogName defaults to "snmpm_log". LogFile defaults to "snmpm.log".

log_to_txt(LogDir)

Equivalent to log_to_txt/8.

log_to_txt/2

Equivalent to log_to_txt/8.

log_to_txt/3

Equivalent to log_to_txt/8.

log_to_txt/4

Equivalent to log_to_txt/8.

log_to_txt/5

Equivalent to log_to_txt/8.

log_to_txt/6

Equivalent to log_to_txt/8.

log_to_txt/7

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

Converts an Audit Trail Log to a readable text file. OutFile defaults to "./snmpm_log.txt". LogName defaults to "snmpm_log". LogFile defaults to "snmpm.log".

monitor()

Monitor the SNMP manager. In case of a crash, the calling (monitoring) process will get a 'DOWN' message (see the erlang module for more info).

name_to_oid(AliasName)

Transform a alias-name to its oid.

notify_started/1

Request a notification (message) when the SNMP manager has started.

oid_to_name(OID)

Transform a oid to its aliasname.

oid_to_type(OID)

Retrieve the type (asn1 bertype) of an oid.

register_agent(UserId, TargetName, Config)

Explicitly instruct the manager to handle this agent, with UserId as the responsible user.

register_user(UserId, Module, Data)

Equivalent to register_user/4.

register_user(UserId, Module, Data, DefaultAgentConfig)

Register the manager entity (=user) responsible for specific agent(s).

register_user_monitor(UserId, Module, Data)

Equivalent to register_user_monitor/4.

register_user_monitor(UserId, Module, Data, DefaultAgentConfig)

Register the monitored manager entity (=user) responsible for specific agent(s).

register_usm_user(EngineID, UserName, Config)

Explicitly instruct the manager to handle this USM user. Note that there is an alternate way to do the same thing: Add the usm user to the manager config files (see usm.conf).

restart(What)

Restart the indicated process (What). Note that its not without risk to restart a process, and should therefore be used with care.

set_log_type(NewType)

Changes the run-time Audit Trail log type.

sync_get2(UserId, TargetName, Oids)

Equivalent to sync_get2/4.

sync_get2(UserId, TargetName, Oids, SendOpts)

Synchronous get-request.

sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids)

Equivalent to sync_get_bulk2/6.

sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts)

Synchronous get-bulk-request (See RFC1905).

sync_get_next2(UserId, TargetName, Oids)

Equivalent to sync_get_next2/4.

sync_get_next2(UserId, TargetName, Oids, SendOpts)

Synchronous get-next-request.

sync_set2(UserId, TargetName, VarsAndVals)

Equivalent to sync_set2/4.

sync_set2(UserId, TargetName, VarsAndVals, SendOpts)

Synchronous set-request.

unload_mib(MibName)

Unload a Mib from the manager. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

unregister_agent(UserId, TargetName)

Unregister the agent.

unregister_user(UserId)

Unregister the user.

unregister_usm_user(EngineID, UserName)

Unregister this USM user.

update_agent_info(UserId, TargetName, Info)

Update agent config.

update_agent_info(UserId, TargetName, Item, Value)

Update agent config.

update_usm_user_info(EngineID, UserName, Item, Value)

Update usm user config.

usm_user_info(EngineID, UserName, Item)

Retrieve usm user config.

verbosity(Target, Verbosity)

Sets verbosity for the designated process. For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

which_agents()

Equivalent to which_agents/1.

which_agents(UserId)

Get a list of all registered agents or all agents registered by a specific user.

which_mibs()

Get a list of all the mib's loaded into the manager.

which_users()

Get a list of the identities of all registered users.

which_usm_users()

Get a list of all registered usm users.

which_usm_users(EngineID)

Get a list of all registered usm users with engine-id EngineID.

Types

agent_config()

-type agent_config() ::
          {engine_id, snmp:engine_id()} |
          {address, inet:ip_address()} |
          {port, inet:port_number()} |
          {tdomain, snmp:tdomain()} |
          {community, snmp:community()} |
          {timeout, register_timeout()} |
          {max_message_size, snmp:mms()} |
          {version, snmp:version()} |
          {sec_model, snmp:sec_model()} |
          {sec_name, snmp:sec_name()} |
          {sec_level, snmp:sec_level()}.

agent_config_item()

-type agent_config_item() ::
          engine_id | address | port | tdomain | community | timeout | max_message_size | version |
          sec_model | sec_name | sec_level.

Value type depend on the item according to:

engine_id - Engine ID of the agent.

Value type: engine_id()

address - The IP address of the agent.

Value type: ip_address()

port - Port number of the agent.

Value type: port_number()

tdomain - Transport domain.

Value type: tdomain()

community - Community.

Value type: community()

timeout - Registration timeout.

Value type: register_timeout/0

max_message_size - Max Message Size of a message.

Value type: mms()

version - What SNMP version is used when communicating with this agent.

Value type: version()

sec_model - Security Model.

Value type: sec_model()

sec_name - Security Name.

Value type: sec_name()

sec_level - Security Level.

Value type: sec_level()

pdu_type()

-type pdu_type() :: snmp:pdu_type() | trappdu.

register_timeout()

-type register_timeout() :: pos_integer() | snmp:snmp_timer().

The time to complete a (agent) registration.

request_id()

-opaque request_id()

Is a unique term that identifies a request.

snmp_reply()

-type snmp_reply() :: {snmp:error_status(), snmp:error_index(), [snmp:varbind()]}.

snmpm_user()

-type snmpm_user() :: module().

Module implementing the snmpm_user behaviour.

target_name()

-type target_name() :: string().

Is a unique non-empty string.

user_id()

-type user_id() :: term().

Is a unique term that identifies a user.

usm_config_item()

-type usm_config_item() :: sec_name | auth | auth_key | priv | priv_key.

Value type depend on the item according to:

sec_name - Security Name.

Value type: snmp:sec_name()

auth - Authentication protocol.

Value type: snmp:usm_auth_protocol()

auth_key - Authentication key.

Value type: snmp:usm_auth_key()

priv - Privacy protocol.

Value type: snmp:usm_priv_protocol()

priv_key - Privacy key.

Value type: snmp:usm_priv_key()

value_type()

-type value_type() :: o | i | u | g | s | s | b | ip | op | c32 | c64 | tt.

o - 'OBJECT IDENTIFIER'

i - 'INTEGER'

u - 'Unsigned32

g - 'Unsigned32'

s - 'OCTET STRING'

b - 'BITS'

ip - 'IpAddress'

op - 'Opaque'

c32 - 'Counter32'

c64 - 'Counter64'

tt - 'TimeTicks'

var_and_val()

-type var_and_val() ::
          {OID :: snmp:oid(), ValueType :: value_type(), Value :: term()} |
          {OID :: snmp:oid(), Value :: term()}.

Functions

agent_info(TargetName, Item)

-spec agent_info(TargetName, Item) -> {ok, Value} | {error, Reason}
                    when
                        TargetName :: target_name(),
                        Item :: agent_config_item(),
                        Value :: term(),
                        Reason :: term().

Retrieve agent config.

async_get2(UserId, TargetName, Oids)

(since OTP R14B03)

-spec async_get2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
                    when
                        UserId :: user_id(),
                        TargetName :: target_name(),
                        Oids :: [snmp:oid()],
                        ReqId :: request_id(),
                        Reason :: term().

Equivalent to async_get2/4.

async_get2(UserId, TargetName, Oids, SendOpts)

(since OTP R14B03)

-spec async_get2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}
                    when
                        UserId :: user_id(),
                        TargetName :: target_name(),
                        Oids :: [snmp:oid()],
                        SendOpts :: [SendOpt],
                        SendOpt ::
                            {context, snmp:context_name()} |
                            {timeout, pos_integer()} |
                            {community, snmp:community()} |
                            {sec_model, snmp:sec_model()} |
                            {sec_name, snmp:sec_name()} |
                            {sec_level, snmp:sec_level()} |
                            {max_message_size, snmp:mms()} |
                            {extra, term()},
                        ReqId :: request_id(),
                        Reason :: term().

Asynchronous get-request.

The reply, if it arrives, will be delivered to the user through a call to the snmpm_user callback function handle_pdu.

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids)

(since OTP R14B03)

-spec async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId} | {error, Reason}
                         when
                             UserId :: user_id(),
                             TargetName :: target_name(),
                             NonRep :: non_neg_integer(),
                             MaxRep :: non_neg_integer(),
                             Oids :: [snmp:oid()],
                             ReqId :: request_id(),
                             Reason :: term().

Equivalent to async_get_bulk2/6.

async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts)

(since OTP R14B03)

-spec async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts) ->
                         {ok, ReqId} | {error, Reason}
                         when
                             UserId :: user_id(),
                             TargetName :: target_name(),
                             NonRep :: non_neg_integer(),
                             MaxRep :: non_neg_integer(),
                             Oids :: [snmp:oid()],
                             SendOpts :: [SendOpt],
                             SendOpt ::
                                 {context, snmp:context_name()} |
                                 {timeout, pos_integer()} |
                                 {community, snmp:community()} |
                                 {sec_model, snmp:sec_model()} |
                                 {sec_name, snmp:sec_name()} |
                                 {sec_level, snmp:sec_level()} |
                                 {max_message_size, snmp:mms()} |
                                 {extra, term()},
                             ReqId :: request_id(),
                             Reason :: term().

Asynchronous get-bulk-request (See RFC1905).

The reply, if it arrives, will be delivered to the user through a call to the snmpm_user callback function handle_pdu.

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes no use of this info, so the only use for it in such a configuration (when using the built in net-if) would be tracing.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

async_get_next2(UserId, TargetName, Oids)

(since OTP R14B03)

-spec async_get_next2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}
                         when
                             UserId :: user_id(),
                             TargetName :: target_name(),
                             Oids :: [snmp:oid()],
                             ReqId :: request_id(),
                             Reason :: term().

Equivalent to async_get_next2/4.

async_get_next2(UserId, TargetName, Oids, SendOpts)

(since OTP R14B03)

-spec async_get_next2(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}
                         when
                             UserId :: user_id(),
                             TargetName :: target_name(),
                             Oids :: [snmp:oid()],
                             SendOpts :: [SendOpt],
                             SendOpt ::
                                 {context, snmp:context_name()} |
                                 {timeout, pos_integer()} |
                                 {community, snmp:community()} |
                                 {sec_model, snmp:sec_model()} |
                                 {sec_name, snmp:sec_name()} |
                                 {sec_level, snmp:sec_level()} |
                                 {max_message_size, snmp:mms()} |
                                 {extra, term()},
                             ReqId :: request_id(),
                             Reason :: term().

Asynchronous get-next-request.

The reply, if it arrives, will be delivered to the user through a call to the snmpm_user callback function handle_pdu.

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

async_set2(UserId, TargetName, VarsAndVals)

(since OTP R14B03)

-spec async_set2(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error, Reason}
                    when
                        UserId :: user_id(),
                        TargetName :: target_name(),
                        VarsAndVals :: [var_and_val()],
                        ReqId :: request_id(),
                        Reason :: term().

Equivalent to async_set2/4.

async_set2(UserId, TargetName, VarsAndVals, SendOpts)

(since OTP R14B03)

-spec async_set2(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, ReqId} | {error, Reason}
                    when
                        UserId :: user_id(),
                        TargetName :: target_name(),
                        VarsAndVals :: [var_and_val()],
                        SendOpts :: [SendOpt],
                        SendOpt ::
                            {context, snmp:context_name()} |
                            {timeout, pos_integer()} |
                            {community, snmp:community()} |
                            {sec_model, snmp:sec_model()} |
                            {sec_name, snmp:sec_name()} |
                            {sec_level, snmp:sec_level()} |
                            {max_message_size, snmp:mms()} |
                            {extra, term()},
                        ReqId :: request_id(),
                        Reason :: term().

Asynchronous set-request.

The reply will be delivered to the user through a call to the snmpm_user callback function handle_pdu.

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

When var_and_val() is {oid(), value()}, the manager makes an educated guess based on the loaded mibs.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

backup(BackupDir)

-spec backup(BackupDir) -> ok | {error, Reason} when BackupDir :: snmp:dir(), Reason :: term().

Backup persistent data handled by the manager.

BackupDir cannot be identical to DbDir.

cancel_async_request(UserId, ReqId)

-spec cancel_async_request(UserId, ReqId) -> ok | {error, Reason}
                              when UserId :: user_id(), ReqId :: request_id(), Reason :: term().

Cancel a previous asynchronous request.

cancel_notify_started(Pid)

-spec cancel_notify_started(Pid) -> snmp:void() when Pid :: pid().

Cancel a previous request to be notified of SNMP manager start.

change_log_size(NewSize)

-spec change_log_size(NewSize) -> ok | {error, Reason} when NewSize :: snmp:log_size(), 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 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.

demonitor(Ref)

-spec demonitor(Ref) -> true when Ref :: reference().

Turn off monitoring of the SNMP manager.

format_reason(Reason)

-spec format_reason(Reason) -> FReason when Reason :: term(), FReason :: string().

Equivalent to format_reason/2.

format_reason(Prefix, Reason)

-spec format_reason(Prefix, Reason) -> FReason
                       when
                           Prefix :: non_neg_integer() | string(), Reason :: term(), FReason :: string().

This utility function is used to create a formatted (pretty printable) string of the error reason received from either:

The Reason returned value if any of the sync/async get/get-next/set/get-bulk functions returns {error, Reason}

The Reason parameter in the handle_error user callback function.

Prefix should either be an indentation string (e.g. a list of spaces) or a positive integer (which will be used to create the indentation string of that length).

info()

-spec info() -> [{Key, Value}] when Key :: atom(), Value :: term().

Returns a list (a dictionary) containing information about the manager. Information includes statistics counters, miscellaneous info about each process (e.g. memory allocation), and so on.

load_mib(MibName)

-spec load_mib(MibName) -> ok | {error, Reason} when MibName :: snmp:mib_name(), Reason :: term().

Load a Mib into the manager. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

          Dir = code:priv_dir(my_app) ++ "/mibs/",
          snmpm:load_mib(Dir ++ "MY-MIB").

log_to_io(LogDir)

(since OTP R15B01)

-spec log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/2

(since OTP R15B01)

-spec log_to_io(LogDir, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/3

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/4

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName, LogFile) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/5

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName, LogFile, Start) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Start :: null | snmp:log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io/6

(since OTP R15B01)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Start :: null | snmp:log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term();
               (LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Start :: null | snmp:log_time(),
                       Stop :: null | snmp:log_time(),
                       Cnt :: {NumOK, NumERR},
                       NumOK :: non_neg_integer(),
                       NumERR :: pos_integer(),
                       Reason :: term().

Equivalent to log_to_io/7.

log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop)

(since OTP R16B03)

-spec log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {ok, Cnt} | {error, Reason}
                   when
                       LogDir :: snmp:dir(),
                       Mibs :: [snmp:mib_name()],
                       LogName :: string(),
                       LogFile :: string(),
                       Block :: boolean(),
                       Start :: null | snmp:log_time(),
                       Stop :: null | snmp:log_time(),
                       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. LogName defaults to "snmpm_log". LogFile defaults to "snmpm.log".

The Block argument indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

Start and Stop indicates which log entries should be converted, from when (Start) to when (Stop). Start = null => Start from the beginning of the log. Stop = null => Stop the conversion at the end of the log. Defaults to Start = null and Stop = null (the entire log).

See snmp:log_to_io/7 for more info.

log_to_txt(LogDir)

(since OTP R16B03)

-spec log_to_txt(LogDir :: snmp:dir()) -> snmp:void().

Equivalent to log_to_txt/8.

log_to_txt/2

-spec log_to_txt(LogDir :: snmp:dir(), Block :: boolean()) -> snmp:void();
                (LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()]) -> snmp:void().

Equivalent to log_to_txt/8.

log_to_txt/3

-spec log_to_txt(LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()], Block :: boolean()) -> snmp:void();
                (LogDir :: snmp:dir(), Mibs :: [snmp:mib_name()], OutFile :: file:filename()) ->
                    snmp:void().

Equivalent to log_to_txt/8.

log_to_txt/4

-spec log_to_txt(LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 Block :: boolean()) ->
                    snmp:void();
                (LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 LogName :: string()) ->
                    snmp:void().

Equivalent to log_to_txt/8.

log_to_txt/5

-spec log_to_txt(LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 LogName :: string(),
                 Block :: boolean()) ->
                    snmp:void();
                (LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 LogName :: string(),
                 LogFile :: string()) ->
                    snmp:void().

Equivalent to log_to_txt/8.

log_to_txt/6

-spec log_to_txt(LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean()) ->
                    snmp:void();
                (LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 LogName :: string(),
                 LogFile :: string(),
                 Start :: null | snmp:log_time()) ->
                    snmp:void().

Equivalent to log_to_txt/8.

log_to_txt/7

-spec log_to_txt(LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Start :: null | snmp:log_time()) ->
                    snmp:void();
                (LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 LogName :: string(),
                 LogFile :: string(),
                 Start :: null | snmp:log_time(),
                 Stop :: null | snmp:log_time()) ->
                    snmp:void().

Equivalent to log_to_txt/8.

log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)

(since OTP R16B03)

-spec log_to_txt(LogDir :: snmp:dir(),
                 Mibs :: [snmp:mib_name()],
                 OutFile :: file:filename(),
                 LogName :: string(),
                 LogFile :: string(),
                 Block :: boolean(),
                 Start :: snmp:log_time(),
                 Stop :: snmp:log_time()) ->
                    snmp:void().

Converts an Audit Trail Log to a readable text file. OutFile defaults to "./snmpm_log.txt". LogName defaults to "snmpm_log". LogFile defaults to "snmpm.log".

The Block argument indicates if the log should be blocked during conversion. This could be useful when converting large logs (when otherwise the log could wrap during conversion). Defaults to true.

Start and Stop indicates which log entries should be converted, from when (Start) to when (Stop). Start = null => Start from the beginning of the log. Stop = null => Stop the conversion at the end of the log. Defaults to Start = null and Stop = null (the entire log).

See snmp:log_to_txt/8 for more info.

monitor()

-spec monitor() -> MRef when MRef :: reference().

Monitor the SNMP manager. In case of a crash, the calling (monitoring) process will get a 'DOWN' message (see the erlang module for more info).

name_to_oid(AliasName)

-spec name_to_oid(AliasName) -> {ok, OIDs} | {error, Reason}
                     when AliasName :: atom(), OIDs :: [snmp:oid()], Reason :: term().

Transform a alias-name to its oid.

Note that an alias-name is only unique within the mib, so when loading several mib's into a manager, there might be several instances of the same aliasname.

notify_started/1

-spec notify_started(Timeout) -> Pid when Timeout :: non_neg_integer(), Pid :: pid();
                    (Args) -> Pid when Args :: map(), Pid :: pid().

Request a notification (message) when the SNMP manager has started.

The Timeout is the time the request is valid. The value has to be greater then zero.

The Pid is the process handling the supervision of the SNMP manager start. When the manager has started a completion message will be sent to the client from this process: {snmpm_started, Pid}. If the SNMP manager was not started in time, a timeout message will be sent to the client: {snmpm_start_timeout, Pid}.

A client application that is dependent on the SNMP manager will use this function in order to be notified of when the manager has started. There are two situations when this is useful:

During the start of a system, when a client application could start prior to the SNMP manager but is dependent upon it, and therefore has to wait for it to start.

When the SNMP manager has crashed, the dependent client application has to wait for the SNMP manager to be restarted before it can reconnect.

The function returns the pid() of a handler process, that does the supervision on behalf of the client application. Note that the client application is linked to this handler.

This function is used in conjunction with the monitor function.

oid_to_name(OID)

-spec oid_to_name(OID) -> {ok, AliasName} | {error, Reason}
                     when OID :: snmp:oid(), AliasName :: atom(), Reason :: term().

Transform a oid to its aliasname.

oid_to_type(OID)

-spec oid_to_type(OID) -> {ok, Type} | {error, Reason}
                     when OID :: snmp:oid(), Type :: atom(), Reason :: term().

Retrieve the type (asn1 bertype) of an oid.

register_agent(UserId, TargetName, Config)

-spec register_agent(UserId, TargetName, Config) -> ok | {error, Reason}
                        when
                            UserId :: user_id(),
                            TargetName :: target_name(),
                            Config :: [ConfigEntry],
                            ConfigEntry :: {Item, Value},
                            Item :: agent_config_item(),
                            Value :: term(),
                            Reason :: term().

Explicitly instruct the manager to handle this agent, with UserId as the responsible user.

Called to instruct the manager that this agent shall be handled. This function is used when the user knows in advance which agents the manager shall handle. Note that there is an alternate way to do the same thing: Add the agent to the manager config files (see agents.conf).

TargetName is a non-empty string, uniquely identifying the agent.

The type of Val depends on Item:

[mandatory] engine_id = engine_id()
[mandatory] address = inet:ip_address()  % Depends on tdomain
[optional]  port = inet:port_number()
[optional]  tdomain = snmp:tdomain()
[optional]  community = snmp:community()
[optional]  timeout = register_timeout()
[optional]  max_message_size = snmp:mms()
[optional]  version = snmp:version()
[optional]  sec_model = snmp:sec_model()
[optional]  sec_name = snmp:sec_name()
[optional]  sec_level = snmp:sec_level()

Note that if no tdomain is given, the default value, transportDomainUdpIpv4, is used.

Note that if no port is given and if taddress does not contain a port number, the default value is used.

register_user(UserId, Module, Data)

-spec register_user(UserId, Module, Data) -> ok | {error, Reason}
                       when
                           UserId :: user_id(), Module :: snmpm_user(), Data :: term(), Reason :: term().

Equivalent to register_user/4.

register_user(UserId, Module, Data, DefaultAgentConfig)

-spec register_user(UserId, Module, Data, DefaultAgentConfig) -> ok | {error, Reason}
                       when
                           UserId :: user_id(),
                           Module :: snmpm_user(),
                           Data :: term(),
                           DefaultAgentConfig :: [DefaultConfigEntry],
                           DefaultConfigEntry :: {Item, Value},
                           Item :: agent_config_item(),
                           Value :: term(),
                           Reason :: term().

Register the manager entity (=user) responsible for specific agent(s).

Module is the callback module (snmpm_user behaviour) which will be called whenever something happens (detected agent, incoming reply or incoming trap/notification).

Data is an opaque data structure, not inspected by the manager, that will be included in all callback calls to the Module callback module (snmpm_user behaviour).

The argument DefaultAgentConfig is used as default values when this user register agents.

Note that this operation (register user) could have already been done as a consequence of the node config. (see users.conf).

register_user_monitor(UserId, Module, Data)

-spec register_user_monitor(UserId, Module, Data) -> ok | {error, Reason}
                               when
                                   UserId :: user_id(),
                                   Module :: snmpm_user(),
                                   Data :: term(),
                                   Reason :: term().

Equivalent to register_user_monitor/4.

register_user_monitor(UserId, Module, Data, DefaultAgentConfig)

-spec register_user_monitor(UserId, Module, Data, DefaultAgentConfig) -> ok | {error, Reason}
                               when
                                   UserId :: user_id(),
                                   Module :: snmpm_user(),
                                   Data :: term(),
                                   DefaultAgentConfig :: [DefaultConfigEntry],
                                   DefaultConfigEntry :: {Item, Value},
                                   Item :: agent_config_item(),
                                   Value :: term(),
                                   Reason :: term().

Register the monitored manager entity (=user) responsible for specific agent(s).

The process performing the registration will be monitored. Which means that if that process should die, all agents registered by that user process will be unregistered. All outstanding requests will be canceled.

Module is the callback module (snmpm_user behaviour) which will be called whenever something happens (detected agent, incoming reply or incoming trap/notification).

Data is an opaque data structure, not inspected by the manager, that will be included in all callback calls to the Module callback module (snmpm_user behaviour).

The argument DefaultAgentConfig is used as default values when this user register agents.

register_usm_user(EngineID, UserName, Config)

-spec register_usm_user(EngineID, UserName, Config) -> ok | {error, Reason}
                           when
                               EngineID :: snmp:engine_id(),
                               UserName :: snmp:usm_name(),
                               Config :: [ConfigEntry],
                               ConfigEntry :: {Item, Value},
                               Item :: usm_config_item(),
                               Value :: term(),
                               Reason :: term().

Explicitly instruct the manager to handle this USM user. Note that there is an alternate way to do the same thing: Add the usm user to the manager config files (see usm.conf).

restart(What)

(since OTP 22.3)

-spec restart(What) -> snmp:void() when What :: net_if.

Restart the indicated process (What). Note that its not without risk to restart a process, and should therefore be used with care.

set_log_type(NewType)

-spec set_log_type(NewType) -> {ok, OldType} | {error, Reason}
                      when NewType :: snmp:atl_type(), OldType :: snmp:atl_type(), Reason :: term().

Changes the run-time Audit Trail log type.

Note that this has no effect on the application configuration as defined by configuration files, so a node restart will revert the config to whatever is in those files.

This function is primarily useful in testing/debugging scenarios.

sync_get2(UserId, TargetName, Oids)

(since OTP R14B03)

-spec sync_get2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}
                   when
                       UserId :: user_id(),
                       TargetName :: target_name(),
                       Oids :: [snmp:oid()],
                       SnmpReply :: snmp_reply(),
                       Remaining :: non_neg_integer(),
                       Reason ::
                           {send_failed, ReqId, ActualReason} |
                           {invalid_sec_info, SecInfo, SnmpInfo} |
                           term(),
                       ReqId :: request_id(),
                       ActualReason :: term(),
                       SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                       SecTag :: atom(),
                       ExpectedValue :: term(),
                       ReceivedValue :: term(),
                       SnmpInfo :: term().

Equivalent to sync_get2/4.

sync_get2(UserId, TargetName, Oids, SendOpts)

(since OTP R14B03)

-spec sync_get2(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason}
                   when
                       UserId :: user_id(),
                       TargetName :: target_name(),
                       Oids :: [snmp:oid()],
                       SendOpts :: [SendOpt],
                       SendOpt ::
                           {context, snmp:context_name()} |
                           {timeout, pos_integer()} |
                           {community, snmp:community()} |
                           {sec_model, snmp:sec_model()} |
                           {sec_name, snmp:sec_name()} |
                           {sec_level, snmp:sec_level()} |
                           {max_message_size, snmp:mms()} |
                           {extra, term()},
                       SnmpReply :: snmp_reply(),
                       Remaining :: non_neg_integer(),
                       Reason ::
                           {send_failed, ReqId, ActualReason} |
                           {invalid_sec_info, SecInfo, SnmpInfo} |
                           term(),
                       ReqId :: request_id(),
                       ActualReason :: term(),
                       SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                       SecTag :: atom(),
                       ExpectedValue :: term(),
                       ReceivedValue :: term(),
                       SnmpInfo :: term().

Synchronous get-request.

Remaining is the remaining time of the given (or default) timeout time.

When Reason is {send_failed, ...} it means that the net-if process failed to send the (get-request ) message. This could happen because of any number of reasons, i.e. encoding error. ActualReason is the actual reason in this case.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

For SnmpInfo, see the user callback function handle_report.

sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids)

(since OTP R14B03)

-spec sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) ->
                        {ok, SnmpReply, Remaining} | {error, Reason}
                        when
                            UserId :: user_id(),
                            TargetName :: target_name(),
                            NonRep :: non_neg_integer(),
                            MaxRep :: non_neg_integer(),
                            Oids :: [snmp:oid()],
                            SnmpReply :: snmp_reply(),
                            Remaining :: non_neg_integer(),
                            Reason ::
                                {send_failed, ReqId, ActualReason} |
                                {invalid_sec_info, SecInfo, SnmpInfo} |
                                term(),
                            ReqId :: request_id(),
                            ActualReason :: term(),
                            SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                            SecTag :: atom(),
                            ExpectedValue :: term(),
                            ReceivedValue :: term(),
                            SnmpInfo :: term().

Equivalent to sync_get_bulk2/6.

sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts)

(since OTP R14B03)

-spec sync_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts) ->
                        {ok, SnmpReply, Remaining} | {error, Reason}
                        when
                            UserId :: user_id(),
                            TargetName :: target_name(),
                            NonRep :: non_neg_integer(),
                            MaxRep :: non_neg_integer(),
                            Oids :: [snmp:oid()],
                            SendOpts :: [SendOpt],
                            SendOpt ::
                                {context, snmp:context_name()} |
                                {timeout, pos_integer()} |
                                {community, snmp:community()} |
                                {sec_model, snmp:sec_model()} |
                                {sec_name, snmp:sec_name()} |
                                {sec_level, snmp:sec_level()} |
                                {max_message_size, snmp:mms()} |
                                {extra, term()},
                            ReqId :: request_id(),
                            SnmpReply :: snmp_reply(),
                            Remaining :: non_neg_integer(),
                            Reason ::
                                {send_failed, ReqId, ActualReason} |
                                {invalid_sec_info, SecInfo, SnmpInfo} |
                                term(),
                            ReqId :: request_id(),
                            ActualReason :: term(),
                            SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                            SecTag :: atom(),
                            ExpectedValue :: term(),
                            ReceivedValue :: term(),
                            SnmpInfo :: term().

Synchronous get-bulk-request (See RFC1905).

Remaining is the remaining time of the given (or default) timeout time.

When Reason is {send_failed, ...} it means that the net-if process failed to send the message. This could happen because of any number of reasons, i.e. encoding error. ActualReason is the actual reason in this case.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

For SnmpInfo, see the user callback function snmpm_user:handle_report/3.

sync_get_next2(UserId, TargetName, Oids)

(since OTP R14B03)

-spec sync_get_next2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}
                        when
                            UserId :: user_id(),
                            TargetName :: target_name(),
                            Oids :: [snmp:oid()],
                            SnmpReply :: snmp_reply(),
                            Remaining :: non_neg_integer(),
                            Reason ::
                                {send_failed, ReqId, ActualReason} |
                                {invalid_sec_info, SecInfo, SnmpInfo} |
                                term(),
                            ReqId :: request_id(),
                            ActualReason :: term(),
                            SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                            SecTag :: atom(),
                            ExpectedValue :: term(),
                            ReceivedValue :: term(),
                            SnmpInfo :: term().

Equivalent to sync_get_next2/4.

sync_get_next2(UserId, TargetName, Oids, SendOpts)

(since OTP R14B03)

-spec sync_get_next2(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason}
                        when
                            UserId :: user_id(),
                            TargetName :: target_name(),
                            Oids :: [snmp:oid()],
                            SendOpts :: [SendOpt],
                            SendOpt ::
                                {context, snmp:context_name()} |
                                {timeout, pos_integer()} |
                                {community, snmp:community()} |
                                {sec_model, snmp:sec_model()} |
                                {sec_name, snmp:sec_name()} |
                                {sec_level, snmp:sec_level()} |
                                {max_message_size, snmp:mms()} |
                                {extra, term()},
                            SnmpReply :: snmp_reply(),
                            Remaining :: non_neg_integer(),
                            Reason ::
                                {send_failed, ReqId, ActualReason} |
                                {invalid_sec_info, SecInfo, SnmpInfo} |
                                term(),
                            ReqId :: request_id(),
                            ActualReason :: term(),
                            SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                            SecTag :: atom(),
                            ExpectedValue :: term(),
                            ReceivedValue :: term(),
                            SnmpInfo :: term().

Synchronous get-next-request.

Remaining is the remaining time of the given (or default) timeout time.

When Reason is {send_failed, ...} it means that the net-if process failed to send the message. This could happen because of any number of reasons, i.e. encoding error. ActualReason is the actual reason in this case.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

For SnmpInfo, see the user callback function handle_report.

sync_set2(UserId, TargetName, VarsAndVals)

(since OTP R14B03)

-spec sync_set2(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason}
                   when
                       UserId :: user_id(),
                       TargetName :: target_name(),
                       VarsAndVals :: [var_and_val()],
                       SnmpReply :: snmp_reply(),
                       Remaining :: non_neg_integer(),
                       Reason ::
                           {send_failed, ReqId, ActualReason} |
                           {invalid_sec_info, SecInfo, SnmpInfo} |
                           term(),
                       ReqId :: request_id(),
                       ActualReason :: term(),
                       SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                       SecTag :: atom(),
                       ExpectedValue :: term(),
                       ReceivedValue :: term(),
                       SnmpInfo :: term().

Equivalent to sync_set2/4.

sync_set2(UserId, TargetName, VarsAndVals, SendOpts)

(since OTP R14B03)

-spec sync_set2(UserId, TargetName, VarsAndVals, SendOpts) ->
                   {ok, SnmpReply, Remaining} | {error, Reason}
                   when
                       UserId :: user_id(),
                       TargetName :: target_name(),
                       VarsAndVals :: [var_and_val()],
                       SendOpts :: [SendOpt],
                       SendOpt ::
                           {context, snmp:context_name()} |
                           {timeout, pos_integer()} |
                           {community, snmp:community()} |
                           {sec_model, snmp:sec_model()} |
                           {sec_name, snmp:sec_name()} |
                           {sec_level, snmp:sec_level()} |
                           {max_message_size, snmp:mms()} |
                           {extra, term()},
                       SnmpReply :: snmp_reply(),
                       Remaining :: non_neg_integer(),
                       Reason ::
                           {send_failed, ReqId, ActualReason} |
                           {invalid_sec_info, SecInfo, SnmpInfo} |
                           term(),
                       ReqId :: request_id(),
                       ActualReason :: term(),
                       SecInfo :: {SecTag, ExpectedValue, ReceivedValue},
                       SecTag :: atom(),
                       ExpectedValue :: term(),
                       ReceivedValue :: term(),
                       SnmpInfo :: term().

Synchronous set-request.

Remaining is the remaining time of the given (or default) timeout time.

When Reason is {send_failed, ...} it means that the net-if process failed to send the message. This could happen because of any number of reasons, i.e. encoding error. ActualReason is the actual reason in this case.

When var_and_val() is {oid(), value()}, the manager makes an educated guess based on the loaded mibs.

The send option extra specifies an opaque data structure passed on to the net-if process. The net-if process included in this application makes, with one exception, no use of this info, so the only use for it (when using the built in net-if) would be tracing. The one usage exception is: Any tuple with snmpm_extra_info_tag as its first element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, for this request, they override any configuration done when the agent was registered.

For SnmpInfo, see the user callback function snmpm_user:handle_report/3.

unload_mib(MibName)

-spec unload_mib(MibName) -> ok | {error, Reason} when MibName :: snmp:mib_name(), Reason :: term().

Unload a Mib from the manager. The MibName is the name of the Mib, including the path to where the compiled mib is found. For example,

          Dir = code:priv_dir(my_app) ++ "/mibs/",
          snmpm:unload_mib(Dir ++ "MY-MIB").

unregister_agent(UserId, TargetName)

-spec unregister_agent(UserId, TargetName) -> ok | {error, Reason}
                          when UserId :: user_id(), TargetName :: target_name(), Reason :: term().

Unregister the agent.

unregister_user(UserId)

-spec unregister_user(UserId) -> ok | {error, Reason} when UserId :: user_id(), Reason :: term().

Unregister the user.

unregister_usm_user(EngineID, UserName)

-spec unregister_usm_user(EngineID, UserName) -> ok | {error, Reason}
                             when
                                 EngineID :: snmp:engine_id(),
                                 UserName :: snmp:usm_name(),
                                 Reason :: term().

Unregister this USM user.

update_agent_info(UserId, TargetName, Info)

(since OTP R14B04)

-spec update_agent_info(UserId, TargetName, Info) -> ok | {error, Reason}
                           when
                               UserId :: user_id(),
                               TargetName :: target_name(),
                               Info :: [{Item, Value}],
                               Item :: agent_config_item(),
                               Value :: term(),
                               Reason :: term().

Update agent config.

This function, update_agent_info/3, should be used when several values needs to be updated atomically.

See function register_agent/3 for more info about what kind of items are allowed.

update_agent_info(UserId, TargetName, Item, Value)

-spec update_agent_info(UserId, TargetName, Item, Value) -> ok | {error, Reason}
                           when
                               UserId :: user_id(),
                               TargetName :: target_name(),
                               Item :: agent_config_item(),
                               Value :: term(),
                               Reason :: term().

Update agent config.

See function register_agent/3 for more info about what kind of items are allowed.

update_usm_user_info(EngineID, UserName, Item, Value)

-spec update_usm_user_info(EngineID, UserName, Item, Value) -> ok | {error, Reason}
                              when
                                  EngineID :: snmp:engine_id(),
                                  UserName :: snmp:usm_name(),
                                  Item :: usm_config_item(),
                                  Value :: term(),
                                  Reason :: term().

Update usm user config.

usm_user_info(EngineID, UserName, Item)

-spec usm_user_info(EngineID, UserName, Item) -> {ok, Value} | {error, Reason}
                       when
                           EngineID :: snmp:engine_id(),
                           UserName :: snmp:usm_name(),
                           Item :: usm_config_item(),
                           Value :: term(),
                           Reason :: term().

Retrieve usm user config.

verbosity(Target, Verbosity)

-spec verbosity(Target, Verbosity) -> snmp:void()
                   when
                       Target :: config | server | net_if | note_store | all,
                       Verbosity :: snmp:verbosity().

Sets verbosity for the designated process. For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

which_agents()

-spec which_agents() -> Agents when Agents :: [target_name()].

Equivalent to which_agents/1.

which_agents(UserId)

-spec which_agents(UserId) -> Agents when UserId :: user_id(), Agents :: [target_name()].

Get a list of all registered agents or all agents registered by a specific user.

which_mibs()

-spec which_mibs() -> Mibs
                    when Mibs :: [{MibName, MibFile}], MibName :: snmp:mib_name(), MibFile :: string().

Get a list of all the mib's loaded into the manager.

which_users()

-spec which_users() -> Users when Users :: [user_id()].

Get a list of the identities of all registered users.

which_usm_users()

-spec which_usm_users() -> UsmUsers
                         when
                             UsmUsers :: [{EngineID, UserName}],
                             EngineID :: snmp:engine_id(),
                             UserName :: snmp:usm_name().

Get a list of all registered usm users.

which_usm_users(EngineID)

-spec which_usm_users(EngineID) -> UsmUsers
                         when
                             EngineID :: snmp:engine_id(),
                             UsmUsers :: [UserName],
                             UserName :: snmp:usm_name().

Get a list of all registered usm users with engine-id EngineID.

snmpm_conf

Utility functions for handling the manager config files.

The module snmpm_conf contains various utility functions to used for manipulating (write/append/read) the config files of the SNMP manager.

Summary

Types

agent_entry()

An opaque data structure containg all configuration for one agent for the manager.

manager_entry()

An opaque data structure that represents one configuration entry for the manager.

user_entry()

An opaque data structure containg all configuration for one user for the manager.

usm_entry()

An opaque data structure containg information about security data for usm for the manager.

Functions

agents_entry/12

Create an entry for the manager agents config file, agents.conf.

append_agents_config(Dir, Conf)

Append the agents config to the current manager agents config file.

append_manager_config(Dir, Conf)

Append the config to the current manager config file.

append_users_config(Dir, Conf)

Append the users config to the current manager users config file.

append_usm_config(Dir, Conf)

Append the usm config to the current manager usm config file.

manager_entry(Tag, Val)

Create an entry for the manager config file, manager.conf.

read_agents_config(Dir)

Read the current manager agents config file.

read_manager_config(Dir)

Read the current manager config file.

read_users_config(Dir)

Read the current manager users config file.

read_usm_config(Dir)

Read the current manager usm config file.

users_entry(UserId)

Equivalent to users_entry(UserId, snmpm_user_default).

users_entry(UserId, UserMod)

Equivalent to users_entry(UserId, UserMod, undefined).

users_entry(UserId, UserMod, UserData)

Equivalent to users_entry(UserId, UserMod, UserData, []).

users_entry(UserId, UserMod, UserData, DefaultAgentConfig)

Create an entry for the manager users config file, users.conf.

usm_entry(EngineID, UserName, AuthP, AuthKey, PrivP, PrivKey)

Equivalent to usm_entry/7.

usm_entry(EngineID, UserName, SecName, AuthP, AuthKey, PrivP, PrivKey)

Create an entry for the manager usm config file, usm.conf.

write_agents_config(Dir, Conf)

Equivalent to write_agents_config/3.

write_agents_config(Dir, Hdr, Conf)

Write the manager agents config to the manager agents config file.

write_manager_config(Dir, Conf)

Equivalent to write_manager_config/3.

write_manager_config(Dir, Hdr, Conf)

Write the manager config to the manager config file.

write_users_config(Dir, Conf)

Equivalent to write_users_config/3.

write_users_config(Dir, Hdr, Conf)

Write the manager users config to the manager users config file.

write_usm_config(Dir, Conf)

Equivalent to write_usm_config/3.

write_usm_config(Dir, Hdr, Conf)

Write the manager usm config to the manager usm config file.

Types

agent_entry()

-opaque agent_entry()

An opaque data structure containg all configuration for one agent for the manager.

manager_entry()

-opaque manager_entry()

An opaque data structure that represents one configuration entry for the manager.

user_entry()

-opaque user_entry()

An opaque data structure containg all configuration for one user for the manager.

usm_entry()

-opaque usm_entry()

An opaque data structure containg information about security data for usm for the manager.

Functions

agents_entry/12

-spec agents_entry(UserId, TargetName, Comm, TDomain, TAddr, EngineID, Timeout, MaxMessageSize, Version,
                   SecModel, SecName, SecLevel) ->
                      Entry
                      when
                          UserId :: snmpm:user_id(),
                          TargetName :: snmpm:target_name(),
                          Comm :: snmp:community(),
                          TDomain :: snmp:tdomain(),
                          TAddr :: snmp:taddress(),
                          EngineID :: snmp:engine_id(),
                          Timeout :: snmpm:register_timeout(),
                          MaxMessageSize :: snmp:mms(),
                          Version :: snmp:version(),
                          SecModel :: snmp:sec_model(),
                          SecName :: snmp:sec_name(),
                          SecLevel :: snmp:sec_level(),
                          Entry :: agent_entry();
                  (UserId, TargetName, Comm, Ip, Port, EngineID, Timeout, MaxMessageSize, Version,
                   SecModel, SecName, SecLevel) ->
                      Entry
                      when
                          UserId :: snmpm:user_id(),
                          TargetName :: snmpm:target_name(),
                          Comm :: snmp:community(),
                          Ip :: inet:ip_address(),
                          Port :: inet:port_number(),
                          EngineID :: snmp:engine_id(),
                          Timeout :: snmpm:register_timeout(),
                          MaxMessageSize :: snmp:mms(),
                          Version :: snmp:version(),
                          SecModel :: snmp:sec_model(),
                          SecName :: snmp:sec_name(),
                          SecLevel :: snmp:sec_level(),
                          Entry :: agent_entry().

Create an entry for the manager agents config file, agents.conf.

See Agents for more info.

append_agents_config(Dir, Conf)

-spec append_agents_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [agent_entry()].

Append the agents config to the current manager agents config file.

Dir is the path to the directory where to store the config file.

See Agents for more info.

append_manager_config(Dir, Conf)

-spec append_manager_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [manager_entry()].

Append the config to the current manager config file.

Dir is the path to the directory where to store the config file.

See Manager Information for more info.

append_users_config(Dir, Conf)

-spec append_users_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [user_entry()].

Append the users config to the current manager users config file.

Dir is the path to the directory where to store the config file.

See Users for more info.

append_usm_config(Dir, Conf)

-spec append_usm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [usm_entry()].

Append the usm config to the current manager usm config file.

Dir is the path to the directory where to store the config file.

See Security data for USM for more info.

manager_entry(Tag, Val)

-spec manager_entry(Tag, Val) -> ManagerEntry
                       when
                           Tag :: transports | port | engine_id | max_message_size,
                           Val :: term(),
                           ManagerEntry :: manager_entry();
                   (Tag, Val) -> ManagerEntry
                       when Tag :: address, Val :: term(), ManagerEntry :: manager_entry().

Create an entry for the manager config file, manager.conf.

The type of Val depends on the value of Tag, see Manager Information for more info.

read_agents_config(Dir)

-spec read_agents_config(Dir) -> {ok, Conf} | {error, Reason}
                            when Dir :: snmp:dir(), Conf :: [agent_entry()], Reason :: term().

Read the current manager agents config file.

Dir is the path to the directory where to store the config file.

See Agents for more info.

read_manager_config(Dir)

-spec read_manager_config(Dir) -> {ok, Conf} | {error, Reason}
                             when Dir :: snmp:dir(), Conf :: [manager_entry()], Reason :: term().

Read the current manager config file.

Dir is the path to the directory where to store the config file.

See Manager Information for more info.

read_users_config(Dir)

-spec read_users_config(Dir) -> {ok, Conf} | {error, Reason}
                           when Dir :: snmp:dir(), Conf :: [user_entry()], Reason :: term().

Read the current manager users config file.

Dir is the path to the directory where to store the config file.

See Users for more info.

read_usm_config(Dir)

-spec read_usm_config(Dir) -> {ok, Conf} | {error, Reason}
                         when Dir :: snmp:dir(), Conf :: [usm_entry()], Reason :: term().

Read the current manager usm config file.

Dir is the path to the directory where to store the config file.

See Security data for USM for more info.

users_entry(UserId)

-spec users_entry(UserId) -> UserEntry when UserId :: snmpm:user_id(), UserEntry :: user_entry().

Equivalent to users_entry(UserId, snmpm_user_default).

users_entry(UserId, UserMod)

-spec users_entry(UserId, UserMod) -> UserEntry
                     when
                         UserId :: snmpm:user_id(),
                         UserMod :: snmpm:snmpm_user(),
                         UserEntry :: user_entry().

Equivalent to users_entry(UserId, UserMod, undefined).

users_entry(UserId, UserMod, UserData)

-spec users_entry(UserId, UserMod, UserData) -> UserEntry
                     when
                         UserId :: snmpm:user_id(),
                         UserMod :: snmpm:snmpm_user(),
                         UserData :: term(),
                         UserEntry :: user_entry().

Equivalent to users_entry(UserId, UserMod, UserData, []).

users_entry(UserId, UserMod, UserData, DefaultAgentConfig)

(since OTP 27.0)

-spec users_entry(UserId, UserMod, UserData, DefaultAgentConfig) -> UserEntry
                     when
                         UserId :: snmpm:user_id(),
                         UserMod :: snmpm:snmpm_user(),
                         UserData :: term(),
                         DefaultAgentConfig :: [snmpm:agent_config()],
                         UserEntry :: user_entry().

Create an entry for the manager users config file, users.conf.

See the Users chapter of the (SNMP) Manager Configuration User Guide for more info.

usm_entry(EngineID, UserName, AuthP, AuthKey, PrivP, PrivKey)

-spec usm_entry(EngineID, UserName, AuthP, AuthKey, PrivP, PrivKey) -> UsmEntry
                   when
                       EngineID :: snmp:engine_id(),
                       UserName :: snmp:usm_name(),
                       AuthP :: snmp:usm_auth_protocol(),
                       AuthKey :: snmp:usm_auth_key(),
                       PrivP :: snmp:usm_priv_protocol(),
                       PrivKey :: snmp:usm_priv_key(),
                       UsmEntry :: usm_entry().

Equivalent to usm_entry/7.

usm_entry(EngineID, UserName, SecName, AuthP, AuthKey, PrivP, PrivKey)

-spec usm_entry(EngineID, UserName, SecName, AuthP, AuthKey, PrivP, PrivKey) -> UsmEntry
                   when
                       EngineID :: snmp:engine_id(),
                       UserName :: snmp:usm_name(),
                       SecName :: snmp:sec_name(),
                       AuthP :: snmp:usm_auth_protocol(),
                       AuthKey :: snmp:usm_auth_key(),
                       PrivP :: snmp:usm_priv_protocol(),
                       PrivKey :: snmp:usm_priv_key(),
                       UsmEntry :: usm_entry().

Create an entry for the manager usm config file, usm.conf.

See Security data for USM for more info.

write_agents_config(Dir, Conf)

-spec write_agents_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [agent_entry()].

Equivalent to write_agents_config/3.

write_agents_config(Dir, Hdr, Conf)

-spec write_agents_config(Dir, Hdr, Conf) -> ok
                             when Dir :: snmp:dir(), Hdr :: string(), Conf :: [agent_entry()].

Write the manager agents config to the manager agents config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Agents for more info.

write_manager_config(Dir, Conf)

-spec write_manager_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [manager_entry()].

Equivalent to write_manager_config/3.

write_manager_config(Dir, Hdr, Conf)

-spec write_manager_config(Dir, Hdr, Conf) -> ok
                              when Dir :: snmp:dir(), Hdr :: string(), Conf :: [manager_entry()].

Write the manager config to the manager config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Manager Information for more info.

write_users_config(Dir, Conf)

-spec write_users_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [user_entry()].

Equivalent to write_users_config/3.

write_users_config(Dir, Hdr, Conf)

-spec write_users_config(Dir, Hdr, Conf) -> ok
                            when Dir :: snmp:dir(), Hdr :: string(), Conf :: [user_entry()].

Write the manager users config to the manager users config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Users for more info.

write_usm_config(Dir, Conf)

-spec write_usm_config(Dir, Conf) -> ok when Dir :: snmp:dir(), Conf :: [user_entry()].

Equivalent to write_usm_config/3.

write_usm_config(Dir, Hdr, Conf)

-spec write_usm_config(Dir, Hdr, Conf) -> ok
                          when Dir :: snmp:dir(), Hdr :: string(), Conf :: [user_entry()].

Write the manager usm config to the manager usm config file.

Dir is the path to the directory where to store the config file.

Hdr is an optional file header (note that this text is written to the file as is).

See Security data for USM for more info.

snmpm_mpd

Message Processing and Dispatch module for the SNMP manager

The module snmpm_mpd implements the version independent Message Processing and Dispatch functionality in SNMP for the manager. It is supposed to be used from a Network Interface process (Definition of Manager Net if).

Legacy API function process_msg/7 that has got separate IpAddr and PortNumber arguments still works as before for backwards compatibility reasons.

Summary

Types

logger()

A fun that handles audit trail logging.

mpd_state()

msg_data_acm()

Is an opaque data structure containing necessary security information for (incoming) v3 messages.

msg_data_cmy()

Is an opaque data structure containing necessary security information for v1 and v2 messages.

msg_data_cmyt()

Is an opaque data structure containing necessary security and transport information for v1 and v2 messages.

msg_data_v3()

Is an opaque data structure containing necessary security information for v3 messages.

Functions

generate_msg(Vsn, NoteStore, Pdu, MsgData, Log)

Generates a possibly encrypted packet to be sent to the network.

generate_response_msg(Vsn, Pdu, MsgData, Log)

Generates a possibly encrypted response packet to be sent to the network.

init(Vsns)

This function can be called from the net-if process at start-up. The options list defines which versions to use.

process_msg(Msg, Domain, Addr, State, NoteStore, Log)

Processes an incoming message. Performs authentication and decryption as necessary. The return values should be passed the manager server.

Types

logger()

-type logger() ::
          fun((Data ::
                   binary() |
                   snmp_pdus:pdu() |
                   snmp_pdus:trappdu() |
                   snmp_pdus:message() |
                   {V3Hdr :: snmp_pdus:v3_hdr(), ScopedPDUBytes :: binary()}) ->
                  snmp:void()).

A fun that handles audit trail logging.

mpd_state()

-opaque mpd_state()

msg_data_acm()

-opaque msg_data_acm()

Is an opaque data structure containing necessary security information for (incoming) v3 messages.

msg_data_cmy()

-opaque msg_data_cmy()

Is an opaque data structure containing necessary security information for v1 and v2 messages.

msg_data_cmyt()

-opaque msg_data_cmyt()

Is an opaque data structure containing necessary security and transport information for v1 and v2 messages.

msg_data_v3()

-opaque msg_data_v3()

Is an opaque data structure containing necessary security information for v3 messages.

Functions

generate_msg(Vsn, NoteStore, Pdu, MsgData, Log)

-spec generate_msg(Vsn, NoteStore, Pdu, MsgData, Log) -> {ok, Packet} | {discarded, Reason}
                      when
                          Vsn :: snmp_pdus:version(),
                          NoteStore :: pid(),
                          Pdu :: snmp_pdus:pdu(),
                          MsgData :: msg_data_cmy() | msg_data_v3(),
                          Log :: logger(),
                          Packet :: binary(),
                          Reason :: term().

Generates a possibly encrypted packet to be sent to the network.

NoteStore is the pid() of the note-store process.

MsgData is the message specific data used in the SNMP message. In SNMPv1 and SNMPv2c, this message data is the community string. In SNMPv3, it is the context information.

Logger is the function used for audit trail logging.

generate_response_msg(Vsn, Pdu, MsgData, Log)

-spec generate_response_msg(Vsn, Pdu, MsgData, Log) ->
                               {ok, Packet} | {discarded, Reason} | {error, Reason}
                               when
                                   Vsn :: snmp_pdus:version(),
                                   Pdu :: snmp_pdus:pdu(),
                                   MsgData :: msg_data_cmy() | msg_data_cmyt() | msg_data_v3(),
                                   Log :: logger(),
                                   Packet :: binary(),
                                   Reason :: term().

Generates a possibly encrypted response packet to be sent to the network.

MsgData is the message specific data used in the SNMP message. This value is received from the process_msg/6 function.

init(Vsns)

-spec init(Vsns) -> MPDState when Vsns :: [snmp:version()], MPDState :: mpd_state().

This function can be called from the net-if process at start-up. The options list defines which versions to use.

It also initializes some SNMP counters.

process_msg(Msg, Domain, Addr, State, NoteStore, Log)

(since OTP 17.3)

-spec process_msg(Msg, Domain, Addr, State, NoteStore, Log) ->
                     {ok, Vsn, PduV2, PduMS, MsgDataV2} |
                     {ok, 'version-3', PduV3, PduMS, MsgDataV3} |
                     {discarded, Reason}
                     when
                         Msg :: binary(),
                         Domain :: snmpUDPDomain | snmp:tdomain(),
                         Addr :: {Ip, Port},
                         Ip :: inet:ip_address(),
                         Port :: inet:port_number(),
                         State :: mpd_state(),
                         NoteStore :: pid(),
                         Log :: logger(),
                         Vsn :: 'version-1' | 'version-2',
                         PduV2 :: snmp_pdus:pdu() | snmp_pdus:trappdu(),
                         PduV3 :: snmp_pdus:pdu(),
                         PduMS :: pos_integer(),
                         MsgDataV2 :: msg_data_cmyt(),
                         MsgDataV3 :: ok | {error, ReqId, ACM} | undefined | msg_data_acm(),
                         ReqId :: snmpm:request_id(),
                         ACM :: term(),
                         Reason :: term().

Processes an incoming message. Performs authentication and decryption as necessary. The return values should be passed the manager server.

NoteStore is the pid() of the note-store process.

Logger is the function used for audit trail logging.

In the case when the pdu type is report, MsgData is either ok or {error, ReqId, Reason}.

snmpm_network_interface behaviour

Behaviour module for the SNMP manager network interface.

This module defines the behaviour of the manager network interface. A snmpm_network_interface compliant module must export the following functions:

start_link/2

stop/1

send_pdu/7

inform_response/4

note_store/2

info/1

get_log_type/1

set_log_type/2

verbosity/2

The semantics of them and their exact signatures are explained below.

Legacy API function send_pdu/7 that has got separate IpAddr and PortNumber arguments still works as before for backwards compatibility reasons.

Summary

Callbacks

get_log_type(Pid)

The Audit Trail Log is managed by the network interface process. So, it is this process that has to return the actual log-type.

info(Pid)

The info returned is basically up to the implementer to decide. The implementation provided by this application provides info about memory allocation and various socket information.

inform_response(Pid, Ref, Addr, Port)

Instruct the network interface process to send the response (acknowledgment) to an inform-request.

note_store(Pid, NoteStore)

Change the pid of the note-store process. This is used when the server restarts the note-store (e.g. after a crach).

send_pdu(Pid, Pdu, Vsn, MsgData, Domain, Addr, ExtraInfo)

Request the network interface process (Pid) to send this pdu (Pdu).

set_log_type(Pid, NewType)

The Audit Trail Log is managed by the network interface process. So, it is this process that has to do the actual changing of the type.

start_link(Server, NoteStore)

Start-link the network interface process.

stop(Pid)

Stop the network interface process.

verbosity(Pid, Verbosity)

Change the verbosity of the network interface process.

Callbacks

get_log_type(Pid)

-callback get_log_type(Pid) -> {ok, LogType} | {error, Reason}
                          when Pid :: pid(), LogType :: snmp:atl_type(), Reason :: term().

The Audit Trail Log is managed by the network interface process. So, it is this process that has to return the actual log-type.

info(Pid)

-callback info(Pid) -> Info when Pid :: pid(), Info :: [{Key, Value}], Key :: term(), Value :: term().

The info returned is basically up to the implementer to decide. The implementation provided by this application provides info about memory allocation and various socket information.

The info returned by this function is returned together with other info collected by the manager when the snmpm:info() function is called (tagged with the key net_if).

inform_response(Pid, Ref, Addr, Port)

-callback inform_response(Pid, Ref, Addr, Port) -> snmp:void()
                             when
                                 Pid :: pid(),
                                 Ref :: term(),
                                 Addr :: inet:ip_address(),
                                 Port :: inet:port_number().

Instruct the network interface process to send the response (acknowledgment) to an inform-request.

Ref is something that can be used to identify the inform-request, e.g. request-id of the inform-request.

Addr and Port identifies the agent, from which the inform-request originated.

note_store(Pid, NoteStore)

-callback note_store(Pid, NoteStore) -> snmp:void() when Pid :: pid(), NoteStore :: pid().

Change the pid of the note-store process. This is used when the server restarts the note-store (e.g. after a crach).

send_pdu(Pid, Pdu, Vsn, MsgData, Domain, Addr, ExtraInfo)

-callback send_pdu(Pid, Pdu, Vsn, MsgData, Domain, Addr, ExtraInfo) -> snmp:void()
                      when
                          Pid :: pid(),
                          Pdu :: snmp:pdu(),
                          Vsn :: 'version-1' | 'version-2' | 'version-3',
                          MsgData :: term(),
                          Domain :: snmp:tdomain(),
                          Addr :: {inet:ip_address(), inet:port_number()},
                          ExtraInfo :: term().

Request the network interface process (Pid) to send this pdu (Pdu).

ExtraInfo is some opaque data that is passed to the net-if process. It originates from the ExtraInfo parameter in the calls to the synchronous get-request, asynchronous get-request, synchronous get-next-request, asynchronous get-next-request, synchronous set-request and asynchronous set-request functions. Whether the net-if process chooses to use this is implementation dependent. The net-if process included in this application ignores it.

set_log_type(Pid, NewType)

-callback set_log_type(Pid, NewType) -> {ok, OldType} | {error, Reason}
                          when
                              Pid :: pid(),
                              NewType :: snmp:atl_type(),
                              OldType :: snmp:atl_type(),
                              Reason :: term().

The Audit Trail Log is managed by the network interface process. So, it is this process that has to do the actual changing of the type.

See snmpm:set_log_type/1 for more info.

start_link(Server, NoteStore)

-callback start_link(Server, NoteStore) -> {ok, Pid} | {error, Reason}
                        when Server :: pid(), NoteStore :: pid(), Pid :: pid(), Reason :: term().

Start-link the network interface process.

Server is the pid of the managing process.

NoteStore is the pid of the note-store process.

stop(Pid)

-callback stop(Pid) -> snmp:void() when Pid :: pid().

Stop the network interface process.

verbosity(Pid, Verbosity)

-callback verbosity(Pid, Verbosity) -> snmp:void() when Pid :: pid(), Verbosity :: snmp:verbosity().

Change the verbosity of the network interface process.

snmpm_network_interface_filter behaviour

Behaviour module for the SNMP manager network-interface filter.

This module defines the behaviour of the manager network interface filter. A snmpm_network_interface_filter compliant module must export the following functions:

accept_recv/2

accept_send/2

accept_recv_pdu/3

accept_send_pdu/3

The semantics of them and their exact signatures are explained below.

The purpose of the network interface filter is to allow for filtering of messages (accept or reject) receive and send. This is done on two levels:

The first level is at the UDP entry / exit point, i.e. immediately after the receipt of the message, before any message processing is done (accept_recv) and immediately before sending the message, after all message processing is done (accept_send).

The second level is at the MPD entry / exit point, i.e. immediately after the basic message processing (accept_recv_pdu) / immediately before the basic message processing (accept_send_pdu).

Note that the network interface filter is something which is used by the network interface implementation provided by the application (snmpm_net_if and snmpm_net_if_mt). The default filter accepts all messages.

A network interface filter can e.g. be used during testing or for load regulation.

Legacy network interface filter modules used arguments on the form (IpAddr, PortNumber,...) instead of (Domain, Addr, ...), and if the SNMP manager is run without changing the configuration to use transport domains the network interface filter will still get the old arguments and work as before.

Summary

Types

pdu_type()

transportAddressWithPort()

transportDomain()

Callbacks

accept_recv(Domain, Addr)

Called at the reception of a message (before any processing has been done).

accept_recv_pdu(Domain, Addr, PduType)

Called after the basic message processing (MPD) has been done, but before the pdu is handed over to the server for primary processing.

accept_send(Domain, Addr)

Called before the sending of a message (after all processing has been done).

accept_send_pdu(Domain, Addr, PduType)

Called before the basic message processing (MPD) is done, when a pdu has been received from the master-agent.

Types

pdu_type()

(not exported)

-type pdu_type() :: snmpm:pdu_type().

transportAddressWithPort()

(not exported)

-type transportAddressWithPort() :: snmpa_conf:transportAddressWithPort().

transportDomain()

(not exported)

-type transportDomain() :: snmpa_conf:transportDomain().

Callbacks

accept_recv(Domain, Addr)

-callback accept_recv(Domain, Addr) -> boolean()
                         when Domain :: transportDomain(), Addr :: transportAddressWithPort().

Called at the reception of a message (before any processing has been done).

For the message to be rejected, the function must return false.

accept_recv_pdu(Domain, Addr, PduType)

-callback accept_recv_pdu(Domain, Addr, PduType) -> boolean()
                             when
                                 Domain :: transportDomain(),
                                 Addr :: transportAddressWithPort(),
                                 PduType :: pdu_type().

Called after the basic message processing (MPD) has been done, but before the pdu is handed over to the server for primary processing.

For the pdu to be rejected, the function must return false.

accept_send(Domain, Addr)

-callback accept_send(Domain, Addr) -> boolean()
                         when Domain :: transportDomain(), Addr :: transportAddressWithPort().

Called before the sending of a message (after all processing has been done).

For the message to be rejected, the function must return false.

accept_send_pdu(Domain, Addr, PduType)

-callback accept_send_pdu(Domain, Addr, PduType) -> boolean()
                             when
                                 Domain :: transportDomain(),
                                 Addr :: transportAddressWithPort(),
                                 PduType :: pdu_type().

Called before the basic message processing (MPD) is done, when a pdu has been received from the master-agent.

For the message to be rejected, the function must return false.

snmpm_user behaviour

Behaviour module for the SNMP manager user.

This module defines the behaviour of the manager user. A snmpm_user compliant module must export the following functions:

handle_error/3

handle_agent/5

handle_pdu/4

handle_trap/3

handle_inform/3

handle_report/3

handle_invalid_result/2

The semantics of them and their exact signatures are explained below.

Some of the function has no defined return value (void()), they can of course return anything. But the functions that do have specified return value(s) must adhere to this. None of the functions can use exit of throw to return.

If the manager is not configured to use any particular transport domain, the behaviour handle_agent/5 will for backwards copmpatibility reasons be called with the old IpAddr and PortNumber arguments

Summary

Types

ip_address()

port_number()

snmp_gen_info()

General error information (does not have to indicate an error)..

snmp_v1_trap_info()

Trap related information.

Callbacks

handle_agent(Domain, Address, Type, SnmpInfo, UserData)

This function is called when a message is received from an unknown agent.

handle_error(ReqId, Reason, UserData)

This function is called when the manager needs to communicate an "asynchronous" error to the user: e.g. failure to send an asynchronous message (i.e. encoding error), a received message was discarded due to security error, the manager failed to generate a response message to a received inform-request, or when receiving an unexpected PDU from an agent (could be an expired async request).

handle_inform(TargetName, SnmpInform, UserData)

Handle a inform message.

handle_invalid_result(In, Out)

If any of the other callback functions crashes (exit, throw or a plain crash) or return an invalid result (if a valid return has been specified), this function is called. The purpose is to allow the user handle this error (for instance to issue an error report).

handle_pdu(TargetName, ReqId, SnmpResponse, UserData)

Handle the reply to an asynchronous request, such as async_get, async_get_next or async_set.

handle_report(TargetName, SnmpReport, UserData)

Handle a report message.

handle_trap(TargetName, SnmpTrapInfo, UserData)

Handle a trap/notification message from an agent.

Types

ip_address()

(not exported)

-type ip_address() :: inet:ip_address().

port_number()

(not exported)

-type port_number() :: inet:port_number().

snmp_gen_info()

-type snmp_gen_info() ::
          {ErrorStatus :: atom(), ErrorIndex :: pos_integer(), Varbinds :: [snmp:varbind()]}.

General error information (does not have to indicate an error)..

snmp_v1_trap_info()

-type snmp_v1_trap_info() ::
          {Enteprise :: snmp:oid(),
           Generic :: integer(),
           Spec :: integer(),
           Timestamp :: integer(),
           Varbinds :: [snmp:varbind()]}.

Trap related information.

Callbacks

handle_agent(Domain, Address, Type, SnmpInfo, UserData)

-callback handle_agent(Domain :: atom(),
                       Address :: term(),
                       Type :: pdu | trap | inform | report,
                       SnmpInfo :: snmp_gen_info() | snmp_v1_trap_info(),
                       UserData :: term()) ->
                          Reply ::
                              ignore |
                              {register,
                               UserId :: term(),
                               RTargetName :: snmpm:target_name(),
                               AgentConfig :: [snmpm:agent_config()]}.

This function is called when a message is received from an unknown agent.

Note that this will always be the default user that is called.

For more info about the agent_config(), see snmpm:register_agent/3.

The arguments Type and SnmpInfo relates in the following way:

pdu - SnmpPduInfo (see handle_pdu/4 for more info).

trap - SnmpTrapInfo (see handle_trap/3 for more info).

report - SnmpReportInfo (see handle_report/3 for more info).

inform - SnmpInformInfo (see handle_inform/3 for more info).

The only user which would return {register, UserId, TargetName, AgentConfig} is the default user.

handle_error(ReqId, Reason, UserData)

-callback handle_error(ReqId :: netif | integer(),
                       Reason ::
                           {unexpected_pdu, SnmpInfo :: snmp_gen_info()} |
                           {invalid_sec_info, SecInfo :: term(), SnmpInfo :: snmp_gen_info()} |
                           {failed_processing_message,
                            {securityError, SecurityError :: atom(), Info :: proplists:proplist()}} |
                           {empty_message,
                            TransportDomain :: atom(),
                            {Addr :: ip_address(), Port :: port_number()}} |
                           term(),
                       UserData :: term()) ->
                          snmp:void().

This function is called when the manager needs to communicate an "asynchronous" error to the user: e.g. failure to send an asynchronous message (i.e. encoding error), a received message was discarded due to security error, the manager failed to generate a response message to a received inform-request, or when receiving an unexpected PDU from an agent (could be an expired async request).

If ReqId is less then 0, it means that this information was not available to the manager (that info was never retrieved before the message was discarded).

For SnmpInfo see handle_agent below.

When Reason is {failed_processing_message, {securityError, SecurityError, Opts}}, the Opts proplist may contain a sec_data entry with USM security parameters from the received message. In particular, when SecurityError is usmStatsUnknownEngineIDs, the sec_data proplist contains msgAuthoritativeEngineID and msgUserName, which can be used for SNMPv3 USM EngineID discovery (RFC 3414, Section 4).

Note that there is a special case when the value of ReqId has the value of the atom netif. This means that the NetIF process has suffered a "fatal" error and been restarted. With possible loss of traffic!

handle_inform(TargetName, SnmpInform, UserData)

-callback handle_inform(TargetName :: snmpm:target_name(),
                        SnmpInform :: snmp_gen_info(),
                        UserData :: term()) ->
                           Reply ::
                               ignore | no_reply | unregister |
                               {register,
                                UserId :: term(),
                                RTargetName :: snmpm:target_name(),
                                AgentConfig :: [snmpm:agent_config()]}.

Handle a inform message.

For more info about the agent_config(), see snmpm:register_agent/3.

The only user which would return {register, UserId, TargetName2, AgentConfig} is the default user.

If the inform request behaviour configuration option is set to user or {user, integer()}, the response (acknowledgment) to this inform-request will be sent when this function returns.

handle_invalid_result(In, Out)

(since OTP R16B03) (optional)

-callback handle_invalid_result(In, Out) -> no_return()
                                   when
                                       In :: {Fun :: atom(), Args :: list()},
                                       Out :: {crash, CrashInfo} | {result, InvalidResult :: term()},
                                       CrashInfo ::
                                           {ErrorType :: atom(),
                                            Error :: term(),
                                            Stacktrace :: erlang:stacktrace()}.

If any of the other callback functions crashes (exit, throw or a plain crash) or return an invalid result (if a valid return has been specified), this function is called. The purpose is to allow the user handle this error (for instance to issue an error report).

IN reprecents the function called (and its arguments). OUT represents the unexpected/invalid result.

handle_pdu(TargetName, ReqId, SnmpResponse, UserData)

-callback handle_pdu(TargetName :: snmpm:target_name(),
                     ReqId :: term(),
                     SnmpResponse :: snmp_gen_info(),
                     UserData :: term()) ->
                        snmp:void().

Handle the reply to an asynchronous request, such as async_get, async_get_next or async_set.

It could also be a late reply to a synchronous request.

ReqId is returned by the asynchronous request function.

handle_report(TargetName, SnmpReport, UserData)

-callback handle_report(TargetName :: snmpm:target_name(),
                        SnmpReport :: snmp_gen_info(),
                        UserData :: term()) ->
                           Reply ::
                               ignore | unregister |
                               {register,
                                UserId :: term(),
                                RTargetName :: snmpm:target_name(),
                                AgentConfig :: [snmpm:agent_config()]}.

Handle a report message.

For more info about the agent_config(), see snmpm:register_agent/3.

The only user which would return {register, UserId, TargetName2, AgentConfig} is the default user.

handle_trap(TargetName, SnmpTrapInfo, UserData)

-callback handle_trap(TargetName :: snmpm:target_name(),
                      SnmpTrapInfo :: snmp_gen_info() | snmp_v1_trap_info(),
                      UserData :: term()) ->
                         Reply ::
                             ignore | unregister |
                             {register,
                              UserId :: term(),
                              RTargetName :: snmpm:target_name(),
                              AgentConfig :: [snmpm:agent_config()]}.

Handle a trap/notification message from an agent.

For more info about the agent_config(), see snmpm:register_agent/3.

The only user which would return {register, UserId, TargetName2, agent_info()} is the default user.