idnits 2.17.1 draft-ietf-rap-sppi-04.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. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == 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 an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. ** 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 1428: '..., the conversion SHOULD provide a conf...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1763 has weird spacing: '...Example usage...' -- 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 (22 January 2001) is 8489 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: 'APPLICATION 7' is mentioned on line 149, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 149, but not defined == Missing Reference: 'APPLICATION 11' is mentioned on line 370, but not defined == Missing Reference: 'APPLICATION 0' is mentioned on line 347, but not defined == Missing Reference: 'APPLICATION 2' is mentioned on line 352, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 357, but not defined == Missing Reference: 'APPLICATION 10' is mentioned on line 366, but not defined -- No information found for draft-ietf-rap-cops-pr - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'COPS-PR' ** Obsolete normative reference: RFC 2573 (ref. 'APPL') (Obsoleted by RFC 3413) -- Possible downref: Non-RFC (?) normative reference: ref. 'ASN1' Summary: 9 errors (**), 0 flaws (~~), 10 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group K. McCloghrie 2 Internet Draft M. Fine 3 Cisco Systems 4 J. Seligson 5 K. Chan 6 Nortel Networks 7 S. Hahn 8 R. Sahita 9 Intel 10 A. Smith 11 Allegro Networks 12 F. Reichmeyer 13 PFN 15 22 January 2001 17 Structure of Policy Provisioning Information (SPPI) 19 draft-ietf-rap-sppi-04.txt 21 Status of this Memo 23 This document is an Internet-Draft and is in full conformance with all 24 provisions of Section 10 of RFC2026. Internet-Drafts are working 25 documents of the Internet Engineering Task Force (IETF), its areas, and 26 its working groups. Note that other groups may also distribute working 27 documents as Internet-Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference material 32 or to cite them other than as ``work in progress.'' 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 Copyright Notice 42 Copyright (C) The Internet Society (2000). All Rights Reserved. 44 Draft SPPI January 2001 46 1. Introduction 48 RFC 2748 [COPS] defines the COPS protocol, and RFC 2749 [COPS-RSVP] 49 describes how the COPS protocol is used to provide for the outsourcing 50 of policy decisions for RSVP. Another usage of the COPS protocol, for 51 the provisioning of policy, is introduced in [COPS-PR]. In this 52 provisioning model, the policy information is viewed as a collection of 53 Provisioning Classes (PRCs) and Provisioning Instances (PRIs) residing 54 in a virtual information store, termed the Policy Information Base 55 (PIB). Collections of related Provisioning Classes are defined in a PIB 56 module. PIB modules are written using an adapted subset of SNMP's 57 Structure of Management Information (SMI) [SMI, TC, CONF]. It is the 58 purpose of this document, the Structure of Policy Provisioning 59 Information (SPPI), to define that adapted subset. 61 1.1. Change Log 63 This log to be removed as and when this draft is published as an RFC. 65 1.1.1. Changes made in version published on 13 July 2000 67 - included definition of the TEXTUAL-CONVENTION macro in the SPPI's 68 ASN.1 module so that TC's in PIBs can use data types not present in the 69 SMI. 71 - renamed the CLIENT-TYPES clause to be the SUBJECT-CATEGORIES clause in 72 order to be more generic. 74 - renamed the POLICY-ACCESS clause to be the PIB-ACCESS clause for 75 consistency. Added an extra parameter on the PIB-ACCESS clause for use 76 as the sub-identifier for a RowStatus column when converting to a MIB. 78 - added new clauses: EXTENDS, PIB-INDEX, PIB-REFERENCES, PIB-TAG, and 79 PIB-MODULES. 81 - renamed the MIN-ACCESS clause to be the PIB-MIN-ACCESS clause. 83 - created a new PIB module to contain the TC's defined in the SPPI. 85 - defined new TC's: Prid, PolicyTagId, PolicyTagReference. 87 - added Appendix with example usage of PIB-REFERENCES and PIB-TAG. 89 - added detail on carrying an INSTALL-ERROR in COPS-PR messages. 91 Draft SPPI January 2001 93 1.1.2. Changes made in version published on 20 September 2000 95 - copied (unmodified) the definitions of the OBJECT-IDENTITY and OBJECT- 96 GROUP macros into this document. 98 - changed syntax of PolicyTagId and PolicyTagReference to Unsigned32. 100 - changed the PolicyXxx TC names to remove "Policy" and be more 101 consistent, i.e., PolicyTagId, PolicyReferenceId and PolicyTagReference 102 to TagId, ReferenceId and TagReferenceId. 104 - made the UNIQUENESS clause optional, but recommended wherever it 105 provides useful information. 107 - changed usage of the PIB-INDEX and INDEX clauses to be more 108 consistent: a PIB-INDEX clause is now always required, and always has 109 the same meaning. The INDEX clause is now optional, and is only used 110 for the algorithmic conversion to a MIB. 112 - changed default OID value for an added RowStatus column to be 127. 114 - removed the PIB-MODULES clause. 116 - changed the meaning of PRC to be Provisioning Class, and of PRI to be 117 Provisioning Instance. 119 - required the algorithmic conversion to a MIB to have a configurable 120 option with respect to how Integer64 and Unsigned64 are mapped to the 121 SMI. 123 - specified that a PIB module's SUBJECT-CATEGORIES clause is not 124 exclusive. That is, some other specification might (e.g., at a future 125 date) specify additional COPS Client Types to which the PIB module is 126 relevant. 128 - updated the Reserved Keywords. 130 - copied the definitions of IpAddress, Unsigned32, TimeTicks from the 131 SMI into COPS-PR-SPPI, and clarified that PIB modules must import each 132 base data type that it uses from COPS-PR-SPPI, and may import, from the 133 SMI, (subtree) OIDs for the purpose of defining new OIDs. 135 - various typos. 137 Draft SPPI January 2001 139 1.1.3. Changes made in version published on 13 November 2000 141 - clarified definition of PIB-REFERENCES. 143 - added "report-only" as a value of PIB-ACCESS. 145 1.1.4. Changes made in version published 22 January 2000 147 - Converted PIB-REFERENCE to PIB-REFERENCES 149 - Changed [APPLICATION 7] and [APPLICATION 8] references to [APPLICATION 150 10] and [APPLICATION 11]. 152 Draft SPPI January 2001 154 2. Use of the SMI 156 The SPPI and PIB modules are based on SNMP's SMI and MIB modules, which 157 use an adapted subset of the ASN.1 data definition language [ASN1]. The 158 decision to base the definition of PIB modules on this format allows for 159 the leveraging of the community's knowledge, experience and tools of the 160 SMI and MIB modules. 162 2.1. Terminology Translation 164 The SMI uses the term "managed objects" to refer to object types, both 165 tabular types with descriptors such as xxxTable and xxxEntry, as well as 166 scalar and columnar object types. The SPPI does not use the term 167 "object" so as to avoid confusion with COPS protocol objects. Instead, 168 the SPPI uses the term Provisioning Class (PRC) for the table and row 169 definitions (the xxxTable and xxxEntry objects, respectively), and 170 Provisioning Instance (PRI) for an instantiation of a row definition. 171 For a columnar object of a table definition, the SPPI uses the term 172 "attribute" of a Provisioning Class. (The SPPI does not support the 173 equivalent of the SMI's scalar objects.) 175 2.2. Overview 177 SNMP's SMI is divided into five parts: module definitions, object 178 definitions, notification definitions [SMI], textual convention 179 definitions [TC] and conformance definitions [CONF]. 181 - The SMI's MODULE-IDENTITY macro is used to convey the semantics of 182 a MIB module. The SPPI uses this macro to convey the semantics of 183 a PIB module. 185 - The SMI's OBJECT-TYPE macro is used to convey the syntax and 186 semantics of managed objects. The SPPI uses this macro to convey 187 the syntax and semantics of PRCs and their attributes. 189 - The SMI's notification definitions are not used (at this time) by 190 the SPPI. (Note that the use of the keyword 'notify' in the SPPI 191 is not related to the SMI's notifications). 193 - The SMI's TEXTUAL CONVENTION macro allows new data types to be 194 defined. The SPPI uses this macro to define new data types having 195 particular syntax and semantics which is common to several 196 attributes of one of more PRCs. 198 Draft SPPI January 2001 200 - The SMI's conformance definitions define several macros: the 201 OBJECT-GROUP macro, the NOTIFICATION-GROUP macro, the MODULE- 202 COMPLIANCE macro and the AGENT-CAPABILITIES macro. The SPPI uses 203 the OBJECT-GROUP and MODULE-COMPLIANCE macros to specify acceptable 204 lower-bounds of implementation of the attributes of PRCs, and 205 thereby indirectly, acceptable lower-bounds of implementation of 206 the PRCs themselves. The NOTIFICATION-GROUP macro is not used (at 207 this time) by the SPPI. Potential usage by the SPPI of the AGENT- 208 CAPABILITIES macro is for further study. 210 3. Structure of this Specification 212 The SMI is specified in terms of an ASN.1 definition together with 213 descriptive text for each element introduced in that ASN.1 definition. 214 This document specifies the SPPI also via a ASN.1 definition, which is a 215 modified version of the SMI's definition, together with descriptive text 216 for only those elements in the SPPI's ASN.1 definition which have 217 differences from the SMI's. For elements in the ASN.1 definition which 218 have no descriptive text in this specification, the reader is referred 219 to the SMI's descriptive text for that element. 221 Draft SPPI January 2001 223 4. Definitions 225 COPS-PR-SPPI DEFINITIONS ::= BEGIN 227 IMPORTS ObjectName, SimpleSyntax, ExtUTCTime 228 FROM SNMPv2-SMI; 230 -- definitions for PIB modules 232 MODULE-IDENTITY MACRO ::= 233 BEGIN 234 TYPE NOTATION ::= 235 SubjectPart -- new 236 "LAST-UPDATED" value(Update ExtUTCTime) 237 "ORGANIZATION" Text 238 "CONTACT-INFO" Text 239 "DESCRIPTION" Text 240 RevisionPart 242 VALUE NOTATION ::= 243 value(VALUE OBJECT IDENTIFIER) 245 SubjectPart ::= -- new 246 "SUBJECT-CATEGORIES" "{" Categories "}" 247 Categories ::= -- new 248 CategoryIDs 249 | "all" 250 CategoryIDs ::= -- new 251 CategoryID 252 | CategoryIDs "," CategoryID 253 CategoryID ::= -- new 254 identifier "(" number ")" -- number is positive 256 RevisionPart ::= 257 Revisions 258 | empty 259 Revisions ::= 260 Revision 261 | Revisions Revision 262 Revision ::= 263 "REVISION" value(Update ExtUTCTime) 264 "DESCRIPTION" Text 266 Draft SPPI January 2001 268 -- a character string as defined in [SMI] 269 Text ::= value(IA5String) 270 END 272 -- 274 OBJECT-IDENTITY MACRO ::= 275 BEGIN 276 TYPE NOTATION ::= 277 "STATUS" Status 278 "DESCRIPTION" Text 279 ReferPart 281 VALUE NOTATION ::= 282 value(VALUE OBJECT IDENTIFIER) 284 Status ::= 285 "current" 286 | "deprecated" 287 | "obsolete" 289 ReferPart ::= 290 "REFERENCE" Text 291 | empty 293 -- a character string as defined in [SMI] 294 Text ::= value(IA5String) 295 END 297 -- syntax of attributes 299 -- the "base types" defined here are: 300 -- 3 built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER 301 -- 6 application-defined types: Integer32, IpAddress, Unsigned32, 302 -- TimeTicks, Integer64 and Unsigned64 304 ObjectSyntax ::= 305 CHOICE { 306 simple 307 SimpleSyntax, 309 -- note that SEQUENCEs for table and row definitions 310 -- are not mentioned here... 312 Draft SPPI January 2001 314 application-wide 315 ApplicationSyntax 316 } 318 -- application-wide types 320 ApplicationSyntax ::= 321 CHOICE { 322 ipAddress-value 323 IpAddress, 325 timeticks-value 326 TimeTicks, 328 unsigned-integer-value 329 Unsigned32, 331 large-integer-value -- new 332 Integer64, 334 large-unsigned-integer-value -- new 335 Unsigned64 336 } 338 -- the following 4 types are copied from the SMI 340 -- indistinguishable from INTEGER, but never needs more than 341 -- 32-bits for a two's complement representation 342 Integer32 ::= 343 INTEGER (-2147483648..2147483647) 345 -- (this is a tagged type for historical reasons) 346 IpAddress ::= 347 [APPLICATION 0] 348 IMPLICIT OCTET STRING (SIZE (4)) 350 -- an unsigned 32-bit quantity 351 Unsigned32 ::= 352 [APPLICATION 2] 353 IMPLICIT INTEGER (0..4294967295) 355 -- hundredths of seconds since an epoch 356 TimeTicks ::= 357 [APPLICATION 3] 359 Draft SPPI January 2001 361 IMPLICIT INTEGER (0..4294967295) 363 -- the following 2 types are not present in the SMI 365 Integer64 ::= 366 [APPLICATION 10] 367 IMPLICIT INTEGER (-9223372036854775808..9223372036854775807) 369 Unsigned64 370 [APPLICATION 11] 371 IMPLICIT INTEGER (0..18446744073709551615) 373 -- definition for Provisioning Classes and their attributes 374 -- (differences from the SMI are noted in the ASN.1 comments) 376 OBJECT-TYPE MACRO ::= 377 BEGIN 378 TYPE NOTATION ::= 379 "SYNTAX" Syntax 380 UnitsPart 381 "PIB-ACCESS" AccessPart -- modified 382 PibReferencesPart -- new 383 PibTagPart -- new 384 "STATUS" Status 385 "DESCRIPTION" Text 386 ErrorsPart -- new 387 ReferPart 388 IndexPart -- modified 389 MibIndexPart -- modified 390 UniquePart -- new 391 DefValPart 393 VALUE NOTATION ::= 394 value(VALUE ObjectName) 396 Syntax ::= -- Must be one of the following: 397 -- a base type (or its refinement), 398 -- a textual convention (or its refinement), or 399 -- a BITS pseudo-type 400 type 401 | "BITS" "{" NamedBits "}" 403 NamedBits ::= NamedBit 404 | NamedBits "," NamedBit 406 Draft SPPI January 2001 408 NamedBit ::= identifier "(" number ")" -- number is nonnegative 410 UnitsPart ::= 411 "UNITS" Text 412 | empty 414 AccessPart ::= -- new 415 Access 416 | Access "," number -- number is positive 418 Access ::= -- modified 419 "install" 420 | "notify" 421 | "install-notify" 422 | "report-only" 424 Status ::= 425 "current" 426 | "deprecated" 427 | "obsolete" 429 ErrorsPart ::= -- new 430 "INSTALL-ERRORS" "{" Errors "}" 431 | empty 433 Errors ::= -- new 434 Error 435 | Errors "," Error 436 Error ::= -- new 437 identifier "(" number ")" -- number is positive 439 ReferPart ::= 440 "REFERENCE" Text 441 | empty 443 IndexPart ::= 444 "PIB-INDEX" "{" Index "}" -- new 445 | "AUGMENTS" "{" Entry "}" 446 | "EXTENDS" "{" Entry "}" -- new 447 | empty 448 Index ::= 449 -- the correspondent OBJECT-TYPE invocation 450 value(ObjectName) 451 Entry ::= 452 -- use the INDEX value of the 454 Draft SPPI January 2001 456 -- correspondent OBJECT-TYPE invocation 457 value(ObjectName) 458 MibIndexPart ::= 459 "INDEX" "{" IndexTypePart "}" 460 | empty 461 IndexTypePart ::= 462 IndexTypes 463 | IndexTypes "," ImpliedIndex 464 | ImpliedIndex 465 IndexTypes ::= 466 Index 467 | IndexTypes "," Index 468 ImpliedIndex ::= 469 "IMPLIED" Index 471 PibReferencesPart ::= 472 -- for use with ReferenceId TC 473 "PIB-REFERENCES" "{" Entry "}" 474 | empty 476 PibTagPart ::= 477 -- for use with TagReferenceId TC 478 "PIB-TAG" "{" Attr "}" 479 | empty 481 Attr ::= -- specifies an attribute 482 value(ObjectName) 484 UniquePart ::= -- new 485 "UNIQUENESS" "{" UniqueTypes "}" 486 | "UNIQUENESS" "{" "}" 487 | empty 488 UniqueTypes ::= 489 UniqueType 490 | UniqueTypes "," UniqueType 491 UniqueType ::= 492 -- the correspondent OBJECT-TYPE invocation 493 value(ObjectName) 495 DefValPart ::= "DEFVAL" "{" Defvalue "}" 496 | empty 498 Defvalue ::= -- must be valid for the type specified in 499 -- SYNTAX clause of same OBJECT-TYPE macro 501 Draft SPPI January 2001 503 value(ObjectSyntax) 504 | "{" BitsValue "}" 506 BitsValue ::= BitNames 507 | empty 509 BitNames ::= BitName 510 | BitNames "," BitName 512 BitName ::= identifier 514 -- a character string as defined in [SMI] 515 Text ::= value(IA5String) 516 END 518 -- definitions for conformance groups 520 OBJECT-GROUP MACRO ::= 521 BEGIN 522 TYPE NOTATION ::= 523 ObjectsPart 524 "STATUS" Status 525 "DESCRIPTION" Text 526 ReferPart 528 VALUE NOTATION ::= 529 value(VALUE OBJECT IDENTIFIER) 531 ObjectsPart ::= 532 "OBJECTS" "{" Objects "}" 533 Objects ::= 534 Object 535 | Objects "," Object 536 Object ::= 537 value(ObjectName) 539 Status ::= 540 "current" 541 | "deprecated" 542 | "obsolete" 544 ReferPart ::= 545 "REFERENCE" Text 546 | empty 548 Draft SPPI January 2001 550 -- a character string as defined in [SMI] 551 Text ::= value(IA5String) 552 END 554 -- definitions for compliance statements 556 MODULE-COMPLIANCE MACRO ::= 557 BEGIN 558 TYPE NOTATION ::= 559 "STATUS" Status 560 "DESCRIPTION" Text 561 ReferPart 562 ModulePart 564 VALUE NOTATION ::= 565 value(VALUE OBJECT IDENTIFIER) 567 Status ::= 568 "current" 569 | "deprecated" 570 | "obsolete" 572 ReferPart ::= 573 "REFERENCE" Text 574 | empty 576 ModulePart ::= 577 Modules 578 Modules ::= 579 Module 580 | Modules Module 581 Module ::= 582 -- name of module -- 583 "MODULE" ModuleName 584 MandatoryPart 585 CompliancePart 587 ModuleName ::= 588 -- identifier must start with uppercase letter 589 identifier ModuleIdentifier 590 -- must not be empty unless contained 591 -- in MIB Module 592 | empty 593 ModuleIdentifier ::= 595 Draft SPPI January 2001 597 value(OBJECT IDENTIFIER) 598 | empty 600 MandatoryPart ::= 601 "MANDATORY-GROUPS" "{" Groups "}" 602 | empty 604 Groups ::= 605 Group 606 | Groups "," Group 607 Group ::= 608 value(OBJECT IDENTIFIER) 610 CompliancePart ::= 611 Compliances 612 | empty 614 Compliances ::= 615 Compliance 616 | Compliances Compliance 617 Compliance ::= 618 ComplianceGroup 619 | Object 621 ComplianceGroup ::= 622 "GROUP" value(OBJECT IDENTIFIER) 623 "DESCRIPTION" Text 625 Object ::= 626 "OBJECT" value(ObjectName) 627 InstallSyntaxPart -- modified 628 AccessPart 629 "DESCRIPTION" Text 631 -- must be a refinement for object's SYNTAX clause 632 InstallSyntaxPart ::= "SYNTAX" Syntax 633 | empty 635 Syntax ::= -- Must be one of the following: 636 -- a base type (or its refinement), 637 -- a textual convention (or its refinement), or 638 -- a BITS pseudo-type 639 type 640 | "BITS" "{" NamedBits "}" 642 Draft SPPI January 2001 644 NamedBits ::= NamedBit 645 | NamedBits "," NamedBit 647 NamedBit ::= identifier "(" number ")" -- number is nonnegative 649 AccessPart ::= 650 "PIB-MIN-ACCESS" Access -- modified 651 | empty 652 Access ::= -- modified 653 "not-accessible" 654 | "install" 655 | "notify" 656 | "install-notify" 658 -- a character string as defined in [SMI] 659 Text ::= value(IA5String) 660 END 662 -- definition of textual conventions 664 TEXTUAL-CONVENTION MACRO ::= 665 BEGIN 666 TYPE NOTATION ::= 667 DisplayPart 668 "STATUS" Status 669 "DESCRIPTION" Text 670 ReferPart 671 "SYNTAX" Syntax 673 VALUE NOTATION ::= 674 value(VALUE Syntax) -- adapted ASN.1 676 DisplayPart ::= 677 "DISPLAY-HINT" Text 678 | empty 680 Status ::= 681 "current" 682 | "deprecated" 683 | "obsolete" 685 ReferPart ::= 686 "REFERENCE" Text 687 | empty 689 Draft SPPI January 2001 691 -- a character string as defined in [SMI] 692 Text ::= value(IA5String) 694 Syntax ::= -- Must be one of the following: 695 -- a base type (or its refinement), or 696 -- a BITS pseudo-type 697 type 698 | "BITS" "{" NamedBits "}" 700 NamedBits ::= NamedBit 701 | NamedBits "," NamedBit 703 NamedBit ::= identifier "(" number ")" -- number is nonnegative 705 END 707 END 708 Draft SPPI January 2001 710 COPS-PR-SPPI-TC PIB-DEFINITIONS ::= BEGIN 712 IMPORTS Unsigned32, MODULE-IDENTITY, TEXTUAL-CONVENTION 713 FROM COPS-PR-SPPI; 715 copsPrSppiTc MODULE-IDENTITY 716 SUBJECT-CATEGORIES { all } 717 LAST-UPDATED "200009201800Z" 718 ORGANIZATION "IETF RAP WG" 719 CONTACT-INFO "Keith McCloghrie 720 Cisco Systems, Inc. 721 170 West Tasman Drive, 722 San Jose, CA 95134-1706 USA 723 Phone: +1 408 526 5260 724 Email: kzm@cisco.com 726 Ravi Sahita 727 Intel 728 2111 NE 25th Avenue 729 Hillsboro, OR 97124 USA 730 Phone: +1 503 712 1554 731 Email: ravi.sahita@intel.com " 732 DESCRIPTION 733 "The PIB module containing a set of Textual Conventions 734 which have general applicability to all PIB modules." 735 REVISION "200009201800Z" 736 DESCRIPTION 737 "Initial version, published in RFC xxxx." 738 ::= { tbd } 740 InstanceId ::= TEXTUAL-CONVENTION 741 STATUS current 742 DESCRIPTION 743 "The textual convention for use by an attribute which is used 744 as the instance-identifying index of a PRC, i.e., an attribute 745 named in a PIB-INDEX clause. The value of an attribute with this 746 syntax is always greater than zero. PRIs of the same PRC need 747 not have contiguous values for their instance-identifying 748 attribute." 749 SYNTAX Unsigned32 (1..4294967295) 751 ReferenceId ::= TEXTUAL-CONVENTION 752 STATUS current 753 DESCRIPTION 754 "A textual convention for use by an attribute which is used as 756 Draft SPPI January 2001 758 a pointer in order to reference an instance of a particular 759 PRC. An attribute with this syntax must not be used in a 760 PIB-INDEX clause , and its description must specify the 761 particular PRC to which the referenced PRI will belong. 762 For an attribute of this type, the referenced PRI must exist. 763 Furthermore, it is an error to try to delete a PRI that is 764 referenced by another instance without first deleting/modifying 765 the referencing instance. The definition of an attribute with 766 this syntax can permit the attribute to have a value of zero to 767 indicate that it is not currently pointing to an PRI." 768 SYNTAX Unsigned32 770 Prid ::= TEXTUAL-CONVENTION 771 STATUS current 772 DESCRIPTION 773 "Represents a pointer to a PRI, i.e,. to an instance of a 774 PRC. The value is the OID name of the PRC's row definition, 775 appended with one sub-identifier containing the value of the 776 InstanceId value for the referenced instance. The definition 777 of an attribute with this syntax can permit the attribute to 778 have a value of 0.0 to indicate that it is not currently 779 pointing to a PRI." 780 SYNTAX OBJECT IDENTIFIER 782 TagId ::= TEXTUAL-CONVENTION 783 STATUS current 784 DESCRIPTION 785 "Represents a tag value, such that all instances of a 786 particular PRC having the same tag value form a tag list. 787 A tag list is identified by the tag value shared by all 788 instances in that tag list." 789 SYNTAX Unsigned32 (1..4294967295) 791 TagReferenceId ::= TEXTUAL-CONVENTION 792 STATUS current 793 DESCRIPTION 794 "Represents a reference to a tag list of instances of a 795 particular PRC. The particular PRC must have an attribute 796 with the syntax of TagId. The tag list consists of 797 all instances which have the same value of the TagId 798 attribute. Reference to the tag list is via the attribute 799 with the syntax of TagReferenceId containing the tag 800 value which identifies the tag list." 801 SYNTAX Unsigned32 802 END 803 Draft SPPI January 2001 805 5. PIB Modules 807 The names of all standard PIB modules must be unique (but different 808 versions of the same module should have the same name). Developers of 809 enterprise PIB modules are encouraged to choose names for their modules 810 that will have a low probability of colliding with standard or other 811 enterprise modules. 813 The first line of a PIB module is: 815 PIB-MODULE-NAME PIB-DEFINITIONS ::= BEGIN 817 where PIB-MODULE-NAME is the module name. 819 Like the SMI, additional ASN.1 macros must not be defined in PIB 820 modules. 822 5.1. Importing Definitions 824 Like the SMI, a PIB module which needs to reference an external 825 definition, must use the IMPORTS statement to identify both the 826 descriptor and the module in which the descriptor is defined, where a 827 module is identified by its ASN.1 module name. 829 In particular, a PIB module imports each of the base data types that it 830 uses from COPS-PR-SPPI (defined in this document), and may import as 831 required from other PIB modules. A PIB module may import, from the SMI, 832 (subtree) OIDs for the purpose of defining new OIDs. A PIB module may 833 also import, from MIB modules, OID assignments as well as textual 834 convention definitions providing that their underlying syntax is 835 supported by the SPPI. However, the following must not be included in 836 an IMPORTS statement: 838 - named types defined by ASN.1 itself, specifically: INTEGER, OCTET 839 STRING, OBJECT IDENTIFIER, SEQUENCE, SEQUENCE OF type, 840 - the BITS construct. 842 For each ASN.1 macro that a PIB uses, it must import that macro's 843 definition from the COPS-PR-SPPI. 845 5.2. Reserved Keywords 847 In addition to the reserved keywords listed in the SMI, the following 848 must not be used as descriptors or module names: 850 Draft SPPI January 2001 852 EXTENDS INSTALL-ERRORS Integer64 PIB-MIN-ACCESS PIB-ACCESS 853 PIB-INDEX PIB-REFERENCES PIB-TAG SUBJECT-CATEGORIES UNIQUENESS 854 Unsigned64 856 6. Naming Hierarchy 858 The SPPI uses the same OBJECT IDENTIFIER naming hierarchy as the SMI. 859 That is, OIDs are typically assigned to PIB modules from the subtree 860 administered by the Internet Assigned Numbers Authority (IANA). 861 However, like the SMI, the SPPI does not prohibit the definition of PRCs 862 in other portions of the OID tree. 864 7. Mapping of the MODULE-IDENTITY macro 866 7.1. Mapping of the SUBJECT-CATEGORIES clause 868 The SUBJECT-CATEGORIES clause, which must be present, identifies one or 869 more categories of provisioning data for which this PIB module defines 870 provisioning information. For use with the COPS-PR protocol, the 871 individual subject categories are mapped to COPS Client Types [COPS-PR]. 872 The subject categories are identified either: 874 - via the keyword "all", indicating the PIB module defines 875 provisioning information relevant for all subject categories (and 876 thus, all COPS Client Types), or 878 - a list of named-number enumerations, where each number which must 879 be greater than zero, identifies a subject category, and is mapped 880 to the Client Type which is identified by that same number in the 881 COPS protocol. The namespace for these named numbers is global and 882 therefore the labels should be assigned consistently across PIB 883 modules. At present time, no more than one named-number 884 enumeration should be specified. 886 Note that the list of categories specified in a PIB module's SUBJECT- 887 CATEGORIES clause is not exclusive. That is, some other specification 888 might (e.g., at a future date) specify additional COPS Client Types to 889 which the module is relevant. 891 When a PIB module applies to multiple subject categories, that PIB 892 module exists in multiple virtual information stores, one for each 893 Client-Type. 895 Draft SPPI January 2001 897 8. Mapping of the OBJECT-TYPE macro 899 The SPPI requires that all attribute definitions be contained within a 900 PRC, i.e., within a table definition. 902 8.1. Mapping of the SYNTAX clause 904 The SYNTAX clause, which must be present within the definition of an 905 attribute, defines the abstract data structure of that attribute. The 906 data structure must be one of the following: a base type, the BITS 907 construct, or a textual convention. 909 The SYNTAX clause must also be present for the table and row definitions 910 of a PRC, and in this case must be a SEQUENCE OF or SEQUENCE (see 911 section 8.1.7 below). 913 The base types are an extended subset of the SMI's base types: 915 - built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER, 917 - application-defined types: Integer32, IpAddress, Unsigned32, 918 TimeTicks, Integer64 and Unsigned64. 920 A textual convention is a newly-defined type defined as a sub-type of a 921 base type [TC]. The value of an attribute whose syntax is defined using 922 a textual convention is encoded "on-the-wire" according to the textual 923 convention's underlying base type. 925 Note that the set of base types has been chosen so as to provide 926 sufficient variety of on-the-wire encodings for attribute values; base 927 types should contain a minimum of semantics. Semantics should, to the 928 extent possible, be incorporated into a data type through the use of a 929 textual convention. Thus, the IpAddress and TimeTicks data types should 930 really be defined as textual conventions because they contain semantics. 931 However, they are defined here as base types so as to avoid confusion 932 with the SMI which defines them as base types. 934 The differences from the SMI in the semantics of ObjectSyntax are now 935 described. 937 8.1.1. Counter32 939 The Counter32 type is not supported by the SPPI. 941 Draft SPPI January 2001 943 8.1.2. Gauge32 945 The Gauge32 type is not supported by the SPPI. 947 8.1.3. Opaque 949 The Opaque type is not supported by the SPPI. 951 8.1.4. Counter64 953 The Counter64 type is not supported by the SPPI. 955 8.1.5. Integer64 957 The Integer64 type represents integer-valued information between -2^63 958 and 2^63-1 inclusive (-9223372036854775808 to 9223372036854775807 959 decimal). While Integer64 may be sub-typed to be more constrained, if 960 the constraint results in all possible values being contained in the 961 range (-2147483648..2147483647), then the Integer32 type must be used 962 instead of Integer64. 964 8.1.6. Unsigned64 966 The Unsigned64 type represents integer-valued information between 0 and 967 2^64-1 inclusive (0 to 18446744073709551615 decimal). While Unsigned64 968 may be sub-typed to be more constrained, if the constraint results in 969 all possible values being contained in the range (0..4294967295), then 970 the Unsigned32 type must be used instead of Unsigned64. 972 8.1.7. Provisioning Classes 974 The operations (on PIBs) supported by the SPPI apply exclusively to 975 PRCs. Each PRC is modelled as a tabular structure, i.e., a table. Each 976 instance of a particular PRC has the same set of attributes. The set of 977 attributes which belong to every instance of a particular PRC is 978 modelled as a row in the table. This model is formalized by using the 979 OBJECT-TYPE macro to define both: 981 - the PRC as a whole, called the table definition, and 983 - the characteristics of every instance of a particular PRC, called 984 the row definition. 986 In the table definition, the SYNTAX clause has the form: 988 Draft SPPI January 2001 990 SEQUENCE OF 992 where refers to the SEQUENCE type of its attribute 993 definitions. In the row definition, the SYNTAX clause has the form: 995 997 where is a SEQUENCE type defined as follows: 999 ::= SEQUENCE { , ... , } 1001 where there is one for each attribute, and each is of the 1002 form: 1004 1006 where is the descriptor naming an attribute, and 1007 has the value of that attribute's SYNTAX clause, except that both sub- 1008 typing information and the named values for enumerated integers or the 1009 named bits for the BITS construct, are omitted from . 1011 8.2. Mapping of the MAX-ACCESS clause 1013 The MAX-ACCESS clause is not supported by the SPPI. 1015 8.3. Mapping of the PIB-ACCESS clause 1017 The PIB-ACCESS clause must be present for a PRC's table definition, and 1018 must not be present for any other OBJECT-TYPE definition. The PIB- 1019 ACCESS clause defines what kind of access is appropriate for the PRC. 1020 The PIB-ACCESS clause also optionally (default value is 127) provides a 1021 number which is used in the algorithmic conversion of a PIB to a MIB 1022 (see Appendix A). 1024 - the value "install" is used to indicate a PRC which a PDP can 1025 install in the PEP as provisioning information. 1027 - the value "notify" is used to indicate a PRC for which the PEP must 1028 notify the PDP of all its instances and attribute values of that 1029 PRC. 1031 - the value "install-notify" is used to indicate the uncommon type of 1032 PRC which has both characteristics: "install" and "notify". 1034 Draft SPPI January 2001 1036 the value "report-only" is used to indicate a PRC which has neither the 1037 "install" characteristic nor the "notify" characteristic. However, 1038 instances of such a PRC may be included in synchronous/asynchronous 1039 reports generated by the PEP. (Note: PRCs having the "install" and/or 1040 "notify" characteristics may also be included in reports generated by 1041 the PEP.) 1043 8.4. Mapping of the INSTALL-ERRORS clause 1045 The INSTALL-ERRORS clause, which may optionally be present for a PRC's 1046 table definition, and must be absent otherwise, lists one or more 1047 potential reasons for rejecting an install or a removal of an instance 1048 of the PRC. Each reason consists of a named-number enumeration, where 1049 the number represents a PRC-specific error-code to be used in a COPS 1050 protocol message, as the Sub-Error Code, with the Error-Code set to 1051 priSpecificError (see [COPS-PR]). The semantics of each named-number 1052 enumeration should be described in the PRC's DESCRIPTION clause. 1054 The numbers listed in an INSTALL-ERRORS must be greater than zero and 1055 less than 65536. If this clause is not present, an install/remove can 1056 still fail, but no PRC-specific error is available to be reported. 1058 8.5. Mapping of the PIB-INDEX clause 1060 The PIB-INDEX clause, which must be present for a row definition (unless 1061 an AUGMENTS or an EXTENDS clause is present instead), and must be absent 1062 otherwise, defines identification information for instances of the PRC. 1064 The PIB-INDEX clause includes exactly one descriptor. This descriptor 1065 specifies an attribute (typically, but not necessarily of the same PRC) 1066 which is used to identify an instance of that PRC. The syntax of this 1067 attribute is required to be InstanceId (a textual convention with an 1068 underlying syntax of Unsigned32), and it has no semantics other than its 1069 use in identifying the PRC instance. The OBJECT IDENTIFIER which 1070 identifies an instance of a PRC is formed by appending one sub- 1071 identifier to the OID which identifies that PRC's row definition. The 1072 value of the additional sub-identifier is that instance's value of the 1073 attribute specified in the INDEX clause. 1075 Note that SPPI does not permit use of the IMPLIED keyword in a PIB-INDEX 1076 clause. 1078 Draft SPPI January 2001 1080 8.6. Mapping of the INDEX clause 1082 The INDEX clause is optionally present if a PIB-INDEX clause is present, 1083 and must be absent otherwise. If present, the INDEX clause can contain 1084 any number of attributes, and is used only by the algorithmic conversion 1085 of a PIB to a MIB (see Appendix A). 1087 An IMPLIED keyword can be present in an INDEX clause if so desired. 1089 8.7. Mapping of the AUGMENTS clause 1091 The AUGMENTS clause, which must not be present except in row 1092 definitions, is an alternative to the PIB-INDEX clause and the EXTENDS 1093 clause. Every row definition has exactly one of: a PIB-INDEX clause, an 1094 AUGMENTS clause, or an EXTENDS clause. 1096 A row definition which has a PIB-INDEX clause is called a base row 1097 definition. A row definition which has an AUGMENTS clause is called a 1098 row augmentation, where the AUGMENTS clause names the base row 1099 definition which is augmented by this row augmentation. (Thus, a row 1100 augmentation cannot itself be augmented.) 1102 A PRC whose row definition is a row augmentation is called an augmenting 1103 PRC. Instances of an augmenting PRC are identified according to the 1104 PIB-INDEX clause of the base row definition named in the AUGMENTS 1105 clause. Further, instances of an augmenting PRC exist according to the 1106 same semantics as instances of the PRC which it augments. As such, when 1107 an instance of a PRC is installed or removed, an instance of every PRC 1108 which augments it is also installed or removed (for more details, see 1109 [COPS-PR]). 1111 8.8. Mapping of the EXTENDS clause 1113 The EXTENDS clause, which must not be present except in row definitions, 1114 is an alternative to the PIB-INDEX clause and the AUGMENTS clause. 1115 Every row definition has exactly one of: a PIB-INDEX clause, an AUGMENTS 1116 clause, or an EXTENDS clause. 1118 A row definition which has an EXTENDS clause is called a sparse row 1119 augmentation, where the EXTENDS clause names the row definition which is 1120 sparsely-augmented by this sparse row augmentation. The sparsely- 1121 augmented row can be a base row definition, or another sparse row 1122 augmentation. 1124 Draft SPPI January 2001 1126 A PRC whose row definition is a sparse row augmentation is called a 1127 sparsely augmenting PRC. Instances of a sparsely augmenting PRC are 1128 identified according to the PIB-INDEX clause of the row definition named 1129 in the sparsely augmenting PRC's EXTENDS clause. 1131 An instance of a sparsely augmenting PRC can not exist unless a 1132 corresponding instance of the PRC which it sparsely augments exists. As 1133 such, when an instance of a PRC is removed, an instance of any PRC which 1134 sparsely augments it is also removed. However, an instance of a 1135 sparsely augmenting PRC need not exist when the corresponding instance 1136 of the PRC that it sparsely augments exists. Thus, an instance of a 1137 sparsely augmenting PRC can be installed at the same time as or 1138 subsequent to the installation of, and can be removed prior to the 1139 removal of, the corresponding instance of the PRC that it sparsely 1140 augments. So, instances of a sparsely augmenting PRC must be installed 1141 explicitly, but are removed either implicitly (via removal of the 1142 augmented PRI) or explicitly. 1144 8.8.1. Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1146 When defining instance identification information for a PRC: 1148 - If there is a one-to-one correspondence between instances of this 1149 PRC and instances of an existing PRC, then the AUGMENTS clause 1150 should be used. 1152 - Otherwise, if there is a sparse relationship between instances of 1153 this PRC and instances of an existing PRC, then an EXTENDS clause 1154 should be used. 1156 - Otherwise, a PIB-INDEX clause should be used which names its own 1157 InstanceId attribute. 1159 8.9. Mapping of the UNIQUENESS clause 1161 The UNIQUENESS clause, which is optionally present for any row 1162 definition which has a PIB-INDEX clause, and must be absent otherwise, 1163 lists a set of zero or more of the PRC's attributes, for which no two 1164 instances of the PRC can have the same set of values. The specified set 1165 of attributes provide a necessary and sufficient set of values by which 1166 to identify an instance of this PRC. The attribute contained in the 1167 PIB-INDEX clause may not be present in the UNIQUENESS clause. By 1168 definition, an attribute may not appear more than once in a UNIQUENESS 1169 clause. A UNIQUENESS clause containing zero attributes indicates that 1170 Draft SPPI January 2001 1172 it's possible for two instances of the PRC to have identical values for 1173 all attributes except, of course, for the one named in the PIB-INDEX 1174 clause. 1176 Even though the UNIQUENESS clause is optional, its inclusion is 1177 recommended wherever it provides useful information. 1179 8.10. Mapping of the PIB-REFERENCES clause 1181 The PIB-REFERENCES clause, which must be present for any attribute which 1182 has the SYNTAX of ReferenceId, and must be absent otherwise, names the 1183 PRC, an instance of which is referenced by the ReferenceId attribute. 1184 For example usages of the PIB-REFERENCES clause, see Appendix B. 1186 8.11. Mapping of the PIB-TAG clause 1188 The PIB-TAG clause, which must be present for an attribute which has the 1189 SYNTAX TagReferenceId, and must be absent otherwise, is used to indicate 1190 that this attribute references a "tag list" of instances of another PRC. 1191 Such a tag list (similar in concept to the usage of the same term in 1192 [APPL]) is formed by all instances of the other PRC which have the same 1193 (tag) value of a particular attribute of that other PRC. The particular 1194 attribute of the other PRC, which must have the SYNTAX TagId, is named 1195 in the PIB-TAG clause. For an example usage of the PIB-TAG clause, see 1196 Appendix B. 1198 9. Mapping of the OBJECT-IDENTITY macro 1200 The OBJECT-IDENTITY macro is used in PIB modules to define information 1201 about an OBJECT IDENTIFIER assignment. 1203 Draft SPPI January 2001 1205 10. Mapping of the OBJECT-GROUP macro 1207 For conformance purposes, it is useful to define a conformance group as 1208 a collection of related PRCs and their attributes. The OBJECT-GROUP 1209 macro (directly) defines the collection of attributes which belong to a 1210 conformance group. Since each attribute included in the collection 1211 belongs to a PRC, the collection of related PRCs which belong to a 1212 conformance group is also specified (indirectly) as the set of PRCs to 1213 which the included attributes belong. 1215 10.1. Mapping of the OBJECTS clause 1217 The OBJECTS clause, which must be present, is used to specify each 1218 attribute contained in the conformance group. Each of the specified 1219 attributes must be defined in the same PIB module as the OBJECT-GROUP 1220 macro appears. 1222 It is required that every attribute defined in a PIB module be contained 1223 in at least one conformance group. This avoids the common error of 1224 adding a new attribute to a module and forgetting to add the new 1225 attribute to a group. 1227 11. Mapping of the MODULE-COMPLIANCE macro 1229 The MODULE-COMPLIANCE macro is used to convey a minimum set of 1230 requirements with respect to implementation of one or more PIB modules. 1232 A requirement on all "standard" PIB modules is that a corresponding 1233 MODULE-COMPLIANCE specification is also defined, either in the same 1234 module or in a companion module. 1236 11.1. Mapping of the MODULE clause 1238 The MODULE clause, which must be present, is repeatedly used to name 1239 each PIB module for which compliance requirements are being specified. 1240 Each PIB module is named by its module name, and optionally, by its 1241 associated OBJECT IDENTIFIER as well. The module name can be omitted 1242 when the MODULE-COMPLIANCE invocation occurs inside a PIB module, to 1243 refer to the encompassing PIB module. 1245 11.1.1. Mapping of the MANDATORY-GROUPS clause 1247 The MANDATORY-GROUPS clause, which need not be present, names the one or 1248 more conformance groups within the correspondent PIB module which are 1249 Draft SPPI January 2001 1251 unconditionally mandatory for implementation. If an agent claims 1252 compliance to the PIB module, then it must implement each and every 1253 attribute (and therefore the PRCs to which they belong) within each 1254 conformance group listed. 1256 11.1.2. Mapping of the GROUP clause 1258 The GROUP clause, which need not be present, is repeatedly used to name 1259 each conformance group which is conditionally mandatory for compliance 1260 to the PIB module. The GROUP clause can also be used to name 1261 unconditionally optional groups. A group named in a GROUP clause must 1262 be absent from the correspondent MANDATORY-GROUPS clause. 1264 Conditionally mandatory groups include those which are mandatory only if 1265 a particular protocol is implemented, or only if another group is 1266 implemented. A GROUP clause's DESCRIPTION specifies the conditions 1267 under which the group is conditionally mandatory. 1269 A group which is named in neither a MANDATORY-GROUPS clause nor a GROUP 1270 clause, is unconditionally optional for compliance to the PIB module. 1272 11.1.3. Mapping of the OBJECT clause 1274 The OBJECT clause, which need not be present, is repeatedly used to 1275 specify each attribute for which compliance has a refined requirement 1276 with respect to the PIB module definition. The attribute must be 1277 present in one of the conformance groups named in the correspondent 1278 MANDATORY-GROUPS clause or GROUP clauses. 1280 By definition, each attribute specified in an OBJECT clause follows a 1281 MODULE clause which names the PIB module in which that attribute is 1282 defined. Therefore, the use of an IMPORTS statement, to specify from 1283 where such attributes are imported, is redundant and is not required in 1284 a PIB module. 1286 11.1.3.1. Mapping of the SYNTAX clause 1288 The SYNTAX clause, which need not be present, is used to provide a 1289 refined SYNTAX for the attribute named in the correspondent OBJECT 1290 clause. The refined syntax is the minimum level of support needed for 1291 this attribute in order to be compliant. 1293 Draft SPPI January 2001 1295 11.1.3.2. Mapping of the WRITE-SYNTAX clause 1297 The WRITE-SYNTAX clause is not supported by the SPPI. 1299 11.1.3.3. Mapping of the PIB-MIN-ACCESS clause 1301 The PIB-MIN-ACCESS clause, which need not be present, is used to define 1302 the minimal level of access for the attribute named in the correspondent 1303 OBJECT clause. If this clause is absent, the minimal level of access is 1304 the same as the maximal level specified in the PIB-ACCESS clause of the 1305 correspondent invocation of the OBJECT-TYPE macro. If present, this 1306 clause must specify a subset of the access specified in the 1307 correspondent PIB-ACCESS clause, where: "install" is a subset of 1308 "install-notify", "notify" is a subset of "install-notify", and "not- 1309 accessible" is a subset of all other values. 1311 An implementation is compliant if the level of access it provides is the 1312 same or a superset of the minimal level in the MODULE-COMPLIANCE macro 1313 and the same or a subset of the maximal level in the PIB-ACCESS clause. 1315 12. Textual Conventions 1317 When designing a PIB module, it is often useful to define new data types 1318 similar to those defined in the SPPI. In comparison to a type defined 1319 in the SPPI, each of these new types has a different name, a similar 1320 syntax, and specific semantics. These newly defined types are termed 1321 textual conventions, and are used for the convenience of humans reading 1322 the PIB module. 1324 Attributes defined using a textual convention are always encoded by 1325 means of the rules that define their underlying type. 1327 12.1. Mapping of the TEXTUAL-CONVENTION macro 1329 The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics 1330 associated with a textual convention. It should be noted that the 1331 expansion of the TEXTUAL-CONVENTION macro is something which 1332 conceptually happens during implementation and not during run-time. 1334 The name of a textual convention must consist of one or more letters or 1335 digits, with the initial character being an upper case letter. The name 1336 must not conflict with any of the reserved words listed in section 5.2, 1337 should not consist of all upper case letters, and shall not exceed 64 1338 characters in length. (However, names longer than 32 characters are not 1339 Draft SPPI January 2001 1341 recommended.) The hyphen is not allowed in the name of a textual 1342 convention (except for use in information modules converted from SMIv1 1343 which allowed hyphens in ASN.1 type assignments). Further, all names 1344 used for the textual conventions defined in all "standard" PIB modules 1345 shall be unique. 1347 12.1.1. Mapping of the SYNTAX clause 1349 The SYNTAX clause, which must be present, defines abstract data 1350 structure corresponding to the textual convention. The data structure 1351 must be one of the following: a base type (see the SYNTAX clause of an 1352 OBJECT-TYPE macro), or the BITS construct. Note that this means that 1353 the SYNTAX clause of a Textual Convention can not refer to a previously 1354 defined Textual Convention. 1356 12.1.1.1. Sub-typing of Textual Conventions 1358 The SYNTAX clause of a TEXTUAL CONVENTION macro may be sub-typed in the 1359 same way as the SYNTAX clause of an OBJECT-TYPE macro. 1361 13. Extending a PIB Module 1363 The SMI's rules for extending an information module are augmented with 1364 the following rules: 1366 13.1. OBJECT-TYPE Definitions 1368 An invocation of the OBJECT-TYPE macro may also be revised in any of the 1369 following ways: 1371 - An INSTALL-ERRORS clause may be added or an existing INSTALL-ERRORS 1372 clause have additional errors defined. 1374 - Additional named-number enumerations may be added to a SUBJECT- 1375 CATEGORIES clause. 1377 Draft SPPI January 2001 1379 14. Appendix A: Mapping a PIB to a MIB 1381 Since the SPPI is modelled on the SMI, a PIB can be easily and 1382 algorithmically mapped into a MIB. This mapping is achieved by means of 1383 the following rules: 1385 - Modify the module's module name by appending "-MIB" to the name. 1387 - Change the OID assigned to the MODULE-IDENTITY to be different 1388 value. 1390 - Replace the keyword PIB-DEFINITIONS with the keyword DEFINITIONS. 1392 - Modify the module names of all external references to PIB modules 1393 by appending "-MIB" to each such module name. 1395 - For each PRC definition, if an INDEX clause is absent, change the 1396 "PIB-INDEX" keyword to "INDEX"; otherwise, delete the PIB-INDEX 1397 clause. 1399 - Delete all of the following clauses: PIB-ACCESS, PIB-REFERENCES, 1400 PIB-TAG, UNIQUENESS, INSTALL-ERRORS, and SUBJECT-CATEGORIES. 1402 - Change all PIB-MIN-ACCESS clauses to MIN-ACCESS clauses, modifying 1403 "install" and "install-notify" to "read-create", and "notify" to 1404 "read-only". 1406 - Add a MAX-ACCESS clause for each OBJECT-TYPE. For each table 1407 definition and row definition, the MAX-ACCESS is "not-accessible". 1408 For each attribute that is in the INDEX clause, the MAX-ACCESS is 1409 "not-accessible". For the remaining attributes, the MAX-ACCESS is 1410 "read-create". 1412 - Add a columnar attribute of type RowStatus with a descriptor and 1413 appropriate DESCRIPTION. The descriptor can be formed by appending 1414 the nine characters "RowStatus" to the end of the PRC's descriptor 1415 (truncated if necessary to avoid the resulting descriptor being too 1416 long). The optional number provided by the PIB-ACCESS clause is 1417 used as the OID for this columnar attribute. If no number is 1418 provided by the PIB-ACCESS clause, then the default number 127 is 1419 used. 1421 - Modify any SYNTAX clause which has a base data type which is not 1422 allowed in the SMI, either to be a valid SMI data type or to omit 1423 the OBJECT-TYPE or TEXTUAL-CONVENTION definition and all references 1425 Draft SPPI January 2001 1427 to it. Since it is not clear (at this time) which is the best SMI 1428 data type to use, the conversion SHOULD provide a configurable 1429 option allowing a choice from at least the following: 1431 - convert to an OCTET STRING of the relevant size. 1432 Specifically, this option would map both Integer64 and 1433 Unsigned64 to OCTET STRING (SIZE(8)), or 1435 - omit them from the conversion, or 1437 - map Integer64 and Unsigned64 to Counter64 (even though this 1438 has problems representing negative numbers, and unwanted 1439 counter semantics.) 1441 Draft SPPI January 2001 1443 15. Appendix B: Example usage of PIB-REFERENCES and PIB-TAG clauses 1445 The following example demonstrates the use of the PIB-REFERENCES and 1446 PIB-TAG clauses. 1448 In this example, the PIB-REFERENCES clause is used by the 1449 qosIfDscpMapQueue attribute to indicate the PRC of which it references 1450 an instance, and similarly, by the qosIfDscpMapThresh attribute. 1452 The qosIfDscpMapTable PRC has an instance for each DSCP of a particular 1453 "map", but there is no PRC defined for a map itself; rather, a map 1454 consists of all instances of qosIfDscpMapTable which have the same value 1455 of qosIfDscpMapMapId. That is, a tag list is formed by all instances of 1456 qosIfDscpMapTable which have the same value of qosIfDscpMapMapId. This 1457 tag list is referenced by the attribute qosIfDscpAssignDscpMap, and its 1458 use of the PIB-TAG clause indicates this. 1460 qosIfDscpAssignTable OBJECT-TYPE 1461 SYNTAX SEQUENCE OF QosIfDscpAssignEntry 1462 PIB-ACCESS install 1463 STATUS current 1464 DESCRIPTION " " 1465 ::= { qosIfParameters 9 } 1467 qosIfDscpAssignEntry OBJECT-TYPE 1468 SYNTAX QosIfDscpAssignEntry 1469 STATUS current 1470 DESCRIPTION 1471 "An instance of the qosIfDscpAssign class." 1472 PIB-INDEX { qosIfDscpAssignPrid } 1473 UNIQUENESS { qosIfDscpAssignName, qosIfDscpAssignRoles } 1474 ::= { qosIfDscpAssignTable 1 } 1476 QosIfDscpAssignEntry ::= SEQUENCE { 1477 qosIfDscpAssignPrid InstanceId, 1478 qosIfDscpAssignName SnmpAdminString, 1479 qosIfDscpAssignRoles RoleCombination, 1480 qosIfDscpAssignDscpMap TagReferenceId 1481 } 1483 qosIfDscpAssignDscpMap OBJECT-TYPE 1484 SYNTAX TagReferenceId 1485 PIB-TAG qosIfDscpMapMapId -- attribute defined below 1486 STATUS current 1487 DESCRIPTION 1489 Draft SPPI January 2001 1491 "The DSCP map which is applied to interfaces of type 1492 qosIfDscpAssignName which have a role combination of 1493 qosIfDscpAssignRoles." 1494 ::= { qosIfDscpAssignEntry 3 } 1496 -- 1497 -- DSCP to Queue and Threshold Mapping Table 1498 -- 1500 qosIfDscpMapTable OBJECT-TYPE 1501 SYNTAX SEQUENCE OF QosIfDscpMapEntry 1502 PIB-ACCESS install 1503 STATUS current 1504 DESCRIPTION 1505 "Assigns DSCP values to queues and thresholds for an arbitrary 1506 DSCP map. This map can then be assigned to various interface 1507 and role combination pairs." 1508 ::= { qosIfParameters 10 } 1510 qosIfDscpMapEntry OBJECT-TYPE 1511 SYNTAX QosIfDscpMapEntry 1512 STATUS current 1513 DESCRIPTION 1514 "An instance of the qosIfDscpMap class." 1515 PIB-INDEX { qosIfDscpMapPrid } 1516 UNIQUENESS { qosIfDscpMapMapId, qosIfDscpMapDscp } 1517 ::= { qosIfDscpMapTable 1 } 1519 QosIfDscpMapEntry ::= SEQUENCE { 1520 qosIfDscpMapPrid InstanceId, 1521 qosIfDscpMapMapId TagId, 1522 qosIfDscpMapDscp Dscp, 1523 qosIfDscpMapQueue ReferenceId, 1524 qosIfDscpMapThresh ReferenceId 1525 } 1527 qosIfDscpMapMapId OBJECT-TYPE 1528 SYNTAX TagId 1529 STATUS current 1530 DESCRIPTION 1531 "An integer that identifies the DSCP map to which this PRI 1532 belongs." 1533 ::= { qosIfDscpMapEntry 2 } 1535 qosIfDscpMapQueue OBJECT-TYPE 1536 Draft SPPI January 2001 1538 SYNTAX ReferenceId 1539 PIB-REFERENCES qosIfQueueTable 1540 STATUS current 1541 DESCRIPTION 1542 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1543 the queue identified by qosIfQueuePrid in qosIfQueueTable. 1544 For a given DSCP map, all the queues must belong to a single 1545 queue set." 1546 ::= { qosIfDscpMapEntry 4 } 1548 qosIfDscpMapThresh OBJECT-TYPE 1549 SYNTAX ReferenceId 1550 PIB-REFERENCES qosIfThresholdTable 1551 STATUS current 1552 DESCRIPTION 1553 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1554 the threshold identified by qosIfThresholdId in 1555 qosIfThresholdTable. The threshold set to which this 1556 threshold belongs must be assigned to the queue specified by 1557 qosIfDscpMapQueue." 1558 ::= { qosIfDscpMapEntry 5 } 1560 Draft SPPI January 2001 1562 16. Security Considerations 1564 This document defines a language with which to define provisioning 1565 information. The language itself has no security impact on the 1566 Internet. 1568 17. Authors' Addresses 1570 Keith McCloghrie 1571 Cisco Systems, Inc. 1572 170 West Tasman Drive 1573 San Jose, CA 95134-1706 USA 1574 Phone: +1 408 526 5260 1575 Email: kzm@cisco.com 1577 Michael Fine 1578 Cisco Systems, Inc. 1579 170 West Tasman Drive 1580 San Jose, CA 95134-1706 USA 1581 Phone: +1 408 527 8218 1582 Email: mfine@cisco.com 1584 John Seligson 1585 Nortel Networks, Inc. 1586 4401 Great America Parkway 1587 Santa Clara, CA 95054 USA 1588 Phone: +1 408 495 2992 1589 Email: jseligso@nortelnetworks.com 1591 Kwok Ho Chan 1592 Nortel Networks, Inc. 1593 600 Technology Park Drive 1594 Billerica, MA 01821 USA 1595 Phone: +1 978 288 8175 1596 Email: khchan@nortelnetworks.com 1598 Scott Hahn 1599 Intel 1600 2111 NE 25th Avenue 1601 Hillsboro, OR 97124 USA 1602 Phone: +1 503 264 8231 1603 Email: scott.hahn@intel.com 1605 Draft SPPI January 2001 1607 Ravi Sahita 1608 Intel 1609 2111 NE 25th Avenue 1610 Hillsboro, OR 97124 USA 1611 Phone: +1 503 712 1554 1612 Email: ravi.sahita@intel.com 1614 Andrew Smith 1615 Allegro Networks 1616 6399 San Ignacio Ave. 1617 San Jose 1618 CA 95119 1619 FAX: 415 345 1827 1620 Email: andrew@allegronetworks.com 1622 Francis Reichmeyer 1623 PFN Inc. 1624 University Park at MIT 1625 26 Landsdowne Street 1626 Cambridge, MA 02139 1627 Phone: +1 617 494 9980 1628 Email: franr@pfn.com 1630 18. References 1632 [COPS] 1633 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1634 Sastry, "The COPS (Common Open Policy Service) Protocol" RFC 2748, 1635 January 2000. 1637 [COPS-RSVP] 1638 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1639 Sastry, " COPS usage for RSVP", RFC 2749, January 2000. 1641 [COPS-PR] 1642 Reichmeyer, F., Herzog, S., Chan, K., Durham, D., Yavatkar, R. 1643 Gai, S., McCloghrie, K. and A. Smith, "COPS Usage for Policy 1644 Provisioning" Internet Draft, draft-ietf-rap-cops-pr-04.txt, August 1645 2000. 1647 [SMI] 1648 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1649 and S. Waldbusser. "Structure of Management Information Version 2 1650 (SMIv2)", RFC 2578, April 1999. 1652 Draft SPPI January 2001 1654 [TC] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1655 and S. Waldbusser. "Textual Conventions for SMIv2", RFC 2579, 1656 April 1999. 1658 [CONF] 1659 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1660 and S. Waldbusser. "Conformance Statements for SMIv2", RFC 2580, 1661 April 1999. 1663 [APPL] 1664 Levi, D., Meyer, P., and B. Stewart, "SNMP Applications", RFC 2573, 1665 April 1999. 1667 [ASN1] 1668 Information processing systems -- Open Systems Interconnection -- 1669 Specification of Abstract Syntax Notation One (ASN.1), 1670 International Organization for Standardization. International 1671 Standard 8824, December 1987. 1673 Draft SPPI January 2001 1675 19. Full Copyright Statement 1677 Copyright (C) The Internet Society (2000). All Rights Reserved. 1679 This document and translations of it may be copied and furnished to 1680 others, and derivative works that comment on or otherwise explain it or 1681 assist in its implementation may be prepared, copied, published and 1682 distributed, in whole or in part, without restriction of any kind, 1683 provided that the above copyright notice and this paragraph are included 1684 on all such copies and derivative works. However, this document itself 1685 may not be modified in any way, such as by removing the copyright notice 1686 or references to the Internet Society or other Internet organizations, 1687 except as needed for the purpose of developing Internet standards in 1688 which case the procedures for copyrights defined in the Internet 1689 Standards process must be followed, or as required to translate it into 1690 languages other than English. 1692 The limited permissions granted above are perpetual and will not be 1693 revoked by the Internet Society or its successors or assigns. 1695 This document and the information contained herein is provided on an "AS 1696 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 1697 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 1698 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 1699 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 1700 FITNESS FOR A PARTICULAR PURPOSE." 1701 Draft SPPI January 2001 1703 Table of Contents 1705 1 Introduction .................................................... 2 1706 1.1 Change Log .................................................... 2 1707 1.1.1 Changes made in version published on 13 July 2000 ........... 2 1708 1.1.2 Changes made in version published on 20 September 2000 ...... 3 1709 1.1.3 Changes made in version published on 13 November 2000 ....... 4 1710 1.1.4 Changes made in version published 22 January 2000 ........... 4 1711 2 Use of the SMI .................................................. 5 1712 2.1 Terminology Translation ....................................... 5 1713 2.2 Overview ...................................................... 5 1714 3 Structure of this Specification ................................. 6 1715 4 Definitions ..................................................... 7 1716 5 PIB Modules ..................................................... 20 1717 5.1 Importing Definitions ......................................... 20 1718 5.2 Reserved Keywords ............................................. 20 1719 6 Naming Hierarchy ................................................ 21 1720 7 Mapping of the MODULE-IDENTITY macro ............................ 21 1721 7.1 Mapping of the SUBJECT-CATEGORIES clause ...................... 21 1722 8 Mapping of the OBJECT-TYPE macro ................................ 22 1723 8.1 Mapping of the SYNTAX clause .................................. 22 1724 8.1.1 Counter32 ................................................... 22 1725 8.1.2 Gauge32 ..................................................... 23 1726 8.1.3 Opaque ...................................................... 23 1727 8.1.4 Counter64 ................................................... 23 1728 8.1.5 Integer64 ................................................... 23 1729 8.1.6 Unsigned64 .................................................. 23 1730 8.1.7 Provisioning Classes ........................................ 23 1731 8.2 Mapping of the MAX-ACCESS clause .............................. 24 1732 8.3 Mapping of the PIB-ACCESS clause .............................. 24 1733 8.4 Mapping of the INSTALL-ERRORS clause .......................... 25 1734 8.5 Mapping of the PIB-INDEX clause ............................... 25 1735 8.6 Mapping of the INDEX clause ................................... 26 1736 8.7 Mapping of the AUGMENTS clause ................................ 26 1737 8.8 Mapping of the EXTENDS clause ................................. 26 1738 8.8.1 Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1739 .............................................................. 27 1740 8.9 Mapping of the UNIQUENESS clause .............................. 27 1741 8.10 Mapping of the PIB-REFERENCES clause ......................... 28 1742 8.11 Mapping of the PIB-TAG clause ................................ 28 1743 9 Mapping of the OBJECT-IDENTITY macro ............................ 28 1744 10 Mapping of the OBJECT-GROUP macro .............................. 29 1745 10.1 Mapping of the OBJECTS clause ................................ 29 1746 11 Mapping of the MODULE-COMPLIANCE macro ......................... 29 1747 Draft SPPI January 2001 1749 11.1 Mapping of the MODULE clause ................................. 29 1750 11.1.1 Mapping of the MANDATORY-GROUPS clause ..................... 29 1751 11.1.2 Mapping of the GROUP clause ................................ 30 1752 11.1.3 Mapping of the OBJECT clause ............................... 30 1753 11.1.3.1 Mapping of the SYNTAX clause ............................. 30 1754 11.1.3.2 Mapping of the WRITE-SYNTAX clause ....................... 31 1755 11.1.3.3 Mapping of the PIB-MIN-ACCESS clause ..................... 31 1756 12 Textual Conventions ............................................ 31 1757 12.1 Mapping of the TEXTUAL-CONVENTION macro ...................... 31 1758 12.1.1 Mapping of the SYNTAX clause ............................... 32 1759 12.1.1.1 Sub-typing of Textual Conventions ........................ 32 1760 13 Extending a PIB Module ......................................... 32 1761 13.1 OBJECT-TYPE Definitions ...................................... 32 1762 14 Appendix A: Mapping a PIB to a MIB ............................. 33 1763 15 Appendix B: Example usage of PIB-REFERENCES and PIB-TAG 1764 clauses ...................................................... 35 1765 16 Security Considerations ........................................ 38 1766 17 Authors' Addresses ............................................. 38 1767 18 References ..................................................... 39 1768 19 Full Copyright Statement ....................................... 41