snmpa_mpd — snmp v5.16

Search documentation of snmp

# View Source snmpa_mpd (snmp v5.16)

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

Link to this type

# acm_data()

View Source

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

Link to this opaque

# acm_data_cmy()

View Source

    -opaque acm_data_cmy()

This is the message specific data used in the SNMPv1 and SNMPv2c message.

Link to this opaque

# acm_data_v3()

View Source

    -opaque acm_data_v3()

This is the message specific data used in the SNMPv3 message.

Link to this type

# logger()

View Source

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

Link to this opaque

# mpd_state()

View Source

    -opaque mpd_state()

Link to this type

# msg_data()

View Source

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

Link to this opaque

# msg_data_cmy()

View Source

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

Link to this opaque

# msg_data_ctx()

View Source

    -opaque msg_data_ctx()

This is the message specific data used in the SNMP message. In SNMPv3, it is the context information.

# Functions

Link to this function

# discarded_pdu(Variable)

View Source

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

Link to this function

# generate_msg(Vsn, NoteStore, Pdu, MsgData, To)

View Source (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`.

Link to this function

# generate_msg(Vsn, NoteStore, Pdu, MsgData, LocalEngineID, To)

View Source (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).

Link to this function

# generate_response_msg(Vsn, RePdu, Type, ACMData, Log)

View Source (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`.

Link to this function

# generate_response_msg(Vsn, RePdu, Type, ACMData, LocalEngineID, Log)

View Source (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).

Link to this function

# init(Vsns)

View Source

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

Link to this function

# process_packet(Packet, From, State, NoteStore, Log)

View Source (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`.

Link to this function

# process_packet/6

View Source (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).

Link to this function

# process_taddrs(InDests)

View Source (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`.