idnits 2.17.1 draft-ietf-rap-sppi-05.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 1440: '..., 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 1755 has weird spacing: '...elation betwe...' == Line 1780 has weird spacing: '...Example usage...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (20 February 2001) is 8465 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'APPLICATION 7' is mentioned on line 149, but not defined == Missing Reference: 'APPLICATION 8' is mentioned on line 149, but not defined == Missing Reference: 'APPLICATION 11' is mentioned on line 380, but not defined == Missing Reference: 'APPLICATION 0' is mentioned on line 349, but not defined == Missing Reference: 'APPLICATION 2' is mentioned on line 365, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 370, but not defined == Missing Reference: 'APPLICATION 10' is mentioned on line 376, 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' ** Obsolete normative reference: RFC 2851 (ref. 'INETADDR') (Obsoleted by RFC 3291) Summary: 10 errors (**), 0 flaws (~~), 11 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 20 February 2001 17 Structure of Policy Provisioning Information (SPPI) 19 draft-ietf-rap-sppi-05.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 February 2001 46 1. Introduction 48 RFC 2748 [COPS] defines the COPS protocol, and RFC 2749 [COPS-RSVP] 49 describes how the COPS protocol is used to provide for the outsourcing 50 of policy decisions for RSVP. Another usage of the COPS protocol, for 51 the provisioning of policy, is introduced in [COPS-PR]. In this 52 provisioning model, the policy information is viewed as a collection of 53 Provisioning Classes (PRCs) and Provisioning Instances (PRIs) residing 54 in a virtual information store, termed the Policy Information Base 55 (PIB). Collections of related Provisioning Classes are defined in a PIB 56 module. PIB modules are written using an adapted subset of SNMP's 57 Structure of Management Information (SMI) [SMI, TC, CONF]. It is the 58 purpose of this document, the Structure of Policy Provisioning 59 Information (SPPI), to define that adapted subset. 61 1.1. Change Log 63 This log to be removed as and when this draft is published as an RFC. 65 1.1.1. Changes made in version published on 13 July 2000 67 - included definition of the TEXTUAL-CONVENTION macro in the SPPI's 68 ASN.1 module so that TC's in PIBs can use data types not present in the 69 SMI. 71 - renamed the CLIENT-TYPES clause to be the SUBJECT-CATEGORIES clause in 72 order to be more generic. 74 - renamed the POLICY-ACCESS clause to be the PIB-ACCESS clause for 75 consistency. Added an extra parameter on the PIB-ACCESS clause for use 76 as the sub-identifier for a RowStatus column when converting to a MIB. 78 - added new clauses: EXTENDS, PIB-INDEX, PIB-REFERENCES, PIB-TAG, and 79 PIB-MODULES. 81 - renamed the MIN-ACCESS clause to be the PIB-MIN-ACCESS clause. 83 - created a new PIB module to contain the TC's defined in the SPPI. 85 - defined new TC's: Prid, PolicyTagId, PolicyTagReference. 87 - added Appendix with example usage of PIB-REFERENCES and PIB-TAG. 89 - added detail on carrying an INSTALL-ERROR in COPS-PR messages. 91 Draft SPPI February 2001 93 1.1.2. Changes made in version published on 20 September 2000 95 - copied (unmodified) the definitions of the OBJECT-IDENTITY and OBJECT- 96 GROUP macros into this document. 98 - changed syntax of PolicyTagId and PolicyTagReference to Unsigned32. 100 - changed the PolicyXxx TC names to remove "Policy" and be more 101 consistent, i.e., PolicyTagId, PolicyReferenceId and PolicyTagReference 102 to TagId, ReferenceId and TagReferenceId. 104 - made the UNIQUENESS clause optional, but recommended wherever it 105 provides useful information. 107 - changed usage of the PIB-INDEX and INDEX clauses to be more 108 consistent: a PIB-INDEX clause is now always required, and always has 109 the same meaning. The INDEX clause is now optional, and is only used 110 for the algorithmic conversion to a MIB. 112 - changed default OID value for an added RowStatus column to be 127. 114 - removed the PIB-MODULES clause. 116 - changed the meaning of PRC to be Provisioning Class, and of PRI to be 117 Provisioning Instance. 119 - required the algorithmic conversion to a MIB to have a configurable 120 option with respect to how Integer64 and Unsigned64 are mapped to the 121 SMI. 123 - specified that a PIB module's SUBJECT-CATEGORIES clause is not 124 exclusive. That is, some other specification might (e.g., at a future 125 date) specify additional COPS Client Types to which the PIB module is 126 relevant. 128 - updated the Reserved Keywords. 130 - copied the definitions of IpAddress, Unsigned32, TimeTicks from the 131 SMI into COPS-PR-SPPI, and clarified that PIB modules must import each 132 base data type that it uses from COPS-PR-SPPI, and may import, from the 133 SMI, (subtree) OIDs for the purpose of defining new OIDs. 135 - various typos. 137 Draft SPPI February 2001 139 1.1.3. Changes made in version published on 13 November 2000 141 - clarified definition of PIB-REFERENCES. 143 - added "report-only" as a value of PIB-ACCESS. 145 1.1.4. Changes made in version published 22 January 2001 147 - Converted PIB-REFERENCE to PIB-REFERENCES 149 - Changed [APPLICATION 7] and [APPLICATION 8] references to [APPLICATION 150 10] and [APPLICATION 11]. 152 1.1.5. Changes made in version published 20 February 2001 154 - Deprecated IpAddress and added reference to INET-ADDRESS-MIB. 156 2. Use of the SMI 158 The SPPI and PIB modules are based on SNMP's SMI and MIB modules, which 159 use an adapted subset of the ASN.1 data definition language [ASN1]. The 160 decision to base the definition of PIB modules on this format allows for 161 the leveraging of the community's knowledge, experience and tools of the 162 SMI and MIB modules. 164 2.1. Terminology Translation 166 The SMI uses the term "managed objects" to refer to object types, both 167 tabular types with descriptors such as xxxTable and xxxEntry, as well as 168 scalar and columnar object types. The SPPI does not use the term 169 "object" so as to avoid confusion with COPS protocol objects. Instead, 170 the SPPI uses the term Provisioning Class (PRC) for the table and row 171 definitions (the xxxTable and xxxEntry objects, respectively), and 172 Provisioning Instance (PRI) for an instantiation of a row definition. 173 For a columnar object of a table definition, the SPPI uses the term 174 "attribute" of a Provisioning Class. (The SPPI does not support the 175 equivalent of the SMI's scalar objects.) 177 2.2. Overview 179 SNMP's SMI is divided into five parts: module definitions, object 180 definitions, notification definitions [SMI], textual convention 181 definitions [TC] and conformance definitions [CONF]. 183 Draft SPPI February 2001 185 - The SMI's MODULE-IDENTITY macro is used to convey the semantics of 186 a MIB module. The SPPI uses this macro to convey the semantics of 187 a PIB module. 189 - The SMI's OBJECT-TYPE macro is used to convey the syntax and 190 semantics of managed objects. The SPPI uses this macro to convey 191 the syntax and semantics of PRCs and their attributes. 193 - The SMI's notification definitions are not used (at this time) by 194 the SPPI. (Note that the use of the keyword 'notify' in the SPPI 195 is not related to the SMI's notifications). 197 - The SMI's TEXTUAL CONVENTION macro allows new data types to be 198 defined. The SPPI uses this macro to define new data types having 199 particular syntax and semantics which is common to several 200 attributes of one of more PRCs. 202 - The SMI's conformance definitions define several macros: the 203 OBJECT-GROUP macro, the NOTIFICATION-GROUP macro, the MODULE- 204 COMPLIANCE macro and the AGENT-CAPABILITIES macro. The SPPI uses 205 the OBJECT-GROUP and MODULE-COMPLIANCE macros to specify acceptable 206 lower-bounds of implementation of the attributes of PRCs, and 207 thereby indirectly, acceptable lower-bounds of implementation of 208 the PRCs themselves. The NOTIFICATION-GROUP macro is not used (at 209 this time) by the SPPI. Potential usage by the SPPI of the AGENT- 210 CAPABILITIES macro is for further study. 212 3. Structure of this Specification 214 The SMI is specified in terms of an ASN.1 definition together with 215 descriptive text for each element introduced in that ASN.1 definition. 216 This document specifies the SPPI also via a ASN.1 definition, which is a 217 modified version of the SMI's definition, together with descriptive text 218 for only those elements in the SPPI's ASN.1 definition which have 219 differences from the SMI's. For elements in the ASN.1 definition which 220 have no descriptive text in this specification, the reader is referred 221 to the SMI's descriptive text for that element. 223 Draft SPPI February 2001 225 4. Definitions 227 COPS-PR-SPPI DEFINITIONS ::= BEGIN 229 IMPORTS ObjectName, SimpleSyntax, ExtUTCTime 230 FROM SNMPv2-SMI; 232 -- definitions for PIB modules 234 MODULE-IDENTITY MACRO ::= 235 BEGIN 236 TYPE NOTATION ::= 237 SubjectPart -- new 238 "LAST-UPDATED" value(Update ExtUTCTime) 239 "ORGANIZATION" Text 240 "CONTACT-INFO" Text 241 "DESCRIPTION" Text 242 RevisionPart 244 VALUE NOTATION ::= 245 value(VALUE OBJECT IDENTIFIER) 247 SubjectPart ::= -- new 248 "SUBJECT-CATEGORIES" "{" Categories "}" 249 Categories ::= -- new 250 CategoryIDs 251 | "all" 252 CategoryIDs ::= -- new 253 CategoryID 254 | CategoryIDs "," CategoryID 255 CategoryID ::= -- new 256 identifier "(" number ")" -- number is positive 258 RevisionPart ::= 259 Revisions 260 | empty 261 Revisions ::= 262 Revision 263 | Revisions Revision 264 Revision ::= 265 "REVISION" value(Update ExtUTCTime) 266 "DESCRIPTION" Text 268 Draft SPPI February 2001 270 -- a character string as defined in [SMI] 271 Text ::= value(IA5String) 272 END 274 -- 276 OBJECT-IDENTITY MACRO ::= 277 BEGIN 278 TYPE NOTATION ::= 279 "STATUS" Status 280 "DESCRIPTION" Text 281 ReferPart 283 VALUE NOTATION ::= 284 value(VALUE OBJECT IDENTIFIER) 286 Status ::= 287 "current" 288 | "deprecated" 289 | "obsolete" 291 ReferPart ::= 292 "REFERENCE" Text 293 | empty 295 -- a character string as defined in [SMI] 296 Text ::= value(IA5String) 297 END 299 -- syntax of attributes 301 -- the "base types" defined here are: 302 -- 3 built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER 303 -- 6 application-defined types: Integer32, IpAddress, Unsigned32, 304 -- TimeTicks, Integer64 and Unsigned64 306 ObjectSyntax ::= 307 CHOICE { 308 simple 309 SimpleSyntax, 311 -- note that SEQUENCEs for table and row definitions 312 -- are not mentioned here... 314 Draft SPPI February 2001 316 application-wide 317 ApplicationSyntax 318 } 320 -- application-wide types 322 ApplicationSyntax ::= 323 CHOICE { 324 ipAddress-value 325 IpAddress, 327 timeticks-value 328 TimeTicks, 330 unsigned-integer-value 331 Unsigned32, 333 large-integer-value -- new 334 Integer64, 336 large-unsigned-integer-value -- new 337 Unsigned64 338 } 340 -- the following 4 types are copied from the SMI 342 -- indistinguishable from INTEGER, but never needs more than 343 -- 32-bits for a two's complement representation 344 Integer32 ::= 345 INTEGER (-2147483648..2147483647) 347 -- (this is a tagged type for historical reasons) 348 IpAddress ::= 349 [APPLICATION 0] 350 IMPLICIT OCTET STRING (SIZE (4)) 351 -- ******* THIS TYPE DEFINITION IS DEPRECATED ******* 352 -- The IpAddress type represents a 32-bit internet 353 -- IPv4 address. It is represented as an OctetString 354 -- of length 4, in network byte-order. 356 -- Note that the IpAddress type is present for 357 -- historical reasons. IPv4 and IPv6 addresses should 358 -- be represented using the INET-ADDRESS-MIB 359 -- defined in [INETADDR]. 361 Draft SPPI February 2001 363 -- an unsigned 32-bit quantity 364 Unsigned32 ::= 365 [APPLICATION 2] 366 IMPLICIT INTEGER (0..4294967295) 368 -- hundredths of seconds since an epoch 369 TimeTicks ::= 370 [APPLICATION 3] 371 IMPLICIT INTEGER (0..4294967295) 373 -- the following 2 types are not present in the SMI 375 Integer64 ::= 376 [APPLICATION 10] 377 IMPLICIT INTEGER (-9223372036854775808..9223372036854775807) 379 Unsigned64 380 [APPLICATION 11] 381 IMPLICIT INTEGER (0..18446744073709551615) 383 -- definition for Provisioning Classes and their attributes 384 -- (differences from the SMI are noted in the ASN.1 comments) 386 OBJECT-TYPE MACRO ::= 387 BEGIN 388 TYPE NOTATION ::= 389 "SYNTAX" Syntax 390 UnitsPart 391 "PIB-ACCESS" AccessPart -- modified 392 PibReferencesPart -- new 393 PibTagPart -- new 394 "STATUS" Status 395 "DESCRIPTION" Text 396 ErrorsPart -- new 397 ReferPart 398 IndexPart -- modified 399 MibIndexPart -- modified 400 UniquePart -- new 401 DefValPart 403 VALUE NOTATION ::= 404 value(VALUE ObjectName) 406 Syntax ::= -- Must be one of the following: 408 Draft SPPI February 2001 410 -- a base type (or its refinement), 411 -- a textual convention (or its refinement), or 412 -- a BITS pseudo-type 413 type 414 | "BITS" "{" NamedBits "}" 416 NamedBits ::= NamedBit 417 | NamedBits "," NamedBit 419 NamedBit ::= identifier "(" number ")" -- number is nonnegative 421 UnitsPart ::= 422 "UNITS" Text 423 | empty 425 AccessPart ::= -- new 426 Access 427 | Access "," number -- number is positive 429 Access ::= -- modified 430 "install" 431 | "notify" 432 | "install-notify" 433 | "report-only" 435 Status ::= 436 "current" 437 | "deprecated" 438 | "obsolete" 440 ErrorsPart ::= -- new 441 "INSTALL-ERRORS" "{" Errors "}" 442 | empty 444 Errors ::= -- new 445 Error 446 | Errors "," Error 447 Error ::= -- new 448 identifier "(" number ")" -- number is positive 450 ReferPart ::= 451 "REFERENCE" Text 452 | empty 454 IndexPart ::= 456 Draft SPPI February 2001 458 "PIB-INDEX" "{" Index "}" -- new 459 | "AUGMENTS" "{" Entry "}" 460 | "EXTENDS" "{" Entry "}" -- new 461 | empty 462 Index ::= 463 -- the correspondent OBJECT-TYPE invocation 464 value(ObjectName) 465 Entry ::= 466 -- use the INDEX value of the 467 -- correspondent OBJECT-TYPE invocation 468 value(ObjectName) 469 MibIndexPart ::= 470 "INDEX" "{" IndexTypePart "}" 471 | empty 472 IndexTypePart ::= 473 IndexTypes 474 | IndexTypes "," ImpliedIndex 475 | ImpliedIndex 476 IndexTypes ::= 477 Index 478 | IndexTypes "," Index 479 ImpliedIndex ::= 480 "IMPLIED" Index 482 PibReferencesPart ::= 483 -- for use with ReferenceId TC 484 "PIB-REFERENCES" "{" Entry "}" 485 | empty 487 PibTagPart ::= 488 -- for use with TagReferenceId TC 489 "PIB-TAG" "{" Attr "}" 490 | empty 492 Attr ::= -- specifies an attribute 493 value(ObjectName) 495 UniquePart ::= -- new 496 "UNIQUENESS" "{" UniqueTypes "}" 497 | "UNIQUENESS" "{" "}" 498 | empty 499 UniqueTypes ::= 500 UniqueType 501 | UniqueTypes "," UniqueType 503 Draft SPPI February 2001 505 UniqueType ::= 506 -- the correspondent OBJECT-TYPE invocation 507 value(ObjectName) 509 DefValPart ::= "DEFVAL" "{" Defvalue "}" 510 | empty 512 Defvalue ::= -- must be valid for the type specified in 513 -- SYNTAX clause of same OBJECT-TYPE macro 514 value(ObjectSyntax) 515 | "{" BitsValue "}" 517 BitsValue ::= BitNames 518 | empty 520 BitNames ::= BitName 521 | BitNames "," BitName 523 BitName ::= identifier 525 -- a character string as defined in [SMI] 526 Text ::= value(IA5String) 527 END 529 -- definitions for conformance groups 531 OBJECT-GROUP MACRO ::= 532 BEGIN 533 TYPE NOTATION ::= 534 ObjectsPart 535 "STATUS" Status 536 "DESCRIPTION" Text 537 ReferPart 539 VALUE NOTATION ::= 540 value(VALUE OBJECT IDENTIFIER) 542 ObjectsPart ::= 543 "OBJECTS" "{" Objects "}" 544 Objects ::= 545 Object 546 | Objects "," Object 547 Object ::= 548 value(ObjectName) 550 Draft SPPI February 2001 552 Status ::= 553 "current" 554 | "deprecated" 555 | "obsolete" 557 ReferPart ::= 558 "REFERENCE" Text 559 | empty 561 -- a character string as defined in [SMI] 562 Text ::= value(IA5String) 563 END 565 -- definitions for compliance statements 567 MODULE-COMPLIANCE MACRO ::= 568 BEGIN 569 TYPE NOTATION ::= 570 "STATUS" Status 571 "DESCRIPTION" Text 572 ReferPart 573 ModulePart 575 VALUE NOTATION ::= 576 value(VALUE OBJECT IDENTIFIER) 578 Status ::= 579 "current" 580 | "deprecated" 581 | "obsolete" 583 ReferPart ::= 584 "REFERENCE" Text 585 | empty 587 ModulePart ::= 588 Modules 589 Modules ::= 590 Module 591 | Modules Module 592 Module ::= 593 -- name of module -- 594 "MODULE" ModuleName 595 MandatoryPart 597 Draft SPPI February 2001 599 CompliancePart 601 ModuleName ::= 602 -- identifier must start with uppercase letter 603 identifier ModuleIdentifier 604 -- must not be empty unless contained 605 -- in MIB Module 606 | empty 607 ModuleIdentifier ::= 608 value(OBJECT IDENTIFIER) 609 | empty 611 MandatoryPart ::= 612 "MANDATORY-GROUPS" "{" Groups "}" 613 | empty 615 Groups ::= 616 Group 617 | Groups "," Group 618 Group ::= 619 value(OBJECT IDENTIFIER) 621 CompliancePart ::= 622 Compliances 623 | empty 625 Compliances ::= 626 Compliance 627 | Compliances Compliance 628 Compliance ::= 629 ComplianceGroup 630 | Object 632 ComplianceGroup ::= 633 "GROUP" value(OBJECT IDENTIFIER) 634 "DESCRIPTION" Text 636 Object ::= 637 "OBJECT" value(ObjectName) 638 InstallSyntaxPart -- modified 639 AccessPart 640 "DESCRIPTION" Text 642 -- must be a refinement for object's SYNTAX clause 643 InstallSyntaxPart ::= "SYNTAX" Syntax 645 Draft SPPI February 2001 647 | empty 649 Syntax ::= -- Must be one of the following: 650 -- a base type (or its refinement), 651 -- a textual convention (or its refinement), or 652 -- a BITS pseudo-type 653 type 654 | "BITS" "{" NamedBits "}" 656 NamedBits ::= NamedBit 657 | NamedBits "," NamedBit 659 NamedBit ::= identifier "(" number ")" -- number is nonnegative 661 AccessPart ::= 662 "PIB-MIN-ACCESS" Access -- modified 663 | empty 664 Access ::= -- modified 665 "not-accessible" 666 | "install" 667 | "notify" 668 | "install-notify" 670 -- a character string as defined in [SMI] 671 Text ::= value(IA5String) 672 END 674 -- definition of textual conventions 676 TEXTUAL-CONVENTION MACRO ::= 677 BEGIN 678 TYPE NOTATION ::= 679 DisplayPart 680 "STATUS" Status 681 "DESCRIPTION" Text 682 ReferPart 683 "SYNTAX" Syntax 685 VALUE NOTATION ::= 686 value(VALUE Syntax) -- adapted ASN.1 688 DisplayPart ::= 689 "DISPLAY-HINT" Text 690 | empty 692 Draft SPPI February 2001 694 Status ::= 695 "current" 696 | "deprecated" 697 | "obsolete" 699 ReferPart ::= 700 "REFERENCE" Text 701 | empty 703 -- a character string as defined in [SMI] 704 Text ::= value(IA5String) 706 Syntax ::= -- Must be one of the following: 707 -- a base type (or its refinement), or 708 -- a BITS pseudo-type 709 type 710 | "BITS" "{" NamedBits "}" 712 NamedBits ::= NamedBit 713 | NamedBits "," NamedBit 715 NamedBit ::= identifier "(" number ")" -- number is nonnegative 717 END 719 END 720 Draft SPPI February 2001 722 COPS-PR-SPPI-TC PIB-DEFINITIONS ::= BEGIN 724 IMPORTS Unsigned32, MODULE-IDENTITY, TEXTUAL-CONVENTION 725 FROM COPS-PR-SPPI; 727 copsPrSppiTc MODULE-IDENTITY 728 SUBJECT-CATEGORIES { all } 729 LAST-UPDATED "200009201800Z" 730 ORGANIZATION "IETF RAP WG" 731 CONTACT-INFO "Keith McCloghrie 732 Cisco Systems, Inc. 733 170 West Tasman Drive, 734 San Jose, CA 95134-1706 USA 735 Phone: +1 408 526 5260 736 Email: kzm@cisco.com 738 Ravi Sahita 739 Intel 740 2111 NE 25th Avenue 741 Hillsboro, OR 97124 USA 742 Phone: +1 503 712 1554 743 Email: ravi.sahita@intel.com " 744 DESCRIPTION 745 "The PIB module containing a set of Textual Conventions 746 which have general applicability to all PIB modules." 747 REVISION "200009201800Z" 748 DESCRIPTION 749 "Initial version, published in RFC xxxx." 750 ::= { tbd } 752 InstanceId ::= TEXTUAL-CONVENTION 753 STATUS current 754 DESCRIPTION 755 "The textual convention for use by an attribute which is used 756 as the instance-identifying index of a PRC, i.e., an attribute 757 named in a PIB-INDEX clause. The value of an attribute with this 758 syntax is always greater than zero. PRIs of the same PRC need 759 not have contiguous values for their instance-identifying 760 attribute." 761 SYNTAX Unsigned32 (1..4294967295) 763 ReferenceId ::= TEXTUAL-CONVENTION 764 STATUS current 765 DESCRIPTION 766 "A textual convention for use by an attribute which is used as 768 Draft SPPI February 2001 770 a pointer in order to reference an instance of a particular 771 PRC. An attribute with this syntax must not be used in a 772 PIB-INDEX clause , and its description must specify the 773 particular PRC to which the referenced PRI will belong. 774 For an attribute of this type, the referenced PRI must exist. 775 Furthermore, it is an error to try to delete a PRI that is 776 referenced by another instance without first deleting/modifying 777 the referencing instance. The definition of an attribute with 778 this syntax can permit the attribute to have a value of zero to 779 indicate that it is not currently pointing to an PRI." 780 SYNTAX Unsigned32 782 Prid ::= TEXTUAL-CONVENTION 783 STATUS current 784 DESCRIPTION 785 "Represents a pointer to a PRI, i.e,. to an instance of a 786 PRC. The value is the OID name of the PRC's row definition, 787 appended with one sub-identifier containing the value of the 788 InstanceId value for the referenced instance. The definition 789 of an attribute with this syntax can permit the attribute to 790 have a value of 0.0 to indicate that it is not currently 791 pointing to a PRI." 792 SYNTAX OBJECT IDENTIFIER 794 TagId ::= TEXTUAL-CONVENTION 795 STATUS current 796 DESCRIPTION 797 "Represents a tag value, such that all instances of a 798 particular PRC having the same tag value form a tag list. 799 A tag list is identified by the tag value shared by all 800 instances in that tag list." 801 SYNTAX Unsigned32 (1..4294967295) 803 TagReferenceId ::= TEXTUAL-CONVENTION 804 STATUS current 805 DESCRIPTION 806 "Represents a reference to a tag list of instances of a 807 particular PRC. The particular PRC must have an attribute 808 with the syntax of TagId. The tag list consists of 809 all instances which have the same value of the TagId 810 attribute. Reference to the tag list is via the attribute 811 with the syntax of TagReferenceId containing the tag 812 value which identifies the tag list." 813 SYNTAX Unsigned32 814 END 815 Draft SPPI February 2001 817 5. PIB Modules 819 The names of all standard PIB modules must be unique (but different 820 versions of the same module should have the same name). Developers of 821 enterprise PIB modules are encouraged to choose names for their modules 822 that will have a low probability of colliding with standard or other 823 enterprise modules. 825 The first line of a PIB module is: 827 PIB-MODULE-NAME PIB-DEFINITIONS ::= BEGIN 829 where PIB-MODULE-NAME is the module name. 831 Like the SMI, additional ASN.1 macros must not be defined in PIB 832 modules. 834 5.1. Importing Definitions 836 Like the SMI, a PIB module which needs to reference an external 837 definition, must use the IMPORTS statement to identify both the 838 descriptor and the module in which the descriptor is defined, where a 839 module is identified by its ASN.1 module name. 841 In particular, a PIB module imports each of the base data types that it 842 uses from COPS-PR-SPPI (defined in this document), and may import as 843 required from other PIB modules. A PIB module may import, from the SMI, 844 (subtree) OIDs for the purpose of defining new OIDs. A PIB module may 845 also import, from MIB modules, OID assignments as well as textual 846 convention definitions providing that their underlying syntax is 847 supported by the SPPI. However, the following must not be included in 848 an IMPORTS statement: 850 - named types defined by ASN.1 itself, specifically: INTEGER, OCTET 851 STRING, OBJECT IDENTIFIER, SEQUENCE, SEQUENCE OF type, 852 - the BITS construct. 854 For each ASN.1 macro that a PIB uses, it must import that macro's 855 definition from the COPS-PR-SPPI. 857 5.2. Reserved Keywords 859 In addition to the reserved keywords listed in the SMI, the following 860 must not be used as descriptors or module names: 862 Draft SPPI February 2001 864 EXTENDS INSTALL-ERRORS Integer64 PIB-MIN-ACCESS PIB-ACCESS 865 PIB-INDEX PIB-REFERENCES PIB-TAG SUBJECT-CATEGORIES UNIQUENESS 866 Unsigned64 868 6. Naming Hierarchy 870 The SPPI uses the same OBJECT IDENTIFIER naming hierarchy as the SMI. 871 That is, OIDs are typically assigned to PIB modules from the subtree 872 administered by the Internet Assigned Numbers Authority (IANA). 873 However, like the SMI, the SPPI does not prohibit the definition of PRCs 874 in other portions of the OID tree. 876 7. Mapping of the MODULE-IDENTITY macro 878 7.1. Mapping of the SUBJECT-CATEGORIES clause 880 The SUBJECT-CATEGORIES clause, which must be present, identifies one or 881 more categories of provisioning data for which this PIB module defines 882 provisioning information. For use with the COPS-PR protocol, the 883 individual subject categories are mapped to COPS Client Types [COPS-PR]. 884 The subject categories are identified either: 886 - via the keyword "all", indicating the PIB module defines 887 provisioning information relevant for all subject categories (and 888 thus, all COPS Client Types), or 890 - a list of named-number enumerations, where each number which must 891 be greater than zero, identifies a subject category, and is mapped 892 to the Client Type which is identified by that same number in the 893 COPS protocol. The namespace for these named numbers is global and 894 therefore the labels should be assigned consistently across PIB 895 modules. At present time, no more than one named-number 896 enumeration should be specified. 898 Note that the list of categories specified in a PIB module's SUBJECT- 899 CATEGORIES clause is not exclusive. That is, some other specification 900 might (e.g., at a future date) specify additional COPS Client Types to 901 which the module is relevant. 903 When a PIB module applies to multiple subject categories, that PIB 904 module exists in multiple virtual information stores, one for each 905 Client-Type. 907 Draft SPPI February 2001 909 8. Mapping of the OBJECT-TYPE macro 911 The SPPI requires that all attribute definitions be contained within a 912 PRC, i.e., within a table definition. 914 8.1. Mapping of the SYNTAX clause 916 The SYNTAX clause, which must be present within the definition of an 917 attribute, defines the abstract data structure of that attribute. The 918 data structure must be one of the following: a base type, the BITS 919 construct, or a textual convention. 921 The SYNTAX clause must also be present for the table and row definitions 922 of a PRC, and in this case must be a SEQUENCE OF or SEQUENCE (see 923 section 8.1.7 below). 925 The base types are an extended subset of the SMI's base types: 927 - built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER, 929 - application-defined types: Integer32, IpAddress, Unsigned32, 930 TimeTicks, Integer64 and Unsigned64. 932 A textual convention is a newly-defined type defined as a sub-type of a 933 base type [TC]. The value of an attribute whose syntax is defined using 934 a textual convention is encoded "on-the-wire" according to the textual 935 convention's underlying base type. 937 Note that the set of base types has been chosen so as to provide 938 sufficient variety of on-the-wire encodings for attribute values; base 939 types should contain a minimum of semantics. Semantics should, to the 940 extent possible, be incorporated into a data type through the use of a 941 textual convention. Thus, the IpAddress and TimeTicks data types should 942 really be defined as textual conventions because they contain semantics. 943 However, they are defined here as base types so as to avoid confusion 944 with the SMI which defines them as base types. 946 The differences from the SMI in the semantics of ObjectSyntax are now 947 described. 949 8.1.1. Counter32 951 The Counter32 type is not supported by the SPPI. 953 Draft SPPI February 2001 955 8.1.2. Gauge32 957 The Gauge32 type is not supported by the SPPI. 959 8.1.3. Opaque 961 The Opaque type is not supported by the SPPI. 963 8.1.4. Counter64 965 The Counter64 type is not supported by the SPPI. 967 8.1.5. Integer64 969 The Integer64 type represents integer-valued information between -2^63 970 and 2^63-1 inclusive (-9223372036854775808 to 9223372036854775807 971 decimal). While Integer64 may be sub-typed to be more constrained, if 972 the constraint results in all possible values being contained in the 973 range (-2147483648..2147483647), then the Integer32 type must be used 974 instead of Integer64. 976 8.1.6. Unsigned64 978 The Unsigned64 type represents integer-valued information between 0 and 979 2^64-1 inclusive (0 to 18446744073709551615 decimal). While Unsigned64 980 may be sub-typed to be more constrained, if the constraint results in 981 all possible values being contained in the range (0..4294967295), then 982 the Unsigned32 type must be used instead of Unsigned64. 984 8.1.7. Provisioning Classes 986 The operations (on PIBs) supported by the SPPI apply exclusively to 987 PRCs. Each PRC is modelled as a tabular structure, i.e., a table. Each 988 instance of a particular PRC has the same set of attributes. The set of 989 attributes which belong to every instance of a particular PRC is 990 modelled as a row in the table. This model is formalized by using the 991 OBJECT-TYPE macro to define both: 993 - the PRC as a whole, called the table definition, and 995 - the characteristics of every instance of a particular PRC, called 996 the row definition. 998 In the table definition, the SYNTAX clause has the form: 1000 Draft SPPI February 2001 1002 SEQUENCE OF 1004 where refers to the SEQUENCE type of its attribute 1005 definitions. In the row definition, the SYNTAX clause has the form: 1007 1009 where is a SEQUENCE type defined as follows: 1011 ::= SEQUENCE { , ... , } 1013 where there is one for each attribute, and each is of the 1014 form: 1016 1018 where is the descriptor naming an attribute, and 1019 has the value of that attribute's SYNTAX clause, except that both sub- 1020 typing information and the named values for enumerated integers or the 1021 named bits for the BITS construct, are omitted from . 1023 8.2. Mapping of the MAX-ACCESS clause 1025 The MAX-ACCESS clause is not supported by the SPPI. 1027 8.3. Mapping of the PIB-ACCESS clause 1029 The PIB-ACCESS clause must be present for a PRC's table definition, and 1030 must not be present for any other OBJECT-TYPE definition. The PIB- 1031 ACCESS clause defines what kind of access is appropriate for the PRC. 1032 The PIB-ACCESS clause also optionally (default value is 127) provides a 1033 number which is used in the algorithmic conversion of a PIB to a MIB 1034 (see Appendix A). 1036 - the value "install" is used to indicate a PRC which a PDP can 1037 install in the PEP as provisioning information. 1039 - the value "notify" is used to indicate a PRC for which the PEP must 1040 notify the PDP of all its instances and attribute values of that 1041 PRC. 1043 - the value "install-notify" is used to indicate the uncommon type of 1044 PRC which has both characteristics: "install" and "notify". 1046 Draft SPPI February 2001 1048 the value "report-only" is used to indicate a PRC which has neither the 1049 "install" characteristic nor the "notify" characteristic. However, 1050 instances of such a PRC may be included in synchronous/asynchronous 1051 reports generated by the PEP. (Note: PRCs having the "install" and/or 1052 "notify" characteristics may also be included in reports generated by 1053 the PEP.) 1055 8.4. Mapping of the INSTALL-ERRORS clause 1057 The INSTALL-ERRORS clause, which may optionally be present for a PRC's 1058 table definition, and must be absent otherwise, lists one or more 1059 potential reasons for rejecting an install or a removal of an instance 1060 of the PRC. Each reason consists of a named-number enumeration, where 1061 the number represents a PRC-specific error-code to be used in a COPS 1062 protocol message, as the Sub-Error Code, with the Error-Code set to 1063 priSpecificError (see [COPS-PR]). The semantics of each named-number 1064 enumeration should be described in the PRC's DESCRIPTION clause. 1066 The numbers listed in an INSTALL-ERRORS must be greater than zero and 1067 less than 65536. If this clause is not present, an install/remove can 1068 still fail, but no PRC-specific error is available to be reported. 1070 8.5. Mapping of the PIB-INDEX clause 1072 The PIB-INDEX clause, which must be present for a row definition (unless 1073 an AUGMENTS or an EXTENDS clause is present instead), and must be absent 1074 otherwise, defines identification information for instances of the PRC. 1076 The PIB-INDEX clause includes exactly one descriptor. This descriptor 1077 specifies an attribute (typically, but not necessarily of the same PRC) 1078 which is used to identify an instance of that PRC. The syntax of this 1079 attribute is required to be InstanceId (a textual convention with an 1080 underlying syntax of Unsigned32), and it has no semantics other than its 1081 use in identifying the PRC instance. The OBJECT IDENTIFIER which 1082 identifies an instance of a PRC is formed by appending one sub- 1083 identifier to the OID which identifies that PRC's row definition. The 1084 value of the additional sub-identifier is that instance's value of the 1085 attribute specified in the INDEX clause. 1087 Note that SPPI does not permit use of the IMPLIED keyword in a PIB-INDEX 1088 clause. 1090 Draft SPPI February 2001 1092 8.6. Mapping of the INDEX clause 1094 The INDEX clause is optionally present if a PIB-INDEX clause is present, 1095 and must be absent otherwise. If present, the INDEX clause can contain 1096 any number of attributes, and is used only by the algorithmic conversion 1097 of a PIB to a MIB (see Appendix A). 1099 An IMPLIED keyword can be present in an INDEX clause if so desired. 1101 8.7. Mapping of the AUGMENTS clause 1103 The AUGMENTS clause, which must not be present except in row 1104 definitions, is an alternative to the PIB-INDEX clause and the EXTENDS 1105 clause. Every row definition has exactly one of: a PIB-INDEX clause, an 1106 AUGMENTS clause, or an EXTENDS clause. 1108 A row definition which has a PIB-INDEX clause is called a base row 1109 definition. A row definition which has an AUGMENTS clause is called a 1110 row augmentation, where the AUGMENTS clause names the base row 1111 definition which is augmented by this row augmentation. (Thus, a row 1112 augmentation cannot itself be augmented.) 1114 A PRC whose row definition is a row augmentation is called an augmenting 1115 PRC. Instances of an augmenting PRC are identified according to the 1116 PIB-INDEX clause of the base row definition named in the AUGMENTS 1117 clause. Further, instances of an augmenting PRC exist according to the 1118 same semantics as instances of the PRC which it augments. As such, when 1119 an instance of a PRC is installed or removed, an instance of every PRC 1120 which augments it is also installed or removed (for more details, see 1121 [COPS-PR]). 1123 8.8. Mapping of the EXTENDS clause 1125 The EXTENDS clause, which must not be present except in row definitions, 1126 is an alternative to the PIB-INDEX clause and the AUGMENTS clause. 1127 Every row definition has exactly one of: a PIB-INDEX clause, an AUGMENTS 1128 clause, or an EXTENDS clause. 1130 A row definition which has an EXTENDS clause is called a sparse row 1131 augmentation, where the EXTENDS clause names the row definition which is 1132 sparsely-augmented by this sparse row augmentation. The sparsely- 1133 augmented row can be a base row definition, or another sparse row 1134 augmentation. 1136 Draft SPPI February 2001 1138 A PRC whose row definition is a sparse row augmentation is called a 1139 sparsely augmenting PRC. Instances of a sparsely augmenting PRC are 1140 identified according to the PIB-INDEX clause of the row definition named 1141 in the sparsely augmenting PRC's EXTENDS clause. 1143 An instance of a sparsely augmenting PRC can not exist unless a 1144 corresponding instance of the PRC which it sparsely augments exists. As 1145 such, when an instance of a PRC is removed, an instance of any PRC which 1146 sparsely augments it is also removed. However, an instance of a 1147 sparsely augmenting PRC need not exist when the corresponding instance 1148 of the PRC that it sparsely augments exists. Thus, an instance of a 1149 sparsely augmenting PRC can be installed at the same time as or 1150 subsequent to the installation of, and can be removed prior to the 1151 removal of, the corresponding instance of the PRC that it sparsely 1152 augments. So, instances of a sparsely augmenting PRC must be installed 1153 explicitly, but are removed either implicitly (via removal of the 1154 augmented PRI) or explicitly. 1156 8.8.1. Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1158 When defining instance identification information for a PRC: 1160 - If there is a one-to-one correspondence between instances of this 1161 PRC and instances of an existing PRC, then the AUGMENTS clause 1162 should be used. 1164 - Otherwise, if there is a sparse relationship between instances of 1165 this PRC and instances of an existing PRC, then an EXTENDS clause 1166 should be used. 1168 - Otherwise, a PIB-INDEX clause should be used which names its own 1169 InstanceId attribute. 1171 8.9. Mapping of the UNIQUENESS clause 1173 The UNIQUENESS clause, which is optionally present for any row 1174 definition which has a PIB-INDEX clause, and must be absent otherwise, 1175 lists a set of zero or more of the PRC's attributes, for which no two 1176 instances of the PRC can have the same set of values. The specified set 1177 of attributes provide a necessary and sufficient set of values by which 1178 to identify an instance of this PRC. The attribute contained in the 1179 PIB-INDEX clause may not be present in the UNIQUENESS clause. By 1180 definition, an attribute may not appear more than once in a UNIQUENESS 1181 clause. A UNIQUENESS clause containing zero attributes indicates that 1182 Draft SPPI February 2001 1184 it's possible for two instances of the PRC to have identical values for 1185 all attributes except, of course, for the one named in the PIB-INDEX 1186 clause. 1188 Even though the UNIQUENESS clause is optional, its inclusion is 1189 recommended wherever it provides useful information. 1191 8.10. Mapping of the PIB-REFERENCES clause 1193 The PIB-REFERENCES clause, which must be present for any attribute which 1194 has the SYNTAX of ReferenceId, and must be absent otherwise, names the 1195 PRC, an instance of which is referenced by the ReferenceId attribute. 1196 For example usages of the PIB-REFERENCES clause, see Appendix B. 1198 8.11. Mapping of the PIB-TAG clause 1200 The PIB-TAG clause, which must be present for an attribute which has the 1201 SYNTAX TagReferenceId, and must be absent otherwise, is used to indicate 1202 that this attribute references a "tag list" of instances of another PRC. 1203 Such a tag list (similar in concept to the usage of the same term in 1204 [APPL]) is formed by all instances of the other PRC which have the same 1205 (tag) value of a particular attribute of that other PRC. The particular 1206 attribute of the other PRC, which must have the SYNTAX TagId, is named 1207 in the PIB-TAG clause. For an example usage of the PIB-TAG clause, see 1208 Appendix B. 1210 9. Mapping of the OBJECT-IDENTITY macro 1212 The OBJECT-IDENTITY macro is used in PIB modules to define information 1213 about an OBJECT IDENTIFIER assignment. 1215 Draft SPPI February 2001 1217 10. Mapping of the OBJECT-GROUP macro 1219 For conformance purposes, it is useful to define a conformance group as 1220 a collection of related PRCs and their attributes. The OBJECT-GROUP 1221 macro (directly) defines the collection of attributes which belong to a 1222 conformance group. Since each attribute included in the collection 1223 belongs to a PRC, the collection of related PRCs which belong to a 1224 conformance group is also specified (indirectly) as the set of PRCs to 1225 which the included attributes belong. 1227 10.1. Mapping of the OBJECTS clause 1229 The OBJECTS clause, which must be present, is used to specify each 1230 attribute contained in the conformance group. Each of the specified 1231 attributes must be defined in the same PIB module as the OBJECT-GROUP 1232 macro appears. 1234 It is required that every attribute defined in a PIB module be contained 1235 in at least one conformance group. This avoids the common error of 1236 adding a new attribute to a module and forgetting to add the new 1237 attribute to a group. 1239 11. Mapping of the MODULE-COMPLIANCE macro 1241 The MODULE-COMPLIANCE macro is used to convey a minimum set of 1242 requirements with respect to implementation of one or more PIB modules. 1244 A requirement on all "standard" PIB modules is that a corresponding 1245 MODULE-COMPLIANCE specification is also defined, either in the same 1246 module or in a companion module. 1248 11.1. Mapping of the MODULE clause 1250 The MODULE clause, which must be present, is repeatedly used to name 1251 each PIB module for which compliance requirements are being specified. 1252 Each PIB module is named by its module name, and optionally, by its 1253 associated OBJECT IDENTIFIER as well. The module name can be omitted 1254 when the MODULE-COMPLIANCE invocation occurs inside a PIB module, to 1255 refer to the encompassing PIB module. 1257 11.1.1. Mapping of the MANDATORY-GROUPS clause 1259 The MANDATORY-GROUPS clause, which need not be present, names the one or 1260 more conformance groups within the correspondent PIB module which are 1261 Draft SPPI February 2001 1263 unconditionally mandatory for implementation. If an agent claims 1264 compliance to the PIB module, then it must implement each and every 1265 attribute (and therefore the PRCs to which they belong) within each 1266 conformance group listed. 1268 11.1.2. Mapping of the GROUP clause 1270 The GROUP clause, which need not be present, is repeatedly used to name 1271 each conformance group which is conditionally mandatory for compliance 1272 to the PIB module. The GROUP clause can also be used to name 1273 unconditionally optional groups. A group named in a GROUP clause must 1274 be absent from the correspondent MANDATORY-GROUPS clause. 1276 Conditionally mandatory groups include those which are mandatory only if 1277 a particular protocol is implemented, or only if another group is 1278 implemented. A GROUP clause's DESCRIPTION specifies the conditions 1279 under which the group is conditionally mandatory. 1281 A group which is named in neither a MANDATORY-GROUPS clause nor a GROUP 1282 clause, is unconditionally optional for compliance to the PIB module. 1284 11.1.3. Mapping of the OBJECT clause 1286 The OBJECT clause, which need not be present, is repeatedly used to 1287 specify each attribute for which compliance has a refined requirement 1288 with respect to the PIB module definition. The attribute must be 1289 present in one of the conformance groups named in the correspondent 1290 MANDATORY-GROUPS clause or GROUP clauses. 1292 By definition, each attribute specified in an OBJECT clause follows a 1293 MODULE clause which names the PIB module in which that attribute is 1294 defined. Therefore, the use of an IMPORTS statement, to specify from 1295 where such attributes are imported, is redundant and is not required in 1296 a PIB module. 1298 11.1.3.1. Mapping of the SYNTAX clause 1300 The SYNTAX clause, which need not be present, is used to provide a 1301 refined SYNTAX for the attribute named in the correspondent OBJECT 1302 clause. The refined syntax is the minimum level of support needed for 1303 this attribute in order to be compliant. 1305 Draft SPPI February 2001 1307 11.1.3.2. Mapping of the WRITE-SYNTAX clause 1309 The WRITE-SYNTAX clause is not supported by the SPPI. 1311 11.1.3.3. Mapping of the PIB-MIN-ACCESS clause 1313 The PIB-MIN-ACCESS clause, which need not be present, is used to define 1314 the minimal level of access for the attribute named in the correspondent 1315 OBJECT clause. If this clause is absent, the minimal level of access is 1316 the same as the maximal level specified in the PIB-ACCESS clause of the 1317 correspondent invocation of the OBJECT-TYPE macro. If present, this 1318 clause must specify a subset of the access specified in the 1319 correspondent PIB-ACCESS clause, where: "install" is a subset of 1320 "install-notify", "notify" is a subset of "install-notify", and "not- 1321 accessible" is a subset of all other values. 1323 An implementation is compliant if the level of access it provides is the 1324 same or a superset of the minimal level in the MODULE-COMPLIANCE macro 1325 and the same or a subset of the maximal level in the PIB-ACCESS clause. 1327 12. Textual Conventions 1329 When designing a PIB module, it is often useful to define new data types 1330 similar to those defined in the SPPI. In comparison to a type defined 1331 in the SPPI, each of these new types has a different name, a similar 1332 syntax, and specific semantics. These newly defined types are termed 1333 textual conventions, and are used for the convenience of humans reading 1334 the PIB module. 1336 Attributes defined using a textual convention are always encoded by 1337 means of the rules that define their underlying type. 1339 12.1. Mapping of the TEXTUAL-CONVENTION macro 1341 The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics 1342 associated with a textual convention. It should be noted that the 1343 expansion of the TEXTUAL-CONVENTION macro is something which 1344 conceptually happens during implementation and not during run-time. 1346 The name of a textual convention must consist of one or more letters or 1347 digits, with the initial character being an upper case letter. The name 1348 must not conflict with any of the reserved words listed in section 5.2, 1349 should not consist of all upper case letters, and shall not exceed 64 1350 characters in length. (However, names longer than 32 characters are not 1351 Draft SPPI February 2001 1353 recommended.) The hyphen is not allowed in the name of a textual 1354 convention (except for use in information modules converted from SMIv1 1355 which allowed hyphens in ASN.1 type assignments). Further, all names 1356 used for the textual conventions defined in all "standard" PIB modules 1357 shall be unique. 1359 12.1.1. Mapping of the SYNTAX clause 1361 The SYNTAX clause, which must be present, defines abstract data 1362 structure corresponding to the textual convention. The data structure 1363 must be one of the following: a base type (see the SYNTAX clause of an 1364 OBJECT-TYPE macro), or the BITS construct. Note that this means that 1365 the SYNTAX clause of a Textual Convention can not refer to a previously 1366 defined Textual Convention. 1368 12.1.1.1. Sub-typing of Textual Conventions 1370 The SYNTAX clause of a TEXTUAL CONVENTION macro may be sub-typed in the 1371 same way as the SYNTAX clause of an OBJECT-TYPE macro. 1373 13. Extending a PIB Module 1375 The SMI's rules for extending an information module are augmented with 1376 the following rules: 1378 13.1. OBJECT-TYPE Definitions 1380 An invocation of the OBJECT-TYPE macro may also be revised in any of the 1381 following ways: 1383 - An INSTALL-ERRORS clause may be added or an existing INSTALL-ERRORS 1384 clause have additional errors defined. 1386 - Additional named-number enumerations may be added to a SUBJECT- 1387 CATEGORIES clause. 1389 Draft SPPI February 2001 1391 14. Appendix A: Mapping a PIB to a MIB 1393 Since the SPPI is modelled on the SMI, a PIB can be easily and 1394 algorithmically mapped into a MIB. This mapping is achieved by means of 1395 the following rules: 1397 - Modify the module's module name by appending "-MIB" to the name. 1399 - Change the OID assigned to the MODULE-IDENTITY to be different 1400 value. 1402 - Replace the keyword PIB-DEFINITIONS with the keyword DEFINITIONS. 1404 - Modify the module names of all external references to PIB modules 1405 by appending "-MIB" to each such module name. 1407 - For each PRC definition, if an INDEX clause is absent, change the 1408 "PIB-INDEX" keyword to "INDEX"; otherwise, delete the PIB-INDEX 1409 clause. 1411 - Delete all of the following clauses: PIB-ACCESS, PIB-REFERENCES, 1412 PIB-TAG, UNIQUENESS, INSTALL-ERRORS, and SUBJECT-CATEGORIES. 1414 - Change all PIB-MIN-ACCESS clauses to MIN-ACCESS clauses, modifying 1415 "install" and "install-notify" to "read-create", and "notify" to 1416 "read-only". 1418 - Add a MAX-ACCESS clause for each OBJECT-TYPE. For each table 1419 definition and row definition, the MAX-ACCESS is "not-accessible". 1420 For each attribute that is in the INDEX clause, the MAX-ACCESS is 1421 "not-accessible". For the remaining attributes, the MAX-ACCESS is 1422 "read-create". 1424 - Add a columnar attribute of type RowStatus with a descriptor and 1425 appropriate DESCRIPTION. The descriptor can be formed by appending 1426 the nine characters "RowStatus" to the end of the PRC's descriptor 1427 (truncated if necessary to avoid the resulting descriptor being too 1428 long). The optional number provided by the PIB-ACCESS clause is 1429 used as the OID for this columnar attribute. If no number is 1430 provided by the PIB-ACCESS clause, then the default number 127 is 1431 used. 1433 - Modify any SYNTAX clause which has a base data type which is not 1434 allowed in the SMI, either to be a valid SMI data type or to omit 1435 the OBJECT-TYPE or TEXTUAL-CONVENTION definition and all references 1437 Draft SPPI February 2001 1439 to it. Since it is not clear (at this time) which is the best SMI 1440 data type to use, the conversion SHOULD provide a configurable 1441 option allowing a choice from at least the following: 1443 - convert to an OCTET STRING of the relevant size. 1444 Specifically, this option would map both Integer64 and 1445 Unsigned64 to OCTET STRING (SIZE(8)), or 1447 - omit them from the conversion, or 1449 - map Integer64 and Unsigned64 to Counter64 (even though this 1450 has problems representing negative numbers, and unwanted 1451 counter semantics.) 1453 Draft SPPI February 2001 1455 15. Appendix B: Example usage of PIB-REFERENCES and PIB-TAG clauses 1457 The following example demonstrates the use of the PIB-REFERENCES and 1458 PIB-TAG clauses. 1460 In this example, the PIB-REFERENCES clause is used by the 1461 qosIfDscpMapQueue attribute to indicate the PRC of which it references 1462 an instance, and similarly, by the qosIfDscpMapThresh attribute. 1464 The qosIfDscpMapTable PRC has an instance for each DSCP of a particular 1465 "map", but there is no PRC defined for a map itself; rather, a map 1466 consists of all instances of qosIfDscpMapTable which have the same value 1467 of qosIfDscpMapMapId. That is, a tag list is formed by all instances of 1468 qosIfDscpMapTable which have the same value of qosIfDscpMapMapId. This 1469 tag list is referenced by the attribute qosIfDscpAssignDscpMap, and its 1470 use of the PIB-TAG clause indicates this. 1472 qosIfDscpAssignTable OBJECT-TYPE 1473 SYNTAX SEQUENCE OF QosIfDscpAssignEntry 1474 PIB-ACCESS install 1475 STATUS current 1476 DESCRIPTION " " 1477 ::= { qosIfParameters 9 } 1479 qosIfDscpAssignEntry OBJECT-TYPE 1480 SYNTAX QosIfDscpAssignEntry 1481 STATUS current 1482 DESCRIPTION 1483 "An instance of the qosIfDscpAssign class." 1484 PIB-INDEX { qosIfDscpAssignPrid } 1485 UNIQUENESS { qosIfDscpAssignName, qosIfDscpAssignRoles } 1486 ::= { qosIfDscpAssignTable 1 } 1488 QosIfDscpAssignEntry ::= SEQUENCE { 1489 qosIfDscpAssignPrid InstanceId, 1490 qosIfDscpAssignName SnmpAdminString, 1491 qosIfDscpAssignRoles RoleCombination, 1492 qosIfDscpAssignDscpMap TagReferenceId 1493 } 1495 qosIfDscpAssignDscpMap OBJECT-TYPE 1496 SYNTAX TagReferenceId 1497 PIB-TAG qosIfDscpMapMapId -- attribute defined below 1498 STATUS current 1499 DESCRIPTION 1501 Draft SPPI February 2001 1503 "The DSCP map which is applied to interfaces of type 1504 qosIfDscpAssignName which have a role combination of 1505 qosIfDscpAssignRoles." 1506 ::= { qosIfDscpAssignEntry 3 } 1508 -- 1509 -- DSCP to Queue and Threshold Mapping Table 1510 -- 1512 qosIfDscpMapTable OBJECT-TYPE 1513 SYNTAX SEQUENCE OF QosIfDscpMapEntry 1514 PIB-ACCESS install 1515 STATUS current 1516 DESCRIPTION 1517 "Assigns DSCP values to queues and thresholds for an arbitrary 1518 DSCP map. This map can then be assigned to various interface 1519 and role combination pairs." 1520 ::= { qosIfParameters 10 } 1522 qosIfDscpMapEntry OBJECT-TYPE 1523 SYNTAX QosIfDscpMapEntry 1524 STATUS current 1525 DESCRIPTION 1526 "An instance of the qosIfDscpMap class." 1527 PIB-INDEX { qosIfDscpMapPrid } 1528 UNIQUENESS { qosIfDscpMapMapId, qosIfDscpMapDscp } 1529 ::= { qosIfDscpMapTable 1 } 1531 QosIfDscpMapEntry ::= SEQUENCE { 1532 qosIfDscpMapPrid InstanceId, 1533 qosIfDscpMapMapId TagId, 1534 qosIfDscpMapDscp Dscp, 1535 qosIfDscpMapQueue ReferenceId, 1536 qosIfDscpMapThresh ReferenceId 1537 } 1539 qosIfDscpMapMapId OBJECT-TYPE 1540 SYNTAX TagId 1541 STATUS current 1542 DESCRIPTION 1543 "An integer that identifies the DSCP map to which this PRI 1544 belongs." 1545 ::= { qosIfDscpMapEntry 2 } 1547 qosIfDscpMapQueue OBJECT-TYPE 1548 Draft SPPI February 2001 1550 SYNTAX ReferenceId 1551 PIB-REFERENCES qosIfQueueTable 1552 STATUS current 1553 DESCRIPTION 1554 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1555 the queue identified by qosIfQueuePrid in qosIfQueueTable. 1556 For a given DSCP map, all the queues must belong to a single 1557 queue set." 1558 ::= { qosIfDscpMapEntry 4 } 1560 qosIfDscpMapThresh OBJECT-TYPE 1561 SYNTAX ReferenceId 1562 PIB-REFERENCES qosIfThresholdTable 1563 STATUS current 1564 DESCRIPTION 1565 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1566 the threshold identified by qosIfThresholdId in 1567 qosIfThresholdTable. The threshold set to which this 1568 threshold belongs must be assigned to the queue specified by 1569 qosIfDscpMapQueue." 1570 ::= { qosIfDscpMapEntry 5 } 1572 Draft SPPI February 2001 1574 16. Security Considerations 1576 This document defines a language with which to define provisioning 1577 information. The language itself has no security impact on the 1578 Internet. 1580 17. Authors' Addresses 1582 Keith McCloghrie 1583 Cisco Systems, Inc. 1584 170 West Tasman Drive 1585 San Jose, CA 95134-1706 USA 1586 Phone: +1 408 526 5260 1587 Email: kzm@cisco.com 1589 Michael Fine 1590 Cisco Systems, Inc. 1591 170 West Tasman Drive 1592 San Jose, CA 95134-1706 USA 1593 Phone: +1 408 527 8218 1594 Email: mfine@cisco.com 1596 John Seligson 1597 Nortel Networks, Inc. 1598 4401 Great America Parkway 1599 Santa Clara, CA 95054 USA 1600 Phone: +1 408 495 2992 1601 Email: jseligso@nortelnetworks.com 1603 Kwok Ho Chan 1604 Nortel Networks, Inc. 1605 600 Technology Park Drive 1606 Billerica, MA 01821 USA 1607 Phone: +1 978 288 8175 1608 Email: khchan@nortelnetworks.com 1610 Scott Hahn 1611 Intel 1612 2111 NE 25th Avenue 1613 Hillsboro, OR 97124 USA 1614 Phone: +1 503 264 8231 1615 Email: scott.hahn@intel.com 1617 Draft SPPI February 2001 1619 Ravi Sahita 1620 Intel 1621 2111 NE 25th Avenue 1622 Hillsboro, OR 97124 USA 1623 Phone: +1 503 712 1554 1624 Email: ravi.sahita@intel.com 1626 Andrew Smith 1627 Allegro Networks 1628 6399 San Ignacio Ave. 1629 San Jose 1630 CA 95119 1631 FAX: 415 345 1827 1632 Email: andrew@allegronetworks.com 1634 Francis Reichmeyer 1635 PFN Inc. 1636 University Park at MIT 1637 26 Landsdowne Street 1638 Cambridge, MA 02139 1639 Phone: +1 617 494 9980 1640 Email: franr@pfn.com 1642 18. References 1644 [COPS] 1645 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1646 Sastry, "The COPS (Common Open Policy Service) Protocol" RFC 2748, 1647 January 2000. 1649 [COPS-RSVP] 1650 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1651 Sastry, " COPS usage for RSVP", RFC 2749, January 2000. 1653 [COPS-PR] 1654 Reichmeyer, F., Herzog, S., Chan, K., Durham, D., Yavatkar, R. 1655 Gai, S., McCloghrie, K. and A. Smith, "COPS Usage for Policy 1656 Provisioning" Internet Draft, draft-ietf-rap-cops-pr-04.txt, August 1657 2000. 1659 [SMI] 1660 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1661 and S. Waldbusser. "Structure of Management Information Version 2 1662 (SMIv2)", RFC 2578, April 1999. 1664 Draft SPPI February 2001 1666 [TC] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1667 and S. Waldbusser. "Textual Conventions for SMIv2", RFC 2579, 1668 April 1999. 1670 [CONF] 1671 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1672 and S. Waldbusser. "Conformance Statements for SMIv2", RFC 2580, 1673 April 1999. 1675 [APPL] 1676 Levi, D., Meyer, P., and B. Stewart, "SNMP Applications", RFC 2573, 1677 April 1999. 1679 [ASN1] 1680 Information processing systems -- Open Systems Interconnection -- 1681 Specification of Abstract Syntax Notation One (ASN.1), 1682 International Organization for Standardization. International 1683 Standard 8824, December 1987. 1685 [INETADDR] 1686 M. Daniele, B. Haberman, S. Routhier and J. Schoenwaelder "Textual 1687 Conventions for Internet Network Addresses", RFC 2851, June 2000. 1689 Draft SPPI February 2001 1691 19. Full Copyright Statement 1693 Copyright (C) The Internet Society (2000). All Rights Reserved. 1695 This document and translations of it may be copied and furnished to 1696 others, and derivative works that comment on or otherwise explain it or 1697 assist in its implementation may be prepared, copied, published and 1698 distributed, in whole or in part, without restriction of any kind, 1699 provided that the above copyright notice and this paragraph are included 1700 on all such copies and derivative works. However, this document itself 1701 may not be modified in any way, such as by removing the copyright notice 1702 or references to the Internet Society or other Internet organizations, 1703 except as needed for the purpose of developing Internet standards in 1704 which case the procedures for copyrights defined in the Internet 1705 Standards process must be followed, or as required to translate it into 1706 languages other than English. 1708 The limited permissions granted above are perpetual and will not be 1709 revoked by the Internet Society or its successors or assigns. 1711 This document and the information contained herein is provided on an "AS 1712 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 1713 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 1714 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 1715 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 1716 FITNESS FOR A PARTICULAR PURPOSE." 1717 Draft SPPI February 2001 1719 Table of Contents 1721 1 Introduction .................................................... 2 1722 1.1 Change Log .................................................... 2 1723 1.1.1 Changes made in version published on 13 July 2000 ........... 2 1724 1.1.2 Changes made in version published on 20 September 2000 ...... 3 1725 1.1.3 Changes made in version published on 13 November 2000 ....... 4 1726 1.1.4 Changes made in version published 22 January 2001 ........... 4 1727 1.1.5 Changes made in version published 20 February 2001 .......... 4 1728 2 Use of the SMI .................................................. 4 1729 2.1 Terminology Translation ....................................... 4 1730 2.2 Overview ...................................................... 4 1731 3 Structure of this Specification ................................. 5 1732 4 Definitions ..................................................... 6 1733 5 PIB Modules ..................................................... 19 1734 5.1 Importing Definitions ......................................... 19 1735 5.2 Reserved Keywords ............................................. 19 1736 6 Naming Hierarchy ................................................ 20 1737 7 Mapping of the MODULE-IDENTITY macro ............................ 20 1738 7.1 Mapping of the SUBJECT-CATEGORIES clause ...................... 20 1739 8 Mapping of the OBJECT-TYPE macro ................................ 21 1740 8.1 Mapping of the SYNTAX clause .................................. 21 1741 8.1.1 Counter32 ................................................... 21 1742 8.1.2 Gauge32 ..................................................... 22 1743 8.1.3 Opaque ...................................................... 22 1744 8.1.4 Counter64 ................................................... 22 1745 8.1.5 Integer64 ................................................... 22 1746 8.1.6 Unsigned64 .................................................. 22 1747 8.1.7 Provisioning Classes ........................................ 22 1748 8.2 Mapping of the MAX-ACCESS clause .............................. 23 1749 8.3 Mapping of the PIB-ACCESS clause .............................. 23 1750 8.4 Mapping of the INSTALL-ERRORS clause .......................... 24 1751 8.5 Mapping of the PIB-INDEX clause ............................... 24 1752 8.6 Mapping of the INDEX clause ................................... 25 1753 8.7 Mapping of the AUGMENTS clause ................................ 25 1754 8.8 Mapping of the EXTENDS clause ................................. 25 1755 8.8.1 Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1756 .............................................................. 26 1757 8.9 Mapping of the UNIQUENESS clause .............................. 26 1758 8.10 Mapping of the PIB-REFERENCES clause ......................... 27 1759 8.11 Mapping of the PIB-TAG clause ................................ 27 1760 9 Mapping of the OBJECT-IDENTITY macro ............................ 27 1761 10 Mapping of the OBJECT-GROUP macro .............................. 28 1762 10.1 Mapping of the OBJECTS clause ................................ 28 1763 Draft SPPI February 2001 1765 11 Mapping of the MODULE-COMPLIANCE macro ......................... 28 1766 11.1 Mapping of the MODULE clause ................................. 28 1767 11.1.1 Mapping of the MANDATORY-GROUPS clause ..................... 28 1768 11.1.2 Mapping of the GROUP clause ................................ 29 1769 11.1.3 Mapping of the OBJECT clause ............................... 29 1770 11.1.3.1 Mapping of the SYNTAX clause ............................. 29 1771 11.1.3.2 Mapping of the WRITE-SYNTAX clause ....................... 30 1772 11.1.3.3 Mapping of the PIB-MIN-ACCESS clause ..................... 30 1773 12 Textual Conventions ............................................ 30 1774 12.1 Mapping of the TEXTUAL-CONVENTION macro ...................... 30 1775 12.1.1 Mapping of the SYNTAX clause ............................... 31 1776 12.1.1.1 Sub-typing of Textual Conventions ........................ 31 1777 13 Extending a PIB Module ......................................... 31 1778 13.1 OBJECT-TYPE Definitions ...................................... 31 1779 14 Appendix A: Mapping a PIB to a MIB ............................. 32 1780 15 Appendix B: Example usage of PIB-REFERENCES and PIB-TAG 1781 clauses ...................................................... 34 1782 16 Security Considerations ........................................ 37 1783 17 Authors' Addresses ............................................. 37 1784 18 References ..................................................... 38 1785 19 Full Copyright Statement ....................................... 40