idnits 2.17.1 draft-ietf-rap-sppi-02.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 1405: '..., 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 1709 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 (20 September 2000) is 8619 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 332, but not defined == Missing Reference: 'APPLICATION 2' is mentioned on line 337, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 342, but not defined == Missing Reference: 'APPLICATION 7' is mentioned on line 351, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 355, 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 No Affiliation 12 F. Reichmeyer 13 PFN 15 20 September 2000 17 Structure of Policy Provisioning Information (SPPI) 19 draft-ietf-rap-sppi-02.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 September 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 September 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 September 2000 139 2. Use of the SMI 141 The SPPI and PIB modules are based on SNMP's SMI and MIB modules, which 142 use an adapted subset of the ASN.1 data definition language [ASN1]. The 143 decision to base the definition of PIB modules on this format allows for 144 the leveraging of the community's knowledge, experience and tools of the 145 SMI and MIB modules. 147 2.1. Terminology Translation 149 The SMI uses the term "managed objects" to refer to object types, both 150 tabular types with descriptors such as xxxTable and xxxEntry, as well as 151 scalar and columnar object types. The SPPI does not use the term 152 "object" so as to avoid confusion with COPS protocol objects. Instead, 153 the SPPI uses the term Provisioning Class (PRC) for the table and row 154 definitions (the xxxTable and xxxEntry objects, respectively), and 155 Provisioning Instance (PRI) for an instantiation of a row definition. 156 For a columnar object of a table definition, the SPPI uses the term 157 "attribute" of a Provisioning Class. (The SPPI does not support the 158 equivalent of the SMI's scalar objects.) 160 2.2. Overview 162 SNMP's SMI is divided into five parts: module definitions, object 163 definitions, notification definitions [SMI], textual convention 164 definitions [TC] and conformance definitions [CONF]. 166 - The SMI's MODULE-IDENTITY macro is used to convey the semantics of 167 a MIB module. The SPPI uses this macro to convey the semantics of 168 a PIB module. 170 - The SMI's OBJECT-TYPE macro is used to convey the syntax and 171 semantics of managed objects. The SPPI uses this macro to convey 172 the syntax and semantics of PRCs and their attributes. 174 - The SMI's notification definitions are not used (at this time) by 175 the SPPI. 177 - The SMI's TEXTUAL CONVENTION macro allows new data types to be 178 defined. The SPPI uses this macro to define new data types having 179 particular syntax and semantics which is common to several 180 attributes of one of more PRCs. 182 - The SMI's conformance definitions define several macros: the 183 OBJECT-GROUP macro, the NOTIFICATION-GROUP macro, the MODULE- 185 Draft SPPI September 2000 187 COMPLIANCE macro and the AGENT-CAPABILITIES macro. The SPPI uses 188 the OBJECT-GROUP and MODULE-COMPLIANCE macros to specify acceptable 189 lower-bounds of implementation of the attributes of PRCs, and 190 thereby indirectly, acceptable lower-bounds of implementation of 191 the PRCs themselves. The NOTIFICATION-GROUP macro is not used (at 192 this time) by the SPPI. Potential usage by the SPPI of the AGENT- 193 CAPABILITIES macro is for further study. 195 3. Structure of this Specification 197 The SMI is specified in terms of an ASN.1 definition together with 198 descriptive text for each element introduced in that ASN.1 definition. 199 This document specifies the SPPI also via a ASN.1 definition, which is a 200 modified version of the SMI's definition, together with descriptive text 201 for only those elements in the SPPI's ASN.1 definition which have 202 differences from the SMI's. For elements in the ASN.1 definition which 203 have no descriptive text in this specification, the reader is referred 204 to the SMI's descriptive text for that element. 206 Draft SPPI September 2000 208 4. Definitions 210 COPS-PR-SPPI DEFINITIONS ::= BEGIN 212 IMPORTS ObjectName, SimpleSyntax, ExtUTCTime 213 FROM SNMPv2-SMI; 215 -- definitions for PIB modules 217 MODULE-IDENTITY MACRO ::= 218 BEGIN 219 TYPE NOTATION ::= 220 SubjectPart -- new 221 "LAST-UPDATED" value(Update ExtUTCTime) 222 "ORGANIZATION" Text 223 "CONTACT-INFO" Text 224 "DESCRIPTION" Text 225 RevisionPart 227 VALUE NOTATION ::= 228 value(VALUE OBJECT IDENTIFIER) 230 SubjectPart ::= -- new 231 "SUBJECT-CATEGORIES" "{" Categories "}" 232 Categories ::= -- new 233 CategoryIDs 234 | "all" 235 CategoryIDs ::= -- new 236 CategoryID 237 | CategoryIDs "," CategoryID 238 CategoryID ::= -- new 239 identifier "(" number ")" -- number is positive 241 RevisionPart ::= 242 Revisions 243 | empty 244 Revisions ::= 245 Revision 246 | Revisions Revision 247 Revision ::= 248 "REVISION" value(Update ExtUTCTime) 249 "DESCRIPTION" Text 251 Draft SPPI September 2000 253 -- a character string as defined in [SMI] 254 Text ::= value(IA5String) 255 END 257 -- 259 OBJECT-IDENTITY MACRO ::= 260 BEGIN 261 TYPE NOTATION ::= 262 "STATUS" Status 263 "DESCRIPTION" Text 264 ReferPart 266 VALUE NOTATION ::= 267 value(VALUE OBJECT IDENTIFIER) 269 Status ::= 270 "current" 271 | "deprecated" 272 | "obsolete" 274 ReferPart ::= 275 "REFERENCE" Text 276 | empty 278 -- a character string as defined in [SMI] 279 Text ::= value(IA5String) 280 END 282 -- syntax of attributes 284 -- the "base types" defined here are: 285 -- 3 built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER 286 -- 6 application-defined types: Integer32, IpAddress, Unsigned32, 287 -- TimeTicks, Integer64 and Unsigned64 289 ObjectSyntax ::= 290 CHOICE { 291 simple 292 SimpleSyntax, 294 -- note that SEQUENCEs for table and row definitions 295 -- are not mentioned here... 297 Draft SPPI September 2000 299 application-wide 300 ApplicationSyntax 301 } 303 -- application-wide types 305 ApplicationSyntax ::= 306 CHOICE { 307 ipAddress-value 308 IpAddress, 310 timeticks-value 311 TimeTicks, 313 unsigned-integer-value 314 Unsigned32, 316 large-integer-value -- new 317 Integer64, 319 large-unsigned-integer-value -- new 320 Unsigned64 321 } 323 -- the following 4 types are copied from the SMI 325 -- indistinguishable from INTEGER, but never needs more than 326 -- 32-bits for a two's complement representation 327 Integer32 ::= 328 INTEGER (-2147483648..2147483647) 330 -- (this is a tagged type for historical reasons) 331 IpAddress ::= 332 [APPLICATION 0] 333 IMPLICIT OCTET STRING (SIZE (4)) 335 -- an unsigned 32-bit quantity 336 Unsigned32 ::= 337 [APPLICATION 2] 338 IMPLICIT INTEGER (0..4294967295) 340 -- hundredths of seconds since an epoch 341 TimeTicks ::= 342 [APPLICATION 3] 344 Draft SPPI September 2000 346 IMPLICIT INTEGER (0..4294967295) 348 -- the following 2 types are not present in the SMI 350 Integer64 ::= 351 [APPLICATION 7] 352 IMPLICIT INTEGER (-9223372036854775808..9223372036854775807) 354 Unsigned64 355 [APPLICATION 8] 356 IMPLICIT INTEGER (0..18446744073709551615) 358 -- definition for Provisioning Classes and their attributes 359 -- (differences from the SMI are noted in the ASN.1 comments) 361 OBJECT-TYPE MACRO ::= 362 BEGIN 363 TYPE NOTATION ::= 364 "SYNTAX" Syntax 365 UnitsPart 366 "PIB-ACCESS" AccessPart -- modified 367 PibReferencesPart -- new 368 PibTagPart -- new 369 "STATUS" Status 370 "DESCRIPTION" Text 371 ErrorsPart -- new 372 ReferPart 373 IndexPart -- modified 374 MibIndexPart -- modified 375 UniquePart -- new 376 DefValPart 378 VALUE NOTATION ::= 379 value(VALUE ObjectName) 381 Syntax ::= -- Must be one of the following: 382 -- a base type (or its refinement), 383 -- a textual convention (or its refinement), or 384 -- a BITS pseudo-type 385 type 386 | "BITS" "{" NamedBits "}" 388 NamedBits ::= NamedBit 389 | NamedBits "," NamedBit 391 Draft SPPI September 2000 393 NamedBit ::= identifier "(" number ")" -- number is nonnegative 395 UnitsPart ::= 396 "UNITS" Text 397 | empty 399 AccessPart ::= -- new 400 Access 401 | Access "," number -- number is positive 403 Access ::= -- modified 404 "install" 405 | "notify" 406 | "install-notify" 408 Status ::= 409 "current" 410 | "deprecated" 411 | "obsolete" 413 ErrorsPart ::= -- new 414 "INSTALL-ERRORS" "{" Errors "}" 415 | empty 417 Errors ::= -- new 418 Error 419 | Errors "," Error 420 Error ::= -- new 421 identifier "(" number ")" -- number is positive 423 ReferPart ::= 424 "REFERENCE" Text 425 | empty 427 IndexPart ::= 428 "PIB-INDEX" "{" Index "}" -- new 429 | "AUGMENTS" "{" Entry "}" 430 | "EXTENDS" "{" Entry "}" -- new 431 | empty 432 Index ::= 433 -- the correspondent OBJECT-TYPE invocation 434 value(ObjectName) 435 Entry ::= 436 -- use the INDEX value of the 437 -- correspondent OBJECT-TYPE invocation 439 Draft SPPI September 2000 441 value(ObjectName) 442 MibIndexPart ::= 443 "INDEX" "{" IndexTypePart "}" 444 | empty 445 IndexTypePart ::= 446 IndexTypes 447 | IndexTypes "," ImpliedIndex 448 | ImpliedIndex 449 IndexTypes ::= 450 Index 451 | IndexTypes "," Index 452 ImpliedIndex ::= 453 "IMPLIED" Index 455 PibReferencesPart ::= 456 -- for use with ReferenceId TC 457 "PIB-REFERENCES" "{" Entry "}" 458 | empty 460 PibTagPart ::= 461 -- for use with TagReferenceId TC 462 "PIB-TAG" "{" Attr "}" 463 | empty 465 Attr ::= -- specifies an attribute 466 value(ObjectName) 468 UniquePart ::= -- new 469 "UNIQUENESS" "{" UniqueTypes "}" 470 | "UNIQUENESS" "{" "}" 471 | empty 472 UniqueTypes ::= 473 UniqueType 474 | UniqueTypes "," UniqueType 475 UniqueType ::= 476 -- the correspondent OBJECT-TYPE invocation 477 value(ObjectName) 479 DefValPart ::= "DEFVAL" "{" Defvalue "}" 480 | empty 482 Defvalue ::= -- must be valid for the type specified in 483 -- SYNTAX clause of same OBJECT-TYPE macro 484 value(ObjectSyntax) 486 Draft SPPI September 2000 488 | "{" BitsValue "}" 490 BitsValue ::= BitNames 491 | empty 493 BitNames ::= BitName 494 | BitNames "," BitName 496 BitName ::= identifier 498 -- a character string as defined in [SMI] 499 Text ::= value(IA5String) 500 END 502 -- definitions for conformance groups 504 OBJECT-GROUP MACRO ::= 505 BEGIN 506 TYPE NOTATION ::= 507 ObjectsPart 508 "STATUS" Status 509 "DESCRIPTION" Text 510 ReferPart 512 VALUE NOTATION ::= 513 value(VALUE OBJECT IDENTIFIER) 515 ObjectsPart ::= 516 "OBJECTS" "{" Objects "}" 517 Objects ::= 518 Object 519 | Objects "," Object 520 Object ::= 521 value(ObjectName) 523 Status ::= 524 "current" 525 | "deprecated" 526 | "obsolete" 528 ReferPart ::= 529 "REFERENCE" Text 530 | empty 532 Draft SPPI September 2000 534 -- a character string as defined in [SMI] 535 Text ::= value(IA5String) 536 END 538 -- definitions for compliance statements 540 MODULE-COMPLIANCE MACRO ::= 541 BEGIN 542 TYPE NOTATION ::= 543 "STATUS" Status 544 "DESCRIPTION" Text 545 ReferPart 546 ModulePart 548 VALUE NOTATION ::= 549 value(VALUE OBJECT IDENTIFIER) 551 Status ::= 552 "current" 553 | "deprecated" 554 | "obsolete" 556 ReferPart ::= 557 "REFERENCE" Text 558 | empty 560 ModulePart ::= 561 Modules 562 Modules ::= 563 Module 564 | Modules Module 565 Module ::= 566 -- name of module -- 567 "MODULE" ModuleName 568 MandatoryPart 569 CompliancePart 571 ModuleName ::= 572 -- identifier must start with uppercase letter 573 identifier ModuleIdentifier 574 -- must not be empty unless contained 575 -- in MIB Module 576 | empty 577 ModuleIdentifier ::= 579 Draft SPPI September 2000 581 value(OBJECT IDENTIFIER) 582 | empty 584 MandatoryPart ::= 585 "MANDATORY-GROUPS" "{" Groups "}" 586 | empty 588 Groups ::= 589 Group 590 | Groups "," Group 591 Group ::= 592 value(OBJECT IDENTIFIER) 594 CompliancePart ::= 595 Compliances 596 | empty 598 Compliances ::= 599 Compliance 600 | Compliances Compliance 601 Compliance ::= 602 ComplianceGroup 603 | Object 605 ComplianceGroup ::= 606 "GROUP" value(OBJECT IDENTIFIER) 607 "DESCRIPTION" Text 609 Object ::= 610 "OBJECT" value(ObjectName) 611 InstallSyntaxPart -- modified 612 AccessPart 613 "DESCRIPTION" Text 615 -- must be a refinement for object's SYNTAX clause 616 InstallSyntaxPart ::= "SYNTAX" Syntax 617 | empty 619 Syntax ::= -- Must be one of the following: 620 -- a base type (or its refinement), 621 -- a textual convention (or its refinement), or 622 -- a BITS pseudo-type 623 type 624 | "BITS" "{" NamedBits "}" 626 Draft SPPI September 2000 628 NamedBits ::= NamedBit 629 | NamedBits "," NamedBit 631 NamedBit ::= identifier "(" number ")" -- number is nonnegative 633 AccessPart ::= 634 "PIB-MIN-ACCESS" Access -- modified 635 | empty 636 Access ::= -- modified 637 "not-accessible" 638 | "install" 639 | "notify" 640 | "install-notify" 642 -- a character string as defined in [SMI] 643 Text ::= value(IA5String) 644 END 646 -- definition of textual conventions 648 TEXTUAL-CONVENTION MACRO ::= 649 BEGIN 650 TYPE NOTATION ::= 651 DisplayPart 652 "STATUS" Status 653 "DESCRIPTION" Text 654 ReferPart 655 "SYNTAX" Syntax 657 VALUE NOTATION ::= 658 value(VALUE Syntax) -- adapted ASN.1 660 DisplayPart ::= 661 "DISPLAY-HINT" Text 662 | empty 664 Status ::= 665 "current" 666 | "deprecated" 667 | "obsolete" 669 ReferPart ::= 670 "REFERENCE" Text 671 | empty 673 Draft SPPI September 2000 675 -- a character string as defined in [SMI] 676 Text ::= value(IA5String) 678 Syntax ::= -- Must be one of the following: 679 -- a base type (or its refinement), or 680 -- a BITS pseudo-type 681 type 682 | "BITS" "{" NamedBits "}" 684 NamedBits ::= NamedBit 685 | NamedBits "," NamedBit 687 NamedBit ::= identifier "(" number ")" -- number is nonnegative 689 END 691 END 692 Draft SPPI September 2000 694 COPS-PR-SPPI-TC PIB-DEFINITIONS ::= BEGIN 696 IMPORTS Unsigned32, MODULE-IDENTITY, TEXTUAL-CONVENTION 697 FROM COPS-PR-SPPI; 699 copsPrSppiTc MODULE-IDENTITY 700 SUBJECT-CATEGORIES { all } 701 LAST-UPDATED "200009201800Z" 702 ORGANIZATION "IETF RAP WG" 703 CONTACT-INFO "Keith McCloghrie 704 Cisco Systems, Inc. 705 170 West Tasman Drive, 706 San Jose, CA 95134-1706 USA 707 Phone: +1 408 526 5260 708 Email: kzm@cisco.com 710 Ravi Sahita 711 Intel 712 2111 NE 25th Avenue 713 Hillsboro, OR 97124 USA 714 Phone: +1 503 712 1554 715 Email: ravi.sahita@intel.com " 716 DESCRIPTION 717 "The PIB module containing a set of Textual Conventions 718 which have general applicability to all PIB modules." 719 REVISION "200009201800Z" 720 DESCRIPTION 721 "Initial version, published in RFC xxxx." 722 ::= { tbd } 724 InstanceId ::= TEXTUAL-CONVENTION 725 STATUS current 726 DESCRIPTION 727 "The textual convention for use by an attribute which is used 728 as the instance-identifying index of a PRC, i.e., an attribute 729 named in a PIB-INDEX clause. The value of an attribute with this 730 syntax is always greater than zero. PRIs of the same PRC need 731 not have contiguous values for their instance-identifying 732 attribute." 733 SYNTAX Unsigned32 (1..4294967295) 735 ReferenceId ::= TEXTUAL-CONVENTION 736 STATUS current 737 DESCRIPTION 738 "A textual convention for use by an attribute which is used as 740 Draft SPPI September 2000 742 a pointer in order to reference an instance of a particular 743 PRC. An attribute with this syntax must not be used in a 744 PIB-INDEX clause , and its description must specify the 745 particular PRC to which the referenced PRI will belong. 746 For an attribute of this type, the referenced PRI must exist. 747 Furthermore, it is an error to try to delete a PRI that is 748 referenced by another instance without first deleting/modifying 749 the referencing instance. The definition of an attribute with 750 this syntax can permit the attribute to have a value of zero to 751 indicate that it is not currently pointing to an PRI." 752 SYNTAX Unsigned32 754 Prid ::= TEXTUAL-CONVENTION 755 STATUS current 756 DESCRIPTION 757 "Represents a pointer to a PRI, i.e,. to an instance of a 758 PRC. The value is the OID name of the PRC's row definition, 759 appended with one sub-identifier containing the value of the 760 InstanceId value for the referenced instance. The definition 761 of an attribute with this syntax can permit the attribute to 762 have a value of 0.0 to indicate that it is not currently 763 pointing to a PRI." 764 SYNTAX OBJECT IDENTIFIER 766 TagId ::= TEXTUAL-CONVENTION 767 STATUS current 768 DESCRIPTION 769 "Represents a tag value, such that all instances of a 770 particular PRC having the same tag value form a tag list. 771 A tag list is identified by the tag value shared by all 772 instances in that tag list." 773 SYNTAX Unsigned32 (1..4294967295) 775 TagReferenceId ::= TEXTUAL-CONVENTION 776 STATUS current 777 DESCRIPTION 778 "Represents a reference to a tag list of instances of a 779 particular PRC. The particular PRC must have an attribute 780 with the syntax of TagId. The tag list consists of 781 all instances which have the same value of the TagId 782 attribute. Reference to the tag list is via the attribute 783 with the syntax of TagReferenceId containing the tag 784 value which identifies the tag list." 785 SYNTAX Unsigned32 786 END 787 Draft SPPI September 2000 789 5. PIB Modules 791 The names of all standard PIB modules must be unique (but different 792 versions of the same module should have the same name). Developers of 793 enterprise PIB modules are encouraged to choose names for their modules 794 that will have a low probability of colliding with standard or other 795 enterprise modules. 797 The first line of a PIB module is: 799 PIB-MODULE-NAME PIB-DEFINITIONS ::= BEGIN 801 where PIB-MODULE-NAME is the module name. 803 Like the SMI, additional ASN.1 macros must not be defined in PIB 804 modules. 806 5.1. Importing Definitions 808 Like the SMI, a PIB module which needs to reference an external 809 definition, must use the IMPORTS statement to identify both the 810 descriptor and the module in which the descriptor is defined, where a 811 module is identified by its ASN.1 module name. 813 In particular, a PIB module imports each of the base data types that it 814 uses from COPS-PR-SPPI (defined in this document), and may import as 815 required from other PIB modules. A PIB module may import, from the SMI, 816 (subtree) OIDs for the purpose of defining new OIDs. A PIB module may 817 also import, from MIB modules, OID assignments as well as textual 818 convention definitions providing that their underlying syntax is 819 supported by the SPPI. However, the following must not be included in 820 an IMPORTS statement: 822 - named types defined by ASN.1 itself, specifically: INTEGER, OCTET 823 STRING, OBJECT IDENTIFIER, SEQUENCE, SEQUENCE OF type, 824 - the BITS construct. 826 For each ASN.1 macro that a PIB uses, it must import that macro's 827 definition from the COPS-PR-SPPI. 829 5.2. Reserved Keywords 831 In addition to the reserved keywords listed in the SMI, the following 832 must not be used as descriptors or module names: 834 Draft SPPI September 2000 836 EXTENDS INSTALL-ERRORS Integer64 PIB-MIN-ACCESS PIB-ACCESS 837 PIB-INDEX PIB-REFERENCES PIB-TAG SUBJECT-CATEGORIES UNIQUENESS 838 Unsigned64 840 6. Naming Hierarchy 842 The SPPI uses the same OBJECT IDENTIFIER naming hierarchy as the SMI. 843 That is, OIDs are typically assigned to PIB modules from the subtree 844 administered by the Internet Assigned Numbers Authority (IANA). 845 However, like the SMI, the SPPI does not prohibit the definition of PRCs 846 in other portions of the OID tree. 848 7. Mapping of the MODULE-IDENTITY macro 850 7.1. Mapping of the SUBJECT-CATEGORIES clause 852 The SUBJECT-CATEGORIES clause, which must be present, identifies one or 853 more categories of provisioning data for which this PIB module defines 854 provisioning information. For use with the COPS-PR protocol, the 855 individual subject categories are mapped to COPS Client Types [COPS-PR]. 856 The subject categories are identified either: 858 - via the keyword "all", indicating the PIB module defines 859 provisioning information relevant for all subject categories (and 860 thus, all COPS Client Types), or 862 - a list of named-number enumerations, where each number which must 863 be greater than zero, identifies a subject category, and is mapped 864 to the Client Type which is identified by that same number in the 865 COPS protocol. The namespace for these named numbers is global and 866 therefore the labels should be assigned consistently across PIB 867 modules. At present time, no more than one named-number 868 enumeration should be specified. 870 Note that the list of categories specified in a PIB module's SUBJECT- 871 CATEGORIES clause is not exclusive. That is, some other specification 872 might (e.g., at a future date) specify additional COPS Client Types to 873 which the module is relevant. 875 When a PIB module applies to multiple subject categories, that PIB 876 module exists in multiple virtual information stores, one for each 877 Client-Type. 879 Draft SPPI September 2000 881 8. Mapping of the OBJECT-TYPE macro 883 The SPPI requires that all attribute definitions be contained within a 884 PRC, i.e., within a table definition. 886 8.1. Mapping of the SYNTAX clause 888 The SYNTAX clause, which must be present within the definition of an 889 attribute, defines the abstract data structure of that attribute. The 890 data structure must be one of the following: a base type, the BITS 891 construct, or a textual convention. 893 The SYNTAX clause must also be present for the table and row definitions 894 of a PRC, and in this case must be a SEQUENCE OF or SEQUENCE (see 895 section 8.1.7 below). 897 The base types are an extended subset of the SMI's base types: 899 - built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER, 901 - application-defined types: Integer32, IpAddress, Unsigned32, 902 TimeTicks, Integer64 and Unsigned64. 904 A textual convention is a newly-defined type defined as a sub-type of a 905 base type [TC]. The value of an attribute whose syntax is defined using 906 a textual convention is encoded "on-the-wire" according to the textual 907 convention's underlying base type. 909 Note that the set of base types has been chosen so as to provide 910 sufficient variety of on-the-wire encodings for attribute values; base 911 types should contain a minimum of semantics. Semantics should, to the 912 extent possible, be incorporated into a data type through the use of a 913 textual convention. Thus, the IpAddress and TimeTicks data types should 914 really be defined as textual conventions because they contain semantics. 915 However, they are defined here as base types so as to avoid confusion 916 with the SMI which defines them as base types. 918 The differences from the SMI in the semantics of ObjectSyntax are now 919 described. 921 8.1.1. Counter32 923 The Counter32 type is not supported by the SPPI. 925 Draft SPPI September 2000 927 8.1.2. Gauge32 929 The Gauge32 type is not supported by the SPPI. 931 8.1.3. Opaque 933 The Opaque type is not supported by the SPPI. 935 8.1.4. Counter64 937 The Counter64 type is not supported by the SPPI. 939 8.1.5. Integer64 941 The Integer64 type represents integer-valued information between -2^63 942 and 2^63-1 inclusive (-9223372036854775808 to 9223372036854775807 943 decimal). While Integer64 may be sub-typed to be more constrained, if 944 the constraint results in all possible values being contained in the 945 range (-2147483648..2147483647), then the Integer32 type must be used 946 instead of Integer64. 948 8.1.6. Unsigned64 950 The Unsigned64 type represents integer-valued information between 0 and 951 2^64-1 inclusive (0 to 18446744073709551615 decimal). While Unsigned64 952 may be sub-typed to be more constrained, if the constraint results in 953 all possible values being contained in the range (0..4294967295), then 954 the Unsigned32 type must be used instead of Unsigned64. 956 8.1.7. Provisioning Classes 958 The operations (on PIBs) supported by the SPPI apply exclusively to 959 PRCs. Each PRC is modelled as a tabular structure, i.e., a table. Each 960 instance of a particular PRC has the same set of attributes. The set of 961 attributes which belong to every instance of a particular PRC is 962 modelled as a row in the table. This model is formalized by using the 963 OBJECT-TYPE macro to define both: 965 - the PRC as a whole, called the table definition, and 967 - the characteristics of every instance of a particular PRC, called 968 the row definition. 970 In the table definition, the SYNTAX clause has the form: 972 Draft SPPI September 2000 974 SEQUENCE OF 976 where refers to the SEQUENCE type of its attribute 977 definitions. In the row definition, the SYNTAX clause has the form: 979 981 where is a SEQUENCE type defined as follows: 983 ::= SEQUENCE { , ... , } 985 where there is one for each attribute, and each is of the 986 form: 988 990 where is the descriptor naming an attribute, and 991 has the value of that attribute's SYNTAX clause, except that both sub- 992 typing information and the named values for enumerated integers or the 993 named bits for the BITS construct, are omitted from . 995 8.2. Mapping of the MAX-ACCESS clause 997 The MAX-ACCESS clause is not supported by the SPPI. 999 8.3. Mapping of the PIB-ACCESS clause 1001 The PIB-ACCESS clause must be present for a PRC's table definition, and 1002 must not be present for any other OBJECT-TYPE definition. The PIB- 1003 ACCESS clause defines what kind of access is appropriate for the PRC. 1004 The PIB-ACCESS clause also optionally (default value is 127) provides a 1005 number which is used in the algorithmic conversion of a PIB to a MIB 1006 (see Appendix A). 1008 - the value "install" is used to indicate a PRC which a PDP can 1009 install in the PEP as provisioning information. 1011 - the value "notify" is used to indicate a PRC for which the PEP must 1012 notify the PDP of all its instances and attribute values of that 1013 PRC. 1015 - the value "install-notify" is used to indicate the uncommon type of 1016 PRC which has both characteristics: "install" and "notify". 1018 Draft SPPI September 2000 1020 8.4. Mapping of the INSTALL-ERRORS clause 1022 The INSTALL-ERRORS clause, which may optionally be present for a PRC's 1023 table definition, and must be absent otherwise, lists one or more 1024 potential reasons for rejecting an install or a removal of an instance 1025 of the PRC. Each reason consists of a named-number enumeration, where 1026 the number represents a PRC-specific error-code to be used in a COPS 1027 protocol message, as the Sub-Error Code, with the Error-Code set to 1028 priSpecificError (see [COPS-PR]). The semantics of each named-number 1029 enumeration should be described in the PRC's DESCRIPTION clause. 1031 The numbers listed in an INSTALL-ERRORS must be greater than zero and 1032 less than 65536. If this clause is not present, an install/remove can 1033 still fail, but no PRC-specific error is available to be reported. 1035 8.5. Mapping of the PIB-INDEX clause 1037 The PIB-INDEX clause, which must be present for a row definition (unless 1038 an AUGMENTS or an EXTENDS clause is present instead), and must be absent 1039 otherwise, defines identification information for instances of the PRC. 1041 The PIB-INDEX clause includes exactly one descriptor. This descriptor 1042 specifies an attribute (typically, but not necessarily of the same PRC) 1043 which is used to identify an instance of that PRC. The syntax of this 1044 attribute is required to be InstanceId (a textual convention with an 1045 underlying syntax of Unsigned32), and it has no semantics other than its 1046 use in identifying the PRC instance. The OBJECT IDENTIFIER which 1047 identifies an instance of a PRC is formed by appending one sub- 1048 identifier to the OID which identifies that PRC's row definition. The 1049 value of the additional sub-identifier is that instance's value of the 1050 attribute specified in the INDEX clause. 1052 Note that SPPI does not permit use of the IMPLIED keyword in a PIB-INDEX 1053 clause. 1055 8.6. Mapping of the INDEX clause 1057 The INDEX clause is optionally present if a PIB-INDEX clause is present, 1058 and must be absent otherwise. If present, the INDEX clause can contain 1059 any number of attributes, and is used only by the algorithmic conversion 1060 of a PIB to a MIB (see Appendix A). 1062 An IMPLIED keyword can be present in an INDEX clause if so desired. 1064 Draft SPPI September 2000 1066 8.7. Mapping of the AUGMENTS clause 1068 The AUGMENTS clause, which must not be present except in row 1069 definitions, is an alternative to the PIB-INDEX clause and the EXTENDS 1070 clause. Every row definition has exactly one of: a PIB-INDEX clause, an 1071 AUGMENTS clause, or an EXTENDS clause. 1073 A row definition which has a PIB-INDEX clause is called a base row 1074 definition. A row definition which has an AUGMENTS clause is called a 1075 row augmentation, where the AUGMENTS clause names the base row 1076 definition which is augmented by this row augmentation. (Thus, a row 1077 augmentation cannot itself be augmented.) 1079 A PRC whose row definition is a row augmentation is called an augmenting 1080 PRC. Instances of an augmenting PRC are identified according to the 1081 PIB-INDEX clause of the base row definition named in the AUGMENTS 1082 clause. Further, instances of an augmenting PRC exist according to the 1083 same semantics as instances of the PRC which it augments. As such, when 1084 an instance of a PRC is installed or removed, an instance of every PRC 1085 which augments it is also installed or removed (for more details, see 1086 [COPS-PR]). 1088 8.8. Mapping of the EXTENDS clause 1090 The EXTENDS clause, which must not be present except in row definitions, 1091 is an alternative to the PIB-INDEX clause and the AUGMENTS clause. 1092 Every row definition has exactly one of: a PIB-INDEX clause, an AUGMENTS 1093 clause, or an EXTENDS clause. 1095 A row definition which has an EXTENDS clause is called a sparse row 1096 augmentation, where the EXTENDS clause names the row definition which is 1097 sparsely-augmented by this sparse row augmentation. The sparsely- 1098 augmented row can be a base row definition, or another sparse row 1099 augmentation. 1101 A PRC whose row definition is a sparse row augmentation is called a 1102 sparsely augmenting PRC. Instances of a sparsely augmenting PRC are 1103 identified according to the PIB-INDEX clause of the row definition named 1104 in the sparsely augmenting PRC's EXTENDS clause. 1106 An instance of a sparsely augmenting PRC can not exist unless a 1107 corresponding instance of the PRC which it sparsely augments exists. As 1108 such, when an instance of a PRC is removed, an instance of any PRC which 1109 sparsely augments it is also removed. However, an instance of a 1110 sparsely augmenting PRC need not exist when the corresponding instance 1111 Draft SPPI September 2000 1113 of the PRC that it sparsely augments exists. Thus, an instance of a 1114 sparsely augmenting PRC can be installed at the same time as or 1115 subsequent to the installation of, and can be removed prior to the 1116 removal of, the corresponding instance of the PRC that it sparsely 1117 augments. So, instances of a sparsely augmenting PRC must be installed 1118 explicitly, but are removed either implicitly (via removal of the 1119 augmented PRI) or explicitly. 1121 8.8.1. Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1123 When defining instance identification information for a PRC: 1125 - If there is a one-to-one correspondence between instances of this 1126 PRC and instances of an existing PRC, then the AUGMENTS clause 1127 should be used. 1129 - Otherwise, if there is a sparse relationship between instances of 1130 this PRC and instances of an existing PRC, then an EXTENDS clause 1131 should be used. 1133 - Otherwise, a PIB-INDEX clause should be used which names its own 1134 InstanceId attribute. 1136 8.9. Mapping of the UNIQUENESS clause 1138 The UNIQUENESS clause, which is optionally present for any row 1139 definition which has a PIB-INDEX clause, and must be absent otherwise, 1140 lists a set of zero or more of the PRC's attributes, for which no two 1141 instances of the PRC can have the same set of values. The specified set 1142 of attributes provide a necessary and sufficient set of values by which 1143 to identify an instance of this PRC. The attribute contained in the 1144 PIB-INDEX clause may not be present in the UNIQUENESS clause. By 1145 definition, an attribute may not appear more than once in a UNIQUENESS 1146 clause. A UNIQUENESS clause containing zero attributes indicates that 1147 it's possible for two instances of the PRC to have identical values for 1148 all attributes except, of course, for the one named in the PIB-INDEX 1149 clause. 1151 Even though the UNIQUENESS clause is optional, its inclusion is 1152 recommended wherever it provides useful information. 1154 Draft SPPI September 2000 1156 8.10. Mapping of the PIB-REFERENCES clause 1158 The PIB-REFERENCES clause, which must be present for any attribute which 1159 has the SYNTAX of ReferenceId, and must be absent otherwise, names the 1160 PRC, an instance of which is referenced by the ReferenceId attribute. 1161 For example usages of the PIB-REFERENCE clause, see Appendix B. 1163 8.11. Mapping of the PIB-TAG clause 1165 The PIB-TAG clause, which must be present for an attribute which has the 1166 SYNTAX TagReferenceId, and must be absent otherwise, is used to indicate 1167 that this attribute references a "tag list" of instances of another PRC. 1168 Such a tag list (similar in concept to the usage of the same term in 1169 [APPL]) is formed by all instances of the other PRC which have the same 1170 (tag) value of a particular attribute of that other PRC. The particular 1171 attribute of the other PRC, which must have the SYNTAX TagId, is named 1172 in the PIB-TAG clause. For an example usage of the PIB-TAG clause, see 1173 Appendix B. 1175 9. Mapping of the OBJECT-IDENTITY macro 1177 The OBJECT-IDENTITY macro is used in PIB modules to define information 1178 about an OBJECT IDENTIFIER assignment. 1180 10. Mapping of the OBJECT-GROUP macro 1182 For conformance purposes, it is useful to define a conformance group as 1183 a collection of related PRCs and their attributes. The OBJECT-GROUP 1184 macro (directly) defines the collection of attributes which belong to a 1185 conformance group. Since each attribute included in the collection 1186 belongs to a PRC, the collection of related PRCs which belong to a 1187 conformance group is also specified (indirectly) as the set of PRCs to 1188 which the included attributes belong. 1190 10.1. Mapping of the OBJECTS clause 1192 The OBJECTS clause, which must be present, is used to specify each 1193 attribute contained in the conformance group. Each of the specified 1194 attributes must be defined in the same PIB module as the OBJECT-GROUP 1195 macro appears. 1197 It is required that every attribute defined in a PIB module be contained 1198 in at least one conformance group. This avoids the common error of 1199 Draft SPPI September 2000 1201 adding a new attribute to a module and forgetting to add the new 1202 attribute to a group. 1204 11. Mapping of the MODULE-COMPLIANCE macro 1206 The MODULE-COMPLIANCE macro is used to convey a minimum set of 1207 requirements with respect to implementation of one or more PIB modules. 1209 A requirement on all "standard" PIB modules is that a corresponding 1210 MODULE-COMPLIANCE specification is also defined, either in the same 1211 module or in a companion module. 1213 11.1. Mapping of the MODULE clause 1215 The MODULE clause, which must be present, is repeatedly used to name 1216 each PIB module for which compliance requirements are being specified. 1217 Each PIB module is named by its module name, and optionally, by its 1218 associated OBJECT IDENTIFIER as well. The module name can be omitted 1219 when the MODULE-COMPLIANCE invocation occurs inside a PIB module, to 1220 refer to the encompassing PIB module. 1222 11.1.1. Mapping of the MANDATORY-GROUPS clause 1224 The MANDATORY-GROUPS clause, which need not be present, names the one or 1225 more conformance groups within the correspondent PIB module which are 1226 unconditionally mandatory for implementation. If an agent claims 1227 compliance to the PIB module, then it must implement each and every 1228 attribute (and therefore the PRCs to which they belong) within each 1229 conformance group listed. 1231 11.1.2. Mapping of the GROUP clause 1233 The GROUP clause, which need not be present, is repeatedly used to name 1234 each conformance group which is conditionally mandatory for compliance 1235 to the PIB module. The GROUP clause can also be used to name 1236 unconditionally optional groups. A group named in a GROUP clause must 1237 be absent from the correspondent MANDATORY-GROUPS clause. 1239 Conditionally mandatory groups include those which are mandatory only if 1240 a particular protocol is implemented, or only if another group is 1241 implemented. A GROUP clause's DESCRIPTION specifies the conditions 1242 under which the group is conditionally mandatory. 1244 Draft SPPI September 2000 1246 A group which is named in neither a MANDATORY-GROUPS clause nor a GROUP 1247 clause, is unconditionally optional for compliance to the PIB module. 1249 11.1.3. Mapping of the OBJECT clause 1251 The OBJECT clause, which need not be present, is repeatedly used to 1252 specify each attribute for which compliance has a refined requirement 1253 with respect to the PIB module definition. The attribute must be 1254 present in one of the conformance groups named in the correspondent 1255 MANDATORY-GROUPS clause or GROUP clauses. 1257 By definition, each attribute specified in an OBJECT clause follows a 1258 MODULE clause which names the PIB module in which that attribute is 1259 defined. Therefore, the use of an IMPORTS statement, to specify from 1260 where such attributes are imported, is redundant and is not required in 1261 a PIB module. 1263 11.1.3.1. Mapping of the SYNTAX clause 1265 The SYNTAX clause, which need not be present, is used to provide a 1266 refined SYNTAX for the attribute named in the correspondent OBJECT 1267 clause. The refined syntax is the minimum level of support needed for 1268 this attribute in order to be compliant. 1270 11.1.3.2. Mapping of the WRITE-SYNTAX clause 1272 The WRITE-SYNTAX clause is not supported by the SPPI. 1274 11.1.3.3. Mapping of the PIB-MIN-ACCESS clause 1276 The PIB-MIN-ACCESS clause, which need not be present, is used to define 1277 the minimal level of access for the attribute named in the correspondent 1278 OBJECT clause. If this clause is absent, the minimal level of access is 1279 the same as the maximal level specified in the PIB-ACCESS clause of the 1280 correspondent invocation of the OBJECT-TYPE macro. If present, this 1281 clause must specify a subset of the access specified in the 1282 correspondent PIB-ACCESS clause, where: "install" is a subset of 1283 "install-notify", "notify" is a subset of "install-notify", and "not- 1284 accessible" is a subset of all other values. 1286 An implementation is compliant if the level of access it provides is the 1287 same or a superset of the minimal level in the MODULE-COMPLIANCE macro 1288 and the same or a subset of the maximal level in the PIB-ACCESS clause. 1290 Draft SPPI September 2000 1292 12. Textual Conventions 1294 When designing a PIB module, it is often useful to define new data types 1295 similar to those defined in the SPPI. In comparison to a type defined 1296 in the SPPI, each of these new types has a different name, a similar 1297 syntax, and specific semantics. These newly defined types are termed 1298 textual conventions, and are used for the convenience of humans reading 1299 the PIB module. 1301 Attributes defined using a textual convention are always encoded by 1302 means of the rules that define their underlying type. 1304 12.1. Mapping of the TEXTUAL-CONVENTION macro 1306 The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics 1307 associated with a textual convention. It should be noted that the 1308 expansion of the TEXTUAL-CONVENTION macro is something which 1309 conceptually happens during implementation and not during run-time. 1311 The name of a textual convention must consist of one or more letters or 1312 digits, with the initial character being an upper case letter. The name 1313 must not conflict with any of the reserved words listed in section 5.2, 1314 should not consist of all upper case letters, and shall not exceed 64 1315 characters in length. (However, names longer than 32 characters are not 1316 recommended.) The hyphen is not allowed in the name of a textual 1317 convention (except for use in information modules converted from SMIv1 1318 which allowed hyphens in ASN.1 type assignments). Further, all names 1319 used for the textual conventions defined in all "standard" PIB modules 1320 shall be unique. 1322 12.1.1. Mapping of the SYNTAX clause 1324 The SYNTAX clause, which must be present, defines abstract data 1325 structure corresponding to the textual convention. The data structure 1326 must be one of the following: a base type (see the SYNTAX clause of an 1327 OBJECT-TYPE macro), or the BITS construct. Note that this means that 1328 the SYNTAX clause of a Textual Convention can not refer to a previously 1329 defined Textual Convention. 1331 12.1.1.1. Sub-typing of Textual Conventions 1333 The SYNTAX clause of a TEXTUAL CONVENTION macro may be sub-typed in the 1334 same way as the SYNTAX clause of an OBJECT-TYPE macro. 1336 Draft SPPI September 2000 1338 13. Extending a PIB Module 1340 The SMI's rules for extending an information module are augmented with 1341 the following rules: 1343 13.1. OBJECT-TYPE Definitions 1345 An invocation of the OBJECT-TYPE macro may also be revised in any of the 1346 following ways: 1348 - An INSTALL-ERRORS clause may be added or an existing INSTALL-ERRORS 1349 clause have additional errors defined. 1351 - Additional named-number enumerations may be added to a SUBJECT- 1352 CATEGORIES clause. 1354 Draft SPPI September 2000 1356 14. Appendix A: Mapping a PIB to a MIB 1358 Since the SPPI is modelled on the SMI, a PIB can be easily and 1359 algorithmically mapped into a MIB. This mapping is achieved by means of 1360 the following rules: 1362 - Modify the module's module name by appending "-MIB" to the name. 1364 - Change the OID assigned to the MODULE-IDENTITY to be different 1365 value. 1367 - Replace the keyword PIB-DEFINITIONS with the keyword DEFINITIONS. 1369 - Modify the module names of all external references to PIB modules 1370 by appending "-MIB" to each such module name. 1372 - For each PRC definition, if an INDEX clause is absent, change the 1373 "PIB-INDEX" keyword to "INDEX"; otherwise, delete the PIB-INDEX 1374 clause. 1376 - Delete all of the following clauses: PIB-ACCESS, PIB-REFERENCES, 1377 PIB-TAG, UNIQUENESS, INSTALL-ERRORS, and SUBJECT-CATEGORIES. 1379 - Change all PIB-MIN-ACCESS clauses to MIN-ACCESS clauses, modifying 1380 "install" and "install-notify" to "read-create", and "notify" to 1381 "read-only". 1383 - Add a MAX-ACCESS clause for each OBJECT-TYPE. For each table 1384 definition and row definition, the MAX-ACCESS is "not-accessible". 1385 For each attribute that is in the INDEX clause, the MAX-ACCESS is 1386 "not-accessible". For the remaining attributes, the MAX-ACCESS is 1387 "read-create". 1389 - Add a columnar attribute of type RowStatus with a descriptor and 1390 appropriate DESCRIPTION. The descriptor can be formed by appending 1391 the nine characters "RowStatus" to the end of the PRC's descriptor 1392 (truncated if necessary to avoid the resulting descriptor being too 1393 long). The optional number provided by the PIB-ACCESS clause is 1394 used as the OID for this columnar attribute. If no number is 1395 provided by the PIB-ACCESS clause, then the default number 127 is 1396 used. 1398 - Modify any SYNTAX clause which has a base data type which is not 1399 allowed in the SMI, either to be a valid SMI data type or to omit 1400 the OBJECT-TYPE or TEXTUAL-CONVENTION definition and all references 1402 Draft SPPI September 2000 1404 to it. Since it is not clear (at this time) which is the best SMI 1405 data type to use, the conversion SHOULD provide a configurable 1406 option allowing a choice from at least the following: 1408 - convert to an OCTET STRING of the relevant size. 1409 Specifically, this option would map both Integer64 and 1410 Unsigned64 to OCTET STRING (SIZE(8)), or 1412 - omit them from the conversion, or 1414 - map Integer64 and Unsigned64 to Counter64 (even though this 1415 has problems representing negative numbers, and unwanted 1416 counter semantics.) 1418 Draft SPPI September 2000 1420 15. Appendix B: Example usage of PIB-REFERENCE and PIB-TAG clauses 1422 The following example demonstrates the use of the PIB-REFERENCE and PIB- 1423 TAG clauses. 1425 In this example, the PIB-REFERENCE clause is used by the 1426 qosIfDscpMapQueue attribute to indicate the PRC of which it references 1427 an instance, and similarly, by the qosIfDscpMapThresh attribute. 1429 The qosIfDscpMapTable PRC has an instance for each DSCP of a particular 1430 "map", but there is no PRC defined for a map itself; rather, a map 1431 consists of all instances of qosIfDscpMapTable which have the same value 1432 of qosIfDscpMapMapId. That is, a tag list is formed by all instances of 1433 qosIfDscpMapTable which have the same value of qosIfDscpMapMapId. This 1434 tag list is referenced by the attribute qosIfDscpAssignDscpMap, and its 1435 use of the PIB-TAG clause indicates this. 1437 qosIfDscpAssignTable OBJECT-TYPE 1438 SYNTAX SEQUENCE OF QosIfDscpAssignEntry 1439 PIB-ACCESS install 1440 STATUS current 1441 DESCRIPTION " " 1442 ::= { qosIfParameters 9 } 1444 qosIfDscpAssignEntry OBJECT-TYPE 1445 SYNTAX QosIfDscpAssignEntry 1446 STATUS current 1447 DESCRIPTION 1448 "An instance of the qosIfDscpAssign class." 1449 PIB-INDEX { qosIfDscpAssignPrid } 1450 UNIQUENESS { qosIfDscpAssignName, qosIfDscpAssignRoles } 1451 ::= { qosIfDscpAssignTable 1 } 1453 QosIfDscpAssignEntry ::= SEQUENCE { 1454 qosIfDscpAssignPrid InstanceId, 1455 qosIfDscpAssignName SnmpAdminString, 1456 qosIfDscpAssignRoles RoleCombination, 1457 qosIfDscpAssignDscpMap TagReferenceId 1458 } 1460 qosIfDscpAssignDscpMap OBJECT-TYPE 1461 SYNTAX TagReferenceId 1462 PIB-TAG qosIfDscpMapMapId -- attribute defined below 1463 STATUS current 1464 DESCRIPTION 1466 Draft SPPI September 2000 1468 "The DSCP map which is applied to interfaces of type 1469 qosIfDscpAssignName which have a role combination of 1470 qosIfDscpAssignRoles." 1471 ::= { qosIfDscpAssignEntry 3 } 1473 -- 1474 -- DSCP to Queue and Threshold Mapping Table 1475 -- 1477 qosIfDscpMapTable OBJECT-TYPE 1478 SYNTAX SEQUENCE OF QosIfDscpMapEntry 1479 PIB-ACCESS install 1480 STATUS current 1481 DESCRIPTION 1482 "Assigns DSCP values to queues and thresholds for an arbitrary 1483 DSCP map. This map can then be assigned to various interface 1484 and role combination pairs." 1485 ::= { qosIfParameters 10 } 1487 qosIfDscpMapEntry OBJECT-TYPE 1488 SYNTAX QosIfDscpMapEntry 1489 STATUS current 1490 DESCRIPTION 1491 "An instance of the qosIfDscpMap class." 1492 PIB-INDEX { qosIfDscpMapPrid } 1493 UNIQUENESS { qosIfDscpMapMapId, qosIfDscpMapDscp } 1494 ::= { qosIfDscpMapTable 1 } 1496 QosIfDscpMapEntry ::= SEQUENCE { 1497 qosIfDscpMapPrid InstanceId, 1498 qosIfDscpMapMapId TagId, 1499 qosIfDscpMapDscp Dscp, 1500 qosIfDscpMapQueue ReferenceId, 1501 qosIfDscpMapThresh ReferenceId 1502 } 1504 qosIfDscpMapMapId OBJECT-TYPE 1505 SYNTAX TagId 1506 STATUS current 1507 DESCRIPTION 1508 "An integer that identifies the DSCP map to which this PRI 1509 belongs." 1510 ::= { qosIfDscpMapEntry 2 } 1512 qosIfDscpMapQueue OBJECT-TYPE 1513 Draft SPPI September 2000 1515 SYNTAX ReferenceId 1516 PIB-REFERENCE qosIfQueueTable 1517 STATUS current 1518 DESCRIPTION 1519 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1520 the queue identified by qosIfQueuePrid in qosIfQueueTable. 1521 For a given DSCP map, all the queues must belong to a single 1522 queue set." 1523 ::= { qosIfDscpMapEntry 4 } 1525 qosIfDscpMapThresh OBJECT-TYPE 1526 SYNTAX ReferenceId 1527 PIB-REFERENCE qosIfThresholdTable 1528 STATUS current 1529 DESCRIPTION 1530 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1531 the threshold identified by qosIfThresholdId in 1532 qosIfThresholdTable. The threshold set to which this 1533 threshold belongs must be assigned to the queue specified by 1534 qosIfDscpMapQueue." 1535 ::= { qosIfDscpMapEntry 5 } 1537 Draft SPPI September 2000 1539 16. Security Considerations 1541 This document defines a language with which to define provisioning 1542 information. The language itself has no security impact on the 1543 Internet. 1545 17. Authors' Addresses 1547 Keith McCloghrie 1548 Cisco Systems, Inc. 1549 170 West Tasman Drive 1550 San Jose, CA 95134-1706 USA 1551 Phone: +1 408 526 5260 1552 Email: kzm@cisco.com 1554 Michael Fine 1555 Cisco Systems, Inc. 1556 170 West Tasman Drive 1557 San Jose, CA 95134-1706 USA 1558 Phone: +1 408 527 8218 1559 Email: mfine@cisco.com 1561 John Seligson 1562 Nortel Networks, Inc. 1563 4401 Great America Parkway 1564 Santa Clara, CA 95054 USA 1565 Phone: +1 408 495 2992 1566 Email: jseligso@nortelnetworks.com 1568 Kwok Ho Chan 1569 Nortel Networks, Inc. 1570 600 Technology Park Drive 1571 Billerica, MA 01821 USA 1572 Phone: +1 978 288 8175 1573 Email: khchan@nortelnetworks.com 1575 Scott Hahn 1576 Intel 1577 2111 NE 25th Avenue 1578 Hillsboro, OR 97124 USA 1579 Phone: +1 503 264 8231 1580 Email: scott.hahn@intel.com 1582 Draft SPPI September 2000 1584 Ravi Sahita 1585 Intel 1586 2111 NE 25th Avenue 1587 Hillsboro, OR 97124 USA 1588 Phone: +1 503 712 1554 1589 Email: ravi.sahita@intel.com 1591 Andrew Smith 1592 Fax: +1 415 345 1827 1593 Email: ah_smith@pacbell.net 1595 Francis Reichmeyer 1596 PFN Inc. 1597 University Park at MIT 1598 26 Landsdowne Street 1599 Cambridge, MA 02139 1600 Phone: +1 617 494 9980 1601 Email: franr@pfn.com 1603 18. References 1605 [COPS] 1606 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1607 Sastry, "The COPS (Common Open Policy Service) Protocol" RFC 2748, 1608 January 2000. 1610 [COPS-RSVP] 1611 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1612 Sastry, " COPS usage for RSVP", RFC 2749, January 2000. 1614 [COPS-PR] 1615 Reichmeyer, F., Herzog, S., Chan, K., Durham, D., Yavatkar, R. 1616 Gai, S., McCloghrie, K. and A. Smith, "COPS Usage for Policy 1617 Provisioning" Internet Draft, draft-ietf-rap-cops-pr-04.txt, August 1618 2000. 1620 [SMI] 1621 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1622 and S. Waldbusser. "Structure of Management Information Version 2 1623 (SMIv2)", RFC 2578, April 1999. 1625 [TC] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1626 and S. Waldbusser. "Textual Conventions for SMIv2", RFC 2579, 1627 April 1999. 1629 Draft SPPI September 2000 1631 [CONF] 1632 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1633 and S. Waldbusser. "Conformance Statements for SMIv2", RFC 2580, 1634 April 1999. 1636 [APPL] 1637 Levi, D., Meyer, P., and B. Stewart, "SNMP Applications", RFC 2573, 1638 April 1999. 1640 [ASN1] 1641 Information processing systems -- Open Systems Interconnection -- 1642 Specification of Abstract Syntax Notation One (ASN.1), 1643 International Organization for Standardization. International 1644 Standard 8824, December 1987. 1646 Draft SPPI September 2000 1648 19. Full Copyright Statement 1650 Copyright (C) The Internet Society (2000). All Rights Reserved. 1652 This document and translations of it may be copied and furnished to 1653 others, and derivative works that comment on or otherwise explain it or 1654 assist in its implementation may be prepared, copied, published and 1655 distributed, in whole or in part, without restriction of any kind, 1656 provided that the above copyright notice and this paragraph are included 1657 on all such copies and derivative works. However, this document itself 1658 may not be modified in any way, such as by removing the copyright notice 1659 or references to the Internet Society or other Internet organizations, 1660 except as needed for the purpose of developing Internet standards in 1661 which case the procedures for copyrights defined in the Internet 1662 Standards process must be followed, or as required to translate it into 1663 languages other than English. 1665 The limited permissions granted above are perpetual and will not be 1666 revoked by the Internet Society or its successors or assigns. 1668 This document and the information contained herein is provided on an "AS 1669 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 1670 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 1671 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 1672 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 1673 FITNESS FOR A PARTICULAR PURPOSE." 1674 Draft SPPI September 2000 1676 Table of Contents 1678 1 Introduction .................................................... 2 1679 1.1 Change Log .................................................... 2 1680 1.1.1 Changes made in version published on 13 July 2000 ........... 2 1681 1.1.2 Changes made in version published on 20 September 2000 ...... 3 1682 2 Use of the SMI .................................................. 4 1683 2.1 Terminology Translation ....................................... 4 1684 2.2 Overview ...................................................... 4 1685 3 Structure of this Specification ................................. 5 1686 4 Definitions ..................................................... 6 1687 5 PIB Modules ..................................................... 19 1688 5.1 Importing Definitions ......................................... 19 1689 5.2 Reserved Keywords ............................................. 19 1690 6 Naming Hierarchy ................................................ 20 1691 7 Mapping of the MODULE-IDENTITY macro ............................ 20 1692 7.1 Mapping of the SUBJECT-CATEGORIES clause ...................... 20 1693 8 Mapping of the OBJECT-TYPE macro ................................ 21 1694 8.1 Mapping of the SYNTAX clause .................................. 21 1695 8.1.1 Counter32 ................................................... 21 1696 8.1.2 Gauge32 ..................................................... 22 1697 8.1.3 Opaque ...................................................... 22 1698 8.1.4 Counter64 ................................................... 22 1699 8.1.5 Integer64 ................................................... 22 1700 8.1.6 Unsigned64 .................................................. 22 1701 8.1.7 Provisioning Classes ........................................ 22 1702 8.2 Mapping of the MAX-ACCESS clause .............................. 23 1703 8.3 Mapping of the PIB-ACCESS clause .............................. 23 1704 8.4 Mapping of the INSTALL-ERRORS clause .......................... 24 1705 8.5 Mapping of the PIB-INDEX clause ............................... 24 1706 8.6 Mapping of the INDEX clause ................................... 24 1707 8.7 Mapping of the AUGMENTS clause ................................ 25 1708 8.8 Mapping of the EXTENDS clause ................................. 25 1709 8.8.1 Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1710 .............................................................. 26 1711 8.9 Mapping of the UNIQUENESS clause .............................. 26 1712 8.10 Mapping of the PIB-REFERENCES clause ......................... 27 1713 8.11 Mapping of the PIB-TAG clause ................................ 27 1714 9 Mapping of the OBJECT-IDENTITY macro ............................ 27 1715 10 Mapping of the OBJECT-GROUP macro .............................. 27 1716 10.1 Mapping of the OBJECTS clause ................................ 27 1717 11 Mapping of the MODULE-COMPLIANCE macro ......................... 28 1718 11.1 Mapping of the MODULE clause ................................. 28 1719 11.1.1 Mapping of the MANDATORY-GROUPS clause ..................... 28 1720 Draft SPPI September 2000 1722 11.1.2 Mapping of the GROUP clause ................................ 28 1723 11.1.3 Mapping of the OBJECT clause ............................... 29 1724 11.1.3.1 Mapping of the SYNTAX clause ............................. 29 1725 11.1.3.2 Mapping of the WRITE-SYNTAX clause ....................... 29 1726 11.1.3.3 Mapping of the PIB-MIN-ACCESS clause ..................... 29 1727 12 Textual Conventions ............................................ 30 1728 12.1 Mapping of the TEXTUAL-CONVENTION macro ...................... 30 1729 12.1.1 Mapping of the SYNTAX clause ............................... 30 1730 12.1.1.1 Sub-typing of Textual Conventions ........................ 30 1731 13 Extending a PIB Module ......................................... 31 1732 13.1 OBJECT-TYPE Definitions ...................................... 31 1733 14 Appendix A: Mapping a PIB to a MIB ............................. 32 1734 15 Appendix B: Example usage of PIB-REFERENCE and PIB-TAG claus- 1735 es ........................................................... 34 1736 16 Security Considerations ........................................ 37 1737 17 Authors' Addresses ............................................. 37 1738 18 References ..................................................... 38 1739 19 Full Copyright Statement ....................................... 40