Network Working Group G. Carpenter Request for Comments: 1228 B. Wijnen T.J. Watson Research Center, IBM Corp. May 1991 SNMP-DPI Simple Network Management Protocol Distributed Program Interface Status of this Memo This RFC describes a protocol that International Business Machines Corporation (IBM) has been implementing in most of its SNMP agents to allow dynamic extension of supported MIBs. This is an Experimental Protocol for the Internet community. Discussion and suggestions for improvement are requested. Please refer to the current edition of the "IAB Official Protocol Standards" for the standardization state and status of this protocol. Distribution of this memo is unlimited. ABSTRACT The Simple Network Management Protocol (SNMP) [1] Distributed Program Interface (DPI) is an extension to SNMP agents that permits end-users to dynamically add, delete or replace management variables in the local Management Information Base without requiring recompilation of the SNMP agent. This is achieved by writing a so-called sub-agent that communicates with the agent via the SNMP-DPI. For the author of a sub-agent, the SNMP-DPI eliminates the need to know the details of ASN.1 [2] or SNMP PDU (Protocol Data Unit) encoding/decoding [1, 3]. This protocol has been in use within IBM since 1989 and is included in the SNMP agents for VM, MVS and OS/2. Potentially useful sample sub-agent code and implementation examples are available for anonymous FTP from the University of Toronto. MOTIVATION The Simple Network Management Protocol [1] defines a protocol that permits operations on a collection of variables. This set of variables is called the Management Information Base (MIB) and a core set of variables has previously been defined [4, 5]; however, the design of the MIB makes provision for extension of this core set. Thus, an enterprise or individual can define variables of their own which represent information of use to them. An example of a Carpenter & Wijnen [Page 1] RFC 1228 SNMP-DPI May 1991 potentially interesting variable which is not in the core MIB would be CPU utilization (percent busy). Unfortunately, conventional SNMP agent implementations provide no means for an end-user to make available new variables. The SNMP DPI addresses this issue by providing a light-weight mechanism by which a process can register the existence of a MIB variable with the SNMP agent. When requests for the variable are received by the SNMP agent, it will pass the query on to the process acting as a sub-agent. This sub-agent then returns an appropriate answer to the SNMP agent. The SNMP agent eventually packages an SNMP response packet and sends the answer back to the remote network management station that initiated the request. None of the remote network management stations have any knowledge that the SNMP agent calls on other processes to obtain an answer. As far as they can tell, there is only one network management application running on the host. THEORY OF OPERATION CONNECTION ESTABLISHMENT Communication between the SNMP Agent and its clients (sub-agents) takes place over a stream connection. This is typically a TCP connection, but other stream-oriented transport mechanisms can be used. As an example, the VM SNMP agent allows DPI connections over IUCV (Inter-User Communications Vehicle) [6, 7]. Other than the connection establishment procedure, the protocol used is identical in these environments. REGISTRATION Regardless of the connection-oriented transport mechanism used, after establishing a connection to the SNMP agent, the sub-agent registers the set of variables it supports. Finally, when all the variable classes have been registered, the sub-agent then waits for requests from the SNMP agent or generates traps as required. DPI ARCHITECTURE There are three requests that can be initiated by the SNMP agent: GET, GET-NEXT and SET. These correspond directly to the three SNMP requests that a network management station can make. The sub-agent responds to a request with a RESPONSE packet. There are currently two requests that can be initiated by a sub- agent: REGISTER and TRAP. Carpenter & Wijnen [Page 2] RFC 1228 SNMP-DPI May 1991 ------------------------------------------------------------------------ *---------------------------------* | SNMP Network | | Management Station | | | |---------------------------------| | SNMP Protocol | *---------------------------------* A | Get A | | GetNext | GetResponse Trap | | Set | | V | *---------------------------------* *----------------------* | SNMP Protocol | | DPI Interface | |---------------------------------| Reply | *-----------------| | | |<-----------| | | | SNMP Agent | | | | Client | | A *-----------+-> | MIB query | | | | | | Get/Set | |----------->| | or | | Trap| | info | SNMP | | | | |-----+------+-------* | | trap | | SNMP | | | V | | DPI |<-----------| | Sub-Agent | | TCP/IP layers, | | | | | | | Kernel | | |<-----------| | | *---------------------------------* Register *----------------------* ------------------------------------------------------------------------ Figure 1. SNMP DPI overview Remarks for Figure 1: o The SNMP agent communicates with the SNMP manager via the standard SNMP protocol. o The SNMP agent communicates with the TCP/IP layers and kernel (operating system) in an implementation-dependent manner. It potentially implements the standard MIB view in this way. o An SNMP sub-agent, running as a separate process (potentially even on another machine), can register objects with the SNMP agent. o The SNMP agent will decode SNMP Packets. If such a packet contains a Get/GetNext or Set request for an object registered by a sub-agent, it will send the request to the sub-agent via the corresponding query packet. o The SNMP sub-agent sends responses back via a RESPONSE packet. o The SNMP agent then encodes the reply into an SNMP packet and sends it back to the requesting SNMP manager. o If the sub-agent wants to report an important state change, it Carpenter & Wijnen [Page 3] RFC 1228 SNMP-DPI May 1991 sends a TRAP packet to the SNMP agent, which will encode it into an SNMP trap packet and send it to the manager(s). SNMP DPI PROTOCOL This section describes the actual protocol used between the SNMP agent and sub-agents. This information has not previously been published. CONNECTION ESTABLISHMENT In a TCP/IP environment, the SNMP agent listens on an arbitrary TCP port for a connection request from a sub-agent. It is important to realize that a well-known port is not used: every invocation of the SNMP agent will potentially result in a different TCP port being used. A sub-agent needs to determine this port number to establish a connection. The sub-agent learns the port number from the agent by sending it one conventional SNMP get-request PDU. The port number is maintained by the SNMP agent as the object whose identifier is 1.3.6.1.4.1.2.2.1.1.0; this variable is registered under the IBM enterprise-specific tree. The SNMP agent replies with a conventional SNMP response PDU that contains the port number to be used. This response is examined by the sub-agent and the port number is extracted. The sub-agent then establishes the connection to the specified port. On the surface, this procedure appears to mean that the sub-agent must be able to create and parse SNMP packets, but this is not the case. The DPI Application Program Interface (API) has a library routine, query_DPI_port(), which can be used to generate and parse the required SNMP packets. This routine is very small (under 100 lines of C), so it does not greatly increase the size of any sub- agent). For completeness, byte-by-byte descriptions of the packets generated by the SNMP DPI API routine query_DPI_port() are provided below. This is probably of little interest to most readers and reading the source to query_DPI_port() provides much of the same information. SNMP PDU TO GET THE AGENT'S DPI PORT As noted, before a TCP connection to the SNMP agent can be made, the sub-agent must learn which TCP port that the agent is listening on. To do so, it can issue an SNMP GET for an IBM enterprise-specific variable 1.3.6.1.4.1.2.2.1.1.0. Carpenter & Wijnen [Page 4] RFC 1228 SNMP-DPI May 1991 NOTE: the object instance of ".0" is included for clarity in this document. The SNMP PDU can be constructed as shown below. This PDU must be sent to UDP port 161 on the host where the agent runs (probably the same host where the sub-agent runs). Carpenter & Wijnen [Page 5] RFC 1228 SNMP-DPI May 1991 +----------------------------------------------------------------------+ | Table 1. SNMP PDU for GET DPI_port. This is the layout of an SNMP | | PDU for GET DPI_port | +-----------------+-----------------+----------------------------------+ | OFFSET | VALUE | FIELD | +-----------------+-----------------+----------------------------------+ | 0 | 0x30 | ASN.1 header | +-----------------+-----------------+----------------------------------+ | 1 | 34 + len | pdu_length, see formula below | +-----------------+-----------------+----------------------------------+ | 2 | 0x02 0x01 0x00 | version (integer, length=1, | | | 0x04 | value=0), community name | | | | (string) | +-----------------+-----------------+----------------------------------+ | 6 | len | length of community name | +-----------------+-----------------+----------------------------------+ | 7 | community name | | +-----------------+-----------------+----------------------------------+ | 7 + len | 0xa0 0x1b | SNMP GET request: | | | | request_type=0xa0, length=0x1b | +-----------------+-----------------+----------------------------------+ | 7 + len + 2 | 0x02 0x01 0x01 | SNMP request ID: integer, | | | | length=1, ID=1 | +-----------------+-----------------+----------------------------------+ | 7 + len + 5 | 0x02 0x01 0x00 | SNMP error status: integer, | | | | length=1, error=0 | +-----------------+-----------------+----------------------------------+ | 7 + len + 8 | 0x02 0x01 0x00 | SNMP index: integer, length=1, | | | | index=0 | +-----------------+-----------------+----------------------------------+ | 7 + len + 11 | 0x30 0x10 | Varbind list, length=0x10 | +-----------------+-----------------+----------------------------------+ | 7 + len + 13 | 0x30 0x0e | Varbind, length=0x0e | +-----------------+-----------------+----------------------------------+ | 7 + len + 15 | 0x06 0x0a | Object ID, length=0x0a | +-----------------+-----------------+----------------------------------+ | 7 + len + 17 | 0x2b 0x06 0x01 | Object instance: | | | 0x04 0x01 0x02 | 1.3.6.1.4.1.2.2.1.1.0 | | | 0x02 0x01 0x01 | | | | 0x00 | | +-----------------+-----------------+----------------------------------+ | 7 + len + 27 | 0x05 0x00 | null value, length=0 | +-----------------+-----------------+----------------------------------+ +----------------------------------------------------------------------+ The formula to calculate the length field "pdu_length" is as follows: pdu_length = length of version field and string tag (4 bytes) Carpenter & Wijnen [Page 6] RFC 1228 SNMP-DPI May 1991 + length of community length field (1 byte) + length of community name (depends...) + length of SNMP GET request (29 bytes) = 34 + length of community name Carpenter & Wijnen [Page 7] RFC 1228 SNMP-DPI May 1991 SNMP PDU CONTAINING THE RESPONSE TO THE GET Assuming that no errors occured, then the port is returned in the last 2 octets of the received packet. The format of the packet is shown below: +----------------------------------------------------------------------+ | Table 2. SNMP RESPONSE PDU for GET of Agent's DPI port. This is the | | layout of an SNMP RESPONSE PDU for GET DPI_port | +-----------------+-----------------+----------------------------------+ | OFFSET | VALUE | FIELD | +-----------------+-----------------+----------------------------------+ | 0 | 0x30 | ASN.1 header | +-----------------+-----------------+----------------------------------+ | 1 | 36 + len | length, see formula below | +-----------------+-----------------+----------------------------------+ | 2 | 0x02 0x01 0x00 | version (integer, length=1, | | | 0x04 | value=0), community name | | | | (string) | +-----------------+-----------------+----------------------------------+ | 6 | len | length of community name | +-----------------+-----------------+----------------------------------+ | 7 | community name | | +-----------------+-----------------+----------------------------------+ | 7 + len | 0xa2 0x1d | SNMP RESPONSE: | | | | request_type=0xa2, length=0x1d | +-----------------+-----------------+----------------------------------+ | 7 + len + 2 | 0x02 0x01 0x01 | SNMP request ID: integer, | | | | length=1, ID=1 | +-----------------+-----------------+----------------------------------+ | 7 + len + 5 | 0x02 0x01 0x00 | SNMP error status: integer, | | | | length=1, error=0 | +-----------------+-----------------+---------