idnits 2.17.1 draft-ietf-eos-snmp-rowops-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([RFC2571]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (15 June 2001) is 8348 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC1215' is mentioned on line 102, but not defined == Missing Reference: 'RFC1906' is mentioned on line 112, but not defined ** Obsolete undefined reference: RFC 1906 (Obsoleted by RFC 3417) == Missing Reference: 'RFC2572' is mentioned on line 113, but not defined ** Obsolete undefined reference: RFC 2572 (Obsoleted by RFC 3412) == Missing Reference: 'RFC2574' is mentioned on line 113, but not defined ** Obsolete undefined reference: RFC 2574 (Obsoleted by RFC 3414) == Missing Reference: 'RFC1905' is mentioned on line 773, but not defined ** Obsolete undefined reference: RFC 1905 (Obsoleted by RFC 3416) == Missing Reference: 'RFC2573' is mentioned on line 1590, but not defined ** Obsolete undefined reference: RFC 2573 (Obsoleted by RFC 3413) == Missing Reference: 'RFC2575' is mentioned on line 123, but not defined ** Obsolete undefined reference: RFC 2575 (Obsoleted by RFC 3415) == Missing Reference: 'RFC1903' is mentioned on line 204, but not defined ** Obsolete undefined reference: RFC 1903 (Obsoleted by RFC 2579) == Missing Reference: 'TBD' is mentioned on line 699, but not defined -- Looks like a reference, but probably isn't: '9' on line 976 -- Looks like a reference, but probably isn't: '10' on line 980 -- Looks like a reference, but probably isn't: '11' on line 984 -- Looks like a reference, but probably isn't: '12' on line 988 -- Looks like a reference, but probably isn't: '13' on line 992 -- Looks like a reference, but probably isn't: '14' on line 996 == Unused Reference: 'RFC-PROTO' is defined on line 1266, but no explicit reference was found in the text == Unused Reference: 'RFC-TMM' is defined on line 1271, but no explicit reference was found in the text == Unused Reference: 'RFC-MIB' is defined on line 1276, but no explicit reference was found in the text == Unused Reference: 'RFC-COEX' is defined on line 1330, but no explicit reference was found in the text == Unused Reference: 'RFC1909' is defined on line 1286, but no explicit reference was found in the text == Unused Reference: 'RFC1910' is defined on line 1289, but no explicit reference was found in the text == Unused Reference: 'RFC2279' is defined on line 1292, but no explicit reference was found in the text == Unused Reference: 'BCP-11' is defined on line 1298, but no explicit reference was found in the text == Unused Reference: 'RFC2863' is defined on line 1302, but no explicit reference was found in the text == Unused Reference: 'SNMP-MPD' is defined on line 1305, but no explicit reference was found in the text == Unused Reference: 'SNMP-USM' is defined on line 1310, but no explicit reference was found in the text == Unused Reference: 'SNMP-ACM' is defined on line 1315, but no explicit reference was found in the text == Unused Reference: 'RFC-APPL' is defined on line 1321, but no explicit reference was found in the text ** Downref: Normative reference to an Historic RFC: RFC 1157 ** Downref: Normative reference to an Historic RFC: RFC 1901 ** Obsolete normative reference: RFC 2571 (Obsoleted by RFC 3411) -- Possible downref: Non-RFC (?) normative reference: ref. 'RFC-PROTO' -- Possible downref: Non-RFC (?) normative reference: ref. 'RFC-TMM' -- Possible downref: Non-RFC (?) normative reference: ref. 'RFC-MIB' -- Possible downref: Non-RFC (?) normative reference: ref. 'RFC-COEX' ** Downref: Normative reference to an Historic RFC: RFC 1909 ** Downref: Normative reference to an Historic RFC: RFC 1910 ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2028 (ref. 'BCP-11') (Obsoleted by RFC 9281) -- Possible downref: Non-RFC (?) normative reference: ref. 'SNMP-MPD' -- Possible downref: Non-RFC (?) normative reference: ref. 'SNMP-USM' -- Possible downref: Non-RFC (?) normative reference: ref. 'SNMP-ACM' -- Possible downref: Non-RFC (?) normative reference: ref. 'RFC-APPL' ** Obsolete normative reference: RFC 2570 (Obsoleted by RFC 3410) Summary: 19 errors (**), 0 flaws (~~), 25 warnings (==), 16 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT L. Heintz 3 Cisco Systems, Inc. 4 15 June 2001 6 SNMP Row Operations Extensions 8 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. Internet-Drafts are working 14 documents of the Internet Engineering Task Force (IETF), its areas, 15 and its working groups. Note that other groups may also distribute 16 working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at 24 http://www.ietf.org/ietf/1id-abstracts.txt 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html 29 Copyright Notice 31 Copyright (C) The Internet Society (2001). All Rights Reserved. 33 Abstract 35 This document describes a set of extensions (protocol operations and 36 textual conventions) to the existing SNMP framework architecture 37 [RFC2571]. These extensions provide mechanisms for efficient 38 creation, modification, deletion and retrieval of table rows and 39 other information. 41 Table of Contents 43 1. The SNMP Network Management Framework ....................... 3 44 2. Overview .................................................... 4 45 2.1. Terms ..................................................... 4 46 2.2. Motivations for the Extensions ............................ 4 47 2.3. Design Goals .............................................. 5 48 3. The Extensions .............................................. 6 49 3.1. RowState .................................................. 7 50 3.2. Protocol Operations ....................................... 7 51 3.2.1. Singletons .............................................. 8 52 3.2.2. The RowOp ............................................... 9 53 3.2.3. The RowIdentifier ....................................... 10 54 3.2.4. RowIdentifiers in GetBulkRow Requests ................... 11 55 3.2.5. RowIdentifier Inheritance ............................... 12 56 3.2.6. The Operands ............................................ 13 57 3.2.7. Extended Error Codes .................................... 14 58 3.2.8. RowOps and Group Scalar Objects. ....................... 16 59 3.2.9. Three-Phase Sets ........................................ 17 60 3.2.10. Response PDUs .......................................... 17 61 3.2.11. Determining Varbind Roles .............................. 18 62 4. Elements of Procedure ....................................... 19 63 4.1. CreateRow Request Processing .............................. 19 64 4.2. DeleteRow Request Processing .............................. 19 65 4.3. EditRow Request Processing ................................ 19 66 4.4. GetRow Request Processing ................................. 19 67 4.5. GetNextRow Request Processing ............................. 19 68 4.6. GetBulkRow Request Processing ............................. 20 69 4.7. Response-PDU Processing ................................... 20 70 5. Coexistence and Transition .................................. 20 71 6. Protocol Operations Definitions ............................. 21 72 7. Managed Object Definitions .................................. 22 73 8. IANA Considerations ......................................... 26 74 9. Intellectual Property ....................................... 26 75 10. Acknowledgements ........................................... 27 76 11. Security Considerations .................................... 27 77 12. References ................................................. 27 78 13. Editor's Addresses ......................................... 30 79 A. Impact to SNMP and other Protocols .......................... 31 80 A.1. SNMPv3 .................................................... 31 81 A.2. AgentX .................................................... 31 82 B. Examples of Row Operations .................................. 31 83 B.1. CreateRow ................................................. 31 84 B.2. DeleteRow ................................................. 35 85 B.3. GetRow .................................................... 36 86 B.4. GetNextRow ................................................ 39 87 B.5. GetBulkRow ................................................ 41 88 B.6. EditRow ................................................... 48 89 C. Known issues ................................................ 50 90 D. Full Copyright Statement .................................... 51 92 1. The SNMP Network Management Framework 94 The SNMP Management Framework presently consists of five major 95 components: 97 - An overall architecture, described in RFC 2571 [RFC2571]. 99 - Mechanisms for describing and naming objects and events for the 100 purpose of management. The first version of this Structure of 101 Management Information (SMI) is called SMIv1 and described in 102 RFC 1155 [RFC1155], RFC 1212 [RFC1212] and RFC 1215 [RFC1215]. 103 The second version, called SMIv2, is described in RFC 2578 104 [RFC2578], RFC 2579 [RFC2579] and RFC 2580 [RFC2580]. 106 - Message protocols for transferring management information. The 107 first version of the SNMP message protocol is called SNMPv1 and 108 described in RFC 1157 [RFC1157]. A second version of the SNMP 109 message protocol, which is not an Internet standards track 110 protocol, is called SNMPv2c and described in RFC 1901 [RFC1901] 111 and RFC 1906 [RFC1906]. The third version of the message 112 protocol is called SNMPv3 and described in RFC 1906 [RFC1906], 113 RFC 2572 [RFC2572] and RFC 2574 [RFC2574]. 115 - Protocol operations for accessing management information. The 116 first set of protocol operations and associated PDU formats is 117 described in RFC 1157 [RFC1157]. A second set of protocol 118 operations and associated PDU formats is described in RFC 1905 119 [RFC1905]. 121 - A set of fundamental applications described in RFC 2573 122 [RFC2573] and the view-based access control mechanism described 123 in RFC 2575 [RFC2575]. 125 A more detailed introduction to the current SNMP Management Framework 126 can be found in RFC 2570 [RFC2570]. 128 Managed objects are accessed via a virtual information store, termed 129 the Management Information Base or MIB. Objects in the MIB are 130 defined using the mechanisms defined in the SMI. 132 This memo specifies a MIB module that is compliant to the SMIv2. A 133 MIB conforming to the SMIv1 can be produced through the appropriate 134 translations. The resulting translated MIB must be semantically 135 equivalent, except where objects or events are omitted because no 136 translation is possible (use of Counter64). Some machine readable 137 information in SMIv2 will be converted into textual descriptions in 138 SMIv1 during the translation process. However, this loss of machine 139 readable information is not considered to change the semantics of the 140 MIB. 142 2. Overview 144 This document describes a set of SNMP extensions to current protocol 145 operations [RFC1905] to provide for efficient management operations 146 (i.e. creating, modifying, deleting and retrieving table rows and 147 other MIB data). In addition, a new textual convention, RowState, is 148 defined to replace RowStatus in future MIBs. RowState maintains the 149 ability to report the state of a row, but does not provide a 150 mechanism to create or delete a row. 152 2.1. Terms 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 156 document are to be interpreted as described in [RFC2119]. 158 Terminology such as "leftmost" or "left" indicates a PDU component 159 that is transmitted on the wire prior to other components. Thus, 160 terms such as "rightmost" imply components that have similar, but 161 opposite semantics. 163 Protocol operation refers to a high-level request, such as a 164 SetRequest or GetRequest (or one of the six new requests defined 165 within this document). Row operation refers to one logical operation 166 that affects one specific table row. A protocol operation may contain 167 one or more row operations. The term RowOp refers to the aggregate 168 parts of a protocol operation that comprise a single row operation. 170 2.2. Motivations for the Extensions 172 Experience has shown that current SNMP protocol operations and 173 management structures are not ideally suited to effect configuration 174 changes within managed devices and when retrieving large amounts of 175 information. The extensions described in this document are 176 specifically designed to minimize, or provide opportunities to 177 minimize, the following problems which inhibit the effectiveness of 178 SNMP: 180 - Requests that contain multiple varbinds that affect one row of 181 a table may contain significant redundancy of information. This 182 is because each varbind contains an object name (i.e. Object 183 Identifier or OID), and these OIDs may differ only in the 184 single subid that designates a specific column. In cases where 185 strings are used as instance identifiers, for example, UDP 186 maximum-message-size constraints may force multiple SetRequests 187 to be used to construct a new, or modify an existing row in a 188 table. Requests containing redundant data are also more costly 189 to encrypt and decrypt. 191 - SetRequests may contain multiple varbinds that actually refer 192 to the same MIB object. For example, varbind one may be 193 attempting to set the object, foo, to the value 1, while 194 varbind two may be attempting to set the same object, foo, to 195 the value 2. In such cases, the SNMP protocol indicates that 196 implementations may make independent decisions as to which 197 value will be used. 199 - SetRequests do not impose any ordering requirements on the 200 varbinds within a single request, even if they affect different 201 objects in the same row of a table. This can cause added 202 complexity in set request processing. 204 - The RowStatus textual convention [RFC1903] provides a mechanism 205 for row management. RowStatus most often requires the 206 implementation of a rather complicated state machine, many of 207 whose transitions are optional and whose target states are at 208 times non-deterministic. RowStatus also confuses the notion of 209 row status with the notion of row fate, which also tends to 210 complicate both the MIB design and the implementation. 212 2.3. Design Goals 214 Several goals were identified when considering the kind and nature of 215 extensions that were needed: 217 - allow separate row operations (hereafter referred to as RowOps) 218 to be performed in a single protocol operation. 220 - allow operations on individual scalar and/or tabular objects in 221 conjunction with row operations. 223 - minimize redundant information in a protocol operation. The 224 extensions should at least make use of OID suppression 225 techniques to meet this goal. Note that OID suppression 226 (largely an issue of how data is stored within a PDU) is not 227 equivalent to OID compression (data compression algorithms). 228 Issues of OID compression are considered out of scope for this 229 document. 231 - eliminate the need for special MIB objects (e.g. RowStatus) 232 that control the creation and deletion of rows. 234 - minimize the impact on existing network management and subagent 235 protocols such as SNMPv3, AgentX, and related applications. 237 - interoperate with legacy MIBs as well as future MIBs. 239 - operate in existing SNMP networks and not disrupt legacy SNMP- 240 capable devices. 242 3. The Extensions 244 Six new protocol operations are described in this document: 245 CreateRowRequest-PDU (aka CreateRow), DeleteRowRequest-PDU (aka 246 DeleteRow), EditRowRequest-PDU (aka EditRow), GetRowRequest-PDU (aka 247 GetRow), GetNextRowRequest-PDU (aka GetNextRow), and 248 GetBulkRowRequest-PDU (aka GetBulkRow). These requests are based on 249 the BulkPDU structure as originally defined in [RFC1905]. 251 Despite the obvious use of the word "row" throughout this document, 252 these new protocol operations can also be used to create, delete, 253 modify and retrieve non-row data (i.e. scalars); specific details are 254 provided later in the document. 256 For purposes of discussion, the three requests, CreateRow, DeleteRow 257 and EditRow are more generically referred to as SetRow class 258 requests, and GetRow, GetNextRow and GetBulkRow are referred to as 259 RetrieveRow class requests. 261 The CreateRow request can only succeed if it is used to create an 262 aggregate (e.g. row) that doesn't already exist. EditRow has no such 263 constraints and can be used much in the same way traditional 264 SetRequests are used. One noteworthy feature of the GetBulkRow 265 request is that it can perform head and/or tail functions on a table. 266 In addition, all SetRow requests make use of a three-phase processing 267 model in which a new third phase (retrieve) is added to the 268 traditional test and commit phases discussed in [RFC1905]. 270 Another extension defined in this document is the RowState textual 271 convention, which is intended to replace RowStatus in all future MIB 272 designs. It is not the intention to deprecate RowStatus. RowState 273 serves to reestablish a distinction between SNMP data types and SNMP 274 operations -- a line which is blurred in the current RowStatus 275 definition. 277 3.1. RowState 279 The RowState textual convention defined in this document is intended 280 to replace RowStatus in new MIBs and provides several important 281 improvements over RowStatus: 283 - RowState relaxes some of the row timeout rules that RowStatus 284 suffers from. Such rules inhibit the usefulness of RowStatus as 285 a means of temporarily placing system resources (i.e. table 286 rows) out of service. For example, if an SNMP manager changes 287 a given instance of snmpNotifyRowStatus from Active to 288 NotInService as a means of temporarily disabling one or more 289 notifications, an unintended side-effect of this action on some 290 implementations may be that the row is automatically deleted 291 after some short amount of time has elapsed (typically, a few 292 minutes). 294 - More importantly, RowState separates the notion of reporting 295 row status and the notion of managing row fate (i.e. creation & 296 deletion). Specifically, the purpose of RowState is to enable 297 reporting of row state, while matters of creating and deleting 298 rows are better served by protocol operations. 300 RowState provides three states: NotReady, NotInService and Active, 301 which are very similar to the corresponding RowStatus definitions. 302 Unlike RowStatus, RowState does not provide CreateAndWait, 303 CreateAndGo or Destroy. 305 Any entity providing a RowState column in a table must instantiate an 306 instance of RowState when one or more other column objects in the 307 same row have been created or instantiated (by whatever means). Using 308 the new protocol operations defined in this document, it is usually 309 unnecessary to directly set or reference a RowState instance in order 310 to create and activate a new row. 312 3.2. Protocol Operations 314 The new protocol operations are designed to "fit" in the existing 315 BulkPDU structure [RFC1905]. Formal definitions of the new protocol 316 operations are provided in section 6. 318 This document specifies an evolutionary approach in the way the new 319 protocol operations are encoded or contained within the BulkPDU. The 320 new requests capitalize on OID suppression techniques to minimize 321 information redundancy and therefore minimize PDU size. Note that the 322 traditional SNMP protocol operations [RFC1905] are not being changed, 323 either in their semantics, the way data is encoded within them, or 324 the way they are processed. 326 The following general discussion centers on how the varbinds of the 327 new protocol operations and their responses are constructed and 328 generally used. The elements of procedure formally describes how the 329 new requests are processed and how the responses are constructed. The 330 APPENDIX provides high-level examples of protocol exchanges using the 331 extensions. 333 Each varbind in a request serves one of three purposes: as a 334 Singleton, as a RowIdentifier or as an Operand. 336 3.2.1. Singletons 338 A varbind that serves as a Singleton functions more or less like 339 varbinds in a traditional SNMP request (e.g. SetRequest, GetRequest). 340 They are encoded in the same manner, and except for prefix-level 341 inheritance (described below), they do not take advantage of OID 342 suppression techniques. Singletons may exist in any SetRow or 343 RetrieveRow class request or response, but if they do exist in any 344 request, they MUST be the first N varbinds in the request, where N is 345 provided in the non-repeaters field of the request. N may be zero to 346 indicate that Singletons have not been included in the request. If N 347 Singletons are included in a request, then the same N Singletons will 348 also exist in the response, although in a successful response to a 349 GetBulkRow request, additional Singletons may also be present. 351 The set of Singletons contained in a request SHOULD be ordered so 352 that the name of Singleton i is lexicographically smaller than 353 Singleton i+1, though SNMP applications MUST be prepared to accept 354 unordered Singletons. 356 Singletons may be included within a CreateRow or a DeleteRow request. 357 Such Singletons indicate a specific object instance within an 358 aggregate (e.g. a row or a group scalar) upon which a creation or 359 deletion operation is performed. By default, the operation takes 360 affect on all object instances within the same aggregate; however, 361 aggregate semantics may be defined (within the relevant description 362 clauses) as to whether only the directly referenced objects in the 363 Singletons are instead affected. Usually, Singletons are not 364 included within CreateRow and DeleteRow requests, but there are cases 365 when they may be needed (one of the protocol exchange examples in the 366 APPENDIX illustrates such a case). 368 Within any EditRow class request, Singletons function much like 369 individual varbinds within a conventional SetRequest, and the name of 370 any Singleton MUST NOT refer to any other Singleton or to any 371 existing (or not) object within any RowOp of the same EditRow 372 request. 374 Within the GetRow request, Singletons function much like individual 375 varbinds within a conventional GetRequest. 377 Within the GetNextRow request, Singletons function much like 378 individual varbinds within a conventional GetNextRequest. 380 Within the GetBulkRow request, Singletons function much like the 381 non-repeaters varbinds in the conventional GetBulk request; thus, 382 they function as GetNextRequest varbinds. 384 The remaining varbinds in any request form one or more independent 385 RowOps with each varbind serving as either a RowIdentifier or as an 386 Operand component of a RowOp. 388 3.2.2. The RowOp 390 The new requests defined in this document may generally contain zero 391 or more RowOps. This allows a single CreateRow request, for example, 392 to create one or more new rows in a single protocol operation. Each 393 RowOp corresponds to one attempt to create a row, in this case, or 394 corresponds to one attempt to delete a row in the case of DeleteRow, 395 and so forth. 397 Note that the three layers in the diagram below do not describe 398 different sections of the request, rather, they each represent the 399 same information and structure (at different levels of abstraction). 401 402 403 405 Although the above diagram shows a CreateRow request logically 406 containing three RowOps (i.e. create three rows) with two consecutive 407 varbinds per RowOp, in reality, these requests may contain zero to 408 many RowOps, each of which may may be comprised of a differing number 409 of varbinds. 411 The first varbind in each RowOp is hereafter referred to as the 412 RowIdentifier of a RowOp. The remaining varbinds in a given RowOp 413 provide the individual operands (i.e. the affected row objects), 414 which are hereafter referred to as Operands. In the diagram above, 415 the 1st, 3rd and 5th varbinds are therefore RowIdentifiers and the 416 2nd, 4th and 6th varbinds are Operands. 418 3.2.3. The RowIdentifier 420 The following diagram shows a GetRow request containing a single 421 RowOp that itself is composed of the required RowIdentifier and two 422 Operands. In this case, the GetRow request is seeking to retrieve 423 two specific column objects from a specific row. 425 426 427 429 A traditional OID for a given object instance in a table can be 430 broken up into these logical components: 432 OID = <1> 434 ObjectSubid is equivalent to one of the column descriptors. A more 435 formal representation for RowIdentifier is now possible: 437 RowIdentifier = 441 The component, AggName (Aggregate Name), takes the same value of 442 TableName. 444 The vb.type MUST specify a type of OID. This is because the instance 445 part of an OID is actually comprised of one or more table index 446 values, each of which resolves to one or more subids. 448 Because the Instance always resolves to zero or more subids (because 449 there are cases when Instance is optional within a RowIdentifier), 450 and because a valid OID must be composed of at least two subids, 451 Instance is prefixed with the OID value of 1.0. The reason for this 452 choice of prefixes is that every valid table object name contains the 453 value of <1.ObjectSubid> as part of its OID. 455 The AggName of a RowIdentifier MUST NOT contain partial OIDs. This 456 means that the AggName MUST always exactly correspond to a legal 457 table definition (if the desired results are to be achieved). The 458 motivation behind this is that all RowOps are performed at the row 459 level on a specific table. 461 The Instance within a GetNextRow is not required to be fully formed 462 except that if the value is non-NULL, it MUST at least contain the 463 1.0 prefix. Also note that GetNextRow RowOps do not "jump" to the 464 next table. In other words, in the event a GetNextRow RowOp refers 465 to the last row in a given table, the appropriate exception is 466 returned for that RowOp even if other tables follow that contain 467 retrievable rows. In this sense, GetNextRow RowOps are limited to 468 operate within the subtree of the targeted table(s), though the 469 Singletons within a GetNextRow or GetBulkRow request have no such 470 constraint. 472 3.2.4. RowIdentifiers in GetBulkRow Requests 474 GetBulkRow RowIdentifiers have a slightly different construction than 475 the RowIdentifiers for the other five request types. The diagram 476 below shows two new components are included in these RowIdentifiers, 477 InstanceLen and Instance2. 479 RowIdentifier = 483 The two instance components define the search range of the GetBulkRow 484 request (i.e. the rows from which data may be returned). Unlike the 485 traditional GetBulk request, which may operate across one or more 486 tables and/or scalar objects, each RowOp within a GetBulkRow request 487 is confined to operate only within the table specified by the AggName 488 component, although each RowOp may operate on different tables. 489 Furthermore, each RowOp operates only within the range of rows as 490 specified by the two instance components (inclusive) and upon one or 491 more columns within that row range, as specified by the Operands that 492 are associated with the RowOp. 494 The InstanceLen component specifies the number of subids that 495 comprise Instance. InstanceLen may be 0, which indicates that 496 Instance is not provided and that the search range begins at the 497 first row (head) of the table and ends with the row specified by 498 Instance2. Instance or Instance2 need not resolve to existing rows. 500 The number of subids in Instance2 may be 0 or more, and if 0 (i.e. 501 Instance2 is not provided), this indicates that the search range 502 includes any row that may correspond to the row specified by Instance 503 and all those that follow (i.e. to the end of the table). 505 If Instance2 is lexicographically identical to Instance, the search 506 range is confined to the one row common to both instances, or if 507 identical values do not resolve to an existing row, a NuSuchInstance 508 error is returned. If Instance2 is lexicographically smaller than 509 Instance, a NoSuchInstance error will be returned. 511 The max-repetitions field in the GetBulkRow request may contain a 512 non-zero value (M) to indicate a head or tail function should be 513 performed for each RowOp in the request. Otherwise, max-repetitions 514 MUST always be zero (for all request types). If InstanceLen contains 515 the value 0 (i.e. Instance is not provided), at most M rows will be 516 returned from the head of the table. If InstanceLen contains a non- 517 zero value (i.e. Instance is provided), then at most M rows at the 518 tail of the table will be returned. For a head function, all returned 519 rows MUST be lexicographically smaller than or equal to Instance2, if 520 provided. For a tail function, all returned rows MUST be 521 lexicographically greater than or equal to Instance; and Instance2, 522 if provided, is ignored. The Instance2 component of a given RowOp, 523 therefore, SHOULD NOT be provided in a GetBulkRow request whose max- 524 repetitions and InstanceLen values are both non-zero as this 525 unnecessarily increases PDU size. 527 Whether the GetBulkRow request indicates a head or tail function (or 528 neither), it should be noted that the vb.value can be provided as 529 either 1.0.0 or as 1.0 to indicate that the desired search range 530 includes the entire table. The latter OID is slightly more efficient, 531 and both forms have the same semantics unless a head or tail function 532 is indicated (max-repetitions is non-zero). If max-repetitions is 533 non-zero and the vb.value = 1.0.0, this indicates a head function 534 whose search range is the entire table. If max-repetitions is non- 535 zero and the vb.value = 1.0, this indicates a tail function whose 536 search range is the entire table. 538 3.2.5. RowIdentifier Inheritance 540 Several forms of OID inheritance are possible within RowIdentifiers 541 in order to further minimize PDU size: name-level, prefix-level, and 542 instance-level inheritance. 544 In order to further minimize information redundancy, the OID of 0.0 545 is permitted to be substituted as the AggName component of any 546 RowIdentifier to indicate that the most recent (left) RowIdentifier 547 whose AggName is dissimilar (not 0.0) contains the OID value intended 548 to be used. 550 In this example, a simplified notation is used to help illustrate how 551 RowOps (the two middle ones) use the inheritance OID to minimize PDU 552 size. This example shows four RowOps, each comprised of one 553 RowIdentifier and one Operand (op): 555 [] [<0.0>] [<0.0>] [] 557 The following is logically identical, though it forms a larger PDU: 559 [] [] [] [] 561 In order for an inheritance OID to be correctly used, all RowOps that 562 affect the same table MUST be consecutively placed in the varbind 563 list, and also the first such RowIdentifier MUST NOT contain the 564 inheritance OID. The above is known as name-level inheritance. 566 If a RowIdentifier of any request type has a NULL varbind value, this 567 indicates that the most recent non-NULL varbind value is to be 568 inherited. If the first RowIdentifier in a request contains a NULL 569 varbind value, the OID of 1.0 will be substituted. This is known as 570 instance-level inheritance. 572 The third form of inheritance (prefix-level inheritance) occurs 573 whenever the varbind name of any AggName of a RowIdentifier begins 574 with the OID prefix of 0.0 AND four or more subids exist in the OID. 575 In such cases, the OID value of 1.3.6.1 is to be substituted in place 576 of the 0.0 prefix. 578 The example below shows two RowOps, each comprised of one 579 RowIdentifier and one Operand (op). Name- and prefix-level 580 inheritance are used: 582 [<0.0.foo>] [<0.0>] 584 The following is logically identical, though it forms a larger PDU: 586 [<1.3.6.1.foo>] [<1.3.6.1.foo>] 588 The following OID is not a candidate for prefix-level inheritance 589 because it has less than four subids: 0.0.1 591 Each RowOp is fully independent of any other despite any inheritance 592 it may use. 594 3.2.6. The Operands 596 The remaining varbinds for a given RowOp are referred to as its 597 Operands and are formed as standard request varbinds except that the 598 name of each varbind is an OID whose length is either two or three 599 subids long, as follows: 601 0.ObjectSubid (where ObjectSubid > 0 and ObjectSubid <= 39) 603 or 605 0.1.ObjectSubid (where ObjectSubid == 0 or ObjectSubid > 39) 607 Each Operand contained in the same RowOp SHOULD be ordered according 608 to ascending values of the ObjectSubids. 610 By way of example, if a table, foo, had four columns whose 611 descriptors (ObjectSubids) were 0, 1, 39 and 40, their Operand names 612 would be 0.1.0, 0.1, 0.39 and 0.1.40, respectively. Because the 613 majority of MIB object descriptors are between 1 and 39, typical 614 Operand names will take the form of 0.X. 616 3.2.7. Extended Error Codes 618 In addition to the standard error-status and error-index values in a 619 response PDU, and varbind-level exceptions, an implementation MAY 620 provide application-specific (extended) error indications in any 621 response by inserting one new varbind at the end of the varbind list. 622 Only the last varbind MAY contain extended error information. 624 Extended error information may be included in the PDU whether or not 625 other errors/exceptions are indicated in the response (e.g. error- 626 status). 628 The name of any varbind containing an extended error code is 629 constructed as follows: 631 0.0.<...> 633 Each ErrorInfo component is constructed as follows: 635 0.ErrorCode[.] 637 The ErrorInfo component may repeat multiple times but MUST have at 638 least one occurrence. The leading subid of 0 in the ErrorInfo 639 component serves as a separator between successive ErrorInfo 640 components. 642 ErrorCode is a value in the range 1..4294967295. 644 The optional VbList is one or more subids which indicates a list of 645 varbind positions (one per subid) within the same response PDU that 646 associate to the preceding ErrorCode. The subids MUST be a value in 647 the range of 1..max-bindings [RFC1905]. 649 The value component of a varbind containing an extended error 650 information is always NULL. 652 A properly formed varbind name will have a prefix of 0.0.0. This 653 prefix allows EOS-enabled SNMP applications to distinguish these 654 varbinds from all other varbind types (i.e. Singletons, 655 RowIdentifiers or Operands). 657 The ErrorCode of 3 in the following example indicates the 4th and 5th 658 varbinds raised that error. 660 vb.name = 0.0.0.3.4.5 661 vb.name = NULL 663 The same varbinds MAY be associated to one or more extended error 664 codes. The following example indicates an error code of 2 (for 665 varbinds 1 and 2), an error code of 5 (no specific varbinds 666 provided), an error code of 8 (for varbinds 2, 6 and 7) and an error 667 code of 9 (for varbind 8). An error code that does not have a VbList 668 (e.g. 5 in the above example) maps to a condition that applies to the 669 entire PDU as opposed to a set of varbinds. 671 vb.name = 0.0.0.2.1.2.0.5.0.8.2.6.7.0.9.8 672 vb.name = NULL 674 The set of all returned errors and exceptions indicated within a 675 Request-PDU is comprised of the error indicated in error-status (and 676 error-index), if any, the extended errors codes, if any, and the 677 exceptions present in any varbind, if any. Each error and/or 678 exception is independent of any other. 680 An implementation SHOULD NOT provide extended error information if 681 the desired information can instead be adequately conveyed using the 682 error-status/index fields or varbind-level exceptions. An 683 implementation MAY use extended error codes to convey a more detailed 684 error status than is otherwise possible using traditional 685 error/exception mechanisms. For example, if a wrongValue error is 686 returned for varbind 5, an implementation may also choose to provide 687 an extended error value to indicate that the provided value was 688 "TooLarge". 690 The presence of extended error codes (or lack thereof) in a response 691 does not guarantee all possible errors in the original request have 692 been identified (or that there are no unknown errors). The presense 693 of extended error information does not determine success/failure of a 694 protocol operation. Rather, the error-status of noError implies a 695 successful operation, whereas all other error-status values imply 696 failure. 698 The method used to impart meaning to the returned error values is out 699 of scope to this document. See [TBD] for details. 701 3.2.8. RowOps and Group Scalar Objects. 703 It is also possible to use the new requests to access or modify 704 groups of scalar objects where each RowOp relates to a specific 705 group. The only exception to this is that GetBulkRow RowOps are 706 limited to operating on tables only (though the Singletons within a 707 GetBulkRow may reference scalar objects). 709 To form a valid RowOp that refers to a group, the following MUST be 710 done: First, the AggName instead refers to a valid group OID (e.g. 711 the system group OID is 1.3.6.1.2.1.1), second, the RowIdentifier 712 Instance prefix value is always provided as 0.0 (instead of 1.0 as 713 for tables) and third, there is no Instance provided. The following 714 example shows the relevant OIDs within a RowOp which accesses the 715 system group scalars: 717 RowIdentifier = -- not a table 720 Operand1 = 0.1 -- sysDescr 721 Operand2 = 0.2 -- sysObjectID 722 Operand3 = 0.3 -- sysUptime 723 Operand4 = 0.4 -- sysContact 724 Operand5 = 0.5 -- sysName 725 Operand6 = 0.6 -- sysLocation 726 Operand7 = 0.7 -- sysServices 728 A CreateRow request can be used for group scalars if the affected 729 scalars MAX-ACCESS values are read-create and the objects do not 730 exist. 732 A DeleteRow request can be used for group scalars if the affected 733 scalars MAX-ACCESS values are read-create. 735 An EditRow request can be used for group scalars if the affected 736 scalars MAX-ACCESS values are either read-write or read-create. 738 The GetRow or GetNextRow requests may also be used for group scalars. 740 The following shows a request with three RowOps using instance-level 741 inheritance for group scalar access: 743 [] 744 [] 745 [] 747 The following is logically identical to the above example, though it 748 forms a larger PDU: 750 [] 751 [] 752 [] 754 3.2.9. Three-Phase Sets 756 All SetRow requests are processed using a three-phase processing 757 model instead of the two-phase model defined in [RFC1905]. The new 758 third phase (retrieve Operand values) occurs only if the first phase 759 (test) completes successfully. If the test phase results in an 760 error, all Operand values in the response will be set to NULL or 761 appropriate errors and exceptions will be returned. Otherwise, all 762 Operand values in the response will contain the value of the 763 indicated object as it exists at the start of the third-phase (i.e. 764 after the completion of the commit phase) or may contain exceptions 765 if the Operand value is unavailable. In the event any Operand refers 766 to an object which is known to have existed at the start of the first 767 phase but not at the start of the third phase (as is possible with 768 DeleteRow), the value of such Operands will be NULL in the final 769 response. 771 3.2.10. Response PDUs 773 The traditional Response-PDU [RFC1905] is used as the standard 774 response to each of the SetRow and RetrieveRow requests, except that 775 the varbinds are constructed using the same OID suppression 776 techniques as described above and, except for a successful GetBulkRow 777 response, the number and type of varbinds (though not necessarily 778 their names and values) returned are identical to the original 779 request. Any response MAY also contain an additional varbind (the 780 last) containing extended error information. The structure and 781 contents of GetBulkRow responses are a bit more unpredictable. 783 Singletons within a GetBulkRow (or any) request always have 784 corresponding Singletons in the response (i.e. the first N varbinds 785 MAY be Singletons). The RowOps in a GetBulkRow request, however, are 786 not returned in a successful response; instead, new RowOps and/or 787 Singletons are inserted into the response after varbind N. A RowOp 788 will be included only if it contains two or more Operands, whereas a 789 Singleton will be included if a RowOp with only one Operand from a 790 given row would otherwise be returned. Thus, RowOps and Singletons 791 may be interspersed together in the response, although in all cases 792 they are provided in row by row order. 794 The returned row information MUST be ordered so that RowOp i is 795 lexicographically smaller than or equal to RowOp i+1. RowOps with 796 similar AggName values MUST also be sub-ordered in lexicographically 797 ascending order based on their Instance values. Any two returned 798 RowOps MUST NOT contain identical AggName and Instance values. 800 Similarly, for all new Singletons included after varbind N, Singleton 801 i MUST be lexicographically smaller than Singleton i+1 and they MUST 802 be interspersed with RowOps so that all RowIdentifier and Singleton 803 varbinds (after varbind N) are ordered in lexicographically ascending 804 order. In addition, Singletons MUST NOT be inserted between any 805 RowIdentifier and one of its Operands. 807 If an otherwise successful response to a GetBulkRow request ever 808 fails to include all the data requested (due to PDU size 809 limitations), then the response MAY include an appropriate extended 810 error indicating this fact. In this way, the last RowOp (or 811 Singleton) in the response contains an Instance that can be used to 812 calculate the beginning search range for a subsequent GetBulkRow 813 request. 815 SNMP applications which generate GetBulkRow requests MUST preserve 816 (i.e. remember) the value of the non-repeaters field for each request 817 where it was non-zero. This allows the application to easily and 818 correctly distinguish the first N (N = non-repeaters) Singletons from 819 subsequent response components. 821 3.2.11. Determining Varbind Roles 823 Varbinds function as either Singletons, RowIdentifiers, Operands, or 824 as carriers of extended error information. It is important for an 825 implementation to correctly determine the role of every varbind in 826 any given request or response. The following procedure is used to 827 correctly identify the role of a given varbind, V, where V is a value 828 in the range (1..max-bindings) in a request or response, and where N 829 = non-repeaters in the associated request. The first rule below that 830 applies determines the correct role of the varbind. 832 - If V <= N, and N > 0, V is a Singleton. 834 - If V is the last varbind in a Response-PDU, and V has a name 835 prefixed by the value, 0.0.0, V contains extended error 836 information. 838 - If the name of V is comprised of exactly two subids and this 839 name is the value 0.X (where X > 0 and X <= 39), V is an 840 Operand. 842 - If the name of V is comprised of exactly three subids and this 843 name is the value 0.1.X (where X = 0, or X > 39), V is an 844 Operand. 846 - If V is in any request or response other than a successful 847 GetBulkRow response, V is a RowIdentifier. 849 - If V is in a successful GetBulkRow response and the varbind V+1 850 exists, and varbind V+1 is an Operand, then V is a 851 RowIdentifier. 853 - If V is in a successful GetBulkRow response and the varbind V+1 854 exists, and varbind V+1 is NOT an Operand, then V is a 855 Singleton. 857 - Otherwise, V is a Singleton 859 4. Elements of Procedure 861 4.1. CreateRow Request Processing 863 TBD 865 4.2. DeleteRow Request Processing 867 TBD 869 4.3. EditRow Request Processing 871 TBD 873 4.4. GetRow Request Processing 875 TBD 877 4.5. GetNextRow Request Processing 879 TBD 881 4.6. GetBulkRow Request Processing 883 TBD 885 4.7. Response-PDU Processing 887 TBD 889 5. Coexistence and Transition 891 An essential requirement for these operations is that they must 892 operate seamlessly in existing networks and not disrupt legacy SNMP 893 devices. This is satisfied by the fact that the new protocol 894 operations have new and unique ASN.1 tags, which allow older 895 implementations to efficiently and silently drop these new requests. 897 Some entities may only support these extensions for certain tables. 898 For example, different AgentX subagents may or may not support these 899 operations. This requires that the requests fail whenever a table is 900 targeted that cannot support the new operation. The elements of 901 procedure indicate the proper exceptions in these cases. 903 It is also possible that some table implementations may support only 904 some subset of the new operations, for example, the RetrieveRow 905 requests, but not the SetRow requests. 907 In an ideal world, the extensions herein would be easily translatable 908 to traditional operations. However, this is not the case for the 909 CreateRow, DeleteRow and GetBulkRow requests. On the other hand, it 910 is believed the GetRow, GetNextRow and EditRow requests can be 911 translated into conventional request formats (or subagent 912 operations). 914 One possible transition strategy is to enable existing SNMP 915 applications to support GetRow, GetNextRow and EditRow requests (with 916 or without the traditional requests). A proxy application, for 917 example, could bridge an EOS network with a non-EOS network by 918 translating those EOS requests into conventional requests (and 919 responses). Similarly, an AgentX master agent could translate this 920 same subset of EOS requests into conventional AgentX requests (and 921 responses). The benefits achieved with this strategy would be to 922 obtain smaller PDU sizes on the network along with a 100% reuse of 923 existing instrumentation methods (and subagent protocols). Subsequent 924 support of the CreateRow, DeleteRow and GetBulkRow requests is always 925 possible at a future date, or on a subagent by subagent basis 926 (assuming a compatible subagent protocol has been adopted). 928 The procedures to translate EOS requests into conventional 929 operations, where possible, are out of scope of this document. 931 It is RECOMMENDED, however, that new SNMP implementations support 932 (for all MIB objects) all of the RetrieveRow class of requests. It is 933 further RECOMMENDED that new implementations supporting any of the 934 SetRow class of requests instead support all of the SetRow requests 935 (for all applicable MIB objects). 937 Also, it is RECOMMENDED that new SNMP MIBs SHOULD use the RowState 938 textual-convention in lieu of RowStatus, if applicable. 940 Proxy applications wishing to fulfill these recommendations can only 941 serve as EOS request forwarders for the CreateRow, DeleteRow and 942 GetBulkRow requests, and as request translators (or forwarders) for 943 the other requests. 945 6. Protocol Operations Definitions 947 SNMP-ROWOP-PDUS-MIB DEFINITIONS ::= BEGIN 949 IMPORTS 950 BulkPDU 951 SNMPv2-PDU; 953 ROWOP-PDUs ::= 954 CHOICE { 955 create-row-request 956 CreateRowRequest-PDU, 958 delete-row-request 959 DeleteRowRequest-PDU, 961 edit-row-request 962 EditRowRequest-PDU, 964 get-row-request 965 GetRowRequest-PDU, 967 get-next-row-request 968 GetNextRowRequest-PDU 970 get-bulk-row-request 971 GetBulkRowRequest-PDU 972 } 974 CreateRowRequest-PDU ::= 976 [9] 977 IMPLICIT BulkPDU 979 DeleteRowRequest-PDU ::= 980 [10] 981 IMPLICIT BulkPDU 983 EditRowRequest-PDU ::= 984 [11] 985 IMPLICIT BulkPDU 987 GetRowRequest-PDU ::= 988 [12] 989 IMPLICIT BulkPDU 991 GetNextRowRequest-PDU ::= 992 [13] 993 IMPLICIT BulkPDU 995 GetBulkRowRequest-PDU ::= 996 [14] 997 IMPLICIT BulkPDU 999 END 1001 7. Managed Object Definitions 1003 SNMP-ROWOP-MIB DEFINITIONS ::= BEGIN 1005 IMPORTS 1006 MODULE-IDENTITY, OBJECT-TYPE, 1007 OBJECT-IDENTITY, 1008 snmpModules FROM SNMPv2-SMI 1009 TEXTUAL-CONVENTION FROM SNMPv2-TC 1010 MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF; 1012 snmpRowopMIB MODULE-IDENTITY 1013 LAST-UPDATED "200106151500Z" 1014 ORGANIZATION "EOS Working Group" 1015 CONTACT-INFO "WG-EMail: eos@ops.ietf.org 1016 Subscribe: eos-request@ops.ietf.org 1018 Co-Chair: Dale Francisco 1019 EMail: dfrancisco@acm.org 1020 phone: +1 408-324-1389 1022 Co-Chair: Glenn Waters 1023 Nortel Networks 1024 EMail: gww@nortelnetworks.com 1026 Editor: Lauren Heintz 1027 Cisco Systems, Inc. 1028 postal: 130 Baytech Drive 1029 San Jose, CA 95134 1030 USA 1031 EMail: lheintz@cisco.com 1032 phone: +1 408-853-6568 1033 " 1034 DESCRIPTION "The SNMP Row Operations MIB" 1035 REVISION "200106151500Z" 1036 DESCRIPTION "The initial version, published in 1037 draft-ietf-eos-snmp-rowops-01.txt. 1038 " 1039 ::= { snmpModules TBD } 1041 -- Textual Conventions 1043 RowState ::= TEXTUAL-CONVENTION 1044 STATUS current 1045 DESCRIPTION " 1046 This textual-convention provides a means 1047 to represent the state of a conceptual row; 1048 it does not provide a means to manage creation 1049 and/or destruction of conceptual rows. 1051 In any row which includes a definition of RowState 1052 that is also mandatory, that row MUST contain 1053 an instantiation of a RowState object if any other 1054 object in the same row is instantiated. 1056 A status column of this type has three defined 1057 values: 1059 - `active', which indicates that the 1060 conceptual row is in use by the managed 1061 device and is considered fully operational 1062 from a management perspective; 1064 - `notInService', which indicates that the 1065 conceptual row is available for use by 1066 the managed device but is NOT considered 1067 fully operational from a management 1068 perspective; a row in this state contains 1069 all information necessary for a transition to 1070 the active state; 1071 - `notReady', which indicates that the 1072 conceptual row is not available for use 1073 by the managed device, perhaps because the 1074 row is missing information or the row has 1075 been explicitly set to this state; 1077 Any of the three states may be specified in a 1078 management protocol set operation. At any time, 1079 the value of an existing RowState object may be 1080 modified or changed to any other state unless 1081 the current value is notReady and the row (after 1082 completion of a management set operation) would 1083 not be consistent with an active state (i.e. 1084 information is missing or inconsistent and as a 1085 result the row could not assume an active state 1086 until further management set operations were 1087 performed). In this case, the value MUST remain 1088 at notReady and an inconsistentValue error is 1089 returned. 1091 A RowState object whose value is notReady MUST 1092 implicitly promote itself from notReady to 1093 notInService if any management protocol set 1094 operation not referencing the status column 1095 explicitly changes the value of any other object 1096 in the same row AND the row afterward is now 1097 consistent with the active state (i.e all 1098 information needed to make the row active is 1099 available). 1101 When a row does not exist, and a management 1102 protocol set operation causes any object in the row 1103 to be created, the status object will also be 1104 instantiated and its initial value will be determined 1105 by the first of the following rules that are satisfied: 1107 1. if the set operation includes an initial value, 1108 the RowState object will take on the highest 1109 value (i.e. active is highest) consistent with 1110 the state definitions, but no higher than the 1111 provided value. For example, if a set operation 1112 contains a varbind where RowState=notInService 1113 (or active), the initial value will be notReady 1114 if the row is in an inconsistent state after the 1115 operation is complete; otherwise, it will be 1116 notInService (or active). 1118 2. if the set operation does not include an initial 1119 value, but the RowState definition does include 1120 a supported DEFVAL, the initial value will be the 1121 highest value consistent with the state definitions 1122 but no higher than the value specified in the 1123 DEFVAL, unless the DEFVAL specifies a value of 1124 notReady, which in this case, the DEFVAL is ignored 1125 (i.e. case 3 below instead applies). 1127 3. otherwise, the set operation does not include an 1128 initial value, and the RowState definition does 1129 not include a DEFVAL, and the initial value will 1130 be set to the highest value consistent with the 1131 state definitions. Thus, the initial state will 1132 be active if the new row is consistent with that 1133 state, or it will be notReady otherwise. 1135 No constraint is imposed on whether other objects 1136 in the same row can be modified, regardless of the 1137 value of the associated RowState object. If such 1138 constraints are desired, they MUST be explicitly 1139 stated in the DESCRIPTION clause of the status column. 1140 In the absence of such statements, the managed device 1141 MUST allow any object in any row to be modified at 1142 any time, notwithstanding the possibility that other 1143 MIB objects MAY also impose similar constraints. 1144 An inconsistentValue error is returned when an invalid 1145 attempt is made to alter a row whose state precludes 1146 such an operation. 1148 RowState description clauses, in addition to 1149 the DESCRIPTION clauses of associated column 1150 objects, SHOULD together describe the general 1151 conditions under which a row can be made active. 1152 In the absence of such statements, any row SHOULD 1153 generally be capable of being made active at any 1154 time. 1156 The agent must detect conceptual rows that 1157 have been in the notReady state for an abnormally 1158 long period of time and remove them. It is the 1159 responsibility of the DESCRIPTION clause of the 1160 status column to indicate what an abnormally long 1161 period of time would be. This period of time should 1162 be long enough to allow for human response time 1163 (including `think time') between the creation of the 1164 conceptual row and the setting of the status to `active'. 1165 In the absense of such information in the DESCRIPTION 1166 clause, it is suggested that this period be approximately 1167 5 minutes in length. This removal action applies not only 1168 to newly-created rows, but also to previously active rows 1169 which are set to, and left in, the notReady state for a 1170 prolonged period exceeding that which is considered normal 1171 for such a conceptual row." 1172 SYNTAX INTEGER { 1173 active(1), 1174 notInService(2), 1175 notReady(3) 1176 } 1178 END 1180 8. IANA Considerations 1182 This document requires IANASnmpExtendedProtocol values to be reserved 1183 for allowing command responders to advertise their ability to support 1184 the extensions outlined in this document. IANASnmpExtendedProtocol 1185 values are administered by IANA. IANASnmpExtendedProtocol is defined 1186 in SNMP-X-PROTOCOL-TC. 1188 9. Intellectual Property 1190 The IETF takes no position regarding the validity or scope of any 1191 intellectual property or other rights that might be claimed to 1192 pertain to the implementation or use of the technology described in 1193 this document or the extent to which any license under such rights 1194 might or might not be available; neither does it represent that it 1195 has made any effort to identify any such rights. Information on the 1196 IETF's procedures with respect to rights in standards-track and 1197 standards-related documentation can be found in BCP-11. Copies of 1198 claims of rights made available for publication and any assurances of 1199 licenses to be made available, or the result of an attempt made to 1200 obtain a general license or permission for the use of such 1201 proprietary rights by implementors or users of this specification can 1202 be obtained from the IETF Secretariat. 1204 The IETF invites any interested party to bring to its attention any 1205 copyrights, patents or patent applications, or other proprietary 1206 rights which may cover technology that may be required to practice 1207 this standard. Please address the information to the IETF Executive 1208 Director. 1210 10. Acknowledgements 1212 This document is the result of the efforts of the Evolution Of SNMP 1213 (EOS) Working Group. Some special thanks are in order to the 1214 following EOS WG members for their ideas, efforts and asundry 1215 contributions: 1217 Dr. Jeff Case 1218 Sharon Chisholm 1219 Dale Francisco 1220 Sandra McLeod 1221 Steve Moulton 1222 David Perkins 1223 Randy Presuhn 1224 Jeurgen Schoenwaelder 1225 Robert Story 1226 Glenn Waters 1227 Matt White 1229 11. Security Considerations 1231 TBD 1233 12. References 1235 [RFC1155] Rose, M. and K. McCloghrie, "Structure and 1236 Identification of Management Information for TCP/IP- 1237 based internets", STD 16, RFC 1155, May 1990. 1239 [RFC1157] Case, J., M. Fedor, M. Schoffstall and J. Davin, "The 1240 Simple Network Management Protocol", STD 15, RFC 1157, 1241 May 1990. 1243 [RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions", 1244 STD 16, RFC 1212, March 1991. 1246 [RFC1901] The SNMPv2 Working Group, Case, J., McCloghrie, K., 1247 Rose, M. and S. Waldbusser, "Introduction to 1248 Community-based SNMPv2", RFC 1901, January 1996. 1250 [RFC2571] Harrington, D., Presuhn, R., and B. Wijnen, "An 1251 Architecture for Describing SNMP Management Frameworks", 1252 RFC 2571, April 1999. 1254 [RFC2578] McCloghrie, K., Perkins, D. and J. Schoenwaelder, 1255 "Structure of Management Information Version 2 (SMIv2)", 1256 STD 58, RFC 2578, April 1999. 1258 [RFC2579] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 1259 "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1260 1999. 1262 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 1263 "Conformance Statements for SMIv2", STD 58, RFC 2580, 1264 April 1999. 1266 [RFC-PROTO] Presuhn, R., Case, J., McCloghrie, K., Rose, M., and S. 1267 Waldbusser, "Protocol Operations for the Simple Network 1268 Management Protocol", , June 2001. 1271 [RFC-TMM] Presuhn, R., Case, J., McCloghrie, K., Rose, M., and S. 1272 Waldbusser, "Transport Mappings for the Simple Network 1273 Management Protocol", , June 2001. 1276 [RFC-MIB] Presuhn, R., Case, J., McCloghrie, K., Rose, M. and S. 1277 Waldbusser, "Management Information Base for the Simple 1278 Network Management Protocol", , June 2001. 1281 [RFC-COEX] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 1282 "Coexistence between Version 1, Version 2, and Version 3 1283 of the Internet-standard Network Management Framework", 1284 , June 2001. 1286 [RFC1909] McCloghrie, K., Editor, "An Administrative 1287 Infrastructure for SNMPv2", RFC 1909, February 1996. 1289 [RFC1910] Waters, G., Editor, "User-based Security Model for 1290 SNMPv2", RFC 1910, February 1996. 1292 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 1293 10646", RFC 2279, January, 1998. 1295 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1296 Requirement Levels", BCP 14, RFC 2119, March 1997. 1298 [BCP-11] Hovey, R. and S. Bradner, "The Organizations Involved in 1299 the IETF Standards Process", BCP 11, RFC 2028, October 1300 1996. 1302 [RFC2863] McCloghrie, K. and F. Kastenholz. "The Interfaces Group 1303 MIB." RFC 2863, June 2000. 1305 [SNMP-MPD] Case, J., Harrington, D., Presuhn, R. and B. Wijnen, 1306 "Message Processing and Dispatching for the Simple 1307 Network Management Protocol (SNMP)", , June 2001. 1310 [SNMP-USM] Blumenthal, U. and B. Wijnen, "The User-Based Security 1311 Model for Version 3 of the Simple Network Management 1312 Protocol (SNMPv3)", , 1313 June 2001. 1315 [SNMP-ACM] Wijnen, B., Presuhn, R. and K. McCloghrie, "View-based 1316 Access Control Model for the Simple Network Management 1317 Protocol (SNMP)", , 1318 February 1999. , June 1319 2001. 1321 [RFC-APPL] Levi, D., Meyer, P. and B. Stewart, "SNMP 1322 Applications", , June 1323 2001. 1325 [RFC2570] Case, J., Mundy, R., Partain, D. and B. Stewart, 1326 "Introduction to Version 3 of the Internet-standard 1327 Network Management Framework", , January 1999. 1330 [RFC-COEX] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 1331 "Coexistence between Version 1, Version 2, and Version 3 1332 of the Internet-standard Network Management Framework", 1333 , June 2001. 1335 13. Editor's Addresses 1337 Lauren Heintz 1338 Cisco Systems, Inc. 1339 130 Baytech Drive 1340 San Jose, Ca 95134 1342 Phone: +1 408-853-6568 1343 EMail: lheintz@cisco.com 1345 APPENDIXES 1347 A. Impact to SNMP and other Protocols 1349 A.1. SNMPv3 1351 An issue remains whether a new message processing model MUST be 1352 specified as part of the SNMPv3 (or later) standard. Otherwise, it is 1353 not seen that these extensions pose any impact to other SNMPv3 1354 architectural components (i.e. USM, VACM) because the new protocol 1355 operations and their contents contain sufficient information (along 1356 with the information provided in whatever version-specific message 1357 wrapper they are contined within) to satisfy the abstract service 1358 interfaces for those components. 1360 However, these extensions may not be fully compatible with the SNMPv3 1361 proxy application (or any legacy SNMP application incorporating a 1362 message processing module that receives and processes or forwards 1363 SNMP messages). 1365 A.2. AgentX 1367 These extensions imply that AgentX will have to evolve in order to 1368 support the new protocol operations. For example, AgentX does not 1369 provide a delete PDU (to support DeleteRow), and neither does its 1370 TestSet PDU provide for a standard way to indicate whether the 1371 operation being performed maps to a CreateRow or EditRow request. 1372 Furthermore, master agents will need to know how to recognize and 1373 process the new protocol operations (i.e. distinguish RowIdentifiers 1374 from Operands, logically expand the targeted object OIDs and map them 1375 to subtree registrations). 1377 The feature to allow extended error codes to be returned in response 1378 PDUs may also require AgentX to provide a means to communicate such 1379 information from the subagent(s) to the master agent. 1381 B. Examples of Row Operations 1383 B.1. CreateRow 1385 Create two new rows in the snmpNotifyTable [RFC2573]. This table 1386 uses RowStatus, so we choose to explicitly set its value for each row 1387 (new impls may allow the request to omit a RowStatus varbind if its 1388 value is createAndGo). The response includes the values of the 1389 specified Operands after row creation. 1391 CreateRow 1392 ( 1393 request-id = 1 1394 non-repeaters = 0 -- 0 Singletons 1395 max-repetitions = 0 1397 -- RowOp 1 1399 -- RowIdentifier 1400 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1401 vb1.value = 1.0.114.111.119.49 -- "row1" 1403 vb2.name = 0.2 -- snmpNotifyTag 1404 vb2.value = "tag1" 1406 vb3.name = 0.3 -- snmpNotifyType 1407 vb3.value = 1 -- trap 1409 -- skip snmpNotifyStorageType. Use DEFVAL 1411 vb4.name = 0.5 -- snmpNotifyRowStatus 1412 vb4.value = createAndGo 1414 -- RowOp 2 1416 -- RowIdentifier 1417 vb5.name = 0.0 -- inherit snmpNotifyTable 1418 vb5.value = 1.0.114.111.119.50 -- "row2" 1420 vb6.name = 0.3 -- snmpNotifyType 1421 vb6.value = 1 -- trap 1423 vb7.name = 0.5 -- snmpNotifyRowStatus 1424 vb7.value = createAndWait 1425 ) 1427 ResponsePdu 1428 ( 1429 request-id = 1 1430 error-status = noError 1432 -- RowOp 1 1434 -- RowIdentifier 1435 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1436 vb1.value = 1.0.114.111.119.49 -- "row1" 1438 vb2.name = 0.2 -- snmpNotifyTag 1439 vb2.value = "tag1" 1441 vb3.name = 0.3 -- snmpNotifyType 1442 vb3.value = 1 -- trap 1444 vb4.name = 0.5 -- snmpNotifyRowStatus 1445 vb4.value = active 1447 -- RowOp 2 1449 -- RowIdentifier 1450 vb5.name = 0.0 -- inherit snmpNotifyTable 1451 vb5.value = 1.0.114.111.119.50 -- "row2" 1453 vb6.name = 0.3 -- snmpNotifyType 1454 vb6.value = 1 -- trap 1456 vb7.name = 0.5 -- snmpNotifyRowStatus 1457 vb7.value = notInService 1458 ) 1460 This protocol exchange illustrates the use of the CreateRow request 1461 to create two new rows in the snmpNotifyTable [RFC2573] except that 1462 we pretend here that RowState was used in the design of that table 1463 instead of RowStatus. 1465 CreateRow 1466 ( 1467 request-id = 2 1468 non-repeaters = 0 -- 0 Singletons 1469 max-repetitions = 0 1471 -- RowOp 1 1473 -- RowIdentifier 1474 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1475 vb1.value = 1.0.114.111.119.49 -- "row1" 1477 vb2.name = 0.2 -- snmpNotifyTag 1478 vb2.value = "tag1" 1480 vb3.name = 0.3 -- snmpNotifyType 1481 vb3.value = 1 -- trap 1483 -- skip snmpNotifyStorageType. Use DEFVAL 1484 -- By omitting a RowState varbind, it is the 1485 -- same as setting RowState=Active. 1487 -- RowOp 2 1489 -- RowIdentifier 1490 vb4.name = 0.0 -- inherit snmpNotifyTable 1491 vb4.value = 1.0.114.111.119.50 -- "row2" 1493 vb5.name = 0.3 -- snmpNotifyType 1494 vb5.value = 1 -- trap 1496 -- Explicitly set RowState to an initial 1497 -- value because we don't want to go 1498 -- active just yet. Even though we hint 1499 -- for an initial value of NotInService, 1500 -- it's possible that the result might 1501 -- show NotReady (if the row as defined 1502 -- by this RowOp were not ready to go Active). 1503 -- If a DEFVAL (NotInService) were provided 1504 -- in the MIB, this varbind could be omitted 1505 -- from this RowOp. 1506 vb6.name = 0.5 -- snmpNotifyRowState 1507 vb6.value = NotInService 1508 ) 1510 ResponsePdu 1511 ( 1512 request-id = 2 1513 error-status = noError 1515 -- RowOp 1 1517 -- RowIdentifier 1518 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1519 vb1.value = 1.0.114.111.119.49 -- "row1" 1521 vb2.name = 0.2 -- snmpNotifyTag 1522 vb2.value = "tag1" 1524 vb3.name = 0.3 -- snmpNotifyType 1525 vb3.value = 1 -- trap 1527 -- RowOp 2 1529 -- RowIdentifier 1530 vb4.name = 0.0 -- inherit snmpNotifyTable 1531 vb4.value = 1.0.114.111.119.50 -- "row2" 1532 vb5.name = 0.3 -- snmpNotifyType 1533 vb5.value = 1 -- trap 1535 vb6.name = 0.5 -- snmpNotifyRowState 1536 vb6.value = NotInService 1537 ) 1539 B.2. DeleteRow 1541 Delete the two rows created in either of the two previous examples. 1542 Note that the RowIdentifier in the second RowOp does not inherit the 1543 table OID from the first RowOp. Although this is legal, it also 1544 needlessly increases the request PDU size. Also note that the 1545 command responder instead chose to use name-level inheritance. 1547 DeleteRow 1548 ( 1549 request-id = 3 1550 non-repeaters = 0 -- 0 Singletons 1551 max-repetitions = 0 1553 -- RowOp 1 1555 -- RowIdentifier 1556 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1557 vb1.value = 1.0.114.111.119.49 -- "row1" 1559 -- RowOp 2 1561 -- RowIdentifier 1562 vb2.name = 1.3.6.1.6.3.13.1.1 -- snmpNotifyTable 1563 vb2.value = 1.0.114.111.119.50 -- "row2" 1564 ) 1566 ResponsePdu 1567 ( 1568 request-id = 3 1569 error-status = noError 1571 -- RowOp 1 1573 -- RowIdentifier 1574 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1575 vb1.value = 1.0.114.111.119.49 -- "row1" 1577 -- RowOp 2 1578 -- RowIdentifier 1579 vb2.name = 0.0 -- snmpNotifyTable 1580 vb2.value = 1.0.114.111.119.50 -- "row2" 1581 ) 1583 This DeleteRow example illustrates the use of Singletons. The 1584 Singletons allow a complete object instance to be provided (whereas 1585 the previous example contained no Operands and thus did not have 1586 access to the column descriptors, which are needed to form complete 1587 OIDs). If the user's VACM view only allowed him/her to delete certain 1588 rows in a table, the DeleteRow request would have to contain enough 1589 information to satisfy the isAccessAllowed service interface 1590 [RFC2573], and the above example does not. This can be accomplished 1591 by either providing an Operand within each RowOp or by instead using 1592 Singletons, which are more efficient than using RowOps in such cases. 1594 DeleteRow 1595 ( 1596 request-id = 4 1597 non-repeaters = 2 -- 2 Singletons 1598 max-repetitions = 0 1600 -- Singleton 1 1602 -- delete snmpNotifyTag in row1, which 1603 -- in this case also deletes all of row1 1604 vb1.name = 0.0.6.3.13.1.1.1.2.114.111.119.49 1605 vb1.value = NULL 1607 -- Singleton 2 1609 -- delete snmpNotifyTag in row2, which 1610 -- in this case also deletes all of row2 1611 vb1.name = 0.0.6.3.13.1.1.1.2.114.111.119.50 1612 vb1.value = NULL 1613 ) 1615 B.3. GetRow 1617 This is an example of a protocol exchange for a GetRow request and 1618 its response. 1620 GetRow 1621 ( 1622 request-id = 5 1623 non-repeaters = 0 -- 0 Singletons 1624 max-repetitions = 0 1626 -- RowOp 1 1628 -- RowIdentifier 1629 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1630 vb1.value = 1.0.114.111.119.49 -- "row1" 1632 vb2.name = 0.2 -- snmpNotifyTag 1633 vb2.value = NULL 1635 vb3.name = 0.3 -- snmpNotifyType 1636 vb3.value = NULL 1638 -- RowOp 2 1640 -- RowIdentifier 1641 vb4.name = 0.0 -- inherit snmpNotifyTable 1642 vb4.value = 1.0.114.111.119.50 -- "row2" 1644 vb5.name = 0.5 -- snmpNotifyRowStatus 1645 vb5.value = NULL 1647 -- must use the 0.1.X OID form because 999 > 39 1648 vb6.name = 0.1.999 -- Should result in NoSuchObject 1649 vb6.value = NULL 1650 ) 1652 ResponsePdu 1653 ( 1654 request-id = 5 1655 error-status = noError 1657 -- RowOp 1 1659 -- RowIdentifier 1660 vb1.name = 0.0.6.3.13.1.1.1 -- snmpNotifyTable 1661 vb1.value = 1.0.114.111.119.49 -- "row1" 1663 vb2.name = 0.2 -- snmpNotifyTag 1664 vb2.value = "tag1" 1666 vb3.name = 0.3 -- snmpNotifyType 1667 vb3.value = 1 -- trap 1669 -- RowOp 2 1671 -- RowIdentifier 1672 vb4.name = 0.0 -- inherit snmpNotifyTable 1673 vb4.value = 1.0.114.111.119.50 -- "row2" 1674 vb5.name = 0.5 -- snmpNotifyRowStatus 1675 vb5.value = NotInService 1677 vb6.name = 0.1.999 1678 vb6.value = NoSuchObject 1679 ) 1681 This GetRow request includes one Singleton using prefix-level 1682 inheritance to retrieve the sysUpTime value along with one RowOp. 1684 GetRow 1685 ( 1686 request-id = 6 1687 non-repeaters = 1 -- 1 Singleton 1688 max-repetitions = 0 1690 -- Singletons 1692 vb1.name = 0.0.2.1.1.3.0 -- get(sysUpTime.0) 1693 vb1.value = NULL 1695 -- RowOp 1 1697 -- RowIdentifier 1698 vb2.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1699 vb2.value = 1.0.114.111.119.49 -- "row1" 1701 vb3.name = 0.2 -- snmpNotifyTag 1702 vb3.value = NULL 1704 vb4.name = 0.3 -- snmpNotifyType 1705 vb4.value = NULL 1706 } 1708 ResponsePdu 1709 ( 1710 request-id = 6 1711 error-status = noError 1713 -- Singletons 1715 -- Singleton 1. The original request 1716 -- contained non-repeaters = 1. This 1717 -- count is not transmitted back in the 1718 -- response, so the originating command generator 1719 -- must maintain this count and associate it 1720 -- to the returned request-id. 1721 vb1.name = 0.0.2.1.1.3.0 -- sysUpTime.0 1722 vb1.value = 123456 1724 -- RowOp 1 1726 -- RowIdentifier 1727 vb2.name = 0.0.6.3.13.1.1.1 -- snmpNotifyTable 1728 vb2.value = 1.0.114.111.119.49 -- "row1" 1730 vb3.name = 0.2 -- snmpNotifyTag 1731 vb3.value = "tag1" 1733 vb4.name = 0.3 -- snmpNotifyType 1734 vb4.value = 1 -- trap 1735 ) 1737 B.4. GetNextRow 1739 This is an example of a protocol exchange for a GetNextRow request 1740 and its response. 1742 GetNextRow 1743 ( 1744 request-id = 7 1745 non-repeaters = 1 -- 1 Singleton 1746 max-repetitions = 0 1748 -- Singletons 1750 vb1.name = 0.0.2.1.1.3 -- getNext(sysUpTime) 1751 vb1.value = NULL 1753 -- RowOp 1 1755 -- RowIdentifier 1756 vb2.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1757 vb2.value = 1.0.114.111.119 -- "row" (partial instance) 1759 vb3.name = 0.2 -- snmpNotifyTag 1760 vb3.value = NULL 1762 vb4.name = 0.3 -- snmpNotifyType 1763 vb4.value = NULL 1765 -- RowOp 2 1767 -- RowIdentifier 1768 vb5.name = 0.0 -- inherit snmpNotifyTable 1769 vb5.value = 1.0 1771 -- No Operands, this RowOp is logically identical 1772 -- to GetNext(snmpNotifyEntry). A bit inefficient 1773 -- since it produces a response RowOp containing 1774 -- only one Operand (would be better as a Singleton).. 1775 ) 1777 ResponsePdu 1778 ( 1779 request-id = 7 1780 error-status = noError 1782 -- Singletons 1784 vb1.name = 0.0.2.1.1.3.0 -- sysUpTime.0 1785 vb1.value = 123457 1787 -- RowOp 1 1789 -- RowIdentifier 1790 vb2.name = 0.0.6.3.13.1.1.1 -- snmpNotifyTable 1791 vb2.value = 1.0.114.111.119.49 -- "row1" 1793 vb3.name = 0.2 -- snmpNotifyTag 1794 vb3.value = "tag1" 1796 vb4.name = 0.3 -- snmpNotifyType 1797 vb4.value = 1 -- trap 1799 -- RowOp 2 1801 -- RowIdentifier 1802 vb5.name = 0.0 -- inherit snmpNotifyTable 1803 vb5.value = 1.0.114.111.119.49 -- "row1" 1805 vb6.name = 0.2 -- snmpNotifyTag 1806 vb6.value = "tag1" 1807 ) 1809 The RowOps in this GetNextRow request are logically the same as a 1810 getNext(snmpNotifyEntry), getNext(snmpNotifyTag) and getNext(system). 1811 The fourth RowOp is illegally constructed and would return a genErr 1812 error, because although the RowIdentifier is correctly formed, in 1813 this case it contains an Instance without at least one Operand, and 1814 without an Operand it is impossible to decide which table object the 1815 getNext should be performed on. Note that it would be more efficient 1816 to instead provide these types of RowOps as individual Singletons. 1818 GetNextRow 1819 ( 1820 request-id = 8 1821 non-repeaters = 0 -- 0 Singletons 1822 max-repetitions = 0 1824 -- RowOp 1, same as getNext(snmpNotifyEntry) 1826 -- RowIdentifier 1827 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1828 vb1.value = 1.0 1830 -- RowOp 2, same as getNext(snmpNotifyTag) 1832 -- RowIdentifier 1833 vb2.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1834 vb2.value = 1.0 1836 vb3.name = 0.2 -- snmpNotifyTag 1837 vb3.value = NULL 1839 -- RowOp 3, same as getNext(system) 1841 -- RowIdentifier 1842 vb4.name = 0.0.2.1.1 -- system 1843 vb4.value = 0.0 -- not a table 1845 -- RowOp 4, same as getNext(snmpNotifyEntry) 1847 -- RowIdentifier (missing Operand produces genErr) 1848 vb5.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1849 vb5.value = 1.0.114.111.119.49 -- "row1" 1850 } 1852 B.5. GetBulkRow 1854 This GetBulkRow request includes one Singleton using prefix-level 1855 inheritance to retrieve the sysUpTime value along with two RowOps. 1856 Though both of the RowOps in this request are legal, note that RowOp2 1857 returns a subset of RowOp1's desired values. Therefore, RowOp2 could 1858 be omitted without affecting the response. 1860 GetBulkRow 1861 ( 1862 request-id = 9 1863 non-repeaters = 1 -- 1 Singleton 1864 max-repetitions = 0 -- head/tail disabled 1866 -- Singletons 1868 vb1.name = 0.0.2.1.1.3 -- getNext(sysUpTime) 1869 vb1.value = NULL 1871 -- RowOp 1 1873 -- RowIdentifier 1874 -- Retreive all snmpNotifyTags and 1875 -- RowStatus objects from 1876 -- row1 to end of table (Instance2 not provided). 1877 vb2.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1878 vb2.value = 1.0.4.114.111.119.49 -- "row1" 1880 vb3.name = 0.2 -- snmpNotifyTag 1881 vb3.value = NULL 1883 vb4.name = 0.5 -- snmpNotifyRowStatus 1884 vb4.value = NULL 1886 -- RowOp 2 1888 -- RowIdentifier 1889 -- Retreive all snmpNotifyTags and 1890 -- RowStatus objects from 1891 -- row1 to row3 (inclusive) 1892 vb5.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1893 vb5.value = 1.0.4.114.111.119.49.114.111.119.51 1895 vb6.name = 0.2 -- snmpNotifyTag 1896 vb6.value = NULL 1898 vb7.name = 0.5 -- snmpNotifyRowStatus 1899 vb7.value = NULL 1900 } 1902 ResponsePdu 1903 ( 1904 request-id = 9 1905 error-status = noError 1907 -- Singletons 1909 vb1.name = 0.0.2.1.1.3.0 -- sysUpTime.0 1910 vb1.value = 123458 1912 -- RowOp 1 1913 -- RowIdentifier 1914 vb2.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1915 vb2.value = 1.0.4.114.111.119.49 -- "row1" 1917 vb3.name = 0.2 -- snmpNotifyTag 1918 vb3.value = "tag1" 1920 vb4.name = 0.5 -- snmpNotifyRowStatus 1921 vb4.value = Active 1923 -- RowOp 2 1925 -- RowIdentifier 1926 vb5.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1927 vb5.value = 1.0.4.114.111.119.50 -- "row2" 1929 vb6.name = 0.2 -- snmpNotifyTag 1930 vb6.value = "tag2" 1932 vb7.name = 0.5 -- snmpNotifyRowStatus 1933 vb7.value = Active 1935 -- RowOp 3 1937 -- RowIdentifier 1938 vb8.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1939 vb8.value = 1.0.4.114.111.119.51 -- "row3" 1941 vb9.name = 0.2 -- snmpNotifyTag 1942 vb9.value = "tag3" 1944 vb10.name = 0.5 -- snmpNotifyRowStatus 1945 vb10.value = Active 1947 -- RowOp 4 1949 -- RowIdentifier 1950 vb11.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1951 vb11.value = 1.0.4.114.111.119.52 -- "row4" 1953 vb12.name = 0.2 -- snmpNotifyTag 1954 vb12.value = "tag4" 1956 vb13.name = 0.5 -- snmpNotifyRowStatus 1957 vb13.value = Active 1959 -- RowOp 5 1960 -- RowIdentifier 1961 vb14.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1962 vb14.value = 1.0.4.114.111.119.53 -- "row5" 1964 vb15.name = 0.2 -- snmpNotifyTag 1965 vb15.value = "tag5" 1967 vb16.name = 0.5 -- snmpNotifyRowStatus 1968 vb16.value = Active 1969 } 1971 This GetBulkRow request is the same as the previous example except 1972 that RowOp2 specifies a column not included in RowOp1. The response 1973 would be identical to the above response except that RowOps1-3 (row 1974 1-3) would include a Operand/value for snmpNotifyType. 1976 GetBulkRow 1977 ( 1978 request-id = 10 1979 non-repeaters = 1 -- 1 Singleton 1980 max-repetitions = 0 -- head/tail disabled 1982 -- Singletons 1984 vb1.name = 0.0.2.1.1.3 -- getNext(sysUpTime) 1985 vb1.value = NULL 1987 -- RowOp 1 1989 -- RowIdentifier 1990 -- Retreive all snmpNotifyTags and 1991 -- RowStatus objects from 1992 -- row1 to end of table (Instance2 not provided). 1993 vb2.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 1994 vb2.value = 1.0.4.114.111.119.49 -- "row1" 1996 vb3.name = 0.2 -- snmpNotifyTag 1997 vb3.value = NULL 1999 vb4.name = 0.5 -- snmpNotifyRowStatus 2000 vb4.value = NULL 2002 -- RowOp 2 2004 -- RowIdentifier 2005 -- Retreive all snmpNotifyTypes and 2006 -- RowStatus objects from 2007 -- row1 to row3 (inclusive) 2008 vb5.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 2009 vb5.value = 1.0.4.114.111.119.49.114.111.119.51 2011 vb6.name = 0.3 -- snmpNotifyType 2012 vb6.value = NULL 2014 vb7.name = 0.5 -- snmpNotifyRowStatus 2015 vb7.value = NULL 2016 } 2018 This GetBulkRow request includes two RowOps to show how to perform a 2019 head and tail function, respectively. 2021 In RowOp1 (head function), the search range is indicated by the OID 2022 1.0.0 (no Instance or Instance2 values provided). That value along 2023 with a non-zero max-reps value indicates a head function with a 2024 possible search range of the entire table. 2026 In RowOp2 (tail function), the search range is indicated by the the 2027 OID 1.0 (no InstanceLen, Instance or Instance2 values provided). That 2028 value along with a non-zero max-reps value indicates a tail function 2029 with a possible search range of the entire table. 2031 The Response indicates the desired objects in the first and last two 2032 rows of the table are returned (five rows in table, so row3 is not 2033 returned). 2035 Note that if max-reps were instead 0, the two RowOps would be 2036 logically identical. 2038 GetBulkRow 2039 ( 2040 request-id = 11 2041 non-repeaters = 0 -- 0 Singletons 2042 max-repetitions = 2 -- head/tail enabled 2044 -- RowOp 1 2046 -- RowIdentifier 2047 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 2048 vb1.value = 1.0.0 -- head search entire table 2050 vb2.name = 0.2 -- snmpNotifyTag 2051 vb2.value = NULL 2053 vb3.name = 0.5 -- snmpNotifyRowStatus 2054 vb3.value = NULL 2056 -- RowOp 2 2058 -- RowIdentifier 2059 vb4.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 2060 vb4.value = 1.0 -- tail search entire table 2062 vb5.name = 0.2 -- snmpNotifyTag 2063 vb5.value = NULL 2065 vb6.name = 0.5 -- snmpNotifyRowStatus 2066 vb6.value = NULL 2067 } 2069 ResponsePdu 2070 ( 2071 request-id = 11 2072 error-status = noError 2074 -- RowOp 1 2076 -- RowIdentifier 2077 vb1.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 2078 vb1.value = 1.0.4.114.111.119.49 -- "row1" 2080 vb2.name = 0.2 -- snmpNotifyTag 2081 vb2.value = "tag1" 2083 vb3.name = 0.5 -- snmpNotifyRowStatus 2084 vb3.value = Active 2086 -- RowOp 2 2088 -- RowIdentifier 2089 vb4.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 2090 vb4.value = 1.0.4.114.111.119.50 -- "row2" 2092 vb5.name = 0.2 -- snmpNotifyTag 2093 vb5.value = "tag2" 2095 vb6.name = 0.5 -- snmpNotifyRowStatus 2096 vb6.value = Active 2098 -- RowOp 3 2100 -- RowIdentifier 2101 vb7.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 2102 vb7.value = 1.0.4.114.111.119.52 -- "row4" 2103 vb8.name = 0.2 -- snmpNotifyTag 2104 vb8.value = "tag4" 2106 vb9.name = 0.5 -- snmpNotifyRowStatus 2107 vb9.value = Active 2109 -- RowOp 4 2111 -- RowIdentifier 2112 vb10.name = 0.0.6.3.13.1.1 -- snmpNotifyTable 2113 vb10.value = 1.0.4.114.111.119.53 -- "row5" 2115 vb11.name = 0.2 -- snmpNotifyTag 2116 vb11.value = "tag5" 2118 vb12.name = 0.5 -- snmpNotifyRowStatus 2119 vb12.value = Active 2120 } 2122 This GetBulkRow requests data from two columns of the same table. The 2123 response shows RowOps and Singletons interspersed with one another 2124 (i.e. rows with only one object to return cause Singletons to be 2125 returned instead of RowOps, which be definitions MUST have two or 2126 more Operands in GetBulkRow responses). Although this example uses a 2127 shorthand notation (i.e. fooTable), the actual OIDs would utilize OID 2128 inheritance wherever possible. Also note that row3 did not produce a 2129 result. 2131 GetBulkRow 2132 ( 2133 request-id = 12 2134 non-repeaters = 0 -- 0 Singletons 2135 max-repetitions = 0 -- head/tail disabled 2137 -- RowOp 1 2139 -- RowIdentifier 2140 vb1.name = fooTable 2141 vb1.value = 1.0 -- search entire table 2143 vb2.name = 0.2 -- fooColumnA 2144 vb2.value = NULL 2146 vb3.name = 0.3 -- fooColumnB 2147 vb3.value = NULL 2148 } 2150 ResponsePdu 2151 ( 2152 request-id = 12 2153 error-status = noError 2155 -- RowOp 1 2157 -- RowIdentifier 2158 vb1.name = fooTable 2159 vb1.value = 1.0.1 -- row 1 2161 vb2.name = 0.2 -- fooColumnA 2162 vb2.value = 1 2164 vb3.name = 0.3 -- fooColumnB 2165 vb3.value = 1 2167 -- Singleton 1 2169 vb4.name = fooColumnA.2 -- row 2 2170 vb4.value = 2 2172 -- Singleton 2 2174 vb5.name = fooColumnB.3 -- row 4 2175 vb5.value = 4 2177 -- RowOp 2 2179 -- RowIdentifier 2180 vb6.name = fooTable 2181 vb6.value = 1.0.5 -- row 5 2183 vb7.name = 0.2 -- fooColumnA 2184 vb7.value = 5 2186 vb8.name = 0.3 -- fooColumnB 2187 vb8.value = 5 2189 -- Singleton 3 2191 vb9.name = fooColumnA.6 -- row 6 2192 vb9.value = 6 2193 } 2195 B.6. EditRow 2197 This EditRow hypothetically produces the shown response which 2198 indicates several errors: first, varbind 2 caused a wrongValue error, 2199 secondly, varbind 2 also caused an application specific error 11 2200 (perhaps tooManySlicesInserted), and finally, varbinds 3 and 6 both 2201 caused yet another application specific error 14 (perhaps 2202 tempTooHigh). Additionally, the returned Operand values are set to 2203 NULL to indicate the third-phase (get) was not executed (due to 2204 test-phase failure). 2206 EditRow 2207 ( 2208 request-id = 13 2209 non-repeaters = 0 -- no Singletons 2210 max-repetitions = 0 2212 -- RowOp 1 2214 -- RowIdentifier 2215 vb1.name = toasterTable 2216 vb1.value = 1.0.1 -- toaster/row "1" 2218 vb2.name = 0.2 -- toasterSlicesInserted 2219 vb2.value = 100 2221 vb3.name = 0.3 -- toasterTemp 2222 vb3.value = 1000 2224 -- RowOp 2 2226 -- RowIdentifier 2227 vb4.name = toasterTable 2228 vb4.value = 1.0.2 -- toaster/row "2" 2230 vb5.name = 0.2 -- toasterSlicesInserted 2231 vb5.value = 2 2233 vb6.name = 0.3 -- toasterTemp 2234 vb6.value = 1000 2235 } 2237 ResponsePdu 2238 ( 2239 request-id = 13 2240 error-status = 10 (wrongValue) 2241 error-index = 2 2243 -- RowOp 1 2245 -- RowIdentifier 2246 vb1.name = toasterTable 2247 vb1.value = 1.0.1 -- toaster/row "1" 2249 vb2.name = 0.2 -- toasterSlicesInserted 2250 vb2.value = NULL 2252 vb3.name = 0.3 -- toasterTemp 2253 vb3.value = NULL 2255 -- RowOp 2 2257 -- RowIdentifier 2258 vb4.name = toasterTable 2259 vb4.value = 1.0.2 -- toaster/row "2" 2261 vb5.name = 0.2 -- toasterSlicesInserted 2262 vb5.value = NULL 2264 vb6.name = 0.3 -- toasterTemp 2265 vb6.value = NULL 2267 -- Extended errors: 2269 vb7.name = 0.0.0.11.2.0.14.3.6 2270 vb7.value = NULL 2271 } 2273 C. Known issues 2275 This section will be deleted before becoming an RFC. 2277 These are known issues that need to be resolved before going 2278 standards track: 2280 - Should the coexistence and transition section be moved to a 2281 different document? 2283 - Need to specify a way for extended error codes to be mapped to 2284 meaningful error messages. Perhaps IANA would maintain an 2285 IANAExtendedErrorCodes textual-convention (along the lines of 2286 IANAIfType) and all extended error codes would thus be 2287 controlled via IANA. Also, a small range of the codes may need 2288 to be reserved up-front for use by the IETF so that the 2289 standard SNMP error-status codes and varbind-level exceptions 2290 can also be mapped to extended code values. For example, we 2291 may want to return "tooBig" in the case where a successful 2292 GetBulkRow response is returned with only a portion of the 2293 requested data. The tooBig extended error is a "more" signal 2294 to perform at least one more GetBulkRow (using the Instance in 2295 the last RowOp as a beginnning search range). 2297 - What other extended error codes should be reserved and defined 2298 up front? For example, perhaps an "unsupportedOperation" needs 2299 to be defined so that the EOS requests could return that error 2300 on a RowOp by RowOp basis (where a given subagent is non-EOS 2301 capable and others are). In such cases, incrementing the 2302 droppedPdu counter may not be possible. 2304 - How can SetRequests and/or EditRows be used to safely create 2305 rows in tables using RowState in multi-mgr environments? It 2306 would be ideal to have such a mechanism (without re-creating 2307 RowStatus all over again) in order to ease the transition to 2308 EOS-capable networks. 2310 - Should this document contain procedures to translate EOS 2311 operations to/from conventional operations? 2313 - Should the MIB defs in this document (and all other EOS 2314 documents) instead be located in one EOS document? This could 2315 reduce the number of modules needed to be IMPORTED in future 2316 MIBs/appls. 2318 D. Full Copyright Statement 2320 Copyright (C) The Internet Society (2001). All Rights Reserved. 2322 This document and translations of it may be copied and furnished to 2323 others, and derivative works that comment on or otherwise explain it 2324 or assist in its implementation may be prepared, copied, published 2325 and distributed, in whole or in part, without restriction of any 2326 kind, provided that the above copyright notice and this paragraph are 2327 included on all such copies and derivative works. However, this 2328 document itself may not be modified in any way, such as by removing 2329 the copyright notice or references to the Internet Society or other 2330 Internet organizations, except as needed for the purpose of 2331 developing Internet standards in which case the procedures for 2332 copyrights defined in the Internet Standards process must be 2333 followed, or as required to translate it into languages other than 2334 English. 2336 The limited permissions granted above are perpetual and will not be 2337 revoked by the Internet Society or its successors or assigns. 2339 This document and the information contained herein is provided on an 2340 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 2341 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 2342 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 2343 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 2344 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2346 Acknowledgement 2348 Funding for the RFC Editor function is currently provided by the 2349 Internet Society.