snmp(3)

MODULE
snmp - Interface Functions to the SNMP toolkit

DESCRIPTION

The module snmp contains interface functions to the SNMP toolkit. Some functions are off-line functions (e.g. c to compile a MIB), and some are functions called by instrumentation functions in a target system (e.g. current_address).

Common Data Types

The following datatypes are used in the functions below:

    *   oid() = [byte()]

The oid() type is used to represent an ASN.1 OBJECT IDENTIFIER.

EXPORTS

add_agent_caps(SysORID, SysORDescr) -> SysORIndex

    Types
        SysORID = oid()
        SysORDescr = string()
        SysORIndex = 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.

c(File)
c(File,Options) -> {ok, BinFileName} | {error, Reason}

    Types
        File = string()
        Options = [opt()]
        opt() = {db, volatile|persistent|mnesia} | {i, [dir()]} | {il, [dir()]} | {outdir, dir()} | {warnings, bool()} | {group_check, bool()} | {deprecated, bool()} | {description, bool()} | {verbosity, silence|warning|info|log|debug|trace}
        dir() = string()
        BinFileName = string()

    Compiles the specified MIB file <File>.mib. The compiled file BinFileName is called <File>.bin.

        *   The option db specifies which database should be used for the default instrumentation. Default is volatile.

        *   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 warnings specifies whether warning messages should be shown. Default is true.

        *   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 group_check specifies whether the mib compiler should check the OBJECT-GROUP macro for correctness or not. Default is true.

        *   The option deprecated specifies if a deprecated definition should be ignored or not. If the option is true will the MIB-compilator ignore all deprecated definitions. Default is false.

        *   The option description specifies if the text of the DESCRIPTION field will be included or not. Default is false, in which case the description will be replaced by the atom undefined.

    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 be invoked from the OS command line by using the command erlc. erlc recognises the extension .mib, and invokes the SNMP MIB compiler for files with that extension. The options db, group_check and deprecated have to be specified to erlc using the syntax +term. See erlc(1) for details.

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

    Types
        NewSize = {MaxBytes, MaxFiles}
        MaxBytes = integer()
        MaxFiles = integer()

    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 remebered across reboots.

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

    A simple interactive SNMP agent 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.

current_address() -> {value, {IP, UDP}} | false

    Types
        IP = [int(), int(), int(), int()]
        UDP = int()

    Retrieves the IP address of the management station sending the request. It must be called from the same process that is handling the request (normally an instrumentation function).

    Returns false if no request is currently handled.

current_community() -> {value, Community} | false

    Types
        Community = string()

    Retrieves the community referred to in the current request. It must be called from the same process that is handling the request (normally an instrumentation function).

    Returns false if no request is currently handled.

    NOTE: This function should only be used if the agent speaks SNMPv1 or SNMPv2c only. Otherwise, use current_context/0.

current_context() -> {value, ContextName} | false

    Types
        ContextName = string()

    Retrieves the context referred to in the current request. It must be called from the same process that is handling the request (normally an instrumentation function).

    Returns false if no request is currently handled.

current_net_if_data() -> {value, NetIfData} | false

    Types
        NetIfData = term()

    Retrieves the Net_if data for the current pdu being handled. This data is defined in the Net_if process, and can be used to forward information about the packet to the instrumentation functions. With the default Net_if implementation, it is nil. It must be called from the same process that handles the request (normally an instrumentation function).

    Returns false if no request is currently handled.

current_request_id() -> {value, RequestId} | false

    Types
        RequestId = int()

    Retrieves the request Id of the current request. It must be called from the same process that is handling the request (normally an instrumentation function).

    Returns false if no request is currently handled.

date_and_time() -> DateAndTime

    Types
        DateAndTime = [int()]

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

date_and_time_to_universal_time(DateAndTime) -> UTC

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

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

date_and_time_to_string(DateAndTime) -> string()

    Types
        DateAndTime = [int()]

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

debug(Agent,Bool) -> void()

    Types
        Agent = pid() | atom()
        Bool = bool()

    Turns debugging of the agent on/off. Debug information is printed whenever an instrumentation function is called, and when a packet is received or sent. This actually sets verbosity to log or silence for the snmp_master_agent and snmp_net_if.

del_agent_caps(SysORIndex) -> void()

    Types
        SysORIndex = 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.

enum_to_int(Name,Enum) -> {value, Int} | false

    Types
        Name = atom()
        Enum = atom()
        Int = int()

    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.

enum_to_int(Db,Name,Enum) -> {value, Int} | false

    Types
        Db = term()
        Name = atom()
        Enum = atom()
        Int = int()

    Converts the symbolic value Enum to the corresponding integer of the enumerated object or type Name in a MIB. The MIB must be loaded. Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0<c>). <p><c>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.

get(Agent,Vars) -> Values | {error, Reason}

    Types
        Agent = pid() | atom()
        Vars = [oid()]
        Values = [term()]
        Reason = {atom(), oid()}

    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. That the request specific parameters (such as snmp:current_request_id/0 are not accessible for the instrumentation functions if this function is used.

get_agent_caps() -> [[SysORIndex, SysORID, SysORDescr, SysORUpTime]]

    Types
        SysORIndex = integer()
        SysORId = oid()
        SysORDescr = string()
        SysORUpTime = integer()

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

get_symbolic_store_db() -> Db

    Types
        Db = term()

    Retrieve the symbolic store database reference. This is used for faster access to the database using the functions: int_to_enum/3, enum_to_int/3, name_to_oid/2, oid_to_name/2.

info(Agent) -> [{Key, Value}]

    Types
        Agent = pid() | atom()

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

int_to_enum(Name,Int) -> {value, Enum} | false

    Types
        Name = atom()
        Int = int()
        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.

int_to_enum(Db,Name,Int) -> {value, Enum} | false

    Types
        Db = term()
        Name = atom()
        Int = int()
        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. Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0<c>). <p><c>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.

is_consistent(Mibs) -> ok | {error, Reason}

    Types
        Mibs = [MibName]
        MibName = string()

    Checks for multiple usage of object identifiers and traps between MIBs.

load_mibs(Agent,Mibs) -> ok | {error, Reason}

    Types
        Agent = pid() | atom()
        Mibs = [MibName]
        MibName = string()

    Loads Mibs into an agent. If the agent cannot load all MIBs, 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/",
              snmp:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).

local_time_to_date_and_time(Local) -> DateAndTime

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

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

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

    Types
        LogDir = string()
        Mibs = [MibName]
        OutFile = string()
        MibName = string()
        LogName = string()
        LogFile = string()
        Start = Stop = null | datetime() | {local_time, datetime()} | {universal_time, datetime()}

    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 textfile. It defaults to "./snmp_log.txt". LogName is the name of the log (default is "snmp log"), LogFile is the name of the log file (default is "snmp.log"). 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 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.

mib_to_hrl(MibName) -> ok | {error, Reason}

    Types
        MibName = string()

    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 recognises the extension .bin, and invokes this function for files with that extension.

name_to_oid(Name) -> {value, oid()} | false

    Types
        Name = atom()

    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.

name_to_oid(Db,Name) -> {value, oid()} | false

    Types
        Db = term()
        Name = atom()

    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. Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0<c>). <p><c>false is returned if the object is not defined in any loaded MIB.

oid_to_name(OID) -> {value, Name} | false

    Types
        OID = 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.

oid_to_name(Db,OID) -> {value, Name} | false

    Types
        Db = term()
        OID = oid()
        Name = atom()

    Looks up the symbolic name of a MIB object, given OBJECT IDENTIFIER. Db is a reference to the symbolic store database (retrieved by a call to get_symbolic_store_db/0<c>). <p><c>false is returned if the object is not defined in any loaded MIB.

register_subagent(Agent,SubTreeOid,Subagent) -> ok | {error, Reason}

    Types
        Agent = pid() | atom()
        SubTreeOid = oid()
        SubAgent = pid()

    Registers a subagent under a subtree of another agent.

    It is easy to make mistakes when registering subagents 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.

send_notification(Agent,Notification,Receiver)
send_notification(Agent,Notification,Receiver,Varbinds)
send_notification(Agent,Notification,Receiver, NotifyName,Varbinds)
send_notification(Agent,Notification,Receiver, NotifyName,ContextName,Varbinds) -> void()

    Types
        Agent = pid() | atom()
        Notification = atom()
        Receiver = no_receiver | {Tag, Recv}
        Tag = term()
        Recv = pid() | atom() | {M, F, A}
        NotifyName = string()
        ContextName = string()
        Varbinds = [Varbind]
        Varbind = {Variable, Value} | {Column, RowIndex, Value} | {OID, Value}
        Variable = atom()
        Column = atom()
        OID = oid()
        Value = term()
        RowIndex = [int()]

    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. 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 acknowledgements from the managers. If the Receiver is specified as no_receiver, nothing is sent. Otherwise, it is specified as {Tag, Recv}. The receiver (Recv) gets a message:

        *   {snmp_targets, Tag, Addresses}

    Addresses is a list of management target addresses. If UDP over IP is used, this is a 2-tuple {IP, UDPport}, where IP is a 4-tuple with the IP address, and UDPport is an integer. The notification is sent as an Inform-Request to each target address in Addresses. If there are no targets for which an Inform-Request is sent, Addresses is the empty list [].

    For each such Address is the Addresses list, one of the following two messages is sent to Recv:

        *   {snmp_notification, Tag, {got_response, Address}}

        *   {snmp_notification, Tag, {no_response, Address}}

    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.

send_trap(Agent,Trap,Community)
send_trap(Agent,Trap,Community,Varbinds) -> void()

    Types
        Agent = pid() | atom()
        Trap = atom()
        Community = string()
        Varbinds = [Varbind]
        Varbind = {Variable, Value} | {Column, RowIndex, Value} | {OID, Value}
        Variable = atom()
        Column = atom()
        OID = oid()
        Value = term()
        RowIndex = [int()]

    Note! This function is only kept for backwards compatibility reasons. Use send_notification instead.

    Sends the trap Trap to the managers defined for Community in the intTrapDestTable in OTP-SNMPEA-MIB. The optional argument Varbinds defines values for the objects in the trap. 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 trap 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 trap 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 trap, 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 trap 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 trap 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, snmp_error:user_err/2 is called and the trap is discarded.

universal_time_to_date_and_time(UTC) -> DateAndTime

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

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

unload_mibs(Agent,Mibs) -> ok | {error, Reason}

    Types
        Agent = pid() | atom()
        Mibs = [MibName]
        MibName = string()

    Unloads MIBs into an agent. If it cannot unload all MIBs, it will indicate where unloading was aborted.

unregister_subagent(Agent,SubagentOidOrPid) -> ok | {ok, SubAgentPid} | {error, Reason}

    Types
        Agent = pid() | atom()
        SubTreeOidorPid = oid() | pid()

    Unregisters a subagent. If the second argument is a pid, then that subagent will be unregistered from all trees in Agent.

validate_date_and_time(DateAndTime) bool()

    Types
        DateAndTime = term()

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

verbosity(Ref,Verbosity) -> void()

    Types
        Ref = pid() | snmp_master_agent | snmp_net_if | snmp_mib | snmp_symbolic_store | snmp_note_store | snmp_local_db
        Verbosity = silence | info | log | debug | trace

    Sets verbosity for the designated process. For the lowest verbosity silence, nothing is printed. The higher the verbosity, the more is printed.

See Also

calendar(3), erlc(1)

AUTHORS
Martin Bjorklund - support@erlang.ericsson.se
Klas Eriksson - support@erlang.ericsson.se