From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc2089.txt | 675 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 675 insertions(+) create mode 100644 doc/rfc/rfc2089.txt (limited to 'doc/rfc/rfc2089.txt') 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] + -- cgit v1.2.3