Internet Draft Dave Shield Expires: March 2003 University of Liverpool September 2002 SNMP Extended Error Reporting draft-shield-eos-extended-error-00.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of [RFC2026]. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Abstract This draft discusses a mechanism for reporting on failures to fulfil an SNMP request, in somewhat more detail than is currently possible. This includes both providing a textual description of the error, and reporting on more than one problem with an individual request. Dave Shield [Page 1] Internet Draft SNMP Extended Error Reporting September 2002 Table of Contents 1. Introduction.............................. 2 2. Error Varbinds ........................... 2 3. MIB Definitions........................... 4 4. References................................ 7 5. Full Copyright Statement ................. 8 1. Introduction Traditionally, SNMP has used a pre-defined list of "error status" values to report on problems with fulfilling a request. This use of a closed set of values simplifies the task of failure-handling in management applications, but limits the amount of information that can be returned to a (human) network administrator. Feedback from the operator community [1], has indicated a desire for a fuller error-reporting mechanism, and at least one recently proposed extension to the protocol (OOPS [2]) has responded to this. This draft proposes a mechanism for returning extended error-related information, within the basic SNMP framework. It also suggests a mechanism for reporting more than one error in a single response, or applying a single error status code to more than one varbind. The basic concept used is to insert additional "error reporting" varbinds in the response PDU VarBindList, preceding the standard "data" varbinds, copied across from the original request PDU. The current expectation is that this facility would be used in conjunction with the Capability Negotiation proposal [3], in which case these error varbinds would follow the capability varbinds, and hence come between these and the data varbinds. This expectation does not preclude some other form of signalling being used to indicate the desire for, and use of, this extended error reporting. Note that this proposal is only applicable to 'failed' requests - i.e. response PDUs where the error status field has a value other than 'noError'. These error varbinds should not appear in the VarBindList of request PDUs, or response PDUs where the error status field has the value 'noError'. 2. Error Varbinds There are three styles of objects being proposed for extended error reporting. It is implementation dependent as to which form (or forms) are used by an individual agent. In all cases, when individual varbinds are referenced using the "error index" field (or similar varbind indexing in the extended error reporting MIB tables), this indexing applies only to the data varbinds. The error status varbinds are not included in such indexing, and should be removed (conceptually at least) before identifying a varbind or varbinds. Dave Shield [Page 2] Internet Draft SNMP Extended Error Reporting September 2002 2.1 Error Description The first form of extended error reporting is a single scalar varbind (eErrDescr), containing a textual description of the error indicated by the main error status/error index pair. It is recommended that if other forms of extended error reporting are also being used, that this varbind should come first in order to simplify the task of management applications that don't wish to handle the full range of extended-error-reporting facilities, but do support error descriptions. 2.2 Additional Error Reporting The second form of extended error reporting is a table of error status values and textual descriptions, indexed by an integer corresponding to the traditional 'error index' field - i.e. indicating which (data) varbind this status or description refers to. It is recommended that the eErrAddnlStatus object should always be used - either in isolation, or together with a corresponding eErrAddnlDescr varbind. An eErrAddnlDescr object should not be used on its own, without a matching eErrAddnlStatus. 2.3 Error Ranges The third form of extended error reporting applies the basic error status field to cover a range of (data) varbinds, in addition to (or including) the one indicated by the error index field. Typically, this will take the form of eErrRangeStart/eErrRangeEnd pairs, defining a range of consecutive varbinds. Multiple such Start/End pairs can be used to define a non-contiguous set of varbinds, and a missing eErrRangeStart (or eErrRangeEnd) varbind is taken to indicate the first (or last) data varbind respectively. Thus a single varbind of 'eErrRangeStart.1' indicates that the error status applies to all varbinds in the request. It is recommended that error range varbinds should appear in order, with eErrRangeStart varbinds appearing before the corresponding eErrRangeEnd, and with ranges appearing in increasing order of varbind index. Dave Shield [Page 3] Internet Draft SNMP Extended Error Reporting September 2002 3. MIB Definitions The following module defines a scalar object for describing the "main" error being reported by the agent, and two MIB tables for reporting multiple errors in the same request. Note that none of these objects "exist" in the agent in the conventional sense, should not be referenced in an information retrieval request, and would not appear in a walk of the agent's full MIB tree. EXTENDED-ERRORS-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-IDENTITY, OBJECT-TYPE, enterprises FROM SNMPv2-SMI ExtendedCapabilities FROM EXTENDED-CAPABILITIES-TC MODULE-COMPLIANCE, TEXTUAL-CONVENTION FROM SNMPv2-TC OBJECT-GROUP FROM SNMPv2-CONF; extendedErrorsMib MODULE-IDENTITY LAST-UPDATED "200209060000Z" ORGANIZATION "University of Liverpool" CONTACT-INFO "Postal: Dave Shield Computer Science University of Liverpool Peach Street Liverpool L69 7ZF United Kingdom E-Mail: D.T.Shield@csc.liv.ac.uk" DESCRIPTION "This MIB module defines a framework for reporting additional information regarding problems fulfilling an SNMP request." ::= { enterprises liv(1579) compsci(42) dts(1) eErr(4) 1 } eErrObjects OBJECT IDENTIFIER ::= { extendedErrorsMib 1 } eErrConformance OBJECT IDENTIFIER ::= { extendedErrorsMib 2 } -- -- MIB objects to advertise support for extended capabilities -- eErrDescr OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "A description of the problem causing the SNMP request to fail. At a minimum, this should apply to the error and varbind indicated by the main error status/error index pair (though this may apply more widely as well)." ::= { eErrObjects 1 } Dave Shield [Page 4] Internet Draft SNMP Extended Error Reporting September 2002 -- -- MIB objects to report additional errors in the same request -- eErrAddnlTable OBJECT-TYPE SYNTAX SEQUENCE OF EErrAddnlEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A table of alternative sets of extended capabilities, supported by particular MIB subtrees of the agent." ::= { eErrObjects 2 } eErrAddnlEntry OBJECT-TYPE SYNTAX EErrAddnlEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "" INDEX { eErrAddnlIndex } ::= { eErrTable 1 } EErrAddnlEntry ::= SEQUENCE { eErrAddnlIndex Unsigned32, eErrAddnlStatus INTEGER, eErrAddnlDescr DisplayString } eErrAddnlIndex OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "The index of the varbind affected by this problem." ::= { eErrAddnlEntry 1 } eErrAddnlStatus OBJECT-TYPE SYNTAX INTEGER(1..18) MAX-ACCESS read-only STATUS current DESCRIPTION "The error-status value (as defined in RFC 1905) that identifies the problem affecting the indicated varbind." ::= { eErrAddnlEntry 2 } eErrAddnlDescr OBJECT-TYPE SYNTAX DisplayString MAX-ACCESS read-only STATUS current DESCRIPTION "An (optional) description providing more information about the error being reported by the corresponding eErrAddnlStatus. Note that the eErrAddnlDescr object should only be used in conjunction with eErrAddnlStatus, and should not appear in isolation." ::= { eErrAddnlEntry 3 } Dave Shield [Page 5] Internet Draft SNMP Extended Error Reporting September 2002 -- -- MIB objects to apply an error-status to a range of varbinds -- eErrRangeTable OBJECT-TYPE SYNTAX SEQUENCE OF EErrRangeEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A 'pseudo-table', used to indicate which varbinds in a request should involve particular extended capabilities. This is not a conventional MIB table, and will not appear in the output of walking the agent." ::= { eErrObjects 3 } eErrRangeEntry OBJECT-TYPE SYNTAX EErrRangeEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "" INDEX { eErrRangeIndex } ::= { eErrRangeTable 1 } EErrRangeEntry ::= SEQUENCE { eErrRangeVBIndex Unsigned32, eErrRangeRangeStart Unsigned32, eErrRangeRangeEnd Unsigned32 } eErrRangeIndex OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "An arpitatrary index into the eErrRangeTable." ::= { eErrRangeEntry 1 } eErrRangeStart OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS read-only STATUS current DESCRIPTION "Indicates the varbind at the start of the range being specified. If this is missing for a particular row, this should be taken as equivalent to '1' (i.e. the first data varbind)." ::= { eErrRangeEntry 2 } eErrRangeEnd OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS read-only STATUS current DESCRIPTION "Indicates the varbind at the end of the range being specified. If this is missing for a particular row, this should be taken as equivalent to the index of the last data varbind." ::= { eErrRangeEntry 3 } Dave Shield [Page 6] Internet Draft SNMP Extended Error Reporting September 2002 -- -- MIB objects to advertise support for extended error reporting -- eErrGroups OBJECT IDENTIFIER ::= { eErrConformance 1 } eErrGeneralGroup OBJECT-GROUP OBJECTS { eErrDescr } STATUS current DESCRIPTION "Description of the basic error." ::= { eErrGroups 1} eErrAddnlGroup OBJECT-GROUP OBJECTS { eErrAddnlStatus, eErrAddnlDescr } STATUS current DESCRIPTION "Reporting and description of additional errors." ::= { eErrGroups 2} eErrRangeGroup OBJECT-GROUP OBJECTS { eErrRangeRangeStart, eErrRangeRangeEnd } STATUS current DESCRIPTION "Negotiation of extended capabilities to use." ::= { eErrGroups 3} END 4. References [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3" BCP 9, RFC 2026, October 1996. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [1] Woodcock, D., "Operator Requirements of Infrastructure Management Methods", Internet Draft draft-ops-operator-req-mgmt-02.txt, expired August 2002. [2] Hardaker, W., "Object Oriented PDUs for SNMP", Internet Draft draft-hardaker-eos-oops-00.txt, expires December 2002. [3] Shield, D., "SNMP Extended Protocol MIB", Internet Draft draft-shield-eos-capabilities-00.txt, expires February 2003. Dave Shield [Page 7] Internet Draft SNMP Extended Error Reporting September 2002 5. Full Copyright Statement Copyright (C) The Internet Society (2002). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. This Internet Draft expires: March 2003 Dave Shield [Page 8]