RFC 2580
Conformance Statements for SMIv2
RFC 2580: Conformance Statements for SMIv2 🎀
okay bestie, let's get into it 💖 RFC 2580 is all about conformance statements for SMIv2, and it's a Standards Track doc (STD 58) from the Network Working Group. It obsoletes RFC 1904 and doesn't update anything else 👑. The current editors are K. McCloghrie (Cisco Systems), D. Perkins (SNMPinfo), and J. Schoenwaelder (TU Braunschweig). The previous authors were J. Case (SNMP Research), K. McCloghrie (Cisco Systems), M. Rose (First Virtual Holdings), and S. Waldbusser (International Network Services) ✨. It's dated April 1999 🌸.
Status of this Memo
so this part is giving "official notice" energy 💅 This document specifies an Internet standards track protocol for the Internet community, and it's literally asking for discussion and suggestions for improvements 🦋 If you want the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 📚 And distribution of this memo is unlimited 🌈
Copyright Notice
Copyright (C) The Internet Society (1999). All Rights Reserved. 🫶
Table of Contents
1 Introduction .....................................................3
1.1 A Note on Terminology ..........................................3
2 Definitions ......................................................3
2.1 The OBJECT-GROUP macro .........................................3
2.2 The NOTIFICATION-GROUP macro ...................................4
2.3 The MODULE-COMPLIANCE macro ....................................5
2.4 The AGENT-CAPABILITIES macro ...................................7
3 Mapping of the OBJECT-GROUP macro ...............................10
3.1 Mapping of the OBJECTS clause .................................10
3.2 Mapping of the STATUS clause ..................................11
3.3 Mapping of the DESCRIPTION clause .............................11
3.4 Mapping of the REFERENCE clause ...............................11
3.5 Mapping of the OBJECT-GROUP value .............................11
3.6 Usage Example .................................................12
4 Mapping of the NOTIFICATION-GROUP macro .........................12
4.1 Mapping of the NOTIFICATIONS clause ...........................12
4.2 Mapping of the STATUS clause ..................................13
4.3 Mapping of the DESCRIPTION clause .............................13
4.4 Mapping of the REFERENCE clause ...............................13
4.5 Mapping of the NOTIFICATION-GROUP value .......................13
4.6 Usage Example .................................................13
5 Mapping of the MODULE-COMPLIANCE macro ..........................14
5.1 Mapping of the STATUS clause ..................................14
5.2 Mapping of the DESCRIPTION clause .............................14
5.3 Mapping of the REFERENCE clause ...............................15
5.4 Mapping of the MODULE clause ..................................15
5.4.1 Mapping of the MANDATORY-GROUPS clause ......................15
5.4.2 Mapping of the GROUP clause .................................15
5.4.3 Mapping of the OBJECT clause ................................16
5.4.3.1 Mapping of the SYNTAX clause ..............................16
5.4.3.2 Mapping of the WRITE-SYNTAX clause ........................16
5.4.3.3 Mapping of the MIN-ACCESS clause ..........................16
5.4.4 Mapping of the DESCRIPTION clause ...........................17
5.5 Mapping of the MODULE-COMPLIANCE value ........................17
5.6 Usage Example .................................................17
6 Mapping of the AGENT-CAPABILITIES macro .........................19
6.1 Mapping of the PRODUCT-RELEASE clause .........................19
6.2 Mapping of the STATUS clause ..................................19
6.3 Mapping of the DESCRIPTION clause .............................20
6.4 Mapping of the REFERENCE clause ...............................20
6.5 Mapping of the SUPPORTS clause ................................20
6.5.1 Mapping of the INCLUDES clause ..............................20
6.5.2 Mapping of the VARIATION clause .............................20
6.5.2.1 Mapping of the SYNTAX clause ..............................21
6.5.2.2 Mapping of the WRITE-SYNTAX clause ........................21
6.5.2.3 Mapping of the ACCESS clause ..............................21
6.5.2.4 Mapping of the CREATION-REQUIRES clause ...................22
6.5.2.5 Mapping of the DEFVAL clause ..............................22
6.5.2.6 Mapping of the DESCRIPTION clause .........................22
6.6 Mapping of the AGENT-CAPABILITIES value .......................22
6.7 Usage Example .................................................23
7 Extending an Information Module .................................25
7.1 Conformance Groups ............................................25
7.2 Compliance Definitions ........................................26
7.3 Capabilities Definitions ......................................26
8 Security Considerations .........................................27
9 Editors' Addresses ..............................................27
10 References .....................................................28
11 Full Copyright Statement .......................................291. Introduction ✨
okay so the big picture 🧚 Management information gets viewed as a collection of managed objects, living in a virtual information store called the Management Information Base (MIB) 💜 Related objects are grouped together into MIB modules. Those modules get written in an adapted subset of OSI's Abstract Syntax Notation One, ASN.1 (1988) [1], and that subset is called the Structure of Management Information (SMI) [2] 🍓
It can be really useful to define the acceptable lower-bounds of an implementation, along with the level of implementation that's actually achieved 🎯 That's the whole purpose of this doc: defining the notation used for those things 💅
1.1. A Note on Terminology
quick terminology moment 🌸 For clarity, the original Structure of Management Information, the one described in RFCs 1156 (STD 16), 1212 (STD 16), and RFC 1215, is called SMI version 1 (SMIv1) 🦋 The current version is called SMI version 2 (SMIv2) ✨
2. Definitions 👑
here's the actual ASN.1 module, so get ready for the vibes 🫶
SNMPv2-CONF DEFINITIONS ::= BEGIN
IMPORTS ObjectName, NotificationName, ObjectSyntax
FROM SNMPv2-SMI;
-- 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 [2]
Text ::= value(IA5String)
END
-- more definitions for conformance groups
NOTIFICATION-GROUP MACRO ::=
BEGIN
TYPE NOTATION ::=
NotificationsPart
"STATUS" Status
"DESCRIPTION" Text
ReferPart
VALUE NOTATION ::=
value(VALUE OBJECT IDENTIFIER)
NotificationsPart ::=
"NOTIFICATIONS" "{" Notifications "}"
Notifications ::=
Notification
| Notifications "," Notification
Notification ::=
value(NotificationName)
Status ::=
"current"
| "deprecated"
| "obsolete"
ReferPart ::=
"REFERENCE" Text
| empty
-- a character string as defined in [2]
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)
SyntaxPart
WriteSyntaxPart
AccessPart
"DESCRIPTION" Text
-- must be a refinement for object's SYNTAX clause
SyntaxPart ::= "SYNTAX" Syntax
| empty
-- must be a refinement for object's SYNTAX clause
WriteSyntaxPart ::= "WRITE-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 ::=
"MIN-ACCESS" Access
| empty
Access ::=
"not-accessible"
| "accessible-for-notify"
| "read-only"
| "read-write"
| "read-create"
-- a character string as defined in [2]
Text ::= value(IA5String)
END
-- definitions for capabilities statements
AGENT-CAPABILITIES MACRO ::=BEGIN
TYPE NOTATION ::=
"PRODUCT-RELEASE" Text
"STATUS" Status
"DESCRIPTION" Text
ReferPart
ModulePart
VALUE NOTATION ::=
value(VALUE OBJECT IDENTIFIER)
Status ::=
"current"
| "obsolete"
ReferPart ::=
"REFERENCE" Text
| empty
ModulePart ::=
Modules
| empty
Modules ::=
Module
| Modules Module
Module ::=
-- name of module --
"SUPPORTS" ModuleName
"INCLUDES" "{" Groups "}"
VariationPart
ModuleName ::=
-- identifier must start with uppercase letter
identifier ModuleIdentifier
ModuleIdentifier ::=
value(OBJECT IDENTIFIER)
| empty
Groups ::=
Group
| Groups "," Group
Group ::=
value(OBJECT IDENTIFIER)
VariationPart ::=
Variations
| empty
Variations ::=
Variation
| Variations Variation
Variation ::=
ObjectVariation
| NotificationVariation
NotificationVariation ::=
"VARIATION" value(NotificationName)
AccessPart
"DESCRIPTION" Text
ObjectVariation ::=
"VARIATION" value(ObjectName)
SyntaxPart
WriteSyntaxPart
AccessPart
CreationPart
DefValPart
"DESCRIPTION" Text
-- must be a refinement for object's SYNTAX clause
SyntaxPart ::= "SYNTAX" Syntax
| empty
WriteSyntaxPart ::= "WRITE-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 ::=
"ACCESS" Access
| empty
Access ::=
"not-implemented"
-- only "not-implemented" for notifications
| "accessible-for-notify"
| "read-only"
| "read-write"
| "read-create"
-- following is for backward-compatibility only
| "write-only"
CreationPart ::=
"CREATION-REQUIRES" "{" Cells "}"
| empty
Cells ::=
Cell
| Cells "," Cell
Cell ::=
value(ObjectName)
DefValPart ::= "DEFVAL" "{" Defvalue "}"
| empty
Defvalue ::= -- must be valid for the object's syntax
-- in this macro's SYNTAX clause, if present,
-- or if not, in object's OBJECT-TYPE macro
value(ObjectSyntax)
| "{" BitsValue "}"
BitsValue ::= BitNames
| empty
BitNames ::= BitName
| BitNames "," BitName
BitName ::= identifier
-- a character string as defined in [2]
Text ::= value(IA5String)
END
END3. Mapping of the OBJECT-GROUP macro ✨
okay so for conformance purposes it's so useful to bundle related managed objects together 🫶 The OBJECT-GROUP macro is the thing that lets you make each of those collections. Just so you know, the expansion of the OBJECT-GROUP macro conceptually happens during implementation, and not at run-time 💅
To "implement" an object, an agent must return a reasonably accurate value for management protocol retrieval operations. And if the object is writable, then when a management protocol set operation comes in, the agent must be able to reasonably influence the underlying managed entity 🔥 If an agent can't implement an object, the management protocol lets it return an exception or error, e.g., noSuchObject [4].
🚨 Under no circumstances shall an agent return a value for objects which it does not implement. It must always return the appropriate exception or error, as described in the protocol specification [4]. No exceptions, bestie 💀
Also, the OBJECT-GROUP macro itself gives zero conformance information 🙈 Instead, conformance info comes from including defined groups in a MODULE-COMPLIANCE macro. Main character energy for the groups, background character for the macro lol 🎀
3.1. Mapping of the OBJECTS clause
The OBJECTS clause, which must be present, is how you list each object inside the conformance group 🌸 Every object you list must be defined in the same information module where the OBJECT-GROUP macro shows up. It also must have a MAX-ACCESS clause value of "accessible-for-notify", "read-only", "read-write", or "read-create" ✨
It is required that every object defined in an information module with a MAX-ACCESS clause other than "not-accessible" be contained in at least one object group. This is giving "don't forget the new object" prevention 🦋 It stops that super common mistake where you add a new object to a module and then totally forget to put it in a group 😭
3.2. Mapping of the STATUS clause
The STATUS clause, which must be present, tells you whether this definition is current or historic 💜
The value "current" means the definition is current and valid 🌈 The value "obsolete" means the definition is obsolete, and the group should no longer be used for defining conformance. Then there's "deprecated" 👀 It also indicates an obsolete definition, but it still permits new/continued use of conformance definitions using this group. Lowkey confusing, but now you know 🧚
3.3. Mapping of the DESCRIPTION clause
The DESCRIPTION clause, which must be present, holds a textual definition of that group, plus a description of any relations to other groups 🍓 Heads up: generic compliance requirements should not be stated in this clause. Implementation relationships between this group and other groups, though, may be defined in this clause ✨
3.4. Mapping of the REFERENCE clause
The REFERENCE clause is optional, so it need not be present 🫶 It holds a textual cross-reference to some other document. That could be another information module that defines a related assignment, or some other document that gives extra info relevant to this definition 📚
3.5. Mapping of the OBJECT-GROUP value
The value of an invocation of the OBJECT-GROUP macro is the name of the group. That name is an OBJECT IDENTIFIER, an administratively assigned name 🎀
3.6. Usage Example
Okay, example time 🦋 The SNMP Group [3] is described like this:
snmpGroup OBJECT-GROUP
OBJECTS { snmpInPkts,
snmpInBadVersions,
snmpInASNParseErrs,
snmpBadOperations,
snmpSilentDrops,
snmpProxyDrops,
snmpEnableAuthenTraps }
STATUS current
DESCRIPTION
"A collection of objects providing basic instrumentation
and control of an agent."
::= { snmpMIBGroups 8 }According to this invocation, the conformance group named
{ snmpMIBGroups 8 }contains 7 objects 🌟 Iconic, and that's the whole vibe 💅
4. Mapping of the NOTIFICATION-GROUP macro 🔔
For conformance purposes, it's useful to define a collection of notifications, and the NOTIFICATION-GROUP macro is what does that job 💖 Same deal as before: the expansion of the NOTIFICATION-GROUP macro conceptually happens during implementation and not during run-time 🧚
4.1. Mapping of the NOTIFICATIONS clause
The NOTIFICATIONS clause, which must be present, is used to specify each notification contained in the conformance group 🔥 Each one you list must be defined in the same information module where the NOTIFICATION-GROUP macro appears.
It is required that every notification defined in an information module be contained in at least one notification group. No notification left behind, periodt 🫶
4.2. Mapping of the STATUS clause
The STATUS clause, which must be present, indicates whether this definition is current or historic 💜
The value "current" means the definition is current and valid ✨ The value "obsolete" means the definition is obsolete, and this group should no longer be used for defining conformance. "deprecated" still means obsolete too, but it permits new/continued use of conformance definitions using this group 🌸
4.3. Mapping of the DESCRIPTION clause
The DESCRIPTION clause, which must be present, contains a textual definition of the group, along with a description of any relations to other groups 🍓 Generic compliance requirements should not be stated in this clause. Implementation relationships between this group and other groups may be defined here, though 🦋
4.4. Mapping of the REFERENCE clause
The REFERENCE clause is optional (need not be present) 🎀 It contains a textual cross-reference to some other document, either another information module which defines a related assignment, or some other document which provides additional information relevant to this definition 📖
4.5. Mapping of the NOTIFICATION-GROUP value
The value of an invocation of the NOTIFICATION-GROUP macro is the name of the group. That's an OBJECT IDENTIFIER, an administratively assigned name 🌈
4.6. Usage Example
The SNMP Basic Notifications Group [3] is described like this 🔔
snmpBasicNotificationsGroup NOTIFICATION-GROUP
NOTIFICATIONS { coldStart, authenticationFailure }
STATUS current
DESCRIPTION
"The two notifications which an agent is required to
implement."
::= { snmpMIBGroups 7 }According to this invocation, the conformance group named
{ snmpMIBGroups 7 }contains 2 notifications 💅 Two notifications, very small group, very big energy ✨
5. Mapping of the MODULE-COMPLIANCE macro 👑
The MODULE-COMPLIANCE macro is used to convey a minimum set of requirements for implementing one or more MIB modules 🫶 Once again, its expansion conceptually happens during implementation and not during run-time 💖
A requirement on all "standard" MIB modules is that a corresponding MODULE-COMPLIANCE specification is also defined, either in the same information module or in a companion information module. So every standard MIB gets its own compliance buddy 🦋
5.1. Mapping of the STATUS clause
The STATUS clause, which must be present, indicates whether this definition is current or historic 💜
The value "current" means the definition is current and valid 🌈 The value "obsolete" means the definition is obsolete, and this MODULE-COMPLIANCE specification no longer specifies a valid definition of conformance. "deprecated" also indicates an obsolete definition, but it permits new/continued use of the MODULE-COMPLIANCE specification 🧚
5.2. Mapping of the DESCRIPTION clause
The DESCRIPTION clause, which must be present, contains a textual definition of this compliance statement 🍓 It should embody any information which would otherwise be communicated in any ASN.1 commentary annotations associated with the statement. So put the commentary in here, not in the margins 📝
5.3. Mapping of the REFERENCE clause
The REFERENCE clause is optional (need not be present) 🎀 It contains a textual cross-reference to some other document, either another information module which defines a related assignment, or some other document which provides additional information relevant to this definition ✨
5.4. Mapping of the MODULE clause ✨
okay so the MODULE clause is a must-have 💅 It gets used over and over to name each MIB module that you're setting compliance requirements for. You name a module by its module name, and you can optionally add its OBJECT IDENTIFIER too 🦋 bestie, if the MODULE-COMPLIANCE invocation is sitting inside a MIB module, you can leave out the module name, and it just means the MIB module it's wrapped in 🎀
5.4.1. Mapping of the MANDATORY-GROUPS clause
the MANDATORY-GROUPS clause doesn't have to show up, but if it does, it names one or more object or notification groups in the matching MIB module that are unconditionally mandatory to implement 🔥 this is the big one, so listen up: if an agent claims compliance with the MIB module, it must implement every single object and notification in each conformance group that's listed. no skipping, no "close enough" 😭 so if an agent gives back a noSuchObject exception for any object in a mandatory conformance group, in every possible MIB view, in response to a management protocol get operation [4], or if it can't generate every notification in a listed conformance group under the right circumstances, then that agent is not a conformant implementation of the MIB module. no cap, it's a hard no 💀
5.4.2. Mapping of the GROUP clause
the GROUP clause is optional too (need not be present), and you can use it again and again to name each object and notification group that's conditionally mandatory for compliance with the MIB module ✨ it can also name groups that are unconditionally optional, which is a fun little twist 🌈 a group named in a GROUP clause has to be absent from the matching MANDATORY-GROUPS clause, so don't double-dip 🙈
conditionally mandatory groups are the ones that only become mandatory if a particular protocol is implemented, or if some other group is implemented. the GROUP clause's DESCRIPTION is where you spell out the exact conditions that make the group conditionally mandatory 🫶
and if a group isn't named in either a MANDATORY-GROUPS clause or a GROUP clause, it's unconditionally optional for compliance with the MIB module. easy peasy 🧚
5.4.3. Mapping of the OBJECT clause
the OBJECT clause doesn't have to be there, but you can use it over and over to call out each MIB object that has a refined requirement for compliance, compared with what the MIB module definition says 💖 that MIB object has to be present in one of the conformance groups named in the matching MANDATORY-GROUPS clause or GROUP clauses, no exceptions 👑
by definition, every object named in an OBJECT clause comes after a MODULE clause that names the information module where that object is defined. so using an IMPORTS statement to say where the objects are imported from is redundant, and it's not required in an information module. it's giving "already handled" energy 💅
5.4.3.1. Mapping of the SYNTAX clause
the SYNTAX clause is optional, and it gives a refined SYNTAX for the object named in the matching OBJECT clause ✨ heads up: if this clause and a WRITE-SYNTAX clause are both there, this one only applies when instances of that object are read 👀
for more on refined syntax, check out Section 9 of [2] 🦋
5.4.3.2. Mapping of the WRITE-SYNTAX clause
the WRITE-SYNTAX clause is also optional. it gives a refined SYNTAX for the object named in the matching OBJECT clause, but only when instances of that object are written 🍓
for more on refined syntax, see Section 9 of [2] 🌸
5.4.3.3. Mapping of the MIN-ACCESS clause
the MIN-ACCESS clause is optional too, and it sets the minimal level of access for the object named in the matching OBJECT clause 🔥 if it's absent, the minimal access is the same as the maximal level from the matching OBJECT-TYPE macro invocation. if it is present, it must not give a greater level of access than the OBJECT-TYPE invocation does. no sneaking extra access in, bestie 🙅♀️
some objects have their access level locked in by their syntax, so you can't really negotiate it 😤 these include conceptual tables and rows, auxiliary objects, and objects with the syntax of Counter32 or Counter64 (and possibly some textual conventions too). for those objects, a MIN-ACCESS clause should not be present 💀
an implementation is compliant when the access level it provides is greater than or equal to the minimal level in the MODULE-COMPLIANCE macro, and less than or equal to the maximal level in the OBJECT-TYPE macro ✨ that's the sweet spot 🎀
5.4.4. Mapping of the DESCRIPTION clause
the DESCRIPTION clause must be present for each use of the GROUP or OBJECT clause 🫶 for an OBJECT clause, it holds a textual description of the refined compliance requirement. for a GROUP clause, it holds a textual description of the conditions under which the group is conditionally mandatory or unconditionally optional 💜
5.5. Mapping of the MODULE-COMPLIANCE value ✨
the value of a MODULE-COMPLIANCE macro invocation is an OBJECT IDENTIFIER, so it's a real, identifiable value you can use to point at the compliance statement that invocation contains 🧚 it can be used authoritatively for that purpose, which is so iconic 🌈
5.6. Usage Example 💅
okay, here's a hypothetical XYZv2-MIB compliance statement to vibe with 🎀 the compliance statement in the (hypothetical) XYZv2-MIB might look like this:
xyzMIBCompliance MODULE-COMPLIANCE
STATUS current
DESCRIPTION
"The compliance statement for XYZv2 entities which
implement the XYZv2 MIB."
MODULE -- compliance to the containing MIB module
MANDATORY-GROUPS { xyzSystemGroup,
xyzStatsGroup, xyzTrapGroup,
xyzSetGroup,
xyzBasicNotificationsGroup }
GROUP xyzV1Group
DESCRIPTION
"The xyzV1 group is mandatory only for those
XYZv2 entities which also implement XYZv1."
::= { xyzMIBCompliances 1 }so based on this invocation, if a system wants to claim alignment with the compliance statement named
{ xyzMIBCompliances 1 }it has to implement the XYZv2-MIB's xyzSystemGroup, xyzStatsGroup, xyzTrapGroup, and xyzSetGroup object conformance groups, plus the xyzBasicNotificationsGroup notifications group 🔥 and if the XYZv2 entity also implements XYZv1, then it must support the XYZv1Group group too, if it wants to claim compliance 👑
6. Mapping of the AGENT-CAPABILITIES macro 🧚
the AGENT-CAPABILITIES macro is used to convey a set of capabilities present in an agent ✨ it should be noted that expanding the AGENT-CAPABILITIES macro is something that conceptually happens during implementation, not at run-time 🎀
when a MIB module is written, it gets divided into units of conformance called groups 🦋 if an agent claims to implement a group, then it must implement every single object, or every single notification, within that group. of course, for whatever reason, an agent might only implement some of the groups in a MIB module, and that's valid 🌸 also, the definition of some MIB objects and notifications leaves some aspects up to the implementor's discretion 💅
practical experience has shown that there's a real need to describe an agent's capabilities concisely, with respect to one or more MIB modules 💖 the AGENT-CAPABILITIES macro lets an agent implementor describe the precise level of support the agent claims for a MIB group, and bind that description to the value of an instance of sysORID [3] 🌈 some objects may have restricted or augmented syntax, or restricted or augmented access levels, so this is where that gets spelled out 🍓
if the AGENT-CAPABILITIES invocation is handed to a management-station implementor, they can build management applications that optimize themselves when talking to a particular agent 🫶 for example, the management station can keep a database of these invocations. when it interacts with an agent, it retrieves the values of all instances of sysORID [3] from that agent, then checks the database for each entry matching one of the retrieved sysORID values. with those entries in hand, the management application can optimize its behavior accordingly 🧠✨
note that the AGENT-CAPABILITIES macro specifies refinements or variations with respect to the OBJECT-TYPE and NOTIFICATION-TYPE macros in MIB modules, NOT with respect to the MODULE-COMPLIANCE macros in compliance statements 🙈 that distinction matters!
6.1. Mapping of the PRODUCT-RELEASE clause
the PRODUCT-RELEASE clause must be present, and it holds a textual description of the product release that includes this set of capabilities 🎀
6.2. Mapping of the STATUS clause
the STATUS clause must be present, and it shows whether this definition is current or historic 🦋
the value "current" means the definition is current and valid ✨ the value "obsolete" means the definition is obsolete, and this capabilities statement is no longer in use 💀
6.3. Mapping of the DESCRIPTION clause
the DESCRIPTION clause must be present, and it holds a textual description of this set of capabilities 💖
6.4. Mapping of the REFERENCE clause
the REFERENCE clause doesn't have to show up, but if it does, it holds a textual cross-reference to some other document. that document could be another information module defining a related assignment, or some other document that gives extra info relevant to this definition 🌸
6.5. Mapping of the SUPPORTS clause
the SUPPORTS clause is optional, and you can use it repeatedly to name each MIB module the agent claims a complete or partial implementation of 🧚 every MIB module gets named by its module name, and optionally by its associated OBJECT IDENTIFIER (as registered by the MODULE-IDENTITY macro, see [2]) too 🫶
6.5.1. Mapping of the INCLUDES clause
the INCLUDES clause must follow each and every use of the SUPPORTS clause ✨ it names each MIB group associated with that SUPPORTS clause which the agent claims to implement 🔥
6.5.2. Mapping of the VARIATION clause
the VARIATION clause doesn't have to be present, and you can use it repeatedly to name each object or notification the agent implements in some variant or refined fashion, compared with the matching OBJECT-TYPE or NOTIFICATION-TYPE macro invocation 🌈
note that the variation concept is meant for generic implementation restrictions. for example, if the variation for an object depends on the values of other objects, then that should be noted in the appropriate DESCRIPTION clause 💅
by definition, every object named in a VARIATION clause comes after a SUPPORTS clause that names the information module where that object is defined. so using an IMPORTS statement to say where those objects are imported from is redundant, and it's not required in an information module 💜
6.5.2.1. Mapping of the SYNTAX clause 🎀
okay so the SYNTAX clause is totally optional (it need not be present 🙃), and its whole job is to give a refined SYNTAX for the object named in the matching VARIATION clause. 💅 bestie, if this clause and a WRITE-SYNTAX clause are BOTH there, then this one only applies when instances of that object get read. the write side has its own vibe ✨
Go check Section 9 of [2] if you want the full scoop on refined syntax, it's giving deep dive 🦋
ngl this part is spicy: for enumerated INTEGERs and the BITS construct, updating a MIB module can mean adding enumerations and/or changing the labels of existing ones (see Section 10.2 of [2]) 🌈. That can cause problems for an AGENT-CAPABILITIES macro that was written against the old revision of the MIB module 💀. One way to dodge that drama is to explicitly list ALL the objects with an enumerated syntax in a VARIATION clause, even when every enumeration is supported right now 🫶
6.5.2.2. Mapping of the WRITE-SYNTAX clause 🌸
The WRITE-SYNTAX clause is also optional (need not be present) 💖 and it gives a refined SYNTAX for the object named in the correspondent VARIATION clause, but this time specifically when instances of that object get written 🧚. Same deal: Section 9 of [2] has the details on refined syntax 📚✨
6.5.2.3. Mapping of the ACCESS clause 👑
The ACCESS clause is optional too (need not be present) 🍓. It's how you say the agent gives LESS than the maximal level of access to the object or notification named in the VARIATION clause 🙈
The only value that applies to notifications is "not-implemented" 🔥
"not-implemented" means the agent does NOT implement the object or notification 😭. In the ordering of possible values, it's equal to "not-accessible" 💅
"write-only" is only here for backward compatibility 🕰️, so it SHALL NOT be used for newly-defined object types 🚫. In the ordering of possible values, "write-only" is less than "not-accessible" ✨
6.5.2.4. Mapping of the CREATION-REQUIRES clause 🦋
The CREATION-REQUIRES clause is optional (need not be present) 🎀. It names the columnar objects of a conceptual row that MUST be explicitly assigned values, via a management protocol set operation, BEFORE the agent lets the status column instance of that row be set to `active' ✨. (Go peep the definition of RowStatus [5] for more 💜.)
If the conceptual row does NOT have a status column (because the objects were defined using the mechanisms in [6,7]) 🙃, then the CREATION-REQUIRES clause (again, optional) names the columnar objects of a conceptual row that MUST be explicitly assigned values, via a management protocol set operation, BEFORE the agent will create new instances of objects in that row 🧁
This clause MUST NOT be present unless the object named in the correspondent VARIATION clause is a conceptual row, i.e. has a syntax that resolves to a SEQUENCE containing columnar objects 🌈. The objects named in the value of this clause USUALLY refer to columnar objects in that row 🌸. HOWEVER, objects unrelated to the conceptual row MAY also be specified 🦄
All objects named in the CREATION-REQUIRES clause for a conceptual row, which are columnar objects of that row, MUST have an access level of "read-create" 🔐. No exceptions, bestie 💅
6.5.2.5. Mapping of the DEFVAL clause 🍭
The DEFVAL clause is optional (need not be present) 🌷. It gives an alternate DEFVAL value for the object named in the correspondent VARIATION clause 🎀. The semantics are IDENTICAL to the OBJECT-TYPE macro's DEFVAL clause 💖
6.5.2.6. Mapping of the DESCRIPTION clause 📝
The DESCRIPTION clause MUST be present for each use of the VARIATION clause 🙌. It holds a textual description of the variant or refined implementation of the object or notification ✨
6.6. Mapping of the AGENT-CAPABILITIES value 🦋
The value of an AGENT-CAPABILITIES macro invocation is an OBJECT IDENTIFIER 🧚, and it names the value of sysORID [3] for which this capabilities statement is valid 💜. Main character energy 👑
6.7. Usage Example 🎀
Okay, here's the example, bestie 📖✨
exampleAgent AGENT-CAPABILITIES
PRODUCT-RELEASE "ACME Agent release 1.1 for 4BSD."
STATUS current
DESCRIPTION "ACME agent for 4BSD."
SUPPORTS SNMPv2-MIB
INCLUDES { systemGroup, snmpGroup, snmpSetGroup,
snmpBasicNotificationsGroup }
VARIATION coldStart
DESCRIPTION "A coldStart trap is generated on all
reboots."
SUPPORTS IF-MIB
INCLUDES { ifGeneralGroup, ifPacketGroup }
VARIATION ifAdminStatus
SYNTAX INTEGER { up(1), down(2) }
DESCRIPTION "Unable to set test mode on 4BSD."
VARIATION ifOperStatus
SYNTAX INTEGER { up(1), down(2) }
DESCRIPTION "Information limited on 4BSD."
SUPPORTS IP-MIB
INCLUDES { ipGroup, icmpGroup }
VARIATION ipDefaultTTL
SYNTAX INTEGER (255..255)
DESCRIPTION "Hard-wired on 4BSD."
VARIATION ipInAddrErrors
ACCESS not-implemented
DESCRIPTION "Information not available on 4BSD."
VARIATION ipNetToMediaEntry
CREATION-REQUIRES { ipNetToMediaPhysAddress }
DESCRIPTION "Address mappings on 4BSD require
both protocol and media addresses."
SUPPORTS TCP-MIB
INCLUDES { tcpGroup }
VARIATION tcpConnState
ACCESS read-only
DESCRIPTION "Unable to set this on 4BSD."
SUPPORTS UDP-MIB
INCLUDES { udpGroup }
SUPPORTS EVAL-MIB
INCLUDES { functionsGroup, expressionsGroup }
VARIATION exprEntry
CREATION-REQUIRES { evalString, evalStatus }
DESCRIPTION "Conceptual row creation is supported."
::= { acmeAgents 1 }So according to this invocation 🫧, an agent with a sysORID value of
{ acmeAgents 1 }supports objects defined in SIX MIB modules 🤯
From SNMPv2-MIB, FIVE conformance groups are supported 🖐️
From IF-MIB, the ifGeneralGroup and ifPacketGroup groups are supported 🍒. HOWEVER, the objects ifAdminStatus and ifOperStatus have a restricted syntax 🙃
From IP-MIB, ALL objects in the ipGroup and icmpGroup are supported EXCEPT ipInAddrErrors 🙅♀️, while ipDefaultTTL has a restricted range 🌡️. And when creating a new instance in the ipNetToMediaTable, the set-request MUST create an instance of ipNetToMediaPhysAddress 💅
From TCP-MIB, the tcpGroup is supported EXCEPT that tcpConnState is available ONLY for reading 📖
From UDP-MIB, the udpGroup is fully supported 🥰
From the EVAL-MIB, ALL the objects in the functionsGroup and expressionsGroup conformance groups are supported, WITHOUT variation 🌟. Plus, creating new instances in the expr table is supported, and it REQUIRES both evalString and evalStatus to be assigned a value 🧠
- Extending an Information Module 🌱
As experience is gained with a published information module, it MAY be desirable to revise that information module 🌷
Section 10 of [2] defines the rules for extending an information module 📜. The rest of this section defines how conformance groups, compliance statements, and capabilities statements MAY be extended 🦋
7.1. Conformance Groups 🧩
It MAY be desirable to revise the definition of a conformance group (an OBJECT-GROUP or a NOTIFICATION-GROUP) after experience is gained with it 💭. However, conformance groups can be referenced by compliance and/or capabilities definitions 🔗. So a change to a conformance group is NOT ALLOWED if it has the potential to make a reference to the group's original definition different from a reference to the updated definition 🚫. Such changes can ONLY be accommodated by defining a NEW conformance group with a new descriptor and a new OBJECT IDENTIFIER value 🆕
The following revisions are allowed:
(1) 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 📝✨
(2) A REFERENCE clause MAY be added or updated 🎀
(3) Clarifications and additional information MAY be included in the DESCRIPTION clause 💖
(4) Any editorial change 💅
It is NOT RECOMMENDED to change the STATUS value of a conformance group when the status of a member of the group is changed 🙅♀️. Hmm, wait, let me say that properly: it is not necessary to change the STATUS value of a conformance group when the status of a member of the group is changed 🫶
7.2. Compliance Definitions 📋
It MAY be desirable to revise the definition of a compliance definition (MODULE-COMPLIANCE) after experience is gained with it 🌸. However, changes are NOT ALLOWED if they cause the requirements specified by the original definition to be different from the requirements of the updated definition 🛑. Such changes can ONLY be accommodated by defining a NEW compliance definition with a new descriptor and a new OBJECT IDENTIFIER value 🆕
The following revisions are allowed:
(1) 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 📝
(2) A REFERENCE clause MAY be added or updated 🎀
(3) Clarifications and additional information MAY be included in the DESCRIPTION clause(s) 💖
(4) Any editorial change 💅
It is not necessary to change the STATUS value of a compliance definition due to a change in the STATUS value of a definition it references 🦋
7.3. Capabilities Definitions 🧠
It MAY be desirable to revise the definition of a capabilities definition (AGENT-CAPABILITIES) after experience is gained with it 🌷. However, changes are NOT ALLOWED if they cause the capabilities specified by the original specification to be different from the capabilities of the updated specification 🛑. Such changes can ONLY be accommodated by defining a NEW capabilities definition with a new descriptor and a new OBJECT IDENTIFIER value 🆕
The following revisions are allowed:
(1) A STATUS clause value of "current" MAY be revised as "obsolete". When making such a change, the DESCRIPTION clause SHOULD be updated to explain the rationale 📝
(2) A REFERENCE clause MAY be added or updated 🎀
(3) Clarifications and additional information MAY be included in the DESCRIPTION clause(s) 💖
(4) Any editorial change 💅
It is not necessary to change the STATUS value of a capabilities definition due to a change in the STATUS value of a definition it references 🫶
- Security Considerations 🔐
This document defines the means to define conformance requirements for implementing on documents describing management information 📖. This method of defining conformance requirements has NO security impact on the Internet 🌐✨
9. Editors' Addresses ✨
okay bestie, here are the three editors who made this whole thing happen 💅 Keith, David, and Juergen, with all their contact details exactly as they were written:
Keith McCloghrie
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
Phone: +1 408 526 5260
EMail: kzm@cisco.com
David Perkins
SNMPinfo
3763 Benton Street
Santa Clara, CA 95051
USA
Phone: +1 408 221-8702
Email: dperkins@snmpinfo.com
Juergen Schoenwaelder
TU Braunschweig
Bueltenweg 74/75
38106 Braunschweig
Germany
Phone: +49 531 391-3283
EMail: schoenw@ibr.cs.tu-bs.de10. References 📚
these are the sources the spec leans on, and yes, they're all here, every author and date included 🫶
[1] Information processing systems - Open Systems Interconnection -
Specification of Abstract Syntax Notation One (ASN.1),
International Organization for Standardization. International
Standard 8824, (December, 1987).
[2] 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.
[3] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and
S. Waldbusser, "Management Information Base for Version 2 of the
Simple Network Management Protocol (SNMPv2)", RFC 1907, January
1996.
[4] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and
S. Waldbusser, "Protocol Operations for Version 2 of the Simple
Network Management Protocol (SNMPv2)", RFC 1905, January 1996.
[5] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M.
and S. Waldbusser, "Textual Conventions for SMIv2", STD 58,
RFC 2579, April 1999.
[6] Rose, M. and K. McCloghrie, "Structure and Identification of
Management Information for TCP/IP-based internets", STD 16, RFC
1155, May 1990.
[7] Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD 16, RFC
1212, March 1991.11. Full Copyright Statement ⚖️🎀
okay, the legal part, but make it cute 🙈 the Internet Society owns the copyright here (1999), and everything below is the official fine print, no edits to the meaning ✨
Copies of this document and translations of it can be shared with other people. You can also write derivative works that comment on or explain it, or that help people implement it, and publish and distribute those however you like, in whole or in part, with no restrictions, as long as the copyright notice and this paragraph stay on every copy and derivative work. The document itself can't be changed in any way, though. That includes removing the copyright notice or the references to the Internet Society or other Internet organizations. The exceptions are when you need it to develop Internet standards (then the copyright procedures in the Internet Standards process have to be followed), or when you're translating it into a language other than English.
The permissions above last forever, and the Internet Society or its successors or assigns can't take them back 💖
This document and the information in it are provided "AS IS", 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. 💀
📦 where this page comes from
- ietf: rfc2580 1999-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms