home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl502b.zip / ext / DPI / DOC / rfc1228.txt < prev    next >
Text File  |  1991-05-23  |  94KB  |  2,803 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                       G. Carpenter
  8. Request for Comments: 1228                                     B. Wijnen
  9.                                   T.J. Watson Research Center, IBM Corp.
  10.                                                                 May 1991
  11.  
  12.  
  13.                                 SNMP-DPI
  14.                    Simple Network Management Protocol
  15.                      Distributed Program Interface
  16.  
  17. Status of this Memo
  18.  
  19.    This RFC describes a protocol that International Business Machines
  20.    Corporation (IBM) has been implementing in most of its SNMP agents to
  21.    allow dynamic extension of supported MIBs.  This is an Experimental
  22.    Protocol for the Internet community.  Discussion and suggestions for
  23.    improvement are requested.  Please refer to the current edition of
  24.    the "IAB Official Protocol Standards" for the standardization state
  25.    and status of this protocol.  Distribution of this memo is unlimited.
  26.  
  27. ABSTRACT
  28.  
  29.    The Simple Network Management Protocol (SNMP) [1] Distributed Program
  30.    Interface (DPI) is an extension to SNMP agents that permits end-users
  31.    to dynamically add, delete or replace management variables in the
  32.    local Management Information Base without requiring recompilation of
  33.    the SNMP agent.  This is achieved by writing a so-called sub-agent
  34.    that communicates with the agent via the SNMP-DPI.
  35.  
  36.    For the author of a sub-agent, the SNMP-DPI eliminates the need to
  37.    know the details of ASN.1 [2] or SNMP PDU (Protocol Data Unit)
  38.    encoding/decoding [1, 3].
  39.  
  40.    This protocol has been in use within IBM since 1989 and is included
  41.    in the SNMP agents for VM, MVS and OS/2.
  42.  
  43.    Potentially useful sample sub-agent code and implementation examples
  44.    are available for anonymous FTP from the University of Toronto.
  45.  
  46. MOTIVATION
  47.  
  48.    The Simple Network Management Protocol [1] defines a protocol that
  49.    permits operations on a collection of variables.  This set of
  50.    variables is called the Management Information Base (MIB) and a core
  51.    set of variables has previously been defined [4, 5]; however, the
  52.    design of the MIB makes provision for extension of this core set.
  53.    Thus, an enterprise or individual can define variables of their own
  54.    which represent information of use to them.  An example of a
  55.  
  56.  
  57.  
  58. Carpenter & Wijnen                                              [Page 1]
  59.  
  60. RFC 1228                        SNMP-DPI                        May 1991
  61.  
  62.  
  63.    potentially interesting variable which is not in the core MIB would
  64.    be CPU utilization (percent busy).  Unfortunately, conventional SNMP
  65.    agent implementations provide no means for an end-user to make
  66.    available new variables.
  67.  
  68.    The SNMP DPI addresses this issue by providing a light-weight
  69.    mechanism by which a process can register the existence of a MIB
  70.    variable with the SNMP agent.  When requests for the variable are
  71.    received by the SNMP agent, it will pass the query on to the process
  72.    acting as a sub-agent.  This sub-agent then returns an appropriate
  73.    answer to the SNMP agent.  The SNMP agent eventually packages an SNMP
  74.    response packet and sends the answer back to the remote network
  75.    management station that initiated the request.
  76.  
  77.    None of the remote network management stations have any knowledge
  78.    that the SNMP agent calls on other processes to obtain an answer.  As
  79.    far as they can tell, there is only one network management
  80.    application running on the host.
  81.  
  82. THEORY OF OPERATION
  83.  
  84. CONNECTION ESTABLISHMENT
  85.  
  86.    Communication between the SNMP Agent and its clients (sub-agents)
  87.    takes place over a stream connection.  This is typically a TCP
  88.    connection, but other stream-oriented transport mechanisms can be
  89.    used.  As an example, the VM SNMP agent allows DPI connections over
  90.    IUCV (Inter-User Communications Vehicle) [6, 7].  Other than the
  91.    connection establishment procedure, the protocol used is identical in
  92.    these environments.
  93.  
  94. REGISTRATION
  95.  
  96.    Regardless of the connection-oriented transport mechanism used, after
  97.    establishing a connection to the SNMP agent, the sub-agent registers
  98.    the set of variables it supports.  Finally, when all the variable
  99.    classes have been registered, the sub-agent then waits for requests
  100.    from the SNMP agent or generates traps as required.
  101.  
  102. DPI ARCHITECTURE
  103.  
  104.    There are three requests that can be initiated by the SNMP agent:
  105.    GET, GET-NEXT and SET.  These correspond directly to the three SNMP
  106.    requests that a network management station can make.  The sub-agent
  107.    responds to a request with a RESPONSE packet.
  108.  
  109.    There are currently two requests that can be initiated by a sub-
  110.    agent: REGISTER and TRAP.
  111.  
  112.  
  113.  
  114. Carpenter & Wijnen                                              [Page 2]
  115.  
  116. RFC 1228                        SNMP-DPI                        May 1991
  117.  
  118.  
  119. ------------------------------------------------------------------------
  120.  
  121. *---------------------------------*
  122. |  SNMP Network                   |
  123. |  Management Station             |
  124. |                                 |
  125. |---------------------------------|
  126. |  SNMP Protocol                  |
  127. *---------------------------------*
  128.       A      | Get         A
  129.       |      | GetNext     |  GetResponse
  130.  Trap |      | Set         |
  131.       |      V             |
  132. *---------------------------------*            *----------------------*
  133. |     SNMP Protocol               |            |   DPI Interface      |
  134. |---------------------------------|  Reply     |    *-----------------|
  135. |                        |        |<-----------|    |                 |
  136. |     SNMP Agent         |        |            |    |   Client        |
  137. |     A      *-----------+->      | MIB query  |    |                 |
  138. |     |      | Get/Set   |        |----------->|    |     or          |
  139. | Trap|      | info      |  SNMP  |            |    |                 |
  140. |-----+------+-------*   |        |  trap      |    |   SNMP          |
  141. |     |      V       |   |  DPI   |<-----------|    |   Sub-Agent     |
  142. | TCP/IP layers,     |   |        |            |    |                 |
  143. | Kernel             |   |        |<-----------|    |                 |
  144. *---------------------------------*  Register  *----------------------*
  145.  
  146. ------------------------------------------------------------------------
  147. Figure 1. SNMP DPI overview
  148.  
  149. Remarks for Figure 1:
  150.  
  151.    o   The SNMP agent communicates with the SNMP manager via the
  152.        standard SNMP protocol.
  153.    o   The SNMP agent communicates with the TCP/IP layers and kernel
  154.        (operating system) in an implementation-dependent manner.  It
  155.        potentially implements the standard MIB view in this way.
  156.    o   An SNMP sub-agent, running as a separate process (potentially
  157.        even on another machine), can register objects with the SNMP
  158.        agent.
  159.    o   The SNMP agent will decode SNMP Packets.  If such a packet
  160.        contains a Get/GetNext or Set request for an object registered
  161.        by a sub-agent, it will send the request to the sub-agent via
  162.        the corresponding query packet.
  163.    o   The SNMP sub-agent sends responses back via a RESPONSE packet.
  164.    o   The SNMP agent then encodes the reply into an SNMP packet and
  165.        sends it back to the requesting SNMP manager.
  166.    o   If the sub-agent wants to report an important state change, it
  167.  
  168.  
  169.  
  170. Carpenter & Wijnen                                              [Page 3]
  171.  
  172. RFC 1228                        SNMP-DPI                        May 1991
  173.  
  174.  
  175.        sends a TRAP packet to the SNMP agent, which will encode it
  176.        into an SNMP trap packet and send it to the manager(s).
  177.  
  178. SNMP DPI PROTOCOL
  179.  
  180.    This section describes the actual protocol used between the SNMP
  181.    agent and sub-agents.  This information has not previously been
  182.    published.
  183.  
  184. CONNECTION ESTABLISHMENT
  185.  
  186.    In a TCP/IP environment, the SNMP agent listens on an arbitrary TCP
  187.    port for a connection request from a sub-agent.  It is important to
  188.    realize that a well-known port is not used:  every invocation of the
  189.    SNMP agent will potentially result in a different TCP port being
  190.    used.
  191.  
  192.    A sub-agent needs to determine this port number to establish a
  193.    connection.  The sub-agent learns the port number from the agent by
  194.    sending it one conventional SNMP get-request PDU.   The port number
  195.    is maintained by the SNMP agent as the object whose identifier is
  196.    1.3.6.1.4.1.2.2.1.1.0; this variable is registered under the IBM
  197.    enterprise-specific tree.  The SNMP agent replies with a conventional
  198.    SNMP response PDU that contains the port number to be used.  This
  199.    response is examined by the sub-agent and the port number is
  200.    extracted.  The sub-agent then establishes the connection to the
  201.    specified port.
  202.  
  203.    On the surface, this procedure appears to mean that the sub-agent
  204.    must be able to create and parse SNMP packets, but this is not the
  205.    case.  The DPI Application Program Interface (API) has a library
  206.    routine, query_DPI_port(), which can be used to generate and parse
  207.    the required SNMP packets.  This routine is very small (under 100
  208.    lines of C), so it does not greatly increase the size of any sub-
  209.    agent).
  210.  
  211.    For completeness, byte-by-byte descriptions of the packets generated
  212.    by the SNMP DPI API routine query_DPI_port() are provided below.
  213.    This is probably of little interest to most readers and reading the
  214.    source to query_DPI_port() provides much of the same information.
  215.  
  216. SNMP PDU TO GET THE AGENT'S DPI PORT
  217.  
  218.    As noted, before a TCP connection to the SNMP agent can be made, the
  219.    sub-agent must learn which TCP port that the agent is listening on.
  220.    To do so, it can issue an SNMP GET for an IBM enterprise-specific
  221.    variable 1.3.6.1.4.1.2.2.1.1.0.
  222.  
  223.  
  224.  
  225.  
  226. Carpenter & Wijnen                                              [Page 4]
  227.  
  228. RFC 1228                        SNMP-DPI                        May 1991
  229.  
  230.  
  231.    NOTE:  the object instance of ".0" is included for clarity in this
  232.    document.
  233.  
  234.    The SNMP PDU can be constructed as shown below.  This PDU must be
  235.    sent to UDP port 161 on the host where the agent runs (probably the
  236.    same host where the sub-agent runs).
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282. Carpenter & Wijnen                                              [Page 5]
  283.  
  284. RFC 1228                        SNMP-DPI                        May 1991
  285.  
  286.  
  287. +----------------------------------------------------------------------+
  288. | Table 1. SNMP PDU for GET DPI_port.  This is the layout of an SNMP   |
  289. |          PDU for GET DPI_port                                        |
  290. +-----------------+-----------------+----------------------------------+
  291. | OFFSET          | VALUE           | FIELD                            |
  292. +-----------------+-----------------+----------------------------------+
  293. | 0               | 0x30            | ASN.1 header                     |
  294. +-----------------+-----------------+----------------------------------+
  295. | 1               | 34 + len        | pdu_length, see formula below    |
  296. +-----------------+-----------------+----------------------------------+
  297. | 2               | 0x02 0x01 0x00  | version (integer, length=1,      |
  298. |                 | 0x04            | value=0), community name         |
  299. |                 |                 | (string)                         |
  300. +-----------------+-----------------+----------------------------------+
  301. | 6               | len             | length of community name         |
  302. +-----------------+-----------------+----------------------------------+
  303. | 7               | community name  |                                  |
  304. +-----------------+-----------------+----------------------------------+
  305. | 7 + len         | 0xa0 0x1b       | SNMP GET request:                |
  306. |                 |                 | request_type=0xa0, length=0x1b   |
  307. +-----------------+-----------------+----------------------------------+
  308. | 7 + len + 2     | 0x02 0x01 0x01  | SNMP request ID: integer,        |
  309. |                 |                 | length=1, ID=1                   |
  310. +-----------------+-----------------+----------------------------------+
  311. | 7 + len + 5     | 0x02 0x01 0x00  | SNMP error status: integer,      |
  312. |                 |                 | length=1, error=0                |
  313. +-----------------+-----------------+----------------------------------+
  314. | 7 + len + 8     | 0x02 0x01 0x00  | SNMP index: integer, length=1,   |
  315. |                 |                 | index=0                          |
  316. +-----------------+-----------------+----------------------------------+
  317. | 7 + len + 11    | 0x30 0x10       | Varbind list, length=0x10        |
  318. +-----------------+-----------------+----------------------------------+
  319. | 7 + len + 13    | 0x30 0x0e       | Varbind, length=0x0e             |
  320. +-----------------+-----------------+----------------------------------+
  321. | 7 + len + 15    | 0x06 0x0a       | Object ID, length=0x0a           |
  322. +-----------------+-----------------+----------------------------------+
  323. | 7 + len + 17    | 0x2b 0x06 0x01  | Object instance:                 |
  324. |                 | 0x04 0x01 0x02  | 1.3.6.1.4.1.2.2.1.1.0            |
  325. |                 | 0x02 0x01 0x01  |                                  |
  326. |                 | 0x00            |                                  |
  327. +-----------------+-----------------+----------------------------------+
  328. | 7 + len + 27    | 0x05 0x00       | null value, length=0             |
  329. +-----------------+-----------------+----------------------------------+
  330. +----------------------------------------------------------------------+
  331.  
  332. The formula to calculate the length field "pdu_length" is as follows:
  333.  
  334.   pdu_length =   length of version field and string tag (4 bytes)
  335.  
  336.  
  337.  
  338. Carpenter & Wijnen                                              [Page 6]
  339.  
  340. RFC 1228                        SNMP-DPI                        May 1991
  341.  
  342.  
  343.              +   length of community length field (1 byte)
  344.              +   length of community name (depends...)
  345.              +   length of SNMP GET request (29 bytes)
  346.  
  347.              =   34 + length of community name
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394. Carpenter & Wijnen                                              [Page 7]
  395.  
  396. RFC 1228                        SNMP-DPI                        May 1991
  397.  
  398.  
  399. SNMP PDU CONTAINING THE RESPONSE TO THE GET
  400.  
  401. Assuming that no errors occured, then the port is returned in the last 2
  402. octets of the received packet.  The format of the packet is shown below:
  403.  
  404. +----------------------------------------------------------------------+
  405. | Table 2. SNMP RESPONSE PDU for GET of Agent's DPI port.  This is the |
  406. |          layout of an SNMP RESPONSE PDU for GET DPI_port             |
  407. +-----------------+-----------------+----------------------------------+
  408. | OFFSET          | VALUE           | FIELD                            |
  409. +-----------------+-----------------+----------------------------------+
  410. | 0               | 0x30            | ASN.1 header                     |
  411. +-----------------+-----------------+----------------------------------+
  412. | 1               | 36 + len        | length, see formula below        |
  413. +-----------------+-----------------+----------------------------------+
  414. | 2               | 0x02 0x01 0x00  | version (integer, length=1,      |
  415. |                 | 0x04            | value=0), community name         |
  416. |                 |                 | (string)                         |
  417. +-----------------+-----------------+----------------------------------+
  418. | 6               | len             | length of community name         |
  419. +-----------------+-----------------+----------------------------------+
  420. | 7               | community name  |                                  |
  421. +-----------------+-----------------+----------------------------------+
  422. | 7 + len         | 0xa2 0x1d       | SNMP RESPONSE:                   |
  423. |                 |                 | request_type=0xa2, length=0x1d   |
  424. +-----------------+-----------------+----------------------------------+
  425. | 7 + len + 2     | 0x02 0x01 0x01  | SNMP request ID: integer,        |
  426. |                 |                 | length=1, ID=1                   |
  427. +-----------------+-----------------+----------------------------------+
  428. | 7 + len + 5     | 0x02 0x01 0x00  | SNMP error status: integer,      |
  429. |                 |                 | length=1, error=0                |
  430. +-----------------+-----------------+----------------------------------+
  431. | 7 + len + 8     | 0x02 0x01 0x00  | SNMP index: integer, length=1,   |
  432. |                 |                 | index=0                          |
  433. +-----------------+-----------------+----------------------------------+
  434. | 7 + len + 11    | 0x30 0x12       | Varbind list, length=0x12        |
  435. +-----------------+-----------------+----------------------------------+
  436. | 7 + len + 13    | 0x30 0x10       | Varbind, length=0x10             |
  437. +-----------------+-----------------+----------------------------------+
  438. | 7 + len + 15    | 0x06 0x0a       | Object ID, length=0x0a           |
  439. +-----------------+-----------------+----------------------------------+
  440. +----------------------------------------------------------------------+
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450. Carpenter & Wijnen                                              [Page 8]
  451.  
  452. RFC 1228                        SNMP-DPI                        May 1991
  453.  
  454.  
  455. +----------------------------------------------------------------------+
  456. | Table 2. SNMP RESPONSE PDU for GET of Agent's DPI port.  This is the |
  457. |          layout of an SNMP RESPONSE PDU for GET DPI_port             |
  458. +-----------------+-----------------+----------------------------------+
  459. | OFFSET          | VALUE           | FIELD                            |
  460. +-----------------+-----------------+----------------------------------+
  461. | 7 + len + 17    | 0x2b 0x06 0x01  | Object instance:                 |
  462. |                 | 0x04 0x01 0x02  | 1.3.6.1.4.1.2.2.1.1.0            |
  463. |                 | 0x02 0x01 0x01  |                                  |
  464. |                 | 0x00            |                                  |
  465. +-----------------+-----------------+----------------------------------+
  466. | 7 + len + 27    | 0x02 0x02       | integer, length=2                |
  467. +-----------------+-----------------+----------------------------------+
  468. | 7 + len + 29    | msb lsb         | port number (msb, lsb)           |
  469. +-----------------+-----------------+----------------------------------+
  470. +----------------------------------------------------------------------+
  471.  
  472. The formula to calculate the length field "pdu_length" is as follows:
  473.  
  474.   pdu_length =   length of version field and string tag (4 bytes)
  475.              +   length of community length field (1 byte)
  476.              +   length of community name (depends...)
  477.              +   length of SNMP RESPONSE (31 bytes)
  478.  
  479.              =   36 + length of community name
  480.  
  481. SNMP DPI PACKET FORMATS
  482.  
  483.    Each request to or response from the agent is constructed as a
  484.    "packet" and is written to the stream.
  485.  
  486.    Each packet is prefaced with the length of the data remaining in the
  487.    packet.  The length is stored in network byte order (most significant
  488.    byte first, least significant last).  The receiving side will read
  489.    the packet by doing something similar to:
  490.  
  491.       unsigned char len_bfr[2];
  492.       char *bfr;
  493.       int len;
  494.  
  495.       read(fd,len_bfr,2);
  496.       len = len_bfr[0] * 256 + len_bfr[1];
  497.       bfr = malloc(len);
  498.       read(fd,bfr,len);
  499.  
  500.    NOTE:  the above example makes no provisions for error handling or a
  501.    read returning less than the requested amount of data.  This is not a
  502.    suggested coding style.
  503.  
  504.  
  505.  
  506. Carpenter & Wijnen                                              [Page 9]
  507.  
  508. RFC 1228                        SNMP-DPI                        May 1991
  509.  
  510.  
  511.    The first part of every packet identifies the application protocol
  512.    being used, as well as some version information.  The protocol major
  513.    version is intended to indicate in broad terms what version of the
  514.    protocol is used.  The protocol minor version is intended to identify
  515.    major incompatible versions of the protocol.  The protocol release is
  516.    intended to indicate incremental modifications to the protocol.  The
  517.    constants that are valid for these fields are defined in Table 10 on
  518.    page 18.
  519.  
  520.    The next (common) field in all packets is the packet type.  This
  521.    field indicates what kind of packet we're dealing with (SNMP DPI GET,
  522.    GET-NEXT, SET, TRAP, RESPONSE or REGISTER).  The permitted values for
  523.    this field are defined in Table 11 on page 18.
  524.  
  525. +----------------------------------------------------------------------+
  526. | Table 3. SNMP DPI packet header.  This header is present in all      |
  527. |          packets.                                                    |
  528. +-------------+--------------------------------------------------------+
  529. | OFFSET      | FIELD                                                  |
  530. +-------------+--------------------------------------------------------+
  531. | 0           | packet length to follow (MSB)                          |
  532. +-------------+--------------------------------------------------------+
  533. | 1           | packet length to follow (LSB)                          |
  534. +-------------+--------------------------------------------------------+
  535. | 2           | protocol major version                                 |
  536. +-------------+--------------------------------------------------------+
  537. | 3           | protocol minor version                                 |
  538. +-------------+--------------------------------------------------------+
  539. | 4           | protocol release                                       |
  540. +-------------+--------------------------------------------------------+
  541. | 5           | packet type                                            |
  542. +-------------+--------------------------------------------------------+
  543. +----------------------------------------------------------------------+
  544.  
  545. >From this point onwards, the contents of the packet are defined by the
  546. protocol being used.  The remainder of this section describes:
  547.  
  548.    o   the structure of packets for the SNMP DPI protocol, version 1.0.
  549.  
  550.    o   The constants as defined with this version of the protocol.
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562. Carpenter & Wijnen                                             [Page 10]
  563.  
  564. RFC 1228                        SNMP-DPI                        May 1991
  565.  
  566.  
  567. REGISTER
  568.  
  569.    In order to register a branch in the MIB tree, an SNMP sub-agent
  570.    sends an SNMP DPI REGISTER packet to the agent.
  571.  
  572.    Such a packet contains the standard SNMP DPI header plus REGISTER-
  573.    specific data, which basically is a null terminated string
  574.    representing the object ID in dotted ASN.1 notation (with a trailing
  575.    dot!).
  576.  
  577. +----------------------------------------------------------------------+
  578. | Table 4. SNMP DPI REGISTER packet.  This is the layout of an SNMP    |
  579. |          DPI REGISTER packet                                         |
  580. +-------------+--------------------------------------------------------+
  581. | OFFSET      | FIELD                                                  |
  582. +-------------+--------------------------------------------------------+
  583. | 0           | packet length to follow (MSB)                          |
  584. +-------------+--------------------------------------------------------+
  585. | 1           | packet length to follow (LSB)                          |
  586. +-------------+--------------------------------------------------------+
  587. | 2           | protocol major version                                 |
  588. +-------------+--------------------------------------------------------+
  589. | 3           | protocol minor version                                 |
  590. +-------------+--------------------------------------------------------+
  591. | 4           | protocol release                                       |
  592. +-------------+--------------------------------------------------------+
  593. | 5           | packet type = SNMP_DPI_REGISTER                        |
  594. +-------------+--------------------------------------------------------+
  595. | 6           | null terminated object ID                              |
  596. +-------------+--------------------------------------------------------+
  597. +----------------------------------------------------------------------+
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618. Carpenter & Wijnen                                             [Page 11]
  619.  
  620. RFC 1228                        SNMP-DPI                        May 1991
  621.  
  622.  
  623. GET
  624.  
  625.    When the SNMP agent receives a PDU containing an SNMP GET request for
  626.    a variable that a sub-agent registered with the agent, it passes an
  627.    SNMP DPI GET packet to the sub-agent.
  628.  
  629.    Such a packet contains the standard SNMP DPI header plus GET-specific
  630.    data, which is basically a null terminated string representing the
  631.    object ID in dotted ASN.1 notation.
  632.  
  633. +----------------------------------------------------------------------+
  634. | Table 5. SNMP DPI GET packet.  This is the layout of an SNMP DPI GET |
  635. |          packet                                                      |
  636. +-------------+--------------------------------------------------------+
  637. | OFFSET      | FIELD                                                  |
  638. +-------------+--------------------------------------------------------+
  639. | 0           | packet length to follow (MSB)                          |
  640. +-------------+--------------------------------------------------------+
  641. | 1           | packet length to follow (LSB)                          |
  642. +-------------+--------------------------------------------------------+
  643. | 2           | protocol major version                                 |
  644. +-------------+--------------------------------------------------------+
  645. | 3           | protocol minor version                                 |
  646. +-------------+--------------------------------------------------------+
  647. | 4           | protocol release                                       |
  648. +-------------+--------------------------------------------------------+
  649. | 5           | packet type = SNMP_DPI_GET                             |
  650. +-------------+--------------------------------------------------------+
  651. | 6           | null terminated object ID                              |
  652. +-------------+--------------------------------------------------------+
  653. +----------------------------------------------------------------------+
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674. Carpenter & Wijnen                                             [Page 12]
  675.  
  676. RFC 1228                        SNMP-DPI                        May 1991
  677.  
  678.  
  679. GET-NEXT
  680.  
  681.    When the SNMP agent receives a PDU containing an SNMP GET-NEXT
  682.    request for a variable for which a sub-agent may be authoritative, it
  683.    passes an SNMP DPI GET-NEXT packet to the sub-agent.
  684.  
  685.    Such a packet contains the standard SNMP DPI header plus GET-NEXT-
  686.    specific data.  These data take the form of two null terminated
  687.    strings.  The first string represents the object ID in dotted ASN.1
  688.    notation; the second string represents the group ID in dotted ASN.1
  689.    notation.
  690.  
  691. +----------------------------------------------------------------------+
  692. | Table 6. SNMP DPI GET NEXT packet.  This is the layout of an SNMP    |
  693. |          DPI GET NEXT packet                                         |
  694. +-------------+--------------------------------------------------------+
  695. | OFFSET      | FIELD                                                  |
  696. +-------------+--------------------------------------------------------+
  697. | 0           | packet length to follow (MSB)                          |
  698. +-------------+--------------------------------------------------------+
  699. | 1           | packet length to follow (LSB)                          |
  700. +-------------+--------------------------------------------------------+
  701. | 2           | protocol major version                                 |
  702. +-------------+--------------------------------------------------------+
  703. | 3           | protocol minor version                                 |
  704. +-------------+--------------------------------------------------------+
  705. | 4           | protocol release                                       |
  706. +-------------+--------------------------------------------------------+
  707. | 5           | packet type = SNMP_DPI_GET_NEXT                        |
  708. +-------------+--------------------------------------------------------+
  709. | 6           | null terminated object ID                              |
  710. +-------------+--------------------------------------------------------+
  711. | 6 + len     | null terminated group ID                               |
  712. +-------------+--------------------------------------------------------+
  713. | NOTE:  len=strlen(object ID)+1                                       |
  714. +----------------------------------------------------------------------+
  715. +----------------------------------------------------------------------+
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. Carpenter & Wijnen                                             [Page 13]
  731.  
  732. RFC 1228                        SNMP-DPI                        May 1991
  733.  
  734.  
  735. SET
  736.  
  737.    When the SNMP agent receives a PDU containing an SNMP SET request for
  738.    a variable that a sub-agent registered with the agent, it passes an
  739.    SNMP DPI SET packet to the sub-agent.
  740.  
  741.    Such a packet contains the standard SNMP DPI header plus SET specific
  742.    data, which is basically a null terminated string representing the
  743.    object ID in ASN.1 notation, with the type, value length and value to
  744.    be set.  The permitted types for the type field are defined in Table
  745.    12 on page 19.  Integer values are sent as 4-byte elements in network
  746.    byte order (most significant byte first, least significant byte
  747.    last).
  748.  
  749. +----------------------------------------------------------------------+
  750. | Table 7. SNMP DPI SET packet.  This is the layout of an SNMP DPI SET |
  751. |          packet                                                      |
  752. +-------------+--------------------------------------------------------+
  753. | OFFSET      | FIELD                                                  |
  754. +-------------+--------------------------------------------------------+
  755. | 0           | packet length to follow (MSB)                          |
  756. +-------------+--------------------------------------------------------+
  757. | 1           | packet length to follow (LSB)                          |
  758. +-------------+--------------------------------------------------------+
  759. | 2           | protocol major version                                 |
  760. +-------------+--------------------------------------------------------+
  761. | 3           | protocol minor version                                 |
  762. +-------------+--------------------------------------------------------+
  763. | 4           | protocol release                                       |
  764. +-------------+--------------------------------------------------------+
  765. | 5           | packet type = SNMP_DPI_SET                             |
  766. +-------------+--------------------------------------------------------+
  767. | 6           | null terminated object ID                              |
  768. +-------------+--------------------------------------------------------+
  769. | 6 + len     | SNMP Variable Type Value                               |
  770. +-------------+--------------------------------------------------------+
  771. | 6 + len + 1 | Length of value (MSB)                                  |
  772. +-------------+--------------------------------------------------------+
  773. | 6 + len + 2 | Length of value (LSB)                                  |
  774. +-------------+--------------------------------------------------------+
  775. | 6 + len + 3 | Value                                                  |
  776. +-------------+--------------------------------------------------------+
  777. | NOTE:  len=strlen(object ID)+1                                       |
  778. +----------------------------------------------------------------------+
  779. +----------------------------------------------------------------------+
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786. Carpenter & Wijnen                                             [Page 14]
  787.  
  788. RFC 1228                        SNMP-DPI                        May 1991
  789.  
  790.  
  791. RESPONSE
  792.  
  793.    An SNMP sub-agent must respond to a GET, GET_NEXT or SET request that
  794.    it has received from the agent (unless it fails or has a bug).  To do
  795.    so, it sends an SNMP DPI RESPONSE packet to the agent.
  796.  
  797.    Such a packet contains the standard SNMP DPI header plus RESPONSE
  798.    specific data, which basically is an error_code plus (if there was no
  799.    error), the name/type/value tuple representing the returned object.
  800.    This is described as by a string representing the object ID in ASN.1
  801.    notation, plus the type, value length and value of the object that
  802.    was manipulated.  The permitted types for the type field are defined
  803.    in Table 12 on page 19.  Integer values are sent as 4-byte elements
  804.    in network byte order (most significant byte first, least significant
  805.    byte last).
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842. Carpenter & Wijnen                                             [Page 15]
  843.  
  844. RFC 1228                        SNMP-DPI                        May 1991
  845.  
  846.  
  847. +----------------------------------------------------------------------+
  848. | Table 8. SNMP DPI RESPONSE packet.  This is the layout of an SNMP    |
  849. |          DPI RESPONSE packet                                         |
  850. +-------------+--------------------------------------------------------+
  851. | OFFSET      | FIELD                                                  |
  852. +-------------+--------------------------------------------------------+
  853. | 0           | packet length to follow (MSB)                          |
  854. +-------------+--------------------------------------------------------+
  855. | 1           | packet length to follow (LSB)                          |
  856. +-------------+--------------------------------------------------------+
  857. | 2           | protocol major version                                 |
  858. +-------------+--------------------------------------------------------+
  859. | 3           | protocol minor version                                 |
  860. +-------------+--------------------------------------------------------+
  861. | 4           | protocol release                                       |
  862. +-------------+--------------------------------------------------------+
  863. | 5           | packet type = SNMP_DPI_RESPONSE                        |
  864. +-------------+--------------------------------------------------------+
  865. | 6           | SNMP error code                                        |
  866. +-------------+--------------------------------------------------------+
  867. | 7           | null terminated object ID                              |
  868. +-------------+--------------------------------------------------------+
  869. | 7 + len     | SNMP Variable Type Value                               |
  870. +-------------+--------------------------------------------------------+
  871. | 7 + len + 1 | Length of value (MSB)                                  |
  872. +-------------+--------------------------------------------------------+
  873. | 7 + len + 2 | Length of value (LSB)                                  |
  874. +-------------+--------------------------------------------------------+
  875. | 7 + len + 3 | Value                                                  |
  876. +-------------+--------------------------------------------------------+
  877. | NOTE:  len=strlen(object ID)+1                                       |
  878. +----------------------------------------------------------------------+
  879. +----------------------------------------------------------------------+
  880.  
  881. TRAP
  882.  
  883.    An SNMP sub-agent can request the agent to generate a TRAP by sending
  884.    an SNMP DPI TRAP packet to the agent.
  885.  
  886.    Such a packet contains the standard SNMP DPI header plus TRAP
  887.    specific data, which is basically the generic and specific trap code,
  888.    plus a name/type/value tuple.  The tuple is described by a string
  889.    representing the object ID in ASN.1 notation, plus the type, value
  890.    length and value of the object that is being sent in the trap.  The
  891.    permitted types for the type field are defined in Table 12 on page
  892.    19.  Integer values are sent as 4-byte elements in network byte order
  893.    (most significant byte first, least significant byte last).
  894.  
  895.  
  896.  
  897.  
  898. Carpenter & Wijnen                                             [Page 16]
  899.  
  900. RFC 1228                        SNMP-DPI                        May 1991
  901.  
  902.  
  903. +----------------------------------------------------------------------+
  904. | Table 9. SNMP DPI TRAP packet.  This is the layout of an SNMP DPI    |
  905. |          TRAP packet                                                 |
  906. +-------------+--------------------------------------------------------+
  907. | OFFSET      | FIELD                                                  |
  908. +-------------+--------------------------------------------------------+
  909. | 0           | packet length to follow (MSB)                          |
  910. +-------------+--------------------------------------------------------+
  911. | 1           | packet length to follow (LSB)                          |
  912. +-------------+--------------------------------------------------------+
  913. | 2           | protocol major version                                 |
  914. +-------------+--------------------------------------------------------+
  915. | 3           | protocol minor version                                 |
  916. +-------------+--------------------------------------------------------+
  917. | 4           | protocol release                                       |
  918. +-------------+--------------------------------------------------------+
  919. | 5           | packet type - SNMP_DPI_TRAP                            |
  920. +-------------+--------------------------------------------------------+
  921. | 6           | SNMP generic trap code                                 |
  922. +-------------+--------------------------------------------------------+
  923. | 7           | SNMP specific trap code                                |
  924. +-------------+--------------------------------------------------------+
  925. | 8           | null terminated object ID                              |
  926. +-------------+--------------------------------------------------------+
  927. | 8 + len     | SNMP Variable Type Value                               |
  928. +-------------+--------------------------------------------------------+
  929. | 8 + len + 1 | Length of value (MSB)                                  |
  930. +-------------+--------------------------------------------------------+
  931. | 8 + len + 2 | Length of value (LSB)                                  |
  932. +-------------+--------------------------------------------------------+
  933. | 8 + len + 3 | Value                                                  |
  934. +-------------+--------------------------------------------------------+
  935. | NOTE:  len=strlen(object ID)+1                                       |
  936. +----------------------------------------------------------------------+
  937. +----------------------------------------------------------------------+
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954. Carpenter & Wijnen                                             [Page 17]
  955.  
  956. RFC 1228                        SNMP-DPI                        May 1991
  957.  
  958.  
  959. CONSTANTS AND VALUES
  960.  
  961.    This section describes the constants that have been defined for this
  962.    version of the SNMP DPI Protocol.
  963.  
  964. PROTOCOL VERSION AND RELEASE VALUES
  965.  
  966. +----------------------------------------------------------------------+
  967. | Table 10. Protocol version and release values                        |
  968. +-----------------------------------+----------------------------------+
  969. | FIELD                             | VALUE                            |
  970. +-----------------------------------+----------------------------------+
  971. | protocol major version            | 2 (SNMP DPI protocol)            |
  972. +-----------------------------------+----------------------------------+
  973. | protocol minor version            | 1 (version 1)                    |
  974. +-----------------------------------+----------------------------------+
  975. | protocol release                  | 0 (release 0)                    |
  976. +-----------------------------------+----------------------------------+
  977. +----------------------------------------------------------------------+
  978.  
  979. Any other values are currently undefined.
  980.  
  981. PACKET TYPE VALUES
  982.  
  983.    The packet type field can have the following values:
  984.  
  985. +----------------------------------------------------------------------+
  986. | Table 11. Valid values for the packet type field                     |
  987. +-------+--------------------------------------------------------------+
  988. | VALUE | PACKET TYPE                                                  |
  989. +-------+--------------------------------------------------------------+
  990. | 1     | SNMP_DPI_GET                                                 |
  991. +-------+--------------------------------------------------------------+
  992. | 2     | SNMP_DPI_GET_NEXT                                            |
  993. +-------+--------------------------------------------------------------+
  994. | 3     | SNMP_DPI_SET                                                 |
  995. +-------+--------------------------------------------------------------+
  996. | 4     | SNMP_DPI_TRAP                                                |
  997. +-------+--------------------------------------------------------------+
  998. | 5     | SNMP_DPI_RESPONSE                                            |
  999. +-------+--------------------------------------------------------------+
  1000. | 6     | SNMP_DPI_REGISTER                                            |
  1001. +-------+--------------------------------------------------------------+
  1002. +----------------------------------------------------------------------+
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010. Carpenter & Wijnen                                             [Page 18]
  1011.  
  1012. RFC 1228                        SNMP-DPI                        May 1991
  1013.  
  1014.  
  1015. VARIABLE TYPE VALUES
  1016.  
  1017.    The variable type field can have the following values:
  1018.  
  1019. +----------------------------------------------------------------------+
  1020. | Table 12. Valid values for the Value Type field                      |
  1021. +-------+--------------------------------------------------------------+
  1022. | VALUE | VALUE TYPE                                                   |
  1023. +-------+--------------------------------------------------------------+
  1024. | 0     | text representation                                          |
  1025. +-------+--------------------------------------------------------------+
  1026. | 129   | number (integer)                                             |
  1027. +-------+--------------------------------------------------------------+
  1028. | 2     | octet string                                                 |
  1029. +-------+--------------------------------------------------------------+
  1030. | 3     | object identifier                                            |
  1031. +-------+--------------------------------------------------------------+
  1032. | 4     | empty (no value)                                             |
  1033. +-------+--------------------------------------------------------------+
  1034. | 133   | internet address                                             |
  1035. +-------+--------------------------------------------------------------+
  1036. | 134   | counter (unsigned)                                           |
  1037. +-------+--------------------------------------------------------------+
  1038. | 135   | gauge (unsigned)                                             |
  1039. +-------+--------------------------------------------------------------+
  1040. | 136   | time ticks (1/100ths seconds)                                |
  1041. +-------+--------------------------------------------------------------+
  1042. | 9     | display string                                               |
  1043. +-------+--------------------------------------------------------------+
  1044. +----------------------------------------------------------------------+
  1045.  
  1046.    NOTE:  Fields which represent values that are stored as a 4-byte
  1047.    integer are indicated by ORing their base type value with 128.
  1048.  
  1049. Error Code Values for SNMP Agent Detected Errors
  1050.  
  1051.    The error code can have one of the following values:
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066. Carpenter & Wijnen                                             [Page 19]
  1067.  
  1068. RFC 1228                        SNMP-DPI                        May 1991
  1069.  
  1070.  
  1071. +----------------------------------------------------------------------+
  1072. | Table 13. Valid values for the SNMP Agent Minor Error Code field     |
  1073. +-------+--------------------------------------------------------------+
  1074. | VALUE | SNMP AGENT ERROR CODE                                        |
  1075. +-------+--------------------------------------------------------------+
  1076. | 0     | no error                                                     |
  1077. +-------+--------------------------------------------------------------+
  1078. | 1     | too big                                                      |
  1079. +-------+--------------------------------------------------------------+
  1080. | 2     | no such name                                                 |
  1081. +-------+--------------------------------------------------------------+
  1082. | 3     | bad value                                                    |
  1083. +-------+--------------------------------------------------------------+
  1084. | 4     | read only                                                    |
  1085. +-------+--------------------------------------------------------------+
  1086. | 5     | general error                                                |
  1087. +-------+--------------------------------------------------------------+
  1088. +----------------------------------------------------------------------+
  1089.  
  1090. SNMP DPI APPLICATION PROGRAM INTERFACE
  1091.  
  1092.    This section documents an API that implements the SNMP DPI.  This
  1093.    information has been previously published [6, 8], but the information
  1094.    provided below is more current as of May 14, 1991.
  1095.  
  1096. OVERVIEW OF REQUEST PROCESSING
  1097.  
  1098. GET PROCESSING
  1099.  
  1100.    A GET request is the easiest to process.  When the DPI packet is
  1101.    parsed, the parse tree holds the object ID of the variable being
  1102.    requested.
  1103.  
  1104.    If the specified object is not supported by the sub-agent, it would
  1105.    return an error indication of "no such name".  No name/type/value
  1106.    information would be returned.
  1107.  
  1108.         unsigned char *cp;
  1109.  
  1110.         cp = mkDPIresponse(SNMP_NO_SUCH_NAME,0);
  1111.  
  1112.    If the object is recognized, then the sub-agent creates a parse tree
  1113.    representing the name/type/value of the object in question (using the
  1114.    DPI API routine mkDPIset()), and returns no error indication.  This
  1115.    is demonstrated below (a string is being returned).
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122. Carpenter & Wijnen                                             [Page 20]
  1123.  
  1124. RFC 1228                        SNMP-DPI                        May 1991
  1125.  
  1126.  
  1127.         char *obj_id;
  1128.  
  1129.         unsigned char *cp;
  1130.         struct dpi_set_packet *ret_value;
  1131.         char *data;
  1132.  
  1133.         /* obj_id = object ID of variable, like 1.3.6.1.2.1.1.1 */
  1134.         /* should be identical to object ID sent in get request */
  1135.         data = "a string to be returned";
  1136.         ret_value = mkDPIset(obj_id,SNMP_TYPE_STRING,
  1137.                         strlen(data)+1,data);
  1138.         cp = mkDPIresponse(0,ret_value);
  1139.  
  1140. SET PROCESSING
  1141.  
  1142.    Processing a SET request is only slightly more difficult than a GET
  1143.    request.  In this case, additional information is made available in
  1144.    the parse tree, namely the type, length and value to be set.
  1145.  
  1146.    The sub-agent may return an error indication of "no such name" if the
  1147.    variable is unrecognized, just as in a GET request.  If the variable
  1148.    is recognized, but cannot be set, an error indication of "no such
  1149.    name" should be also be returned, although it is tempting to return a
  1150.    "read only" error.
  1151.  
  1152. GET NEXT PROCESSING
  1153.  
  1154.    GET-NEXT requests are the most complicated requests to process.
  1155.    After parsing a GET-NEXT request, the parse tree will contain two
  1156.    parameters.  One is the object ID on which the GET-NEXT operation is
  1157.    being performed.  The semantics of the operation are that the sub-
  1158.    agent is to return the name/type/value of the next variable it
  1159.    supports whose name lexicographically follows the passed object ID.
  1160.  
  1161.    It is important to realize that a given sub-agent may support several
  1162.    discontiguous sections of the MIB tree.  In such a situation it would
  1163.    be incorrect to jump from one section to another.  This problem is
  1164.    correctly handled by examining the second parameter which is passed.
  1165.    This parameter represents the "reason" why the sub-agent is being
  1166.    called.  It holds the prefix of the tree that the sub-agent had
  1167.    indicated it supported.
  1168.  
  1169.    If the next variable supported by the sub-agent does not begin with
  1170.    that prefix, the sub-agent must return an error indication of "no
  1171.    such name".  If required, the SNMP agent will call upon the sub-agent
  1172.    again, but pass it a different group prefix.  This is illustrated in
  1173.    the discussion below:
  1174.  
  1175.  
  1176.  
  1177.  
  1178. Carpenter & Wijnen                                             [Page 21]
  1179.  
  1180. RFC 1228                        SNMP-DPI                        May 1991
  1181.  
  1182.  
  1183.    Assume there are two sub-agents.  The first sub-agent registers two
  1184.    distinct sections of the tree, A and C.  In reality, the sub-agent
  1185.    supports variables A.1 and A.2, but it correctly registers the
  1186.    minimal prefix required to uniquely identify the variable class it
  1187.    supports.
  1188.  
  1189.    The second sub-agent registers a different section, B, which appears
  1190.    between the two sections registered by the first agent.
  1191.  
  1192.    If a remote management station begins dumping the MIB, starting from
  1193.    A, the following sequence of queries would be performed:
  1194.  
  1195.      Sub-agent 1 gets called:
  1196.             get-next(A,A) == A.1
  1197.             get-next(A.1,A) = A.2
  1198.             get-next(A.2,A) = error(no such name)
  1199.  
  1200.      Sub-agent 2 is then called:
  1201.             get-next(A.2,B) = B.1
  1202.             get-next(B.1,B) = error(no such name)
  1203.  
  1204.      Sub-agent 1 gets called again:
  1205.             get-next(B.1,C) = C.1
  1206.  
  1207. REGISTER REQUESTS
  1208.  
  1209.    A sub-agent must register the variables it supports with the SNMP
  1210.    agent.  The appropriate packets may be created using the DPI API
  1211.    library routine mkDPIregister().
  1212.  
  1213.          unsigned char *cp;
  1214.  
  1215.          cp = mkDPIregister("1.3.6.1.2.1.1.2.");
  1216.  
  1217. NOTE:  object IDs are registered with a trailing dot (".").
  1218.  
  1219. TRAP REQUESTS
  1220.  
  1221.    A sub-agent can request that the SNMP agent generate a trap for it.
  1222.    The sub-agent must provide the desired values for the generic and
  1223.    specific parameters of the trap.  It may optionally provide a
  1224.    name/type/value parameter that will be included in the trap packet.
  1225.    The DPI API library routine mkDPItrap() can be used to generate the
  1226.    required packet.
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234. Carpenter & Wijnen                                             [Page 22]
  1235.  
  1236. RFC 1228                        SNMP-DPI                        May 1991
  1237.  
  1238.  
  1239. DPI API LIBRARY ROUTINES
  1240.  
  1241.    This section documents Application Program Interfaces to the DPI.
  1242.  
  1243.    QUERY_DPI_PORT()
  1244.  
  1245.      int port;
  1246.      char *hostname, *community_name;
  1247.  
  1248.      port = query_DPI_port(hostname, community_name);
  1249.  
  1250.    The query_DPI_port() function is used by a DPI client to determine
  1251.    what TCP port number is associated with the DPI.  This port number is
  1252.    needed to connect() to the SNMP agent.  If the port cannot be
  1253.    determined, -1 is returned.
  1254.  
  1255.    The function is passed two arguments:  a string representing the
  1256.    host's name or IP address and the community name to be used when
  1257.    making the request.
  1258.  
  1259.    This function enables a DPI client to "bootstrap" itself.  The port
  1260.    number is obtained via an SNMP GET request, but the DPI client does
  1261.    not have to be able to create and parse SNMP packets--this is all
  1262.    done by the query_DPI_port() function.
  1263.  
  1264.    NOTE:  the query_DPI_port() function assumes that the community name
  1265.    does not contain any null characters.  If this is not the case, use
  1266.    the _query_DPI_port() function which takes a third parameter, the
  1267.    length of the community name.
  1268.  
  1269. MKDPIREGISTER
  1270.  
  1271.      #include "snmp_dpi.h"
  1272.  
  1273.      unsigned char *packet;
  1274.      int len;
  1275.  
  1276.      /* register sysDescr variable */
  1277.      packet = mkDPIregister("1.3.6.1.2.1.1.1.");
  1278.  
  1279.      len = *packet * 256 + *(packet + 1);
  1280.      len += 2;  /* include length bytes */
  1281.  
  1282.    The mkDPIregister() function creates the necessary register-request
  1283.    packet and returns a pointer to a static buffer holding the packet
  1284.    contents.  The null pointer (0) is returned if there is an error
  1285.    detected during the creation of the packet.
  1286.  
  1287.  
  1288.  
  1289.  
  1290. Carpenter & Wijnen                                             [Page 23]
  1291.  
  1292. RFC 1228                        SNMP-DPI                        May 1991
  1293.  
  1294.  
  1295.    The length of the remainder packet is stored in the first two bytes
  1296.    of the packet, as demonstrated in the example above.
  1297.  
  1298.    NOTE:  object identifiers are registered with a trailing dot (".").
  1299.  
  1300. MKDPISET
  1301.  
  1302.      #include "snmp_dpi.h"
  1303.  
  1304.      struct dpi_set_packet *set_value;
  1305.  
  1306.      char *obj_id;
  1307.      int type, length;
  1308.      char *value;
  1309.  
  1310.      set_value = mkDPIset(obj_id, type, length, value);
  1311.  
  1312.    The mkDPIset() function can be used to create the portion of a parse
  1313.    tree that represents a name/value pair (as would be normally be
  1314.    returned in a response packet).  It returns a pointer to a
  1315.    dynamically allocated parse tree representing the name/type/value
  1316.    information.  If there is an error detected while creating the parse
  1317.    tree, the null pointer (0) is returned.
  1318.  
  1319.    The value of type can be one of the following (which are defined in
  1320.    the include file "snmp_dpi.h"):
  1321.  
  1322.       o   SNMP_TYPE_NUMBER
  1323.       o   SNMP_TYPE_STRING
  1324.       o   SNMP_TYPE_OBJECT
  1325.       o   SNMP_TYPE_INTERNET
  1326.       o   SNMP_TYPE_COUNTER
  1327.       o   SNMP_TYPE_GAUGE
  1328.       o   SNMP_TYPE_TICKS
  1329.  
  1330.    The value parameter is always a pointer to the first byte of the
  1331.    object's value.
  1332.  
  1333.    NOTE:  the parse tree is dynamically allocated and copies are made of
  1334.    the passed parameters.  After a successful call to mkDPIset(), they
  1335.    can be disposed of in any manner the application chooses without
  1336.    affecting the parse tree contents.
  1337.  
  1338. MKDPIRESPONSE
  1339.  
  1340.      #include "snmp_dpi.h"
  1341.  
  1342.      unsigned char *packet;
  1343.  
  1344.  
  1345.  
  1346. Carpenter & Wijnen                                             [Page 24]
  1347.  
  1348. RFC 1228                        SNMP-DPI                        May 1991
  1349.  
  1350.  
  1351.      int error_code;
  1352.      struct dpi_set_packet *ret_value;
  1353.  
  1354.      packet = mkDPIresponse(error_code, ret_value);
  1355.  
  1356.      len = *packet * 256 + *(packet + 1);
  1357.      len += 2;  /* include length bytes */
  1358.  
  1359.    The mkDPIresponse() function creates an appropriate response packet.
  1360.    It takes two parameters.  The first is the error code to be returned.
  1361.    It may be 0 (indicating no error) or one of the following (which are
  1362.    defined in the include file "snmp_dpi.h"):
  1363.  
  1364.       o   SNMP_NO_ERROR
  1365.       o   SNMP_TOO_BIG
  1366.       o   SNMP_NO_SUCH_NAME
  1367.       o   SNMP_BAD_VALUE
  1368.       o   SNMP_READ_ONLY
  1369.       o   SNMP_GEN_ERR
  1370.  
  1371.    If the error code indicates no error, then the second parameter is a
  1372.    pointer to a parse tree (created by mkDPIset()) which represents the
  1373.    name/type/value information being returned.  If an error is
  1374.    indicated, the second parameter is passed as a null pointer (0).
  1375.  
  1376.    If the packet can be created, a pointer to a static buffer containing
  1377.    the packet contents is returned.  This is the same buffer used by
  1378.    mkDPIregister().  If an error is encountered while creating the
  1379.    packet, the null pointer (0) is returned.
  1380.  
  1381.    The length of the remainder packet is stored in the first two bytes
  1382.    of the packet, as demonstrated in the example above.
  1383.  
  1384.    NOTE:  mkDPIresponse() always frees the passed parse tree.
  1385.  
  1386. MKDPITRAP
  1387.  
  1388.      #include "snmp_dpi.h"
  1389.  
  1390.      unsigned char *packet;
  1391.  
  1392.      int generic, specific;
  1393.      struct dpi_set_packet *ret_value;
  1394.  
  1395.      packet = mkDPItrap(generic, specific, ret_value);
  1396.  
  1397.      len = *packet * 256 + *(packet + 1);
  1398.      len += 2;  /* include length bytes */
  1399.  
  1400.  
  1401.  
  1402. Carpenter & Wijnen                                             [Page 25]
  1403.  
  1404. RFC 1228                        SNMP-DPI                        May 1991
  1405.  
  1406.  
  1407.    The mkDPItrap() function creates an appropriate trap request packet.
  1408.    The first two parameters correspond to to value of the generic and
  1409.    specific fields in the SNMP trap packet.  The third field can be used
  1410.    to pass a name/value pair to be provided in the SNMP trap packet.
  1411.    This information is passed as the set-packet portion of the parse
  1412.    tree.  As an example, a linkDown trap for interface 3 might be
  1413.    generated by the following:
  1414.  
  1415.      struct dpi_set_packet *if_index_value;
  1416.      unsigned long data;
  1417.      unsigned char *packet;
  1418.      int len;
  1419.  
  1420.      data = 3;  /* interface number = 3 */
  1421.      if_index_value = mkDPIset("1.3.6.1.2.1.2.2.1.1", SNMP_TYPE_NUMBER,
  1422.              sizeof(unsigned long), &data);
  1423.      packet = mkDPItrap(2, 0, if_index_value);
  1424.      len = *packet * 256 + *(packet + 1);
  1425.      len += 2;  /* include length bytes */
  1426.      write(fd,packet,len);
  1427.  
  1428.    If the packet can be created, a pointer to a static buffer containing
  1429.    the packet contents is returned.  This is the same buffer used by
  1430.    mkDPIregister().  If an error is encountered while creating the
  1431.    packet, the null pointer (0) is returned.
  1432.  
  1433.    The length of the remainder packet is stored in the first two bytes
  1434.    of the packet, as demonstrated in the example above.
  1435.  
  1436.    NOTE:  mkDPItrap() always frees the passed parse tree.
  1437.  
  1438. PDPIPACKET
  1439.  
  1440.      #include "snmp_dpi.h"
  1441.  
  1442.      unsigned char *packet;
  1443.  
  1444.      struct snmp_dpi_hdr *hdr;
  1445.  
  1446.      hdr = pDPIpacket(packet)
  1447.  
  1448.    The pDPIpacket() function parses a DPI packet and returns a parse
  1449.    tree representing its contents.  The parse tree is dynamically
  1450.    allocated and contains copies of the information within the DPI
  1451.    packet.  After a successful call to pDPIpacket(), the packet may be
  1452.    disposed of in any manner the application chooses without affecting
  1453.    the contents of the parse tree.  If an error is encountered during
  1454.    the parse, the null pointer (0) is returned.
  1455.  
  1456.  
  1457.  
  1458. Carpenter & Wijnen                                             [Page 26]
  1459.  
  1460. RFC 1228                        SNMP-DPI                        May 1991
  1461.  
  1462.  
  1463.    NOTE:  the relevant parse tree structures are defined in the include
  1464.    file "snmp_dpi.h", and that file remains the definitive reference.
  1465.  
  1466.    The root of the parse tree is represented by a snmp_dpi_hdr
  1467.    structure:
  1468.  
  1469.      struct snmp_dpi_hdr {
  1470.          unsigned char  proto_major;
  1471.          unsigned char  proto_minor;
  1472.          unsigned char  proto_release;
  1473.  
  1474.          unsigned char  packet_type;
  1475.          union {
  1476.               struct dpi_get_packet    *dpi_get;
  1477.               struct dpi_next_packet   *dpi_next;
  1478.               struct dpi_set_packet    *dpi_set;
  1479.               struct dpi_resp_packet   *dpi_response;
  1480.               struct dpi_trap_packet   *dpi_trap;
  1481.          } packet_body;
  1482.      };
  1483.  
  1484.    The field of immediate interest is packet_type.  This field can have
  1485.    one of the following values (which are defined in the include file
  1486.    "snmp_dpi.h"):
  1487.  
  1488.       o   SNMP_DPI_GET
  1489.       o   SNMP_DPI_GET_NEXT
  1490.       o   SNMP_DPI_SET
  1491.  
  1492.    The packet_type field indicates what request is being made of the DPI
  1493.    client.  For each of these requests, the remainder of the packet_body
  1494.    will be different.
  1495.  
  1496.    If a get request is indicated, the object ID of the desired variable
  1497.    is passed in a dpi_get_packet structure:
  1498.  
  1499.      struct dpi_get_packet {
  1500.          char *object_id;
  1501.      };
  1502.  
  1503.    A get-next request is similar, but the dpi_next_packet structure also
  1504.    contains the object ID prefix of the group that is currently being
  1505.    traversed:
  1506.  
  1507.      struct dpi_next_packet {
  1508.          char *object_id;
  1509.          char *group_id;
  1510.      };
  1511.  
  1512.  
  1513.  
  1514. Carpenter & Wijnen                                             [Page 27]
  1515.  
  1516. RFC 1228                        SNMP-DPI                        May 1991
  1517.  
  1518.  
  1519.    If the next object whose object ID lexicographically follows the
  1520.    object ID indicated by object_id does not begin with the suffix
  1521.    indicated by group_id, the DPI client must return an error indication
  1522.    of SNMP_NO_SUCH_NAME.
  1523.  
  1524.    A set request has the most amount of data associated with it and this
  1525.    is contained in a dpi_set_packet structure:
  1526.  
  1527.      struct dpi_set_packet {
  1528.          char      *object_id;
  1529.          unsigned char  type;
  1530.          unsigned short value_len;
  1531.          char      *value;
  1532.      };
  1533.  
  1534.    The object ID of the variable to be modified is indicated by
  1535.    object_id The type of the variable is provided in type and may have
  1536.    one of the following values:
  1537.  
  1538.       o   SNMP_TYPE_NUMBER
  1539.       o   SNMP_TYPE_STRING
  1540.       o   SNMP_TYPE_OBJECT
  1541.       o   SNMP_TYPE_EMPTY
  1542.       o   SNMP_TYPE_INTERNET
  1543.       o   SNMP_TYPE_COUNTER
  1544.       o   SNMP_TYPE_GAUGE
  1545.       o   SNMP_TYPE_TICKS
  1546.  
  1547.    The length of the value to be set is stored in value_len and value
  1548.    contains a pointer to the value.
  1549.  
  1550.    NOTE:  the storage pointed to by value will be reclaimed when the
  1551.    parse tree is freed.  The DPI client must make provision for copying
  1552.    the value contents.
  1553.  
  1554. FDPIPARSE
  1555.  
  1556.      #include "snmp_dpi.h"
  1557.  
  1558.      struct snmp_dpi_hdr *hdr;
  1559.  
  1560.      fDPIparse(hdr);
  1561.  
  1562.    The routine fDPIparse() frees a parse tree previously created by a
  1563.    call to pDPIpacket This routine is declared as void--it has no return
  1564.    value.
  1565.  
  1566.    NOTE:  after calling fDPIparse(), no further references to the parse
  1567.  
  1568.  
  1569.  
  1570. Carpenter & Wijnen                                             [Page 28]
  1571.  
  1572. RFC 1228                        SNMP-DPI                        May 1991
  1573.  
  1574.  
  1575.    tree can be made.
  1576.  
  1577. AGENT IMPLEMENTATION ISSUES
  1578.  
  1579.    Although the SNMP DPI protocol is completely documented in this
  1580.    paper, the document itself is somewhat biased towards clearly
  1581.    defining the interface provided to sub-agents (i.e., it provides a
  1582.    specification of a C language API).  This detailed coverage is
  1583.    possible because the client side of the interface is completely
  1584.    self-contained.
  1585.  
  1586.    The agent side of the interface has to be integrated into individual
  1587.    vendor implementations, many of which may have a unique
  1588.    organizational structure in an attempt to address various performance
  1589.    and storage constraints.  This makes it infeasible to provide much
  1590.    more than suggestions for SNMP agent implementers.  Unfortunately,
  1591.    this leaves room for a large amount of interpretation which can lead
  1592.    to implementations that don't necessarily work they way they should-
  1593.    -too much ambiguity can be a bad thing.
  1594.  
  1595.    The following characteristics of an agent implementation are to be
  1596.    considered mandatory:
  1597.  
  1598. DUPLICATE REGISTRATIONS
  1599.  
  1600.    With this release of the protocol, order of registration is
  1601.    significant.  The last sub-agent to register a variable is the one
  1602.    that is deemed to be authoritative.  Variables implemented by the
  1603.    base SNMP agent are considered to have been registered prior to any
  1604.    sub-agent registrations.  Thus sub-agents may re-implement support
  1605.    for variables that were incorrectly implemented by a vendor.
  1606.  
  1607. AUTOMATIC DEREGISTRATION ON CLOSE
  1608.  
  1609.    All SNMP DPI connections are carried over a stream connection.  When
  1610.    the connection is closed by the client (no matter what the cause),
  1611.    the agent must automatically unregister all of the variables that
  1612.    were registered by the sub-agent.
  1613.  
  1614. TIMELY RESPONSE CONSTRAINTS
  1615.  
  1616.    A sub-agent must respond to a request in a timely fashion.  In this
  1617.    version of the protocol, we specify that a sub-agent must respond to
  1618.    a request by the SNMP agent within 5 seconds.  If the sub-agent does
  1619.    not respond in time, the SNMP agent should terminate the connection
  1620.    and unregister all of the variables that were previously registered
  1621.    by the sub-agent in question.
  1622.  
  1623.  
  1624.  
  1625.  
  1626. Carpenter & Wijnen                                             [Page 29]
  1627.  
  1628. RFC 1228                        SNMP-DPI                        May 1991
  1629.  
  1630.  
  1631.    NOTE:  agent implementations that do not have access to a timer may
  1632.    not be able to implement this.  In that case, they leave themselves
  1633.    open to being placed in a state where they are blocked forever if the
  1634.    sub-agent malfunctions.
  1635.  
  1636. SUPPORT FOR MULTIPLE MIB VIEWS
  1637.  
  1638.    Some agents allow different MIB views to be selected based on the
  1639.    community name used.  It is not the intention of this document to
  1640.    pass judgement on the various approaches that have been proposed or
  1641.    implemented, but instead merely to recognize the existence of
  1642.    implementations that support this feature.
  1643.  
  1644.    The point of this discussion is to specify clearly that objects
  1645.    supported by an SNMP DPI sub-agent are to be registered under the MIB
  1646.    view that was selected by the community name used in the SNMP GET
  1647.    request that obtained the DPI_port value.
  1648.  
  1649.    The SNMP DPI does not specify a reserved port, but instead sub-agents
  1650.    bootstrap themselves by making an SNMP GET request for the DPI_port
  1651.    variable.  This variable represents the TCP port to which the sub-
  1652.    agent should connect.  It should be understood that there is no
  1653.    reason why the SNMP agent cannot have several listens (passive opens)
  1654.    active, each corresponding to a distinct MIB view.  The port number
  1655.    returned then would be different based on the community name used in
  1656.    the SNMP GET request for the DPI_port variable.
  1657.  
  1658. CONSIDERATIONS FOR THE NEXT RELEASE
  1659.  
  1660.    The SNMP DPI protocol makes provision for extension and parallel use
  1661.    of potentially incompatible releases.  The discussion above documents
  1662.    the protocol as it is currently in use and has not discussed features
  1663.    of interest that should be considered for a future revision.
  1664.  
  1665. UNREGISTER
  1666.  
  1667.    For closure, an UNREGISTER request could be of use.
  1668.  
  1669. SUPPORT FOR ATOMIC SETS
  1670.  
  1671.    The SNMP protocol [1] specifies that:
  1672.  
  1673.       Each variable assignment specified by the SetRequest-PDU should be
  1674.       effected as if simultaneously set with respect to all other
  1675.       assignments specified in the same message.
  1676.  
  1677.    The SNMP DPI has no provision for backing out a successfully
  1678.    processed SET request if one of the subsequent variable assignments
  1679.  
  1680.  
  1681.  
  1682. Carpenter & Wijnen                                             [Page 30]
  1683.  
  1684. RFC 1228                        SNMP-DPI                        May 1991
  1685.  
  1686.  
  1687.    fails.  This omission is a reflection of several biases:
  1688.  
  1689.    o   the SNMP DPI was intended to be light-weight.
  1690.  
  1691.    o   a belief that the SNMP RFC prescribes semantics which are infeasible
  1692.        to implement unless the range of applications is restricted.
  1693.  
  1694.    It has been suggested that a new request, TEST_SET, be added to the
  1695.    DPI protocol.  Processing of a SET request would then be performed as
  1696.    follows:
  1697.  
  1698.    o   all variables would be processed using TEST_SET unless any error
  1699.        occurred.  The subagents would verify that they could process the
  1700.        request.
  1701.  
  1702.    o   if no error occurred, each of the variables would be reprocessed,
  1703.        this time with a SET request.
  1704.  
  1705.    A problem with such an approach is that it relies on the TEST_SET
  1706.    operation to make an assertion that the request can be successfully
  1707.    performed.  If this is not possible, then it cannot be asserted that
  1708.    the prescribed semantics will be provided.  Such situations do exist,
  1709.    for example, a SET request that causes the far-end channel service
  1710.    unit to be looped up--one does not know if the operation will be
  1711.    successful until it is performed.
  1712.  
  1713. SAMPLE SNMP DPI API IMPLEMENTATION
  1714.  
  1715.    The following C language sources show an example implementation of
  1716.    the SNMP DPI Application Programming Interface as it would be exposed
  1717.    to the sub-agents.
  1718.  
  1719. SAMPLE SNMP DPI INCLUDE FILE
  1720.  
  1721.   /* SNMP distributed program interface */
  1722.  
  1723.   #define SNMP_DPI_GET            1
  1724.   #define SNMP_DPI_GET_NEXT       2
  1725.   #define SNMP_DPI_SET            3
  1726.   #define SNMP_DPI_TRAP           4
  1727.   #define SNMP_DPI_RESPONSE       5
  1728.   #define SNMP_DPI_REGISTER       6
  1729.  
  1730.   #define SNMP_DPI_PROTOCOL       2
  1731.   #define SNMP_DPI_VERSION        1
  1732.   #define SNMP_DPI_RELEASE        0
  1733.  
  1734.   /* SNMP error codes from RFC 1098 (1067) */
  1735.  
  1736.  
  1737.  
  1738. Carpenter & Wijnen                                             [Page 31]
  1739.  
  1740. RFC 1228                        SNMP-DPI                        May 1991
  1741.  
  1742.  
  1743.   #define SNMP_NO_ERROR           0
  1744.   #define SNMP_TOO_BIG            1
  1745.   #define SNMP_NO_SUCH_NAME       2
  1746.   #define SNMP_BAD_VALUE          3
  1747.   #define SNMP_READ_ONLY          4
  1748.   #define SNMP_GEN_ERR            5
  1749.  
  1750.   /* variable types */
  1751.   #define SNMP_TYPE_TEXT          0       /* textual representation */
  1752.   #define SNMP_TYPE_NUMBER        (128|1) /* number */
  1753.   #define SNMP_TYPE_STRING        2       /* text string */
  1754.   #define SNMP_TYPE_OBJECT        3       /* object identifier */
  1755.   #define SNMP_TYPE_EMPTY         4       /* no value */
  1756.   #define SNMP_TYPE_INTERNET      (128|5) /* internet address */
  1757.   #define SNMP_TYPE_COUNTER       (128|6) /* counter */
  1758.   #define SNMP_TYPE_GAUGE         (128|7) /* gauge */
  1759.   #define SNMP_TYPE_TICKS         (128|8) /* time ticks (1/100th sec) */
  1760.   #define SNMP_TYPE_MASK          0x7f    /* mask for type */
  1761.  
  1762.  
  1763.   struct dpi_get_packet {
  1764.           char    *object_id;
  1765.   };
  1766.  
  1767.   struct dpi_next_packet {
  1768.           char    *object_id;
  1769.           char    *group_id;
  1770.   };
  1771.  
  1772.   struct dpi_set_packet {
  1773.           char            *object_id;
  1774.           unsigned char   type;
  1775.           unsigned short  value_len;
  1776.           char            *value;
  1777.   };
  1778.  
  1779.   struct dpi_resp_packet {
  1780.           unsigned char   ret_code;
  1781.           struct dpi_set_packet   *ret_data;
  1782.   };
  1783.  
  1784.   struct dpi_trap_packet {
  1785.           unsigned char   generic;
  1786.           unsigned char   specific;
  1787.           struct dpi_set_packet   *info;
  1788.   };
  1789.  
  1790.   struct snmp_dpi_hdr {
  1791.  
  1792.  
  1793.  
  1794. Carpenter & Wijnen                                             [Page 32]
  1795.  
  1796. RFC 1228                        SNMP-DPI                        May 1991
  1797.  
  1798.  
  1799.           unsigned char   proto_major;
  1800.           unsigned char   proto_minor;
  1801.           unsigned char   proto_release;
  1802.  
  1803.           unsigned char   packet_type;
  1804.           union {
  1805.                   struct dpi_get_packet   *dpi_get;
  1806.                   struct dpi_next_packet  *dpi_next;
  1807.                   struct dpi_set_packet   *dpi_set;
  1808.                   struct dpi_resp_packet  *dpi_response;
  1809.                   struct dpi_trap_packet  *dpi_trap;
  1810.           } packet_body;
  1811.   };
  1812.  
  1813.   extern struct snmp_dpi_hdr *pDPIpacket();
  1814.   extern void fDPIparse();
  1815.   extern unsigned char *mkMIBquery();
  1816.   extern unsigned char *mkDPIregister();
  1817.   extern unsigned char *mkDPIresponse();
  1818.   extern unsigned char *mkDPItrap();
  1819.   extern struct dpi_set_packet *mkDPIset();
  1820.  
  1821. SAMPLE QUERY_DPI_PORT() FUNCTION
  1822.  
  1823.  
  1824.   #ifdef VM
  1825.  
  1826.   #include <manifest.h>
  1827.   #include <snmp_vm.h>
  1828.   #include <bsdtime.h>
  1829.   #include <bsdtypes.h>
  1830.   #include <socket.h>
  1831.   #include <in.h>
  1832.   #include <netdb.h>
  1833.   #include <inet.h>
  1834.  
  1835.   #else
  1836.  
  1837.   #include <sys/time.h>
  1838.   #include <sys/types.h>
  1839.   #include <sys/socket.h>
  1840.   #include <netinet/in.h>
  1841.   #include <netdb.h>
  1842.   #include <arpa/inet.h>
  1843.  
  1844.   #endif
  1845.  
  1846.   static unsigned char asn1_hdr[] = {0x30};
  1847.  
  1848.  
  1849.  
  1850. Carpenter & Wijnen                                             [Page 33]
  1851.  
  1852. RFC 1228                        SNMP-DPI                        May 1991
  1853.  
  1854.  
  1855.   /* insert length of remaining packet, not including this */
  1856.   static unsigned char version[] = {0x02, 0x01, 0x00, 0x04};
  1857.  
  1858.   /* integer, len=1, value=0, string */
  1859.   /* insert community name length and community name */
  1860.   static unsigned char request[] = {
  1861.       0xa0, 0x1b,         /* get request, len=0x1b */
  1862.       0x02, 0x01, 0x01,   /* integer, len=1,request_id = 1 */
  1863.       0x02, 0x01, 0x00,   /* integer, len=1, error_status = 0 */
  1864.       0x02, 0x01, 0x00,   /* integer, len=1, error_index = 0 */
  1865.       0x30, 0x10,         /* varbind list, len=0x10 */
  1866.       0x30, 0x0e,         /* varbind , len=0x0e */
  1867.       0x06, 0x0a,         /* object ID, len=0x0a */
  1868.       0x2b, 0x06, 0x01, 0x04, 0x01, 0x02, 0x02, 0x01, 0x01, 0x00,
  1869.       0x05, 0x00          /* value, len = 0 */
  1870.   };
  1871.  
  1872.   static          extract_DPI_port();
  1873.  
  1874.   query_DPI_port(hostname, community_name)
  1875.   char           *hostname;
  1876.   char           *community_name;
  1877.   {
  1878.       int             community_len;
  1879.       int             rc;
  1880.  
  1881.       community_len = strlen(community_name);
  1882.  
  1883.       rc = _query_DPI_port(hostname, community_name, community_len);
  1884.       return (rc);
  1885.   }
  1886.  
  1887.   /* use if community_name has embedded nulls */
  1888.  
  1889.   _query_DPI_port(hostname, community_name, community_len)
  1890.   char           *hostname;
  1891.   char           *community_name;
  1892.   int             community_len;
  1893.   {
  1894.       unsigned char   packet[1024];
  1895.       int             packet_len;
  1896.       int             remaining_len;
  1897.       int             fd, rc, sock_len;
  1898.       struct sockaddr_in sock, dest_sock;
  1899.       struct timeval  timeout;
  1900.       unsigned long   host_addr, read_mask;
  1901.       int             tries;
  1902.  
  1903.  
  1904.  
  1905.  
  1906. Carpenter & Wijnen                                             [Page 34]
  1907.  
  1908. RFC 1228                        SNMP-DPI                        May 1991
  1909.  
  1910.  
  1911.       host_addr = lookup_host(hostname);
  1912.       packet_len = 0;
  1913.       bcopy(asn1_hdr, packet, sizeof(asn1_hdr));
  1914.       packet_len += sizeof(asn1_hdr);
  1915.  
  1916.       remaining_len = sizeof(version) + 1 +
  1917.         community_len + sizeof(request);
  1918.  
  1919.       packet[packet_len++] = remaining_len & 0xff;
  1920.       bcopy(version, packet + packet_len, sizeof(version));
  1921.       packet_len += sizeof(version);
  1922.       packet[packet_len++] = community_len & 0xff;
  1923.       bcopy(community_name, packet + packet_len, community_len);
  1924.       packet_len += community_len;
  1925.       bcopy(request, packet + packet_len, sizeof(request));
  1926.       packet_len += sizeof(request);
  1927.  
  1928.       fd = socket(AF_INET, SOCK_DGRAM, 0);
  1929.       if (fd < 0) {
  1930.       return (-1);
  1931.       }
  1932.       bzero(&sock, sizeof(sock));
  1933.       sock.sin_family = AF_INET;
  1934.       sock.sin_port = 0;
  1935.       sock.sin_addr.s_addr = 0;
  1936.       rc = bind(fd, &sock, sizeof(sock));
  1937.       if (rc < 0)
  1938.       return (-1);
  1939.       timeout.tv_sec = 3;
  1940.       timeout.tv_usec = 0;
  1941.       bzero(&dest_sock, sizeof(dest_sock));
  1942.       dest_sock.sin_family = AF_INET;
  1943.       dest_sock.sin_port = htons(161);
  1944.       dest_sock.sin_addr.s_addr = host_addr;
  1945.  
  1946.       tries = 0;
  1947.       while (++tries < 4) {
  1948.       rc = sendto(fd, packet, packet_len, 0, &dest_sock,
  1949.                sizeof(dest_sock));
  1950.       read_mask = 1 << fd;
  1951.       rc = select(read_mask + 1, &read_mask, 0, 0, &timeout);
  1952.       if (rc <= 0)
  1953.           continue;
  1954.       sock_len = sizeof(dest_sock);
  1955.       packet_len = recvfrom(fd, packet, sizeof(packet), 0,
  1956.                       &dest_sock, &sock_len);
  1957.       if (packet_len <= 0) {
  1958.           return (-1);
  1959.  
  1960.  
  1961.  
  1962. Carpenter & Wijnen                                             [Page 35]
  1963.  
  1964. RFC 1228                        SNMP-DPI                        May 1991
  1965.  
  1966.  
  1967.       }
  1968.       rc = extract_DPI_port(packet, packet_len);
  1969.       return (rc);
  1970.       }
  1971.       return (-1);
  1972.   }
  1973.  
  1974.   static          extract_DPI_port(packet, len)
  1975.   unsigned char   packet[];
  1976.   int             len;
  1977.  
  1978.   {
  1979.       int             offset;
  1980.       int             port;
  1981.  
  1982.       /* should do error checking (like for noSuchName) */
  1983.       offset = len - 2;
  1984.       port = (packet[offset] << 8) + packet[offset + 1];
  1985.       return (port);
  1986.   }
  1987.  
  1988. SAMPLE DPI FUNCTIONS
  1989.  
  1990.   /* DPI parser */
  1991.  
  1992.   #ifdef VM
  1993.   #include "manifest.h"
  1994.   #endif
  1995.  
  1996.   #include "snmp_dpi.h"
  1997.  
  1998.   static struct dpi_get_packet *pDPIget();
  1999.   static struct dpi_next_packet *pDPInext();
  2000.   static struct dpi_set_packet *pDPIset();
  2001.   static struct dpi_trap_packet *pDPItrap();
  2002.   static struct dpi_resp_packet *pDPIresponse();
  2003.  
  2004.   static void     fDPIget();
  2005.   static void     fDPInext();
  2006.   static void     fDPIset();
  2007.   static void     fDPItrap();
  2008.   static void     fDPIresponse();
  2009.  
  2010.   static int      cDPIget();
  2011.   static int      cDPInext();
  2012.   static int      cDPIset();
  2013.   static int      cDPItrap();
  2014.   static int      cDPIresponse();
  2015.  
  2016.  
  2017.  
  2018. Carpenter & Wijnen                                             [Page 36]
  2019.  
  2020. RFC 1228                        SNMP-DPI                        May 1991
  2021.  
  2022.  
  2023.   static struct snmp_dpi_hdr *mkDPIhdr();
  2024.   static struct dpi_get_packet *mkDPIget();
  2025.   static struct dpi_next_packet *mkDPInext();
  2026.   struct dpi_set_packet *mkDPIset();
  2027.  
  2028.  
  2029.   extern char    *malloc();
  2030.  
  2031.   static unsigned char new_packet[1024];
  2032.   static int      packet_len;
  2033.  
  2034.   struct snmp_dpi_hdr *pDPIpacket(packet)
  2035.   unsigned char  *packet;
  2036.   {
  2037.       struct snmp_dpi_hdr *hdr;
  2038.       int             len, offset;
  2039.  
  2040.  
  2041.       hdr = (struct snmp_dpi_hdr *) malloc(sizeof(struct snmp_dpi_hdr));
  2042.       if (hdr == 0)
  2043.           return (0);
  2044.  
  2045.       len = (packet[0] << 8) + packet[1];
  2046.       len += 2;
  2047.       offset = 2;
  2048.       hdr->proto_major = packet[offset++];
  2049.       hdr->proto_minor = packet[offset++];
  2050.       hdr->proto_release = packet[offset++];
  2051.       hdr->packet_type = packet[offset++];
  2052.       switch (hdr->packet_type) {
  2053.       case SNMP_DPI_GET:
  2054.       case SNMP_DPI_REGISTER:
  2055.           hdr->packet_body.dpi_get =
  2056.             pDPIget(packet + offset, len - offset);
  2057.           break;
  2058.       case SNMP_DPI_GET_NEXT:
  2059.           hdr->packet_body.dpi_next =
  2060.             pDPInext(packet + offset, len - offset);
  2061.           break;
  2062.       case SNMP_DPI_SET:
  2063.           hdr->packet_body.dpi_set =
  2064.             pDPIset(packet + offset, len - offset);
  2065.           break;
  2066.       case SNMP_DPI_TRAP:
  2067.           hdr->packet_body.dpi_trap =
  2068.             pDPItrap(packet + offset, len - offset);
  2069.           break;
  2070.       case SNMP_DPI_RESPONSE:
  2071.  
  2072.  
  2073.  
  2074. Carpenter & Wijnen                                             [Page 37]
  2075.  
  2076. RFC 1228                        SNMP-DPI                        May 1991
  2077.  
  2078.  
  2079.           hdr->packet_body.dpi_response =
  2080.             pDPIresponse(packet + offset, len - offset);
  2081.           break;
  2082.       }
  2083.       return (hdr);
  2084.   }
  2085.  
  2086.   static struct dpi_get_packet *pDPIget(packet, len)
  2087.   unsigned char  *packet;
  2088.   int             len;
  2089.   {
  2090.       struct dpi_get_packet *get;
  2091.       int             l;
  2092.  
  2093.       get = (struct dpi_get_packet *)
  2094.         malloc(sizeof(struct dpi_get_packet));
  2095.       if (get == 0)
  2096.           return (0);
  2097.       l = strlen(packet) + 1;
  2098.       get->object_id = malloc(l);
  2099.       strcpy(get->object_id, packet);
  2100.       return (get);
  2101.   }
  2102.  
  2103.   static struct dpi_next_packet *pDPInext(packet, len)
  2104.   unsigned char  *packet;
  2105.   int             len;
  2106.   {
  2107.       struct dpi_next_packet *next;
  2108.       int             l;
  2109.       unsigned char  *cp;
  2110.  
  2111.       next = (struct dpi_next_packet *)
  2112.         malloc(sizeof(struct dpi_next_packet));
  2113.       if (next == 0)
  2114.           return (0);
  2115.       cp = packet;
  2116.       l = strlen(cp) + 1;
  2117.       next->object_id = malloc(l);
  2118.       strcpy(next->object_id, cp);
  2119.       cp += l;
  2120.       l = strlen(cp) + 1;
  2121.       next->group_id = malloc(l);
  2122.       strcpy(next->group_id, cp);
  2123.       return (next);
  2124.   }
  2125.  
  2126.   static struct dpi_set_packet *pDPIset(packet, len)
  2127.  
  2128.  
  2129.  
  2130. Carpenter & Wijnen                                             [Page 38]
  2131.  
  2132. RFC 1228                        SNMP-DPI                        May 1991
  2133.  
  2134.  
  2135.   unsigned char  *packet;
  2136.   int             len;
  2137.   {
  2138.       struct dpi_set_packet *set;
  2139.       int             l;
  2140.       unsigned char  *cp;
  2141.  
  2142.       if (len == 0)
  2143.           return (0);     /* nothing to parse */
  2144.       set = (struct dpi_set_packet *)
  2145.         malloc(sizeof(struct dpi_set_packet));
  2146.       if (set == 0)
  2147.           return (0);
  2148.  
  2149.       cp = packet;
  2150.       l = strlen(cp) + 1;
  2151.       set->object_id = malloc(l);
  2152.       strcpy(set->object_id, cp);
  2153.       cp += l;
  2154.       set->type = *(cp++);
  2155.       l = (*(cp++) << 8);
  2156.       l += *(cp++);
  2157.       set->value_len = l;
  2158.       set->value = malloc(l);
  2159.       bcopy(cp, set->value, l);
  2160.       return (set);
  2161.   }
  2162.  
  2163.   static struct dpi_trap_packet *pDPItrap(packet, len)
  2164.   unsigned char  *packet;
  2165.   int             len;
  2166.   {
  2167.       struct dpi_trap_packet *trap;
  2168.  
  2169.       trap = (struct dpi_trap_packet *)
  2170.         malloc(sizeof(struct dpi_trap_packet));
  2171.       if (trap == 0)
  2172.           return (0);
  2173.  
  2174.       trap->generic = *packet;
  2175.       trap->specific = *(packet + 1);
  2176.       trap->info = pDPIset(packet + 2, len - 2);
  2177.       return (trap);
  2178.   }
  2179.  
  2180.   static struct dpi_resp_packet *pDPIresponse(packet, len)
  2181.   unsigned char  *packet;
  2182.   int             len;
  2183.  
  2184.  
  2185.  
  2186. Carpenter & Wijnen                                             [Page 39]
  2187.  
  2188. RFC 1228                        SNMP-DPI                        May 1991
  2189.  
  2190.  
  2191.   {
  2192.       struct dpi_resp_packet *resp;
  2193.  
  2194.       resp = (struct dpi_resp_packet *)
  2195.         malloc(sizeof(struct dpi_resp_packet));
  2196.       if (resp == 0)
  2197.           return (0);
  2198.  
  2199.       resp->ret_code = *packet;
  2200.       resp->ret_data = pDPIset(packet + 1, len - 1);
  2201.       return (resp);
  2202.   }
  2203.  
  2204.   void            fDPIparse(hdr)
  2205.   struct snmp_dpi_hdr *hdr;
  2206.   {
  2207.       if (hdr == 0)
  2208.           return;
  2209.       switch (hdr->packet_type) {
  2210.       case SNMP_DPI_GET:
  2211.       case SNMP_DPI_REGISTER:
  2212.           fDPIget(hdr);
  2213.           break;
  2214.       case SNMP_DPI_GET_NEXT:
  2215.           fDPInext(hdr);
  2216.           break;
  2217.       case SNMP_DPI_SET:
  2218.           fDPIset(hdr);
  2219.           break;
  2220.       case SNMP_DPI_TRAP:
  2221.           fDPItrap(hdr);
  2222.           break;
  2223.       case SNMP_DPI_RESPONSE:
  2224.           fDPIresponse(hdr);
  2225.           break;
  2226.       }
  2227.       free(hdr);
  2228.   }
  2229.  
  2230.   static void     fDPIget(hdr)
  2231.   struct snmp_dpi_hdr *hdr;
  2232.   {
  2233.       struct dpi_get_packet *get;
  2234.  
  2235.       get = hdr->packet_body.dpi_get;
  2236.       if (get == 0)
  2237.           return;
  2238.       if (get->object_id)
  2239.  
  2240.  
  2241.  
  2242. Carpenter & Wijnen                                             [Page 40]
  2243.  
  2244. RFC 1228                        SNMP-DPI                        May 1991
  2245.  
  2246.  
  2247.           free(get->object_id);
  2248.       free(get);
  2249.   }
  2250.  
  2251.   static void     fDPInext(hdr)
  2252.   struct snmp_dpi_hdr *hdr;
  2253.   {
  2254.       struct dpi_next_packet *next;
  2255.  
  2256.       next = hdr->packet_body.dpi_next;
  2257.       if (next == 0)
  2258.           return;
  2259.       if (next->object_id)
  2260.           free(next->object_id);
  2261.       if (next->group_id)
  2262.           free(next->group_id);
  2263.       free(next);
  2264.   }
  2265.  
  2266.   static void     fDPIset(hdr)
  2267.   struct snmp_dpi_hdr *hdr;
  2268.   {
  2269.       struct dpi_set_packet *set;
  2270.  
  2271.       set = hdr->packet_body.dpi_set;
  2272.       if (set == 0)
  2273.           return;
  2274.       if (set->object_id)
  2275.           free(set->object_id);
  2276.       if (set->value)
  2277.           free(set->value);
  2278.       free(set);
  2279.   }
  2280.  
  2281.   static void     fDPItrap(hdr)
  2282.   struct snmp_dpi_hdr *hdr;
  2283.   {
  2284.       struct dpi_trap_packet *trap;
  2285.       struct dpi_set_packet *set;
  2286.  
  2287.       trap = hdr->packet_body.dpi_trap;
  2288.       if (trap == 0)
  2289.           return;
  2290.  
  2291.       set = trap->info;
  2292.       if (set != 0) {
  2293.           if (set->object_id)
  2294.               free(set->object_id);
  2295.  
  2296.  
  2297.  
  2298. Carpenter & Wijnen                                             [Page 41]
  2299.  
  2300. RFC 1228                        SNMP-DPI                        May 1991
  2301.  
  2302.  
  2303.           if (set->value)
  2304.               free(set->value);
  2305.           free(set);
  2306.       }
  2307.       free(trap);
  2308.   }
  2309.  
  2310.   static void     fDPIresponse(hdr)
  2311.   struct snmp_dpi_hdr *hdr;
  2312.   {
  2313.       struct dpi_resp_packet *resp;
  2314.       struct dpi_set_packet *set;
  2315.  
  2316.       resp = hdr->packet_body.dpi_response;
  2317.       if (resp == 0)
  2318.           return;
  2319.  
  2320.       set = resp->ret_data;
  2321.       if (set != 0) {
  2322.           if (set->object_id)
  2323.               free(set->object_id);
  2324.           if (set->value)
  2325.               free(set->value);
  2326.           free(set);
  2327.       }
  2328.       free(resp);
  2329.   }
  2330.  
  2331.   unsigned char  *cDPIpacket(hdr)
  2332.   struct snmp_dpi_hdr *hdr;
  2333.   {
  2334.       int             rc, len;
  2335.       if (hdr == 0) {
  2336.           return (0);
  2337.       }
  2338.       packet_len = 2;
  2339.       new_packet[packet_len++] = hdr->proto_major;
  2340.       new_packet[packet_len++] = hdr->proto_minor;
  2341.       new_packet[packet_len++] = hdr->proto_release;
  2342.       new_packet[packet_len++] = hdr->packet_type;
  2343.       switch (hdr->packet_type) {
  2344.       case SNMP_DPI_GET:
  2345.       case SNMP_DPI_REGISTER:
  2346.           rc = cDPIget(hdr->packet_body.dpi_get);
  2347.           break;
  2348.       case SNMP_DPI_GET_NEXT:
  2349.           rc = cDPInext(hdr->packet_body.dpi_next);
  2350.           break;
  2351.  
  2352.  
  2353.  
  2354. Carpenter & Wijnen                                             [Page 42]
  2355.  
  2356. RFC 1228                        SNMP-DPI                        May 1991
  2357.  
  2358.  
  2359.       case SNMP_DPI_SET:
  2360.           rc = cDPIset(hdr->packet_body.dpi_set);
  2361.           break;
  2362.       case SNMP_DPI_TRAP:
  2363.           rc = cDPItrap(hdr->packet_body.dpi_trap);
  2364.           break;
  2365.       case SNMP_DPI_RESPONSE:
  2366.           rc = cDPIresponse(hdr->packet_body.dpi_response);
  2367.           break;
  2368.       }
  2369.       if (rc == -1)
  2370.           return (0);
  2371.       len = packet_len - 2;
  2372.       new_packet[1] = len & 0xff;
  2373.       len >>= 8;
  2374.       new_packet[0] = len & 0xff;
  2375.       return (new_packet);
  2376.   }
  2377.  
  2378.   static int      cDPIget(get)
  2379.   struct dpi_get_packet *get;
  2380.   {
  2381.       if (get->object_id == 0)
  2382.           return (-1);
  2383.  
  2384.       strcpy(&new_packet[packet_len], get->object_id);
  2385.       packet_len += strlen(get->object_id) + 1;
  2386.       return (0);
  2387.   }
  2388.  
  2389.   static int      cDPInext(next)
  2390.   struct dpi_next_packet *next;
  2391.   {
  2392.       if (next->object_id == 0)
  2393.           return (-1);
  2394.       if (next->group_id == 0)
  2395.           return (-1);
  2396.  
  2397.       strcpy(&new_packet[packet_len], next->object_id);
  2398.       packet_len += strlen(next->object_id) + 1;
  2399.       strcpy(&new_packet[packet_len], next->group_id);
  2400.       packet_len += strlen(next->group_id) + 1;
  2401.       return (0);
  2402.   }
  2403.  
  2404.   static int      cDPIset(set)
  2405.   struct dpi_set_packet *set;
  2406.   {
  2407.  
  2408.  
  2409.  
  2410. Carpenter & Wijnen                                             [Page 43]
  2411.  
  2412. RFC 1228                        SNMP-DPI                        May 1991
  2413.  
  2414.  
  2415.       int             len;
  2416.  
  2417.       if (set->object_id == 0)
  2418.           return (-1);
  2419.       if ((set->value == 0) && (set->value_len != 0))
  2420.           return (-1);
  2421.  
  2422.       strcpy(&new_packet[packet_len], set->object_id);
  2423.       packet_len += strlen(set->object_id) + 1;
  2424.       new_packet[packet_len++] = set->type;
  2425.       len = set->value_len >> 8;
  2426.       new_packet[packet_len++] = len & 0xff;
  2427.       new_packet[packet_len++] = set->value_len & 0xff;
  2428.       bcopy(set->value, &new_packet[packet_len], set->value_len);
  2429.       packet_len += set->value_len;
  2430.       return (0);
  2431.   }
  2432.  
  2433.   static int      cDPIresponse(resp)
  2434.   struct dpi_resp_packet *resp;
  2435.   {
  2436.       int             rc;
  2437.  
  2438.       if (resp == 0)
  2439.           return (-1);
  2440.  
  2441.       new_packet[packet_len++] = resp->ret_code;
  2442.       if (resp->ret_data != 0) {
  2443.           rc = cDPIset(resp->ret_data);
  2444.       } else
  2445.           rc = 0;
  2446.       return (rc);
  2447.   }
  2448.  
  2449.   static int      cDPItrap(trap)
  2450.   struct dpi_trap_packet *trap;
  2451.   {
  2452.       int             rc;
  2453.  
  2454.       new_packet[packet_len++] = trap->generic;
  2455.       new_packet[packet_len++] = trap->specific;
  2456.       if (trap->info != 0)
  2457.           rc = cDPIset(trap->info);
  2458.       else
  2459.           rc = 0;
  2460.       return (rc);
  2461.   }
  2462.  
  2463.  
  2464.  
  2465.  
  2466. Carpenter & Wijnen                                             [Page 44]
  2467.  
  2468. RFC 1228                        SNMP-DPI                        May 1991
  2469.  
  2470.  
  2471.   unsigned char  *mkMIBquery(cmd, oid_name, group_oid, type, len, value)
  2472.   int             cmd;
  2473.   char           *oid_name, *group_oid;
  2474.   int             type, len;
  2475.   char           *value;
  2476.   {
  2477.       struct snmp_dpi_hdr *hdr;
  2478.       unsigned char  *cp;
  2479.  
  2480.       hdr = mkDPIhdr(cmd);
  2481.       if (hdr == 0)
  2482.           return (0);
  2483.       switch (hdr->packet_type) {
  2484.       case SNMP_DPI_GET:
  2485.       case SNMP_DPI_REGISTER:
  2486.           hdr->packet_body.dpi_get = mkDPIget(oid_name);
  2487.           break;
  2488.       case SNMP_DPI_GET_NEXT:
  2489.           hdr->packet_body.dpi_next = mkDPInext(oid_name, group_oid);
  2490.           break;
  2491.       case SNMP_DPI_SET:
  2492.           hdr->packet_body.dpi_set =
  2493.             mkDPIset(oid_name, type, len, value);
  2494.           break;
  2495.       }
  2496.       cp = cDPIpacket(hdr);
  2497.       fDPIparse(hdr);
  2498.       return (cp);
  2499.   }
  2500.  
  2501.   unsigned char  *mkDPIregister(oid_name)
  2502.   char           *oid_name;
  2503.   {
  2504.       return (mkMIBquery(SNMP_DPI_REGISTER, oid_name));
  2505.   }
  2506.  
  2507.   unsigned char  *mkDPIresponse(ret_code, value_list)
  2508.   int             ret_code;
  2509.   struct dpi_set_packet *value_list;
  2510.   {
  2511.       struct snmp_dpi_hdr *hdr;
  2512.       struct dpi_resp_packet *resp;
  2513.       unsigned char  *cp;
  2514.  
  2515.       hdr = mkDPIhdr(SNMP_DPI_RESPONSE);
  2516.       resp = (struct dpi_resp_packet *)
  2517.         malloc(sizeof(struct dpi_resp_packet));
  2518.       if (resp == 0) {
  2519.  
  2520.  
  2521.  
  2522. Carpenter & Wijnen                                             [Page 45]
  2523.  
  2524. RFC 1228                        SNMP-DPI                        May 1991
  2525.  
  2526.  
  2527.           free(hdr);
  2528.           return (0);
  2529.       }
  2530.       hdr->packet_body.dpi_response = resp;
  2531.       resp->ret_code = ret_code;
  2532.       resp->ret_data = value_list;
  2533.       cp = cDPIpacket(hdr);
  2534.       fDPIparse(hdr);
  2535.       return (cp);
  2536.   }
  2537.  
  2538.   unsigned char  *mkDPItrap(generic, specific, value_list)
  2539.   int             generic, specific;
  2540.   struct dpi_set_packet *value_list;
  2541.   {
  2542.       struct snmp_dpi_hdr *hdr;
  2543.       struct dpi_trap_packet *trap;
  2544.       unsigned char  *cp;
  2545.  
  2546.       hdr = mkDPIhdr(SNMP_DPI_TRAP);
  2547.       trap = (struct dpi_trap_packet *)
  2548.         malloc(sizeof(struct dpi_trap_packet));
  2549.       if (trap == 0) {
  2550.           free(hdr);
  2551.           return (0);
  2552.       }
  2553.       hdr->packet_body.dpi_trap = trap;
  2554.       trap->generic = generic;
  2555.       trap->specific = specific;
  2556.       trap->info = value_list;
  2557.       cp = cDPIpacket(hdr);
  2558.       fDPIparse(hdr);
  2559.       return (cp);
  2560.   }
  2561.  
  2562.   static struct snmp_dpi_hdr *mkDPIhdr(type)
  2563.   int             type;
  2564.   {
  2565.  
  2566.       struct snmp_dpi_hdr *hdr;
  2567.  
  2568.       hdr = (struct snmp_dpi_hdr *) malloc(sizeof(struct snmp_dpi_hdr));
  2569.       if (hdr == 0)
  2570.           return (0);
  2571.       hdr->proto_major = SNMP_DPI_PROTOCOL;
  2572.       hdr->proto_minor = SNMP_DPI_VERSION;
  2573.       hdr->proto_release = SNMP_DPI_RELEASE;
  2574.       hdr->packet_type = type;
  2575.  
  2576.  
  2577.  
  2578. Carpenter & Wijnen                                             [Page 46]
  2579.  
  2580. RFC 1228                        SNMP-DPI                        May 1991
  2581.  
  2582.  
  2583.       return (hdr);
  2584.   }
  2585.  
  2586.   static struct dpi_get_packet *mkDPIget(oid_name)
  2587.   char           *oid_name;
  2588.   {
  2589.       struct dpi_get_packet *get;
  2590.       int             l;
  2591.  
  2592.       get = (struct dpi_get_packet *)
  2593.         malloc(sizeof(struct dpi_get_packet));
  2594.       if (get == 0)
  2595.           return (0);
  2596.  
  2597.       l = strlen(oid_name) + 1;
  2598.       get->object_id = malloc(l);
  2599.       strcpy(get->object_id, oid_name);
  2600.       return (get);
  2601.   }
  2602.  
  2603.   static struct dpi_next_packet *mkDPInext(oid_name, group_oid)
  2604.   char           *oid_name;
  2605.   char           *group_oid;
  2606.   {
  2607.       struct dpi_next_packet *next;
  2608.       int             l;
  2609.  
  2610.       next = (struct dpi_next_packet *)
  2611.         malloc(sizeof(struct dpi_next_packet));
  2612.       if (next == 0)
  2613.           return (0);
  2614.       l = strlen(oid_name) + 1;
  2615.       next->object_id = malloc(l);
  2616.       strcpy(next->object_id, oid_name);
  2617.       l = strlen(group_oid) + 1;
  2618.       next->group_id = malloc(l);
  2619.       strcpy(next->group_id, group_oid);
  2620.       return (next);
  2621.   }
  2622.  
  2623.   struct dpi_set_packet *mkDPIset(oid_name, type, len, value)
  2624.   char           *oid_name;
  2625.   int             type;
  2626.   int             len;
  2627.   char           *value;
  2628.   {
  2629.       struct dpi_set_packet *set;
  2630.       int             l;
  2631.  
  2632.  
  2633.  
  2634. Carpenter & Wijnen                                             [Page 47]
  2635.  
  2636. RFC 1228                        SNMP-DPI                        May 1991
  2637.  
  2638.  
  2639.       set = (struct dpi_set_packet *)
  2640.         malloc(sizeof(struct dpi_set_packet));
  2641.       if (set == 0)
  2642.           return (0);
  2643.  
  2644.       l = strlen(oid_name) + 1;
  2645.       set->object_id = malloc(l);
  2646.       strcpy(set->object_id, oid_name);
  2647.       set->type = type;
  2648.       set->value_len = len;
  2649.       set->value = malloc(len);
  2650.       bcopy(value, set->value, len);
  2651.       return (set);
  2652.   }
  2653.  
  2654.  
  2655. SAMPLE SOURCES FOR ANONYMOUS FTP
  2656.  
  2657.    The complete source to two SNMP DPI-related programs is available for
  2658.    anonymous ftp from the University of Toronto.  The host name to use
  2659.    is "vm.utcs.utoronto.ca" (128.100.100.2).  The files are in the
  2660.    "anonymou.204" minidisk, so one must issue a "cd anonymou.204" after
  2661.    having logged in.  Don't forget to use the binary transmission mode.
  2662.  
  2663. The Ping Engine
  2664.  
  2665.    This program is an SNMP DPI sub-agent which allows network management
  2666.    stations to perform remote PINGs.  The source to this applications is
  2667.    in the file "ping_eng.tarbin".  The source to the SNMP DPI API is
  2668.    also contained within the archive.
  2669.  
  2670. The DPI->SMUX daemon
  2671.  
  2672.    This program illustrates what is required to include the SNMP DPI in
  2673.    an SNMP agent.  This is actually a SMUX-based agent that works with
  2674.    the ISODE SNMP agent and provides an interface for SNMP DPI sub-
  2675.    agents.  The source to this program is in the file "dpid.tarbin".
  2676.    ISODE 6.7, or later, is a prerequisite.
  2677.  
  2678. References
  2679.  
  2680.    [1] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple
  2681.        Network Management Protocol", RFC 1157, SNMP Research,
  2682.        Performance Systems International, Performance Systems
  2683.        International, MIT Laboratory for Computer Science, May 1990.
  2684.  
  2685.    [2] Information processing systems - Open Systems Interconnection,
  2686.        "Specification of Abstract Syntax Notation One (ASN.1)",
  2687.  
  2688.  
  2689.  
  2690. Carpenter & Wijnen                                             [Page 48]
  2691.  
  2692. RFC 1228                        SNMP-DPI                        May 1991
  2693.  
  2694.  
  2695.        International Organization for Standardization, International
  2696.        Standard 8824, December 1987.
  2697.  
  2698.    [3] Information processing systems - Open Systems Interconnection,
  2699.        "Specification of Basic Encoding Rules for Abstract Syntax
  2700.        Notation One (ASN.1)", International Organization for
  2701.        Standardization, International Standard 8825, December 1987.
  2702.  
  2703.    [4] McCloghrie K., and M. Rose, "Management Information Base for
  2704.        Network Management of TCP/IP-based internets", RFC 1156,
  2705.        Performance Systems International and Hughes LAN Systems, May
  2706.        1990.
  2707.  
  2708.    [5] Rose, M., and K. McCloghrie, "Structure and Identification of
  2709.        Management Information for TCP/IP-based internets", RFC 1155,
  2710.        Performance Systems International and Hughes LAN Systems, May
  2711.        1990.
  2712.  
  2713.    [6] International Business Machines, Inc., "TCP/IP for VM:
  2714.        Programmer's Reference", SC31-6084-0, 1990.
  2715.  
  2716.    [7] International Business Machines, Inc., "Virtual Machine System
  2717.        Facilities for Programming, Release 6", SC24-5288-01, 1988.
  2718.  
  2719.    [8] International Business Machines, Inc., "TCP/IP Version 1.1 for
  2720.        OS/2 EE:  Programmer's Reference", SC31-6077-1, 1990.
  2721.  
  2722. Security Considerations
  2723.  
  2724.    Security issues are not discussed in this memo.
  2725.  
  2726.  
  2727.  
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746. Carpenter & Wijnen                                             [Page 49]
  2747.  
  2748. RFC 1228                        SNMP-DPI                        May 1991
  2749.  
  2750.  
  2751. Authors' Addresses
  2752.  
  2753.    Geoffrey C. Carpenter
  2754.    IBM T. J. Watson Research Center
  2755.    P. O. Box 218
  2756.    Yorktown Heights, NY  10598
  2757.  
  2758.    Phone:  (914) 945-1970
  2759.  
  2760.    Email:  gcc@watson.ibm.com
  2761.  
  2762.  
  2763.    Bert Wijnen
  2764.    IBM International Operations
  2765.    Watsonweg 2
  2766.    1423 ND Uithoorn
  2767.    The Netherlands
  2768.  
  2769.    Phone:  +31-2975-53316
  2770.  
  2771.    Email:  wijnen@uitvm2.iinus1.ibm.com
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.  
  2784.  
  2785.  
  2786.  
  2787.  
  2788.  
  2789.  
  2790.  
  2791.  
  2792.  
  2793.  
  2794.  
  2795.  
  2796.  
  2797.  
  2798.  
  2799.  
  2800.  
  2801.  
  2802. Carpenter & Wijnen                                             [Page 50]
  2803.