> ## 10 Definition of Net if

> The Purpose of Net if

> The Network Interface (Net if) process delivers SNMP PDUs to a master agent, and receives SNMP PDUs from the master agent. The most common behaviour of a Net if process is that is receives bytes from a network, decodes them into an SNMP PDU, which it sends to a master agent. When the master agent has processed the PDU, it sends a response PDU to the Net if process, which encodes the PDU into bytes and transmits the bytes onto the network.

> However, that simple behaviour can be modified in numerous ways. For example, the Net if process can apply some kind of encrypting/decrypting scheme on the bytes or act as a proxy filter, which sends some packets to a proxy agent and some packets to the master agent.

> It is also possible to write your own Net if process. The default Net if process is implemented in the module `snmp_net_if` and it uses UDP as the transport protocol.

> This section describes how to write a Net if process.

> ### 10.1 Mandatory Functions

> A Net if process must be implemented in a module that exports the `Module:start_link/2` function, which starts a new Net if process. The name of the Net if module is passed as a start argument to the `snmp_agent` process.

> #### 10.1.1 Function

> `Module:start_link(MasterAgent,Args)`

> #### 10.1.2 Arguments

> `MasterAgent` -> is a Pid.

> `Args` is a a list of arguments:

> -     {net_if_verbosity,silence|info|log|debug|trace}

>   A description of verbosity can be found here and here

> -     {net_if_recbuf,integer()}

>   The size to be used for the UDP receive buffer.

> #### 10.1.3 Return values

> The return values are:

> - `{ok, Pid}`, where Pid is a linked Pid of the Net if process.
> - `{error, Reason}` if the operation fails.

> ### 10.2 Messages

> The section Messages describes mandatory messages, which Net if must send and be able to receive.

> #### 10.2.1 Outgoing Messages

> Net if must send the following message when it receives an SNMP PDU from the network that is aimed for the MasterAgent:

>     MasterAgent ! {snmp_pdu, Vsn, Pdu, PduMS, ACMData, From, Extra}

> - `Vsn` is either `'version-1'`, `'version-2'`, or `'version-3'`.
> - `Pdu` is an SNMP PDU record, as defined in `snmp_types.hrl`, with the SNMP request.
> - `PduMS` is the Maximum Size of the response Pdu allowed. Normally this is returned from `snmp_mpd:process_packet` (see Reference Manual).
> - `ACMData` is data used by the Access Control Module in use. Normally this is returned from `snmp_mpd:process_packet` (see Reference Manual).
> - `From` is the source address. If UDP over IP is used, this should be a 2-tuple `{IP, UDPport}`, where `IP` is a 4-tuple with the IP address, and `UDPport` is an integer.
> - `Extra` is any term the Net if process wishes to send to the agent. This term can be retrieved by the instrumentation functions by calling `snmp:current_net_if_data()`. This data is also sent back to the Net if process when the agent generates a response to the request.

> The following message is used to report that a response to a request has been received. The only request an agent can send is an Inform-Request.

>     Pid ! {snmp_response_received, Vsn, Pdu, From}

> - `Pid` is the Process that waits for the response for the request. The Pid was specified in the `send_pdu_req` message (see below).
> - `Vsn` is either `'version-1'`, `'version-2'`, or `'version-3'`.
> - `Pdu` is the SNMP Pdu received
> - `From` is the source address. If UDP over IP is used, this should be a 2-tuple `{IP, UDPport}`, where `IP` is a 4-tuple with the IP address, and `UDPport` is an integer.

> #### 10.2.2 Incoming Messages

> This section describes the incoming messages which a Net if process must be able to receive.

> - `{snmp_response, Vsn, Pdu, Type, ACMData, To, Extra}` This message is sent to the Net if process from a master agent as a response to a previously received request.
>   - `Vsn` is either `'version-1'`, `'version-2'`, or `'version-3'`.
>   - `Pdu` is an SNMP PDU record (as defined in snmp_types.hrl) with the SNMP response.
>   - `Type` is the `#pdu.type` of the original request.
>   - `ACMData` is data used by the Access Control Module in use. Normally this is just sent to `snmp_mpd:generate_response_message` (see Reference Manual).
>   - `To` is the destination address. If UDP over IP is used, this should be a 2-tuple `{IP, UDPport}`, where `IP` is a 4-tuple with the IP address, and `UDPport` is an integer.
>   - `Extra` is the term that the Net if process sent to the agent when the request was sent to the agent.
> - `{discarded_pdu, Vsn, ReqId, ACMData, Variable, Extra}` This message is sent from a master agent if it for some reason decided to discard the pdu.
>   - `Vsn` is either `'version-1'`, `'version-2'`, or `'version-3'`.
>   - `ReqId` is the request id of the original request.
>   - `ACMData` is data used by the Access Control Module in use. Normally this is just sent to `snmp_mpd:generate_response_message` (see Reference Manual).
>   - `Variable` is the name of an snmp counter that represents the error, e.g. `snmpInBadCommunityUses`.
>   - `Extra` is the term that the Net if process sent to the agent when the request was sent to the agent.
> - `{send_pdu, Vsn, Pdu, MsgData, To}` This message is sent from a master agent when a trap is to be sent.
>   - `Vsn` is either `'version-1'`, `'version-2'`, or `'version-3'`.
>   - `Pdu` is an SNMP PDU record (as defined in snmp_types.hrl) with the SNMP response.
>   - `MsgData` is the message specific data used in the SNMP message. This value is normally sent to `snmp_mpd:generate_message/4`. In SNMPv1 and SNMPv2c, this message data is the community string. In SNMPv3, it is the context information.
>   - `To` is a list of the destination addresses and their corresponding security parameters. This value is normally sent to `snmp_mpd:generate_message/4`.
> - `{send_pdu_req, Vsn, Pdu, MsgData, To, Pid}` This message is sent from a master agent when a request is to be sent. The only request an agent can send is Inform-Request. The net if process needs to remember the request id and the Pid, and when a response is received for the request id, send it to Pid, using a `snmp_response_received` message.
>   - `Vsn` is either `'version-1'`, `'version-2'`, or `'version-3'`.
>   - `Pdu` is an SNMP PDU record (as defined in snmp_types.hrl) with the SNMP response.
>   - `MsgData` is the message specific data used in the SNMP message. This value is normally sent to `snmp_mpd:generate_message/4`. In SNMPv1 and SNMPv2c, this message data is the community string. In SNMPv3, it is the context information.
>   - `To` is a list of the destination addresses and their corresponding security parameters. This value is normally sent to `snmp_mpd:generate_message/4`.
>   - `Pid` is a process identifier.

> #### 10.2.3 Notes

> Since the Net if process is responsible for encoding and decoding of SNMP messages, it must also update the relevant counters in the SNMP group in MIB-II. It can use the functions in the module `snmp_mpd` for this purpose (refer to the Reference Manual, section `snmp`, module `snmp_mpd` for more details.)

> There are also some useful functions for encoding and decoding of SNMP messages in the module `snmp_pdus`.

Copyright © 1991-2003 Ericsson Utvecklings AB