Request for Comments: 2741 Compaq Computer Corporation
Obsoletes: 2257 B. Wijnen
Category: Standards Track T.J. Watson Research Center, IBM Corp.
M. Ellison, Ed.
Ellison Software Consulting, Inc.
D. Francisco. Ed.
Cisco Systems, Inc.
January 2000
Agent Extensibility (AgentX) Protocol
Version 1
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2000). All Rights Reserved.
Abstract
This memo defines a standardized framework for extensible SNMP
agents. It defines processing entities called master agents and
subagents, a protocol (AgentX) used to communicate between them, and
the elements of procedure by which the extensible agent processes
SNMP protocol messages. This memo obsoletes RFC2257.
Table of Contents
1. Introduction.....................................................4
2. The SNMP Management Framework....................................4
2.1. A Note on Terminology........................................5
3. Extending the MIB................................................5
3.1. Motivation for AgentX........................................6
4. AgentX Framework.................................................6
4.1. AgentX Roles.................................................7
4.2. Applicability................................................8
4.3. Design Features of AgentX....................................9
4.4. Non-Goals...................................................10
5. AgentX Encodings................................................11
5.1. Object Identifier...........................................11
5.2. SearchRange.................................................13
5.3. Octet String................................................14
5.4. Value Representation........................................15
6. Protocol Definitions............................................17
6.1. AgentX PDU Header...........................................17
6.1.1. Context.................................................20
6.2. AgentX PDUs.................................................20
6.2.1. The agentx-Open-PDU.....................................20
6.2.2. The agentx-Close-PDU....................................22
6.2.3. The agentx-Register-PDU.................................23
6.2.4. The agentx-Unregister-PDU...............................27
6.2.5. The agentx-Get-PDU......................................29
6.2.6. The agentx-GetNext-PDU..................................30
6.2.7. The agentx-GetBulk-PDU..................................32
6.2.8. The agentx-TestSet-PDU..................................34
6.2.9. The agentx-CommitSet, -UndoSet, -CleanupSet PDUs........35
6.2.10. The agentx-Notify-PDU..................................36
6.2.11. The agentx-Ping-PDU....................................37
6.2.12. The agentx-IndexAllocate-PDU...........................37
6.2.13. The agentx-IndexDeallocate-PDU.........................38
6.2.14. The agentx-AddAgentCaps-PDU............................39
6.2.15. The agentx-RemoveAgentCaps-PDU.........................41
6.2.16. The agentx-Response-PDU................................43
7. Elements of Procedure...........................................45
7.1. Processing AgentX Administrative Messages...................45
7.1.1. Processing the agentx-Open-PDU..........................46
7.1.2. Processing the agentx-IndexAllocate-PDU.................47
7.1.3. Processing the agentx-IndexDeallocate-PDU...............49
7.1.4. Processing the agentx-Register-PDU......................50
7.1.4.1. Handling Duplicate and Overlapping Subtrees.........50
7.1.4.2. Registering Stuff...................................51
7.1.4.2.1. Registration Priority...........................51
7.1.4.2.2. Index Allocation................................51
7.1.4.2.3. Examples........................................53
7.1.5. Processing the agentx-Unregister-PDU....................55
7.1.6. Processing the agentx-AddAgentCaps-PDU..................55
7.1.7. Processing the agentx-RemoveAgentCaps-PDU...............55
7.1.8. Processing the agentx-Close-PDU.........................56
7.1.9. Detecting Connection Loss...............................56
7.1.10. Processing the agentx-Notify-PDU.......................56
7.1.11. Processing the agentx-Ping-PDU.........................57
7.2. Processing Received SNMP Protocol Messages..................58
7.2.1. Dispatching AgentX PDUs.................................58
7.2.1.1. agentx-Get-PDU......................................61
7.2.1.2. agentx-GetNext-PDU..................................61
7.2.1.3. agentx-GetBulk-PDU..................................62
7.2.1.4. agentx-TestSet-PDU..................................63
7.2.1.5. Dispatch............................................64
7.2.2. Subagent Processing.....................................64
7.2.3. Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs65
7.2.3.1. Subagent Processing of the agentx-Get-PDU...........65
7.2.3.2. Subagent Processing of the agentx-GetNext-PDU.......66
7.2.3.3. Subagent Processing of the agentx-GetBulk-PDU.......66
7.2.4. Subagent Processing of agentx-TestSet, -CommitSet,
-UndoSet, -CleanupSet-PDUs..............................67
7.2.4.1. Subagent Processing of the agentx-TestSet-PDU.......68
7.2.4.2. Subagent Processing of the agentx-CommitSet-PDU.....69
7.2.4.3. Subagent Processing of the agentx-UndoSet-PDU.......69
7.2.4.4. Subagent Processing of the agentx-CleanupSet-PDU....70
7.2.5. Master Agent Processing of AgentX Responses.............70
7.2.5.1. Common Processing of All AgentX Response PDUs.......70
7.2.5.2. Processing of Responses to agentx-Get-PDUs..........70
7.2.5.3. Processing of Responses to agentx-GetNext-PDU and
agentx-GetBulk-PDU..................................71
7.2.5.4. Processing of Responses to agentx-TestSet-PDUs......72
7.2.5.5. Processing of Responses to agentx-CommitSet-PDUs....73
7.2.5.6. Processing of Responses to agentx-UndoSet-PDUs......74
7.2.6. Sending the SNMP Response-PDU...........................74
7.2.7. MIB Views...............................................74
7.3. State Transitions...........................................75
7.3.1. Set Transaction States..................................75
7.3.2. Transport Connection States.............................77
7.3.3. Session States..........................................78
8. Transport Mappings..............................................79
8.1. AgentX over TCP.............................................79
8.1.1. Well-known Values.......................................79
8.1.2. Operation...............................................79
8.2. AgentX over UNIX-domain Sockets.............................80
8.2.1. Well-known Values.......................................80
8.2.2. Operation...............................................80
9. Security Considerations.........................................81
10. Acknowledgements...............................................82
11. Authors' and Editor's Addresses................................83
12. References.....................................................84
13. Notices........................................................86
Appendix A. Changes relative to RFC2257 ..........................87
Full Copyright Statement ..........................................91
1. Introduction
This memo defines a standardized framework for extensible SNMP
agents. It defines processing entities called master agents and
subagents, a protocol (AgentX) used to communicate between them, and
the elements of procedure by which the extensible agent processes
SNMP protocol messages.
This memo obsoletes RFC2257. It is worth noting that most of the
changes are for the purpose of clarification. The only changes
affecting AgentX protocol messages on the wire are:
- The agentx-Notify-PDU and agentx-Close-PDU now generate an
agentx-Response-PDU
- Three new error codes are available: parseFailed(266),
requestDenied(267), and processingError(268)
Appendix A provides a detailed list of changes relative to RFC2257.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [27].
2. The SNMP Management Framework
The SNMP Management Framework presently consists of five major
components:
An overall architecture, described in RFC2571 [1].
Mechanisms for describing and naming objects and events for the
purpose of management. The first version of this Structure of
Management Information (SMI) is called SMIv1 and described in STD 16,
RFC1155 [2], STD 16, RFC1212 [3] and RFC1215 [4]. The second
version, called SMIv2, is described in STD 58, RFC2578 [5], STD 58,
RFC2579 [6] and STD 58, RFC2580 [7].
Message protocols for transferring management information. The first
version of the SNMP message protocol is called SNMPv1 and described
in STD 15, RFC1157 [8]. A second version of the SNMP message
protocol, which is not an Internet standards track protocol, is
called SNMPv2c and described in RFC1901 [9] and RFC1906 [10]. The
third version of the message protocol is called SNMPv3 and described
in RFC1906 [10], RFC2572 [11] and RFC2574 [12].
Protocol operations for accessing management information. The first
set of protocol operations and associated PDU formats is described in
STD 15, RFC1157 [8]. A second set of protocol operations and
associated PDU formats is described in RFC1905 [13].
A set of fundamental applications described in RFC2573 [14] and the
view-based access control mechanism described in RFC2575 [15].
A more detailed introduction to the current SNMP Management Framework
can be found in RFC2570 [16].
Managed objects are accessed via a virtual information store, termed
the Management Information Base or MIB. Objects in the MIB are
defined using the mechanisms defined in the SMI.
2.1. A Note on Terminology
The term "variable" refers to an instance of a non-aggregate object
type defined according to the conventions set forth in the SMIv2 (STD
58, RFC2578, [5]) or the textual conventions based on the SMIv2 (STD
58, RFC2579 [6]). The term "variable binding" normally refers to
the pairing of the name of a variable and its associated value.
However, if certain kinds of exceptional conditions occur during
processing of a retrieval request, a variable binding will pair a
name and an indication of that exception.
A variable-binding list is a simple list of variable bindings.
The name of a variable is an OBJECT IDENTIFIER, which is the
concatenation of the OBJECT IDENTIFIER of the corresponding object
type together with an OBJECT IDENTIFIER fragment identifying the
instance. The OBJECT IDENTIFIER of the corresponding object-type is
called the OBJECT IDENTIFIER prefix of the variable.
3. Extending the MIB
New MIB modules that extend the Internet-standard MIB are
continuously being defined by various IETF working groups. It is
also common for enterprises or individuals to create or extend
enterprise-specific or experimental MIBs.
As a result, managed devices are frequently complex collections of
manageable components that have been independently installed on a
managed node. Each component provides instrumentation for the
managed objects defined in the MIB module(s) it implements.
The SNMP framework does not describe how the set of managed objects
supported by a particular agent may be changed dynamically.
3.1. Motivation for AgentX
This very real need to dynamically extend the management objects
within a node has given rise to a variety of "extensible agents",
which typically comprise
- a "master" agent that is available on the standard transport
address and that accepts SNMP protocol messages
- a set of "subagents" that each contain management
instrumentation
- a protocol that operates between the master agent and
subagents, permitting subagents to "connect" to the master
agent, and the master agent to multiplex received SNMP protocol
messages amongst the subagents.
- a set of tools to aid subagent development, and a runtime (API)
environment that hides much of the protocol operation between a
subagent and the master agent.
The wide deployment of extensible SNMP agents, coupled with the lack
of Internet standards in this area, makes it difficult to field
SNMP-manageable applications. A vendor may have to support several
different subagent environments (APIs) in order to support different
target platforms.
It can also become quite cumbersome to configure subagents and
(possibly multiple) master agents on a particular managed node.
Specifying a standard protocol for agent extensibility (AgentX)
provides the technical foundation required to solve both of these
problems. Independently developed AgentX-capable master agents and
subagents will be able to interoperate at the protocol level.
Vendors can continue to differentiate their products in all other
respects.
4. AgentX Framework
Within the SNMP framework, a managed node contains a processing
entity, called an agent, which has access to management information.
Within the AgentX framework, an agent is further defined to consist
of:
- a single processing entity called the master agent, which sends
and receives SNMP protocol messages in an agent role (as
specified by the SNMP framework documents) but typically has
little or no direct access to management information.
- zero or more processing entities called subagents, which are
"shielded" from the SNMP protocol messages processed by the
master agent, but which have access to management information.
The master and subagent entities communicate via AgentX protocol
messages, as specified in this memo. Other interfaces (if any) on
these entities, and their associated protocols, are outside the scope
of this document. While some of the AgentX protocol messages appear
similar in syntax and semantics to the SNMP, bear in mind that AgentX
is not SNMP.
The internal operations of AgentX are invisible to an SNMP entity
operating in a manager role. From a manager's point of view, an
extensible agent behaves exactly as would a non-extensible
(monolithic) agent that has access to the same management
instrumentation.
This transparency to managers is a fundamental requirement of AgentX,
and is what differentiates AgentX subagents from SNMP proxy agents.
4.1. AgentX Roles
An entity acting in a master agent role performs the following
functions:
- Accepts AgentX session establishment requests from subagents.
- Accepts registration of MIB regions by subagents.
- Sends and accepts SNMP protocol messages on the agent's
specified transport addresses.
- Implements the agent role Elements of Procedure specified for
the administrative framework applicable to the SNMP protocol
message, except where they specify performing management
operations. (The application of MIB views, and the access
control policy for the managed node, are implemented by the
master agent.)
- Provides instrumentation for the MIB objects defined in RFC
1907 [17], and for any MIB objects relevant to any
administrative framework it supports.
- Sends and receives AgentX protocol messages to access
management information, based on the current registry of MIB
regions.
- Forwards notifications on behalf of subagents.
An entity acting in a subagent role performs the following functions:
- Initiates AgentX sessions with the master agent.
- Registers MIB regions with the master agent.
- Instantiates managed objects.
- Binds OIDs within its registered MIB regions to actual
variables.
- Performs management operations on variables.
- Initiates notifications.
4.2. Applicability
It is intended that this memo specify the smallest amount of required
behavior necessary to achieve the largest benefit, that is, to cover
a very large number of possible MIB implementations and
configurations with minimum complexity and low "cost of entry".
This section discusses several typical usage scenarios.
1) Subagents implement separate MIB modules -- for example, subagent
`A' implements "mib-2", subagent `B' implements "host-resources".
It is anticipated that this will be the most common subagent
configuration.
2) Subagents implement rows in a "simple table". A simple table is
one in which row creation is not specified, and for which the MIB
does not define an object that counts entries in the table.
Examples of simple tables are rdbmsDbTable, udpTable, and
hrSWRunTable.
This is the most commonly defined type of MIB table, and probably
represents the next most typical configuration that AgentX would
support.
3) Subagents share MIBs along non-row partitions. Subagents register
"chunks" of the MIB that represent multiple rows, due to the
nature of the MIB's index structure. Examples include registering
ipNetToMediaEntry.n, where n represents the ifIndex value for an
interface implemented by the subagent, and tcpConnEntry.a.b.c.d,
where a.b.c.d represents an IP address on an interface implemented
by the subagent.
AgentX supports these three common configurations, and all
permutations of them, completely. The consensus is that they
comprise a very large majority of current and likely future uses of
multi-vendor extensible agent configurations.
4) Subagents implement rows in tables that permit row creation, for
example, the RMON historyControlTable. To implement row creation
in such tables, at least one AgentX subagent must register at a
point "higher" in the OID tree than an individual row (per
AgentX's dispatching procedure).
5) Subagents implement rows in tables whose MIB also defines an
object that counts entries in the table, for example the MIB-2
ifTable (due to ifNumber). The subagent that implements such a
counter object (like ifNumber) must go beyond AgentX to correctly
implement it. This is an implementation issue (and most new MIB
designs no longer include such objects).
Scenarios in these latter 2 categories were thought to occur somewhat
rarely in configurations where subagents are independently
implemented by different vendors. The focus of a standard protocol,
however, must be in just those areas where multi-vendor
interoperability must be assured.
Note that it would be inefficient (due to AgentX registration
overhead) to share a table among AgentX subagents if the table
contains very dynamic instances, and each subagent registers fully
qualified instances. ipRouteTable could be an example of such a
table in some environments.
4.3. Design Features of AgentX
The primary features of the design described in this memo are:
1) A general architectural division of labor between master agent and
subagent: The master agent is MIB ignorant and SNMP omniscient,
while the subagent is SNMP ignorant and MIB omniscient (for the
MIB variables it instantiates). That is, master agents,
exclusively, are concerned with SNMP protocol operations and the
translations to and from AgentX protocol operations needed to
carry them out; subagents are exclusively concerned with
management instrumentation; and neither should intrude on the
other's territory.
2) A standard protocol and "rules of engagement" to enable
interoperability between management instrumentation and extensible
agents.
3) Mechanisms for independently developed subagents to integrate into
the extensible agent on a particular managed node in such a way
that they need not be aware of any other existing subagents.
4) A simple, deterministic registry and dispatching algorithm. For a
given extensible agent configuration, there is a single subagent
who is "authoritative" for any particular region of the MIB (where
"region" may extend from an entire MIB down to a single object-
instance).
5) Performance considerations. It is likely that the master agent
and all subagents will reside on the same host, and in such cases
AgentX is more a form of inter-process communication than a
traditional communications protocol.
Some of the design decisions made with this in mind include:
- 32-bit alignment of data within PDUs
- Native byte-order encoding by subagents
- Large AgentX PDU payload sizes.
4.4. Non-Goals
1) Subagent-to-subagent communication. This is out of scope, due to
the security ramifications and complexity involved.
2) Subagent access (via the master agent) to MIB variables. This is
not addressed, since various other mechanisms are available and it
was not a fundamental requirement.
3) The ability to accommodate every conceivable extensible agent
configuration option. This was the most contentious aspect in the
development of this protocol. In essence, certain features
currently available in some commercial extensible agent products
are not included in AgentX. Although useful or even vital in some
implementation strategies, the rough consensus was that these
features were not appropriate for an Internet Standard, or not
typically required for independently developed subagents to
coexist. The set of supported extensible agent configurations is
described above, in Section 4.2, "Applicability".
Some possible future version of the AgentX protocol may provide
coverage for one or more of these "non-goals" or for new goals that
might be identified after greater deployment experience.
5. AgentX Encodings
AgentX PDUs consist of a common header, followed by PDU-specific data
of variable length. Unlike SNMP PDUs, AgentX PDUs are not encoded
using the BER (as specified in ISO 8824 [18]), but are transmitted as
a contiguous byte stream. The data within this stream is organized
to provide natural alignment with respect to the start of the PDU,
permitting direct (integer) access by the processing entities.
The first four fields in the header are single-byte values. A bit
(NETWORK_BYTE_ORDER) in the third field (h.flags) is used to indicate
the byte ordering of all multi-byte integer values in the PDU,
including those which follow in the header itself. This is described
in more detail in Section 6.1, "AgentX PDU Header", below.
PDUs are depicted in this memo using the following convention (where
byte 1 is the first transmitted byte):
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| byte 1 | byte 2 | byte 3 | byte 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| byte 5 | byte 6 | byte 7 | byte 8 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Fields marked "<reserved>" are reserved for future use and must be
zero-filled.
5.1. Object Identifier
An object identifier is encoded as a 4-byte header, followed by a
variable number of contiguous 4-byte fields representing sub-
identifiers. This representation (termed Object Identifier) is as
follows:
Object Identifier
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | include | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Object Identifier header fields:
n_subid
The number (0-128) of sub-identifiers in the object identifier.
An ordered list of "n_subid" 4-byte sub-identifiers follows the
4-byte header.
prefix
An unsigned value used to reduce the length of object
identifier encodings. A non-zero value "x" is interpreted as
the first sub-identifier after "internet" (1.3.6.1), and
indicates an implicit prefix "internet.x" to the actual sub-
identifiers encoded in the Object Identifier. For example, a
prefix field value 2 indicates an implicit prefix "1.3.6.1.2".
A value of 0 in the prefix field indicates there is no prefix
to the sub-identifiers.
include
Used only when the Object Identifier is the start of a
SearchRange, as described in section 5.2, "SearchRange".
sub-identifier 1, 2, ... n_subid
A 4-byte unsigned integer, encoded according to the header's
NETWORK_BYTE_ORDER bit.
A null Object Identifier consists of the 4-byte header with all bytes
set to 0.
Examples:
sysDescr.0 (1.3.6.1.2.1.1.1.0)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 4 | 2 | 0 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1.2.3.4
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 4 | 0 | 0 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 3 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
5.2. SearchRange
A SearchRange consists of two Object Identifiers. In its
communication with a subagent, the master agent uses a SearchRange to
identify a requested variable binding, and, in GetNext and GetBulk
operations, to set an upper bound on the names of managed object
instances the subagent may send in reply.
The first Object Identifier in a SearchRange (called the starting
OID) indicates the beginning of the range. It is frequently (but not
necessarily) the name of a requested variable binding.
The "include" field in this OID's header is a boolean value (0 or 1)
indicating whether or not the starting OID is included in the range.
The second object identifier (ending OID) indicates the non-inclusive
end of the range, and its "include" field is always 0. A null value
for ending OID indicates an unbounded SearchRange.
Example: To indicate a search range from 1.3.6.1.2.1.25.2
(inclusive) to 1.3.6.1.2.1.25.2.1 (exclusive), the SearchRange would
be:
(start)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 3 | 2 | 1 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 25 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(end)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 4 | 2 | 0 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 25 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
A SearchRangeList is a contiguous list of SearchRanges.
5.3. Octet String
An octet string is represented by a contiguous series of bytes,
beginning with a 4-byte integer (encoded according to the header's
NETWORK_BYTE_ORDER bit) whose value is the number of octets in the
octet string, followed by the octets themselves. This representation
is termed an Octet String. If the last octet does not end on a 4-
byte offset from the start of the Octet String, padding bytes are
appended to achieve alignment of following data. This padding must
be added even if the Octet String is the last item in the PDU.
Padding bytes must be zero filled.
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
A null Octet String consists of a 4-byte length field set to 0.
5.4. Value Representation
Variable bindings may be encoded within the variable-length portion
of some PDUs. The representation of a variable binding (termed a
VarBind) consists of a 2-byte type field, a name (Object Identifier),
and the actual value data.
VarBind
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| v.type | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(v.name)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(v.data)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| data |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| data |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
VarBind fields:
v.type
Indicates the variable binding's syntax, and must be one of the
following values:
Integer (2),
Octet String (4),
Null (5),
Object Identifier (6),
IpAddress (64),
Counter32 (65),
Gauge32 (66),
TimeTicks (67),
Opaque (68),
Counter64 (70),
noSuchObject (128),
noSuchInstance (129),
endOfMibView (130)
v.name
The Object Identifier which names the variable.
v.data
The actual value, encoded as follows:
- Integer, Counter32, Gauge32, and TimeTicks are encoded as 4
contiguous bytes, according to the header's
NETWORK_BYTE_ORDER bit.
- Counter64 is encoded as 8 contiguous bytes, according to
the header's NETWORK_BYTE_ORDER bit.
- Object Identifiers are encoded as described in section 5.1,
Object Identifier.
- IpAddress, Opaque, and Octet String are all octet strings
and are encoded as described in section 5.3, "Octet
String", Octet String. Note that the octets used to
represent IpAddress are always ordered most significant to
least significant.
Value data always follows v.name whenever v.type is one of
the above types. These data bytes are present even if they
will not be used (as, for example, in certain types of
index allocation).
- Null, noSuchObject, noSuchInstance, and endOfMibView do not
contain any encoded value. Value data never follows v.name
in these cases.
Note that the VarBind itself does not contain the value size.
That information is implied for the fixed-length types, and
explicitly contained in the encodings of variable-length types
Object Identifier and Octet String).
A VarBindList is a contiguous list of VarBinds. Within a
VarBindList, a particular VarBind is identified by an index value.
The first VarBind in a VarBindList has index value 1, the second has
index value 2, and so on.
6. Protocol Definitions
6.1. AgentX PDU Header
The AgentX PDU header is a fixed-format, 20-octet structure:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version | h.type | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
An AgentX PDU header contains the following fields:
h.version
The version of the AgentX protocol (1 for this memo).
h.type
The PDU type; one of the following values:
agentx-Open-PDU (1),
agentx-Close-PDU (2),
agentx-Register-PDU (3),
agentx-Unregister-PDU (4),
agentx-Get-PDU (5),
agentx-GetNext-PDU (6),
agentx-GetBulk-PDU (7),
agentx-TestSet-PDU (8),
agentx-CommitSet-PDU (9),
agentx-UndoSet-PDU (10),
agentx-CleanupSet-PDU (11),
agentx-Notify-PDU (12),
agentx-Ping-PDU (13),
agentx-IndexAllocate-PDU (14),
agentx-IndexDeallocate-PDU (15),
agentx-AddAgentCaps-PDU (16),
agentx-RemoveAgentCaps-PDU (17),
agentx-Response-PDU (18)
The set of PDU types for "administrative processing" are 1-4
and 12-17. The set of PDU types for "SNMP request
processing" are 5-11.
h.flags
A bitmask, with bit 0 the least significant bit. The bit
definitions are as follows:
Bit Definition
--- ----------
0 INSTANCE_REGISTRATION
1 NEW_INDEX
2 ANY_INDEX
3 NON_DEFAULT_CONTEXT
4 NETWORK_BYTE_ORDER
5-7 (reserved)
The NETWORK_BYTE_ORDER bit applies to all multi-byte integer
values in the entire AgentX packet, including the remaining
header fields. If set, then network byte order (most
significant byte first; "big endian") is used. If not set,
then least significant byte first ("little endian") is used.
The NETWORK_BYTE_ORDER bit applies to all AgentX PDUs.
The NON_DEFAULT_CONTEXT bit is used only in the AgentX PDUs
described in section 6.1.1, "Context".
The NEW_INDEX and ANY_INDEX bits are used only within the
agentx-IndexAllocate-, and -IndexDeallocate-PDUs.
The INSTANCE_REGISTRATION bit is used only within the
agentx-Register-PDU.
h.sessionID
The session ID uniquely identifies a session over which
AgentX PDUs are exchanged between a subagent and the master
agent. The session ID has no significance and no defined
value in the agentx-Open-PDU sent by a subagent to open a
session with the master agent; in this case, the master
agent will assign a unique session ID that it will pass back
in the corresponding agentx-Response-PDU. From that point
on, that same session ID will appear in every AgentX PDU
exchanged over that session between the master and the
subagent. A subagent may establish multiple AgentX sessions
by sending multiple agentx-Open-PDUs to the master agent.
In master agents that support multiple transport protocols,
the sessionID should be globally unique rather than unique
just to a particular transport.
h.transactionID
The transaction ID uniquely identifies, for a given session,
the single SNMP management request (and single SNMP PDU)
with which an AgentX PDU is associated. If a single SNMP
management request results in multiple AgentX PDUs being
sent by the master agent with the same session ID, each of
these AgentX PDUs must contain the same transaction ID;
conversely, AgentX PDUs sent during a particular session,
that result from distinct SNMP management requests, must
have distinct transaction IDs within the limits of the 32-
bit field).
Note that the transaction ID is not the same as the SNMP
PDU's request-id (as described in section 4.1 of RFC1905
[13], nor is it the same as the SNMP Message's msgID (as
described in section 6.2 of RFC2572 [11]), nor can it be,
since a master agent might receive SNMP requests with the
same request-ids or msgIDs from different managers.
The transaction ID has no significance and no defined value
in AgentX administrative PDUs, i.e., AgentX PDUs that are
not associated with an SNMP management request.
h.packetID
A packet ID generated by the sender for all AgentX PDUs
except the agentx-Response-PDU. In an agentx-Response-PDU,
the packet ID must be the same as that in the received
AgentX PDU to which it is a response. A master agent might
use this field to associate subagent response PDUs with
their corresponding request PDUs. A subagent might use this
field to correlate responses to multiple (batched)
registrations.
h.payload_length
The size in octets of the PDU contents, excluding the 20-
byte header. As a result of the encoding schemes and PDU
layouts, this value will always be either 0, or a multiple
of 4.
6.1.1. Context
In the SNMPv1 or SNMPv2c, the community string may be used as an
index into a local repository of configuration information that may
include community profiles or more complex context information. In
SNMPv3 this notion of "context" is formalized (see section 3.3.1 in
RFC2571 [1].
AgentX provides a mechanism for transmitting a context specification
within relevant PDUs, but does not place any constraints on the
content of that specification.
An optional context field may be present in the agentx-Register-,
UnRegister-, AddAgentCaps-, RemoveAgentCaps-, Get-, GetNext-,
GetBulk-, IndexAllocate-, IndexDeallocate-, Notify-, TestSet-, and
Ping- PDUs.
If the NON_DEFAULT_CONTEXT bit in the AgentX header field h.flags is
clear, then there is no context field in the PDU, and the operation
refers to the default context. (This does not mean there is a zero-
length Octet String, it means there is no Octet String present.) If
the NON_DEFAULT_CONTEXT bit is set, then a context field immediately
follows the AgentX header, and the operation refers to that specific
context. The context is represented as an Octet String. There are
no constraints on its length or contents.
Thus, all of these AgentX PDUs (that is, those listed immediately
above) refer to, or "indicate" a context, which is either the default
context, or a non-default context explicitly named in the PDU.
6.2. AgentX PDUs
6.2.1. The agentx-Open-PDU
An agentx-Open-PDU is generated by a subagent to request
establishment of an AgentX session with the master agent.
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (1) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| o.timeout | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(o.id)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| subidentifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| subidentifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(o.descr)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
An agentx-Open-PDU contains the following fields:
o.timeout
The length of time, in seconds, that a master agent should
allow to elapse after dispatching a message on a session
before it regards the subagent as not responding. This is
the default value for the session, and may be overridden by
values associated with specific registered MIB regions. The
default value of 0 indicates that there is no session-wide
default value.
o.id
An Object Identifier that identifies the subagent.
Subagents that do not support such an notion may send a null
Object Identifier.
o.descr
An Octet String containing a DisplayString describing the
subagent.
6.2.2. The agentx-Close-PDU
An agentx-Close-PDU issued by either a subagent or the master agent
terminates an AgentX session.
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (2) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| c.reason | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
An agentx-Close-PDU contains the following field:
c.reason
An enumerated value that gives the reason that the master
agent or subagent closed the AgentX session. This field may
take one of the following values:
reasonOther(1)
None of the following reasons
reasonParseError(2)
Too many AgentX parse errors from peer
reasonProtocolError(3)
Too many AgentX protocol errors from peer
reasonTimeouts(4)
Too many timeouts waiting for peer
reasonShutdown(5)
Sending entity is shutting down
reasonByManager(6)
Due to Set operation; this reason code can be used only
by the master agent, in response to an SNMP management
request.
6.2.3. The agentx-Register-PDU
An agentx-Register-PDU is generated by a subagent for each region of
the MIB variable naming tree (within one or more contexts) that it
wishes to support.
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (3) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.context) (OPTIONAL)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| r.timeout | r.priority | r.range_subid | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.subtree)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.upper_bound)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| optional upper-bound sub-identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
An agentx-Register-PDU contains the following fields:
r.context
An optional non-default context.
r.timeout
The length of time, in seconds, that a master agent should
allow to elapse after dispatching a message on a session
before it regards the subagent as not responding. r.timeout
applies only to messages that concern MIB objects within
r.subtree. It overrides both the session's default value
(if any) indicated when the AgentX session with the master
agent was established, and the master agent's default
timeout. The default value for r.timeout is 0 (no
override).
r.priority
A value between 1 and 255, used to achieve a desired
configuration when different sessions register identical or
overlapping regions. Subagents with no particular knowledge
of priority should register with the default value of 127.
In the master agent's dispatching algorithm, smaller values
of r.priority take precedence over larger values, as
described in section 7.1.4.1, "Handling Duplicate and
Overlapping Subtrees".
r.subtree
An Object Identifier that names the basic subtree of a MIB
region for which a subagent indicates its support. The term
"subtree" is used generically here, it may represent a
fully-qualified instance name, a partial instance name, a
MIB table, an entire MIB, etc.
The choice of what to register is implementation-specific;
this memo does not specify permissible values. Standard
practice however is for a subagent to register at the
highest level of the naming tree that makes sense.