idnits 2.17.1 draft-ietf-rap-sppi-06.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 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 abstract seems to contain references ([SMI,TC,, [COPS-PR], CONF], [COPS-RSVP], [COPS]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1854 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 (11 April 2001) is 8406 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 267, but not defined == Missing Reference: 'APPLICATION 2' is mentioned on line 283, but not defined == Missing Reference: 'APPLICATION 3' is mentioned on line 288, but not defined == Missing Reference: 'APPLICATION 4' is mentioned on line 293, but not defined == Missing Reference: 'APPLICATION 10' is mentioned on line 299, but not defined == Missing Reference: 'APPLICATION 11' is mentioned on line 303, but not defined == Unused Reference: 'IANA-CONSIDERATIONS' is defined on line 1760, but no explicit reference was found in the text ** Downref: Normative reference to an Historic RFC: RFC 3084 (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) -- Possible downref: Non-RFC (?) normative reference: ref. 'IANA' ** Obsolete normative reference: RFC 2434 (ref. 'IANA-CONSIDERATIONS') (Obsoleted by RFC 5226) Summary: 10 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group K. McCloghrie 3 Internet Draft M. Fine 4 Cisco Systems 5 J. Seligson 6 K. Chan 7 Nortel Networks 8 S. Hahn 9 R. Sahita 10 Intel 11 A. Smith 12 Allegro Networks 13 F. Reichmeyer 14 PFN 16 11 April 2001 18 Structure of Policy Provisioning Information (SPPI) 20 draft-ietf-rap-sppi-06.txt 22 Status of this Memo 24 This document is an Internet-Draft and is in full conformance with all 25 provisions of Section 10 of RFC2026. Internet-Drafts are working 26 documents of the Internet Engineering Task Force (IETF), its areas, and 27 its working groups. Note that other groups may also distribute working 28 documents as Internet-Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference material 33 or to cite them other than as ``work in progress.'' 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 Copyright Notice 43 Copyright (C) The Internet Society (2000). All Rights Reserved. 45 SPPI April 2001 47 Abstract 49 RFC 2748 [COPS] defines the COPS protocol, and RFC 2749 [COPS-RSVP] 50 describes how the COPS protocol is used to provide for the outsourcing 51 of policy decisions for RSVP. Another usage of the COPS protocol, for 52 the provisioning of policy, is introduced in RFC 3084 [COPS-PR]. In 53 this provisioning model, the policy information is viewed as a 54 collection of Provisioning Classes (PRCs) and Provisioning Instances 55 (PRIs) residing in a virtual information store, termed the Policy 56 Information Base (PIB). Collections of related Provisioning Classes are 57 defined in a PIB module. PIB modules are written using an adapted 58 subset of SNMP's Structure of Management Information (SMI) [SMI, TC, 59 CONF]. It is the purpose of this document, the Structure of Policy 60 Provisioning Information (SPPI), to define that adapted subset. 62 Conventions used in this document 64 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 65 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 66 document are to be interpreted as described in [RFC-2119]. 68 1. Use of the SMI 70 The SPPI and PIB modules are based on SNMP's SMI and MIB modules, which 71 use an adapted subset of the ASN.1 data definition language [ASN1]. The 72 decision to base the definition of PIB modules on this format allows for 73 the leveraging of the community's knowledge, experience and tools of the 74 SMI and MIB modules. 76 1.1. Terminology Translation 78 The SMI uses the term "managed objects" to refer to object types, both 79 tabular types with descriptors such as xxxTable and xxxEntry, as well as 80 scalar and columnar object types. The SPPI does not use the term 81 "object" so as to avoid confusion with COPS protocol objects. Instead, 82 the SPPI uses the term Provisioning Class (PRC) for the table and row 83 definitions (the xxxTable and xxxEntry objects, respectively), and 84 Provisioning Instance (PRI) for an instantiation of a row definition. 85 For a columnar object of a table definition, the SPPI uses the term 86 "attribute" of a Provisioning Class. (The SPPI does not support the 87 equivalent of the SMI's scalar objects.) 88 SPPI April 2001 90 1.2. Overview 92 SNMP's SMI is divided into five parts: module definitions, object 93 definitions, notification definitions [SMI], textual convention 94 definitions [TC] and conformance definitions [CONF]. 96 - The SMI's MODULE-IDENTITY macro is used to convey the semantics of 97 a MIB module. The SPPI uses this macro to convey the semantics of 98 a PIB module. 100 - The SMI's OBJECT-TYPE macro is used to convey the syntax and 101 semantics of managed objects. The SPPI uses this macro to convey 102 the syntax and semantics of PRCs and their attributes. 104 - The SMI's notification definitions are not used (at this time) by 105 the SPPI. (Note that the use of the keyword 'notify' in the SPPI 106 is not related to the SMI's notifications). 108 - The SMI's TEXTUAL CONVENTION macro allows new data types to be 109 defined. The SPPI uses this macro to define new data types having 110 particular syntax and semantics which is common to several 111 attributes of one of more PRCs. 113 - The SMI's conformance definitions define several macros: the 114 OBJECT-GROUP macro, the NOTIFICATION-GROUP macro, the MODULE- 115 COMPLIANCE macro and the AGENT-CAPABILITIES macro. The SPPI uses 116 the OBJECT-GROUP and MODULE-COMPLIANCE macros to specify acceptable 117 lower-bounds of implementation of the attributes of PRCs, and 118 thereby indirectly, acceptable lower-bounds of implementation of 119 the PRCs themselves. The NOTIFICATION-GROUP macro is not used (at 120 this time) by the SPPI. Potential usage by the SPPI of the AGENT- 121 CAPABILITIES macro is for further study. 123 2. Structure of this Specification 125 The SMI is specified in terms of an ASN.1 definition together with 126 descriptive text for each element introduced in that ASN.1 definition. 127 This document specifies the SPPI also via a ASN.1 definition, which is a 128 modified version of the SMI's definition, together with descriptive text 129 for only those elements in the SPPI's ASN.1 definition which have 130 differences from the SMI's. For elements in the ASN.1 definition which 131 have no descriptive text in this specification, the reader is referred 132 to the SMI's descriptive text for that element. 134 SPPI April 2001 136 3. Definitions 138 COPS-PR-SPPI DEFINITIONS ::= BEGIN 140 IMPORTS ObjectName, SimpleSyntax, ExtUTCTime, mgmt 141 FROM SNMPv2-SMI; 143 -- the root for PIB definitions 145 pib OBJECT IDENTIFIER ::= { mgmt 2 } 147 -- definitions for PIB modules 149 MODULE-IDENTITY MACRO ::= 150 BEGIN 151 TYPE NOTATION ::= 152 SubjectPart -- new 153 "LAST-UPDATED" value(Update ExtUTCTime) 154 "ORGANIZATION" Text 155 "CONTACT-INFO" Text 156 "DESCRIPTION" Text 157 RevisionPart 159 VALUE NOTATION ::= 160 value(VALUE OBJECT IDENTIFIER) 162 SubjectPart ::= -- new 163 "SUBJECT-CATEGORIES" "{" Categories "}" 164 Categories ::= -- new 165 CategoryIDs 166 | "all" 167 CategoryIDs ::= -- new 168 CategoryID 169 | CategoryIDs "," CategoryID 170 CategoryID ::= -- new 171 identifier "(" number ")" -- number is positive 173 RevisionPart ::= 174 Revisions 175 | empty 176 Revisions ::= 177 Revision 178 | Revisions Revision 179 Revision ::= 180 "REVISION" value(Update ExtUTCTime) 181 SPPI April 2001 183 "DESCRIPTION" Text 185 -- a character string as defined in [SMI] 186 Text ::= value(IA5String) 187 END 189 -- 191 OBJECT-IDENTITY MACRO ::= 192 BEGIN 193 TYPE NOTATION ::= 194 "STATUS" Status 195 "DESCRIPTION" Text 196 ReferPart 198 VALUE NOTATION ::= 199 value(VALUE OBJECT IDENTIFIER) 201 Status ::= 202 "current" 203 | "deprecated" 204 | "obsolete" 206 ReferPart ::= 207 "REFERENCE" Text 208 | empty 210 -- a character string as defined in [SMI] 211 Text ::= value(IA5String) 212 END 214 -- syntax of attributes 216 -- the "base types" defined here are: 217 -- 3 built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER 218 -- 7 application-defined types: Integer32, IpAddress, Unsigned32, 219 -- TimeTicks, Opaque, Integer64 and Unsigned64 221 ObjectSyntax ::= 222 CHOICE { 223 simple 224 SimpleSyntax, 226 -- note that SEQUENCEs for table and row definitions 227 SPPI April 2001 229 -- are not mentioned here... 231 application-wide 232 ApplicationSyntax 233 } 235 -- application-wide types 237 ApplicationSyntax ::= 238 CHOICE { 239 ipAddress-value 240 IpAddress, 242 timeticks-value 243 TimeTicks, 245 arbitrary-value 246 Opaque, 248 unsigned-integer-value 249 Unsigned32, 251 large-integer-value -- new 252 Integer64, 254 large-unsigned-integer-value -- new 255 Unsigned64 256 } 258 -- the following 5 types are copied from the SMI 260 -- indistinguishable from INTEGER, but never needs more than 261 -- 32-bits for a two's complement representation 262 Integer32 ::= 263 INTEGER (-2147483648..2147483647) 265 -- (this is a tagged type for historical reasons) 266 IpAddress ::= 267 [APPLICATION 0] 268 IMPLICIT OCTET STRING (SIZE (4)) 269 -- ******* THIS TYPE DEFINITION IS DEPRECATED ******* 270 -- The IpAddress type represents a 32-bit internet 271 -- IPv4 address. It is represented as an OctetString 272 -- of length 4, in network byte-order. 274 SPPI April 2001 276 -- Note that the IpAddress type is present for 277 -- historical reasons. IPv4 and IPv6 addresses should 278 -- be represented using the INET-ADDRESS-MIB 279 -- defined in [INETADDR]. 281 -- an unsigned 32-bit quantity 282 Unsigned32 ::= 283 [APPLICATION 2] 284 IMPLICIT INTEGER (0..4294967295) 286 -- hundredths of seconds since an epoch 287 TimeTicks ::= 288 [APPLICATION 3] 289 IMPLICIT INTEGER (0..4294967295) 291 --for backward compatibility only 292 Opaque ::= 293 [APPLICATION 4] 294 IMPLICIT OCTET STRING 296 -- the following 2 types are not present in the SMI 298 Integer64 ::= 299 [APPLICATION 10] 300 IMPLICIT INTEGER (-9223372036854775808..9223372036854775807) 302 Unsigned64 303 [APPLICATION 11] 304 IMPLICIT INTEGER (0..18446744073709551615) 306 -- definition for Provisioning Classes and their attributes 307 -- (differences from the SMI are noted in the ASN.1 comments) 309 OBJECT-TYPE MACRO ::= 310 BEGIN 311 TYPE NOTATION ::= 312 "SYNTAX" Syntax 313 UnitsPart 314 "PIB-ACCESS" Access -- modified 315 PibReferencesPart -- new 316 PibTagPart -- new 317 "STATUS" Status 318 "DESCRIPTION" Text 319 ErrorsPart -- new 320 SPPI April 2001 322 ReferPart 323 IndexPart -- modified 324 MibIndexPart -- modified 325 UniquePart -- new 326 DefValPart 328 VALUE NOTATION ::= 329 value(VALUE ObjectName) 331 Syntax ::= -- Must be one of the following: 332 -- a base type (or its refinement), 333 -- a textual convention (or its refinement), or 334 -- a BITS pseudo-type 335 type 336 | "BITS" "{" NamedBits "}" 338 NamedBits ::= NamedBit 339 | NamedBits "," NamedBit 341 NamedBit ::= identifier "(" number ")" -- number is nonnegative 343 UnitsPart ::= 344 "UNITS" Text 345 | empty 347 Access ::= -- modified 348 "install" 349 | "notify" 350 | "install-notify" 351 | "report-only" 353 Status ::= 354 "current" 355 | "deprecated" 356 | "obsolete" 358 ErrorsPart ::= -- new 359 "INSTALL-ERRORS" "{" Errors "}" 360 | empty 362 Errors ::= -- new 363 Error 364 | Errors "," Error 365 Error ::= -- new 366 identifier "(" number ")" -- number is positive 367 SPPI April 2001 369 ReferPart ::= 370 "REFERENCE" Text 371 | empty 373 IndexPart ::= 374 "PIB-INDEX" "{" Index "}" -- new 375 | "AUGMENTS" "{" Entry "}" 376 | "EXTENDS" "{" Entry "}" -- new 377 | empty 378 Index ::= 379 -- the correspondent OBJECT-TYPE invocation 380 value(ObjectName) 381 Entry ::= 382 -- use the INDEX value of the 383 -- correspondent OBJECT-TYPE invocation 384 value(ObjectName) 385 MibIndexPart ::= 386 "INDEX" "{" IndexTypePart "}" 387 | empty 388 IndexTypePart ::= 389 IndexTypes 390 | IndexTypes "," ImpliedIndex 391 | ImpliedIndex 392 IndexTypes ::= 393 Index 394 | IndexTypes "," Index 395 ImpliedIndex ::= 396 "IMPLIED" Index 398 PibReferencesPart ::= 399 -- for use with ReferenceId TC 400 "PIB-REFERENCES" "{" Entry "}" 401 | empty 403 PibTagPart ::= 404 -- for use with TagReferenceId TC 405 "PIB-TAG" "{" Attr "}" 406 | empty 408 Attr ::= -- specifies an attribute 409 value(ObjectName) 411 UniquePart ::= -- new 412 "UNIQUENESS" "{" UniqueTypes "}" 413 SPPI April 2001 415 | "UNIQUENESS" "{" "}" 416 | empty 417 UniqueTypes ::= 418 UniqueType 419 | UniqueTypes "," UniqueType 420 UniqueType ::= 421 -- the correspondent OBJECT-TYPE invocation 422 value(ObjectName) 424 DefValPart ::= "DEFVAL" "{" Defvalue "}" 425 | empty 427 Defvalue ::= -- must be valid for the type specified in 428 -- SYNTAX clause of same OBJECT-TYPE macro 429 value(ObjectSyntax) 430 | "{" BitsValue "}" 432 BitsValue ::= BitNames 433 | empty 435 BitNames ::= BitName 436 | BitNames "," BitName 438 BitName ::= identifier 440 -- a character string as defined in [SMI] 441 Text ::= value(IA5String) 442 END 444 -- definitions for conformance groups 446 OBJECT-GROUP MACRO ::= 447 BEGIN 448 TYPE NOTATION ::= 449 ObjectsPart 450 "STATUS" Status 451 "DESCRIPTION" Text 452 ReferPart 454 VALUE NOTATION ::= 455 value(VALUE OBJECT IDENTIFIER) 457 ObjectsPart ::= 458 "OBJECTS" "{" Objects "}" 459 SPPI April 2001 461 Objects ::= 462 Object 463 | Objects "," Object 464 Object ::= 465 value(ObjectName) 467 Status ::= 468 "current" 469 | "deprecated" 470 | "obsolete" 472 ReferPart ::= 473 "REFERENCE" Text 474 | empty 476 -- a character string as defined in [SMI] 477 Text ::= value(IA5String) 478 END 480 -- definitions for compliance statements 482 MODULE-COMPLIANCE MACRO ::= 483 BEGIN 484 TYPE NOTATION ::= 485 "STATUS" Status 486 "DESCRIPTION" Text 487 ReferPart 488 ModulePart 490 VALUE NOTATION ::= 491 value(VALUE OBJECT IDENTIFIER) 493 Status ::= 494 "current" 495 | "deprecated" 496 | "obsolete" 498 ReferPart ::= 499 "REFERENCE" Text 500 | empty 502 ModulePart ::= 503 Modules 504 Modules ::= 505 SPPI April 2001 507 Module 508 | Modules Module 509 Module ::= 510 -- name of module -- 511 "MODULE" ModuleName 512 MandatoryPart 513 CompliancePart 515 ModuleName ::= 516 -- identifier must start with uppercase letter 517 identifier ModuleIdentifier 518 -- must not be empty unless contained 519 -- in MIB Module 520 | empty 521 ModuleIdentifier ::= 522 value(OBJECT IDENTIFIER) 523 | empty 525 MandatoryPart ::= 526 "MANDATORY-GROUPS" "{" Groups "}" 527 | empty 529 Groups ::= 530 Group 531 | Groups "," Group 532 Group ::= 533 value(OBJECT IDENTIFIER) 535 CompliancePart ::= 536 Compliances 537 | empty 539 Compliances ::= 540 Compliance 541 | Compliances Compliance 542 Compliance ::= 543 ComplianceGroup 544 | Object 546 ComplianceGroup ::= 547 "GROUP" value(OBJECT IDENTIFIER) 548 "DESCRIPTION" Text 550 Object ::= 551 "OBJECT" value(ObjectName) 552 SPPI April 2001 554 InstallSyntaxPart -- modified 555 AccessPart 556 "DESCRIPTION" Text 558 -- must be a refinement for object's SYNTAX clause 559 InstallSyntaxPart ::= "SYNTAX" Syntax 560 | empty 562 Syntax ::= -- Must be one of the following: 563 -- a base type (or its refinement), 564 -- a textual convention (or its refinement), or 565 -- a BITS pseudo-type 566 type 567 | "BITS" "{" NamedBits "}" 569 NamedBits ::= NamedBit 570 | NamedBits "," NamedBit 572 NamedBit ::= identifier "(" number ")" -- number is nonnegative 574 AccessPart ::= 575 "PIB-MIN-ACCESS" Access -- modified 576 | empty 577 Access ::= -- modified 578 "not-accessible" 579 | "install" 580 | "notify" 581 | "install-notify" 583 -- a character string as defined in [SMI] 584 Text ::= value(IA5String) 585 END 587 -- definition of textual conventions 589 TEXTUAL-CONVENTION MACRO ::= 590 BEGIN 591 TYPE NOTATION ::= 592 DisplayPart 593 "STATUS" Status 594 "DESCRIPTION" Text 595 ReferPart 596 "SYNTAX" Syntax 598 VALUE NOTATION ::= 599 SPPI April 2001 601 value(VALUE Syntax) -- adapted ASN.1 603 DisplayPart ::= 604 "DISPLAY-HINT" Text 605 | empty 607 Status ::= 608 "current" 609 | "deprecated" 610 | "obsolete" 612 ReferPart ::= 613 "REFERENCE" Text 614 | empty 616 -- a character string as defined in [SMI] 617 Text ::= value(IA5String) 619 Syntax ::= -- Must be one of the following: 620 -- a base type (or its refinement), or 621 -- a BITS pseudo-type 622 type 623 | "BITS" "{" NamedBits "}" 625 NamedBits ::= NamedBit 626 | NamedBits "," NamedBit 628 NamedBit ::= identifier "(" number ")" -- number is nonnegative 630 END 632 END 633 SPPI April 2001 635 COPS-PR-SPPI-TC PIB-DEFINITIONS ::= BEGIN 637 IMPORTS Unsigned32, MODULE-IDENTITY, TEXTUAL-CONVENTION, pib 638 FROM COPS-PR-SPPI; 640 copsPrSppiTc MODULE-IDENTITY 641 SUBJECT-CATEGORIES { all } 642 LAST-UPDATED "200009201800Z" 643 ORGANIZATION "IETF RAP WG" 644 CONTACT-INFO "Keith McCloghrie 645 Cisco Systems, Inc. 646 170 West Tasman Drive, 647 San Jose, CA 95134-1706 USA 648 Phone: +1 408 526 5260 649 Email: kzm@cisco.com 651 Ravi Sahita 652 Intel 653 2111 NE 25th Avenue 654 Hillsboro, OR 97124 USA 655 Phone: +1 503 712 1554 656 Email: ravi.sahita@intel.com " 657 DESCRIPTION 658 "The PIB module containing a set of Textual Conventions 659 which have general applicability to all PIB modules." 660 REVISION "200009201800Z" 661 DESCRIPTION 662 "Initial version, published in RFC xxxx." 663 ::= { pib xxx } -- to be assigned by IANA 665 InstanceId ::= TEXTUAL-CONVENTION 666 STATUS current 667 DESCRIPTION 668 "The textual convention for use by an attribute which is used 669 as the instance-identifying index of a PRC, i.e., an attribute 670 named in a PIB-INDEX clause. The value of an attribute with this 671 syntax is always greater than zero. PRIs of the same PRC need 672 not have contiguous values for their instance-identifying 673 attribute." 674 SYNTAX Unsigned32 (1..4294967295) 676 ReferenceId ::= TEXTUAL-CONVENTION 677 STATUS current 678 DESCRIPTION 679 "A textual convention for use by an attribute which is used as 680 SPPI April 2001 682 a pointer in order to reference an instance of a particular 683 PRC. An attribute with this syntax must not be used in a 684 PIB-INDEX clause , and its description must specify the 685 particular PRC to which the referenced PRI will belong. 686 For an attribute of this type, the referenced PRI must exist. 687 Furthermore, it is an error to try to delete a PRI that is 688 referenced by another instance without first deleting/modifying 689 the referencing instance. The definition of an attribute with 690 this syntax can permit the attribute to have a value of zero to 691 indicate that it is not currently pointing to an PRI." 692 SYNTAX Unsigned32 694 Prid ::= TEXTUAL-CONVENTION 695 STATUS current 696 DESCRIPTION 697 "Represents a pointer to a PRI, i.e,. to an instance of a 698 PRC. The value is the OID name of the PRC's row definition, 699 appended with one sub-identifier containing the value of the 700 InstanceId value for the referenced instance. The definition 701 of an attribute with this syntax can permit the attribute to 702 have a value of 0.0 to indicate that it is not currently 703 pointing to a PRI." 704 SYNTAX OBJECT IDENTIFIER 706 TagId ::= TEXTUAL-CONVENTION 707 STATUS current 708 DESCRIPTION 709 "Represents a tag value, such that all instances of a 710 particular PRC having the same tag value form a tag list. 711 A tag list is identified by the tag value shared by all 712 instances in that tag list." 713 SYNTAX Unsigned32 (1..4294967295) 715 TagReferenceId ::= TEXTUAL-CONVENTION 716 STATUS current 717 DESCRIPTION 718 "Represents a reference to a tag list of instances of a 719 particular PRC. The particular PRC must have an attribute 720 with the syntax of TagId. The tag list consists of 721 all instances which have the same value of the TagId 722 attribute. Reference to the tag list is via the attribute 723 with the syntax of TagReferenceId containing the tag 724 value which identifies the tag list." 725 SYNTAX Unsigned32 726 END 727 SPPI April 2001 729 4. PIB Modules 731 The names of all standard PIB modules must be unique (but different 732 versions of the same module should have the same name). Developers of 733 enterprise PIB modules are encouraged to choose names for their modules 734 that will have a low probability of colliding with standard or other 735 enterprise modules. 737 The first line of a PIB module is: 739 PIB-MODULE-NAME PIB-DEFINITIONS ::= BEGIN 741 where PIB-MODULE-NAME is the module name. 743 Like the SMI, additional ASN.1 macros must not be defined in PIB 744 modules. 746 4.1. Importing Definitions 748 Like the SMI, a PIB module which needs to reference an external 749 definition, must use the IMPORTS statement to identify both the 750 descriptor and the module in which the descriptor is defined, where a 751 module is identified by its ASN.1 module name. 753 In particular, a PIB module imports each of the base data types that it 754 uses from COPS-PR-SPPI (defined in this document), and may import as 755 required from other PIB modules. A PIB module may import, from the SMI, 756 (subtree) OIDs for the purpose of defining new OIDs. A PIB module may 757 also import, from MIB modules, OID assignments as well as textual 758 convention definitions providing that their underlying syntax is 759 supported by the SPPI. However, the following must not be included in 760 an IMPORTS statement: 762 - named types defined by ASN.1 itself, specifically: INTEGER, OCTET 763 STRING, OBJECT IDENTIFIER, SEQUENCE, SEQUENCE OF type, 764 - the BITS construct. 766 For each ASN.1 macro that a PIB uses, it must import that macro's 767 definition from the COPS-PR-SPPI. 769 4.2. Reserved Keywords 771 In addition to the reserved keywords listed in the SMI, the following 772 must not be used as descriptors or module names: 774 SPPI April 2001 776 EXTENDS INSTALL-ERRORS Integer64 PIB-MIN-ACCESS PIB-ACCESS 777 PIB-INDEX PIB-REFERENCES PIB-TAG SUBJECT-CATEGORIES UNIQUENESS 778 Unsigned64 780 5. Naming Hierarchy 782 The SPPI uses the same OBJECT IDENTIFIER naming hierarchy as the SMI. 783 That is, OIDs are typically assigned to PIB modules from the subtree 784 administered by the Internet Assigned Numbers Authority (IANA). 785 However, like the SMI, the SPPI does not prohibit the definition of PRCs 786 in other portions of the OID tree. 788 6. Mapping of the MODULE-IDENTITY macro 790 6.1. Mapping of the SUBJECT-CATEGORIES clause 792 The SUBJECT-CATEGORIES clause, which must be present, identifies one or 793 more categories of provisioning data for which this PIB module defines 794 provisioning information. For use with the COPS-PR protocol, the 795 individual subject categories are mapped to COPS Client Types [COPS-PR]. 796 IANA Considerations for SPPI SUBJECT-CATEGORIES follow the same 797 requirements as specified in [COPS] IANA Considerations for COPS Client 798 Types. The subject categories are identified either: 800 - via the keyword "all", indicating the PIB module defines 801 provisioning information relevant for all subject categories (and 802 thus, all COPS Client Types), or 804 - a list of named-number enumerations, where each number which must 805 be greater than zero, identifies a subject category, and is mapped 806 to the Client Type which is identified by that same number in the 807 COPS protocol. The namespace for these named numbers is global and 808 therefore the labels should be assigned consistently across PIB 809 modules. At present time, no more than one named-number 810 enumeration should be specified. 812 Note that the list of categories specified in a PIB module's SUBJECT- 813 CATEGORIES clause is not exclusive. That is, some other specification 814 might (e.g., at a future date) specify additional COPS Client Types to 815 which the module is relevant. 817 When a PIB module applies to multiple subject categories, that PIB 818 module exists in multiple virtual information stores, one for each 819 SPPI April 2001 821 Client-Type. A PIB module with SUBJECT-CATEGORIES "all" uses the named- 822 number specified in the SUBJECT-CATEGORIES of the PIB it is associated 823 with, as the COPS Client-Type when it is sent over COPS. 825 7. Mapping of the OBJECT-TYPE macro 827 The SPPI requires that all attribute definitions be contained within a 828 PRC, i.e., within a table definition. 830 7.1. Mapping of the SYNTAX clause 832 The SYNTAX clause, which must be present within the definition of an 833 attribute, defines the abstract data structure of that attribute. The 834 data structure must be one of the following: a base type, the BITS 835 construct, or a textual convention. 837 The SYNTAX clause must also be present for the table and row definitions 838 of a PRC, and in this case must be a SEQUENCE OF or SEQUENCE (see 839 section 8.1.7 below). 841 The base types are an extended subset of the SMI's base types: 843 - built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER, 845 - application-defined types: Integer32, Unsigned32, TimeTicks, 846 Integer64 and Unsigned64. 848 A textual convention is a newly-defined type defined as a sub-type of a 849 base type [TC]. The value of an attribute whose syntax is defined using 850 a textual convention is encoded "on-the-wire" according to the textual 851 convention's underlying base type. 853 Note that the set of base types has been chosen so as to provide 854 sufficient variety of on-the-wire encodings for attribute values; base 855 types should contain a minimum of semantics. Semantics should, to the 856 extent possible, be incorporated into a data type through the use of a 857 textual convention. 859 The differences from the SMI in the semantics of ObjectSyntax are now 860 described. 862 7.1.1. Counter32 864 The Counter32 type is not supported by the SPPI. 866 SPPI April 2001 868 7.1.2. Gauge32 870 The Gauge32 type is not supported by the SPPI. 872 7.1.3. Opaque 874 The Opaque type is provided solely for backward-compatibility, and shall 875 not be used for newly-defined object types. The Opaque type supports the 876 capability to pass arbitrary ASN.1 syntax. A value is encoded using the 877 ASN.1 Basic Encoding Rules [ASN1] into a string of octets. This, in 878 turn, is encoded as an OCTET STRING, in effect "double-wrapping" the 879 original ASN.1 value. Note that a conforming implementation need only be 880 able to accept and recognize opaquely-encoded data. It need not be able 881 to unwrap the data and then interpret its contents. A requirement on 882 "standard" PIB modules is that no object may have a SYNTAX clause value 883 of Opaque. 885 7.1.4. IpAddress 887 The IpAddress type is provided solely for backward-compatibility, and 888 shall not be used for newly-defined object types. Instead, It is 889 recommended to use the InetAddressType/InetAddress pair TCs as defined 890 in RFC2851 [INETADDR]. 892 7.1.5. Counter64 894 The Counter64 type is not supported by the SPPI. 896 7.1.6. Integer64 898 The Integer64 type represents integer-valued information between -2^63 899 and 2^63-1 inclusive (-9223372036854775808 to 9223372036854775807 900 decimal). While Integer64 may be sub-typed to be more constrained, if 901 the constraint results in all possible values being contained in the 902 range (-2147483648..2147483647), then the Integer32 type must be used 903 instead of Integer64. 905 7.1.7. Unsigned64 907 The Unsigned64 type represents integer-valued information between 0 and 908 2^64-1 inclusive (0 to 18446744073709551615 decimal). While Unsigned64 909 may be sub-typed to be more constrained, if the constraint results in 910 all possible values being contained in the range (0..4294967295), then 911 the Unsigned32 type must be used instead of Unsigned64. 913 SPPI April 2001 915 7.1.8. Provisioning Classes 917 The operations (on PIBs) supported by the SPPI apply exclusively to 918 PRCs. Each PRC is modelled as a tabular structure, i.e., a table. Each 919 instance of a particular PRC has the same set of attributes. The set of 920 attributes which belong to every instance of a particular PRC is 921 modelled as a row in the table. Note that a PRC must have no more than 922 127 attributes. The usage of subids (for PRC attributes) beyond 127 923 (that is 128 and above) is reserved for Mapping PIBs to MIBs (see 924 Appendix A). PRCs that require more than 127 attributes must use the 925 AUGMENTS clause to augment the PRC containing the initial 127 attributes 926 to add additional attributes. Definition of Provisioning Classes is 927 formalized by using the OBJECT-TYPE macro to define both: 929 - the PRC as a whole, called the table definition, and 931 - the characteristics of every instance of a particular PRC, called 932 the row definition. 934 In the table definition, the SYNTAX clause has the form: 936 SEQUENCE OF 938 where refers to the SEQUENCE type of its attribute 939 definitions. In the row definition, the SYNTAX clause has the form: 941 943 where is a SEQUENCE type defined as follows: 945 ::= SEQUENCE { , ... , } 947 where there is one for each attribute, and each is of the 948 form: 950 952 where is the descriptor naming an attribute, and 953 has the value of that attribute's SYNTAX clause, except that both sub- 954 typing information and the named values for enumerated integers or the 955 named bits for the BITS construct, are omitted from . 957 SPPI April 2001 959 7.2. Mapping of the MAX-ACCESS clause 961 The MAX-ACCESS clause is not supported by the SPPI. 963 7.3. Mapping of the PIB-ACCESS clause 965 The PIB-ACCESS clause must be present for a PRC's table definition, and 966 must not be present for any other OBJECT-TYPE definition. The PIB- 967 ACCESS clause defines what kind of access is appropriate for the PRC. 969 - the value "install" is used to indicate a PRC which a PDP can 970 install in the PEP as provisioning information. 972 - the value "notify" is used to indicate a PRC for which the PEP must 973 notify the PDP of all its instances and attribute values of that 974 PRC. 976 - the value "install-notify" is used to indicate the uncommon type of 977 PRC which has both characteristics: "install" and "notify". 979 the value "report-only" is used to indicate a PRC which has neither the 980 "install" characteristic nor the "notify" characteristic. However, 981 instances of such a PRC may be included in synchronous/asynchronous 982 reports generated by the PEP. (Note: PRCs having the "install" and/or 983 "notify" characteristics may also be included in reports generated by 984 the PEP.) 986 7.4. Mapping of the INSTALL-ERRORS clause 988 The INSTALL-ERRORS clause, which may optionally be present for a PRC's 989 table definition, and must be absent otherwise, lists one or more 990 potential reasons for rejecting an install or a removal of an instance 991 of the PRC. Each reason consists of a named-number enumeration, where 992 the number represents a PRC-specific error-code to be used in a COPS 993 protocol message, as the Error Sub-code, with the Error-Code set to 994 priSpecificError (see [COPS-PR]). The semantics of each named-number 995 enumeration should be described in the PRC's DESCRIPTION clause. 997 The numbers listed in an INSTALL-ERRORS must be greater than zero and 998 less than 65536. If this clause is not present, an install/remove can 999 still fail, but no PRC-specific error is available to be reported. 1001 SPPI April 2001 1003 7.5. Mapping of the PIB-INDEX clause 1005 The PIB-INDEX clause, which must be present for a row definition (unless 1006 an AUGMENTS or an EXTENDS clause is present instead), and must be absent 1007 otherwise, defines identification information for instances of the PRC. 1009 The PIB-INDEX clause includes exactly one descriptor. This descriptor 1010 specifies an attribute (typically, but not necessarily of the same PRC) 1011 which is used to identify an instance of that PRC. The syntax of this 1012 attribute is REQUIRED to be InstanceId (a textual convention with an 1013 underlying syntax of Unsigned32), and it has no semantics other than its 1014 use in identifying the PRC instance. The OBJECT IDENTIFIER which 1015 identifies an instance of a PRC is formed by appending one sub- 1016 identifier to the OID which identifies that PRC's row definition. The 1017 value of the additional sub-identifier is that instance's value of the 1018 attribute specified in the INDEX clause. 1020 Note that SPPI does not permit use of the IMPLIED keyword in a PIB-INDEX 1021 clause. 1023 7.6. Mapping of the INDEX clause 1025 The INDEX clause is optionally present if a PIB-INDEX clause is present, 1026 and must be absent otherwise. If present, the INDEX clause can contain 1027 any number of attributes, and is used only by the algorithmic conversion 1028 of a PIB to a MIB (see Appendix A). 1030 An IMPLIED keyword can be present in an INDEX clause if so desired. 1032 7.7. Mapping of the AUGMENTS clause 1034 The AUGMENTS clause, which must not be present except in row 1035 definitions, is an alternative to the PIB-INDEX clause and the EXTENDS 1036 clause. Every row definition has exactly one of: a PIB-INDEX clause, an 1037 AUGMENTS clause, or an EXTENDS clause. 1039 A row definition which has a PIB-INDEX clause is called a base row 1040 definition. A row definition which has an AUGMENTS clause is called a 1041 row augmentation, where the AUGMENTS clause names the base row 1042 definition which is augmented by this row augmentation. (Thus, a row 1043 augmentation cannot itself be augmented.) 1045 A PRC whose row definition is a row augmentation is called an augmenting 1046 PRC. Instances of an augmenting PRC are identified according to the 1047 PIB-INDEX clause of the base row definition named in the AUGMENTS 1048 SPPI April 2001 1050 clause. Further, instances of an augmenting PRC exist according to the 1051 same semantics as instances of the PRC which it augments. As such, when 1052 an instance of a PRC is installed or removed, an instance of every PRC 1053 which augments it is also installed or removed. (for more details, see 1054 [COPS-PR]). 1056 7.8. Mapping of the EXTENDS clause 1058 The EXTENDS clause, which must not be present except in row definitions, 1059 is an alternative to the PIB-INDEX clause and the AUGMENTS clause. 1060 Every row definition has exactly one of: a PIB-INDEX clause, an AUGMENTS 1061 clause, or an EXTENDS clause. 1063 A row definition which has an EXTENDS clause is called a sparse row 1064 augmentation, where the EXTENDS clause names the row definition which is 1065 sparsely-augmented by this sparse row augmentation. The sparsely- 1066 augmented row can be a base row definition, or another sparse row 1067 augmentation. 1069 A PRC whose row definition is a sparse row augmentation is called a 1070 sparsely augmenting PRC. Instances of a sparsely augmenting PRC are 1071 identified according to the PIB-INDEX clause of the row definition named 1072 in the sparsely augmenting PRC's EXTENDS clause. 1074 An instance of a sparsely augmenting PRC can not exist unless a 1075 corresponding instance of the PRC which it sparsely augments exists. As 1076 such, when an instance of a PRC is removed, an instance of any PRC which 1077 sparsely augments it is also removed. However, an instance of a 1078 sparsely augmenting PRC need not exist when the corresponding instance 1079 of the PRC that it sparsely augments exists. Thus, an instance of a 1080 sparsely augmenting PRC can be installed at the same time as or 1081 subsequent to the installation of, and can be removed prior to the 1082 removal of, the corresponding instance of the PRC that it sparsely 1083 augments. So, instances of a sparsely augmenting PRC must be installed 1084 explicitly, but are removed either implicitly (via removal of the 1085 augmented PRI) or explicitly. When a sparsely augmented PRC is 1086 installed, both instances, the instance of the sparsely augmented PRC 1087 and the instance of the sparsely augmenting PRC must be sent in one COPS 1088 message.x 1090 7.8.1. Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1092 When defining instance identification information for a PRC: 1094 SPPI April 2001 1096 - If there is a one-to-one correspondence between instances of this 1097 PRC and instances of an existing PRC, then the AUGMENTS clause 1098 should be used. 1100 - Otherwise, if there is a sparse relationship between instances of 1101 this PRC and instances of an existing PRC (that is, there is a one 1102 to zero or one correspondence between instances of a sparsely 1103 augmented PRC and the instances of the PRC that sparsely augments 1104 it.), then an EXTENDS clause should be used. 1106 - Otherwise, a PIB-INDEX clause should be used which names its own 1107 InstanceId attribute. 1109 7.9. Mapping of the UNIQUENESS clause 1111 The UNIQUENESS clause, which is optionally present for any row 1112 definition, lists a set of zero or more of the PRC's attributes, for 1113 which no two instances of the PRC can have the same set of values. The 1114 specified set of attributes provide a necessary and sufficient set of 1115 values by which to identify an instance of this PRC. The attribute 1116 contained in the PIB-INDEX clause may not be present in the UNIQUENESS 1117 clause. By definition, an attribute may not appear more than once in a 1118 UNIQUENESS clause. A UNIQUENESS clause containing zero attributes 1119 indicates that it's possible for two instances of the PRC to have 1120 identical values for all attributes except, of course, for the one named 1121 in the PIB-INDEX clause. 1123 If a PRC and its sparsely augmenting PRC both have UNIQUENESS clauses, 1124 then the UNIQUENESS constraint for instances of each PRC MUST be applied 1125 according to the UNIQUENESS clause in the corresponding PRC definition. 1126 Note that a sparsely augmenting PRC thus can override the UNIQUENESS 1127 clause of the PRC it sparsely augments. 1129 Even though the UNIQUENESS clause is optional, its inclusion is 1130 recommended wherever it provides useful information. 1132 7.10. Mapping of the PIB-REFERENCES clause 1134 The PIB-REFERENCES clause, which must be present for any attribute which 1135 has the SYNTAX of ReferenceId, and must be absent otherwise, names the 1136 PRC, an instance of which is referenced by the ReferenceId attribute. 1137 For example usages of the PIB-REFERENCES clause, see Appendix B. 1139 SPPI April 2001 1141 7.11. Mapping of the PIB-TAG clause 1143 The PIB-TAG clause, which must be present for an attribute which has the 1144 SYNTAX TagReferenceId, and must be absent otherwise, is used to indicate 1145 that this attribute references a "tag list" of instances of another PRC. 1146 Such a tag list (similar in concept to the usage of the same term in 1147 [APPL]) is formed by all instances of the other PRC which have the same 1148 (tag) value of a particular attribute of that other PRC. The particular 1149 attribute of the other PRC, which must have the SYNTAX TagId, is named 1150 in the PIB-TAG clause. For an example usage of the PIB-TAG clause, see 1151 Appendix B. 1153 8. Mapping of the OBJECT-IDENTITY macro 1155 The OBJECT-IDENTITY macro is used in PIB modules to define information 1156 about an OBJECT IDENTIFIER assignment. 1158 9. Mapping of the OBJECT-GROUP macro 1160 For conformance purposes, it is useful to define a conformance group as 1161 a collection of related PRCs and their attributes. The OBJECT-GROUP 1162 macro (directly) defines the collection of attributes which belong to a 1163 conformance group. Since each attribute included in the collection 1164 belongs to a PRC, the collection of related PRCs which belong to a 1165 conformance group is also specified (indirectly) as the set of PRCs to 1166 which the included attributes belong. 1168 9.1. Mapping of the OBJECTS clause 1170 The OBJECTS clause, which must be present, is used to specify each 1171 attribute contained in the conformance group. Each of the specified 1172 attributes must be defined in the same PIB module as the OBJECT-GROUP 1173 macro appears. 1175 It is required that every attribute defined in a PIB module be contained 1176 in at least one conformance group. This avoids the common error of 1177 adding a new attribute to a module and forgetting to add the new 1178 attribute to a group. 1180 SPPI April 2001 1182 10. Mapping of the MODULE-COMPLIANCE macro 1184 The MODULE-COMPLIANCE macro is used to convey a minimum set of 1185 requirements with respect to implementation of one or more PIB modules. 1187 A requirement on all "standard" PIB modules is that a corresponding 1188 MODULE-COMPLIANCE specification is also defined, either in the same 1189 module or in a companion module. 1191 10.1. Mapping of the MODULE clause 1193 The MODULE clause, which must be present, is repeatedly used to name 1194 each PIB module for which compliance requirements are being specified. 1195 Each PIB module is named by its module name, and optionally, by its 1196 associated OBJECT IDENTIFIER as well. The module name can be omitted 1197 when the MODULE-COMPLIANCE invocation occurs inside a PIB module, to 1198 refer to the encompassing PIB module. 1200 10.1.1. Mapping of the MANDATORY-GROUPS clause 1202 The MANDATORY-GROUPS clause, which need not be present, names the one or 1203 more conformance groups within the correspondent PIB module which are 1204 unconditionally mandatory for implementation. If an agent claims 1205 compliance to the PIB module, then it must implement each and every 1206 attribute (and therefore the PRCs to which they belong) within each 1207 conformance group listed. 1209 10.1.2. Mapping of the GROUP clause 1211 The GROUP clause, which need not be present, is repeatedly used to name 1212 each conformance group which is conditionally mandatory for compliance 1213 to the PIB module. The GROUP clause can also be used to name 1214 unconditionally optional groups. A group named in a GROUP clause must 1215 be absent from the correspondent MANDATORY-GROUPS clause. 1217 Conditionally mandatory groups include those which are mandatory only if 1218 a particular protocol is implemented, or only if another group is 1219 implemented. A GROUP clause's DESCRIPTION specifies the conditions 1220 under which the group is conditionally mandatory. 1222 A group which is named in neither a MANDATORY-GROUPS clause nor a GROUP 1223 clause, is unconditionally optional for compliance to the PIB module. 1225 SPPI April 2001 1227 10.1.3. Mapping of the OBJECT clause 1229 The OBJECT clause, which need not be present, is repeatedly used to 1230 specify each attribute for which compliance has a refined requirement 1231 with respect to the PIB module definition. The attribute must be 1232 present in one of the conformance groups named in the correspondent 1233 MANDATORY-GROUPS clause or GROUP clauses. 1235 By definition, each attribute specified in an OBJECT clause follows a 1236 MODULE clause which names the PIB module in which that attribute is 1237 defined. Therefore, the use of an IMPORTS statement, to specify from 1238 where such attributes are imported, is redundant and is not required in 1239 a PIB module. 1241 10.1.3.1. Mapping of the SYNTAX clause 1243 The SYNTAX clause, which need not be present, is used to provide a 1244 refined SYNTAX for the attribute named in the correspondent OBJECT 1245 clause. The refined syntax is the minimum level of support needed for 1246 this attribute in order to be compliant. 1248 10.1.3.2. Mapping of the WRITE-SYNTAX clause 1250 The WRITE-SYNTAX clause is not supported by the SPPI. 1252 10.1.3.3. Mapping of the PIB-MIN-ACCESS clause 1254 The PIB-MIN-ACCESS clause, which need not be present, is used to define 1255 the minimal level of access for the attribute named in the correspondent 1256 OBJECT clause. If this clause is absent, the minimal level of access is 1257 the same as the maximal level specified in the PIB-ACCESS clause of the 1258 correspondent invocation of the OBJECT-TYPE macro. If present, this 1259 clause must specify a subset of the access specified in the 1260 correspondent PIB-ACCESS clause, where: "install" is a subset of 1261 "install-notify", "notify" is a subset of "install-notify", and "not- 1262 accessible" is a subset of all other values. 1264 An implementation is compliant if the level of access it provides is the 1265 same or a superset of the minimal level in the MODULE-COMPLIANCE macro 1266 and the same or a subset of the maximal level in the PIB-ACCESS clause. 1268 SPPI April 2001 1270 11. Textual Conventions 1272 When designing a PIB module, it is often useful to define new data types 1273 similar to those defined in the SPPI. In comparison to a type defined 1274 in the SPPI, each of these new types has a different name, a similar 1275 syntax, and specific semantics. These newly defined types are termed 1276 textual conventions, and are used for the convenience of humans reading 1277 the PIB module. 1279 Attributes defined using a textual convention are always encoded by 1280 means of the rules that define their underlying type. 1282 11.1. Mapping of the TEXTUAL-CONVENTION macro 1284 The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics 1285 associated with a textual convention. It should be noted that the 1286 expansion of the TEXTUAL-CONVENTION macro is something which 1287 conceptually happens during implementation and not during run-time. 1289 The name of a textual convention must consist of one or more letters or 1290 digits, with the initial character being an upper case letter. The name 1291 must not conflict with any of the reserved words listed in section 5.2, 1292 should not consist of all upper case letters, and shall not exceed 64 1293 characters in length. (However, names longer than 32 characters are not 1294 recommended.) The hyphen is not allowed in the name of a textual 1295 convention (except for use in information modules converted from SMIv1 1296 which allowed hyphens in ASN.1 type assignments). Further, all names 1297 used for the textual conventions defined in all "standard" PIB modules 1298 shall be unique. 1300 11.1.1. Mapping of the SYNTAX clause 1302 The SYNTAX clause, which must be present, defines abstract data 1303 structure corresponding to the textual convention. The data structure 1304 must be one of the following: a base type (see the SYNTAX clause of an 1305 OBJECT-TYPE macro), or the BITS construct. Note that this means that 1306 the SYNTAX clause of a Textual Convention can not refer to a previously 1307 defined Textual Convention. 1309 11.1.1.1. Sub-typing of Textual Conventions 1311 The SYNTAX clause of a TEXTUAL CONVENTION macro may be sub-typed in the 1312 same way as the SYNTAX clause of an OBJECT-TYPE macro. 1314 SPPI April 2001 1316 12. Extending a PIB Module 1318 PIBs may be revised as implementation experience is gained. However, 1319 changes with potential to cause disruption to interoperability between 1320 the previous PIB and the revised PIB are not allowed. 1322 12.1. PIB Modules 1324 For any change, the invocation of the MODULE-IDENTITY macro must be 1325 updated to include information about the revision: specifically, 1326 updating the LAST-UPDATED clause, adding a pair of REVISION and 1327 DESCRIPTION clauses, and making any necessary changes to existing 1328 clauses, including the ORGANIZATION and CONTACT-INFO clauses. 1330 Note that any definition contained in an existing PIB is available to be 1331 IMPORT-ed by any other PIB, and is referenced in an IMPORTS clause via 1332 the PIB module name. Thus, a PIB module name should not be changed. 1333 Definitions should not be moved from one PIB to another. 1335 Also note that obsolete definitions must not be removed from PIB modules 1336 since their descriptors may still be referenced by other PIB modules, 1337 and the OBJECT IDENTIFIERs used to name them must never be re-assigned. 1338 The EXTENDS/AUGMENTS clause should be used to extend previous 1339 definitions depending on the information to be represented. 1341 Changes to an existing PIB can be made in several ways: 1343 - Additional PRCs can be added to a PIB or an existing one 1344 deprecated. 1346 - Attributes can be added to, or deprecated from, an existing PRC. 1347 Note that an ASN.1 value of the correct type or an ASN.1 NULL value 1348 must be sent even for deprecated attributes to mantain 1349 interoperability. New attributes must be added in sequence after 1350 the existing ones. 1352 - An existing PRC can be extended or augmented with a new PRC defined 1353 in another (perhaps enterprise specific) PIB. 1355 Additional named-number enumerations may be added to a SUBJECT- 1356 CATEGORIES clause. 1358 SPPI April 2001 1360 12.2. Object Assignments 1362 If any non-editorial change is made to any clause of a object 1363 assignment, then the OBJECT IDENTIFIER value associated with that object 1364 assignment must also be changed, along with its associated descriptor. 1365 Note that the max subid for PRC attributes is 127 (See Section 7.1.8) 1367 12.3. Object Definitions 1369 An object definition may be revised in any of the following ways: 1371 - A SYNTAX clause containing an enumerated INTEGER may have new 1372 enumerations added or existing labels changed. Similarly, named 1373 bits may be added or existing labels changed for the BITS 1374 construct. 1376 - The value of a SYNTAX clause may be replaced by a textual 1377 convention, providing the textual convention is defined to use the 1378 same primitive ASN.1 type, has the same set of values, and has 1379 identical semantics. 1381 - A UNITS clause may be added. 1383 - A STATUS clause value of "current" may be revised as "deprecated" 1384 or "obsolete". Similarly, a STATUS clause value of "deprecated" 1385 may be revised as "obsolete". When making such a change, the 1386 DESCRIPTION clause should be updated to explain the rationale. 1388 - Clarifications and additional information may be included in the 1389 DESCRIPTION clause. 1391 - An INSTALL-ERRORS clause may be added or an existing INSTALL-ERRORS 1392 clause have additional errors defined. 1394 - A REFERENCE clause may be added or updated. 1396 - A DEFVAL clause may be added or updated. 1398 - A PRC may be augmented by adding new objects at the end of the row, 1399 and making the corresponding update to the SEQUENCE definition. 1401 - Entirely new objects may be defined, named with previously 1402 unassigned OBJECT IDENTIFIER values. 1404 SPPI April 2001 1406 Otherwise, if the semantics of any previously defined object are changed 1407 (i.e., if a non-editorial change is made to any clause other than those 1408 specifically allowed above), then the OBJECT IDENTIFIER value associated 1409 with that object must also be changed. 1411 Note that changing the descriptor associated with an existing object is 1412 considered a semantic change, as these strings may be used in an IMPORTS 1413 statement. 1415 SPPI April 2001 1417 13. Appendix A: Mapping a PIB to a MIB 1419 Since the SPPI is modelled on the SMI, a PIB can be potentially 1420 algorithmically mapped into a MIB. This mapping is achieved by means of 1421 the following rules: 1423 - Modify the module's module name by appending "-MIB" to the name. 1425 - Change the OID assigned to the MODULE-IDENTITY to be different 1426 value. 1428 - Replace the keyword PIB-DEFINITIONS with the keyword DEFINITIONS. 1430 - Modify the module names of all external references to PIB modules 1431 by appending "-MIB" to each such module name. 1433 - For each PRC definition, if an INDEX clause is absent, change the 1434 "PIB-INDEX" keyword to "INDEX"; otherwise, delete the PIB-INDEX 1435 clause. 1437 - Delete all of the following clauses: PIB-ACCESS, PIB-REFERENCES, 1438 PIB-TAG, UNIQUENESS, INSTALL-ERRORS, and SUBJECT-CATEGORIES. 1440 - Change all PIB-MIN-ACCESS clauses to MIN-ACCESS clauses, modifying 1441 "install" and "install-notify" to "read-create", and "notify" to 1442 "read-only". 1444 - Add a MAX-ACCESS clause for each OBJECT-TYPE. For each table 1445 definition and row definition, the MAX-ACCESS is "not-accessible". 1446 For each attribute that is in the INDEX clause, the MAX-ACCESS is 1447 "not-accessible". For the remaining attributes, the MAX-ACCESS is 1448 "read-create". 1450 - Add a columnar attribute of type RowStatus with a descriptor and 1451 appropriate DESCRIPTION. The descriptor can be formed by appending 1452 the nine characters "RowStatus" to the end of the PRC's descriptor 1453 (truncated if necessary to avoid the resulting descriptor being too 1454 long). A Subid beyond 127 (i.e., 128 and above) can be used as the 1455 OID for this columnar attribute. 1457 - Modify any SYNTAX clause which has a base data type which is not 1458 allowed in the SMI, either to be a valid SMI data type or to omit 1459 the OBJECT-TYPE or TEXTUAL-CONVENTION definition and all references 1460 to it. Since it is not clear (at this time) which is the best SMI 1461 data type to use, the conversion SHOULD provide a configurable 1462 SPPI April 2001 1464 option allowing a choice from at least the following: 1466 - convert to an OCTET STRING of the relevant size. 1467 Specifically, this option would map both Integer64 and 1468 Unsigned64 to OCTET STRING (SIZE(8)), or 1470 - omit them from the conversion, or 1472 - map Integer64 and Unsigned64 to Counter64 (even though this 1473 has problems representing negative numbers, and unwanted 1474 counter semantics.) 1475 SPPI April 2001 1477 14. Appendix B: Example usage of PIB-REFERENCES and PIB-TAG clauses 1479 The following example demonstrates the use of the PIB-REFERENCES and 1480 PIB-TAG clauses. 1482 In this example, the PIB-REFERENCES clause is used by the 1483 qosIfDscpMapQueue attribute to indicate the PRC of which it references 1484 an instance, and similarly, by the qosIfDscpMapThresh attribute. 1486 The qosIfDscpMapTable PRC has an instance for each DSCP of a particular 1487 "map", but there is no PRC defined for a map itself; rather, a map 1488 consists of all instances of qosIfDscpMapTable which have the same value 1489 of qosIfDscpMapMapId. That is, a tag list is formed by all instances of 1490 qosIfDscpMapTable which have the same value of qosIfDscpMapMapId. This 1491 tag list is referenced by the attribute qosIfDscpAssignDscpMap, and its 1492 use of the PIB-TAG clause indicates this. 1494 qosIfDscpAssignTable OBJECT-TYPE 1495 SYNTAX SEQUENCE OF QosIfDscpAssignEntry 1496 PIB-ACCESS install 1497 STATUS current 1498 DESCRIPTION " " 1499 ::= { qosIfParameters 9 } 1501 qosIfDscpAssignEntry OBJECT-TYPE 1502 SYNTAX QosIfDscpAssignEntry 1503 STATUS current 1504 DESCRIPTION 1505 "An instance of the qosIfDscpAssign class." 1506 PIB-INDEX { qosIfDscpAssignPrid } 1507 UNIQUENESS { qosIfDscpAssignName, qosIfDscpAssignRoles } 1508 ::= { qosIfDscpAssignTable 1 } 1510 QosIfDscpAssignEntry ::= SEQUENCE { 1511 qosIfDscpAssignPrid InstanceId, 1512 qosIfDscpAssignName SnmpAdminString, 1513 qosIfDscpAssignRoles RoleCombination, 1514 qosIfDscpAssignDscpMap TagReferenceId 1515 } 1517 qosIfDscpAssignDscpMap OBJECT-TYPE 1518 SYNTAX TagReferenceId 1519 PIB-TAG { qosIfDscpMapMapId } -- attribute defined below 1520 STATUS current 1521 DESCRIPTION 1522 SPPI April 2001 1524 "The DSCP map which is applied to interfaces of type 1525 qosIfDscpAssignName which have a role combination of 1526 qosIfDscpAssignRoles." 1527 ::= { qosIfDscpAssignEntry 3 } 1529 -- 1530 -- DSCP to Queue and Threshold Mapping Table 1531 -- 1533 qosIfDscpMapTable OBJECT-TYPE 1534 SYNTAX SEQUENCE OF QosIfDscpMapEntry 1535 PIB-ACCESS install 1536 STATUS current 1537 DESCRIPTION 1538 "Assigns DSCP values to queues and thresholds for an arbitrary 1539 DSCP map. This map can then be assigned to various interface 1540 and role combination pairs." 1541 ::= { qosIfParameters 10 } 1543 qosIfDscpMapEntry OBJECT-TYPE 1544 SYNTAX QosIfDscpMapEntry 1545 STATUS current 1546 DESCRIPTION 1547 "An instance of the qosIfDscpMap class." 1548 PIB-INDEX { qosIfDscpMapPrid } 1549 UNIQUENESS { qosIfDscpMapMapId, qosIfDscpMapDscp } 1550 ::= { qosIfDscpMapTable 1 } 1552 QosIfDscpMapEntry ::= SEQUENCE { 1553 qosIfDscpMapPrid InstanceId, 1554 qosIfDscpMapMapId TagId, 1555 qosIfDscpMapDscp Dscp, 1556 qosIfDscpMapQueue ReferenceId, 1557 qosIfDscpMapThresh ReferenceId 1558 } 1560 qosIfDscpMapMapId OBJECT-TYPE 1561 SYNTAX TagId 1562 STATUS current 1563 DESCRIPTION 1564 "An integer that identifies the DSCP map to which this PRI 1565 belongs." 1566 ::= { qosIfDscpMapEntry 2 } 1568 qosIfDscpMapQueue OBJECT-TYPE 1569 SPPI April 2001 1571 SYNTAX ReferenceId 1572 PIB-REFERENCES { qosIfQueueEntry } 1573 STATUS current 1574 DESCRIPTION 1575 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1576 the queue identified by qosIfQueuePrid in qosIfQueueTable. 1577 For a given DSCP map, all the queues must belong to a single 1578 queue set." 1579 ::= { qosIfDscpMapEntry 4 } 1581 qosIfDscpMapThresh OBJECT-TYPE 1582 SYNTAX ReferenceId 1583 PIB-REFERENCES { qosIfThresholdEntry } 1584 STATUS current 1585 DESCRIPTION 1586 "This attribute maps the DSCP specified by qosIfDscpMapDscp to 1587 the threshold identified by qosIfThresholdId in 1588 qosIfThresholdTable. The threshold set to which this 1589 threshold belongs must be assigned to the queue specified by 1590 qosIfDscpMapQueue." 1591 ::= { qosIfDscpMapEntry 5 } 1592 SPPI April 2001 1594 15. Security Considerations 1596 This document defines a language with which to define provisioning 1597 information. The language itself has no security impact on the 1598 Internet. 1600 16. IANA Considerations 1602 The root of the subtree administered by the Internet Assigned Numbers 1603 Authority (IANA) for the Internet is: 1605 internet OBJECT IDENTIFIER ::= { iso 3 6 1 } 1607 That is, the Internet subtree of OBJECT IDENTIFIERs starts with the 1608 prefix: 1610 1.3.6.1. 1612 Several branches underneath this subtree are used for network 1613 management: 1615 mgmt OBJECT IDENTIFIER ::= { internet 2 } 1616 experimental OBJECT IDENTIFIER ::= { internet 3 } 1617 private OBJECT IDENTIFIER ::= { internet 4 } 1618 enterprises OBJECT IDENTIFIER ::= { private 1 } 1620 The mgmt(2) subtree is used to identify "standard" objects. 1622 This document defines 1624 pib OBJECT IDENTIFIER ::= { mgmt 2 } 1626 as the root for PIBs defined to be carried over [COPS-PR]. This Object 1627 Identifier is a high level assignment that needs to be registered with 1628 [IANA]. Root Object Identifiers for future "standards track" PIBs will 1629 also need to be registered and MUST use Object Identifiers below this 1630 oid. A standards track PIB can only be assigned an OID by IANA if the 1631 PIB is approved by the IESG as a "standards track" document. 1632 Experimental and enterprise PIBs MUST be defined under the 1633 "experimental" and "enterprises" Object Identifiers respectively. 1635 The PIB module "copsPrSppiTc" is defined in this document as a standard 1636 module and hence, needs a subid assignment under the "pib" oid from 1637 IANA. 1639 SPPI April 2001 1641 SPPI SUBJECT-CATEGORIES are mapped to COPS Client Types. IANA 1642 Considerations for SUBJECT-CATEGORIES follow the same requirements as 1643 specified in [COPS] IANA Considerations for COPS Client Types. Thus, a 1644 new PIB can define a new COPS Client Type in the "standards", 1645 "experimental" or "enterprise" space, and when approved that would mean 1646 that a new COPS Client Type gets assigned. IANA must update the registry 1647 for COPS CLient Types (where applicable as described in [COPS] IANA 1648 Considerations) as a result. 1650 17. Authors' Addresses 1652 Keith McCloghrie 1653 Cisco Systems, Inc. 1654 170 West Tasman Drive 1655 San Jose, CA 95134-1706 USA 1656 Phone: +1 408 526 5260 1657 Email: kzm@cisco.com 1659 Michael Fine 1660 Cisco Systems, Inc. 1661 170 West Tasman Drive 1662 San Jose, CA 95134-1706 USA 1663 Phone: +1 408 527 8218 1664 Email: mfine@cisco.com 1666 John Seligson 1667 Nortel Networks, Inc. 1668 4401 Great America Parkway 1669 Santa Clara, CA 95054 USA 1670 Phone: +1 408 495 2992 1671 Email: jseligso@nortelnetworks.com 1673 Kwok Ho Chan 1674 Nortel Networks, Inc. 1675 600 Technology Park Drive 1676 Billerica, MA 01821 USA 1677 Phone: +1 978 288 8175 1678 Email: khchan@nortelnetworks.com 1680 Scott Hahn 1681 Intel 1682 2111 NE 25th Avenue 1683 Hillsboro, OR 97124 USA 1684 Phone: +1 503 264 8231 1685 Email: scott.hahn@intel.com 1686 SPPI April 2001 1688 Ravi Sahita 1689 Intel 1690 2111 NE 25th Avenue 1691 Hillsboro, OR 97124 USA 1692 Phone: +1 503 712 1554 1693 Email: ravi.sahita@intel.com 1695 Andrew Smith 1696 Allegro Networks 1697 6399 San Ignacio Ave. 1698 San Jose 1699 CA 95119 1700 FAX: 415 345 1827 1701 Email: andrew@allegronetworks.com 1703 Francis Reichmeyer 1704 PFN Inc. 1705 University Park at MIT 1706 26 Landsdowne Street 1707 Cambridge, MA 02139 1708 Phone: +1 617 494 9980 1709 Email: franr@pfn.com 1711 18. References 1713 [COPS] 1714 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1715 Sastry, "The COPS (Common Open Policy Service) Protocol" RFC 2748, 1716 January 2000. 1718 [COPS-RSVP] 1719 Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R., and A. 1720 Sastry, " COPS usage for RSVP", RFC 2749, January 2000. 1722 [COPS-PR] 1723 Reichmeyer, F., Herzog, S., Chan, K., Durham, D., Yavatkar, R. 1724 Gai, S., McCloghrie, K. and A. Smith, "COPS Usage for Policy 1725 Provisioning" RFC 3084, March 2001. 1727 [SMI] 1728 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1729 and S. Waldbusser. "Structure of Management Information Version 2 1730 (SMIv2)", RFC 2578, STD 58, April 1999. 1732 SPPI April 2001 1734 [TC] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1735 and S. Waldbusser. "Textual Conventions for SMIv2", RFC 2579, STD 1736 58, April 1999. 1738 [CONF] 1739 McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., 1740 and S. Waldbusser. "Conformance Statements for SMIv2", RFC 2580, 1741 STD 58, April 1999. 1743 [APPL] 1744 Levi, D., Meyer, P., and B. Stewart, "SNMP Applications", RFC 2573, 1745 April 1999. 1747 [ASN1] 1748 Information processing systems -- Open Systems Interconnection -- 1749 Specification of Abstract Syntax Notation One (ASN.1), 1750 International Organization for Standardization. International 1751 Standard 8824, December 1987. 1753 [INETADDR] 1754 M. Daniele, B. Haberman, S. Routhier and J. Schoenwaelder "Textual 1755 Conventions for Internet Network Addresses", RFC 2851, June 2000. 1757 [IANA] 1758 http://www.isi.edu/in-notes/iana/assignments/smi-numbers 1760 [IANA-CONSIDERATIONS] 1761 Alvestrand, H. and T. Narten, "Guidelines for Writing an IANA 1762 Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. 1764 [RFC-2119] 1765 Bradner, S., "Key words for use in RFCs to Indicate Requirement 1766 Levels", BCP 14, RFC 2119, March 1997 1767 SPPI April 2001 1769 19. Full Copyright Statement 1771 Copyright (C) The Internet Society (2000). All Rights Reserved. 1773 This document and translations of it may be copied and furnished to 1774 others, and derivative works that comment on or otherwise explain it or 1775 assist in its implementation may be prepared, copied, published and 1776 distributed, in whole or in part, without restriction of any kind, 1777 provided that the above copyright notice and this paragraph are included 1778 on all such copies and derivative works. However, this document itself 1779 may not be modified in any way, such as by removing the copyright notice 1780 or references to the Internet Society or other Internet organizations, 1781 except as needed for the purpose of developing Internet standards in 1782 which case the procedures for copyrights defined in the Internet 1783 Standards process must be followed, or as required to translate it into 1784 languages other than English. 1786 The limited permissions granted above are perpetual and will not be 1787 revoked by the Internet Society or its successors or assigns. 1789 This document and the information contained herein is provided on an "AS 1790 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 1791 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 1792 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 1793 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 1794 FITNESS FOR A PARTICULAR PURPOSE." 1795 SPPI April 2001 1797 Table of Contents 1799 1 Use of the SMI .................................................. 2 1800 1.1 Terminology Translation ....................................... 2 1801 1.2 Overview ...................................................... 3 1802 2 Structure of this Specification ................................. 3 1803 3 Definitions ..................................................... 4 1804 4 PIB Modules ..................................................... 17 1805 4.1 Importing Definitions ......................................... 17 1806 4.2 Reserved Keywords ............................................. 17 1807 5 Naming Hierarchy ................................................ 18 1808 6 Mapping of the MODULE-IDENTITY macro ............................ 18 1809 6.1 Mapping of the SUBJECT-CATEGORIES clause ...................... 18 1810 7 Mapping of the OBJECT-TYPE macro ................................ 19 1811 7.1 Mapping of the SYNTAX clause .................................. 19 1812 7.1.1 Counter32 ................................................... 19 1813 7.1.2 Gauge32 ..................................................... 20 1814 7.1.3 Opaque ...................................................... 20 1815 7.1.4 IpAddress ................................................... 20 1816 7.1.5 Counter64 ................................................... 20 1817 7.1.6 Integer64 ................................................... 20 1818 7.1.7 Unsigned64 .................................................. 20 1819 7.1.8 Provisioning Classes ........................................ 21 1820 7.2 Mapping of the MAX-ACCESS clause .............................. 22 1821 7.3 Mapping of the PIB-ACCESS clause .............................. 22 1822 7.4 Mapping of the INSTALL-ERRORS clause .......................... 22 1823 7.5 Mapping of the PIB-INDEX clause ............................... 23 1824 7.6 Mapping of the INDEX clause ................................... 23 1825 7.7 Mapping of the AUGMENTS clause ................................ 23 1826 7.8 Mapping of the EXTENDS clause ................................. 24 1827 7.8.1 Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 1828 .............................................................. 24 1829 7.9 Mapping of the UNIQUENESS clause .............................. 25 1830 7.10 Mapping of the PIB-REFERENCES clause ......................... 25 1831 7.11 Mapping of the PIB-TAG clause ................................ 26 1832 8 Mapping of the OBJECT-IDENTITY macro ............................ 26 1833 9 Mapping of the OBJECT-GROUP macro ............................... 26 1834 9.1 Mapping of the OBJECTS clause ................................. 26 1835 10 Mapping of the MODULE-COMPLIANCE macro ......................... 27 1836 10.1 Mapping of the MODULE clause ................................. 27 1837 10.1.1 Mapping of the MANDATORY-GROUPS clause ..................... 27 1838 10.1.2 Mapping of the GROUP clause ................................ 27 1839 10.1.3 Mapping of the OBJECT clause ............................... 28 1840 10.1.3.1 Mapping of the SYNTAX clause ............................. 28 1841 SPPI April 2001 1843 10.1.3.2 Mapping of the WRITE-SYNTAX clause ....................... 28 1844 10.1.3.3 Mapping of the PIB-MIN-ACCESS clause ..................... 28 1845 11 Textual Conventions ............................................ 29 1846 11.1 Mapping of the TEXTUAL-CONVENTION macro ...................... 29 1847 11.1.1 Mapping of the SYNTAX clause ............................... 29 1848 11.1.1.1 Sub-typing of Textual Conventions ........................ 29 1849 12 Extending a PIB Module ......................................... 30 1850 12.1 PIB Modules .................................................. 30 1851 12.2 Object Assignments ........................................... 31 1852 12.3 Object Definitions ........................................... 31 1853 13 Appendix A: Mapping a PIB to a MIB ............................. 33 1854 14 Appendix B: Example usage of PIB-REFERENCES and PIB-TAG 1855 clauses ...................................................... 35 1856 15 Security Considerations ........................................ 38 1857 16 IANA Considerations ............................................ 38 1858 17 Authors' Addresses ............................................. 39 1859 18 References ..................................................... 40 1860 19 Full Copyright Statement ....................................... 42