The AGENT-CAPABILITIES macro is used to convey a set of capabilities present in a SNMPv2 entity acting in an agent role. It should be noted that the expansion of the AGENT-CAPABILITIES macro is something which conceptually happens during implementation and not during time.
When a MIB module is written, it is divided into units of conformance termed groups. If a SNMPv2 entity acting in an agent role claims to implement a group, then it must implement each and every object within that group. Of course, for whatever reason, a SNMPv2 entity might implement only a subset of the groups within a MIB module. In addition, the definition of some MIB objects leave some aspects of
the definition to the discretion of an implementor.
Practical experience has demonstrated a need for concisely describing the capabilities of an agent with respect to one or more MIB modules.
The AGENT-CAPABILITIES macro allows an agent implementor to describe the precise level of support which an agent claims in regards to a MIB group, and to bind that description to the value of an instance of sysORID [3]. In particular, some objects may have restricted or augmented syntax or access-levels.
If the AGENT-CAPABILITIES invocation is given to a management-station implementor, then that implementor can build management applications which optimize themselves when communicating with a particular agent.
For example, the management-station can maintain a database of these invocations. When a management-station interacts with an agent, it retrieves from the agent the values of all instances of sysORID [3].
Based on this, it consults the database to locate each entry matching one of the retrieved values of sysORID. Using the located entries, the management application can now optimize its behavior accordingly.
Note that the AGENT-CAPABILITIES macro specifies refinements or variations with respect to OBJECT-TYPE and NOTIFICATION-TYPE macros in MIB modules, NOT with respect to MODULE-COMPLIANCE macros in compliance statements.
6.1. Mapping of the PRODUCT-RELEASE clause
The PRODUCT-RELEASE clause, which must be present, contains a textual description of the product release which includes this set of
capabilities.
6.2. Mapping of the STATUS clause
The STATUS clause, which must be present, indicates whether this definition is current ("current") or historic ("obsolete").
6.3. Mapping of the DESCRIPTION clause
The DESCRIPTION clause, which must be present, contains a textual description of this set of capabilities.
6.4. Mapping of the REFERENCE clause
The REFERENCE clause, which need not be present, contains a textual cross-reference to a capability statement defined in some other information module.
6.5. Mapping of the SUPPORTS clause
The SUPPORTS clause, which need not be present, is repeatedly used to name each MIB module for which the agent claims a complete or partial implementation. Each MIB module is named by its module name, and optionally, by its associated OBJECT IDENTIFIER as well.
6.5.1. Mapping of the INCLUDES clause
The INCLUDES clause, which must be present for each use of the SUPPORTS clause, is used to name each MIB group associated with the SUPPORTS clause, which the agent claims to implement.
6.5.2. Mapping of the VARIATION clause
The VARIATION clause, which need not be present, is repeatedly used to name each object or notification which the agent implements in some variant or refined fashion with respect to the correspondent invocation of the OBJECT-TYPE or NOTIFICATION-TYPE macro.
Note that the variation concept is meant for generic implementation restrictions, e.g., if the variation for an object depends on the values of other objects, then this should be noted in the appropriate DESCRIPTION clause.
By definition, each object specified in a VARIATION clause follows a SUPPORTS clause which names the information module in which that object is defined. Therefore, the use of an IMPORTS statement, to specify from where such objects are imported, is redundant and is not required in an information module.
6.5.2.1. Mapping of the SYNTAX clause
The SYNTAX clause, which need not be present, is used to provide a refined SYNTAX for the object named in the correspondent VARIATION clause. Note that if this clause and a WRITE-SYNTAX clause are both present, then this clause only applies when instances of the object named in the correspondent VARIATION clause are read.
Consult Section 9 of [2] for more information on refined syntax.
6.5.2.2. Mapping of the WRITE-SYNTAX clause
The WRITE-SYNTAX clause, which need not be present, is used to provide a refined SYNTAX for the object named in the correspondent VARIATION clause when instances of that object are written.
Consult Section 9 of [2] for more information on refined syntax.
6.5.2.3. Mapping of the ACCESS clause
The ACCESS clause, which need not be present, is used to indicate the agent provides less than the maximal level of access to the object or notification named in the correspondent VARIATION clause.
The only value applicable to notifications is "not-implemented".
The value "not-implemented" indicates the agent does not implement the object or notification, and in the ordering of possible values is equivalent to "not-accessible".
The value "write-only" is provided solely for backward compatibility, and shall not be used for newly-defined object types. In the
ordering of possible values, "write-only" is less than accessible".
6.5.2.4. Mapping of the CREATION-REQUIRES clause
The CREATION-REQUIRES clause, which need not be present, is used to name the columnar objects of a conceptual row to which values must be explicitly assigned, by a management protocol set operation, before the agent will allow the instance of the status column of that row to be set to ‘active’. (Consult the definition of RowStatus [5].)
If the conceptual row does not have a status column (i.e., the
objects corresponding to the conceptual table were defined using the mechanisms in [6,7]), then the CREATION-REQUIRES clause, which need not be present, is used to name the columnar objects of a conceptual row to which values must be explicitly assigned, by a management protocol set operation, before the agent will create new instances of objects in that row.
This clause must not present unless the object named in the correspondent VARIATION clause is a conceptual row, i.e., has a
syntax which resolves to a SEQUENCE containing columnar objects. The objects named in the value of this clause usually will refer to
columnar objects in that row. However, objects unrelated to the conceptual row may also be specified.
All objects which are named in the CREATION-REQUIRES clause for a conceptual row, and which are columnar objects of that row, must have an access level of "read-create".
6.5.2.5. Mapping of the DEFVAL clause
The DEFVAL clause, which need not be present, is used to provide a refined DEFVAL value for the object named in the correspondent
VARIATION clause. The semantics of this value are identical to those of the OBJECT-TYPE macro’s DEFVAL clause.
6.5.2.6. Mapping of the DESCRIPTION clause
The DESCRIPTION clause, which must be present for each use of the VARIATION clause, contains 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 invocation of the AGENT-CAPABILITIES macro is an OBJECT IDENTIFIER, which names the value of sysORID [3] for which this capabilities statement is valid.
6.7. Usage Example
Consider how a capabilities statement for an agent might be described:
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 }
DESCRIPTION "Conceptual row creation supported"
::= { acmeAgents 1 }
According to this invocation, an agent with a sysORID value of { acmeAgents 1 }
supports 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
request must create an instance of atPhysAddress.
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 contained in the functionsGroup and expressionsGroup conformance groups are supported, without
variation. In addition, creation of new instances in the expr table is supported.