idnits 2.17.1 draft-ietf-rap-sppi-03.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 1421: '..., 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 1730 has weird spacing: '...elation betwe...' -- 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 (13 November 2000) is 8563 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 0' is mentioned on line 340, but not defined == Missing Reference: 'APPLICATION 2' is mentioned on line 345, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 350, but not defined == Missing Reference: 'APPLICATION 7' is mentioned on line 359, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 363, 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 (~~), 8 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 13 November 2000 17 Structure of Policy Provisioning Information (SPPI) 19 draft-ietf-rap-sppi-03.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 November 2000 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-REFERENCE and PIB-TAG. 89 - added detail on carrying an INSTALL-ERROR in COPS-PR messages. 91 Draft SPPI November 2000 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 November 2000 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 Draft SPPI November 2000 147 2. Use of the SMI 149 The SPPI and PIB modules are based on SNMP's SMI and MIB modules, which 150 use an adapted subset of the ASN.1 data definition language [ASN1]. The 151 decision to base the definition of PIB modules on this format allows for 152 the leveraging of the community's knowledge, experience and tools of the 153 SMI and MIB modules. 155 2.1. Terminology Translation 157 The SMI uses the term "managed objects" to refer to object types, both 158 tabular types with descriptors such as xxxTable and xxxEntry, as well as 159 scalar and columnar object types. The SPPI does not use the term 160 "object" so as to avoid confusion with COPS protocol objects. Instead, 161 the SPPI uses the term Provisioning Class (PRC) for the table and row 162 definitions (the xxxTable and xxxEntry objects, respectively), and 163 Provisioning Instance (PRI) for an instantiation of a row definition. 164 For a columnar object of a table definition, the SPPI uses the term 165 "attribute" of a Provisioning Class. (The SPPI does not support the 166 equivalent of the SMI's scalar objects.) 168 2.2. Overview 170 SNMP's SMI is divided into five parts: module definitions, object 171 definitions, notification definitions [SMI], textual convention 172 definitions [TC] and conformance definitions [CONF]. 174 - The SMI's MODULE-IDENTITY macro is used to convey the semantics of 175 a MIB module. The SPPI uses this macro to convey the semantics of 176 a PIB module. 178 - The SMI's OBJECT-TYPE macro is used to convey the syntax and 179 semantics of managed objects. The SPPI uses this macro to convey 180 the syntax and semantics of PRCs and their attributes. 182 - The SMI's notification definitions are not used (at this time) by 183 the SPPI. (Note that the use of the keyword 'notify' in the SPPI 184 is not related to the SMI's notifications). 186 - The SMI's TEXTUAL CONVENTION macro allows new data types to be 187 defined. The SPPI uses this macro to define new data types having 188 particular syntax and semantics which is common to several 189 attributes of one of more PRCs. 191 Draft SPPI November 2000 193 - The SMI's conformance definitions define several macros: the 194 OBJECT-GROUP macro, the NOTIFICATION-GROUP macro, the MODULE- 195 COMPLIANCE macro and the AGENT-CAPABILITIES macro. The SPPI uses 196 the OBJECT-GROUP and MODULE-COMPLIANCE macros to specify acceptable 197 lower-bounds of implementation of the attributes of PRCs, and 198 thereby indirectly, acceptable lower-bounds of implementation of 199 the PRCs themselves. The NOTIFICATION-GROUP macro is not used (at 200 this time) by the SPPI. Potential usage by the SPPI of the AGENT- 201 CAPABILITIES macro is for further study. 203 3. Structure of this Specification 205 The SMI is specified in terms of an ASN.1 definition together with 206 descriptive text for each element introduced in that ASN.1 definition. 207 This document specifies the SPPI also via a ASN.1 definition, which is a 208 modified version of the SMI's definition, together with descriptive text 209 for only those elements in the SPPI's ASN.1 definition which have 210 differences from the SMI's. For elements in the ASN.1 definition which 211 have no descriptive text in this specification, the reader is referred 212 to the SMI's descriptive text for that element. 214 Draft SPPI November 2000 216 4. Definitions 218 COPS-PR-SPPI DEFINITIONS ::= BEGIN 220 IMPORTS ObjectName, SimpleSyntax, ExtUTCTime 221 FROM SNMPv2-SMI; 223 -- definitions for PIB modules 225 MODULE-IDENTITY MACRO ::= 226 BEGIN 227 TYPE NOTATION ::= 228 SubjectPart -- new 229 "LAST-UPDATED" value(Update ExtUTCTime) 230 "ORGANIZATION" Text 231 "CONTACT-INFO" Text 232 "DESCRIPTION" Text 233 RevisionPart 235 VALUE NOTATION ::= 236 value(VALUE OBJECT IDENTIFIER) 238 SubjectPart ::= -- new 239 "SUBJECT-CATEGORIES" "{" Categories "}" 240 Categories ::= -- new 241 CategoryIDs 242 | "all" 243 CategoryIDs ::= -- new 244 CategoryID 245 | CategoryIDs "," CategoryID 246 CategoryID ::= -- new 247 identifier "(" number ")" -- number is positive 249 RevisionPart ::= 250 Revisions 251 | empty 252 Revisions ::= 253 Revision 254 | Revisions Revision 255 Revision ::= 256 "REVISION" value(Update ExtUTCTime) 257 "DESCRIPTION" Text 259 Draft SPPI November 2000 261 -- a character string as defined in [SMI] 262 Text ::= value(IA5String) 263 END 265 -- 267 OBJECT-IDENTITY MACRO ::= 268 BEGIN 269 TYPE NOTATION ::= 270 "STATUS" Status 271 "DESCRIPTION" Text 272 ReferPart 274 VALUE NOTATION ::= 275 value(VALUE OBJECT IDENTIFIER) 277 Status ::= 278 "current" 279 | "deprecated" 280 | "obsolete" 282 ReferPart ::= 283 "REFERENCE" Text 284 | empty 286 -- a character string as defined in [SMI] 287 Text ::= value(IA5String) 288 END 290 -- syntax of attributes 292 -- the "base types" defined here are: 293 -- 3 built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER 294 -- 6 application-defined types: Integer32, IpAddress, Unsigned32, 295 -- TimeTicks, Integer64 and Unsigned64 297 ObjectSyntax ::= 298 CHOICE { 299 simple 300 SimpleSyntax, 302 -- note that SEQUENCEs for table and row definitions 303 -- are not mentioned here... 305 Draft SPPI November 2000 307 application-wide 308 ApplicationSyntax 309 } 311 -- application-wide types 313 ApplicationSyntax ::= 314 CHOICE { 315 ipAddress-value 316 IpAddress, 318 timeticks-value 319 TimeTicks, 321 unsigned-integer-value 322 Unsigned32, 324 large-integer-value -- new 325 Integer64, 327 large-unsigned-integer-value -- new 328 Unsigned64 329 } 331 -- the following 4 types are copied from the SMI 333 -- indistinguishable from INTEGER, but never needs more than 334 -- 32-bits for a two's complement representation 335 Integer32 ::= 336 INTEGER (-2147483648..2147483647) 338 -- (this is a tagged type for historical reasons) 339 IpAddress ::= 340 [APPLICATION 0] 341 IMPLICIT OCTET STRING (SIZE (4)) 343 -- an unsigned 32-bit quantity 344 Unsigned32 ::= 345 [APPLICATION 2] 346 IMPLICIT INTEGER (0..4294967295) 348 -- hundredths of seconds since an epoch 349 TimeTicks ::= 350 [APPLICATION 3] 352 Draft SPPI November 2000 354 IMPLICIT INTEGER (0..4294967295) 356 -- the following 2 types are not present in the SMI 358 Integer64 ::= 359 [APPLICATION 7] 360 IMPLICIT INTEGER (-9223372036854775808..9223372036854775807) 362 Unsigned64 363 [APPLICATION 8] 364 IMPLICIT INTEGER (0..18446744073709551615) 366 -- definition for Provisioning Classes and their attributes 367 -- (differences from the SMI are noted in the ASN.1 comments) 369 OBJECT-TYPE MACRO ::= 370 BEGIN 371 TYPE NOTATION ::= 372 "SYNTAX" Syntax 373 UnitsPart 374 "PIB-ACCESS" AccessPart -- modified 375 PibReferencesPart -- new 376 PibTagPart -- new 377 "STATUS" Status 378 "DESCRIPTION" Text 379 ErrorsPart -- new 380 ReferPart 381 IndexPart -- modified 382 MibIndexPart -- modified 383 UniquePart -- new 384 DefValPart 386 VALUE NOTATION ::= 387 value(VALUE ObjectName) 389 Syntax ::= -- Must be one of the following: 390 -- a base type (or its refinement), 391 -- a textual convention (or its refinement), or 392 -- a BITS pseudo-type 393 type 394 | "BITS" "{" NamedBits "}" 396 NamedBits ::= NamedBit 397 | NamedBits "," NamedBit 399 Draft SPPI November 2000 401 NamedBit ::= identifier "(" number ")" -- number is nonnegative 403 UnitsPart ::= 404 "UNITS" Text 405 | empty 407 AccessPart ::= -- new 408 Access 409 | Access "," number -- number is positive 411 Access ::= -- modified 412 "install" 413 | "notify" 414 | "install-notify" 415 | "report-only" 417 Status ::= 418 "current" 419 | "deprecated" 420 | "obsolete" 422 ErrorsPart ::= -- new 423 "INSTALL-ERRORS" "{" Errors "}" 424 | empty 426 Errors ::= -- new 427 Error 428 | Errors "," Error 429 Error ::= -- new 430 identifier "(" number ")" -- number is positive 432 ReferPart ::= 433 "REFERENCE" Text 434 | empty 436 IndexPart ::= 437 "PIB-INDEX" "{" Index "}" -- new 438 | "AUGMENTS" "{" Entry "}" 439 | "EXTENDS" "{" Entry "}" -- new 440 | empty 441 Index ::= 442 -- the correspondent OBJECT-TYPE invocation 443 value(ObjectName) 444 Entry ::= 445 -- use the INDEX value of the 447 Draft SPPI November 2000 449 -- correspondent OBJECT-TYPE invocation 450 value(ObjectName) 451 MibIndexPart ::= 452 "INDEX" "{" IndexTypePart "}" 453 | empty 454 IndexTypePart ::= 455 IndexTypes 456 | IndexTypes "," ImpliedIndex 457 | ImpliedIndex 458 IndexTypes ::= 459 Index 460 | IndexTypes "," Index 461 ImpliedIndex ::= 462 "IMPLIED" Index 464 PibReferencesPart ::= 465 -- for use with ReferenceId TC 466 "PIB-REFERENCES" "{" Entry "}" 467 | empty 469 PibTagPart ::= 470 -- for use with TagReferenceId TC 471 "PIB-TAG" "{" Attr "}" 472 | empty 474 Attr ::= -- specifies an attribute 475 value(ObjectName) 477 UniquePart ::= -- new 478 "UNIQUENESS" "{" UniqueTypes "}" 479 | "UNIQUENESS" "{" "}" 480 | empty 481 UniqueTypes ::= 482 UniqueType 483 | UniqueTypes "," UniqueType 484 UniqueType ::= 485 -- the correspondent OBJECT-TYPE invocation 486 value(ObjectName) 488 DefValPart ::= "DEFVAL" "{" Defvalue "}" 489 | empty 491 Defvalue ::= -- must be valid for the type specified in 492 -- SYNTAX clause of same OBJECT-TYPE macro 494 Draft SPPI November 2000 496 value(ObjectSyntax) 497 | "{" BitsValue "}" 499 BitsValue ::= BitNames 500 | empty 502 BitNames ::= BitName 503 | BitNames "," BitName 505 BitName ::= identifier 507 -- a character string as defined in [SMI] 508 Text ::= value(IA5String) 509 END 511 -- definitions for conformance groups 513 OBJECT-GROUP MACRO ::= 514 BEGIN 515 TYPE NOTATION ::= 516 ObjectsPart 517 "STATUS" Status 518 "DESCRIPTION" Text 519 ReferPart 521 VALUE NOTATION ::= 522 value(VALUE OBJECT IDENTIFIER) 524 ObjectsPart ::= 525 "OBJECTS" "{" Objects "}" 526 Objects ::= 527 Object 528 | Objects "," Object 529 Object ::= 530 value(ObjectName) 532 Status ::= 533 "current" 534 | "deprecated" 535 | "obsolete" 537 ReferPart ::= 538 "REFERENCE" Text 539 | empty 541 Draft SPPI November 2000 543 -- a character string as defined in [SMI] 544 Text ::= value(IA5String) 545 END 547 -- definitions for compliance statements 549 MODULE-COMPLIANCE MACRO ::= 550 BEGIN 551 TYPE NOTATION ::= 552 "STATUS" Status 553 "DESCRIPTION" Text 554 ReferPart 555 ModulePart 557 VALUE NOTATION ::= 558 value(VALUE OBJECT IDENTIFIER) 560 Status ::= 561 "current" 562 | "deprecated" 563 | "obsolete" 565 ReferPart ::= 566 "REFERENCE" Text 567 | empty 569 ModulePart ::= 570 Modules 571 Modules ::= 572 Module 573 | Modules Module 574 Module ::= 575 -- name of module -- 576 "MODULE" ModuleName 577 MandatoryPart 578 CompliancePart 580 ModuleName ::= 581 -- identifier must start with uppercase letter 582 identifier ModuleIdentifier 583 -- must not be empty unless contained 584 -- in MIB Module 585 | empty 586 ModuleIdentifier ::= 588 Draft SPPI November 2000 590 value(OBJECT IDENTIFIER) 591 | empty 593 MandatoryPart ::= 594 "MANDATORY-GROUPS" "{" Groups "}" 595 | empty 597 Groups ::= 598 Group 599 | Groups "," Group 600 Group ::= 601 value(OBJECT IDENTIFIER) 603 CompliancePart ::= 604 Compliances 605 | empty 607 Compliances ::= 608 Compliance 609 | Compliances Compliance 610 Compliance ::= 611 ComplianceGroup 612 | Object 614 ComplianceGroup ::= 615 "GROUP" value(OBJECT IDENTIFIER) 616 "DESCRIPTION" Text 618 Object ::= 619 "OBJECT" value(ObjectName) 620 InstallSyntaxPart -- modified 621 AccessPart 622 "DESCRIPTION" Text 624 -- must be a refinement for object's SYNTAX clause 625 InstallSyntaxPart ::= "SYNTAX" Syntax 626 | empty 628 Syntax ::= -- Must be one of the following: 629 -- a base type (or its refinement), 630 -- a textual convention (or its refinement), or 631 -- a BITS pseudo-type 632 type 633 | "BITS" "{" NamedBits "}" 635 Draft SPPI November 2000 637 NamedBits ::= NamedBit 638 | NamedBits "," NamedBit 640 NamedBit ::= identifier "(" number ")" -- number is nonnegative 642 AccessPart ::= 643 "PIB-MIN-ACCESS" Access -- modified 644 | empty 645 Access ::= -- modified 646 "not-accessible" 647 | "install" 648 | "notify" 649 | "install-notify" 651 -- a character string as defined in [SMI] 652 Text ::= value(IA5String) 653 END 655 -- definition of textual conventions 657 TEXTUAL-CONVENTION MACRO ::= 658 BEGIN 659 TYPE NOTATION ::= 660 DisplayPart 661 "STATUS" Status 662 "DESCRIPTION" Text 663 ReferPart 664 "SYNTAX" Syntax 666 VALUE NOTATION ::= 667 value(VALUE Syntax) -- adapted ASN.1 669 DisplayPart ::= 670 "DISPLAY-HINT" Text 671 | empty 673 Status ::= 674 "current" 675 | "deprecated" 676 | "obsolete" 678 ReferPart ::= 679 "REFERENCE" Text 680 | empty 682 Draft SPPI November 2000 684 -- a character string as defined in [SMI] 685 Text ::= value(IA5String) 687 Syntax ::= -- Must be one of the following: 688 -- a base type (or its refinement), or 689 -- a BITS pseudo-type 690 type 691 | "BITS" "{" NamedBits "}" 693 NamedBits ::= NamedBit 694 | NamedBits "," NamedBit 696 NamedBit ::= identifier "(" number ")" -- number is nonnegative 698 END 700 END 701 Draft SPPI November 2000 703 COPS-PR-SPPI-TC PIB-DEFINITIONS ::= BEGIN 705 IMPORTS Unsigned32, MODULE-IDENTITY, TEXTUAL-CONVENTION 706 FROM COPS-PR-SPPI; 708 copsPrSppiTc MODULE-IDENTITY 709 SUBJECT-CATEGORIES { all } 710 LAST-UPDATED "200009201800Z" 711 ORGANIZATION "IETF RAP WG" 712 CONTACT-INFO "Keith McCloghrie 713 Cisco Systems, Inc. 714 170 West Tasman Drive, 715 San Jose, CA 95134-1706 USA 716 Phone: +1 408 526 5260 717 Email: kzm@cisco.com 719 Ravi Sahita 720 Intel 721 2111 NE 25th Avenue 722 Hillsboro, OR 97124 USA 723 Phone: +1 503 712 1554 724 Email: ravi.sahita@intel.com " 725 DESCRIPTION 726 "The PIB module containing a set of Textual Conventions 727 which have general applicability to all PIB modules." 728 REVISION "200009201800Z" 729 DESCRIPTION 730 "Initial version, published in RFC xxxx." 731 ::= { tbd } 733 InstanceId ::= TEXTUAL-CONVENTION 734 STATUS current 735 DESCRIPTION 736 "The textual convention for use by an attribute which is used 737 as the instance-identifying index of a PRC, i.e., an attribute 738 named in a PIB-INDEX clause. The value of an attribute with this 739 syntax is always greater than zero. PRIs of the same PRC need 740 not have contiguous values for their instance-identifying 741 attribute." 742 SYNTAX Unsigned32 (1..4294967295) 744 ReferenceId ::= TEXTUAL-CONVENTION 745 STATUS current 746 DESCRIPTION 747 "A textual convention for use by an attribute which is used as 749 Draft SPPI November 2000 751 a pointer in order to reference an instance of a particular 752 PRC. An attribute with this syntax must not be used in a 753 PIB-INDEX clause , and its description must specify the 754 particular PRC to which the referenced PRI will belong. 755 For an attribute of this type, the referenced PRI must exist. 756 Furthermore, it is an error to try to delete a PRI that is 757 referenced by another instance without first deleting/modifying 758 the referencing instance. The definition of an attribute with 759 this syntax can permit the attribute to have a value of zero to 760 indicate that it is not currently pointing to an PRI." 761 SYNTAX Unsigned32 763 Prid ::= TEXTUAL-CONVENTION 764 STATUS current 765 DESCRIPTION 766 "Represents a pointer to a PRI, i.e,. to an instance of a 767 PRC. The value is the OID name of the PRC's row definition, 768 appended with one sub-identifier containing the value of the 769 InstanceId value for the referenced instance. The definition 770 of an attribute with this syntax can permit the attribute to 771 have a value of 0.0 to indicate that it is not currently 772 pointing to a PRI." 773 SYNTAX OBJECT IDENTIFIER 775 TagId ::= TEXTUAL-CONVENTION 776 STATUS current 777 DESCRIPTION 778 "Represents a tag value, such that all instances of a 779 particular PRC having the same tag value form a tag list. 780 A tag list is identified by the tag value shared by all 781 instances in that tag list." 782 SYNTAX Unsigned32 (1..4294967295) 784 TagReferenceId ::= TEXTUAL-CONVENTION 785 STATUS current 786 DESCRIPTION 787 "Represents a reference to a tag list of instances of a 788 particular PRC. The particular PRC must have an attribute 789 with the syntax of TagId. The tag list consists of 790 all instances which have the same value of the TagId 791 attribute. Reference to the tag list is via the attribute 792 with the syntax of TagReferenceId containing the tag 793 value which identifies the tag list." 794 SYNTAX Unsigned32 795 END 796 Draft SPPI November 2000 798 5. PIB Modules 800 The names of all standard PIB modules must be unique (but different 801 versions of the same module should have the same name). Developers of 802 enterprise PIB modules are encouraged to choose names for their modules 803 that will have a low probability of colliding with standard or other 804 enterprise modules. 806 The first line of a PIB module is: 808 PIB-MODULE-NAME PIB-DEFINITIONS ::= BEGIN 810 where PIB-MODULE-NAME is the module name. 812 Like the SMI, additional ASN.1 macros must not be defined in PIB 813 modules. 815 5.1. Importing Definitions 817 Like the SMI, a PIB module which needs to reference an external 818 definition, must use the IMPORTS statement to identify both the 819 descriptor and the module in which the descriptor is defined, where a 820 module is identified by its ASN.1 module name. 822 In particular, a PIB module imports each of the base data types that it 823 uses from COPS-PR-SPPI (defined in this document), and may import as 824 required from other PIB modules. A PIB module may import, from the SMI, 825 (subtree) OIDs for the purpose of defining new OIDs. A PIB module may 826 also import, from MIB modules, OID assignments as well as textual 827 convention definitions providing that their underlying syntax is 828 supported by the SPPI. However, the following must not be included in 829 an IMPORTS statement: 831 - named types defined by ASN.1 itself, specifically: INTEGER, OCTET 832 STRING, OBJECT IDENTIFIER, SEQUENCE, SEQUENCE OF type, 833 - the BITS construct. 835 For each ASN.1 macro that a PIB uses, it must import that macro's 836 definition from the COPS-PR-SPPI. 838 5.2. Reserved Keywords 840 In addition to the reserved keywords listed in the SMI, the following 841 must not be used as descriptors or module names: 843 Draft SPPI November 2000 845 EXTENDS INSTALL-ERRORS Integer64 PIB-MIN-ACCESS PIB-ACCESS 846 PIB-INDEX PIB-REFERENCES PIB-TAG SUBJECT-CATEGORIES UNIQUENESS 847 Unsigned64 849 6. Naming Hierarchy 851 The SPPI uses the same OBJECT IDENTIFIER naming hierarchy as the SMI. 852 That is, OIDs are typically assigned to PIB modules from the subtree 853 administered by the Internet Assigned Numbers Authority (IANA). 854 However, like the SMI, the SPPI does not prohibit the definition of PRCs 855 in other portions of the OID tree. 857 7. Mapping of the MODULE-IDENTITY macro 859 7.1. Mapping of the SUBJECT-CATEGORIES clause 861 The SUBJECT-CATEGORIES clause, which must be present, identifies one or 862 more categories of provisioning data for which this PIB module defines 863 provisioning information. For use with the COPS-PR protocol, the 864 individual subject categories are mapped to COPS Client Types [COPS-PR]. 865 The subject categories are identified either: 867 - via the keyword "all", indicating the PIB module defines 868 provisioning information relevant for all subject categories (and 869 thus, all COPS Client Types), or 871 - a list of named-number enumerations, where each number which must 872 be greater than zero, identifies a subject category, and is mapped 873 to the Client Type which is identified by that same number in the 874 COPS protocol. The namespace for these named numbers is global and 875 therefore the labels should be assigned consistently across PIB 876 modules. At present time, no more than one named-number 877 enumeration should be specified. 879 Note that the list of categories specified in a PIB module's SUBJECT- 880 CATEGORIES clause is not exclusive. That is, some other specification 881 might (e.g., at a future date) specify additional COPS Client Types to 882 which the module is relevant. 884 When a PIB module applies to multiple subject categories, that PIB 885 module exists in multiple virtual information stores, one for each 886 Client-Type. 888 Draft SPPI November 2000 890 8. Mapping of the OBJECT-TYPE macro 892 The SPPI requires that all attribute definitions be contained within a 893 PRC, i.e., within a table definition. 895 8.1. Mapping of the SYNTAX clause 897 The SYNTAX clause, which must be present within the definition of an 898 attribute, defines the abstract data structure of that attribute. The 899 data structure must be one of the following: a base type, the BITS 900 construct, or a textual convention. 902 The SYNTAX clause must also be present for the table and row definitions 903 of a PRC, and in this case must be a SEQUENCE OF or SEQUENCE (see 904 section 8.1.7 below). 906 The base types are an extended subset of the SMI's base types: 908 - built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER, 910 - application-defined types: Integer32, IpAddress, Unsigned32, 911 TimeTicks, Integer64 and Unsigned64. 913 A textual convention is a newly-defined type defined as a sub-type of a 914 base type [TC]. The value of an attribute whose syntax is defined using 915 a textual convention is encoded "on-the-wire" according to the textual 916 convention's underlying base type. 918 Note that the set of base types has been chosen so as to provide 919 sufficient variety of on-the-wire encodings for attribute values; base 920 types should contain a minimum of semantics. Semantics should, to the 921 extent possible, be incorporated into a data type through the use of a 922 textual convention. Thus, the IpAddress and TimeTicks data types should 923 really be defined as textual conventions because they contain semantics. 924 However, they are defined here as base types so as to avoid confusion 925 with the SMI which defines them as base types. 927 The differences from the SMI in the semantics of ObjectSyntax are now 928 described. 930 8.1.1. Counter32 932 The Counter32 type is not supported by the SPPI. 934 Draft SPPI November 2000 936 8.1.2. Gauge32 938 The Gauge32 type is not supported by the SPPI. 940 8.1.3. Opaque 942 The Opaque type is not supported by the SPPI. 944 8.1.4. Counter64 946 The Counter64 type is not supported by the SPPI. 948 8.1.5. Integer64 950 The Integer64 type represents integer-valued information between -2^63 951 and 2^63-1 inclusive (-9223372036854775808 to 9223372036854775807 952 decimal). While Integer64 may be sub-typed to be more constrained, if 953 the constraint results in all possible values being contained in the 954 range (-2147483648..2147483647), then the Integer32 type must be used 955 instead of Integer64. 957 8.1.6. Unsigned64 959 The Unsigned64 type represents integer-valued information between 0 and 960 2^64-1 inclusive (0 to 18446744073709551615 decimal). While Unsigned64 961 may be sub-typed to be more constrained, if the constraint results in 962 all possible values being contained in the range (0..4294967295), then 963 the Unsigned32 type must be used instead of Unsigned64. 965 8.1.7. Provisioning Classes 967 The operations (on PIBs) supported by the SPPI apply exclusively to 968 PRCs. Each PRC is modelled as a tabular structure, i.e., a table. Each 969 instance of a particular PRC has the same set of attributes. The set of 970 attributes which belong to every instance of a particular PRC is 971 modelled as a row in the table. This model is formalized by using the 972 OBJECT-TYPE macro to define both: 974 - the PRC as a whole, called the table definition, and 976 - the characteristics of every instance of a particular PRC, called 977 the row definition. 979 In the table definition, the SYNTAX clause has the form: 981 Draft SPPI November 2000 983 SEQUENCE OF 985 where refers to the SEQUENCE type of its attribute 986 definitions. In the row definition, the SYNTAX clause has the form: 988 990 where is a SEQUENCE type defined as follows: 992 ::= SEQUENCE { , ... , } 994 where there is one for each attribute, and each is of the 995 form: 997 999 where is the descriptor naming an attribute, and 1000 has the value of that attribute's SYNTAX clause, except that both sub- 1001 typing information and the named values for enumerated integers or the 1002 named bits for the BITS construct, are omitted from . 1004 8.2. Mapping of the MAX-ACCESS clause 1006 The MAX-ACCESS clause is not supported by the SPPI. 1008 8.3. Mapping of the PIB-ACCESS clause 1010 The PIB-ACCESS clause must be present for a PRC's table definition, and 1011 must not be present for any other OBJECT-TYPE definition. The PIB- 1012 ACCESS clause defines what kind of access is appropriate for the PRC. 1013 The PIB-ACCESS clause also optionally (default value is 127) provides a 1014 number which is used in the algorithmic conversion of a PIB to a MIB 1015 (see Appendix A). 1017 - the value "install" is used to indicate a PRC which a PDP can 1018 install in the PEP as provisioning information. 1020 - the value "notify" is used to indicate a PRC for which the PEP must 1021 notify the PDP of all its instances and attribute values of that 1022 PRC. 1024 - the value "install-notify" is used to indicate the uncommon type of 1025 PRC which has both characteristics: "install" and "notify". 1027 Draft SPPI November 2000 1029 the value "report-only" is used to indicate a PRC which has neither the 1030 "install" characteristic nor the "notify" characteristic. However, 1031 instances of such a PRC may be included in synchronous/asynchronous 1032 reports generated by the PEP. (Note: PRCs having the "install" and/or 1033 "notify" characteristics may also be included in reports generated by 1034 the PEP.) 1036 8.4. Mapping of the INSTALL-ERRORS clause 1038 The INSTALL-ERRORS clause, which may optionally be present for a PRC's 1039 table definition, and must be absent otherwise, lists one or more 1040 potential reasons for rejecting an install or a removal of an instance 1041 of the PRC. Each reason consists of a named-number enumeration, where 1042 the number represents a PRC-specific error-code to be used in a COPS 1043 protocol message, as the Sub-Error Code, with the Error-Code set to 1044 priSpecificError (see [COPS-PR]). The semantics of each named-number 1045 enumeration should be described in the PRC's DESCRIPTION clause. 1047 The numbers listed in an INSTALL-ERRORS must be greater than zero and 1048 less than 65536. If this clause is not present, an install/remove can 1049 still fail, but no PRC-specific error is available to be reported. 1051 8.5. Mapping of the PIB-INDEX clause 1053 The PIB-INDEX clause, which must be present for a row definition (unless 1054 an AUGMENTS or an EXTENDS clause is present instead), and must be absent 1055 otherwise, defines identification information for instances of the PRC. 1057 The PIB-INDEX clause includes exactly one descriptor. This descriptor 1058 specifies an attribute (typically, but not necessarily of the same PRC) 1059 which is used to identify an instance of that PRC. The syntax of this 1060 attribute is required to be InstanceId (a textual convention with an 1061 underlying syntax of Unsigned32), and it has no semantics other than its 1062 use in identifying the PRC instance. The OBJECT IDENTIFIER which 1063 identifies an instance of a PRC is formed by appending one sub- 1064 identifier to the OID which identifies that PRC's row definition. The 1065 value of the additional sub-identifier is that instance's value of the 1066 attribute specified in the INDEX clause. 1068 Note that SPPI does not permit use of the IMPLIED keyword in a PIB-INDEX 1069 clause. 1071 Draft SPPI November 2000 1073 8.6. Mapping of the INDEX clause 1075 The INDEX clause is optionally present if a PIB-INDEX clause is present, 1076 and must be absent otherwise. If present, the INDEX clause can contain 1077 any number of attributes, and is used only by the algorithmic conversion 1078 of a PIB to a MIB (see Appendix A). 1080 An IMPLIED keyword can be present in an INDEX clause if so desired. 1082 8.7. Mapping of the AUGMENTS clause 1084 The AUGMENTS clause, which must not be present except in row 1085 definitions, is an alternative to the PIB-INDEX clause and the EXTENDS 1086 clause. Every row definition has exactly one of: a PIB-INDEX clause, an 1087 AUGMENTS clause, or an EXTENDS clause. 1089 A row definition which has a PIB-INDEX clause is called a base row 1090 definition. A row definition which has an AUGMENTS clause is called a 1091 row augmentation, where the AUGMENTS clause names the base row 1092 definition which is augmented by this row augmentation. (Thus, a row 1093 augmentation cannot itself be augmented.) 1095 A PRC whose row definition is a row augmentation is called an augmenting 1096 PRC. Instances of an augmenting PRC are identified according to the 1097 PIB-INDEX clause of the base row definition named in the AUGMENTS 1098 clause. Further, instances of an augmenting PRC exist according to the 1099 same semantics as instances of the PRC which it augments. As such, when 1100 an instance of a PRC is installed or removed, an instance of every PRC 1101 which augments it is also installed or removed (for more details, see 1102 [COPS-PR]). 1104 8.8. Mapping of the EXTENDS clause 1106 The EXTENDS clause, which must not be present except in row definitions, 1107 is an alternative to the PIB-INDEX clause and the AUGMENTS clause. 1108 Every row definition has exactly one of: a PIB-INDEX clause, an AUGMENTS 1109 clause, or an EXTENDS clause. 1111 A row definition which has an EXTENDS clause is called a sparse row 1112 augmentation, where the EXTENDS clause names the row definition which is 1113 sparsely-augmented by this sparse row augmentation. The sparsely- 1114 augmented row can be a base row definition, or another sparse row 1115 augmentation. 1117 Draft SPPI November 2000 1119 A PRC whose row definition is a sparse row augmentation is called a 1120 sparsely augmenting PRC. Instances of a sparsely augmenting PRC are 1121 identified according to the PIB-INDEX clause of the row definition named 1122 in the sparsely augmenting PRC's EXTENDS clause. 1124 An instance of a sparsely augmenting PRC can not exist unless a 1125 corresponding instance of the PRC which it sparsely augments exists. As 1126 such, when an instance of a PRC is removed, an instance of any PRC which 1127 sparsely augments it is also removed. However, an instance of a 1128 sparsely augmenting PRC need not exist when the corresponding instance 1129 of the PRC that it sparsely augments exists. Thus, an instance of a 1130 sparsely augmenting PRC can be installed at the same time as or 1131 subsequent to the installation of, and can be removed prior to the 1132 removal of, the corresponding instance of the PRC that it sparsely 1133 augments. So, instances of a sparsely augmenting PRC must be installed 1134 explicitly, but are removed either implicitly (via removal of the 1135 augmented PRI) or explicitly. 1137 8.8.1. Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1139 When defining instance identification information for a PRC: 1141 - If there is a one-to-one correspondence between instances of this 1142 PRC and instances of an existing PRC, then the AUGMENTS clause 1143 should be used. 1145 - Otherwise, if there is a sparse relationship between instances of 1146 this PRC and instances of an existing PRC, then an EXTENDS clause 1147 should be used. 1149 - Otherwise, a PIB-INDEX clause should be used which names its own 1150 InstanceId attribute. 1152 8.9. Mapping of the UNIQUENESS clause 1154 The UNIQUENESS clause, which is optionally present for any row 1155 definition which has a PIB-INDEX clause, and must be absent otherwise, 1156 lists a set of zero or more of the PRC's attributes, for which no two 1157 instances of the PRC can have the same set of values. The specified set 1158 of attributes provide a necessary and sufficient set of values by which 1159 to identify an instance of this PRC. The attribute contained in the 1160 PIB-INDEX clause may not be present in the UNIQUENESS clause. By 1161 definition, an attribute may not appear more than once in a UNIQUENESS 1162 clause. A UNIQUENESS clause containing zero attributes indicates that 1163 Draft SPPI November 2000 1165 it's possible for two instances of the PRC to have identical values for 1166 all attributes except, of course, for the one named in the PIB-INDEX 1167 clause. 1169 Even though the UNIQUENESS clause is optional, its inclusion is 1170 recommended wherever it provides useful information. 1172 8.10. Mapping of the PIB-REFERENCES clause 1174 The PIB-REFERENCES clause, which must be present for any attribute which 1175 has the SYNTAX of ReferenceId, and must be absent otherwise, names the 1176 PRC, an instance of which is referenced by the ReferenceId attribute. 1177 For example usages of the PIB-REFERENCE clause, see Appendix B. 1179 8.11. Mapping of the PIB-TAG clause 1181 The PIB-TAG clause, which must be present for an attribute which has the 1182 SYNTAX TagReferenceId, and must be absent otherwise, is used to indicate 1183 that this attribute references a "tag list" of instances of another PRC. 1184 Such a tag list (similar in concept to the usage of the same term in 1185 [APPL]) is formed by all instances of the other PRC which have the same 1186 (tag) value of a particular attribute of that other PRC. The particular 1187 attribute of the other PRC, which must have the SYNTAX TagId, is named 1188 in the PIB-TAG clause. For an example usage of the PIB-TAG clause, see 1189 Appendix B. 1191 9. Mapping of the OBJECT-IDENTITY macro 1193 The OBJECT-IDENTITY macro is used in PIB modules to define information 1194 about an OBJECT IDENTIFIER assignment. 1196 Draft SPPI November 2000 1198 10. Mapping of the OBJECT-GROUP macro 1200 For conformance purposes, it is useful to define a conformance group as 1201 a collection of related PRCs and their attributes. The OBJECT-GROUP 1202 macro (directly) defines the collection of attributes which belong to a 1203 conformance group. Since each attribute included in the collection 1204 belongs to a PRC, the collection of related PRCs which belong to a 1205 conformance group is also specified (indirectly) as the set of PRCs to 1206 which the included attributes belong. 1208 10.1. Mapping of the OBJECTS clause 1210 The OBJECTS clause, which must be present, is used to specify each 1211 attribute contained in the conformance group. Each of the specified 1212 attributes must be defined in the same PIB module as the OBJECT-GROUP 1213 macro appears. 1215 It is required that every attribute defined in a PIB module be contained 1216 in at least one conformance group. This avoids the common error of 1217 adding a new attribute to a module and forgetting to add the new 1218 attribute to a group. 1220 11. Mapping of the MODULE-COMPLIANCE macro 1222 The MODULE-COMPLIANCE macro is used to convey a minimum set of 1223 requirements with respect to implementation of one or more PIB modules. 1225 A requirement on all "standard" PIB modules is that a corresponding 1226 MODULE-COMPLIANCE specification is also defined, either in the same 1227 module or in a companion module. 1229 11.1. Mapping of the MODULE clause 1231 The MODULE clause, which must be present, is repeatedly used to name 1232 each PIB module for which compliance requirements are being specified. 1233 Each PIB module is named by its module name, and optionally, by its 1234 associated OBJECT IDENTIFIER as well. The module name can be omitted 1235 when the MODULE-COMPLIANCE invocation occurs inside a PIB module, to 1236 refer to the encompassing PIB module. 1238 11.1.1. Mapping of the MANDATORY-GROUPS clause 1240 The MANDATORY-GROUPS clause, which need not be present, names the one or 1241 more conformance groups within the correspondent PIB module which are 1242 Draft SPPI November 2000 1244 unconditionally mandatory for implementation. If an agent claims 1245 compliance to the PIB module, then it must implement each and every 1246 attribute (and therefore the PRCs to which they belong) within each 1247 conformance group listed. 1249 11.1.2. Mapping of the GROUP clause 1251 The GROUP clause, which need not be present, is repeatedly used to name 1252 each conformance group which is conditionally mandatory for compliance 1253 to the PIB module. The GROUP clause can also be used to name 1254 unconditionally optional groups. A group named in a GROUP clause must 1255 be absent from the correspondent MANDATORY-GROUPS clause. 1257 Conditionally mandatory groups include those which are mandatory only if 1258 a particular protocol is implemented, or only if another group is 1259 implemented. A GROUP clause's DESCRIPTION specifies the conditions 1260 under which the group is conditionally mandatory. 1262 A group which is named in neither a MANDATORY-GROUPS clause nor a GROUP 1263 clause, is unconditionally optional for compliance to the PIB module. 1265 11.1.3. Mapping of the OBJECT clause 1267 The OBJECT clause, which need not be present, is repeatedly used to 1268 specify each attribute for which compliance has a refined requirement 1269 with respect to the PIB module definition. The attribute must be 1270 present in one of the conformance groups named in the correspondent 1271 MANDATORY-GROUPS clause or GROUP clauses. 1273 By definition, each attribute specified in an OBJECT clause follows a 1274 MODULE clause which names the PIB module in which that attribute is 1275 defined. Therefore, the use of an IMPORTS statement, to specify from 1276 where such attributes are imported, is redundant and is not required in 1277 a PIB module. 1279 11.1.3.1. Mapping of the SYNTAX clause 1281 The SYNTAX clause, which need not be present, is used to provide a 1282 refined SYNTAX for the attribute named in the correspondent OBJECT 1283 clause. The refined syntax is the minimum level of support needed for 1284 this attribute in order to be compliant. 1286 Draft SPPI November 2000 1288 11.1.3.2. Mapping of the WRITE-SYNTAX clause 1290 The WRITE-SYNTAX clause is not supported by the SPPI. 1292 11.1.3.3. Mapping of the PIB-MIN-ACCESS clause 1294 The PIB-MIN-ACCESS clause, which need not be present, is used to define 1295 the minimal level of access for the attribute named in the correspondent 1296 OBJECT clause. If this clause is absent, the minimal level of access is 1297 the same as the maximal level specified in the PIB-ACCESS clause of the 1298 correspondent invocation of the OBJECT-TYPE macro. If present, this 1299 clause must specify a subset of the access specified in the 1300 correspondent PIB-ACCESS clause, where: "install" is a subset of 1301 "install-notify", "notify" is a subset of "install-notify", and "not- 1302 accessible" is a subset of all other values. 1304 An implementation is compliant if the level of access it provides is the 1305 same or a superset of the minimal level in the MODULE-COMPLIANCE macro 1306 and the same or a subset of the maximal level in the PIB-ACCESS clause. 1308 12. Textual Conventions 1310 When designing a PIB module, it is often useful to define new data types 1311 similar to those defined in the SPPI. In comparison to a type defined 1312 in the SPPI, each of these new types has a different name, a similar 1313 syntax, and specific semantics. These newly defined types are termed 1314 textual conventions, and are used for the convenience of humans reading 1315 the PIB module. 1317 Attributes defined using a textual convention are always encoded by 1318 means of the rules that define their underlying type. 1320 12.1. Mapping of the TEXTUAL-CONVENTION macro 1322 The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics 1323 associated with a textual convention. It should be noted that the 1324 expansion of the TEXTUAL-CONVENTION macro is something which 1325 conceptually happens during implementation and not during run-time. 1327 The name of a textual convention must consist of one or more letters or 1328 digits, with the initial character being an upper case letter. The name 1329 must not conflict with any of the reserved words listed in section 5.2, 1330 should not consist of all upper case letters, and shall not exceed 64 1331 characters in length. (However, names longer than 32 characters are not 1332 Draft SPPI November 2000 1334 recommended.) The hyphen is not allowed in the name of a textual 1335 convention (except for use in information modules converted from SMIv1 1336 which allowed hyphens in ASN.1 type assignments). Further, all names 1337 used for the textual conventions defined in all "standard" PIB modules 1338 shall be unique. 1340 12.1.1. Mapping of the SYNTAX clause 1342 The SYNTAX clause, which must be present, defines abstract data 1343 structure corresponding to the textual convention. The data structure 1344 must be one of the following: a base type (see the SYNTAX clause of an 1345 OBJECT-TYPE macro), or the BITS construct. Note that this means that 1346 the SYNTAX clause of a Textual Convention can not refer to a previously 1347 defined Textual Convention. 1349 12.1.1.1. Sub-typing of Textual Conventions 1351 The SYNTAX clause of a TEXTUAL CONVENTION macro may be sub-typed in the 1352 same way as the SYNTAX clause of an OBJECT-TYPE macro. 1354 13. Extending a PIB Module 1356 The SMI's rules for extending an information module are augmented with 1357 the following rules: 1359 13.1. OBJECT-TYPE Definitions 1361 An invocation of the OBJECT-TYPE macro may also be revised in any of the 1362 following ways: 1364 - An INSTALL-ERRORS clause may be added or an existing INSTALL-ERRORS 1365 clause have additional errors defined. 1367 - Additional named-number enumerations may be added to a SUBJECT- 1368 CATEGORIES clause. 1370 Draft SPPI November 2000 1372 14. Appendix A: Mapping a PIB to a MIB 1374 Since the SPPI is modelled on the SMI, a PIB can be easily and 1375 algorithmically mapped into a MIB. This mapping is achieved by means of 1376 the following rules: 1378 - Modify the module's module name by appending "-MIB" to the name. 1380 - Change the OID assigned to the MODULE-IDENTITY to be different 1381 value. 1383 - Replace the keyword PIB-DEFINITIONS with the keyword DEFINITIONS. 1385 - Modify the module names of all external references to PIB modules 1386 by appending "-MIB" to each such module name. 1388 - For each PRC definition, if an INDEX clause is absent, change the 1389 "PIB-INDEX" keyword to "INDEX"; otherwise, delete the PIB-INDEX 1390 clause. 1392 - Delete all of the following clauses: PIB-ACCESS, PIB-REFERENCES, 1393 PIB-TAG, UNIQUENESS, INSTALL-ERRORS, and SUBJECT-CATEGORIES. 1395 - Change all PIB-MIN-ACCESS clauses to MIN-ACCESS clauses, modifying 1396 "install" and "install-notify" to "read-create", and "notify" to 1397 "read-only". 1399 - Add a MAX-ACCESS clause for each OBJECT-TYPE. For each table 1400 definition and row definition, the MAX-ACCESS is "not-accessible". 1401 For each attribute that is in the INDEX clause, the MAX-ACCESS is 1402 "not-accessible". For the remaining attributes, the MAX-ACCESS is 1403 "read-create". 1405 - Add a columnar attribute of type RowStatus with a descriptor and 1406 appropriate DESCRIPTION. The descriptor can be formed by appending 1407 the nine characters "RowStatus" to the end of the PRC's descriptor 1408 (truncated if necessary to avoid the resulting descriptor being too 1409 long). The optional number provided by the PIB-ACCESS clause is 1410 used as the OID for this columnar attribute. If no number is 1411 provided by the PIB-ACCESS clause, then the default number 127 is 1412 used. 1414 - Modify any SYNTAX clause which has a base data type which is not 1415 allowed in the SMI, either to be a valid SMI data type or to omit 1416 the OBJECT-TYPE or TEXTUAL-CONVENTION definition and all references 1418 Draft SPPI November 2000 1420 to it. Since it is not clear (at this time) which is the best SMI 1421 data type to use, the conversion SHOULD provide a configurable 1422 option allowing a choice from at least the following: 1424 - convert to an OCTET STRING of the relevant size. 1425 Specifically, this option would map both Integer64 and 1426 Unsigned64 to OCTET STRING (SIZE(8)), or 1428 - omit them from the conversion, or 1430 - map Integer64 and Unsigned64 to Counter64 (even though this 1431 has problems representing negative numbers, and unwanted 1432 counter semantics.) 1434 Draft SPPI November 2000 1436 15. Appendix B: Example usage of PIB-REFERENCE and PIB-TAG clauses 1438 The following example demonstrates the use of the PIB-REFERENCE and PIB- 1439 TAG clauses. 1441 In this example, the PIB-REFERENCE clause is used by the 1442 qosIfDscpMapQueue attribute to indicate the PRC of which it references 1443 an instance, and similarly, by the qosIfDscpMapThresh attribute. 1445 The qosIfDscpMapTable PRC has an instance for each DSCP of a particular 1446 "map", but there is no PRC defined for a map itself; rather, a map 1447 consists of all instances of qosIfDscpMapTable which have the same value 1448 of qosIfDscpMapMapId. That is, a tag list is formed by all instances of 1449 qosIfDscpMapTable which have the same value of qosIfDscpMapMapId. This 1450 tag list is referenced by the attribute qosIfDscpAssignDscpMap, and its 1451 use of the PIB-TAG clause indicates this. 1453 qosIfDscpAssignTable OBJECT-TYPE 1454 SYNTAX SEQUENCE OF QosIfDscpAssignEntry 1455 PIB-ACCESS install 1456 STATUS current 1457 DESCRIPTION " " 1458 ::= { qosIfParameters 9 } 1460 qosIfDscpAssignEntry OBJECT-TYPE 1461 SYNTAX QosIfDscpAssignEntry 1462 STATUS current 1463 DESCRIPTION 1464 "An instance of the qosIfDscpAssign class." 1465 PIB-INDEX { qosIfDscpAssignPrid } 1466 UNIQUENESS { qosIfDscpAssignName, qosIfDscpAssignRoles } 1467 ::= { qosIfDscpAssignTable 1 } 1469 QosIfDscpAssignEntry ::= SEQUENCE { 1470 qosIfDscpAssignPrid InstanceId, 1471 qosIfDscpAssignName SnmpAdminString, 1472 qosIfDscpAssignRoles RoleCombination, 1473 qosIfDscpAssignDscpMap TagReferenceId 1474 } 1476 qosIfDscpAssignDscpMap OBJECT-TYPE 1477 SYNTAX TagReferenceId 1478 PIB-TAG qosIfDscpMapMapId -- attribute defined below 1479 STATUS current 1480 DESCRIPTION 1482 Draft SPPI November 2000 1484 "The DSCP map which is applied to interfaces of type 1485 qosIfDscpAssignName which have a role combination of 1486 qosIfDscpAssignRoles." 1487 ::= { qosIfDscpAssignEntry 3 } 1489 -- 1490 -- DSCP to Queue and Threshold Mapping Table 1491 -- 1493 qosIfDscpMapTable OBJECT-TYPE 1494 SYNTAX SEQUENCE OF QosIfDscpMapEntry 1495 PIB-ACCESS install 1496 STATUS current 1497 DESCRIPTION 1498 "Assigns DSCP values to queues and thresholds for an arbitrary 1499 DSCP map. This map can then be assigned to various interface 1500 and role combination pairs." 1501 ::= { qosIfParameters 10 } 1503 qosIfDscpMapEntry OBJECT-TYPE 1504 SYNTAX QosIfDscpMapEntry 1505 STATUS current 1506 DESCRIPTION 1507 "An instance of the qosIfDscpMap class." 1508 PIB-INDEX { qosIfDscpMapPrid } 1509 UNIQUENESS { qosIfDscpMapMapId, qosIfDscpMapDscp } 1510 ::= { qosIfDscpMapTable 1 } 1512 QosIfDscpMapEntry ::= SEQUENCE { 1513 qosIfDscpMapPrid InstanceId, 1514 qosIfDscpMapMapId TagId, 1515 qosIfDscpMapDscp Dscp, 1516 qosIfDscpMapQueue ReferenceId, 1517 qosIfDscpMapThresh ReferenceId 1518 } 1520 qosIfDscpMapMapId OBJECT-TYPE 1521 SYNTAX TagId 1522 STATUS current 1523 DESCRIPTION 1524 "An integer that identifies the DSCP map to which this PRI 1525 belongs." 1526 ::= { qosIfDscpMapEntry 2 } 1528 qosIfDscpMapQueue OBJECT-TYPE 1529 Draft SPPI November 2000 1531 SYNTAX ReferenceId 1532 PIB-REFERENCE qosIfQueueTable 1533 STATUS current 1534 DESCRIPTION 1535 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1536 the queue identified by qosIfQueuePrid in qosIfQueueTable. 1537 For a given DSCP map, all the queues must belong to a single 1538 queue set." 1539 ::= { qosIfDscpMapEntry 4 } 1541 qosIfDscpMapThresh OBJECT-TYPE 1542 SYNTAX ReferenceId 1543 PIB-REFERENCE qosIfThresholdTable 1544 STATUS current 1545 DESCRIPTION 1546 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1547 the threshold identified by qosIfThresholdId in 1548 qosIfThresholdTable. The threshold set to which this 1549 threshold belongs must be assigned to the queue specified by 1550 qosIfDscpMapQueue." 1551 ::= { qosIfDscpMapEntry 5 } 1553 Draft SPPI November 2000 1555 16. Security Considerations 1557 This document defines a language with which to define provisioning 1558 information. The language itself has no security impact on the 1559 Internet. 1561 17. Authors' Addresses 1563 Keith McCloghrie 1564 Cisco Systems, Inc. 1565 170 West Tasman Drive 1566 San Jose, CA 95134-1706 USA 1567 Phone: +1 408 526 5260 1568 Email: kzm@cisco.com 1570 Michael Fine 1571 Cisco Systems, Inc. 1572 170 West Tasman Drive 1573 San Jose, CA 95134-1706 USA 1574 Phone: +1 408 527 8218 1575 Email: mfine@cisco.com 1577 John Seligson 1578 Nortel Networks, Inc. 1579 4401 Great America Parkway 1580 Santa Clara, CA 95054 USA 1581 Phone: +1 408 495 2992 1582 Email: jseligso@nortelnetworks.com 1584 Kwok Ho Chan 1585 Nortel Networks, Inc. 1586 600 Technology Park Drive 1587 Billerica, MA 01821 USA 1588 Phone: +1 978 288 8175 1589 Email: khchan@nortelnetworks.com 1591 Scott Hahn 1592 Intel 1593 2111 NE 25th Avenue 1594 Hillsboro, OR 97124 USA 1595 Phone: +1 503 264 8231 1596 Email: scott.hahn@intel.com 1598 Draft SPPI November 2000 1600 Ravi Sahita 1601 Intel 1602 2111 NE 25th Avenue 1603 Hillsboro, OR 97124 USA 1604 Phone: +1 503 712 1554 1605 Email: ravi.sahita@intel.com 1607 Andrew Smith 1608 Allegro Networks 1609 6399 San Ignacio Ave. 1610 San Jose 1611 CA 95119 1612 FAX: 415 345 1827 1613 Email: andrew@allegronetworks.com 1615 Francis Reichmeyer 1616 PFN Inc. 1617 University Park at MIT 1618 26 Landsdowne Street 1619 Cambridge, MA 02139 1620 Phone: +1 617 494 9980 1621 Email: franr@pfn.com 1623 18. References 1625 [COPS] 1626 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1627 Sastry, "The COPS (Common Open Policy Service) Protocol" RFC 2748, 1628 January 2000. 1630 [COPS-RSVP] 1631 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1632 Sastry, " COPS usage for RSVP", RFC 2749, January 2000. 1634 [COPS-PR] 1635 Reichmeyer, F., Herzog, S., Chan, K., Durham, D., Yavatkar, R. 1636 Gai, S., McCloghrie, K. and A. Smith, "COPS Usage for Policy 1637 Provisioning" Internet Draft, draft-ietf-rap-cops-pr-04.txt, August 1638 2000. 1640 [SMI] 1641 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1642 and S. Waldbusser. "Structure of Management Information Version 2 1643 (SMIv2)", RFC 2578, April 1999. 1645 Draft SPPI November 2000 1647 [TC] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1648 and S. Waldbusser. "Textual Conventions for SMIv2", RFC 2579, 1649 April 1999. 1651 [CONF] 1652 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1653 and S. Waldbusser. "Conformance Statements for SMIv2", RFC 2580, 1654 April 1999. 1656 [APPL] 1657 Levi, D., Meyer, P., and B. Stewart, "SNMP Applications", RFC 2573, 1658 April 1999. 1660 [ASN1] 1661 Information processing systems -- Open Systems Interconnection -- 1662 Specification of Abstract Syntax Notation One (ASN.1), 1663 International Organization for Standardization. International 1664 Standard 8824, December 1987. 1666 Draft SPPI November 2000 1668 19. Full Copyright Statement 1670 Copyright (C) The Internet Society (2000). All Rights Reserved. 1672 This document and translations of it may be copied and furnished to 1673 others, and derivative works that comment on or otherwise explain it or 1674 assist in its implementation may be prepared, copied, published and 1675 distributed, in whole or in part, without restriction of any kind, 1676 provided that the above copyright notice and this paragraph are included 1677 on all such copies and derivative works. However, this document itself 1678 may not be modified in any way, such as by removing the copyright notice 1679 or references to the Internet Society or other Internet organizations, 1680 except as needed for the purpose of developing Internet standards in 1681 which case the procedures for copyrights defined in the Internet 1682 Standards process must be followed, or as required to translate it into 1683 languages other than English. 1685 The limited permissions granted above are perpetual and will not be 1686 revoked by the Internet Society or its successors or assigns. 1688 This document and the information contained herein is provided on an "AS 1689 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 1690 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 1691 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 1692 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 1693 FITNESS FOR A PARTICULAR PURPOSE." 1694 Draft SPPI November 2000 1696 Table of Contents 1698 1 Introduction .................................................... 2 1699 1.1 Change Log .................................................... 2 1700 1.1.1 Changes made in version published on 13 July 2000 ........... 2 1701 1.1.2 Changes made in version published on 20 September 2000 ...... 3 1702 1.1.3 Changes made in version published on 13 November 2000 ....... 4 1703 2 Use of the SMI .................................................. 5 1704 2.1 Terminology Translation ....................................... 5 1705 2.2 Overview ...................................................... 5 1706 3 Structure of this Specification ................................. 6 1707 4 Definitions ..................................................... 7 1708 5 PIB Modules ..................................................... 20 1709 5.1 Importing Definitions ......................................... 20 1710 5.2 Reserved Keywords ............................................. 20 1711 6 Naming Hierarchy ................................................ 21 1712 7 Mapping of the MODULE-IDENTITY macro ............................ 21 1713 7.1 Mapping of the SUBJECT-CATEGORIES clause ...................... 21 1714 8 Mapping of the OBJECT-TYPE macro ................................ 22 1715 8.1 Mapping of the SYNTAX clause .................................. 22 1716 8.1.1 Counter32 ................................................... 22 1717 8.1.2 Gauge32 ..................................................... 23 1718 8.1.3 Opaque ...................................................... 23 1719 8.1.4 Counter64 ................................................... 23 1720 8.1.5 Integer64 ................................................... 23 1721 8.1.6 Unsigned64 .................................................. 23 1722 8.1.7 Provisioning Classes ........................................ 23 1723 8.2 Mapping of the MAX-ACCESS clause .............................. 24 1724 8.3 Mapping of the PIB-ACCESS clause .............................. 24 1725 8.4 Mapping of the INSTALL-ERRORS clause .......................... 25 1726 8.5 Mapping of the PIB-INDEX clause ............................... 25 1727 8.6 Mapping of the INDEX clause ................................... 26 1728 8.7 Mapping of the AUGMENTS clause ................................ 26 1729 8.8 Mapping of the EXTENDS clause ................................. 26 1730 8.8.1 Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1731 .............................................................. 27 1732 8.9 Mapping of the UNIQUENESS clause .............................. 27 1733 8.10 Mapping of the PIB-REFERENCES clause ......................... 28 1734 8.11 Mapping of the PIB-TAG clause ................................ 28 1735 9 Mapping of the OBJECT-IDENTITY macro ............................ 28 1736 10 Mapping of the OBJECT-GROUP macro .............................. 29 1737 10.1 Mapping of the OBJECTS clause ................................ 29 1738 11 Mapping of the MODULE-COMPLIANCE macro ......................... 29 1739 11.1 Mapping of the MODULE clause ................................. 29 1740 Draft SPPI November 2000 1742 11.1.1 Mapping of the MANDATORY-GROUPS clause ..................... 29 1743 11.1.2 Mapping of the GROUP clause ................................ 30 1744 11.1.3 Mapping of the OBJECT clause ............................... 30 1745 11.1.3.1 Mapping of the SYNTAX clause ............................. 30 1746 11.1.3.2 Mapping of the WRITE-SYNTAX clause ....................... 31 1747 11.1.3.3 Mapping of the PIB-MIN-ACCESS clause ..................... 31 1748 12 Textual Conventions ............................................ 31 1749 12.1 Mapping of the TEXTUAL-CONVENTION macro ...................... 31 1750 12.1.1 Mapping of the SYNTAX clause ............................... 32 1751 12.1.1.1 Sub-typing of Textual Conventions ........................ 32 1752 13 Extending a PIB Module ......................................... 32 1753 13.1 OBJECT-TYPE Definitions ...................................... 32 1754 14 Appendix A: Mapping a PIB to a MIB ............................. 33 1755 15 Appendix B: Example usage of PIB-REFERENCE and PIB-TAG claus- 1756 es ........................................................... 35 1757 16 Security Considerations ........................................ 38 1758 17 Authors' Addresses ............................................. 38 1759 18 References ..................................................... 39 1760 19 Full Copyright Statement ....................................... 41