idnits 2.17.1 draft-ietf-eos-oops-00.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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** 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 a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 115: '...d Responder. It MUST, however, return...' RFC 2119 keyword, line 267: '...he protocol, but MUST expect the possi...' RFC 2119 keyword, line 601: '...nterprise errors MUST be treatable as ...' RFC 2119 keyword, line 898: '...owledgment-PDUs) MUST set this field t...' RFC 2119 keyword, line 910: '... request MUST immediately retu...' (74 more instances...) 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 (February 2003) is 7740 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) -- Looks like a reference, but probably isn't: 'APPLICATION 0' on line 355 -- Looks like a reference, but probably isn't: 'APPLICATION 1' on line 358 -- Looks like a reference, but probably isn't: 'APPLICATION 2' on line 361 -- Looks like a reference, but probably isn't: 'APPLICATION 3' on line 366 -- Looks like a reference, but probably isn't: 'APPLICATION 4' on line 369 -- Looks like a reference, but probably isn't: 'APPLICATION 6' on line 374 -- Looks like a reference, but probably isn't: 'APPLICATION 8' on line 379 -- Looks like a reference, but probably isn't: 'APPLICATION 9' on line 386 -- Looks like a reference, but probably isn't: 'APPLICATION 10' on line 390 -- Looks like a reference, but probably isn't: 'APPLICATION 11' on line 394 -- Looks like a reference, but probably isn't: 'XXX' on line 867 == Missing Reference: '0' is mentioned on line 730, but not defined == Unused Reference: '7' is defined on line 2062, but no explicit reference was found in the text == Outdated reference: A later version (-02) exists of draft-iab-nm-workshop-00 -- Obsolete informational reference (is this intentional?): RFC 2028 (ref. '7') (Obsoleted by RFC 9281) Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 14 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 EOS Working Group W. Hardaker 3 INTERNET-DRAFT Network Associates Laboratories 4 draft-ietf-eos-oops-00.txt February 2003 6 Object Oriented Protocol Operations for 7 the Simple Network Management Protocol 8 draft-ietf-eos-oops-00.txt 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 (2003). All Rights Reserved. 33 Abstract 35 This document defines new Protocol Data Units (PDUs) for use within 36 the Simple Network Management Protocol (SNMP). The goals of the new 37 PDUs are to reduce packet sizes and to reduce processing overhead 38 required at the Command Responder side of the protocol. 40 Table of Contents 42 1. Introduction ............................................... 2 43 1.1. Background and Motivations ............................... 3 44 1.1.1. GET-NEXT complexity .................................... 3 45 1.1.2. OID compression ........................................ 3 46 1.1.3. Row operations ......................................... 4 47 1.1.4. Complex object relationships ........................... 4 48 1.1.5. Retrieval of more data than is desired ................. 4 49 1.1.6. Row hole traversal and object grouping ................. 4 50 1.1.7. Index parsing and OID length restrictions .............. 5 51 1.1.8. Transactions ........................................... 5 52 1.1.9. Easy conversion to and from popular data formats ....... 5 53 1.1.10. Better error condition handling ....................... 6 54 1.2. Related work within the SMIng working group .............. 6 55 1.3. Terminology .............................................. 6 56 2. Transport Protocol Considerations .......................... 7 57 3. PDU definitions ............................................ 7 58 3.1. ASN.1 definitions for the PDUs ........................... 7 59 3.2. New PDU component definitions ............................ 19 60 3.2.1. Common PDU elements of the OOPS PDUs ................... 19 61 3.2.2. Get-Object-PDU specific PDU elements ................... 23 62 3.2.3. Write-Object-PDU specific PDU elements ................. 27 63 3.2.4. Get-Configuration-Object-PDU specific PDU elements ..... 29 64 3.2.5. Notification-Object-PDU specific elements .............. 30 65 4. PDU processing ............................................. 30 66 4.1. Processing a Get-Object-PDU .............................. 30 67 4.2. Processing a Write-Object-PDU. ........................... 33 68 4.3. Processing a Get-Configuration-Object-PDU request ........ 34 69 4.4. Generating a Notification-Object-PDU ..................... 35 70 5. Examples ................................................... 36 71 5.1. Retrieve a specific row from the ifTable ................. 36 72 5.2. A multiple-packet example with a double filter ........... 37 73 5.3. A Write-Object-PDU example ............................... 40 74 5.4. A Get-Configuration-Object-PDU example ................... 42 75 5.5. A Notification-Object-PDU example: IF-MIB::linkUp ........ 43 76 6. References ................................................. 44 77 6.1. Normative References ..................................... 44 78 6.2. Informative References ................................... 45 79 7. Intellectual Property ...................................... 45 80 8. Security Considerations .................................... 45 81 9. IANA Considerations ........................................ 46 82 10. Acknowledgements .......................................... 46 83 11. Editor's Addresses ........................................ 46 84 12. Full Copyright Statement .................................. 47 86 1. Introduction 88 This document specifies some new PDU types to optimize specific 89 operations in SNMP. This draft is still work in progress, though 90 the technical concepts are perceived by the author to be stable and 91 mostly implementable at this point. More feedback from implementors 92 sought at this point in time. Comments and discussion on this 93 document are encouraged and should take place on the EOS working 94 group mailing list (eos@ops.ietf.org). 96 1.1. Background and Motivations 98 Many recognized problems [5, 6] exist within the current PDUs 99 defined for use by the SNMP protocol [1]. Many of these known 100 problems are addressed by the new protocol operations defined within 101 this draft. The general problems solved by this draft are described 102 briefly in this section. 104 1.1.1. GET-NEXT complexity 106 Many problems result from a device's inability to access its data in 107 a way that can be efficiently traversed when searching for the next 108 object in a series of GET-NEXT or GET-BULK SNMP requests. 109 Internally, many implementations differ in how data is stored in a 110 device and thus it would be impossible to define a MIB which would 111 be efficient when implemented on every architecture. 113 The operations defined in this document do not suffer from these 114 problems, as the data can be returned in any order selected by the 115 Command Responder. It MUST, however, return data in a consistent 116 manner such that if the same data is requested twice at any point in 117 time, the Command Responder will return the data in the same order. 118 It is the exact order in which objects are returned is 119 implementation specific. 121 It is likely that every Command Responder will benefit from this 122 design decision and that either most Command Generators don't care 123 about ordering in the first place or have the resources to perform 124 ordering themselves via utilization of database technologies that 125 are not realistically available on many Command Responder platforms. 126 Command Generator's that do need sorted data may even need the data 127 sorted in a different manner than the MIBs specify, in which case 128 the sorting burden placed on the Command Responder is wasted. 130 1.1.2. OID compression 132 SNMPv2 PDUs are constructed using a sequence of varbinds. In many 133 cases, when multiple objects are requested from the Command 134 Responder, the OIDs contained within have common prefixes. It is 135 widely recognized as a waste of bandwidth to duplicate this prefix 136 repeatedly. 138 The PDUs defined in this document only rely on a base OID (e.g., an 139 object identifier pointing to the root of a SNMP Object or Table), 140 and the sub-objects (e.g., a row in a SNMP Table) underneath it are 141 defined as references from the base OID. This allows large groups 142 of data to be transmitted while only requiring a single OID to 143 identify the top most grouping object (e.g., a table). 145 1.1.3. Row operations 147 The ability to manipulate an entire row within a SNMP Table at once 148 has long been a frustration of programmers using the SET operations 149 contained the SNMPv2 PDUs. 151 The PDUs defined in this document allow explicit data dependencies 152 to be marked within the write operations. This allows Command 153 Generators to create more powerful requests, while at the same 154 easing implementation burden within the Command Responder. 156 1.1.4. Complex object relationships 158 Many people do not properly understand the interrelationships 159 between SNMP Tables and have desired the ability to express their 160 data in a more hierarchal fashion, such that SNMP tables can contain 161 other SNMP tables. Although it is not possible to enable nested 162 datatypes within SMIv2 today, the SMIng working group is trying to 163 solve these problems and create the ability to define more complex 164 relationships in SMIv3. 166 The PDUs defined in this document allow hierarchal object data to be 167 transmitted efficiently and as a single group, thus allowing the 168 complex structures defined within SMIv3 to be efficiently 169 transmitted. 171 1.1.5. Retrieval of more data than is desired 173 Extracting only the data needed from an SNMP Table using the GETNEXT 174 or GETBULK operations available in SNMP PDUs today is difficult at 175 best. The request PDUs defined in this document allow more precise 176 selection data and allow simple search criteria to be submitted to 177 the remote Command Responders to help reduce the amount of data 178 returned to the Command Generator. A delicate balance is required 179 to ensure that the devices being polled for data are not taxed with 180 expensive search requests, so the criteria imposed within these 181 documents is restricted to a limited set of operators that may or 182 may not be supported by the command responder implementation. The 183 intention is not to shift all the complex decision processing burden 184 from the Command Generator station to the command responder, but to 185 increase efficiency on the wire where possible. 187 1.1.6. Row hole traversal and object grouping 189 When requests to GET, GET-NEXT, and GET-BULK data come back in a 190 SNMP RESPONSE PDU, the data can be hard to organize back into a 191 logical structure again. Additionally, GET-BULK responses 192 interleave its data with END-OF-MIB exceptions which adds further 193 complexity to the data processing. 195 Since the PDUs defined in this document deal directly with MIB 196 objects as a group, the data relationships within objects are 197 preserved. This makes transferring large amounts of data efficient 198 on both the sending and receiving side. The data groupings are now 199 appropriately marked within the packet itself. 201 1.1.7. Index parsing and OID length restrictions 203 Although the encoding and decoding of Table indexes into and out of 204 OIDs is algorithmic, many SNMP software packages and toolkits make 205 mistakes in implementing the algorithm. Additionally, since the 206 maximum length of an OID is limited to 128 sub-identifiers, it 207 limits the size of the index data that can be utilized within an 208 SNMP table. This limitation results in MIBs which are poorly 209 designed and/or broken and MIBs with less-than-ideal table indexes. 210 Finally, it is impossible to decode the indexes from an OID without 211 knowledge of the MIB module definition. 213 The indexes within the PDUs defined in this document are encoded 214 directly into the packet as opposed to being encoded into the OID. 215 This simplifies both Command Generator and Command Responder code 216 and reduces the chances of one side incorrectly encoding or decoding 217 the indexes. Additionally, because encoding of indexes is done 218 directly within the protocol no MIB module definition is needed to 219 extract them from the protocol operation. Finally, it provides the 220 ability to use a set of indexes which is larger than the OID-encoded 221 imposed length of 128 sub-identifies. 223 1.1.8. Transactions 225 The limited set of SNMP write operation transactions have been 226 difficult to cope with when large sets of data must be pushed 227 around, since all the objects within a SNMP SET PDU must be set as 228 if simultaneously. In actuality, configuration data often contains 229 independent sets of data. 231 The Write-Object-PDU operation defined in this document defines a 232 less restrictive and more flexible transaction model that lets large 233 quantities of data be pushed more efficiently through a network. 235 1.1.9. Easy conversion to and from popular data formats 237 A desire has been shown by network operators for SNMP objects to be 238 easily accessible and convertible to and from more human friendly 239 expression languages and storage systems, like XML or SQL Databases. 240 The objects within the PDUs contained in this document are designed 241 for such a purpose. It should be, for example, trivial to convert 242 them to and from a hierarchical XML schema set describing the 243 objects in question. For the example, the BER hierarchal packet 244 format can be quickly converted to XML by replacing the sequence 245 tags with XML ASCII delimiter tags. 247 1.1.10. Better error condition handling 249 Integer error codes are extremely useful for machine parsibility and 250 interoperability, but it's frequently nice to have an extra error 251 string that may be passed to an operator to assist in extra 252 debugging of problems. The response PDUs defined in this document 253 contain an "error string" for exactly this purpose. 255 Additionally, multiple errors can be returned at once allowing more 256 comprehensive error reporting. In older PDUs only the first error 257 encountered in processing a request could be returned in the 258 response PDU. 260 1.2. Related work within the SMIng working group 262 The PDUs in this document are designed for use with the first three 263 versions of the SMI language. There are specific portions of the 264 protocol operations that are not needed for SMIv1 or SMIv2 265 documents. Command Responders and Command Generators which do not 266 make use of any documents written in the SMIv3 format may not need 267 the SMIv3 portions of the protocol, but MUST expect the possibility 268 that these PDUs may arrive with these extensions requested. 270 1.3. Terminology 272 The SMIv1, SMIv2, and SMIv3 documents are not entirely consistent in 273 their terminology. In this document, we will use the following 274 terminology throughout this document. Most of the terminology is 275 equivalent to what is expected to be in the SMIv3 documents. 277 Note: this section is not entirely finished yet, as we're awaiting 278 the latest SMIng draft to match our terminology to theirs. 280 Aggregate 281 An aggregate is a collection of information. In SMIv2 terms, 282 this is roughly equivalent to a table. In SMIv3 this is an 283 array or other structure with multiple objects contained 284 within it. 286 Object 287 An object is a particular instance of "something". In SMIv2 288 terms, this would be a row. In SMIv3 this would be an 289 instantiated scalar or a particular row within an array. 291 Element 292 An element is one particular part of a an object. In SMIv2 293 terms, this would be a column. In SMIv3 this would be a XXX, 294 which may be defined as another object in itself. 296 Command 297 This document sticks with the SNMPv3 application documentation 298 [4] terminology for describing the different application types 299 that request and receive the PDUs defined in this document. 301 2. Transport Protocol Considerations 303 The PDUs defined in this document allow the transmission of large 304 data sets in a more compact format than previous SNMP PDUs allowed. 305 However, it is still recommended that large requests and responses 306 be transmitted over a SNMP transmission domain which provides for 307 guaranteed network packet delivery (e.g., TCP). Large responses, 308 containing many objects, carried over transmission domains which can 309 not guarantee delivery (e.g., UDP) are still likely to be 310 problematic. It is well beyond the scope of this document to 311 redesign a reliable transmission mechanism. 313 3. PDU definitions 315 This section defines the new PDUs in ASN.1 format. Supporting 316 textual descriptions of PDU components are given in later sections. 318 3.1. ASN.1 definitions for the PDUs 320 SNMP-OOPS DEFINITIONS ::= BEGIN 322 -- 323 -- Notes: ignore the OptionField for now. They'll be fixed later. 324 -- (for instance, they should all be unique definitions) 325 -- 327 -- 328 -- DataTypes 329 -- 331 ElementSyntax ::= CHOICE { 332 simple SimpleSyntax, 333 application-wide ApplicationSyntax 334 } 335 SimpleSyntax ::= CHOICE { 336 integer-value INTEGER (-2147483648..2147483647), 337 string-value OCTET STRING (SIZE (0..65535)), 338 objectID-value OBJECT IDENTIFIER 339 } 341 ApplicationSyntax ::= CHOICE { 342 ipAddress-value IpAddress, 343 counter-value Counter32, 344 timeticks-value TimeTicks, 345 arbitrary-value Opaque, 346 big-counter-value Counter64, 347 unsigned-integer-value Unsigned32, 348 integer64-value Integer64, 349 unsigned64-value Unsigned64, 350 float32-value Float32, 351 float64-value Float64, 352 float128-value Float128 353 } 355 IpAddress ::= [APPLICATION 0] 356 IMPLICIT OCTET STRING (SIZE (4)) 358 Counter32 ::= [APPLICATION 1] 359 IMPLICIT INTEGER (0..4294967295) 361 Unsigned32 ::= [APPLICATION 2] 362 IMPLICIT INTEGER (0..4294967295) 364 Gauge32 ::= Unsigned32 366 TimeTicks ::= [APPLICATION 3] 367 IMPLICIT INTEGER (0..4294967295) 369 Opaque ::= [APPLICATION 4] 370 IMPLICIT OCTET STRING 372 -- APPLICATION 5 was used in 1442 374 Counter64 ::= [APPLICATION 6] 375 IMPLICIT INTEGER (0..18446744073709551615) 377 -- APPLICATION 7 was used in 1442 379 Integer64 ::= [APPLICATION 8] 380 IMPLICIT INTEGER (-9223372036854775808..9223372036854775807) 382 Unsigned64 ::= [APPLICATION 9] 383 IMPLICIT INTEGER (0..18446744073709551615) 385 Float32 ::= 386 [APPLICATION 9] 387 IMPLICIT OCTET STRING(SIZE(4)) -- IEEE format 389 Float64 ::= 390 [APPLICATION 10] 391 IMPLICIT OCTET STRING(SIZE(8)) -- IEEE format 393 Float128 ::= 394 [APPLICATION 11] 395 IMPLICIT OCTET STRING(SIZE(8)) -- IEEE format 397 max-bindings INTEGER ::= 2147483647 399 -- 400 -- Get-Object-PDU definition 401 -- 403 Get-Object-PDU ::= 404 [XXX] -- 9? 405 SEQUENCE { 406 request-id Unsigned32, 407 gop-flags GOPFlags, 408 option-field OptionField, 409 request-objects RequestObjects 410 } 412 GOPFlags ::= 413 IMPLICIT OCTET STRING (SIZE(1)) 414 -- errorOnUnknowFlag(0), 415 -- requestAcknowledgment(1), 417 OptionField ::= SEQUENCE { } -- XXX needs formal definition 419 RequestObjects ::= 420 SEQUENCE (SIZE (0..max-bindings)) OF 421 RequestObject 423 RequestObject ::= 424 SEQUENCE { 425 max-return-objects Unsigned32, 426 skip-objects Unsigned32, 427 cursor OCTET STRING (SIZE(1..256)), 428 request-flags RequestCharacteristics, 430 option-field OptionField, 431 request-base-OID OBJECT IDENTIFIER, 432 request-element-list ElementsRequestList, 433 search-criteria SearchCriteria 434 } 436 RequestCharacteristics ::= 437 IMPLICIT OCTET STRING (SIZE(1)) 438 -- errorOnUnknowFlag(0), 439 -- restartOnInvalidCursor(1), 440 -- returnAllDataOnSearchFailure(2) 442 ElementsRequestList ::= 443 SEQUENCE (SIZE(0..max-bindings)) OF 444 ElementSpecifier 446 ElementSpecifier ::= 447 CHOICE { 448 -- request an index 449 index-number[0] IMPLICIT INTEGER (0..4294967295) 451 -- request an attribute 452 element-number[1] IMPLICIT INTEGER (0..4294967295) 454 -- fully qualified for AUGMENTation tables 455 -- 0.0 prefix = request-base-OID for SMIv3 456 subelement-specifier[2] IMPLICIT OBJECT IDENTIFIER, 458 -- request multiple [sub,...]elements 459 -- *only* usable in an ElementRequestList 460 -- (not in ElementData) 461 multiple-subelement[3] 462 IMPLICIT SEQUENCE { 463 -- fully qualified for AUGMENTation tables 464 -- 0.0 prefix = request-base-OID for SMIv3 465 element-specifier OBJECT IDENTIFIER, 466 element-list ElementRequestList 467 } 469 -- used for referencing external indexes of augmentation 470 -- tables or for SMIv3 sub attributes with external indexes 471 -- This is for use *only* in a SearchCriteria 472 subelement-index[4] 473 IMPLICIT SEQUENCE { 474 -- fully qualified for AUGMENTation tables 475 -- 0.0 prefix = request-base-OID for SMIv3 476 element-specifier OBJECT IDENTIFIER, 477 element-index-number INTEGER (0..4294967295) 478 } 480 } 482 SearchCriteria ::= 483 SEQUENCE { 484 match-type MatchType 485 data 486 CHOICE { 487 -- sub-sequences for logical operations 488 sub-criteria[0] IMPLICIT SEQUENCE 489 (SIZE(0..max-bindings)) 490 OF SearchCriteria, 492 -- match operation data 493 match-data[1] IMPLICIT SEQUENCE { 494 which ElementSpecifier, 495 what ElementSyntax 496 } 497 } 498 } 500 MatchType ::= INTEGER { 501 -- any datatypes: 502 equals(0), 503 not-equals(1), -- note: not-equals NULL ::= exists 505 -- numerical only: 506 lessThan(10), 507 lessThanOrEqual(11), 508 greaterThan(12), 509 greaterThanOrEqual(13), 511 -- binary comparisons: 512 regexp(20), 513 not-regexp(21), 515 -- logical operations: 516 logicalAND(100), 517 logicalOR(101), 518 logicalNOT(102) -- sub-criteria must be exactly 1 in length 520 -- ... IANA assigned up to 255 521 -- enterprise specific: 522 -- 256*EnterpriseID to 523 -- 256*EnterpriseID + 255 524 } 526 -- 527 -- Get-Object-Repsonse-PDU definition 528 -- 530 Get-Object-Repsonse-PDU ::= 531 [XXX] -- 10? 532 SEQUENCE { 533 request-id Unsigned32, 534 gop-flags GOPFlags, 535 option-field OptionField, 536 return-objects ReturnObjects 537 } 539 ReturnObjects ::= 540 SEQUENCE (SIZE(0..max-bindings)) 541 OF ReturnObject 543 ReturnObject ::= 544 SEQUENCE { 545 error-information-list ErrorInformationList, 546 cursor OCTET STRING (SIZE(0..256)), 547 response-flags RequestCharacteristics, 548 option-field OptionField, 550 request-base-OID OBJECT IDENTIFIER, 552 returned-data-list DataList 553 } 555 -- should be an empty sequence if no errors occurred 556 ErrorInformationList ::= 557 SEQUENCE (SIZE(0..max-bindings)) OF 558 ErrorInformation 560 ErrorInformation ::= 561 SEQUENCE { 562 error-status ErrorCode, 563 error-index OBJECT IDENTIFIER, 564 error-string OCTET STRING (SIZE(0..1024)) 565 } 567 ErrorCode ::= 568 INTEGER { 569 -- From RFC3416: 570 noError(0), 571 tooBig(1), 572 noSuchName(2), 573 badValue(3), 574 readOnly(4), 575 genErr(5), 576 noAccess(6), 577 wrongType(7), 578 wrongLength(8), 579 wrongEncoding(9), 580 wrongValue(10), 581 noCreation(11), 582 inconsistentValue(12), 583 resourceUnavailable(13), 584 commitFailed(14), 585 undoFailed(15), 586 authorizationError(16), 587 notWritable(17), 588 inconsistentName(18), 590 -- new in this document: 591 unknownFlag(100), 592 invalidCursor(101), 593 unSupportedSearchOperation(102), 594 tooComplex(103), 595 createFailed(104), 596 deleteFailed(105), 597 getConfigObjectNotSupported(106) 599 -- reserved for enterprise usage: 600 -- 256*EnterpriseID to 256*EnterpriseID + 255 601 -- Enterprise errors MUST be treatable as a genErr for 602 -- applications that don't understand the error enumeration. 603 } 605 -- old speak: multiple rows 606 DataList ::= 607 SEQUENCE (SIZE(0..max-bindings)) OF 608 ObjectData 610 -- old speak: multiple columns with a row 611 ObjectData ::= 612 SEQUENCE (SIZE(0..max-bindings)) OF 613 ElementData 615 ElementData ::= 616 SEQUENCE { 617 which-element ElementSpecifier, 618 element-value ElementValue 619 } 621 ElementValue ::= 622 CHOICE { 623 base-type-object ElementSyntax, 625 -- for SMIv3 sub-object aggregates and augmentation tables: 626 sub-object DataList 627 } 629 -- 630 -- Write-Object-PDU definition 631 -- 633 Write-Object-PDU ::= 634 [XXX] -- 11? 635 SEQUENCE { 636 request-id Unsigned32, 637 write-flags WriteSemantics, 638 option-field OptionField, 639 write-transactions WriteTransaction 640 } 642 WriteSemantics ::= 643 OCTET STRING (SIZE(1)) 644 -- errorOnUnknowFlag(0), 645 -- requestAcknowledgment(1), 646 -- returnDataOnlyOnError(2) 648 WriteTransaction ::= 649 SEQUENCE { 650 transaction-flags TransactionSemantics, 651 option-field OptionField, 653 transaction-data-list TransactionDataList 654 } 656 TransactionSemantics ::= 657 OCTET STRING (SIZE(1)) 658 -- errorOnUnknowFlag(0), 659 -- needSuccess(1), 660 -- needAll(2), 661 -- notOrderDependent(3) 663 TransactionDataList ::= 664 SEQUENCE (SIZE(0..max-bindings)) OF 665 TransactionData 667 TransactionData ::= 668 CHOICE { 669 create-transaction[0] CreateTransaction, 670 modify-transaction[1] ModifyTransaction, 671 delete-transaction[2] DeleteTransaction, 672 method-transaction[3] MethodTransaction 673 sub-transaction WriteTransaction 674 } 676 CreateTransaction ::= SEQUENCE { 677 request-base-OID OBJECT IDENTIFIER, 678 create-data-list DataList 679 } 681 ModifyTransaction ::= SEQUENCE { 682 request-base-OID OBJECT IDENTIFIER, 683 modify-search-criteria SearchCriteria, 684 modify-data-list DataList 685 } 687 DeleteTransaction ::= SEQUENCE { 688 request-base-OID OBJECT IDENTIFIER, 689 delete-search-criteria SearchCriteria, 690 } 692 MethodTransaction ::= SEQUENCE { 693 method-OID OBJECT IDENTIFIER, 694 method-arguments DataList 695 } 697 -- 698 -- Write-Object-Response-PDU definition 699 -- 701 Write-Object-Response-PDU ::= 702 [XXX] -- 12? 703 SEQUENCE { 704 request-id Unsigned32, 705 write-flags WriteSemantics, 706 option-field OptionField, 707 error-information-list ErrorInformationList, 709 write-transaction-results WriteTransactionResults 710 } 712 WriteTransactionResults ::= 713 SEQUENCE (SIZE(0..max-bindings)) OF 714 WriteTransactionResponse 716 WriteTransactionResult ::= 717 SEQUENCE { 718 transaction-flags TransactionSemantics, 719 option-field OptionField, 721 transaction-response-list TransactionResponseList 722 } 724 TransactionResponseList ::= 725 SEQUENCE (SIZE(0..max-bindings)) OF 726 TransactionResponse 728 TransactionResponse ::= 729 CHOICE { 730 create-response[0] CreateResponse, 731 modify-response[1] ModifyResponse, 732 delete-response[2] DeleteResponse 733 } 735 CreateResponse ::= { 736 request-base-OID OBJECT IDENTIFIER, 737 create-data-list DataList -- copy of sent 738 } 740 ModifyResponse ::= { 741 request-base-OID OBJECT IDENTIFIER, 742 modify-data-list DataList -- ONLY indexes of 743 -- modified elements 744 -- and data 745 } 747 DeleteResponse ::= { 748 request-base-OID OBJECT IDENTIFIER, 749 delete-data-list DataList -- ONLY indexes 750 } 752 MethodResponse ::= SEQUENCE { 753 method-OID OBJECT IDENTIFIER, 754 method-return-data DataList 755 } 757 -- 758 -- Get-Configuration-Objects-PDU definition 759 -- 761 Get-Configuration-Objects-PDU ::= 762 [XXX] -- 13? 763 SEQUENCE { 764 request-id Unsigned32, 765 gcop-flags GCOPFlags, 766 option-field OptionField, 767 request-objects ConfigurationObjectsList 768 } 770 GCOPFlags ::= 771 IMPLICIT OCTET STRING (SIZE(1)) 772 -- errorOnUnknowFlag(0), 773 -- requestAcknowledgment(1), 775 ConfigurationObjectsList ::= 776 SEQUENCE OF (SIZE (0..max-bindings)) OF 777 ConfigurationObjects 779 ConfigurationObjects ::= 780 SEQUENCE { 781 request-flags ConfigurationFlags, 782 option-field OptionField, 783 requested-config RequestedConfig 784 } 786 ConfigurationFlags ::= 787 IMPLICIT OCTET STRING (SIZE(1)) 788 -- errorOnUnknowFlag(0), 790 RequestedConfig ::= OBJECT IDENTIFIER 792 -- 793 -- Configuration-Objects-Response-PDU definition 794 -- 795 Configuration-Objects-Response-PDU ::= 796 [XXX] -- 14? 797 SEQUENCE { 798 request-id Unsigned32, 799 gcop-flags GCOPFlags, 800 option-field OptionField, 801 config-results ConfigurationResults 802 } 804 ConfigurationResults ::= 805 SEQUENCE (SIZE(0..max-bindings)) OF 806 ConfigurationResult 808 ConfigurationResult ::= 809 SEQUENCE { 810 request-flags ConfigurationResultFlags, 811 option-field OptionField, 812 error-information ErrorInformationList, 813 config-transactions WriteTransaction 815 } 817 -- 818 -- Notification-Objects-PDU definition 819 -- 821 Notification-Object-PDU ::= 822 [XXX] -- 15? 823 SEQUENCE { 824 request-id Unsigned32, 825 notification-flags NotificationSemantics, 826 option-field OptionField, 828 notifications NotificationList 829 } 831 NotificatonList ::= 832 SEQUENCE (SIZE(0..max-bindings)) OF 833 Notification 835 Notification ::= 836 SEQUENCE { 837 notification-id OBJECT IDENTIFIER, 838 system-uptime TimeTicks, 839 notification-string OCTET STRING, 841 notification-objects NotificationObjects 842 } 844 NotificationObjects ::= 845 SEQUENCE (SIZE(0..max-bindings)) OF 846 NotificationObject 848 NotificationObject ::= 849 SEQUENCE { 850 option-field OptionField, 851 request-base-OID OBJECT IDENTIFIER, 852 notification-data DataList 853 } 855 NotificationSemantics ::= 856 OCTET STRING (SIZE(1)) 857 -- errorOnUnknowFlag(0), 858 -- requestAcknowledgment(1) 860 -- 861 -- Acknowledgment-PDU definition 862 -- 863 -- Note that this PDU used to Acknowledge any PDU with a 864 -- requestAcknowledgement flag set. 866 Acknowledgment-PDU ::= 867 [XXX] -- 16? 868 SEQUENCE { 869 request-id Unsigned32, 870 ack-flags AcknowledgmentFlags, 871 option-field OptionField 872 } 874 AcknowledgmentFlags ::= 875 OCTET STRING (SIZE(1)) 876 -- errorOnUnknowFlag(0), 877 -- requestAcknowledgment(1) 879 END 881 3.2. New PDU component definitions 883 This section clarifies the data components contained within the PDUs 884 defined above. See the "PDU Processing" section below for 885 information on how processing of all of these elements together 886 should be performed. 888 3.2.1. Common PDU elements of the OOPS PDUs 890 The following is a list of PDU fields which are common to multiple 891 PDU sets (for example, they may exist in both the Get-Object-PDU and 892 Write-Object-PDU operation). 894 request-id 895 A numeric field indicating the current request number of a 896 PDU. The response PDUs (Get-Object-Response-PDU, Write- 897 Object-Response-PDU, Configuration-Objects-Response-PDU and 898 the Acknowledgment-PDUs) MUST set this field to the value of 899 the request-id from the request PDUs (Get-Object-PDU, Write- 900 Object-PDU, Get-Configuration-Object-PDU or Notification- 901 Object-PDU) that generated the response. 903 common flags 904 A few common flags exist in multiple spots within all of the 905 PDUs. These flags are: 907 errorOnUnknowFlag 908 This flag is used to indicates that for any unknown flags 909 in the flag list, the Command Responder processing the 910 request MUST immediately return an error without 911 processing the request further. Otherwise, any unknown 912 flags MUST be ignored and the request MUST be processed 913 as if the flags were not set. However, even though 914 processing must continue, an error MUST be inserted into 915 the appropriate error-list, however, to indicate that the 916 flag was ignored.. 918 requestAcknowledgment 919 This flag indicates that the Command Responder should 920 immediately return an Acknowledgment-PDU after the 921 request has been received. The Acknowledgment-PDU serves 922 as a quick reply to indicate that the request was 923 received and is about to be processed. Requests which 924 are expected to need time while processing are encouraged 925 to set this flag so retransmissions or re-connections 926 will be less necessary. 928 Note: This flag is not intended to replace reliable 929 transport mechanisms but merely to serve as an 930 application level acknowledgment. Since the 931 acknowledgment could be lost in a non-reliable transport 932 protocol, utilization of reliable transport (e.g., TCP) 933 is highly encouraged. 935 *-option-field 936 A sequence reserved for future use. Command responders which 937 encounter unknown option types specified in this sequence MUST 938 ignore the data and proceed as if the field itself wasn't 939 included in the request. Future protocol extensions MUST 940 define extensions to be implemented within this sequence in 941 such a way that the option can be safely ignored by 942 implementations which fail to understand it. 944 This field exists in multiple places in the PDU definitions 945 contained within this document. In all cases future extension 946 documents may define extension fields for use within these 947 option-field sequences. The sequences defined in the future 948 MUST contain only an ASN.1 OPTION-ized list of parameters. 949 The option index numbers for the sequence will be assigned and 950 administered by IANA. 952 XXX Note: Proper ASN.1 definitions of the option fields in 953 this document are missing. 955 ErrorInformation 956 The ErrorInformation sequences contain a list of errors 957 associated with processing a request. Multiple errors may be 958 present in this list, and not all of the errors reported may 959 be fatal errors. Some errors reported in the ErrorInformation 960 list may be warnings indicating troubles found while 961 processing a request. It consists of the following elements: 963 error-status 964 This is a numeric value indicating the type of error 965 being conveyed. It's value dictates the type, severity, 966 and the component for which the error-index will refer 967 to. 969 error-index 970 An index into "something", where "something" is defined 971 by what the error-status field contains (as an example, 972 the unSupportedSearchRange error indicates it's an index 973 into the search objects in the original request). It is 974 an OBJECT IDENTIFIER which should begin with a 0.0 975 (zeroDotZero) prefix, and the components of the 976 identifier after that will indicate which sub-element of 977 either the index-request-list, column-request-list or 978 search-criteria field caused the problem. 980 error-string 981 This SHOULD be set to a human-readable, administrative 982 string describing the particular error (in greater detail 983 than the error-status field alone can indicate). 984 Software implementations MUST NOT expect the contents of 985 field to be machine parsable. Standards documents MUST 986 NOT dictate the format of the data to be conveyed by this 987 field. 989 *-base-OID 990 A base-oid is the fundamental structure that a PDU will 991 operate on. For SMIv2 structures, for instance, this will be 992 either a scalar or a table. For SMIv3 objects, it should 993 point to the highest instantiation of an aggregate object. 995 ElementSpecifier 996 An ElementSpecifier is used in many places within the MIB to 997 indicate which element is being referred to. It is used when 998 both sending and receiving data. It is always used in 999 conjunction with a base-oid. All of the elements referenced 1000 by the ElementSpecifier is related to the base-oid in some 1001 fashion. The sub-elements of the ElementSpecifier are: 1003 index-number 1004 This is used to reference an index of the SMI structure 1005 referenced by the base-oid. Indexes are enumerated from 1006 the INDEX clause of a SMI structure, starting with the 1007 number 1. If an index is accessible directly within the 1008 base-oid structure, the element-number specifier SHOULD 1009 be used instead. 1011 element-number 1012 This is used to reference an accessible element of the 1013 SMI structure referenced by the base-oid. The value 1014 directly corresponds with the assigned OID element number 1015 underneath the base-oid. For SMIv2 tables, this field 1016 MUST contain the column number being referenced. For 1017 SMIv2 scalars, this field MUST contain zero. 1019 subelement-specifier 1020 This is used for referencing a single sub-element within 1021 an augmentation table or other SMIv3 structure. SMIv3 1022 sub-element structure references MUST begin with the 1023 nullOID prefix (0.0). 1025 For example, if the base-oid was referring to the IF- 1026 MIB::ifTable, then a subelement-specifier of IF- 1027 MIB::ifName would reference the ifName field of the 1028 ifXTable augmentation table. 1030 multiple-subelements 1031 When multiple sub-elements need to be referenced within a 1032 PDU construct, the multiple-subelements field can be used 1033 to list numerous related fields. 1035 For example, if the base-oid was referring to the IF- 1036 MIB::ifTable, then a multiple-subelement specifier might 1037 have a element-specifier of IF-MIB::ifXTable and a 1038 element-list including both the ifXTable's ifName and 1039 ifHCInOctets columns. 1041 subelement-index 1042 This is a method of specifying indexes of sub-elements 1043 and externally defined elements (E.G., augmentation 1044 tables). This field is only used in SearchCriteria. 1046 DataList 1047 XXX 1049 3.2.2. Get-Object-PDU specific PDU elements 1051 The Get-Object-PDU and Get-Object-Response-PDU specific protocol 1052 elements are briefly summarized here: 1054 request-objects 1055 Each request within the Get-Object-PDU is broken into 1056 individual request-objects and each of these are processed 1057 independently by the receiving Command Responder. The results 1058 of each processed request-object are then combined into 1059 corresponding return-objects within the Get-Object-Response- 1060 PDU. 1062 max-return-objects 1063 The maximum number of objects to return in the Get-Object- 1064 Response-PDU. A value of 0 indicates that all available 1065 objects should be returned. 1067 skip-objects 1068 If the cursor field contains a zero-length string, an Command 1069 Responder MUST NOT return the first skip-objects number of 1070 objects that match the search criteria. Instead, objects 1071 numbering from (skip-objects + 1) to (max-return-objects + 1072 skip-objects + 1) must be returned. A value of 0 indicates 1073 that the Command Responder should start returning object data 1074 beginning with the first object that matches the search- 1075 criteria. The skip-objects field MUST be entirely ignored if 1076 the cursor (see below) field contents is valid. 1078 cursor 1079 An OCTET STRING defining the starting point for collecting 1080 data. This field MUST be a zero length OCTET STRING when 1081 accessing the first object in a structure or table. When 1082 request processing stops because the max-returned-objects 1083 count had been reached for a given request-object, Command 1084 Responders MUST return a value in this field that can be used 1085 in future requests to resume a search from the stopping point 1086 . The value of the cursor is implementation dependent. 1087 Command Generators MUST treat it as generic data and MUST NOT 1088 expect it to be in format which is parsable by the Command 1089 Generator. Command Generators SHOULD use it when continuing a 1090 search operation in a follow-up request. Command responders 1091 MUST refer to the value of the skip-objects field if the 1092 cursor field is a zero length string. Command responders MUST 1093 ignore the value of the skip-objects field if the cursor field 1094 is a non-zero length string and is deemed to be a valid 1095 cursor. 1097 Cursors SHOULD be defined by the command responder in such a 1098 way as to avoid referencing an existing object. Cursors 1099 SHOULD be valid at any time in the future regardless of 1100 whether or not the underlying data within the Command 1101 Responder has changed. I.E., cursors should be data 1102 independent whenever possible and should be a reference into 1103 the appropriate place in the storage mechanism and not a 1104 reference to a data row within the storage mechanism. Command 1105 Responders MAY define cursors in such a way that they are not 1106 valid after an Command Responder reboots, but this is 1107 discouraged. 1109 If a cursor is deemed invalid by the command responder, the 1110 command responder must do one of two things: 1112 a) If the restartOnInvalidCursor request-flag is set, the 1113 search operation MUST NOT be performed and an appropriate 1114 invalidCursor error should be returned in the response. 1116 b) If the restartOnInvalidCursor flag is not set, the search 1117 operation should start at the point indicated by the 1118 skip-objects field. 1120 As an example cursor, an Command Responder which was 1121 performing internal Get-Object-PDU translations to internal or 1122 subagent based GETNEXT instrumentation might return a cursor 1123 containing the BER encoding of the last OID returned within 1124 the response. The next request could merely continue 1125 processing using the encoded OID just as if a real GETNEXT had 1126 come in. 1128 request-flags 1129 A flag list indicating particular features to be used when 1130 processing the Get-Object-PDU. The two Get-Object-PDU 1131 specific flags are: 1133 restartOnInvalidCursor 1134 This flag indicates that when an invalid cursor is sent 1135 in the Get-Object-PDU request, the Command Responder 1136 should behave as described in the cursor field 1137 description above. 1139 returnAllDataOnSearchFailure 1140 When a search operation fails due to an unsupported 1141 match-type, this flag indicates how to handle the error 1142 condition. If the returnAllDataOnSearchFailure bit is 1143 set, the search condition must be functionally ignored as 1144 if it did not restrict the data being returned. If not 1145 set, an error unSupportedSearchOperation condition must 1146 be inserted into the error-information-list and the 1147 request in particular is not processed. 1149 request-base-OID 1150 The base OID for a given element to request information from. 1151 For SMIv2 objects, this is either the OID pointing to a table 1152 or a particular scalar. For SMIv3 objects, it should point to 1153 the highest instantiation of an aggregate object. 1155 request-element-list 1156 This sequence contains a list of attributes to be returned in 1157 the response. IE, what particular data attributes or columns 1158 of a object or tabel's row should be returned. If this 1159 sequence is empty, then all data for the requested request- 1160 base-OID object MUST be returned. Command Generators SHOULD 1161 specify the data they wish to have returned rather than leave 1162 this field empty. Command Generators SHOULD request 1163 accessible index elements be returned as element values rather 1164 than indexes values. 1166 search-criteria 1167 This sequence contains criteria which indicates which elements 1168 should be returned. If the search-criteria is understood and 1169 if the object data to be returned does not match the criteria 1170 imposed by the restrictions in a request, then it SHOULD NOT 1171 be returned. 1173 Command Generator implementations should specify attribute 1174 matching in preference to index matching, and thus index 1175 matching SHOULD ONLY be used for externally defined index 1176 values which don't have a attribute number assignment within 1177 the object. 1179 match-type 1180 Specifies the criteria to be imposed for a given search value. 1181 match-type's are simple logical operators used in search- 1182 criteria expressions. 1184 If the returnAllDataOnSearchFailure bit is set, then if a 1185 search operation fails due to a condition like an unsupported 1186 or unknown match-type, all data MUST BE returned as if the 1187 search-type operator had always returned "true" (i.e., the 1188 Get-Object-Response should contain all possible data that the 1189 match-type would have been used to discriminate against). 1190 Note that other, properly-understood, components of the 1191 search-criteria can still limit the data returned to the 1192 requester. 1194 If the returnAllDataOnSearchFailure bit is not set then the 1195 related return-objects field for the given request MUST NOT 1196 contain any data when sent back to the requester. 1198 XXX: mention WOPs 1200 In either case, an unSupportedSearchOperation error condition 1201 will be added to the error-information-list field of the Get- 1202 Object-Response-PDU and the error-index field will be set to 1203 the search component that caused the failure. As mentioned 1204 above, if the returnAllDataOnSearchFailure bit is set data is 1205 still returned to the requester and the error can be viewed as 1206 a warning that possibly more data was returned than was 1207 requested. 1209 Implementations SHOULD return a unSupportedSearchOperation 1210 error in the error-information-list for each unsupported 1211 unique match-type within the requested search-criteria. 1213 response-flags 1214 The flags field MUST be set according to how the response was 1215 handled within the responder. Ideally this should be an exact 1216 copy of the flags field from the request, assuming the flags 1217 were understood. Flags from the request which were not 1218 understood by the command responder MUST be set to 0 in the 1219 returned Get-Object-Response-PDU. 1221 3.2.3. Write-Object-PDU specific PDU elements 1223 These protocol elements are specific to Write-Object-PDU requests. 1225 write-flags 1227 Global flags to apply to the entire Write-Object-PDU. The are 1228 broken down as follows: 1230 returnDataOnlyOnError 1231 If the returnDataOnlyOnError bit is set, then the Write- 1232 Object-Response-PDU will only contain a duplicate set- 1233 objects portion of the message if there was an error 1234 somewhere in the processing of the message, otherwise the 1235 objects list will be truncated. Command Responder 1236 implementations SHOULD support this flag, but if for any 1237 reason they decide to return the set-objects data portion 1238 of the message they MUST NOT set the 1239 returnDataOnlyOnError bit. If the flag is set, and the 1240 command responder supports it, then the write- 1241 transaction-responses field must be an zero length 1242 sequence. 1244 write-transactions 1245 Flags which apply to each sub-element of the write transaction 1246 to be performed. Currently there are 3 bits to define 1247 transactional processing semantics to be used when processing 1248 this message. These values are described in greater detail in 1249 the next section. 1251 TransactionData 1252 Indicates what type of operation is to be performed by this 1253 transaction set and contains the data associated with that 1254 operation. Specifically: 1256 create-transaction, create-data-list 1257 Creates a new row within a row. It is an error condition 1258 if either the row can not be created (noCreation) or if 1259 the row already existed (createFailed). The create-data- 1260 list parameter specifies the data to be used to create 1261 the row with. 1263 modify-transaction, modify-search-criteria, modify-data-list 1264 Modifies an existing row or set of rows. The rows that 1265 are to be affected by the modify-transaction are 1266 identified by the modify-search-criteria parameters. The 1267 data in the modify-data-list parameter specifies what 1268 values will be updated by the request. Note that a 1269 modify-transaction can not be used to create new rows. 1271 delete-transaction, delete-search-criteria 1272 Deletes a given row or set of rows. If a row can not be 1273 deleted for some reason, it is considered to be an error 1274 condition (deleteFailed). The delete-search-criteria 1275 identifies which rows should be deleted from the table. 1277 method-transaction, method-OID, method-arguments 1278 The method-transaction is similar to a function call, 1279 defined by the documentation associated with the method- 1280 OID, in that it expects arguments (method-arguments) and 1281 generates return values (method-return-data). It is up 1282 to future specifications to define method OIDs that can 1283 make use of this functionality. 1285 sub-transaction 1286 A sub-transaction most likely contains a collection of 1287 transactions which are bound together by a different 1288 transaction-flags settings. 1290 modify-search-criteria 1292 delete-search-criteria 1293 The search criteria imposed by the modify-search-criteria and 1294 delete-search-criteria are identical in operation to the Get- 1295 Object-PDU equivalents, except that instead of requested 1296 information back the describe which objects should be 1297 modified. Unlike the Get-Object-PDU match-type handling, an 1298 unsupported match-type will always trigger an 1299 unSupportedSearchOperation error condition and no modification 1300 or deletion will occur for that transaction (or any other 1301 transactions dependent on the success of transaction one 1302 containing the error). 1304 create-response 1305 A create-response object returns a copy of all the data sent 1306 in a create request. The response MUST contain an exact copy 1307 of the related request if the returnDataOnerror bit in the 1308 write-transactions flags is not set. If the returnDataOnerror 1309 bit in the write-transactions flag is set, this MUST be a 1310 encoded as an empty sequence. 1312 modify-response 1313 A modify response returns the data affected by the outgoing 1314 transaction. The modify-search-criteria field MUST be an 1315 exact copy from the associated Write-Object-PDU modify- 1316 transaction component. The modify-data-list should contain 1317 all the elements modified by the request. It MUST include all 1318 index objects for the object elements that were modified, plus 1319 the data values from the request. 1321 delete-response 1322 A delete response returns the data affected by the outgoing 1323 transaction. The modify-search-criteria field MUST be an 1324 exact copy from the associated Write-Object-PDU delete- 1325 transaction component. It MUST ONLY include the index objects 1326 for the object elements that were deleted. 1328 3.2.4. Get-Configuration-Object-PDU specific PDU elements 1330 A Get-Configuration-Object-PDU is used to request current 1331 configuration state for some portion of an Command Responder. The 1332 Configuration-Objects-Response-PDU will contain transactions 1333 suitable for use in a Write-Object-PDU request which can be issued 1334 to the Command Responder to restore itself to its current state. 1335 These elements of the Get-Configuration-Object-PDU are described 1336 here. 1338 requested-config 1339 A list of object identifiers for which configuration is 1340 desired. These object identifiers can be one of: 1342 a) Defined OIDs from a particular MIB module which describes 1343 what configuration components should be returned in the 1344 Configuration-Objects-Response-PDU. 1346 b) An OID of an object which contains configuration 1347 information. IE, this could point to a particular table 1348 from a MIB module. 1350 c) The ZeroDotZero (0.0) OID which can be used to request 1351 all configuration information from an Command Responder. 1353 Unsupported OBJECT IDENTIFIERS requested will be reported in 1354 the ErrorInformationList in the Configuration-Objects- 1355 Response-PDU as a getConfigObjectNotSupported error. 1357 3.2.5. Notification-Object-PDU specific elements 1359 The Notification-Object-PDU can be used to send SNMP Notifications 1360 to a notification receiver. The elements contained within a 1361 Notification-Object-PDU are described in this section. 1363 notification-id 1364 This is the notification ID as defined by NOTIFICATION-TYPE 1365 and other SMI macros. 1367 system-uptime 1368 The current value of sysUpTime.0 when the notification was 1369 sent from the notification generator. 1371 notification-string 1372 A human readable string describing the notification. 1373 Notification Receivers MUST NOT expect this field to be 1374 machine parsable. 1376 notification-objects 1377 Data objects included with the notification. Minimally, this 1378 must contain the OBJECTS field as defined by NOTIFICATION-TYPE 1379 SMI or other similar SMI macros. 1381 4. PDU processing 1383 4.1. Processing a Get-Object-PDU 1384 The following describes the procedure for processing a Get-Object- 1385 PDU to produce a Get-Object-Response-PDU. The Get-Object-Response- 1386 PDU MUST contain the same request-id as the Get-Object-PDU. The 1387 Get-Object-Response-PDU MUST contain the same number of return- 1388 objects as there were request-objects in the Get-Object-PDU being 1389 processed. return-objects MUST appear in a order which matches the 1390 request-objects they are associated with from the Get-Object-PDU. 1392 Apply the following procedure to each of the request-objects within 1393 the Get-Object-PDU to generate a corresponding return-objects 1394 sequence to be placed in the Get-Object-Response-PDU. 1396 Each request-object MUST generate a corresponding return-object with 1397 less than or equal to max-return-objects pieces as specified in the 1398 request-object unless the max-return-objects field value is zero. 1399 If max-return-objects field is zero then all objects meeting the 1400 search-criteria evaluation MUST be returned. [XXX: transport and 1401 sizing issues] 1403 If the cursor field is specified in the request-object, the cursor 1404 field MUST be used, if it is valid, to determine a starting point 1405 for the data to be returned. If the contents of the cursor field 1406 are invalid or it is impossible to determine a valid starting place 1407 and the restartOnInvalidCursor bit is set in the search-criteria, 1408 then the data returned should start with the skip-objects+1 object. 1409 Note that when counting objects to skip, only objects which meet the 1410 requirements imposed by the search-criteria WILL be counted. If the 1411 restartOnInvalidCursor bit is not set, then no objects should be 1412 returned in the Get-Object-Response-PDU return-objects list. 1413 Regardless of whether the restartOnInvalidCursor bit is set or not, 1414 an invalidCursor error MUST be inserted into the error-information- 1415 list in the return-objects field in the Get-Object-Response-PDU. 1417 The cursor field in the Get-Object-Response-PDU MUST be a zero- 1418 length OCTET STRING if the Get-Object-PDU's max-return-objects is 1419 not 0 and there are less than max-return-objects being returned in 1420 the Get-Object-Response-PDU. If the number of objects being 1421 returned is equal to the max-return-objects parameter, then the 1422 cursor field MAY be a zero length string if the last object being 1423 returned is also the last object in the possible set of data for the 1424 given search-criteria. 1426 Implementations MUST return data in a dependable order. Successive 1427 requests with identical search-criteria and request-base-OIDs MUST 1428 return objects in the same order in which they were returned 1429 previously. I.E., if object A (as defined by it's indexes) is 1430 returned before object B at one point in time, it MUST always be 1431 returned before object B for any future requests. 1433 When the maximum number of objects to be returned has been reached, 1434 a cursor MUST be constructed which meets the criteria described 1435 above. It MUST be usable in the future to determine the starting 1436 place for future follow-on Get-Object-PDUs. The contents of the 1437 cursor field SHOULD [XXX: maybe this should be a MUST?] be data 1438 independent such that it is impossible for a cursor constructed by 1439 an Command Responder to be considered invalid at any point in the 1440 future. Since cursors are designed to alleviate processing overhead 1441 associated with restarting searches in the future, it is highly 1442 recommended that Command Responder implementations make efficient 1443 and appropriate use of the cursor field. 1445 When searching for objects which are to be returned to the 1446 requester, the search-criteria MUST be consulted. Any object not 1447 matching the supported elements of the criteria imposed by the 1448 search-criteria field MUST NOT be included in the response. When 1449 processing the search-criteria field, any match-type which is not 1450 supported by the processing engine MUST result in an 1451 unSupportedSearchOperation error being inserted into the response's 1452 error-information list. Additionally, one of the following must be 1453 followed based on the value of the returnAllDataOnSearchFailure 1454 flag: 1456 a) If the returnAllDataOnSearchFailure bit is set, then the 1457 evaluation MUST return all the data as if the unsupported 1458 match-type imposed no filtering on the data. Generally, this 1459 would mean that any match-type should be considered as 1460 evaluating to true, except in the case where the evaluation is 1461 enclosed directly within a logicalNOT operation, in which case 1462 the result of the logicalNOT must evaluate to true. 1464 b) If the returnAllDataOnSearchFailure bit is unset, then the 1465 response MUST contain an empty returned-data-list. 1467 Logical operations (logicalAND, logicalOR, logicalNOT) WILL use the 1468 sub-criteria field of the SearchCriteria to specify a list of sub- 1469 criteria the logical operation is to operate on. If the match type 1470 is logicalNOT there MUST be exactly one element in the sub-criteria 1471 list. 1473 When constructing a return-objects list, the request-element-list 1474 must be consulted to determine which elements of a given object are 1475 to be returned in the response. When sending a Get-Object-PDU, the 1476 request-element-list SHOULD use the element-number specifier when 1477 possible in preference to the index-number specifier when the index 1478 is an accessible element in an object. 1480 4.2. Processing a Write-Object-PDU. 1482 When a Write-Object-PDU is received by an Command Responder it must 1483 process the transaction(s) found in the write-transaction field. 1484 The transaction-flags field of the write-transaction indicates how 1485 the sub-transactions grouped in a single write-transaction relate to 1486 each other. 1488 The main Write-Object-PDU contains a single WriteTransaction which 1489 itself may be composed of multiple sub-transactions (create, modify, 1490 delete, method, or sub-transactions). The hierarchal nature of the 1491 transaction-data-list allows for more complex transaction 1492 relationships to be defined. Command Responders MAY implement 1493 nested sub-transactions but are not required to in order to conform 1494 with this specification. 1496 The flags that make up the transaction-flags can be summarized as 1497 follows: 1499 needSuccess 1500 If the needSuccess bit is set the containing transaction is 1501 considered sucessful if and only if no error conditions must 1502 occur during the processing of the sub-transactions in the 1503 transactions-data-list. If processing the sub-transactions 1504 results in a failure then the containing transaction is also 1505 considered to be a failure. If this bit is not set then the 1506 containing transaction itself will always be considered 1507 successful. 1509 needAll 1510 If the needAll bit is set each sub-transaction in the 1511 transaction-data-list must be attempted for this transaction 1512 to be considered successful. If this is not set, processing 1513 of the transactions-data-list MUST stop after the first 1514 transaction in the transaction-data-list which is successful. 1516 notOrderDependent 1517 If the notOrderDependent bit is set the transactions contained 1518 in the transaction-data-list MAY be executed in an order. If 1519 the needAll bit is set they may even be processed in parallel. 1520 Note that all transactions must still revert to their previous 1521 state if an error condition requires a state rollback for all 1522 the transactions. 1524 Thus, the following combinations of the first two flags can be 1525 better described in combination: 1527 needSuccess = true, needAll = true: doAll [doUntilFailure] 1528 All contained transactions must succeed. If any failure 1529 occurs, the entire set of transactions in the transactions- 1530 data-list must be rolled back. This mode is most similar to 1531 the previous SNMP SET-PDU. 1533 needSuccess = false, needAll = true: tryAll 1534 With this combination set, the command responder must try to 1535 achieve all the transactions, however if any transaction fails 1536 it is not required to roll back the rest of the transactions. 1537 The failed transactions themselves, however, must individually 1538 properly revert to the previous state. This mode allows a 1539 bunch of independent transactions to be specified in one 1540 management operation. It is roughly equivalent to a bunch of 1541 individual and independent SNMP SET-PDU operations. 1543 needSuccess = true, needAll = false: doAtLeastOne 1544 [doUntilSuccess] 1545 In this case, at least one must succeed for the transaction as 1546 a whole to succeed. More importantly, if any one transaction 1547 component does succeed, processing MUST be stopped and the 1548 transaction as a whole is considered successful. Another way 1549 to put it: at most one successful component is executed and 1550 never more than one. This mode is useful for specifying, for 1551 example, a transaction with one or more "fall-back" 1552 transactions in case one fails. 1554 needSuccess = false, needAll = false: tryAtLeastOne 1555 In this case, at least one must succeed for the transaction as 1556 a whole to succeed. More importantly, if any one transaction 1557 component does succeed, processing MUST be stopped. The 1558 different between this combination of bits and the previous is 1559 that this transaction itself always succeeds, even if all the 1560 sub-transactions fail. It is impossible for a transaction of 1561 this type to be considered a failure in itself. 1563 Also, error reporting will always occur on failed objects even if 1564 they don't affect the containing transactions and surrounding 1565 transactions. 1567 Note that more data can be returned in many cases when search 1568 operations required operations on multiple rows based on the search 1569 criteria. 1571 XXX: response generation. 1573 4.3. Processing a Get-Configuration-Object-PDU request 1574 A Get-Configuration-Object-PDU will contain a sequence of OBJECT 1575 IDENTIFIERs indicating which particular configuration objects are 1576 being requested. The types of OBJECT IDENTIFIERs which may be 1577 specified in the list were previously defined. 1579 When an Command Responder receives a Get-Configuration-Object-PDU it 1580 should return in the Configuration-Objects-Response-PDU a valid set 1581 of WriteTransactions which will return a device to the current 1582 configuration state at the time the request was received. Exactly 1583 one WriteTransaction MUST be returned for each OBJECT IDENTIFIER 1584 requested in the request-objects field. 1586 4.4. Generating a Notification-Object-PDU 1588 A Notification-Object-PDU is generated by first creating an 1589 appropriate request-id, filling in the appropriate bits of the 1590 notification-flags and specifying any options in the option-field. 1591 The notifications field is then filled in with the notifications to 1592 be sent in this PDU. Note that the Notification-Object-PDU allows 1593 for multiple notifications to be sent within a single PDU. This 1594 paves the way for future delivery of multiple notifications at once. 1595 Predicted applications capability for this included combined 1596 delivery of multiple notifications as well as automated Command 1597 Responder data sampling at regular intervals. 1599 For each notification to be delivered, the following procedure is 1600 then used to create each notification with the notifications field: 1601 The notification-id field is filled in with the appropriate OBJECT 1602 IDENTIFIER as required by the specification defining the 1603 notification to be sent (E.G., a NOTIFICATION-TYPE macro for SMIv2 1604 MIB modules). The system-uptime MUST contain the current value of 1605 the sysUpTime object for the Notification Generator sending the 1606 notification. The notification-string field should be filled in 1607 with a human readable string if possible, otherwise a zero-length 1608 OCTET STRING should be used instead. 1610 The notification-objects field MUST then be populated with the 1611 objects required by the specification defining the notification 1612 (E.G., the OBJECTS field of the NOTIFICATION-TYPE macro for SMIv2 1613 MIB modules). Notification-objects will need to make use of the 1614 subelement-specifier field of an ElementSpecifier when sending 1615 objects from a related table. See the "Examples" section below for 1616 an example of this. The notification-objects field MUST be 1617 populated in the same order as required by the defining 1618 specification. Any optional objects the Notification Generator 1619 wishes to append to the notification-objects field may then be 1620 appended to the generated notification-objects field. 1622 5. Examples 1624 Here are some example requests and responses of data retrieval. In 1625 each case, the curly braces indicate a sequence of some kind within 1626 BER. 1628 5.1. Retrieve a specific row from the ifTable 1630 This example retrieves the ifDescr and ifType columns for the 5th 1631 interface from the ifTable 1633 The Request: 1635 Get-Object-PDU { 1636 request-id 1 1637 option-field { } 1638 request-objects { { 1639 max-return-objects 0 -- get all 1640 skip-objects 0 -- starting with the first 1641 cursor "" -- 0 length for 1st request 1642 flags 0x00 -- none specified. 1643 option-field {} 1645 request-base-object IF-MIB::ifTable 1647 request-element-list { element-number = 2, 1648 element-number = 3 } 1650 search-criteria { match-type = 0, -- equals 1651 match-data = { 1652 which = 1, -- ifIndex 1653 what = 5 -- 5th 1654 } } 1655 } } 1656 } 1658 The Response: 1660 Get-Object-Response-PDU { 1661 request-id 1 1662 option-field {} 1663 response-objects ::= { { 1664 error-information-list {} -- no Errors 1665 cursor "" -- no other data 1666 response-flags 0x00 -- none specified. 1667 option-field {} -- no options 1669 request-base-object IF-MIB::ifTable 1670 returned-data-list { { 1671 { which-element = 2, 1672 element-value = "interface 5" }, 1673 { which-element = 3, 1674 element-value = 6 } 1675 } } 1676 } } 1677 } 1679 5.2. A multiple-packet example with a double filter 1681 This example shows the retrieval of the elements of the ifTable 1682 which are of type "ethernetCsmacd" and have a ifSpeed >= 10,000,000 1683 bps. Retrieve only 1 row at a time, and include columns from the 1684 ifXTable augmentation table. Note that the response has the objects 1685 returned in the order the remote Command Responder specified 1686 [interface 12, then interface 5], not in something that would 1687 directly corresponds to the older-style lexicographical ordering. 1688 The order returned must be consistent from one request to the next 1689 (i.e., interface 12 will always be returned before interface 5 in 1690 any future requests at any point in time where they are both to be 1691 returned), but the manner in which the ordering is accomplished is 1692 implementation specific. The cursor is used to indicate to the base 1693 Command Responder where the request should restart from. 1694 The first request: 1696 Get-Object-PDU { 1697 request-id 2 1698 option-field { } 1699 request-objects { { 1700 max-return-objects 1 -- only return 1 1701 skip-objects 0 -- starting with the first 1702 cursor "" -- 0 length for first request 1703 flags 0x00 -- none 1704 option-field {} 1706 request-base-object IF-MIB::ifTable 1708 -- get ifIndex, ifDescr, and ifType and 1709 -- ifHCInOctets, ifHCOutOctets from the ifXTable 1710 request-element-list { element-number = 1, 1711 element-number = 2, 1712 element-number = 3, 1713 multiple-subelement = { 1714 element-specifier = ifXTable, 1715 element-list = { 1716 6, 10 1718 } 1719 } 1720 } 1722 search-criteria { match-type = 100, -- AND 1723 sub-criteria = { 1724 { 1725 match-type = 0, -- equals 1726 match-data = { 1727 which = 3, -- ifType 1728 what = 6 -- ethernetCsmacd 1729 } 1730 }, 1731 { 1732 -- greaterThanOrEqual 1733 match-type = 12, 1734 match-data = { 1735 which = 5, -- ifSpeed 1736 what = 10000000 1737 } 1738 } 1739 } } 1740 } } 1741 } 1743 The first response: 1745 Get-Object-Response-PDU { 1746 request-id 2 1747 option-field {} 1748 response-objects ::= { { 1749 error-information-list {} -- no Errors 1750 cursor "interface 12" 1751 response-flags 0x00 -- none 1752 option-field {} 1754 request-base-object IF-MIB::ifTable 1756 returned-data-list { { 1757 { which-element = 1, 1758 element-value = 12 }, 1759 { which-element = 2, 1760 element-value = "interface 12" }, 1761 { which-element = 3, 1762 element-value = 6 } 1763 { which-element = ifXTable 1764 element-value = { 1765 { which-element = 6, 1766 element-value = 12345 }, 1767 { which-element = 10, 1768 element-value = 12345 }, 1769 } 1770 } 1771 } } 1773 } } 1774 } 1776 The second request to obtain the more data: 1778 Get-Object-PDU { 1779 request-id 3 1780 option-field { } 1781 request-objects { { 1782 max-return-objects 1 -- only return 1 1783 skip-objects 0 -- functionally not used 1784 cursor "interface 12" -- continue 1785 flags 0x00 -- none 1786 option-field {} 1788 request-base-object IF-MIB::ifTable 1790 -- get ifIndex, ifDescr, and ifType and 1791 -- ifHCInOctets, ifHCOutOctets from the ifXTable 1792 request-element-list { element-number = 1, 1793 element-number = 2, 1794 element-number = 3, 1795 multiple-subelement = { 1796 element-specifier = ifXTable, 1797 element-list = { 1798 6, 10 1799 } 1800 } 1801 } 1803 search-criteria { match-type = 100, -- AND 1804 sub-criteria = { 1805 { 1806 match-type = 0, -- equals 1807 match-data = { 1808 which = 3, -- ifType 1809 what = 6 -- ethernetCsmacd 1810 } 1811 }, 1812 { 1813 -- greaterThanOrEqual 1814 match-type = 12, 1815 match-data = { 1816 which = 5, -- ifSpeed 1817 what = 10000000 1818 } 1819 } 1820 } } 1821 } } 1822 } 1824 The second response. The zero length cursor means there is no 1825 further information and no further requests are needed. 1826 Get-Object-Response-PDU { 1827 request-id 3 1828 option-field {} 1829 response-objects ::= { { 1830 error-information-list {} -- no Errors 1831 cursor "" -- has last object 1832 response-flags 0x00 -- none 1833 option-field {} 1835 request-base-object IF-MIB::ifTable 1837 returned-data-list { { 1838 { which-element = 1, 1839 element-value = 5 }, 1840 { which-element = 2, 1841 element-value = "interface 5" }, 1842 { which-element = 3, 1843 element-value = 6 } 1844 { which-element = ifXTable 1845 element-value = { 1846 { which-element = 6, 1847 element-value = 23456 }, 1848 { which-element = 10, 1849 element-value = 23456 }, 1850 } 1851 } 1852 } } 1854 } } 1855 } 1857 5.3. A Write-Object-PDU example 1859 The following is an example of a Write-Object-PDU request which will 1860 set the ifAdminStatus flag to "down" for all interfaces in the 1861 ifTable of type 'basicISDN'. Additionally, an acknowledgment is 1862 requested to verify that an Command Responder has started received 1863 the request. 1864 Write-Object-PDU { 1865 request-id 10 1866 write-flags 0x40 -- requestAcknowledgment 1867 option-field { } 1869 write-transactions { 1870 transaction-flags 0x00 -- none specified 1871 option-field { } 1873 transaction-data-list { 1874 modify-transaction { 1875 request-base-OID IF-MIB::ifTable 1876 modify-search-criteria { match-type = 0, -- equals 1877 match-data = { 1878 which = 3, -- ifType 1879 what = 20 -- basicISDN 1880 } 1881 } 1882 modify-data-list { { 1883 -- ifAdminStatus 1884 which-element 7 1885 element-value 2 -- down 1886 } } 1887 } 1888 } 1889 } } 1890 } 1892 First, the Command Responder will send an acknowledgment indicating 1893 the reception of the Write-Object-PDU. This is sent because the 1894 requestAcknowledgment flag was set in the write-flags field. 1895 Acknowledgment-PDU { 1896 request-id 10 1897 ack-flags 0x00 1898 option-field {} 1899 } 1901 The Write-Object-Response-PDU will indicate which interfaces were 1902 actually affected by the Write-Object-PDU (in this example the 4th 1903 and 2nd interfaces): 1904 Write-Object-Response-PDU { 1905 request-id 10 1906 write-flags 0x00 -- none 1907 option-field {} -- no options 1908 error-information-list {} -- no Errors 1909 write-transaction-results ::= { { 1910 transaction-flags 0x00 -- none 1911 option-field {} -- no options 1912 transaction-response-list ::= { 1913 modify-transaction ::= { 1914 request-base-OID IF-MIB::ifTable 1915 modify-data-list ::= { 1916 { which-element/index-number 1 -- ifIndex 1917 element-value 4 } -- 4th interface 1918 { which-element/index-number 1 -- ifIndex 1919 element-value 2 } -- 2nd interface 1920 } 1921 } 1922 } 1923 } } 1924 } 1926 5.4. A Get-Configuration-Object-PDU example 1928 The following shows how a Command Generator might request the 1929 current configuration of the SNMP-TARGET-MIB::snmpTargetAddrTable, 1930 and an example response from a Command Responder. 1931 Get-Configuration-Objects-PDU { 1932 request-id 30 1933 gcop-flags 0x00 1934 option-field { } 1935 request-objects { { 1936 request-flags 0x00 1937 option-field { } 1938 request-objects SNMP-TARGET-MIB::snmpTargetAddrTable 1939 } } 1940 } 1942 The following shows a possible response for the above request. 1943 Configuration-Objects-Response-PDU { 1944 request-id 30 1945 gcop-flags 0x00 1946 option-field { } 1947 config-results { { 1948 request-flags 0x00 1949 option-field { } 1950 error-information { } 1951 config-transactions { 1952 transaction-flags 0x60 -- needSuccess, needAll 1953 option-field { } 1954 transaction-data-list { 1955 -- deletes all existing rows 1956 delete-transaction { 1957 request-base-OID snmpTargetAddrTable 1958 delete-search-criteria { } -- all data! 1959 } 1960 -- creates a new row 1961 create-transaction { 1962 request-base-OID snmpTargetAddrTable 1963 create-data-list { 1964 -- snmpTargetAddrName 1965 { which-element/index-number 1 1966 element-value "localhost" } 1967 -- snmpTargetAddrTDomain 1968 { which-element/element-number 2 1969 element-value snmpUDPDomain } 1970 -- snmpTargetAddrTAddress 1971 { which-element/element-number 3 1972 element-value 0x7f00000100a2 } 1973 -- snmpTargetAddrTimeout 1974 { which-element/element-number 4 1975 element-value 5 } 1976 -- snmpTargetAddrRetryCount 1977 { which-element/element-number 5 1978 element-value 5 } 1979 -- snmpTargetAddrTagList 1980 { which-element/element-number 6 1981 element-value "mytag" } 1982 -- snmpTargetAddrParams 1983 { which-element/element-number 7 1984 element-value "myparam" } 1985 -- snmpTargetAddrStorageType 1986 { which-element/element-number 8 1987 element-value 3 } 1988 -- snmpTargetAddrRowStatus 1989 { which-element/element-number 9 1990 element-value 4 } 1991 } 1992 } 1993 } 1994 } 1995 } } 1996 } 1998 5.5. A Notification-Object-PDU example: IF-MIB::linkUp 2000 The following shows a standard linkUp notification sent using the 2001 new Notification-Object-PDU. 2002 Notification-Object-PDU { 2003 request-id 40 2004 notification-flags 0x40 -- requestAcknowledgment 2005 option-field {} 2006 notifications ::= { { 2007 notification-id IF-MIB::linkUP 2008 system-uptime 100 2009 notification-string "Interface 12 enabled at the console" 2010 notification-objects ::= { 2011 { which-element = IF-MIB::ifTable 2012 element-value = { 2013 { which-element = 1, -- ifIndex 2014 element-value = 12 }, -- #12 2015 { which-element = 7, -- ifAdminStatus 2016 element-value = 1 }, -- up 2017 { which-element = 8, -- ifOperStatus 2018 element-value = 1 } -- up 2019 } 2020 } 2021 } 2022 } } 2023 } 2025 The notification receiver would then respond with the following 2026 acknowledgment: 2027 Acknowledgment-PDU { 2028 request-id 40 2029 ack-flags 0x00 2030 option-field {} 2031 } 2033 6. References 2035 6.1. Normative References 2037 [1] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and S. 2038 Waldbusser, "Version 2 of the Protocol Operations for the Simple 2039 Network Management Protocol (SNMP)", RFC3416, December 2002. 2041 [2] Blumenthal, U. and B. Wijnen, "The User-Based Security Model (USM) 2042 for Version 3 of the Simple Network Management Protocol (SNMPv3)", 2043 STD 62, RFC 3414, December 2002. 2045 [3] Wijnen, B., Presuhn, R. and K. McCloghrie, "View-based Access 2046 Control Model (VACM) for the Simple Network Management Protocol 2047 (SNMP)", STD 62, RFC 3415, December 2002. 2049 [4] Levi, D., Meyer, P. and B. Stewart, "Simple Network Management 2050 Protocol (SNMP) Applications", STD 62, RFC 3413, December 2002. 2052 6.2. Informative References 2054 [5] Woodcock, D., "Operator Requirements of Infrastructure Management 2055 Methods", Internet Draft draft-ops-operator-req-mgmt-02.txt, 2056 expired August 2002. 2058 [6] Schoenwaelder, J., "Overview of the 2002 IAB Network Management 2059 Workshop", Internet Draft draft-iab-nm-workshop-00.txt, expires 2060 April 2003. 2062 [7] Hovey, R. and S. Bradner, "The Organizations Involved in the IETF 2063 Standards Process", BCP 11, RFC 2028, October 1996. 2065 7. Intellectual Property 2067 The IETF takes no position regarding the validity or scope of any 2068 intellectual property or other rights that might be claimed to 2069 pertain to the implementation or use of the technology described in 2070 this document or the extent to which any license under such rights 2071 might or might not be available; neither does it represent that it 2072 has made any effort to identify any such rights. Information on the 2073 IETF's procedures with respect to rights in standards-track and 2074 standards-related documentation can be found in BCP-11 [7]. Copies 2075 of claims of rights made available for publication and any 2076 assurances of licenses to be made available, or the result of an 2077 attempt made to obtain a general license or permission for the use 2078 of such proprietary rights by implementors or users of this 2079 specification can be obtained from the IETF Secretariat. 2081 The IETF invites any interested party to bring to its attention any 2082 copyrights, patents or patent applications, or other proprietary 2083 rights which may cover technology that may be required to practice 2084 this standard. Please address the information to the IETF Executive 2085 Director. 2087 8. Security Considerations 2089 XXX: discuss VACM 2091 The protocol defined in this document by itself does not provide a 2092 secure environment. Even if the network itself is secure (for 2093 example by using IPSec), there is no control as to who on the secure 2094 network is allowed access to management information. 2096 It is recommended that the implementors consider the security 2097 features as provided by the SNMPv3 framework. Specifically, the use 2098 of the User-based Security Model STD 62, RFC 3414 [2] and the View- 2099 based Access Control Model STD 62, RFC 3415 [3] is recommended. 2101 It is then a customer/user responsibility to ensure that the SNMP 2102 entity is properly configured so that: 2104 - only those principals (users) having legitimate rights can 2105 access or modify the values of any MIB objects supported by 2106 that entity; 2108 - the occurrence of particular events on the entity will be 2109 communicated appropriately; 2111 - the entity responds appropriately and with due credence to 2112 events and information that have been communicated to it. 2114 9. IANA Considerations 2116 IANA will need to administer assignment rights for the following 2117 field identifiers within the PDUs defined in this document: 2119 option-field OPTIONAL tags 2120 The BER encoded OPTIONAL-field tags for the various *-option-field 2121 PDU components will need to be assigned and administered by IANA. 2123 XXX Some more XXX. 2125 10. Acknowledgements 2127 Many people participated in various discussions about the PDUs 2128 defined in this document. Special thanks go to: 2129 Michael Baer (Network Associates Laboratories) 2130 Robert Moore (IBM) 2131 David Perkins (Riverstone Networks and SNMPinfo) 2132 Randy Presuhn (BMC Software) 2133 Dave Shield (University of Liverpool) 2134 Steve Waldbusser (Next Beacon) 2135 Glenn Waters (Nortel Networks) 2137 11. Editor's Addresses 2139 Wes Hardaker 2140 P.O. Box 382 2141 Davis, California 95617 2142 USA 2143 Email: hardaker@tislabs.com 2145 12. Full Copyright Statement 2147 Copyright (C) The Internet Society (2003). All Rights Reserved. 2149 This document and translations of it may be copied and furnished to 2150 others, and derivative works that comment on or otherwise explain it 2151 or assist in its implementation may be prepared, copied, published 2152 and distributed, in whole or in part, without restriction of any 2153 kind, provided that the above copyright notice and this paragraph 2154 are included on all such copies and derivative works. However, this 2155 document itself may not be modified in any way, such as by removing 2156 the copyright notice or references to the Internet Society or other 2157 Internet organizations, except as needed for the purpose of 2158 developing Internet standards in which case the procedures for 2159 copyrights defined in the Internet Standards process must be 2160 followed, or as required to translate it into languages other than 2161 English. 2163 The limited permissions granted above are perpetual and will not be 2164 revoked by the Internet Society or its successors or assigns. 2166 This document and the information contained herein is provided on an 2167 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 2168 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 2169 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 2170 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 2171 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.