RFC 3159
Structure of Policy Provisioning Information (SPPI)
RFC 3159: Structure of Policy Provisioning Information (SPPI) 🎀
Okay bestie, this is RFC 3159, and it's giving Standards Track 💅. It was published in August 2001 by the Network Working Group, with K. McCloghrie and M. Fine from Cisco Systems leading the charge. J. Seligson and K. Chan came from Nortel Networks, S. Hahn and R. Sahita from Intel, A. Smith from Allegro Networks, and F. Reichmeyer from PFN. The title block doesn't list anything this one obsoletes or updates, so it stands on its own ✨.
Status of this Memo
So this doc is an Internet standards track protocol for the Internet community, and it's literally asking for discussion and suggestions for improvements 🫶. For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌸.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved. 💜
Abstract
Okay so the Abstract tells us what this doc is all about 🧚. It defines the Structure of Policy Provisioning Information (SPPI), which is an adapted subset of SNMP's Structure of Management Information (SMI), and it's used to write Policy Information Base (PIB) modules 🍓.
RFC 2748 defines the COPS protocol, and RFC 2749 explains how COPS gets used to outsource policy decisions for RSVP. Then RFC 3084 brings in another use of COPS, which is provisioning policy 🔥. In this model, policy info is a collection of Provisioning Classes (PRCs) and Provisioning Instances (PRIs), and they all live in a virtual information store called the Policy Information Base (PIB). Related Provisioning Classes get grouped together into a PIB module 👑.
Conventions used in this document
Quick note on the vibe: the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this doc get interpreted exactly as described in [RFC2119] 🙈. Don't freestyle them!
Table of Contents
1 Use of the SMI ................................................. 3
1.1 Terminology Translation ...................................... 3
1.2 Overview ..................................................... 3
2 Structure of this Specification ................................ 4
3 Definitions .................................................... 5
4 PIB Modules .................................................... 17
4.1 Importing Definitions ........................................ 17
4.2 Reserved Keywords ............................................ 18
5 Naming Hierarchy ............................................... 18
6 Mapping of the MODULE-IDENTITY macro ........................... 18
6.1 Mapping of the SUBJECT-CATEGORIES clause ..................... 18
7 Mapping of the OBJECT-TYPE macro ............................... 19
7.1 Mapping of the SYNTAX clause ................................. 19
7.1.1 Counter32 .................................................. 19
7.1.2 Gauge32 .................................................... 20
7.1.3 Opaque ..................................................... 20
7.1.4 IpAddress .................................................. 20
7.1.5 Counter64 .................................................. 20
7.1.6 Integer64 .................................................. 20
7.1.7 Unsigned64 ................................................. 20
7.1.8 Provisioning Classes ....................................... 21
7.2 Mapping of the MAX-ACCESS clause ............................. 21
7.3 Mapping of the PIB-ACCESS clause ............................. 22
7.4 Mapping of the INSTALL-ERRORS clause ......................... 22
7.5 Mapping of the PIB-INDEX clause .............................. 22
7.6 Mapping of the INDEX clause .................................. 23
7.7 Mapping of the AUGMENTS clause ............................... 23
7.8 Mapping of the EXTENDS clause ................................ 24
7.8.1 Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses .. 24
7.9 Mapping of the UNIQUENESS clause ............................. 25
7.10 Mapping of the PIB-REFERENCES clause ........................ 25
7.11 Mapping of the PIB-TAG clause ............................... 25
8 Mapping of the OBJECT-IDENTITY macro ........................... 26
9 Mapping of the OBJECT-GROUP macro .............................. 26
9.1 Mapping of the OBJECTS clause ................................ 26
10 Mapping of the MODULE-COMPLIANCE macro ........................ 26
10.1 Mapping of the MODULE clause ................................ 26
10.1.1 Mapping of the MANDATORY-GROUPS clause .................... 27
10.1.2 Mapping of the GROUP clause ............................... 27
10.1.3 Mapping of the OBJECT clause .............................. 27
10.1.3.1 Mapping of the SYNTAX clause ............................ 27
10.1.3.2 Mapping of the WRITE-SYNTAX clause ...................... 28
10.1.3.3 Mapping of the PIB-MIN-ACCESS clause .................... 28
11 Textual Conventions ........................................... 28
11.1 Mapping of the TEXTUAL-CONVENTION macro ..................... 28
11.1.1 Mapping of the DISPLAY-HINT clause ........................ 29
11.1.2 Mapping of the SYNTAX clause .............................. 29
11.1.2.1 Sub-typing of Textual Conventions ....................... 29
12 Extending a PIB Module ........................................ 29
12.1 PIB Modules ................................................. 29
12.2 Object Assignments .......................................... 30
12.3 Object Definitions .......................................... 30
Appendix A: Mapping a PIB to a MIB ............................... 32
Appendix B: Example usage of PIB-REFERENCES and PIB-TAG clauses .. 33
Security Considerations .......................................... 35
IANA Considerations .............................................. 35
Authors' Addresses ............................................... 37
References ....................................................... 38
Full Copyright Statement ......................................... 401. Use of the SMI ✨
Okay so the SPPI and PIB modules are built on top of SNMP's SMI and MIB modules 🌈. Those use an adapted subset of the ASN.1 data definition language [ASN1]. Basing PIB modules on this format is a total win, because it lets us reuse everything the community already knows, has learned, and has built with the SMI and MIB modules 💖.
1.1. Terminology Translation 🦋
So SMI calls things "managed objects", meaning object types. That covers the tabular ones with names like xxxTable and xxxEntry, plus the scalar and columnar object types too 🌸. SPPI doesn't say "object" at all, because that would get confusing with COPS protocol objects 🙈. Instead, SPPI calls the table and row definitions (the xxxTable and xxxEntry objects) Provisioning Classes (PRCs). An instantiation of a row definition is a Provisioning Instance (PRI). And for a columnar object in a table definition, SPPI says "attribute" of a Provisioning Class. Also, SPPI doesn't support the equivalent of SMI's scalar objects, so no solo values here 💅.
1.2. Overview 🧚
SNMP's SMI has five parts: module definitions, object definitions, notification definitions [SMI], textual convention definitions [TC], and conformance definitions [CONF] 👑.
- The SMI's MODULE-IDENTITY macro conveys the semantics of a MIB module. SPPI uses this same macro to convey the semantics of a PIB module ✨.
- The SMI's OBJECT-TYPE macro conveys the syntax and semantics of managed objects. SPPI uses this macro to convey the syntax and semantics of PRCs and their attributes 💜.
- SMI's notification definitions aren't used by SPPI (at this time). Quick heads up that the use of the keyword
notifyin SPPI has nothing to do with SMI's notifications 🙈. - The SMI's TEXTUAL CONVENTION macro lets you define new data types. SPPI uses it to define new data types with particular syntax and semantics that are shared by several attributes of one or more PRCs 🔥.
- SMI's conformance definitions define a few macros: OBJECT-GROUP, NOTIFICATION-GROUP, MODULE-COMPLIANCE, and AGENT-CAPABILITIES 🍓. SPPI uses OBJECT-GROUP and MODULE-COMPLIANCE to specify the acceptable lower bounds of implementation for the attributes of PRCs, and indirectly, for the PRCs themselves 🎀. NOTIFICATION-GROUP isn't used by SPPI (at this time). Any potential use of AGENT-CAPABILITIES by SPPI is still for further study 🌸.
2. Structure of this Specification 🫶
Okay so SMI is specified with an ASN.1 definition plus descriptive text for each element in that definition 💖. This document specifies SPPI using an ASN.1 definition too, but it's a modified version of SMI's definition 🦋. The descriptive text here only covers the elements where SPPI's ASN.1 definition differs from SMI's. For any element with no descriptive text in this spec, you just go check SMI's descriptive text for that element 🧚.
3. Definitions 👑
Here's the big ASN.1 chunk. It's bestie-level detail, so read it carefully 💅.
COPS-PR-SPPI DEFINITIONS ::= BEGIN
IMPORTS ObjectName, SimpleSyntax, ExtUTCTime, mgmt
FROM SNMPv2-SMI;
-- the root for PIB definitions
pib OBJECT IDENTIFIER ::= { mgmt 2 }
-- definitions for PIB modules
MODULE-IDENTITY MACRO ::=
BEGIN
TYPE NOTATION ::=
SubjectPart -- new
"LAST-UPDATED" value(Update ExtUTCTime)
"ORGANIZATION" Text
"CONTACT-INFO" Text
"DESCRIPTION" Text
RevisionPart
VALUE NOTATION ::=
value(VALUE OBJECT IDENTIFIER)
SubjectPart ::= -- new
"SUBJECT-CATEGORIES" "{" Categories "}"
-- see IANA Considerations section
Categories ::= -- new
CategoryIDs
| "all"
CategoryIDs ::= -- new
CategoryID
| CategoryIDs "," CategoryID
CategoryID ::= -- new
identifier "(" number ")" -- number is positive
RevisionPart ::=
Revisions
| empty
Revisions ::=
Revision
| Revisions Revision
Revision ::=
"REVISION" value(Update ExtUTCTime)
"DESCRIPTION" Text
-- a character string as defined in [SMI]
Text ::= value(IA5String)
END
--
OBJECT-IDENTITY MACRO ::=okay so OBJECT-IDENTITY is up next, and it's giving very simple macro energy 🦋
BEGIN
TYPE NOTATION ::=
"STATUS" Status
"DESCRIPTION" Text
ReferPart
VALUE NOTATION ::=
value(VALUE OBJECT IDENTIFIER)
Status ::=
"current"
| "deprecated"
| "obsolete"
ReferPart ::=
"REFERENCE" Text
| empty
-- a character string as defined in [SMI]
Text ::= value(IA5String)
END
-- syntax of attributes
-- the "base types" defined here are:
-- 3 built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER
-- 7 application-defined types: Integer32, IpAddress, Unsigned32,
-- TimeTicks, Opaque, Integer64 and Unsigned64
ObjectSyntax ::=
CHOICE {
simple
SimpleSyntax,
-- note that SEQUENCEs for table and row definitions
-- are not mentioned here...
application-wide
ApplicationSyntax
}
-- application-wide types
ApplicationSyntax ::=
CHOICE {
ipAddress-value
IpAddress,
timeticks-value
TimeTicks,
arbitrary-value
Opaque,
unsigned-integer-value
Unsigned32,
large-integer-value -- new
Integer64,
large-unsigned-integer-value -- new
Unsigned64
}
-- the following 5 types are copied from the SMI
-- indistinguishable from INTEGER, but never needs more than
-- 32-bits for a two's complement representation
Integer32 ::=
INTEGER (-2147483648..2147483647)
-- (this is a tagged type for historical reasons)
IpAddress ::=
[APPLICATION 0]
IMPLICIT OCTET STRING (SIZE (4))
-- ******* THIS TYPE DEFINITION IS DEPRECATED *******
-- The IpAddress type represents a 32-bit internet
-- IPv4 address. It is represented as an OctetString
-- of length 4, in network byte-order.
-- Note that the IpAddress type is present for
-- historical reasons. IPv4 and IPv6 addresses should
-- be represented using the INET-ADDRESS-MIB
-- defined in [INETADDR].
-- an unsigned 32-bit quantity
Unsigned32 ::=
[APPLICATION 2]
IMPLICIT INTEGER (0..4294967295)
-- hundredths of seconds since an epoch
TimeTicks ::=
[APPLICATION 3]
IMPLICIT INTEGER (0..4294967295)
--for backward compatibility only
Opaque ::=
[APPLICATION 4]
IMPLICIT OCTET STRING
-- the following 2 types are not present in the SMI
Integer64 ::=
[APPLICATION 10]
IMPLICIT INTEGER (-9223372036854775808..9223372036854775807)
Unsigned64 ::=
[APPLICATION 11]
IMPLICIT INTEGER (0..18446744073709551615)
-- definition for Provisioning Classes and their attributes
-- (differences from the SMI are noted in the ASN.1 comments)
OBJECT-TYPE MACRO ::=
BEGIN
TYPE NOTATION ::=
"SYNTAX" Syntax
UnitsPart
"PIB-ACCESS" Access -- modified
PibReferencesPart -- new
PibTagPart -- new
"STATUS" Status
"DESCRIPTION" Text
ErrorsPart -- new
ReferPart
IndexPart -- modified
MibIndexPart -- modified
UniquePart -- new
DefValPart
VALUE NOTATION ::=
value(VALUE ObjectName)
Syntax ::= -- Must be one of the following:
-- a base type (or its refinement),
-- a textual convention (or its refinement), or
-- a BITS pseudo-type
type
| "BITS" "{" NamedBits "}"
NamedBits ::= NamedBit
| NamedBits "," NamedBit
NamedBit ::= identifier "(" number ")" -- number is nonnegative
UnitsPart ::=
"UNITS" Text
| empty
Access ::= -- modified
"install"
| "notify"
| "install-notify"
| "report-only"
Status ::=
"current"
| "deprecated"
| "obsolete"
ErrorsPart ::= -- new
"INSTALL-ERRORS" "{" Errors "}"
| empty
Errors ::= -- new
Error
| Errors "," Error
Error ::= -- new
identifier "(" number ")" -- number is positive
ReferPart ::=
"REFERENCE" Text
| empty
IndexPart ::=
"PIB-INDEX" "{" Index "}" -- new
| "AUGMENTS" "{" Entry "}"
| "EXTENDS" "{" Entry "}" -- new
| empty
Index ::=
-- the correspondent OBJECT-TYPE invocation
value(ObjectName)
Entry ::=
-- use the INDEX value of the
-- correspondent OBJECT-TYPE invocation
value(ObjectName)
MibIndexPart ::=
"INDEX" "{" IndexTypePart "}"
| empty
IndexTypePart ::=
IndexTypes
| IndexTypes "," ImpliedIndex
| ImpliedIndex
IndexTypes ::=
Index
| IndexTypes "," Index
ImpliedIndex ::=
"IMPLIED" Index
PibReferencesPart ::=
-- for use with ReferenceId TC
"PIB-REFERENCES" "{" Entry "}"
| empty
PibTagPart ::=
-- for use with TagReferenceId TC
"PIB-TAG" "{" Attr "}"
| empty
Attr ::= -- specifies an attribute
value(ObjectName)
UniquePart ::= -- new
"UNIQUENESS" "{" UniqueTypes "}"
| "UNIQUENESS" "{" "}"
| empty
UniqueTypes ::=
UniqueType
| UniqueTypes "," UniqueType
UniqueType ::=
-- the correspondent OBJECT-TYPE invocation
value(ObjectName)
DefValPart ::= "DEFVAL" "{" Defvalue "}"
| empty
Defvalue ::= -- must be valid for the type specified in
-- SYNTAX clause of same OBJECT-TYPE macro
value(ObjectSyntax)
| "{" BitsValue "}"
BitsValue ::= BitNames
| empty
BitNames ::= BitName
| BitNames "," BitName
BitName ::= identifier
-- a character string as defined in [SMI]
Text ::= value(IA5String)
END
-- definitions for conformance groups
OBJECT-GROUP MACRO ::=
BEGIN
TYPE NOTATION ::=
ObjectsPart
"STATUS" Status
"DESCRIPTION" Text
ReferPart
VALUE NOTATION ::=
value(VALUE OBJECT IDENTIFIER)
ObjectsPart ::=
"OBJECTS" "{" Objects "}"
Objects ::=
Object
| Objects "," Object
Object ::=
value(ObjectName)
Status ::=
"current"
| "deprecated"
| "obsolete"
ReferPart ::=
"REFERENCE" Text
| empty
-- a character string as defined in [SMI]
Text ::= value(IA5String)
END
-- definitions for compliance statements
MODULE-COMPLIANCE MACRO ::=
BEGIN
TYPE NOTATION ::=
"STATUS" Status
"DESCRIPTION" Text
ReferPart
ModulePart
VALUE NOTATION ::=
value(VALUE OBJECT IDENTIFIER)
Status ::=
"current"
| "deprecated"
| "obsolete"
ReferPart ::=
"REFERENCE" Text
| empty
ModulePart ::=
Modules
Modules ::=
Module
| Modules Module
Module ::=
-- name of module --
"MODULE" ModuleName
MandatoryPart
CompliancePart
ModuleName ::=
-- identifier must start with uppercase letter
identifier ModuleIdentifier
-- must not be empty unless contained
-- in MIB Module
| empty
ModuleIdentifier ::=
value(OBJECT IDENTIFIER)
| empty
MandatoryPart ::=
"MANDATORY-GROUPS" "{" Groups "}"
| empty
Groups ::=
Group
| Groups "," Group
Group ::=
value(OBJECT IDENTIFIER)
CompliancePart ::=
Compliances
| empty
Compliances ::=
Compliance
| Compliances Compliance
Compliance ::=
ComplianceGroup
| Object
ComplianceGroup ::=
"GROUP" value(OBJECT IDENTIFIER)
"DESCRIPTION" Text
Object ::=
"OBJECT" value(ObjectName)
InstallSyntaxPart -- modified
AccessPart
"DESCRIPTION" Text
-- must be a refinement for object's SYNTAX clause
InstallSyntaxPart ::= "SYNTAX" Syntax
| empty
Syntax ::= -- Must be one of the following:
-- a base type (or its refinement),
-- a textual convention (or its refinement), or
-- a BITS pseudo-type
type
| "BITS" "{" NamedBits "}"
NamedBits ::= NamedBit
| NamedBits "," NamedBit
NamedBit ::= identifier "(" number ")" -- number is nonnegative
AccessPart ::=
"PIB-MIN-ACCESS" Access -- modified
| empty
Access ::= -- modified
"not-accessible"
| "install"
| "notify"
| "install-notify"
| "report-only"
-- a character string as defined in [SMI]
Text ::= value(IA5String)
END
-- definition of textual conventions
TEXTUAL-CONVENTION MACRO ::=
BEGIN
TYPE NOTATION ::=
DisplayPart
"STATUS" Status
"DESCRIPTION" Text
ReferPart
"SYNTAX" Syntax
VALUE NOTATION ::=
value(VALUE Syntax) -- adapted ASN.1
DisplayPart ::=
"DISPLAY-HINT" Text
| empty
Status ::=
"current"
| "deprecated"
| "obsolete"
ReferPart ::=
"REFERENCE" Text
| empty
-- a character string as defined in [SMI]
Text ::= value(IA5String)
Syntax ::= -- Must be one of the following:
-- a base type (or its refinement), or
-- a BITS pseudo-type
type
| "BITS" "{" NamedBits "}"
NamedBits ::= NamedBit
| NamedBits "," NamedBit
NamedBit ::= identifier "(" number ")" -- number is nonnegative
ENDthat's the whole macro lineup for this part, and the grammar is now all laid out ✨ we'll pick up the rest of the spec next 💜
COPS-PR-SPPI-TC PIB-DEFINITIONS ::= BEGIN
IMPORTS Unsigned32, MODULE-IDENTITY, TEXTUAL-CONVENTION, pib
FROM COPS-PR-SPPI;
copsPrSppiTc MODULE-IDENTITY
SUBJECT-CATEGORIES { all }
LAST-UPDATED "200108160000Z"
ORGANIZATION "IETF RAP WG"
CONTACT-INFO "Keith McCloghrie
Cisco Systems, Inc.
170 West Tasman Drive,
San Jose, CA 95134-1706 USA
Phone: +1 408 526 5260
Email: kzm@cisco.com
Ravi Sahita
Intel
2111 NE 25th Avenue
Hillsboro, OR 97124 USA
Phone: +1 503 712 1554
Email: ravi.sahita@intel.com "
DESCRIPTION
"The PIB module containing a set of Textual Conventions
which have general applicability to all PIB modules."
REVISION "200108160000Z"
DESCRIPTION
"Initial version, published in RFC 3159."
::= { pib 1 }
InstanceId ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"The textual convention for use by an attribute which is used
as the instance-identifying index of a PRC, i.e., an attribute
named in a PIB-INDEX clause. The value of an attribute with
this syntax is always greater than zero. PRIs of the same PRC
need not have contiguous values for their instance-identifying
attribute."
SYNTAX Unsigned32 (1..4294967295)
ReferenceId ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"A textual convention for use by an attribute which is used as
a pointer in order to reference an instance of a particular
PRC. An attribute with this syntax must not be used in a
PIB-INDEX clause , and its description must specify the
particular PRC to which the referenced PRI will belong.
For an attribute of this type, the referenced PRI must exist.
Furthermore, it is an error to try to delete a PRI that is
referenced by another instance without first deleting/modifying
the referencing instance. The definition of an attribute with
this syntax can permit the attribute to have a value of zero to
indicate that it is not currently pointing to a PRI."
SYNTAX Unsigned32
Prid ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"Represents a pointer to a PRI, i.e,. to an instance of a
PRC. The value is the OID name of the PRC's row definition,
appended with one sub-identifier containing the value of the
InstanceId value for the referenced instance. The definition
of an attribute with this syntax can permit the attribute to
have a value of 0.0 to indicate that it is not currently
pointing to a PRI."
SYNTAX OBJECT IDENTIFIER
TagId ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"Represents a tag value, such that all instances of a
particular PRC having the same tag value form a tag list.
A tag list is identified by the tag value shared by all
instances in that tag list."
SYNTAX Unsigned32 (1..4294967295)
TagReferenceId ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"Represents a reference to a tag list of instances of a
particular PRC. The particular PRC must have an attribute
with the syntax of TagId. The tag list consists of
all instances which have the same value of the TagId
attribute. Reference to the tag list is via the attribute
with the syntax of TagReferenceId containing the tag
value which identifies the tag list.
The definition of an attribute with this syntax can permit
the attribute to have a value of 0 to indicate that it is
not currently referencing a tag list."
SYNTAX Unsigned32
END4. PIB Modules ✨
Okay so the names of all standard PIB modules must be unique 💖 (but different versions of the same module should have the same name). If you're making an enterprise PIB module, you're encouraged to pick a name that's unlikely to clash with a standard one or with other enterprise modules 🎀
The first line of a PIB module looks like this 🦋
PIB-MODULE-NAME PIB-DEFINITIONS ::= BEGINwhere PIB-MODULE-NAME is the module name ✨
Just like the SMI, additional ASN.1 macros must not be defined in PIB modules 🙅♀️
4.1. Importing Definitions
Just like the SMI, a PIB module that needs to reference an external definition must use the IMPORTS statement to name both the descriptor and the module it's defined in, where a module is identified by its ASN.1 module name 📦
Specifically, a PIB module imports each of the base data types it uses from COPS-PR-SPPI (the one defined in this document), and it may import other stuff from other PIB modules as needed 🌸 It may also import (subtree) OIDs from the SMI so it can define new OIDs. And it can import OID assignments plus textual convention definitions from MIB modules, as long as their underlying syntax is supported by the SPPI 💜 BUT the following must not go in an IMPORTS statement, no exceptions:
- named types defined by ASN.1 itself, specifically:
INTEGER,OCTET STRING,OBJECT IDENTIFIER,SEQUENCE,SEQUENCE OF type, - the BITS construct.
Every ASN.1 macro that a PIB uses must be imported from COPS-PR-SPPI, with its definition 🫶
4.2. Reserved Keywords
On top of the reserved keywords listed in the SMI, the following must not be used as descriptors or module names 💀
EXTENDS INSTALL-ERRORS Integer64 PIB-MIN-ACCESS PIB-ACCESS PIB-
INDEX PIB-REFERENCES PIB-TAG SUBJECT-CATEGORIES UNIQUENESS
Unsigned645. Naming Hierarchy 🌈
The SPPI uses the exact same OBJECT IDENTIFIER naming hierarchy as the SMI 🧚 So OIDs are usually assigned to PIB modules from the subtree run by the Internet Assigned Numbers Authority (IANA). BUT, just like the SMI, the SPPI doesn't ban defining PRCs in other parts of the OID tree 👑
6. Mapping of the MODULE-IDENTITY macro 🎀
6.1. Mapping of the SUBJECT-CATEGORIES clause
The SUBJECT-CATEGORIES clause must be present, and it tells you one or more categories of provisioning data this PIB module gives provisioning info for 💅 For use with the COPS-PR protocol, each subject category gets mapped to a COPS Client Type [COPS-PR]. IANA Considerations for SPPI SUBJECT-CATEGORIES follow the same requirements as specified in [COPS] IANA Considerations for COPS Client Types. The subject categories are identified either:
- via the keyword "all", meaning the PIB module defines provisioning information relevant for all subject categories (and therefore, all COPS Client Types), or
- a list of named-number enumerations, where each number, which must be greater than zero, identifies a subject category and is mapped to the Client Type identified by that same number in the COPS protocol. The namespace for these named numbers is global, so the labels should be assigned consistently across PIB modules 🔥 At present time, no more than one named-number enumeration should be specified.
Heads up, the list of categories in a PIB module's SUBJECT-CATEGORIES clause is not exclusive 🦋 That means some other specification might (say, at a future date) add more COPS Client Types the module is relevant to.
When a PIB module applies to multiple subject categories, it exists in multiple virtual information stores, one for each Client-Type 🌸 A PIB module with SUBJECT-CATEGORIES "all" uses the named-number specified in the SUBJECT-CATEGORIES of the PIB it's associated with as its COPS Client-Type when it gets sent over COPS 💖
7. Mapping of the OBJECT-TYPE macro ✨
The SPPI requires that all attribute definitions be contained within a PRC, i.e., within a table definition 🫶
7.1. Mapping of the SYNTAX clause
The SYNTAX clause must be present within the definition of an attribute 🌈 It defines the abstract data structure of that attribute, and the data structure must be one of the following: a base type, the BITS construct, or a textual convention 💅
The SYNTAX clause must also be present for the table and row definitions of a PRC, and in that case it must be a SEQUENCE OF or SEQUENCE (see section 8.1.7 below) 🎀
The base types are an extended subset of the SMI's base types 🧚 They are:
- built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER,
- application-defined types: Integer32, Unsigned32, TimeTicks, Integer64 and Unsigned64.
A textual convention is a brand-new type defined as a sub-type of a base type [TC] 💜 The value of an attribute whose syntax is defined using a textual convention is encoded "on-the-wire" according to the textual convention's underlying base type 📦
Heads up, the set of base types was picked to give a good variety of on-the-wire encodings for attribute values, and base types should carry a minimum of semantics 🌸 Semantics should, as much as possible, be built into a data type through a textual convention 👑
The differences from the SMI in the semantics of ObjectSyntax are described next 🦋
7.1.1. Counter32
The Counter32 type is not supported by the SPPI 🙈
7.1.2. Gauge32
The Gauge32 type is not supported by the SPPI 🙈
7.1.3. Opaque
The Opaque type is provided solely for backward-compatibility, and shall not be used for newly-defined object types 💀 The Opaque type lets you pass arbitrary ASN.1 syntax. A value is encoded using the ASN.1 Basic Encoding Rules [ASN1] into a string of octets, and that gets encoded as an OCTET STRING, basically "double-wrapping" the original ASN.1 value 🌀 A conforming implementation only needs to be able to accept and recognize opaquely-encoded data. It doesn't need to unwrap the data and interpret its contents 🫶 A requirement on "standard" PIB modules is that no object may have a SYNTAX clause value of Opaque 🚫
7.1.4. IpAddress
The IpAddress type is provided solely for backward-compatibility, and shall not be used for newly-defined object types 💅 Instead, It is recommended to use the InetAddressType/InetAddress pair TCs as defined in RFC2851 [INETADDR] ✨
7.1.5. Counter64
The Counter64 type is not supported by the SPPI 🙈
7.1.6. Integer64
The Integer64 type represents integer-valued information between -2^63 and 2^63-1 inclusive (-9223372036854775808 to 9223372036854775807 decimal) 🔥 You can sub-type Integer64 to be more constrained, BUT if the constraint results in all possible values being contained in the range (-2147483648..2147483647), then the Integer32 type must be used instead of Integer64 🧚
7.1.7. Unsigned64
The Unsigned64 type represents integer-valued information between 0 and 2^64-1 inclusive (0 to 18446744073709551615 decimal) 🌈 You can sub-type Unsigned64 to be more constrained, BUT if the constraint results in all possible values being contained in the range (0..4294967295), then the Unsigned32 type must be used instead of Unsigned64 👑
7.1.8. Provisioning Classes 💖
Okay bestie, the SPPI operations on PIBs apply ONLY to PRCs (Provisioning Classes) 🎀. Each PRC is modelled as a table, and every instance of a particular PRC has the same set of attributes. That set of attributes is modelled as a row in the table. Quick heads-up: a PRC must have no more than 127 attributes. Subids 128 and up (for PRC attributes) are reserved for mapping PIBs to MIBs (see Appendix A) 🧚. If a PRC needs more than 127 attributes, it must use the AUGMENTS clause to augment the PRC holding the first 127 attributes so it can add more.
The OBJECT-TYPE macro is used to formalize PRC definitions, and it covers two things:
- the PRC as a whole, called the table definition, and
- the characteristics of every instance of a particular PRC, called the row definition.
In the table definition, the SYNTAX clause looks like this:
SEQUENCE OF <EntryType>where <EntryType> refers to the SEQUENCE type of its attribute definitions.
In the row definition, the SYNTAX clause looks like this:
<EntryType>where <EntryType> is a SEQUENCE type defined as follows:
<EntryType> ::= SEQUENCE { <type1>, ... , <typeN> }There's one <type> for each attribute, and each <type> has this form:
<descriptor> <syntax>Here <descriptor> is the descriptor naming an attribute, and <syntax> takes the value of that attribute's SYNTAX clause. The one twist is that sub-typing information, plus the named values for enumerated integers or the named bits for the BITS construct, get left out of <syntax> 💅.
7.2. Mapping of the MAX-ACCESS clause 🙈
The MAX-ACCESS clause is not supported by the SPPI. Nope, not happening.
7.3. Mapping of the PIB-ACCESS clause 🔑
The PIB-ACCESS clause must be present for a PRC's table definition, and must not be present for any other OBJECT-TYPE definition. It defines what kind of access is appropriate for the PRC. The options are:
- the value
"install"is used for a PRC which a PDP can install in the PEP as provisioning information. - the value
"notify"is used for a PRC where the PEP must notify the PDP of all its instances and attribute values of that PRC. - the value
"install-notify"is used for the uncommon type of PRC that has BOTH characteristics:"install"and"notify"🦋. - the value
"report-only"is used for a PRC that has neither the"install"characteristic nor the"notify"characteristic. Instances of such a PRC may still be included in synchronous/asynchronous reports generated by the PEP. (Note: PRCs having the"install"and/or"notify"characteristics may also be included in reports generated by the PEP.)
7.4. Mapping of the INSTALL-ERRORS clause 🚨
The INSTALL-ERRORS clause may optionally be present for a PRC's table definition, and must be absent otherwise. It lists one or more potential reasons for rejecting an install or a removal of an instance of the PRC. Each reason is a named-number enumeration, where the number is a PRC-specific error-code to be used in a COPS protocol message, as the Error Sub-code, with the Error-Code set to priSpecificError (see [COPS-PR]). The semantics of each named-number enumeration should be described in the PRC's DESCRIPTION clause.
The numbers listed in an INSTALL-ERRORS must be greater than zero and less than 65536. If this clause is not present, an install/remove can still fail, but no PRC-specific error is available to be reported 🫶.
7.5. Mapping of the PIB-INDEX clause 🪪
The PIB-INDEX clause must be present for a row definition (unless an AUGMENTS or an EXTENDS clause is present instead), and must be absent otherwise. It defines identification information for instances of the PRC.
The PIB-INDEX clause includes exactly one descriptor. That descriptor specifies an attribute (typically, but not necessarily, of the same PRC) which is used to identify an instance of that PRC. The syntax of this attribute is REQUIRED to be InstanceId (a textual convention with an underlying syntax of Unsigned32), and it has no semantics other than its use in identifying the PRC instance. The OBJECT IDENTIFIER that identifies an instance of a PRC is formed by appending one sub-identifier to the OID that identifies that PRC's row definition. The value of that additional sub-identifier is that instance's value of the attribute specified in the INDEX clause.
Note that SPPI does not permit use of the IMPLIED keyword in a PIB-INDEX clause 🙅♀️.
7.6. Mapping of the INDEX clause 📇
The INDEX clause is optionally present if a PIB-INDEX clause is present, and must be absent otherwise. If present, the INDEX clause can contain any number of attributes, and it is used only by the algorithmic conversion of a PIB to a MIB (see Appendix A).
An IMPLIED keyword can be present in an INDEX clause if so desired ✨.
7.7. Mapping of the AUGMENTS clause 🧩
The AUGMENTS clause must not be present except in row definitions. It's an alternative to the PIB-INDEX clause and the EXTENDS clause. Every row definition has exactly one of: a PIB-INDEX clause, an AUGMENTS clause, or an EXTENDS clause.
A row definition that has a PIB-INDEX clause is called a base row definition. A row definition that has an AUGMENTS clause is called a row augmentation, where the AUGMENTS clause names the base row definition augmented by this row augmentation. (So yes, a row augmentation cannot itself be augmented 🙃.)
A PRC whose row definition is a row augmentation is called an augmenting PRC. Instances of an augmenting PRC are identified according to the PIB-INDEX clause of the base row definition named in the AUGMENTS clause. Instances of an augmenting PRC also exist according to the same semantics as instances of the PRC it augments. So when an instance of a PRC is installed or removed, an instance of every PRC that augments it is also installed or removed (for more details, see [COPS-PR]).
7.8. Mapping of the EXTENDS clause 🌸
The EXTENDS clause must not be present except in row definitions. It's an alternative to the PIB-INDEX clause and the AUGMENTS clause. Every row definition has exactly one of: a PIB-INDEX clause, an AUGMENTS clause, or an EXTENDS clause.
A row definition that has an EXTENDS clause is called a sparse row augmentation, where the EXTENDS clause names the row definition that is sparsely-augmented by this sparse row augmentation. The sparsely-augmented row can be a base row definition, or another sparse row augmentation.
A PRC whose row definition is a sparse row augmentation is called a sparsely augmenting PRC. Instances of a sparsely augmenting PRC are identified according to the PIB-INDEX clause of the row definition named in the sparsely augmenting PRC's EXTENDS clause.
An instance of a sparsely augmenting PRC can not exist unless a corresponding instance of the PRC it sparsely augments exists. So when an instance of a PRC is removed, an instance of any PRC that sparsely augments it is also removed. However, an instance of a sparsely augmenting PRC need not exist when the corresponding instance of the PRC that it sparsely augments exists. This means an instance of a sparsely augmenting PRC can be installed at the same time as, or after, the installation of the corresponding instance of the PRC it sparsely augments, and can be removed before the removal of that instance. So instances of a sparsely augmenting PRC must be installed explicitly, but they're removed either implicitly (via removal of the augmented PRI) or explicitly.
When a sparsely augmented PRC is installed, both instances, the instance of the sparsely augmented PRC and the instance of the sparsely augmenting PRC, must be sent in one COPS message. Bestie, that's the big one 🔥.
7.8.1. Relation between PIB-INDEX, AUGMENTS and EXTENDS clauses 🧠
When defining instance identification information for a PRC:
- If there is a one-to-one correspondence between instances of this PRC and instances of an existing PRC, then the AUGMENTS clause should be used.
- Otherwise, if there is a sparse relationship between instances of this PRC and instances of an existing PRC (that is, there is a one to zero or one correspondence between instances of a sparsely augmented PRC and the instances of the PRC that sparsely augments it), then an EXTENDS clause should be used.
- Otherwise, a PIB-INDEX clause should be used, which names its own InstanceId attribute.
7.9. Mapping of the UNIQUENESS clause 🔐
The UNIQUENESS clause is optionally present for any row definition. It lists a set of zero or more of the PRC's attributes for which no two instances of the PRC can have the same set of values. The specified set of attributes provides a necessary and sufficient set of values to identify an instance of this PRC. The attribute contained in the PIB-INDEX clause may not be present in the UNIQUENESS clause. By definition, an attribute may not appear more than once in a UNIQUENESS clause. A UNIQUENESS clause containing zero attributes indicates that two instances of the PRC could have identical values for all attributes except, of course, the one named in the PIB-INDEX clause.
If a PRC and its sparsely augmenting PRC both have UNIQUENESS clauses, then the UNIQUENESS constraint for instances of each PRC MUST be applied according to the UNIQUENESS clause in the corresponding PRC definition. Note that a sparsely augmenting PRC can thus override the UNIQUENESS clause of the PRC it sparsely augments 🤯.
Even though the UNIQUENESS clause is optional, its inclusion is recommended wherever it provides useful information.
7.10. Mapping of the PIB-REFERENCES clause 🔗
The PIB-REFERENCES clause must be present for any attribute that has the SYNTAX of ReferenceId, and must be absent otherwise. It names the PRC whose instance is referenced by the ReferenceId attribute. For example usages of the PIB-REFERENCES clause, see Appendix B 📚.
7.11. Mapping of the PIB-TAG clause 🏷️
The PIB-TAG clause must be present for an attribute that has the SYNTAX TagReferenceId, and must be absent otherwise. It's used to indicate that this attribute references a "tag list" of instances of another PRC. This tag list (similar in concept to how the same term is used in [APPL]) is formed by all instances of the other PRC that have the same (tag) value of a particular attribute of that other PRC. The particular attribute of the other PRC, which must have the SYNTAX TagId, is named in the PIB-TAG clause. For an example usage of the PIB-TAG clause, see Appendix B 🎀.
8. Mapping of the OBJECT-IDENTITY macro 🪄
The OBJECT-IDENTITY macro is used in PIB modules to define information about an OBJECT IDENTIFIER assignment.
9. Mapping of the OBJECT-GROUP macro 🧺
For conformance purposes, it's useful to define a conformance group as a collection of related PRCs and their attributes. The OBJECT-GROUP macro (directly) defines the collection of attributes that belong to a conformance group. Since each attribute in the collection belongs to a PRC, the collection of related PRCs that belong to a conformance group is also specified (indirectly) as the set of PRCs to which the included attributes belong 👑.
9.1. Mapping of the OBJECTS clause 💖
okay so the OBJECTS clause is the list of every attribute inside a conformance group 🎀 and it MUST be present, bestie. Every attribute you list has to be defined in the same PIB module where the OBJECT-GROUP macro shows up 🧚
It is REQUIRED that every attribute defined in a PIB module be contained in at least one conformance group. This exists to stop the classic oops of adding a brand new attribute and then forgetting to put it in a group 😭 (we've all been there, no judgment 🙈)
10. Mapping of the MODULE-COMPLIANCE macro 🦋
the MODULE-COMPLIANCE macro is how you share the minimum set of requirements for implementing one or more PIB modules ✨
A requirement on all "standard" PIB modules is that a corresponding MODULE-COMPLIANCE specification is also defined, either in the same module or in a companion module. Iconic behaviour, honestly 💅
10.1. Mapping of the MODULE clause 🌸
The MODULE clause, which MUST be present, gets used again and again to name each PIB module that compliance requirements are being specified for. Each PIB module is named by its module name and, optionally, by its associated OBJECT IDENTIFIER as well. The module name can be left out when the MODULE-COMPLIANCE invocation sits inside a PIB module, because then it just means the PIB module it's wrapped in 🧁
10.1.1. Mapping of the MANDATORY-GROUPS clause 💅
The MANDATORY-GROUPS clause need not be present. It names the one or more conformance groups in the matching PIB module that are unconditionally mandatory for implementation. So if an agent claims compliance to the PIB module, then it MUST implement each and every attribute (and therefore the PRCs those attributes belong to) inside every conformance group listed. No skipping, bestie 🫶
10.1.2. Mapping of the GROUP clause 🎀
The GROUP clause need not be present, but it can be used over and over to name each conformance group that is conditionally mandatory for compliance to the PIB module. The GROUP clause can also name unconditionally OPTIONAL groups. A group named in a GROUP clause MUST be absent from the matching MANDATORY-GROUPS clause, so no double-dipping 🙅♀️
Conditionally mandatory groups include the ones that are mandatory only if a particular protocol is implemented, or only if another group is implemented. The DESCRIPTION of a GROUP clause spells out the conditions under which the group is conditionally mandatory 📝
A group named in neither a MANDATORY-GROUPS clause nor a GROUP clause is unconditionally OPTIONAL for compliance to the PIB module 🌈
10.1.3. Mapping of the OBJECT clause 🧚
The OBJECT clause need not be present, but it gets used repeatedly to specify each attribute where compliance has a refined requirement compared to the PIB module definition. That attribute MUST be present in one of the conformance groups named in the matching MANDATORY-GROUPS clause or GROUP clauses ✨
By definition, each attribute specified in an OBJECT clause follows a MODULE clause that names the PIB module where that attribute is defined. So using an IMPORTS statement to say where those attributes come from is redundant, and it is NOT REQUIRED in a PIB module. Less typing, more slay 💅
10.1.3.1. Mapping of the SYNTAX clause 🌷
The SYNTAX clause need not be present. It gives a refined SYNTAX for the attribute named in the matching OBJECT clause. That refined syntax is the minimum level of support needed for this attribute in order to be compliant 💜
10.1.3.2. Mapping of the WRITE-SYNTAX clause 🙃
The WRITE-SYNTAX clause is not supported by the SPPI. Not vibing with it, so we skip it 💀
10.1.3.3. Mapping of the PIB-MIN-ACCESS clause 🔐
The PIB-MIN-ACCESS clause need not be present. It sets the minimal level of access for the attribute named in the matching OBJECT clause. If this clause is absent, the minimal level of access is the same as the maximal level in the PIB-ACCESS clause of the matching invocation of the OBJECT-TYPE macro 🦋
If the clause IS present, it MUST specify a subset of the access in the matching PIB-ACCESS clause. The subset rules go like this: "install" is a subset of "install-notify", "notify" is a subset of "install-notify", and "not- accessible" is a subset of all the other values 🫧
An implementation is compliant if the level of access it provides is the same as or a superset of the minimal level in the MODULE-COMPLIANCE macro, and the same as or a subset of the maximal level in the PIB-ACCESS clause. Basically it has to sit in the sweet spot in between 🍓
11. Textual Conventions 🌈
when you're designing a PIB module, it's super handy to define brand new data types that look a lot like the ones in the SPPI. Compared to an SPPI type, each of these new types has a different name, a similar syntax, and specific semantics. These newly defined types are called textual conventions, and they exist for the convenience of humans reading the PIB module 📖
Attributes defined using a textual convention are always encoded by means of the rules that define their underlying type. So the encoding never changes, just the labels 🎀
11.1. Mapping of the TEXTUAL-CONVENTION macro 🧁
the TEXTUAL-CONVENTION macro is how you convey the syntax and semantics of a textual convention. It SHOULD be noted that expanding the TEXTUAL-CONVENTION macro is something that conceptually happens during implementation, not at run-time ⏰
The name of a textual convention MUST consist of one or more letters or digits, with the very first character being an upper case letter. The name MUST NOT conflict with any of the reserved words listed in section 5.2, SHOULD NOT consist of all upper case letters, and SHALL NOT exceed 64 characters in length. (However, names longer than 32 characters are NOT RECOMMENDED, so keep it short and sweet 🫶) The hyphen is not allowed in the name of a textual convention, except in information modules converted from SMIv1, which allowed hyphens in ASN.1 type assignments. And all names used for textual conventions defined in all "standard" PIB modules SHALL be unique. No copycats 👑
11.1.1. Mapping of the DISPLAY-HINT clause 🖥️
The DISPLAY-HINT clause need not be present. It gives a hint about how the value of an instance of an object with the syntax defined using this textual convention might be displayed. The DISPLAY-HINT clause MUST NOT be present if the Textual Convention is defined with a syntax of OBJECT IDENTIFIER, or any enumerated syntax (BITS or INTEGER). Whether it makes sense for other syntax types depends on the specific definition of the Textual Convention 🌸
The rules for the format specification of the hint are the same as specified in Section 3.1 of [TC]. 📚
11.1.2. Mapping of the SYNTAX clause 🧩
The SYNTAX clause MUST be present. It defines the abstract data structure that corresponds to the textual convention. That data structure MUST be one of the following: a base type (see the SYNTAX clause of an OBJECT-TYPE macro), or the BITS construct. Which means the SYNTAX clause of a Textual Convention can not refer to a previously defined Textual Convention. Plot twist, no nesting 😭
11.1.2.1. Sub-typing of Textual Conventions 🎀
The SYNTAX clause of a TEXTUAL CONVENTION macro MAY be sub-typed in the same way as the SYNTAX clause of an OBJECT-TYPE macro 💅
12. Extending a PIB Module 🌷
PIBs MAY be revised as implementation experience is gained. However, changes that have the potential to disrupt interoperability between the previous PIB and the revised PIB are not allowed. Interop is sacred, bestie 🚫
12.1. PIB Modules 🧚
For any change, the invocation of the MODULE-IDENTITY macro MUST be updated to include information about the revision. Specifically, that means updating the LAST-UPDATED clause, adding a pair of REVISION and DESCRIPTION clauses, and making any necessary changes to existing clauses, including the ORGANIZATION and CONTACT-INFO clauses 📝
Any definition contained in an existing PIB is available to be IMPORT-ed by any other PIB, and it is referenced in an IMPORTS clause via the PIB module name. So a PIB module name SHOULD NOT be changed, and definitions SHOULD NOT be moved from one PIB to another. Hands off the names, babe 🙅♀️
Obsolete definitions MUST NOT be removed from PIB modules, since their descriptors may still be referenced by other PIB modules. The OBJECT IDENTIFIERs used to name them MUST never be re-assigned. The EXTENDS/AUGMENTS clause SHOULD be used to extend previous definitions, depending on the information to be represented 🦋
Changes to an existing PIB can be made in several ways:
- Additional PRCs can be added to a PIB, or an existing one can be deprecated. ✨
- Attributes can be added to, or deprecated from, an existing PRC. Note that an ASN.1 value of the correct type or an ASN.1 NULL value MUST be sent even for deprecated attributes to maintain interoperability. New attributes MUST be added in sequence after the existing ones. 🫶
- An existing PRC can be extended or augmented with a new PRC defined in another PIB (perhaps an enterprise-specific one). 🌈
Additional named-number enumerations MAY be added to a SUBJECT-CATEGORIES clause. 🧁
12.2. Object Assignments 💜
If any non-editorial change is made to any clause of an object assignment, then the OBJECT IDENTIFIER value associated with that object assignment MUST also be changed, along with its associated descriptor. Note that the max subid for PRC attributes is 127 (See Section 7.1.8) 🔢
12.3. Object Definitions 🍓
An object definition MAY be revised in any of the following ways:
- An enumerated INTEGER in a SYNTAX clause MAY have new enumerations added or existing labels changed. Similarly, named bits MAY be added or existing labels changed for the BITS construct. 🌸
- The value of a SYNTAX clause MAY be replaced by a textual convention, provided the textual convention is defined to use the same primitive ASN.1 type, has the same set of values, and has identical semantics. 🎀
- A UNITS clause MAY be added. 📏
- A STATUS clause value of "current" MAY be revised as "deprecated" or "obsolete". Similarly, a STATUS clause value of "deprecated" MAY be revised as "obsolete". When making such a change, the DESCRIPTION clause SHOULD be updated to explain the rationale. 🪦
- Clarifications and additional information MAY be included in the DESCRIPTION clause. 💬
- An INSTALL-ERRORS clause MAY be added, or an existing INSTALL-ERRORS clause MAY have additional errors defined. ⚠️
- A REFERENCE clause MAY be added or updated. 📚
- A DEFVAL clause MAY be added or updated. 🧩
- A PRC MAY be augmented by adding new objects at the end of the row, and making the corresponding update to the SEQUENCE definition. 🧚
- Entirely new objects MAY be defined, named with previously unassigned OBJECT IDENTIFIER values. ✨
Otherwise, if the semantics of any previously defined object are changed (meaning a non-editorial change is made to any clause other than those specifically allowed above), then the OBJECT IDENTIFIER value associated with that object MUST also be changed. Changing the descriptor associated with an existing object counts as a semantic change, because these strings MAY be used in an IMPORTS statement. Not a tiny tweak, bestie 🚨
Appendix A: Mapping a PIB to a MIB ✨
okay so the SPPI is modelled on the SMI, which means a PIB can potentially be algorithmically mapped into a MIB 🧚 this is giving glow-up energy. Here's the recipe:
- Add "-MIB" to the end of the module's module name.
- Give the MODULE-IDENTITY a different OID value.
- Swap the keyword PIB-DEFINITIONS for DEFINITIONS.
- Add "-MIB" to the end of every external module name that refers to a PIB module.
- For each PRC definition: if there's no INDEX clause, change the "PIB-INDEX" keyword to "INDEX". If there is an INDEX clause, just delete the PIB-INDEX clause.
- Delete all of these clauses: PIB-ACCESS, PIB-REFERENCES, PIB-TAG, UNIQUENESS, INSTALL-ERRORS, and SUBJECT-CATEGORIES 🗑️
- Turn every PIB-MIN-ACCESS clause into a MIN-ACCESS clause. "install" and "install-notify" become "read-create", and "notify" becomes "read-only".
- Add a MAX-ACCESS clause to each OBJECT-TYPE. Table and row definitions get
not-accessible. Any attribute in the INDEX clause also getsnot-accessible. Everything else getsread-create. - Add a columnar attribute of type RowStatus, with a descriptor and a suitable DESCRIPTION. The descriptor is the PRC's descriptor with the nine characters "RowStatus" tacked on the end (chopped down if it gets too long). A Subid of 128 or higher (anything beyond 127) can be used as the OID for this column 💅
- Fix any SYNTAX clause whose base data type isn't allowed in the SMI. You can either swap in a valid SMI type, or drop the OBJECT-TYPE or TEXTUAL-CONVENTION definition along with every reference to it. It isn't clear yet which SMI type is the best fit, so the conversion SHOULD give you a configurable option with at least these choices:
- Convert to an
OCTET STRINGof the right size. In particular, this option maps bothInteger64andUnsigned64toOCTET STRING (SIZE(8)), or - Leave them out of the conversion, or
- Map
Integer64andUnsigned64toCounter64(even though this has problems representing negative numbers, and unwanted counter semantics.)
- Convert to an
Appendix B: Example usage of PIB-REFERENCES and PIB-TAG clauses
this example shows how the PIB-REFERENCES and PIB-TAG clauses get used 🎀
the PIB-REFERENCES clause shows up on qosIfDscpMapQueue and qosIfDscpMapThresh. It tells you which PRC those attributes point to an instance of.
the qosIfDscpMapTable PRC has one instance per DSCP in a given "map", but there's no PRC for the map itself. The map is really just every qosIfDscpMapTable instance that shares the same qosIfDscpMapMapId value. So the tag list is all of those instances grouped by that shared value. qosIfDscpAssignDscpMap references this tag list, and its PIB-TAG clause is how that relationship gets shown 🍓
qosIfDscpAssignTable OBJECT-TYPE
SYNTAX SEQUENCE OF QosIfDscpAssignEntry
PIB-ACCESS install
STATUS current
DESCRIPTION " "
::= { qosIfParameters 9 }
qosIfDscpAssignEntry OBJECT-TYPE
SYNTAX QosIfDscpAssignEntry
STATUS current
DESCRIPTION
"An instance of the qosIfDscpAssign class."
PIB-INDEX { qosIfDscpAssignPrid }
UNIQUENESS { qosIfDscpAssignName, qosIfDscpAssignRoles }
::= { qosIfDscpAssignTable 1 }
QosIfDscpAssignEntry ::= SEQUENCE {
qosIfDscpAssignPrid InstanceId,
qosIfDscpAssignName SnmpAdminString,
qosIfDscpAssignRoles RoleCombination,
qosIfDscpAssignDscpMap TagReferenceId
}
qosIfDscpAssignDscpMap OBJECT-TYPE
SYNTAX TagReferenceId
PIB-TAG { qosIfDscpMapMapId } -- attribute defined below
STATUS current
DESCRIPTION
"The DSCP map which is applied to interfaces of type
qosIfDscpAssignName which have a role combination of
qosIfDscpAssignRoles."
::= { qosIfDscpAssignEntry 3 }
--
-- DSCP to Queue and Threshold Mapping Table
--
qosIfDscpMapTable OBJECT-TYPE
SYNTAX SEQUENCE OF QosIfDscpMapEntry
PIB-ACCESS install
STATUS current
DESCRIPTION
"Assigns DSCP values to queues and thresholds for an arbitrary
DSCP map. This map can then be assigned to various interface
and role combination pairs."
::= { qosIfParameters 10 }
qosIfDscpMapEntry OBJECT-TYPE
SYNTAX QosIfDscpMapEntry
STATUS current
DESCRIPTION
"An instance of the qosIfDscpMap class."
PIB-INDEX { qosIfDscpMapPrid }
UNIQUENESS { qosIfDscpMapMapId, qosIfDscpMapDscp }
::= { qosIfDscpMapTable 1 }
QosIfDscpMapEntry ::= SEQUENCE {
qosIfDscpMapPrid InstanceId,
qosIfDscpMapMapId TagId,
qosIfDscpMapDscp Dscp,
qosIfDscpMapQueue ReferenceId,
qosIfDscpMapThresh ReferenceId
}
qosIfDscpMapMapId OBJECT-TYPE
SYNTAX TagId
STATUS current
DESCRIPTION
"An integer that identifies the DSCP map to which this PRI
belongs."
::= { qosIfDscpMapEntry 2 }
qosIfDscpMapQueue OBJECT-TYPE
SYNTAX ReferenceId
PIB-REFERENCES { qosIfQueueEntry }
STATUS current
DESCRIPTION
"This attribute maps the DSCP specified by qosIfDscpMapDscp to
the queue identified by qosIfQueuePrid in qosIfQueueTable.
For a given DSCP map, all the queues must belong to a single
queue set."
::= { qosIfDscpMapEntry 4 }
qosIfDscpMapThresh OBJECT-TYPE
SYNTAX ReferenceId
PIB-REFERENCES { qosIfThresholdEntry }
STATUS current
DESCRIPTION
"This attribute maps the DSCP specified by qosIfDscpMapDscp to
the threshold identified by qosIfThresholdId in
qosIfThresholdTable. The threshold set to which this
threshold belongs must be assigned to the queue specified by
qosIfDscpMapQueue."
::= { qosIfDscpMapEntry 5 }Security Considerations
this doc defines a language for writing provisioning info. The language itself has no security impact on the Internet 🔒✨ (phew, bestie!)
IANA Considerations
the root of the subtree that IANA administers for the Internet is:
internet OBJECT IDENTIFIER ::= { iso 3 6 1 }so the Internet subtree of OBJECT IDENTIFIERs starts with this prefix:
1.3.6.1.a few branches under that subtree get used for network management:
mgmt OBJECT IDENTIFIER ::= { internet 2 }
experimental OBJECT IDENTIFIER ::= { internet 3 }
private OBJECT IDENTIFIER ::= { internet 4 }
enterprises OBJECT IDENTIFIER ::= { private 1 }the mgmt(2) subtree is where "standard" objects live 📚
this document defines pib OBJECT IDENTIFIER ::= { mgmt 2 } as the root for PIBs that get carried over [COPS-PR]. This Object Identifier is a high-level assignment that needs to be registered with [IANA]. Root Object Identifiers for future "standards track" PIBs will also need to be registered, and they MUST use Object Identifiers below this oid 🌸 A standards track PIB can only get an OID from IANA if the IESG has approved the PIB as a "standards track" document. Experimental and enterprise PIBs MUST be defined under the "experimental" and "enterprises" Object Identifiers, respectively.
the PIB module "copsPrSppiTc" is defined in this document as a standard module, so it needs a subid assignment under the "pib" oid from IANA. 🦋
SPPI SUBJECT-CATEGORIES get mapped to COPS Client Types. IANA Considerations for SUBJECT-CATEGORIES follow the same requirements as [COPS] IANA Considerations for COPS Client Types. So a new PIB can define a new COPS Client Type in the "standards", "experimental" or "enterprise" space, and once it's approved, a new COPS Client Type gets assigned. IANA must update the registry for COPS Client Types as a result (where applicable, as described in [COPS] IANA Considerations) 💅
Authors' Addresses
Keith McCloghrie
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706 USA
Phone: +1 408 526 5260
Email: kzm@cisco.comMichael Fine
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706 USA
Phone: +1 408 527 8218
EMail: mfine@cisco.comJohn Seligson
Nortel Networks, Inc.
4401 Great America Parkway
Santa Clara, CA 95054 USA
Phone: +1 408 495 2992
EMail: jseligso@nortelnetworks.comKwok Ho Chan
Nortel Networks, Inc.
600 Technology Park Drive
Billerica, MA 01821 USA
Phone: +1 978 288 8175
EMail: khchan@nortelnetworks.comScott Hahn
Intel
2111 NE 25th Avenue
Hillsboro, OR 97124 USA
Phone: +1 503 264 8231
EMail: scott.hahn@intel.comRavi Sahita
Intel
2111 NE 25th Avenue
Hillsboro, OR 97124 USA
Phone: +1 503 712 1554
EMail: ravi.sahita@intel.comAndrew Smith
Allegro Networks
6399 San Ignacio Ave.
San Jose, CA 95119 USA
Fax: +1 415 345 1827
EMail: andrew@allegronetworks.comFrancis Reichmeyer
PFN Inc.
University Park at MIT
26 Landsdowne Street
Cambridge, MA 02139 USA
Phone: +1 617 494 9980
EMail: franr@pfn.comReferences 📚
okay so this is the bibliography bit, and it's giving research paper energy 🎀 every doc it leans on is listed here, with all the details. no skipping, bestie 💅
- [COPS] Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R. and A. Sastry, "The COPS (Common Open Policy Service) Protocol", RFC 2748, January 2000. 🧚
- [COPS-RSVP] Boyle, J., Cohen, R., Durham, D., Herzog, S., Rajan, R. and A. Sastry, " COPS usage for RSVP", RFC 2749, January 2000. 🌸
- [COPS-PR] Reichmeyer, F., Herzog, S., Chan, K., Durham, D., Yavatkar, R., Gai, S., McCloghrie, K. and A. Smith, "COPS Usage for Policy Provisioning", RFC 3084, March 2001. 💜
- [SMI] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 🦋
- [TC] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. 🍓
- [CONF] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Conformance Statements for SMIv2", STD 58, RFC 2580, April 1999. 👑
- [APPL] Levi, D., Meyer, P. and B. Stewart, "SNMP Applications", RFC 2573, April 1999. ✨
- [ASN1] Information processing systems -- Open Systems Interconnection -- Specification of Abstract Syntax Notation One (ASN.1), International Organization for Standardization. International Standard 8824, December 1987. 🌈
- [INETADDR] Daniele, M., Haberman, B., Routhier, S. and J. Schoenwaelder "Textual Conventions for Internet Network Addresses", RFC 2851, June 2000. 🫶
- [IANA]
http://www.isi.edu/in-notes/iana/assignments/smi-numbers🔥 - [IANA-CONSIDERATIONS] Alvestrand, H. and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. 💖
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 🧚♀️
Full Copyright Statement ⭐
okay this part is the legal stuff, so I'm keeping it word-for-word 🫶 no cap, you don't mess with copyright notices lol
Copyright (C) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 🌸
Acknowledgement 🎀
okay last bit, and it's a quick one 💅
Funding for the RFC Editor function is currently provided by the Internet Society. 🌈
📦 where this page comes from
- ietf: rfc3159 2001-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms