rfc1228.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

Carpenter & Wijnen                                             [Page 24]

RFC 1228                        SNMP-DPI                        May 1991


     int error_code;
     struct dpi_set_packet *ret_value;

     packet = mkDPIresponse(error_code, ret_value);

     len = *packet * 256 + *(packet + 1);
     len += 2;  /* include length bytes */

   The mkDPIresponse() function creates an appropriate response packet.
   It takes two parameters.  The first is the error code to be returned.
   It may be 0 (indicating no error) or one of the following (which are
   defined in the include file "snmp_dpi.h"):

      o   SNMP_NO_ERROR
      o   SNMP_TOO_BIG
      o   SNMP_NO_SUCH_NAME
      o   SNMP_BAD_VALUE
      o   SNMP_READ_ONLY
      o   SNMP_GEN_ERR

   If the error code indicates no error, then the second parameter is a
   pointer to a parse tree (created by mkDPIset()) which represents the
   name/type/value information being returned.  If an error is
   indicated, the second parameter is passed as a null pointer (0).

   If the packet can be created, a pointer to a static buffer containing
   the packet contents is returned.  This is the same buffer used by
   mkDPIregister().  If an error is encountered while creating the
   packet, the null pointer (0) is returned.

   The length of the remainder packet is stored in the first two bytes
   of the packet, as demonstrated in the example above.

   NOTE:  mkDPIresponse() always frees the passed parse tree.

MKDPITRAP

     #include "snmp_dpi.h"

     unsigned char *packet;

     int generic, specific;
     struct dpi_set_packet *ret_value;

     packet = mkDPItrap(generic, specific, ret_value);

     len = *packet * 256 + *(packet + 1);
     len += 2;  /* include length bytes */



Carpenter & Wijnen                                             [Page 25]

RFC 1228                        SNMP-DPI                        May 1991


   The mkDPItrap() function creates an appropriate trap request packet.
   The first two parameters correspond to to value of the generic and
   specific fields in the SNMP trap packet.  The third field can be used
   to pass a name/value pair to be provided in the SNMP trap packet.
   This information is passed as the set-packet portion of the parse
   tree.  As an example, a linkDown trap for interface 3 might be
   generated by the following:

     struct dpi_set_packet *if_index_value;
     unsigned long data;
     unsigned char *packet;
     int len;

     data = 3;  /* interface number = 3 */
     if_index_value = mkDPIset("1.3.6.1.2.1.2.2.1.1", SNMP_TYPE_NUMBER,
             sizeof(unsigned long), &data);
     packet = mkDPItrap(2, 0, if_index_value);
     len = *packet * 256 + *(packet + 1);
     len += 2;  /* include length bytes */
     write(fd,packet,len);

   If the packet can be created, a pointer to a static buffer containing
   the packet contents is returned.  This is the same buffer used by
   mkDPIregister().  If an error is encountered while creating the
   packet, the null pointer (0) is returned.

   The length of the remainder packet is stored in the first two bytes
   of the packet, as demonstrated in the example above.

   NOTE:  mkDPItrap() always frees the passed parse tree.

PDPIPACKET

     #include "snmp_dpi.h"

     unsigned char *packet;

     struct snmp_dpi_hdr *hdr;

     hdr = pDPIpacket(packet)

   The pDPIpacket() function parses a DPI packet and returns a parse
   tree representing its contents.  The parse tree is dynamically
   allocated and contains copies of the information within the DPI
   packet.  After a successful call to pDPIpacket(), the packet may be
   disposed of in any manner the application chooses without affecting
   the contents of the parse tree.  If an error is encountered during
   the parse, the null pointer (0) is returned.



Carpenter & Wijnen                                             [Page 26]

RFC 1228                        SNMP-DPI                        May 1991


   NOTE:  the relevant parse tree structures are defined in the include
   file "snmp_dpi.h", and that file remains the definitive reference.

   The root of the parse tree is represented by a snmp_dpi_hdr
   structure:

     struct snmp_dpi_hdr {
         unsigned char  proto_major;
         unsigned char  proto_minor;
         unsigned char  proto_release;

         unsigned char  packet_type;
         union {
              struct dpi_get_packet    *dpi_get;
              struct dpi_next_packet   *dpi_next;
              struct dpi_set_packet    *dpi_set;
              struct dpi_resp_packet   *dpi_response;
              struct dpi_trap_packet   *dpi_trap;
         } packet_body;
     };

   The field of immediate interest is packet_type.  This field can have
   one of the following values (which are defined in the include file
   "snmp_dpi.h"):

      o   SNMP_DPI_GET
      o   SNMP_DPI_GET_NEXT
      o   SNMP_DPI_SET

   The packet_type field indicates what request is being made of the DPI
   client.  For each of these requests, the remainder of the packet_body
   will be different.

   If a get request is indicated, the object ID of the desired variable
   is passed in a dpi_get_packet structure:

     struct dpi_get_packet {
         char *object_id;
     };

   A get-next request is similar, but the dpi_next_packet structure also
   contains the object ID prefix of the group that is currently being
   traversed:

     struct dpi_next_packet {
         char *object_id;
         char *group_id;
     };



Carpenter & Wijnen                                             [Page 27]

RFC 1228                        SNMP-DPI                        May 1991


   If the next object whose object ID lexicographically follows the
   object ID indicated by object_id does not begin with the suffix
   indicated by group_id, the DPI client must return an error indication
   of SNMP_NO_SUCH_NAME.

   A set request has the most amount of data associated with it and this
   is contained in a dpi_set_packet structure:

     struct dpi_set_packet {
         char      *object_id;
         unsigned char  type;
         unsigned short value_len;
         char      *value;
     };

   The object ID of the variable to be modified is indicated by
   object_id The type of the variable is provided in type and may have
   one of the following values:

      o   SNMP_TYPE_NUMBER
      o   SNMP_TYPE_STRING
      o   SNMP_TYPE_OBJECT
      o   SNMP_TYPE_EMPTY
      o   SNMP_TYPE_INTERNET
      o   SNMP_TYPE_COUNTER
      o   SNMP_TYPE_GAUGE
      o   SNMP_TYPE_TICKS

   The length of the value to be set is stored in value_len and value
   contains a pointer to the value.

   NOTE:  the storage pointed to by value will be reclaimed when the
   parse tree is freed.  The DPI client must make provision for copying
   the value contents.

FDPIPARSE

     #include "snmp_dpi.h"

     struct snmp_dpi_hdr *hdr;

     fDPIparse(hdr);

   The routine fDPIparse() frees a parse tree previously created by a
   call to pDPIpacket This routine is declared as void--it has no return
   value.

   NOTE:  after calling fDPIparse(), no further references to the parse



Carpenter & Wijnen                                             [Page 28]

RFC 1228                        SNMP-DPI                        May 1991


   tree can be made.

AGENT IMPLEMENTATION ISSUES

   Although the SNMP DPI protocol is completely documented in this
   paper, the document itself is somewhat biased towards clearly
   defining the interface provided to sub-agents (i.e., it provides a
   specification of a C language API).  This detailed coverage is
   possible because the client side of the interface is completely
   self-contained.

   The agent side of the interface has to be integrated into individual
   vendor implementations, many of which may have a unique
   organizational structure in an attempt to address various performance
   and storage constraints.  This makes it infeasible to provide much
   more than suggestions for SNMP agent implementers.  Unfortunately,
   this leaves room for a large amount of interpretation which can lead
   to implementations that don't necessarily work they way they should-
   -too much ambiguity can be a bad thing.

   The following characteristics of an agent implementation are to be
   considered mandatory:

DUPLICATE REGISTRATIONS

   With this release of the protocol, order of registration is
   significant.  The last sub-agent to register a variable is the one
   that is deemed to be authoritative.  Variables implemented by the
   base SNMP agent are considered to have been registered prior to any
   sub-agent registrations.  Thus sub-agents may re-implement support
   for variables that were incorrectly implemented by a vendor.

AUTOMATIC DEREGISTRATION ON CLOSE

   All SNMP DPI connections are carried over a stream connection.  When
   the connection is closed by the client (no matter what the cause),
   the agent must automatically unregister all of the variables that
   were registered by the sub-agent.

TIMELY RESPONSE CONSTRAINTS

   A sub-agent must respond to a request in a timely fashion.  In this
   version of the protocol, we specify that a sub-agent must respond to
   a request by the SNMP agent within 5 seconds.  If the sub-agent does
   not respond in time, the SNMP agent should terminate the connection
   and unregister all of the variables that were previously registered
   by the sub-agent in question.




Carpenter & Wijnen                                             [Page 29]

RFC 1228                        SNMP-DPI                        May 1991


   NOTE:  agent implementations that do not have access to a timer may
   not be able to implement this.  In that case, they leave themselves
   open to being placed in a state where they are blocked forever if the
   sub-agent malfunctions.

SUPPORT FOR MULTIPLE MIB VIEWS

   Some agents allow different MIB views to be selected based on the
   community name used.  It is not the intention of this document to
   pass judgement on the various approaches that have been proposed or
   implemented, but instead merely to recognize the existence of
   implementations that support this feature.

   The point of this discussion is to specify clearly that objects
   supported by an SNMP DPI sub-agent are to be registered under the MIB
   view that was selected by the community name used in the SNMP GET
   request that obtained the DPI_port value.

   The SNMP DPI does not specify a reserved port, but instead sub-agents
   bootstrap themselves by making an SNMP GET request for the DPI_port
   variable.  This variable represents the TCP port to which the sub-
   agent should connect.  It should be understood that there is no
   reason why the SNMP agent cannot have several listens (passive opens)
   active, each corresponding to a distinct MIB view.  The port number
   returned then would be different based on the community name used in
   the SNMP GET request for the DPI_port variable.

CONSIDERATIONS FOR THE NEXT RELEASE

   The SNMP DPI protocol makes provision for extension and parallel use
   of potentially incompatible releases.  The discussion above documents
   the protocol as it is currently in use and has not discussed features
   of interest that should be considered for a future revision.

UNREGISTER

   For closure, an UNREGISTER request could be of use.

SUPPORT FOR ATOMIC SETS

   The SNMP protocol [1] specifies that:

      Each variable assignment specified by the SetRequest-PDU should be
      effected as if simultaneously set with respect to all other
      assignments specified in the same message.

   The SNMP DPI has no provision for backing out a successfully
   processed SET reque