doc: Add RFC documents

1 files changed, 675 insertions, 0 deletions

diff --git a/doc/rfc/rfc2089.txt b/doc/rfc/rfc2089.txt
new file mode 100644
index 0000000..9f0da86
--- /dev/null
+++ b/doc/rfc/rfc2089.txt
@@ -0,0 +1,675 @@
+
+
+
+
+
+
+Network Working Group                                          B. Wijnen
+Request for Comments: 2089                                           IBM
+Category: Informational                                          D. Levi
+                                                      SNMP Research, Inc
+                                                            January 1997
+
+                                 V2ToV1
+                       Mapping SNMPv2 onto SNMPv1
+                     within a bi-lingual SNMP agent
+
+Status of this Memo
+
+   This memo provides information for the Internet community.  This memo
+   does not specify an Internet standard of any kind.  Distribution of
+   this memo is unlimited.
+
+Abstract
+
+   The goal of this memo is to document a common way of mapping an
+   SNMPv2 response into an SNMPv1 response within a bi-lingual SNMP
+   agent (one that supports both SNMPv1 and SNMPv2).
+
+Table of Contents
+
+     1.0  Introduction  . . . . . . . . . . . . . . . . . . . . . . .  2
+     2.0  Mapping SNMPv2 into SNMPv1  . . . . . . . . . . . . . . . .  2
+     2.1  Mapping SNMPv2 error-status into SNMPv1 error-status  . . .  3
+     2.2  Mapping SNMPv2 exceptions into SNMPv1   . . . . . . . . . .  3
+     2.3  Mapping noSuchObject and noSuchInstance   . . . . . . . . .  4
+     2.4  Mapping endOfMibView  . . . . . . . . . . . . . . . . . . .  5
+     2.5  Mapping SNMPv2 SMI into SNMPv1  . . . . . . . . . . . . . .  5
+     3.0  Processing SNMPv1 requests  . . . . . . . . . . . . . . . .  6
+     3.1  Processing an SNMPv1 GET request  . . . . . . . . . . . . .  6
+     3.2  Processing an SNMPv1 GETNEXT request  . . . . . . . . . . .  7
+     3.3  Processing an outgoing SNMPv2 trap  . . . . . . . . . . . .  8
+     4.0  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . 10
+     5.0  References  . . . . . . . . . . . . . . . . . . . . . . . . 10
+     6.0  Security Considerations   . . . . . . . . . . . . . . . . . 10
+     7.0  Authors' Addresses  . . . . . . . . . . . . . . . . . . . . 11
+     Appendix A.  Background Information  . . . . . . . . . . . . .   12
+     A.1  Mapping of error-status Values  . . . . . . . . . . . . .   12
+     A.2  SNMPv1 traps without Counter64 varBinds.  . . . . . . . .   12
+
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                      [Page 1]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+1.0  Introduction
+
+   We now have the SNMPv1 protocol (RFC1157 [1]) as a full standard and
+   the SNMPv2 protocol (RFC1905 [1]) as a DRAFT standard.  It can be
+   expected that many agent implementations will support both SNMPv1 and
+   SNMPv2 requests coming from SNMP management entities.  In many cases
+   the underlying instrumentation will be implemented using the new
+   SNMPv2 SMI and SNMPv2 protocol.  The SNMP engine then gets the task
+   to ensure that any SNMPv2 response data coming from such SNMPv2
+   compliant instrumentation gets converted to a proper SNMPv1 response
+   if the original request came in as an SNMPv1 request.  The SNMP
+   engine should also deal with mapping SNMPv2 traps which are generated
+   by an application or by the SNMPv2 compliant instrumentation into
+   SNMPv1 traps if the agent has been configured to send traps to an
+   SNMPv1 manager.
+
+   It seems beneficial if all such agents do this mapping in the same
+   way. This document describes such a mapping based on discussions and
+   perceived consensus on the various mailing lists.  The authors of
+   this document have also compared their own implementations of these
+   mappings. They had a few minor differences and decided to make their
+   implementation behave the same and document this mapping so others
+   can benefit from it.
+
+   We recommend that all agents implement this same mapping.
+
+   Note that the mapping described in this document should also be
+   followed by SNMP proxies that provide a mapping between SNMPv1
+   management applications and SNMPv2 agents.
+
+2.0  Mapping SNMPv2 into SNMPv1
+
+   These are the type of mappings that we need:
+
+     o   Mapping of the SNMPv2 error-status into SNMPv1 error-status
+
+     o   Mapping of the SNMPv2 exceptions into SNMPv1 error-status
+
+     o   Skipping object instances that have a non-SNMPv1 Syntax
+         (specifically Counter64)
+
+     o   Mapping of SNMPv2 traps into SNMPv1 traps
+
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                      [Page 2]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+2.1  Mapping SNMPv2 error-status into SNMPv1 error-status
+
+   With the new SNMPv2 protocol (RFC1905 [1]) we get a set of error-
+   status values that return the cause of an error in much more detail.
+   But an SNMPv1 manager does not understand such error-status values.
+
+   So, when the instrumentation code returns response data and uses an
+   SNMPv2 error-status to report on the success or failure of the
+   requested operation and if the original SNMP request is an SNMPv1
+   request, then we must map such an error-status into an SNMPv1 error-
+   status when composing the SNMP response PDU.
+
+   The SNMPv2 error status is mapped to an SNMPv1 error-status using
+   this table:
+
+             SNMPv2 error-status    SNMPv1 error-status
+             ===================    ===================
+             noError                noError
+             tooBig                 tooBig
+             noSuchName             noSuchName
+             badValue               badValue
+             readOnly               readOnly
+             genErr                 genErr
+             wrongValue             badValue
+             wrongEncoding          badValue
+             wrongType              badValue
+             wrongLength            badValue
+             inconsistentValue      badValue
+             noAccess               noSuchName
+             notWritable            noSuchName
+             noCreation             noSuchName
+             inconsistentName       noSuchName
+             resourceUnavailable    genErr
+             commitFailed           genErr
+             undoFailed             genErr
+             authorizationError     noSuchName
+
+2.2  Mapping SNMPv2 exceptions into SNMPv1
+
+   In SNMPv2 we have so called exception values. These will allow an
+   SNMPv2 response PDU to return as much management information as
+   possible, even if one or more of the requested variables do not
+   exist.  SNMPv1 does not support exception values, and thus does not
+   return the value of management information when any error occurs.
+
+   When multiple variables do not exist, an SNMPv1 agent can return only
+   a single error and index of a single variable.  The agent determines
+   by its implementation strategy which variable to identify as the
+
+
+
+Wijnen & Levi                Informational                      [Page 3]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+   cause of the error via the value of the error-index field. Thus, an
+   SNMPv1 manager may make no assumption on the validity of the other
+   variables in the request.
+
+   So, when an SNMPv1 request is received, we must check the varBinds
+   returned from SNMPv2 compliant instrumentation for exception values,
+   and convert these exception values into SNMPv1 error codes.
+
+   The type of exception we can get back and the action we must take
+   depends on the SNMP operation that is requested.
+
+     o   For SNMP GET requests we can get back noSuchObject and
+         noSuchInstance.
+
+     o   For SNMP GETNEXT requests we can get back endOfMibView.
+
+     o   For SNMP SET requests we cannot get back any exceptions.
+
+     o   For SNMP GETBULK requests we can get back endOfMibView, but
+         such a request should only come in as an SNMPv2 request, so we
+         do not have to worry about any mapping onto SNMPv1.  If a
+         GETBULK comes in as an SNMPv1 request, it is treated as an
+         error and the packet is dropped.
+
+2.3  Mapping noSuchObject and noSuchInstance
+
+   A noSuchObject or noSuchInstance exception generated by SNMPv2
+   compliant instrumentation indicates that the requested object
+   instance can not be returned.  The SNMPv1 error code for this
+   condition is noSuchName, and so the error-status field of the
+   response PDU should be set to noSuchName.  Also, the error-index
+   field is set to the index of the varBind for which an exception
+   occurred, and the varBind list from the original request is returned
+   with the response PDU.
+
+   Note that when the response contains multiple exceptions, that the
+   agent may pick any one to be returned.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                      [Page 4]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+2.4  Mapping endOfMibView
+
+   When SNMPv2 compliant instrumentation returns a varBind containing an
+   endOfMibView exception in response to a GETNEXT request, it indicates
+   that there are no object instances available which lexicographically
+   follow the object in the request. In an SNMPv1 agent, this condition
+   normally results in a noSuchName error, and so the error-status field
+   of the response PDU should be set to noSuchName. Also, the error-
+   index field is set to the index of the varBind for which an exception
+   occurred, and the varBind list from the original request is returned
+   with the response PDU.
+
+   Note that when the response contains multiple exceptions, that the
+   agent may pick any one to be returned.
+
+2.5  Mapping SNMPv2 SMI into SNMPv1
+
+   The SNMPv2 SMI (RFC1902 [2]) defines basically one new syntax that is
+   problematic for SNMPv1 managers. That is the syntax Counter64.  All
+   the others can be handled by SNMPv1 managers.
+
+   The net impact on bi-lingual agents is that they should make sure
+   that they never return a varBind with a Counter64 value to an SNMPv1
+   manager.
+
+   The best accepted practice is to consider such object instances
+   implicitly excluded from the view.  So:
+
+     o   On an SNMPv1 GET request, we return an error-status of
+         noSuchName and the error-index is set to the varBind that
+         causes this error.
+
+     o   On an SNMPv1 GETNEXT request, we skip the object instance and
+         fetch the next object instance that follows the one with a
+         syntax of Counter64.
+
+     o   Any SET request that has a varBind with a Counter64 value must
+         have come from a SNMPv2 manager, and so it should not cause a
+         problem.  If we do receive a Counter64 value in an SNMPv1 SET
+         packet, it should result in an ASN.1 parse error since
+         Counter64 is not valid in the SNMPv1 protocol. When an ASN.1
+         parse error occurs, the counter snmpInASNParseErrs is
+         incremented and no response is returned.
+
+     o   The GETBULK is an SNMPv2 operation, so it should never come
+         from an SNMPv1 manager.  If we do receive a GETBULK PDU from in
+         an SNMPv1 packet, then we consider it an invalid PDU-type and
+         we drop the packet.
+
+
+
+Wijnen & Levi                Informational                      [Page 5]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+3.0  Processing SNMPv1 requests
+
+   This sections contains a step by step description of how to handle
+   SNMPv1 requests in an agent where the underlying instrumentation code
+   is SNMPv2 compliant.
+
+3.1  Processing an SNMPv1 GET request
+
+   First, the request is converted into a call to the underlying
+   instrumentation. This is implementation specific.
+
+   When such instrumentation returns response data using SNMPv2 syntax
+   and error-status values, then:
+
+   1.  If the error-status is anything other than noError,
+
+         a.  The error status is translated to an SNMPv1 error-status
+             using the table from 2.1, "Mapping SNMPv2 error-status into
+             SNMPv1 error-status" on page 2
+
+         b.  The error-index is set to the position (in the original
+             request) of the varBind that caused the error-status.
+
+         c.  The varBindList of the response PDU is made exactly the
+             same as the varBindList that was received in the original
+             request.
+
+    2.  If the error-status is noError, then find any varBind that
+        contains an SNMPv2 exception (noSuchObject or noSuchInstance)
+        or an SNMPv2 syntax that is unknown to SNMPv1 (Counter64).
+        (Note that if there are more than one, the agent may choose any
+        such varBind.)  If there are any such varBinds, then for the
+        one chosen:
+
+         a.  Set the error-status to noSuchName
+
+         b.  Set the error-index to the position (in the varBindList of
+             the original request) of the varBind that returned such an
+             SNMPv2 exception or syntax.
+
+         c.  Make the varBindList of the response PDU exactly the same
+             as the varBindList that was received in the original
+             request.
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                      [Page 6]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+     3.  If there are no such varBinds, then:
+
+         a.  Set the error-status to noError
+
+         b.  Set the error-index to zero
+
+         c.  Compose the varBindList of the response, using the data as
+             it is returned by the instrumentation code.
+
+3.2  Processing an SNMPv1 GETNEXT request
+
+   First, the request is converted into a call to the underlying
+   instrumentation. This is implementation specific.  There may be
+   repetitive calls to (possibly different pieces of) instrumentation
+   code to try to find the first object which lexicographically follows
+   each of the objects in the request.  Again, this is implementation
+   specific.
+
+   When the instrumentation finally returns response data using SNMPv2
+   syntax and error-status values, then:
+
+     1.  If the error-status is anything other than noError,
+
+         a.  The error status is translated to an SNMPv1 error-status
+             using the table from 2.1, "Mapping SNMPv2 error-status into
+             SNMPv1 error-status" on page 2
+
+         b.  The error-index is set to the position (in the original
+             request) of the varBind that caused the error-status.
+
+         c.  The varBindList of the response PDU is made exactly the
+             same as the varBindList that was received in the original
+             request.
+
+     2.  If the error-status is noError, then:
+
+         a.  If there are any varBinds containing an SNMPv2 syntax of
+             Counter64, then consider these varBinds to be not in view
+             and repeat the call to the instrumentation code as often as
+             needed till a value other than Counter64 is returned.
+
+         b.  Find any varBind that contains an SNMPv2 exception
+             endOfMibView.  (Note that if there are more than one, the
+             agent may choose any such varBind.)  If there are any such
+             varBinds, then for the one chosen:
+
+             1)  Set the error-status to noSuchName
+
+
+
+
+Wijnen & Levi                Informational                      [Page 7]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+             2)  Set the error-index to the position (in the varBindList
+                 of the original request) of the varBind that returned
+                 such an SNMPv2 exception.
+
+             3)  Make the varBindList of the response PDU exactly the
+                 same as the varBindList that was received in the
+                 original request.
+
+         c.  If there are no such varBinds, then:
+
+             1)  Set the error-status to noError
+
+             2)  Set the error-index to zero
+
+             3)  Compose the varBindList of the response, using the data
+                 as it is returned by the instrumentation code.
+
+3.3  Processing an outgoing SNMPv2 TRAP
+
+   If SNMPv2 compliant instrumentation presents an SNMPv2 trap to the
+   SNMP engine and such a trap passes all regular checking and then is
+   to be sent to an SNMPv1 destination, then the following steps must be
+   followed to convert such a trap to an SNMPv1 trap.  This is basically
+   the reverse of the SNMPv1 to SNMPv2 mapping as described in RFC1908
+   [3].
+
+     1.  If any of the varBinds in the varBindList has an SNMPv2 syntax
+         of Counter64, then such varBinds are implicitly considered to
+         be not in view, and so they are removed from the varBindList to
+         be sent with the SNMPv1 trap.
+
+     2.  The 3 special varBinds in the varBindList of an SNMPv2 trap
+         (sysUpTime.0 (TimeTicks), snmpTrapOID.0 (OBJECT IDENTIFIER) and
+         optionally snmpTrapEnterprise.0 (OBJECT IDENTIFIER)) are
+         removed from the varBindList to be sent with the SNMPv1 trap.
+         These 2 (or 3) varBinds are used to decide how to set other
+         fields in the SNMPv1 trap PDU as follows:
+
+         a.  The value of sysUpTime.0 is copied into the timestamp field
+             of the SNMPv1 trap.
+
+
+
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                      [Page 8]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+         b.  If the snmpTrapOID.0 value is one of the standard traps the
+             specific-trap field is set to zero and the generic trap
+             field is set according to this mapping:
+
+                value of snmpTrapOID.0                generic-trap
+                ===============================       ============
+                1.3.6.1.6.3.1.1.5.1 (coldStart)                  0
+                1.3.6.1.6.3.1.1.5.2 (warmStart)                  1
+                1.3.6.1.6.3.1.1.5.3 (linkDown)                   2
+                1.3.6.1.6.3.1.1.5.4 (linkUp)                     3
+                1.3.6.1.6.3.1.1.5.5 (authenticationFailure)      4
+                1.3.6.1.6.3.1.1.5.6 (egpNeighborLoss)            5
+
+             The enterprise field is set to the value of
+             snmpTrapEnterprise.0 if this varBind is present, otherwise
+             it is set to the value snmpTraps as defined in RFC1907 [4].
+
+         c.  If the snmpTrapOID.0 value is not one of the standard
+             traps, then the generic-trap field is set to 6 and the
+             specific-trap field is set to the last subid of the
+             snmpTrapOID.0 value.
+
+             o   If the next to last subid of snmpTrapOID.0 is zero,
+                 then the enterprise field is set to snmpTrapOID.0 value
+                 and the last 2 subids are truncated from that value.
+             o   If the next to last subid of snmpTrapOID.0 is not zero,
+                 then the enterprise field is set to snmpTrapOID.0 value
+                 and the last 1 subid is truncated from that value.
+
+             In any event, the snmpTrapEnterprise.0 varBind (if present)
+             is ignored in this case.
+
+     3.  The agent-addr field is set with the appropriate address of the
+         the sending SNMP entity, which is the IP address of the sending
+         entity of the trap goes out over UDP; otherwise the agent-addr
+         field is set to address 0.0.0.0.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                      [Page 9]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+4.0  Acknowledgements
+
+   The authors wish to thank the contributions of the SNMPv2 Working
+   Group in general.  Special thanks for their detailed review and
+   comments goes to these individuals:
+
+       Mike Daniele (DEC)
+       Dave Harrington (Cabletron)
+       Brian O'Keefe (Hewlett Packard)
+       Keith McCloghrie (Cisco Systems)
+       Dave Perkins (independent)
+       Shawn Routhier (Epilogue)
+       Juergen Schoenwaelder (University of Twente)
+
+5.0  References
+
+     [1]  Jeffrey  D. Case, Mark Fedor, Martin Lee Schoffstall and James
+          R. Davin, Simple  Network  Management  Protocol  (SNMP),  SNMP
+          Research,  Performance  Systems  International, MIT Laboratory
+          for Computer Science, RFC 1157, May 1990.
+
+     [2]  Jeffrey D. Case, Keith McCloghrie, Marshall T. Rose and Steven
+          Waldbusser, Structure of Managment Information for  Version  2
+          of  the  Simple  Network  Management  Protocol  (SNMPv2), SNMP
+          Research Inc, Cisco Systems Inc, Dover Beach  Consulting  Inc,
+          International Network Services, RFC1902, January 1996.
+
+     [3]  Jeffrey D. Case, Keith McCloghrie, Marshall T. Rose and Steven
+          Waldbusser, Coexistence between Version 1 and Version 2 of the
+          Internet-standard  Network Management Framework, SNMP Research
+          Inc,  Cisco  Systems  Inc,   Dover   Beach   Consulting   Inc,
+          International Network Services, RFC1908, January 1996.
+
+     [4]  Jeffrey D. Case, Keith McCloghrie, Marshall T. Rose and Steven
+          Waldbusser,  Management  Information Base for Version 2 of the
+          Simple Network Management  Protocol  (SNMPv2),  SNMP  Research
+          Inc,   Cisco   Systems   Inc,   Dover  Beach  Consulting  Inc,
+          International Network Services, RFC1907, January 1996.
+
+6.0  Security Considerations
+
+   Security considerations are not discussed in this memo.
+
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                     [Page 10]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+7.0  Authors' Addresses
+
+          Bert Wijnen
+          IBM International Operations
+          Watsonweg 2
+          1423 ND Uithoorn
+          The Netherlands
+
+          Phone: +31-079-322-8316
+          E-mail: wijnen@vnet.ibm.com
+
+
+          David Levi
+          SNMP Research, Inc
+          3001 Kimberlin Heights Rd.
+          Knoxville, TN 37920-9716
+          USA
+
+          Phone: +1-615-573-1434
+          E-mail: levi@snmp.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                     [Page 11]
+
+RFC 2089                         V2toV1                     January 1997
+
+
+APPENDIX A.  Background Information
+
+   Here follows some reasoning as to why some choices were made.
+
+   A.1  Mapping of error-status values
+
+   The mapping of SNMPv2 error-status values to SNMPv1 error-status
+   values is based on the common interpretation of how an SNMPv1 entity
+   should create an error-status value based on the elements of
+   procedure defined in RFC1157 [1].
+
+   There was a suggestion to map wrongEncoding into genErr, because it
+   could be caused by an ASN.1 parsing error.  Such maybe true, but in
+   most cases when we detect the ASN.1 parsing error, we do not yet know
+   about the PDU data yet.  Most people who responded to our queries
+   have implemented the mapping to a badValue. So we "agreed" on the
+   mapping to badValue.
+
+
+   A.2  SNMPv1 Traps without Counter64 varBinds.
+
+   RFC1448 says that if one of the objects in the varBindList is not
+   included in the view, then the trap is NOT sent.  Current SNMPv2u and
+   SNMPv2* documents make the same statement.  However, the "rough
+   consensus" is that it is better to send partial information than no
+   information at all. Besides:
+
+     o   RFC1448 does not allow for a TRAP to be sent with the varBinds
+         that are not included in the view removed, so it is an all or
+         nothing decision.
+
+     o   We do NOT include the Counter64 varBinds... so the "not in
+         view" varBinds are not sent to the trap destination.
+
+     o   The Counter64 objects are "implicit" not in view.  If any
+         objects are explicit not in view, then this is checked before
+         we do the conversion from an SNMPv2 trap to an SNMPv1 trap, and
+         so the trap is not sent at all.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wijnen & Levi                Informational                     [Page 12]
+