RFC 2257
Agent Extensibility (AgentX) Protocol Version 1
Title Block 🎀
okay bestie, this is RFC 2257, and it's called Agent Extensibility (AgentX) Protocol Version 1 ✨. It's dated January 1998 and it's a Standards Track doc, so it's an actual Internet standards track protocol 👑. Three people wrote it: M. Daniele from Digital Equipment Corporation, B. Wijnen from the T.J. Watson Research Center at IBM Corp., and D. Francisco, who's the editor, from Cisco Systems, Inc. 💅 Nothing is listed as obsoleted or updated in its title block, so it isn't replacing or changing any other RFCs 🫶
Status of this Memo 🦋
okay so this section says the doc specifies an Internet standards track protocol for the Internet community, and it wants discussion and suggestions for improvements 💖 If you want the current standardization state and status of this protocol, check the "Internet Official Protocol Standards" (STD 1) 📚 Distribution of this memo is unlimited 🌸
Copyright Notice 🎀
Copyright (C) The Internet Society (1998). All Rights Reserved. 💜
Table of Contents 🧚
1 Introduction......................................................4
2 The SNMP Framework................................................4
2.1 A Note on Terminology.........................................4
3 Extending the MIB.................................................5
3.1 Motivation for AgentX.........................................5
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.................................................10
5.1 Object Identifier............................................11
5.2 SearchRange..................................................13
5.3 Octet String.................................................14
5.4 Value Representation.........................................14
6 Protocol Definitions.............................................16
6.1 AgentX PDU Header............................................16
6.1.1 Context..................................................19
6.2 AgentX PDUs..................................................20
6.2.1 The agentx-Open-PDU......................................20
6.2.2 The agentx-Close-PDU.....................................21
6.2.3 The agentx-Register-PDU..................................22
6.2.4 The agentx-Unregister-PDU................................25
6.2.5 The agentx-Get-PDU.......................................27
6.2.6 The agentx-GetNext-PDU...................................29
6.2.7 The agentx-GetBulk-PDU...................................30
6.2.8 The agentx-TestSet-PDU...................................31
6.2.9 The agentx-CommitSet, -UndoSet, -CleanupSet
PDUs.....................................................33
6.2.10 The agentx-Notify-PDU...................................33
6.2.11 The agentx-Ping-PDU.....................................34
6.2.12 The agentx-IndexAllocate-PDU............................35
6.2.13 The agentx-IndexDeallocate-PDU..........................36
6.2.14 The agentx-AddAgentCaps-PDU.............................37
6.2.15 The agentx-RemoveAgentCaps-PDU..........................38
6.2.16 The agentx-Response-PDU.................................39
7 Elements of Procedure............................................41
7.1 Processing AgentX Administrative Messages....................42
7.1.1 Processing the agentx-Open-PDU...........................42
7.1.2 Processing the agentx-IndexAllocate-PDU..................43
7.1.3 Using the agentx-IndexAllocate-PDU.......................45
7.1.4 Processing the agentx-IndexDeallocate-PDU................47
7.1.5 Processing the agentx-Register-PDU.......................48
7.1.5.1 Handling Duplicate OID Ranges........................50
7.1.6 Processing the agentx-Unregister-PDU.....................51
7.1.7 Processing the agentx-AddAgentCaps-PDU...................51
7.1.8 Processing the agentx-RemoveAgentCaps-PDU................52
7.1.9 Processing the agentx-Close-PDU..........................52
7.1.10 Detecting Connection Loss...............................53
7.1.11 Processing the agentx-Notify-PDU........................53
7.1.12 Processing the agentx-Ping-PDU..........................54
7.2 Processing Received SNMP Protocol Messages...................54
7.2.1 Dispatching AgentX PDUs..................................55
7.2.1.1 agentx-Get-PDU.......................................57
7.2.1.2 agentx-GetNext-PDU...................................58
7.2.1.3 agentx-GetBulk-PDU...................................59
7.2.1.4 agentx-TestSet-PDU...................................60
7.2.1.5 Dispatch.............................................60
7.2.2 Subagent Processing of agentx-Get, GetNext,
GetBulk-PDUs.............................................61
7.2.2.1 Subagent Processing of the agentx-Get-PDU............61
7.2.2.2 Subagent Processing of the
agentx-GetNext-PDU...................................62
7.2.2.3 Subagent Processing of the
agentx-GetBulk-PDU...................................62
7.2.3 Subagent Processing of agentx-TestSet,
-CommitSet, -UndoSet, -CleanupSet-PDUs...................63
7.2.3.1 Subagent Processing of the
agentx-TestSet-PDU...................................64
7.2.3.2 Subagent Processing of the
agentx-CommitSet-PDU.................................65
7.2.3.3 Subagent Processing of the
agentx-UndoSet-PDU...................................65
7.2.3.4 Subagent Processing of the
agentx-CleanupSet-PDU................................65
7.2.4 Master Agent Processing of AgentX Responses..............66
7.2.4.1 Common Processing of All AgentX Response
PDUs.................................................66
7.2.4.2 Processing of Responses to agentx-Get-PDUs...........66
7.2.4.3 Processing of Responses to
agentx-GetNext-PDU and agentx-GetBulk-PDU............67
7.2.4.4 Processing of Responses to
agentx-TestSet-PDUs..................................68
7.2.4.5 Processing of Responses to
agentx-CommitSet-PDUs................................68
7.2.4.6 Processing of Responses to
agentx-UndoSet-PDUs..................................69
7.2.5 Sending the SNMP Response-PDU............................69
7.2.6 MIB Views................................................69
7.3 State Transitions............................................70
7.3.1 Set Transaction States...................................70
7.3.2 Transport Connection States..............................71
7.3.3 Session States...........................................73
8 Transport Mappings...............................................74
8.1 AgentX over TCP..............................................74
8.1.1 Well-known Values........................................74
8.1.2 Operation................................................74
8.2 AgentX over UNIX-domain Sockets..............................75
8.2.1 Well-known Values........................................75
8.2.2 Operation................................................75
9 Security Considerations..........................................76
10 Acknowledgements................................................77
11 Authors' and Editor's Addresses.................................77
12 References......................................................78
13 Full Copyright Statement........................................801. Introduction ✨
okay so this memo sets up a standardized framework for extensible SNMP agents 🧚 It defines processing entities called master agents and subagents, plus a protocol (AgentX) they use to talk to each other 💬 It also covers the elements of procedure that the extensible agent follows when it processes SNMP protocol messages 💅
2. The SNMP Framework 🌈
so a management system is made of several (potentially many) nodes 🌸 Each node has a processing entity called an agent, which can access management instrumentation 🔧 You also need at least one management station, plus a management protocol that carries management information between the agents and the stations 📡 The protocol's operations run under an administrative framework, and that framework defines authentication, authorization, access control, and privacy policies 🔐
Management stations run management applications that monitor and control managed elements ⭐ Managed elements are devices like hosts, routers, terminal servers, etc., and they get monitored and controlled through access to their management information 🖥️
Management information is seen as a collection of managed objects, living in a virtual information store called the Management Information Base (MIB) 🗂️ Collections of related objects are defined in MIB modules 🧩 These modules are written in a subset of OSI's Abstract Syntax Notation One (ASN.1) [1], which is called the Structure of Management Information (SMI) (see RFC 1902 [2]) 🎀
2.1. A Note on Terminology 💜
quick vocab check bestie 📖 A "variable" is an instance of a non-aggregate object type, defined using the SMI conventions (RFC 1902, [2]) or the textual conventions based on the SMI (RFC 1903 [3]) 🍓 A "variable binding" usually means the pairing of a variable's name with its value 💕 But if certain exceptional conditions happen while a retrieval request is being processed, a variable binding pairs a name with an indication of that exception 🙈
A variable-binding list is just a simple list of variable bindings 📝
The name of a variable is an OBJECT IDENTIFIER, made by concatenating the OBJECT IDENTIFIER of the corresponding object type with an OBJECT IDENTIFIER fragment that identifies the instance 🔢 The OBJECT IDENTIFIER of the corresponding object type is called the OBJECT IDENTIFIER prefix of the variable 🦋
For the purpose of exposition, the original Internet-standard Network Management Framework is called the SNMP version 1 framework (SNMPv1) 🌸 It's described in RFCs 1155 (STD 16), 1157 (STD 15), and 1212 (STD 16) 📚 The current framework, described in RFCs 1902-1908, is called the SNMP version 2 framework (SNMPv2) 💖
3. Extending the MIB 🎀
new MIB modules that extend the Internet-standard MIB keep getting defined by all sorts of IETF working groups 🛠️ Enterprises and individuals also often create or extend enterprise-specific or experimental MIBs 🧁
So managed devices end up being complicated collections of manageable components, and those components get installed independently on a managed node 🧩 Each component provides instrumentation for the managed objects defined in the MIB module(s) it implements 🫶
Neither the SNMP version 1 nor version 2 framework describes how the set of managed objects supported by a particular agent can be changed dynamically 😭 That's the gap AgentX is here to fill 🦋
3.1. Motivation for AgentX
okay bestie, this need to dynamically extend the management objects inside a node is SO real 💅 and it's why we got a whole bunch of "extensible agents" 🦋. They usually come with four pieces:
- a "master" agent that lives on the standard transport address and accepts SNMP protocol messages 💌
- a set of "subagents" that each contain management instrumentation 🧚
- a protocol between the master agent and the subagents, where subagents can "connect" to the master agent and the master agent multiplexes the SNMP protocol messages it receives across the subagents 🔀
- a set of tools to help build subagents, plus a runtime (API) environment that hides most of the protocol stuff between a subagent and the master agent 🛠️
ngl, the wide deployment of extensible SNMP agents plus the lack of Internet standards in this area makes it really hard to field SNMP-manageable applications 😭. A vendor might have to support several different subagent environments (APIs) just to cover different target platforms. Yikes.
It also gets pretty cumbersome to configure subagents and (possibly multiple) master agents on one managed node 🙈.
Specifying a standard protocol for agent extensibility (AgentX) gives us the technical foundation we need to solve both of these problems 👑. Independently developed AgentX-capable master agents and subagents will be able to interoperate at the protocol level, and vendors can keep standing out in every other way 💖.
4. AgentX Framework ✨
Within the SNMP framework, a managed node contains a processing entity called an agent, and that agent 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 version 1 and version 2 framework documents) but typically has little or no direct access to management information 📨
- 0 or more processing entities called subagents, which are "shielded" from the SNMP protocol messages processed by the master agent, but which do 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. Some AgentX protocol messages look similar in syntax and semantics to SNMP, but 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 a non-extensible (monolithic) agent would, as long as that agent has access to the same management instrumentation 👀.
This transparency to managers is a fundamental requirement of AgentX, and it's 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 [5], 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 an AgentX session 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. In other words, it aims to cover a very large number of possible MIB implementations and configurations with minimum complexity and a low "cost of entry" 🎀.
This section discusses several typical usage scenarios 🗂️.
- 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 🥇.
- 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, andhrSWRunTable. This is the most commonly defined type of MIB table, and it probably represents the next most typical configuration that AgentX would support 🍓. - 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, andtcpConnEntry.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 make up a very large majority of current and likely future uses of multi-vendor extensible agent configurations 🫶.
- Subagents implement rows in "complex tables". Complex tables here are defined as tables that permit row creation, or whose MIB also defines an object that counts entries in the table. Examples include the MIB-2
ifTable(due toifNumber) and the RMONhistoryControlTable😵💫.
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 🙃.
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). Again, this is an implementation issue 🔧.
Scenarios in this category 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:
- 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 🏰.
- A standard protocol and "rules of engagement" to enable interoperability between management instrumentation and extensible agents 🤝.
- 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 🌷.
- 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) 👑.
- 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
- Subagent-to-subagent communication. This is out of scope, due to the security ramifications and complexity involved 🚧.
- 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 🙅♀️.
- 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 🧁.
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 ✨
okay so AgentX PDUs are built like a common header followed by PDU-specific data of variable length 🎀 but here's the twist: they are not BER-encoded like SNMP PDUs (BER is from ISO 8824 [1]). Instead they go out as one contiguous byte stream 🌊 The data is laid out so everything lines up naturally with the start of the PDU, which means processing entities can grab integers directly. so clean 💅
The first four header fields are single-byte values. The NETWORK_BYTE_ORDER bit in the third field (h.flags) tells you the byte ordering of every multi-byte integer in the PDU, including the ones in the header itself 🧚 I'll go into more detail in Section 6.1, "AgentX PDU Header", below.
Here's how we draw PDUs in this doc (byte 1 is the first one sent) 🦋
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| byte 1 | byte 2 | byte 3 | byte 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| byte 5 | byte 6 | byte 7 | byte 8 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Any field marked <reserved> is saved for future use and is zero-filled. 🫶
5.1. Object Identifier
An Object Identifier is a 4-byte header followed by a variable number of contiguous 4-byte fields, one for each sub-identifier 🔢 Here's the layout:
Object Identifier
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | include | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Here's what the header fields do 👑
n_subid- This is the number (0-128) of sub-identifiers in the Object Identifier. The list of
n_subid4-byte sub-identifiers comes right after the 4-byte header, in order. 📋
- This is the number (0-128) of sub-identifiers in the Object Identifier. The list of
prefix- This is an unsigned value that shortens Object Identifier encodings 🍓 A non-zero value "x" is read as the first sub-identifier after "internet" (1.3.6.1), so it implies a prefix of "internet.x" for the sub-identifiers that are actually encoded. For example, a
prefixvalue of 2 means an implicit prefix of "1.3.6.1.2". Aprefixvalue of 0 means there's no prefix on the sub-identifiers.
- This is an unsigned value that shortens Object Identifier encodings 🍓 A non-zero value "x" is read as the first sub-identifier after "internet" (1.3.6.1), so it implies a prefix of "internet.x" for the sub-identifiers that are actually encoded. For example, a
include- This one is only used when the Object Identifier is the start of a SearchRange, as described in section 5.2. 🌸
A null Object Identifier is just the 4-byte header with every byte set to 0 🫧
Examples time 🎀
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 is two Object Identifiers stuck together 💕 When a master agent is talking to a subagent, it uses a SearchRange to pin down a requested variable binding. In GetNext and GetBulk operations, it also uses it to set an upper bound on the names of managed object instances the subagent is allowed to send back in the reply ✨
The first Object Identifier, called the starting OID, marks where the range begins. It's often (but not always) the name of a requested variable binding 🦋
The include field in that OID's header is a boolean (0 or 1) that says whether the starting OID is part of the range or not 🌈
The second Object Identifier marks the non-inclusive end of the range, and its include field is always 0 🙈
Example: say we want a search range from 1.3.6.1.2.1.25.2 (inclusive) up to 1.3.6.1.2.1.25.2.1 (exclusive). The SearchRange would look like this:
(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 a contiguous run of bytes 🧸 It starts with a 4-byte integer holding the number of octets in the string, then the octets themselves. This whole thing is called an Octet String. If the last octet doesn't finish on a 4-byte offset from the start of the Octet String, padding bytes get tacked on so the following data stays aligned 🎀 That padding is needed even when 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 is just a 4-byte length field set to 0 🙈
5.4. Value Representation ✨
Okay so variable bindings can get tucked inside the variable-length part of some PDUs 🎀 A variable binding (we call it a VarBind) is made of a 2-byte type field, a name (which is an Object Identifier), and then 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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Here's the breakdown of each VarBind field 🦋
v.type
Tells you the variable binding's syntax. It must be one of these 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 that names the variable. Main character energy 👑
v.data
The actual value, and it gets encoded like this 💅
- Integer, Counter32, Gauge32, and TimeTicks are each encoded as 4 contiguous bytes. If the
NETWORK_BYTE_ORDERbit is set inh.flags, the bytes go most significant to least significant. Otherwise they go least significant to most significant. - Counter64 is encoded as 8 contiguous bytes. Same deal: if
NETWORK_BYTE_ORDERis set inh.flags, the bytes go most significant to least significant, otherwise least significant to most significant. - Object Identifiers are encoded the way section 5.1, Object Identifier, describes.
- IpAddress, Opaque, and Octet String are all octet strings, so they're encoded the way section 5.3, Octet String, describes.
Value data always follows v.name whenever v.type is one of the above types. Those data bytes are there even if they won't get used (like with certain types of index allocation) 🫶
- Null, noSuchObject, noSuchInstance, and endOfMibView don't carry any encoded value. Value data never follows v.name in these cases 🙈
Note that the VarBind itself doesn't store the value size 😭 That info is implied for the fixed-length types, and explicitly included in the encodings of the variable-length types (Object Identifier and Octet String). The way that works is so clean, ngl ✨
A VarBindList is a contiguous list of VarBinds. Inside a VarBindList, each VarBind gets identified by an index value. The first VarBind has index value 1, the second has index value 2, and so on 🌸
6. Protocol Definitions 🎀
6.1. AgentX PDU Header
Okay this is the big one, bestie 😭 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 holds these fields:
h.version
The version of the AgentX protocol (1 for this memo) 🧚
h.type
The PDU type. It's one of these 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)h.flags
A bitmask, where bit 0 is the least significant bit. Here's what each bit means 🍓
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 it's set, network byte order is used (most significant byte first, which is "big endian"). If it's not set, least significant byte first ("little endian") is used 🌈
The NETWORK_BYTE_ORDER bit applies to all AgentX PDUs. Consistency is everything 💅
The NON_DEFAULT_CONTEXT bit is only used in the AgentX PDUs described in section 6.1.1.
The NEW_INDEX and ANY_INDEX bits are only used within the agentx-IndexAllocate- and -IndexDeallocate-PDUs.
The INSTANCE_REGISTRATION bit is only used within the agentx-Register-PDU.
h.sessionID
The session ID uniquely identifies a session over which AgentX PDUs get exchanged between a subagent and the master agent 🦋 It has no significance and no defined value in the agentx-Open-PDU that a subagent sends to open a session with the master agent. In that case, the master agent assigns a unique sessionID and passes it back in the corresponding agentx-Response-PDU. From then on, that same sessionID shows up in every AgentX PDU exchanged over that session between the master and the subagent. A subagent can 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) that an AgentX PDU is associated with 💜 If a single SNMP management request results in multiple AgentX PDUs being sent by the master agent with the same sessionID, each of those AgentX PDUs must contain the same transaction ID. Conversely, AgentX PDUs sent during a particular session that come 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 RFC 1905 [4]), nor can it be, since a master agent might receive SNMP requests with the same request-ids from different managers 🙈
The transaction ID has no significance and no defined value in AgentX administrative PDUs, meaning AgentX PDUs that aren't 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 the one in the received AgentX PDU it's responding to. A master agent might use this field to match subagent response PDUs with their corresponding request PDUs. A subagent might use it to correlate responses to multiple (batched) registrations 🧚
h.payload_length
The size in octets of the PDU contents, not counting the 20-byte header. Because 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 v2c frameworks, the community string can be used as an index into a local repository of configuration information, which may include community profiles or more complex context information. Future versions of SNMP will likely formalize this notion of "context" 👑
AgentX gives you a way to transmit a context specification within relevant PDUs, but it doesn't put any constraints on what that specification contains 🎀
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, there's no context field in the PDU, and the operation refers to the default context.
If the NON_DEFAULT_CONTEXT bit is set, 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 💖
So all of these AgentX PDUs (the ones listed right 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 🎀
okay so an agentx-Open-PDU is what a subagent sends when it wants to start an AgentX session with the master agent. it's basically the "hi, can we be friends? 🥺" message 💖
Here's the layout, bits and all:
(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 has these fields, and they're all important 👑
o.timeout: the number of seconds a master agent should wait after sending a message to a subagent before it decides that subagent isn't responding 🙈 This is a subagent-wide default, and it can be overridden by values tied to specific registered MIB regions. A value of 0 just means "no subagent-wide value, thanks."o.id: an Object Identifier that names the subagent. If a subagent doesn't do IDs, it can send a null Object Identifier instead 🌸o.descr: an Octet String holding aDisplayStringthat describes the subagent. basically a little name tag 🏷️
6.2.2. The agentx-Close-PDU 💀
an agentx-Close-PDU is the goodbye message. either the subagent or the master agent can send it to end an AgentX session, so it's a total mutual breakup energy 😭🫶
Here's the layout:
(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 has just one field, c.reason 🦋 It's an enumerated value that says why the master agent or subagent is closing the session. It can be one of these:
reasonOther(1): none of the reasons below apply 🤷♀️reasonParseError(2): the peer has sent too many AgentX parse errors 🙃reasonProtocolError(3): the peer has sent too many AgentX protocol errors 💅reasonTimeouts(4): too many timeouts waiting on the peer ⏰reasonShutdown(5): the sending entity is shutting down 🌙reasonByManager(6): this is because of a Set operation. only the master agent can use this one, and only in response to an SNMP management request 👑 it's giving "the manager said so" energy
6.2.3. The agentx-Register-PDU ✨
okay so an agentx-Register-PDU is what a subagent sends for each region of the MIB variable naming tree it wants to support 🌳 (and that can be across one or more contexts) 💖
(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.region)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.upper_bound)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| optional upper-bound sub-identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+an agentx-Register-PDU has these fields 🎀
r.context: an optional non-default context 🌸r.timeout: how many seconds a master agent waits after sending a message to a subagent before it decides the subagent isn't responding ⏱️ this only applies to messages about MIB objects insider.region, and it overrides both the subagent-wide value (if there is one, from when the AgentX session got set up) and the master agent's default timeout. the default is0, which means no override 🦋r.priority: a value from1to255that helps get the config you want when different subagents register the same or overlapping regions 👑 subagents that don't know much about priority should register with the default of255, which is the lowest priority 💅 in the master agent's dispatching algorithm, smallerr.priorityvalues win over bigger ones, see section 7.1.5.1 🫶r.region: an Object Identifier that, together withr.range_subid, tells you which part of the MIB a subagent wants to support 🧚 it can be a fully-qualified instance name, a partial instance name, a MIB table, a whole MIB, or ranges of any of these 🌈
the choice of what to register is implementation-specific, and this memo doesn't spell out which values are allowed 💀 the standard vibe is for a subagent to register at the highest level of the naming tree that actually makes sense 👑 registering fully-qualified instances is usually only done when a subagent only does management operations on particular rows of a conceptual table 🙈
if r.region is a fully qualified instance name, the INSTANCE_REGISTRATION bit in h.flags must be set, otherwise it must be cleared 🔥 the master agent may save this info to speed up later operational dispatching ✨
r.range_subid: lets you specify a range in place of one ofr.region's sub-identifiers 🌸 if this value is0, no range is specified 😭 otherwise, ther.range_subid-th sub-identifier inr.regionis the range lower bound, and the range upper bound sub-identifier (r.upper_bound) comes right afterr.region💜
this lets you register a conceptual row with a single PDU, which is so clean 🧁 for example, this PDU registers row 7 of the RFC 1573 ifTable (1.3.6.1.2.1.2.2.1.1-22.7) 🦋
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (3) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| r.timeout | r.priority | 5 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.region)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 6 | 2 | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 7 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.upper_bound)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 22 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+6.2.4. The agentx-Unregister-PDU ✨
the agentx-Unregister-PDU is sent by a subagent to remove a region it previously registered from the master agent's OID space 🫧
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (4) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(u.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| <reserved> | u.priority | u.range_subid | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(u.region)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(u.upper_bound)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| optional upper-bound sub-identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+an agentx-Unregister-PDU has these fields 💅
u.context: an optional non-default context 🌷u.priority: the priority this region was originally registered at 🎀u.region: a previously-registered region of the MIB that a subagent doesn't want to support anymore 🥀
6.2.5. The agentx-Get-PDU 🎀
okay so the agentx-Get-PDU is the one that asks for specific variables, and it's giving a very clean layout 💅 here's the whole shape:
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (5) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(g.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(g.sr)
(start 1)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | include | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(end 1)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0 | 0 | 0 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
(start n)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | include | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(end n)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0 | 0 | 0 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+an agentx-Get-PDU has these two fields 🧚
g.context: an optional non-default context.g.sr: a SearchRangeList containing the requested variables for this subagent. 💜
6.2.6. The agentx-GetNext-PDU 🦋
the GetNext one is basically Get's bestie 👯♀️ same AgentX header, same (g.context) bit, same g.sr energy. the big difference you'll notice is in the end markers: the prefix stays put and the include byte gets zeroed out 👀
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (6) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(g.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(g.sr)
(start 1)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | include | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(end 1)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
(start n)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | include | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(end n)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...6.2.7. The agentx-GetBulk-PDU 🌈
last one in this batch and it's the most extra 💅 the GetBulk-PDU gets the same AgentX header and (g.context) treatment as the others, plus a little 32-bit word holding g.non_repeaters and g.max_repetitions. the g.sr part is copied straight from the agentx-GetNext-PDU, so you already know that one 🫶
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (7) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(g.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| g.non_repeaters | g.max_repetitions |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(g.sr) as in agentx-GetNext-PDU above
...6.2.8. The agentx-TestSet-PDU ✨
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (8) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(t.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(t.vb)
(VarBind 1)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| v.type | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| data |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| data |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
(VarBind n)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| v.type | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| data |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| data |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...An agentx-TestSet-PDU has these fields, bestie 💖:
t.context: an optional, non-default context 🎀t.vb: a VarBindList with the VarBinds requested for this subagent 🦋
6.2.9. The agentx-CommitSet, -UndoSet, -CleanupSet PDUs 🌸
These PDUs are giving simple: they consist of the AgentX header only 💅.
The agentx-CommitSet-, -UndoSet-, and -Cleanup-PDUs are the ones used when processing an SNMP SetRequest operation 🔥.
6.2.10. The agentx-Notify-PDU 📣
An agentx-Notify-PDU is sent by a subagent to make the master agent forward a notification 🫶.
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (12) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(n.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(n.vb)
...An agentx-Notify-PDU contains these fields:
n.context: an optional, non-default context ✨n.vb: a VarBindList whose contents define the actual PDU to be sent. This memo puts these restrictions on what goes in there, so pay attention 👑:- If the subagent supplies sysUpTime.0, it must be present as the first varbind.
- snmpTrapOID.0 must be present, as the second varbind if sysUpTime.0 was supplied, as the first if it was not.
6.2.11 The agentx-Ping-PDU 🧚
The agentx-Ping-PDU is sent by a subagent to the master agent so it can check that the master agent is able to receive and send AgentX PDUs over their AgentX session 🍓.
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (13) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(p.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+An agentx-Ping-PDU may contain this field:
p.context: an optional, non-default context 🌈
Using p.context, a subagent can retrieve the sysUpTime value for a specific context, if it needs to 🦋.
6.2.12. The agentx-IndexAllocate-PDU 🍭
An agentx-IndexAllocate-PDU is sent by a subagent to request allocation of a value for specific index objects. Refer to section 7.1.3 (Using the agentx-IndexAllocate-PDU) for suggested usage 🧠.
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (14) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(i.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(i.vb)
...An agentx-IndexAllocate-PDU contains these fields:
i.context: an optional, non-default context 💜i.vb: a VarBindList containing the index names and values requested for allocation 🎯
6.2.13. The agentx-IndexDeallocate-PDU 🫧
An agentx-IndexDeallocate-PDU is sent by a subagent to release index values that were allocated earlier 🙌.
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (15) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(i.context) OPTIONAL
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(i.vb)
...An agentx-IndexDeallocate-PDU contains these fields:
i.context: an optional, non-default context 🍀i.vb: a VarBindList containing the index names and values to be released 🌷
6.2.14. The agentx-AddAgentCaps-PDU ✨
okay so this is the PDU a subagent sends to tell the master agent what it's capable of 💅 it's basically the subagent going "hey, this is what I support, can you put it on your list?" 🦋
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (16) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(a.context) (OPTIONAL)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Optional Padding |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(a.id)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(a.descr)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Optional Padding |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+An agentx-AddAgentCaps-PDU has these fields, bestie 🎀
a.context- An optional non-default context.
a.id- An Object Identifier holding the value of an invocation of the AGENT-CAPABILITIES macro 🧚 the master agent exports that as a value of sysORID for the indicated context. (Quick reminder: the value of an AGENT-CAPABILITIES invocation is an object identifier describing a precise level of support for the implemented MIB modules. The full scoop on the AGENT-CAPABILITIES macro and related sysORID values is in section 6 of RFC 1904 [10].)
a.descr- An Octet String containing a DisplayString, used as the value of sysORDescr for the sysORID above. 💜
6.2.15. The agentx-RemoveAgentCaps-PDU ✨
so this one is the opposite energy 💀 a subagent uses it to ask the master agent to stop exporting a particular sysORID. and that sysORID must previously have been advertised by the subagent in an agentx-AddAgentCaps-PDU, no skipping steps 🙅♀️
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (17) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(a.context) (OPTIONAL)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Optional Padding |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(a.id)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+An agentx-RemoveAgentCaps-PDU has these fields 🌸
a.context- An optional non-default context.
a.id- An ObjectIdentifier holding the value of sysORID that should no longer be exported. 🥀
6.2.16. The agentx-Response-PDU ✨
and here's the reply PDU, the one that comes back with the receipts 🧾 ngl it's kind of the main character of the whole protocol 👑
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (18) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| res.sysUpTime |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| res.error | res.index |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...An agentx-Response-PDU has these fields, and they're a lot 🫶
h.sessionID- If this is a response to an agentx-Open-PDU, it carries the new and unique sessionID (assigned by the master agent) for this session. 🎉
- Otherwise, it must be identical to the h.sessionID value in the PDU this PDU is responding to.
h.transactionID- It must be identical to the h.transactionID value in the PDU this PDU is responding to.
- In an agentx response PDU from the master agent to the subagent, the value of h.transactionID has no significance and can be ignored by the subagent. 🙈
h.packetID- It must be identical to the h.packetID value in the PDU this PDU is responding to.
res.sysUpTime- This field holds the current value of sysUpTime for the indicated context. It only matters in agentx response PDUs sent from the master agent to a subagent in response to these agentx PDUs:
agentx-Open-PDU (1),
agentx-Close-PDU (2),
agentx-Register-PDU (3),
agentx-Unregister-PDU (4),
agentx-Ping-PDU (13),
agentx-IndexAllocate-PDU (14),
agentx-IndexDeallocate-PDU (15),
agentx-AddAgentCaps-PDU (16),
agentx-RemoveAgentCaps-PDU (17)- In an agentx response PDU from the subagent to the master agent, the value of res.sysUpTime has no significance and is ignored by the master agent. 💅
res.error- Indicates error status, including
noError. The values are limited to those defined for errors in the SNMPv2 SMI (RFC 1905 [4]), plus these AgentX-specific ones:
- Indicates error status, including
openFailed (256),
notOpen (257),
indexWrongType (258),
indexAlreadyAllocated (259),
indexNoneAvailable (260),
indexNotAllocated (261),
unsupportedContext (262),
duplicateRegistration (263),
unknownRegistration (264),
unknownAgentCaps (265)res.index- In error cases, this is the index of the failed variable binding within a received request PDU. (Note: as explained in section 5.4, Value Representation, the index values of variable bindings within a variable binding list are 1-based. 🔢)
A VarBindList may follow these last two fields, depending on which AgentX PDU is being responded to. The subsequent elements of procedure spell out the details. 🧚
7. Elements of Procedure ✨
okay this section is where we get into the actual rules for how the protocol entities (master agents and subagents) behave 🎀 quick disclaimer though: it is not intended to constrain the internal architecture of any conformant implementation, so your code can be as chaotic on the inside as you want 😭
Specific error conditions and their actions are described in various places. Any other error conditions that aren't specifically mentioned fall into one of two categories: "parse" errors and "protocol" errors. 🫠
A parse error happens when a receiving entity cannot decode the PDU. For instance, a VarBind contains an unknown type, or a PDU contains a malformed Object Identifier. 💀
A protocol error happens when a receiving entity can parse a PDU, but the resulting data is unspecified. For instance, an agentx-Response-PDU is successfully parsed but contains an unknown res.error value. 🙃
An implementation may choose either to ignore such messages, or to close the session on which they were received, using the appropriate reason code defined in the agentx-Close-PDU. ✨
The actions of AgentX protocol entities fall broadly under two headings, each described separately:
(1) processing AgentX administrative messages (e.g., connection requests from a subagent to a master agent); and
(2) processing SNMP messages (the coordinated actions of a master agent and one or more subagents in processing, for example, a received SNMP GetRequest-PDU). 🌈
7.1. Processing AgentX Administrative Messages ✨
okay so this part is all the admin paperwork 📋💅 It covers the messages that open and close an AgentX session between a subagent and a master agent, the ones where a subagent asks for instance index values, and the ones where a subagent tells the master agent which MIB regions it supports. Not the most glamorous stuff, but it's the foundation everything else sits on 🫶
7.1.1. Processing the agentx-Open-PDU 🦋
okay so when the master agent gets an agentx-Open-PDU, here's how it handles it 💖
- an agentx-Response-PDU gets created, and res.sysUpTime is set to the value of
sysUpTime.0for the indicated context 🕰️ - if the master agent can't open an AgentX session for any reason, it may refuse the session request. It sends back the agentx-Response-PDU with res.error set to `openFailed'. 🙅♀️
- otherwise, the master agent gives the new session a sessionID and puts it in the h.sessionID field of the agentx-Response-PDU. This value MUST be unique among all the currently open sessions. ✨
Wait, correction on my end: the original says this value "must" be unique, so I'm keeping that lowercase, bestie. Here it is exactly as written: this value must be unique among all existing open sessions. 🎀
- the master agent holds on to some session-specific info from the PDU for this subagent 🧠
- the NETWORK_BYTE_ORDER value in h.flags gets retained. Every AgentX operation the master agent starts for this session has to use that byte ordering and set the bit to match. 🌸
the subagent usually sets this bit to match its own native byte ordering, and it usually doesn't change the byte ordering for a session it started. the master agent must be able to decode each PDU using the h.flag NETWORK_BYTE_ORDER bit in that PDU. it doesn't need to flip its saved value if the subagent changes its byte ordering. 🔄
- the o.timeout value is used to work out the response timeout conditions for this subagent ⏰
- the o.id and o.descr fields are just for information 📝 (the details of that are up to each implementation for now, and they might get used in a future standard AgentX MIB 🔮)
- the agentx-Response-PDU goes out with res.error set to `noError'. 🎉
at this point the AgentX session counts as established between the master agent and the subagent 🥂 An AgentX session is its own private channel for swapping AgentX protocol messages between one master agent and one subagent. It's defined by the session-specific attributes from step 4 above 💜 The subagent is the one that starts session establishment, but either the master agent or the subagent can end a session 🙌
7.1.2. Processing the agentx-IndexAllocate-PDU 🌈
okay, so when the master agent gets an agentx-IndexAllocate-PDU, it runs through this 🧚
- an agentx-Response-PDU gets created, and res.sysUpTime is set to the value of
sysUpTime.0for the default context 🕰️ - if h.sessionID doesn't match a session that's currently established with this subagent, the agentx-Response-PDU is sent back with res.error set to `notOpen'. 🚫
- if the NON_DEFAULT_CONTEXT bit is set, and the master agent only supports a default context, the agentx-Response-PDU comes back with res.error set to
unsupportedContext'. The requested allocation fails 💀 Otherwise, res.sysUpTime is set to the value ofsysUpTime.0` for the indicated context ✨ - every VarBind in the VarBindList gets processed, until either they all succeed or one of them fails 🍓 If any VarBind fails, the agentx-Response-PDU is sent back with the original VarBindList in it. res.index is set to point at the VarBind that failed, and res.error gets set as described below. All the other VarBinds get ignored, and no index values get allocated 🙈
here's how each VarBind gets handled:
- v.name is the name of the index that a value is being allocated for 🏷️
- v.type is the syntax of the index object 🧩
- v.data is the specific index value that was requested. If the NEW_INDEX or the ANY_INDEX bit is set, the actual value in v.data gets ignored, and the master agent makes up an appropriate index value instead 🪄
a) if there are no index values currently allocated for v.name in the indicated context, and v.type doesn't match a valid index type value, the VarBind fails and res.error is set to indexWrongType'. 🙅♀️ b) if there ARE index values currently allocated for v.name in the indicated context, but their syntax doesn't match v.type, the VarBind fails and res.error is set to indexWrongType'. 😬 c) otherwise, if both the NEW_INDEX and ANY_INDEX bits are clear, a specific index value is being asked for. If that requested index is already allocated for v.name in the indicated context, the VarBind fails and res.error is set to indexAlreadyAllocated'. 👯 d) otherwise, if the NEW_INDEX bit is set, the master agent should generate the next available index value for v.name in the indicated context. This value must not have been allocated to any subagent since the last re-initialization of the master agent, even if it was allocated and then released later. If no such value can be made, the VarBind fails and res.error is set to indexNoneAvailable'. 🧁 e) otherwise, if the ANY_INDEX bit is set, the master agent should generate an index value for v.name in the indicated context. This value must not be currently allocated to any subagent. If no such value can be made, the VarBind fails and res.error is set to `indexNoneAvailable'. 🌟
- if every VarBind gets processed successfully, the agentx-Response-PDU is sent back with res.error set to `noError'. It includes a VarBindList that matches the one from the agentx-IndexAllocate-PDU, except that any VarBinds asking for a NEW_INDEX or ANY_INDEX value now come back with a proper value filled in 🎀
7.1.3. Using the agentx-IndexAllocate-PDU ✨
Okay so index allocation is a service that the AgentX master agent provides 💅 It's giving generic support for sharing MIB conceptual tables between subagents who are assumed to have zero clue about each other 🙈
Each subagent sharing a table should first request allocation of index values, then use those index values to qualify MIB regions in its later registrations 🎀
The master agent keeps a database of index objects (OIDs), plus, for each index, the values that have been allocated for it 📚 It has no idea which MIB variables (if any) those index objects represent 🤷♀️
By convention, subagents use the MIB variable listed in the INDEX clause as the index object that needs values allocated 🫶 For tables indexed by multiple variables, values may be allocated for each index (although this is frequently unnecessary; see example 2 below). The subagent may request allocation of:
- a specific index value
- an index value that is not currently allocated
- an index value that has never been allocated
The last two options exist because of the uniqueness and constancy requirements that show up in lots of MIB specifications for arbitrary integer indexes (e.g., ifIndex in the IF MIB (RFC 1573 [11]), snmpFddiSMTIndex in the FDDI MIB (RFC 1285 [12]), or sysApplInstallPkgIndex in the System Application MIB [13]). Subagents needing to share tables that use indexes like these is the main motivation for index allocation in AgentX 👑
Example 1:
A subagent implements an interface and wants to register a single row of the RFC 1573 ifTable. It requests an allocation for the index object ifIndex, for a value that has never been allocated (since ifIndex values must be unique). The master agent returns the value 7.
The subagent now attempts to register row 7 of ifTable by specifying a MIB region in the agentx-Register-PDU of 1.3.6.1.2.1.2.2.1.[1-22].7. If the registration succeeds, no further processing is required. The master agent will dispatch to this subagent correctly ✨
But the registration may fail 😬 Index allocation and MIB region registration are not coupled in the master agent. Some other subagent may have already registered ifTable row 7 without first requesting allocation of the index. The current state of index allocations is not considered when processing registration requests, and the current registry is not considered when processing index allocation requests. If subagents follow the model of "first request allocation of an index, then register the corresponding region", then a successful index allocation request gives a subagent a good hint (but no guarantee) of what it should be able to register.
If the registration failed, the subagent should request allocation of a new index i, and attempt to register ifTable.[1-22].i, until successful 🔁
Example 2:
This same subagent wants to register ipNetToMediaTable rows corresponding to its interface (ifIndex i). Because of the structure of this table, no further index allocation needs to be done. The subagent can register the MIB region ipNetToMediaTable.[1-4].i. It is claiming responsibility for all rows of the table whose value of ipNetToMediaIfIndex is i 🦋
Example 3:
A network device consists of a set of processors, each of which accepts network connections for a unique set of IP addresses 🌈
Further, each processor contains a subagent that implements tcpConnTable. In order to represent tcpConnTable for the entire managed device, the subagents need to share tcpConnTable 💜
In this case, no index allocation needs to be done at all. Each subagent can register a MIB region of tcpConnTable.[1-5].a.b.c.d, where a.b.c.d represents a unique IP address of the individual processor.
Each subagent is claiming responsibility for the region of tcpConnTable where the value of tcpConnLocalAddress is a.b.c.d 🧚
7.1.4. Processing the agentx-IndexDeallocate-PDU 🗑️
When the master agent receives an agentx-IndexDeallocate-PDU, it processes it like this:
- An agentx-Response-PDU is created, and
res.sysUpTimeis set to the value ofsysUpTime.0for the default context. - If
h.sessionIDdoes not correspond to a currently established session with this subagent, the agentx-Response-PDU is sent in reply withres.errorset tonotOpen. - If the
NON_DEFAULT_CONTEXTbit is set, and the master agent supports only a default context, the agentx-Response-PDU is returned withres.errorset tounsupportedContext, and the requested deallocation fails. Otherwise, the value ofres.sysUpTimeis set to the value ofsysUpTime.0for the indicated context. - Each VarBind in the VarBindList is processed until either all are successful, or one fails. If any VarBind fails, the agentx-Response-PDU is sent in reply, containing the original VarBindList, with
res.indexset to indicate the failed VarBind, and withres.errorset as described subsequently. All other VarBinds are ignored, and no index values are released.
VarBinds are processed as follows:
v.nameis the name of the index for which a value is to be releasedv.typeis the syntax of the index objectv.dataindicates the specific index value to be released. TheNEW_INDEXandANY_INDEXbits are ignored.
a) If the index value for the named index is not currently allocated to this subagent, the VarBind fails and res.error is set to indexNotAllocated.
- If all VarBinds are processed successfully,
res.erroris set tonoErrorand the agentx-Response-PDU is sent. A VarBindList is included which is identical to the one sent in the agentx-IndexDeallocate-PDU.
All released index values are now available, and may be used in response to subsequent allocation requests for ANY_INDEX values for the particular index 🎉
7.1.5. Processing the agentx-Register-PDU 📍
When the master agent receives an agentx-Register-PDU, it processes it like this:
- An agentx-Response-PDU is created, and
res.sysUpTimeis set to the value ofsysUpTime.0for the default context. - If
h.sessionIDdoes not correspond to a currently established session with this subagent, the agentx-Response-PDU is sent in reply withres.errorset tonotOpen. - If the
NON_DEFAULT_CONTEXTbit is set, and the master agent supports only a default context, the agentx-Response-PDU is returned withres.errorset tounsupportedContext, and the requested registration fails. Otherwise, the value ofres.sysUpTimeis set to the value ofsysUpTime.0for the indicated context.
Note: Non-default contexts might be added on the fly by the master agent, or the master agent might require such non-default contexts to be pre-configured. The choice is implementation-specific.
- Characterize the request.
If r.region (or any of its set of Object Identifiers, if r.range is non-zero) is exactly the same as any currently registered value of r.region (or any of its set of Object Identifiers), this registration is termed a duplicate region.
If r.region (or any of its set of Object Identifiers, if r.range is non-zero) is a subtree of, or contains, any currently registered value of r.region (or any of its set of Object Identifiers), this registration is termed an overlapping region.
If the NON_DEFAULT_CONTEXT bit is set, this region is to be logically registered within the context indicated by r.context.
Otherwise, this region is to be logically registered within the default context.
A registration that would result in a duplicate region with the same priority and within the same context as that of a current registration is termed a duplicate registration.
- Otherwise, if this is a duplicate registration, the agentx-Response-PDU is returned with
res.errorset toduplicateRegistration, and the requested registration fails. - Otherwise, the agentx-Response-PDU is returned with
res.errorset tonoError.
The master agent adds this region to its registered OID space for the indicated context, to be considered during the dispatching phase for subsequently received SNMP protocol messages.
Note: The following algorithm describes maintaining a set of OID ranges derived from "splitting" registered regions. The algorithm for operational dispatching is also stated in terms of these OID ranges.
These OID ranges are a useful explanatory device, but are not required for a correct implementation.
- If
r.region(R1) is a subtree of a currently registered region (R2), split R2 into 3 new regions (R2a, R2b, and R2c) such that R2b is an exact duplicate of R1. Now remove R2 and add R1, R2a, R2b, and R2c to the master agent's lexicographically ordered set of ranges (the registered OID space). Note: Though the newly-added ranges R1 and R2b are identical in terms of the MIB objects they contain, they are registered by different subagents, possibly at different priorities.
For instance, if subagent S2 registered "ip" (R2 is 1.3.6.1.2.1.4) and subagent S1 subsequently registered "ipNetToMediaTable" (R1 is 1.3.6.1.2.1.4.22), the resulting set of registered regions would be:
1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2)
1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2)
1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1)
1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2)- If
r.region(R1) overlaps one or more currently registered regions, then for each overlapped region (R2), split R1 into 3 new ranges (R1a, R1b, R1c) such that R1b is an exact duplicate of R2. Add R1b and R2 into the lexicographically ordered set of regions. Apply (5) above iteratively to R1a and R1c (since they may overlap, or be subtrees of, other regions).
For instance, given the currently registered regions in the example above, if subagent S3 now registers mib-2 (R1 is 1.3.6.1.2.1), the resulting set of regions would be:
1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3)
1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2)
1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3)
1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2)
1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1)
1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3)
1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2)
1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3)
1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3)Note that at registration time, a region may be split into multiple OID ranges due to pre-existing registrations, or as a result of any subsequent registration. This region splitting is transparent to subagents. Hence, the master agent must always be able to associate any OID range with the information contained in its original agentx-Register-PDU 💖
7.1.5.1. Handling Duplicate OID Ranges 👑
Okay so because of this registration algorithm, you're literally going to end up with duplicate OID ranges (regions of identical MIB objects registered to different subagents) in the master agent's registered OID space 😭 Whenever the master agent's dispatching algorithm (see 7.2.1, Dispatching AgentX PDUs) results in a duplicate OID range, the master agent picks one to use. This one is called the 'authoritative region', and it gets chosen like this:
- Choose the one whose original
agentx-Register-PDUr.regioncontained the most subids, i.e., the most specificr.region. Note: The presence or absence of a range subid has no bearing on how "specific" one object identifier is compared to another. 💅 - If still ambiguous, there were duplicate regions. Choose the one whose original
agentx-Register-PDUspecified the smaller value ofr.priority. 🫶
7.1.6. Processing the agentx-Unregister-PDU 🦋
- An
agentx-Response-PDUis created andres.sysUpTimeis set to the value ofsysUpTime.0for the default context. - If
h.sessionIDdoes not correspond to a currently established session with this subagent, theagentx-Response-PDUis sent in reply withres.errorset tonotOpen'. - If the
NON_DEFAULT_CONTEXTbit is set, and the master agent supports only a default context, theagentx-Response-PDUis returned withres.errorset tounsupportedContext', and the requested unregistration fails. Otherwise: The value ofres.sysUpTimeis set to the value ofsysUpTime.0for the indicated context. - If
u.region,u.priority, and the indicated context do not match an existing registration made during this session, theagentx-Response-PDUis returned withres.errorset tounknownRegistration'. - Otherwise, the
agentx-Response-PDUis sent in reply withres.errorset tonoError', and the previous registration is removed:- The master agent removes
u.regionfrom its registered OID space within the indicated context. If the original region had been split, all such related regions are removed.
- The master agent removes
For instance, given the example registry above, if subagent S2 unregisters "ip", the resulting registry would be: ✨
1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3)
1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3)
1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1)
1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3)
1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3)
1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3)7.1.7. Processing the agentx-AddAgentCaps-PDU 🌸
When the master agent receives an agentx-AddAgentCaps-PDU, it processes it as follows:
- An
agentx-Response-PDUis created andres.sysUpTimeis set to the value ofsysUpTime.0for the default context. - If
h.sessionIDdoes not correspond to a currently established session with this subagent, theagentx-Response-PDUis sent in reply withres.errorset tonotOpen'. - If the
NON_DEFAULT_CONTEXTbit is set, and the master agent supports only a default context, theagentx-Response-PDUis returned withres.errorset tounsupportedContext', and the requested operation fails. Otherwise: The value ofres.sysUpTimeis set to the value ofsysUpTime.0for the indicated context. - Otherwise, the master agent adds the subagent's capabilities information to the sysORTable for the indicated context. An
agentx-Response-PDUis sent in reply withres.errorset tonoError'.
7.1.8. Processing the agentx-RemoveAgentCaps-PDU 🧚
- An
agentx-Response-PDUis created andres.sysUpTimeis set to the value ofsysUpTime.0for the default context. - If
h.sessionIDdoes not correspond to a currently established session with this subagent, theagentx-Response-PDUis sent in reply withres.errorset tonotOpen'. - If the
NON_DEFAULT_CONTEXTbit is set, and the master agent supports only a default context, theagentx-Response-PDUis returned withres.errorset tounsupportedContext', and the requested operation fails. Otherwise: The value ofres.sysUpTimeis set to the value ofsysUpTime.0for the indicated context. - If the combination of
a.idand the optionala.contextdoes not represent a sysORTable entry that was added by this subagent, during this session, theagentx-Response-PDUis returned withres.errorset tounknownAgentCaps'. - Otherwise the master agent deletes the corresponding sysORTable entry and sends in reply the
agentx-Response-PDU, withres.errorset tonoError'.
7.1.9. Processing the agentx-Close-PDU 💜
When the master agent receives an agentx-Close-PDU, it processes it as follows:
- An
agentx-Response-PDUis created andres.sysUpTimeis set to the value ofsysUpTime.0for the default context. - If
h.sessionIDdoes not correspond to a currently established session with this subagent, theagentx-Response-PDUis sent in reply withres.errorset tonotOpen'. - Otherwise, the master agent closes the AgentX session as described below. No
agentx-Response-PDUis sent.- All MIB regions that have been registered during this session are unregistered, as described in 7.1.6.
- All index values allocated during this session are freed, as described in section 7.1.4.
- All sysORID values that were registered during this session are removed, as described in section 7.1.8.
The master agent does not maintain state for closed sessions. If a subagent wishes to re-establish a session after receiving an agentx-Close-PDU, it needs to re-register MIB regions, agent capabilities, etc. 🥹
7.1.10. Detecting Connection Loss 🙈
If a master agent is able to detect (from the underlying transport) that a subagent cannot receive AgentX PDUs, it should close all affected AgentX sessions as described in 7.1.9, step 3). 💀
7.1.11. Processing the agentx-Notify-PDU 🔥
A subagent sending SNMPv1 trap information must map this into (minimally) a value of snmpTrapOID.0, as described in 3.1.2 of RFC 1908 [8].
The master agent processes the agentx-Notify-PDU as follows:
- If
h.sessionIDdoes not correspond to a currently established session with this subagent, anagentx-Response-PDUis sent in reply withres.errorset tonotOpen', andres.sysUpTimeset to the value ofsysUpTime.0for the indicated context. - The VarBindList is parsed. If it does not contain a value for
sysUpTime.0, the master agent supplies the current value ofsysUpTime.0for the indicated context. If the next VarBind (either the first or second VarBind; see section 6.2.10.1) is notsnmpTrapOID.0, the master agent ceases further processing of the notification. - Notifications are sent according to the implementation-specific configuration of the master agent. If SNMPv1 Trap PDUs are generated, the recommended mapping is as described in RFC 2089 [9]. Except in the case of a
notOpen'error as described in (1) above, noagentx-Response-PDUis sent to the subagent when the master agent finishes processing the notification.
7.1.12. Processing the agentx-Ping-PDU 🍓
When the master agent receives an agentx-Ping-PDU, it processes it as follows:
- An
agentx-Response-PDUis created andres.sysUpTimeis set to the value ofsysUpTime.0for the default context. - If
h.sessionIDdoes not correspond to a currently established session with this subagent, theagentx-Response-PDUis sent in reply withres.errorset tonotOpen'. - If the
NON_DEFAULT_CONTEXTbit is set, and the master agent supports only a default context, theagentx-Response-PDUis returned withres.errorset tounsupportedContext'. Otherwise: The value ofres.sysUpTimeis set to the value ofsysUpTime.0for the indicated context. - The
agentx-Response-PDUis sent, withres.errorset tonoError'.
If a subagent does not receive a response to its pings, or if it is able to detect (from the underlying transport) that the master agent is not able to receive AgentX messages, then it eventually must initiate a new AgentX session, re-register its regions, etc. 🌈
7.2. Processing Received SNMP Protocol Messages ✨
When an SNMP GetRequest, GetNextRequest, GetBulkRequest, or SetRequest protocol message is received by the master agent, the master agent applies its access control policy.
In particular, for SNMPv1 or SNMPv2c PDUs, the master agent applies the Elements of Procedure defined in section 4.1 of RFC 1157 [6] that apply to receiving entities. (For other versions of SNMP, the master agent applies the access control policy defined in the Elements of Procedure for those versions.) In the SNMPv1 or v2c frameworks, the master agent uses the community string as an index into a local repository of configuration information that may include community profiles or more complex context information.
If application of the access control policy results in a valid SNMP request PDU, then an SNMP Response-PDU is constructed from information gathered in the exchange of AgentX PDUs between the master agent and one or more subagents. Upon receipt and initial validation of an SNMP request PDU, a master agent uses the procedures described below to dispatch AgentX PDUs to the proper subagents, marshal the subagent responses, and construct an SNMP response PDU. 💖
7.2.1. Dispatching AgentX PDUs ✨
okay bestie, so once a master agent has given an SNMP request PDU its first check 💅, it uses the steps below to send AgentX PDUs to the right subagents 🦋
Note: In the following procedures, an object identifier is said to be "contained" within an OID range when both of the following are true:
- The object identifier does not lexicographically precede the range.
- The object identifier lexicographically precedes the end of the range.
General Rules of Procedure 🌸
While processing one SNMP request, the master agent may send one or more AgentX PDUs to one or more subagents. These rules apply to the AgentX master agent in general. PDU-specific rules are listed in the sections that cover each PDU 💜
- Honoring the registry
Because AgentX supports overlapping registrations, the master agent can get a value for a requested varbind from inside several registered MIB regions 👀
The master agent MUST ensure that the value (or exception) actually returned in the SNMP response PDU comes from the authoritative region (as defined in section 7.1.5.1). no cap, this is the main character rule 👑
- GetNext and GetBulk Processing
The master agent MAY choose to send agentx-Get-PDUs while servicing an SNMP GetNextRequest-PDU. The master agent MAY choose to send agentx-Get-PDUs or agentx-GetNext-PDUs while servicing an SNMP GetBulkRequest-PDU. One reason this could happen is if the current iteration has targeted instance-level registrations 🧚
The master agent MAY choose to "scope" the possible instances returned by a subagent by specifying an ending OID in the SearchRange. If scoping is used, the ending OID would typically be the first lexicographical successor to the target OID range that was registered by a subagent other than the target subagent. Regardless of this choice, rule (1) MUST be obeyed. bestie, this one is non-negotiable 🫶
The master agent MAY require multiple request-response iterations on the same subagent session to figure out the final value of every requested variable 🔥
All AgentX PDUs sent on the session while processing a given SNMP request MUST contain identical values of transactionID. Each different SNMP request processed by the master agent MUST present a unique value of transactionID (within the limits of the 32-bit field) to the session 🎀
- Number and order of variables sent per AgentX PDU
For Get/GetNext/GetBulk operations, at any stage of the process (which can be iterative), the master agent MAY need to dispatch several SearchRanges to a particular subagent session. The master agent MAY send one, some, or all of the SearchRanges in a single AgentX PDU 🍓
The master agent MUST ensure that the correct contents and ordering of the VarBindList in the SNMP Response-PDU are maintained 💖
The following rules govern the number of VarBinds in a given AgentX PDU:
a) The subagent MUST support processing of AgentX PDUs with multiple VarBinds. literally required, no exceptions 😭
b) When processing an SNMP Set request, the master agent MUST send all of the VarBinds applicable to a particular subagent session in a single Test/Set transaction.
c) When processing an SNMP Get, GetNext, or GetBulk request, the master agent MAY send a single AgentX PDU to the subagent with all applicable VarBinds, or multiple PDUs with single VarBinds, or something in between those extremes. Which method to use in a particular case is implementation-specific 🌈
- Timeout Values
The master agent chooses a timeout value for each MIB region being queried, which is:
a) the value specified during registration of the MIB region, if it was non-zero
b) otherwise, the value specified during establishment of the session in which this region was subsequently registered, if that value was non-zero.
c) otherwise, the master agent's default value
When an AgentX PDU that references multiple MIB regions is dispatched, the timeout value used for the PDU is the maximum value of the timeouts determined for each of the referenced MIB regions ⏰
- Context
If the master agent has determined that a specific non-default context is associated with the SNMP request PDU, that context is encoded into the AgentX PDU's context field, and the NON_DEFAULT_CONTEXT bit is set in h.flags ✨
Otherwise, no context Octet String is added to the PDU, and the NON_DEFAULT_CONTEXT bit is cleared 🙈
7.2.1.1. agentx-Get-PDU 🌷
Each variable binding in the SNMP request PDU is processed as follows:
(1) Identify the target OID range.
Within a lexicographically ordered set of OID ranges, valid for the indicated context, locate the authoritative region that contains the binding's name.
(2) If no such OID range exists, the variable binding is not processed further, and its value is set to noSuchObject.
(3) Identify the subagent session in which this region was registered, termed the target session.
(4) If this is the first variable binding to be dispatched over the target session in a request-response exchange entailed in the processing of this management request:
- Create an agentx-Get-PDU for this session, with the header fields initialized as described above (see 6.1 AgentX PDU Header).
(5) Add a SearchRange to the end of the target session's PDU for this variable binding.
- The variable binding's name is encoded into the starting OID.
- The ending OID is encoded as null.
7.2.1.2. agentx-GetNext-PDU 🦋
Each variable binding in the SNMP request PDU is processed as follows:
(1) Identify the target OID range.
Within a lexicographically ordered set of OID ranges, valid for the indicated context, locate
a) the authoritative OID range that contains the variable binding's name and is not a fully qualified instance, or
b) the authoritative OID range that is the first lexicographical successor to the variable binding's name.
(2) If no such OID range exists, the variable binding is not processed further, and its value is set to endOfMibView.
(3) Identify the subagent session in which this region was registered, termed the target session.
(4) If this is the first variable binding to be dispatched over the target session in a request-response exchange entailed in the processing of this management request:
- Create an agentx-GetNext-PDU for the session, with the header fields initialized as described above (see 6.1 AgentX PDU Header).
(5) Add a SearchRange to the end of the target session's agentx-GetNext-PDU for this variable binding.
- if (1a) applies, the variable binding's name is encoded into the starting OID, and the OID's "include" field is set to 0.
- if (1b) applies, the target OID is encoded into the starting OID, and its "include" field is set to 1.
7.2.1.3. agentx-GetBulk-PDU 💫
(Note: The outline of the following procedure is based closely on section 4.2.3, "The GetBulkRequest-PDU" of RFC 1905 [4]. Please refer to it for details on the format of the SNMP GetBulkRequest-PDU itself.)
Each variable binding in the request PDU is processed as follows:
(1) Identify the authoritative target OID range and target session, exactly as described for the agentx-GetNext-PDU (see 7.2.1.2).
(2) If this is the first variable binding to be dispatched over the target session in a request-response exchange entailed in the processing of this management request:
- Create an agentx-GetBulk-PDU for the session, with the header fields initialized as described above (see 6.1 AgentX PDU Header).
(3) Add a SearchRange to the end of the target session's agentx-GetBulk-PDU for this variable binding, as described for the agentx-GetNext-PDU. If the variable binding was a non-repeater in the original request PDU, it MUST be a non-repeater in the agentx-GetBulk-PDU. non-repeaters stay non-repeaters, periodt 🙅♀️
The value of g.max_repetitions in the agentx-GetBulk-PDU MAY be less than (but not greater than) the value in the original request PDU.
The master agent MAY make such alterations due to simple sanity checking, optimizations for the current iteration based on the registry, the maximum possible size of a potential Response-PDU, known constraints of the AgentX transport, or any other implementation-specific constraint 🍓
7.2.1.4. agentx-TestSet-PDU 🎀
AgentX uses test-commit-undo-cleanup phases to get "as if simultaneous" semantics for the SNMP SetRequest-PDU within the extensible agent. The first phase is the agentx-TestSet-PDU 💅
Each variable binding in the SNMP request PDU is processed in order, as follows:
(1) Identify the target OID range.
Within a lexicographically ordered set of OID ranges, valid for the indicated context, locate the authoritative range that contains the variable binding's name.
(2) If no such OID range exists, this variable binding fails with an error of notWritable. Processing is complete for this request.
(3) Identify the single subagent responsible for this OID range, termed the target subagent, and the applicable session, termed the target session.
(4) If this is the first variable binding to be dispatched over the target session in a request-response exchange entailed in the processing of this management request:
- create an agentx-TestSet-PDU for the session, with the header fields initialized as described above (see 6.1 AgentX PDU Header).
(5) Add a VarBind to the end of the target session's PDU for this variable binding, as described in section 5.4.
Note that all VarBinds applicable to a given session MUST be sent in a single agentx-TestSet-PDU. one PDU per session, bestie, don't split it 🫶
7.2.1.5. Dispatch 🚀
A timeout value is calculated for each PDU to be sent. It is the maximum value of the timeouts determined for each of the PDU's SearchRanges (as described above in 7.2.1 Dispatching AgentX PDUs, item 4). Each pending PDU is mapped (via its h.sessionID value) to a particular transport domain/endpoint, as described in section 8 (Transport Mappings) 🦋
7.2.2. Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs 🧚
A conformant AgentX subagent MUST support the agentx-Get, -GetNext, and -GetBulk PDUs, and MUST support multiple variables being supplied in each PDU. that's the baseline, babe 💖
When a subagent receives an agentx-Get-, GetNext-, or GetBulk-PDU, it performs the indicated management operations and returns an agentx-Response-PDU 📬
The agentx-Response-PDU header fields are identical to the received request PDU, except that at the start of processing, the subagent initializes h.type to Response, res.error to noError, res.index to 0, and the VarBindList to null.
Each SearchRange in the request PDU's SearchRangeList is processed as described below, and a VarBind is added in the corresponding location of the agentx-Response-PDU's VarbindList. If processing should fail for any reason not described below, res.error is set to genErr, res.index is set to the index of the failed SearchRange, the VarBindList is reset to null, and this agentx-Response-PDU is returned to the master agent 😭
7.2.2.1. Subagent Processing of the agentx-Get-PDU 💖
Okay so, when the subagent gets an agentx-Get-PDU, it goes through every SearchRange in the request one by one, like a checklist 📋:
(1) It copies the starting OID into v.name 🦋
(2) If that starting OID exactly matches the name of a variable this subagent has instantiated (inside the given context and session), it encodes v.type and v.data to show that variable's syntax and value. Section 5.4, Value Representation, explains how. ✨
(3) Otherwise, if the starting OID doesn't match the object identifier prefix of any variable instantiated in that context and session, the VarBind gets set to `noSuchObject'. The way to do that is in section 5.4, Value Representation. 🙈
(4) Otherwise, the VarBind gets set to `noSuchInstance'. Same vibe, section 5.4, Value Representation. 💀
7.2.2.2. Subagent Processing of the agentx-GetNext-PDU 🧚
Next up, the agentx-GetNext-PDU. Again, each SearchRange in the request gets processed, and this one is a bit of a treasure hunt 🗺️
(1) The subagent searches the lexicographically ordered list of variable names for every variable it instantiates (and it doesn't care about region registration here) inside the indicated context and session. It's looking for a variable where all of these are true:
- If the
"include"field of the starting OID is 0, the variable's name is the closest lexicographical successor to the starting OID. - If the
"include"field of the starting OID is 1, the variable's name is either equal to, or the closest lexicographical successor to, the starting OID. - If the ending OID is not null, the variable's name lexicographically precedes the ending OID.
If all of those conditions are met, v.name gets set to the located variable's name. Then v.type and v.data get encoded to show that variable's syntax and value, as described in section 5.4, Value Representation. 🎀
(2) If no such variable exists, v.name is set to the starting OID, and the VarBind is set to endOfMibView, in the manner described in section 5.4, Value Representation. It's the end of the line, bestie 🌈
7.2.2.3. Subagent Processing of the agentx-GetBulk-PDU 🍓
GetBulk is where things get spicy 🌶️ The maximum number of VarBinds returned is:
N + (M * R)where:
Nequalsg.non_repeatersMequalsg.max_repetitionsRis (number of SearchRanges in the GetBulk request) -N
The first N SearchRanges are processed exactly like an agentx-GetNext-PDU. Easy enough! 💅
If M and R are both non-zero, the remaining R SearchRanges get processed iteratively to make potentially a lot of VarBinds. For each iteration i, where i is greater than zero and less than or equal to M, and for each repeated SearchRange s, where s is greater than zero and less than or equal to R, the (N+((i-1)*R)+s)-th VarBind gets added to the agentx-Response-PDU like this:
- The subagent searches the lexicographically ordered list of variable names for all variables it instantiates (again, without regard to region registration) inside the indicated context and session. It's looking for a variable where all of these are true:
- The variable's name is the
(i)-thlexicographical successor to the(N+s)-threquested OID.
(Note that if i is 0 and the "include" field is 1, the variable's name may be equivalent to, or the first lexicographical successor to, the (N+s)-th requested OID. 🦋)
- If the ending OID is not null, the variable's name lexicographically precedes the ending OID.
If all of these conditions are met, v.name gets set to the located variable's name. Then v.type and v.data get encoded to represent the variable's syntax and value, as described in section 5.4, Value Representation. ✨
- If no such variable exists, the VarBind is set to
endOfMibViewas described in section 5.4, Value Representation.v.nameis set to thev.nameof the(N+((i-2)*R)+s)-thVarBind, unlessiis currently 1. In that case, it's set to the value of the starting OID in the(N+s)-thSearchRange. Little plot twist, but it all checks out 🎀
Further iterative processing should stop if:
- For any iteration
i, allsvalues ofv.typeareendOfMibView. - An AgentX transport constraint or other implementation-specific constraint is reached.
7.2.3. Subagent Processing of agentx-TestSet, -CommitSet, -UndoSet, -CleanupSet-PDUs 🔥
A conformant AgentX subagent must support the agentx-TestSet, -CommitSet, -UndoSet, and -CleanupSet PDUs, and must support multiple variables being supplied in each PDU. Non-negotiable, periodt 👑
These four PDUs team up to perform the management operation. An agentx-Response-PDU gets sent back in reply to each one, so the master agent knows how the operation is going 🧚
The agentx-Response-PDU header fields are identical to the received request PDU, with one exception. At the start of processing, the subagent sets h.type to Response, res.error to noError, and res.index to 0. Fresh start, no drama 🌸
These Response-PDUs don't contain a VarBindList. Nothing extra to see here 🫶
7.2.3.1. Subagent Processing of the agentx-TestSet-PDU 💜
When the subagent receives an agentx-TestSet-PDU, each VarBind in the PDU gets validated until they're all successful, or until one fails. This follows section 4.2.5 of RFC 1905 [4]. The subagent validates variables with respect to the context and session indicated in the testSet-PDU. ✅
If every VarBind is successful, the subagent also has a further responsibility: it has to make sure all the resources it needs (memory, write access, etc.) are available for a successful agentx-CommitSet operation later on. If it can't guarantee that, the subagent should set res.error to resourceUnavailable. 😭
After this validation step, an agentx-Response-PDU gets sent back. Its res.error field is set to one of these (SNMPv2 SMI) values:
noError (0),
genErr (5),
noAccess (6),
wrongType (7),
wrongLength (8),
wrongEncoding (9),
wrongValue (10),
noCreation (11),
inconsistentValue (12),
resourceUnavailable (13),
notWritable (17),
inconsistentName (18)If this value isn't noError, the res.index field must be set to the index of the VarBind that failed validation. 🙈
Real talk: rigorous validation code might be one of the most demanding parts of building a subagent. Implementors are strongly encouraged to get this right, so the extensible agent doesn't have to return commitFailed or undoFailed during later processing if at all possible. Please do the work now, future you will thank you 💅
7.2.3.2. Subagent Processing of the agentx-CommitSet-PDU 🌈
The agentx-CommitSet-PDU tells the subagent to actually carry out the management operation from the previous TestSet-PDU. This is described in the post-validation sections of 4.2.5 of RFC 1905 [4]. Once it's done, the subagent replies with an agentx-Response-PDU whose res.error field is set to one of these (SNMPv2 SMI) values:
noError (0),
commitFailed (14)If this value is commitFailed, the res.index field must be set to the index of the VarBind for which the operation failed. Otherwise, res.index is set to 0. ⭐
7.2.3.3. Subagent Processing of the agentx-UndoSet-PDU 🦋
The agentx-UndoSet-PDU tells the subagent to undo the management operation requested in a preceding CommitSet-PDU. The undo process is described in section 4.2.5 of RFC 1905 [4]. ✨
After the undo process, the subagent sends back an agentx-Response-PDU whose res.index field is set to 0, and whose res.error field is set to one of these (SNMPv2 SMI) values:
noError (0),
undoFailed (15)If this value is undoFailed, the res.index field must be set to the index of the VarBind for which the operation failed. Otherwise, res.index is set to 0. 🥺
This PDU also wraps up processing of the management operation started by the previous TestSet-PDU. The subagent should release resources, etc., as described in section 7.2.3.4. 🎀
7.2.3.4. Subagent Processing of the agentx-CleanupSet-PDU 🧹
The agentx-CleanupSet-PDU marks the end of processing for the management operation requested in the previous TestSet-PDU. It's basically the subagent's cue that it may now release any resources it reserved to carry out the management request. Bye bye, resources 👋
No response is sent by the subagent. Ghosted, but make it procedural 💀
7.2.4. Master Agent Processing of AgentX Responses 👑
The master agent now marshals all subagent AgentX response PDUs and builds an SNMP response PDU. The next few subsections cover the initial processing of all subagent AgentX response PDUs, followed by the subsequent processing for each specific subagent Response. Step by step, bestie 🫶
7.2.4.1. Common Processing of All AgentX Response PDUs 🌸
(1) If a subagent doesn't respond within the timeout interval for this dispatch, it's treated as if the subagent had returned genErr, and it gets processed as described below.
A timeout can happen for a bunch of reasons, and it doesn't necessarily mean the subagent failed or is malfunctioning. So the master agent's response to a subagent timeout is implementation-specific, but with this constraint:
A subagent that times out on three consecutive requests is considered unable to respond, and the master agent must close the AgentX session as described in 7.1.9, step (2). 🚫
(2) Otherwise, the h.packetID, h.sessionID, and h.transactionID fields of the AgentX response PDU are used to correlate subagent responses. If the response doesn't pertain to this SNMP operation, it's ignored. 🧚
(3) Otherwise, the responses are processed jointly to form the SNMP response PDU. Teamwork makes the dream work 💖
7.2.4.2. Processing of Responses to agentx-Get-PDUs 🔍
After the common processing of the subagent's response to an agentx-Get-PDU (see 7.2.4.1 above), processing continues with these steps:
(1) For any received AgentX response PDU, if res.error is not noError, the SNMP response PDU's error code is set to this value, and its error index is set to the index of the variable binding that matches the failed VarBind in the subagent's AgentX response PDU. 😭
All other AgentX response PDUs received because of this SNMP request are ignored. Processing is complete, and the SNMP Response PDU is ready to be sent (see section 7.2.5, Sending the SNMP Response-PDU). Mission accomplished ✨
(2) Otherwise, the content of each VarBind in the AgentX response PDU is used to update the corresponding variable binding in the SNMP Response-PDU. Glow-up complete 🌈
7.2.4.3. Processing of Responses to agentx-GetNext-PDU and agentx-GetBulk-PDU
okay bestie, so after the common processing of the subagent's reply to an agentx-GetNext-PDU or agentx-GetBulk-PDU (see 7.2.4.1 above), things get spicy 🌶️ and processing keeps going with these steps:
- For any received AgentX response PDU, if res.error is not `noError', the SNMP response PDU's error code is set to this value, and its error index is set to the index of the VarBind matching the failed VarBind in the subagent's AgentX response PDU. 🚨
All other AgentX response PDUs received because of this SNMP request get ignored 🙅♀️. Processing is complete, and the SNMP response PDU is ready to be sent (see section 7.2.5, Sending the SNMP Response PDU) ✨.
- Otherwise, the content of each VarBind in the AgentX response PDU is used to update the matching VarBind in the SNMP response PDU 💕.
After all the expected AgentX response PDUs have been processed, if any VarBinds still have the value `endOfMibView' in their v.type fields, processing must continue 🫶:
- A new iteration of AgentX request dispatching starts (as described in section 7.2.1.1). This time, only the VarBinds whose v.type is `endOfMibView' get processed 🔁.
- For each of those VarBinds, a target OID range is identified. It's the lexicographical successor to the target OID range that this VarBind had on the last iteration 🦋. The target subagent is the one that registered that target OID range, and the target session is the one where it was registered.
If an agentx-GetNext- or GetBulk-PDU is being dispatched, the starting OID in the SearchRanges is set to the target OID range, and its "include" field is set to 1 🌸.
- The value of transactionID must be identical to the value used during the previous iteration 🔐.
- The AgentX PDUs go out to the subagent(s), and the responses come back and get processed according to the steps in section 7.2.4 📬.
- This keeps going iteratively until a complete SNMP Response-PDU has been built, or until there are no target OID range lexicographical successors left 🏁.
7.2.4.4. Processing of Responses to agentx-TestSet-PDUs
after the common processing of the subagent's response to an agentx-TestSet-PDU (see 7.2.4.1 above), processing carries on with more AgentX PDU exchanges 💌. The value of h.transactionID in the agentx-CommitSet, -UndoSet, and -CleanupSet-PDUs must be identical to the value sent in the testSet-PDU 🔑.
The state transitions and PDU sequences are drawn out in section 7.3, so go check that out if you're a visual learner 👀✨.
- If any target subagent's response is not `noError', all other agentx-Response-PDUs received because of this SNMP request get ignored 🙈.
An agentx-CleanupSet-PDU is sent to each target subagent that was sent an agentx-TestSet-PDU 🧹.
Processing is complete, and the SNMP response PDU is constructed as described below in 7.2.4.6 💖.
- Otherwise, an agentx-CommitSet-PDU is sent to each target subagent 🚀.
7.2.4.5. Processing of Responses to agentx-CommitSet-PDUs
after the common processing of the subagent's response to an agentx-CommitSet-PDU (see 7.2.4.1 above), processing keeps going with these steps 💅:
- If any response is not `noError', all other agentx-Response-PDUs received because of this SNMP request get ignored 🙅♀️.
An agentx-UndoSet-PDU is sent to each target subagent that was sent an agentx-CommitSet-PDU. All other subagents get an agentx-CleanupSet-PDU 🧼.
- Otherwise, an agentx-CleanupSet-PDU is sent to each target subagent. Processing is complete, and the SNMP response PDU is constructed as described below in 7.2.4.6 🎀.
7.2.4.6. Processing of Responses to agentx-UndoSet-PDUs
after the common processing of the subagent's response to an agentx-UndoSet-PDU (see 7.2.4.1 above), processing continues with these steps 🌈:
- If any response is not `noError', the SNMP response PDU's error code is set to this value, and its error index is set to the index of the VarBind matching the failed VarBind in the agentx-TestSet-PDU 😬.
Otherwise, the SNMP response PDU's error code is set to `noError' and its error index is set to 0 🥰.
7.2.5. Sending the SNMP Response-PDU
once the processing in sections 7.2.1 - 7.2.4 is complete, there's an SNMP response PDU ready to go 📦. The master agent now follows the Elements of Procedure for the applicable version of the SNMP protocol to wrap the PDU into a message, and then sends it back to the originator of the SNMP management request 💌. Heads up: this might mean changing the PDU contents, like swapping out the original VarBinds when an error condition needs to be returned 🙃.
The response PDU may also be altered so it supports the SNMP version 1 framework ✨. In that case, the required mapping is the one defined in RFC 2089 [9]. (Note in particular that the rules for handling Counter64 syntax may require re-sending AgentX GetBulk or GetNext PDUs until a VarBind of suitable syntax is returned 🔁😭.)
7.2.6. MIB Views
AgentX subagents don't know about MIB views, since view information isn't contained in AgentX PDUs 🙈.
As stated above, the procedure descriptions in section 7 of this memo are not meant to constrain the internal architecture of any conformant implementation 🏗️. In particular, the master agent procedures described in sections 7.2.1 and 7.2.4 may be altered so as to optimize AgentX exchanges when implementing MIB views 🦋.
Those optimizations are beyond the scope of this memo. But note that section 7.2.3 defines subagent behavior in a way that lets alteration of SearchRanges be used in such optimizations 💜.
7.3. State Transitions
State diagrams are presented from the master agent's perspective for transport connection and session establishment, and from the subagent's perspective for Set transaction processing 📊✨.
7.3.1. Set Transaction States
the following table shows, from the subagent's perspective, the state transitions involved in Set transaction processing 🧩:
STATE
+----------------+--------------+---------+--------+--------
| A | B | C | D | E
| (Initial | TestOK | Commit | Test | Commit
| State) | | OK | Fail | Fail
| | | | |
EVENT | | | | |
---------+----------------+--------------+---------+--------+--------
| 7.2.3.1 | | | |
Receive | All varbinds | | | |
TestSet | OK? | X | X | X | X
PDU | Yes ->B | | | |
| No ->D | | | |
---------+----------------+--------------+---------+--------+--------
| | 7.2.3.2 | | |
Receive | | NoError? | | |
Commit- | X | Yes ->C | X | X | X
Set PDU | | No ->E | | |
---------+----------------+--------------+---------+--------+--------
Receive | | | 7.2.3.3 | |7.2.4.5
UndoSet | X | X | ->done | X | ->done
PDU | | | | |
---------+----------------+--------------+---------+--------+--------
Receive | | 7.2.4.4 | 7.2.3.4 |7.2.4.4 |
Cleanup- | X | ->done | ->done | ->done | X
Set PDU | | | | |
---------+----------------+--------------+---------+--------+--------
Session | | rollback | undo | |
Loss | ->done | ->done | ->done | ->done | ->done
---------+----------------+--------------+---------+--------+--------there are three possible sequences that a subagent may follow for a particular set transaction 🎢:
1) TestSet CommitSet CleanupSet
2) TestSet CommitSet UndoSet
3) TestSet CleanupSetNote that a single PDU sequence can take multiple paths through the finite state machine (FSM) 🌀. For example, the sequence
TestSet CommitSet UndoSetmay walk through either of these two state sequences 👯♀️:
(initial) TestOK CommitOK (done)
(initial) TestOK CommitFail (done)7.3.2. Transport Connection States
the following table shows, from the master agent's perspective, the state transitions involved in transport connection setup and teardown 🚪💫:
STATE
+--------------+--------------
| A | B
| No transport | Transport
| | connected
| |
EVENT | |
----------------+--------------+--------------
Transport | |
connect | ->B | X
indication | |
----------------+--------------+--------------
Receive | | if duplicate
Open-PDU | | session id,
| | reject, else
| X | establish
| | session
| |
| | ->B
----------------+--------------+--------------
Receive | | if matching
Response-PDU | | session id,
| | feed to that
| X | session's FSM
| | else ignore
| |
| | ->B
----------------+--------------+--------------
Receive other | | if matching
PDUs | | session id,
| | feed to that
| X | session's FSM
| | else reject
| |
| | ->B
----------------+--------------+--------------
Transport | |notify all
disconnect | |sessions on
indication | X |this transport
| |
| | ->A
----------------+--------------+--------------7.3.3. Session States 🧚
Okay so this table is giving session setup and teardown from the master agent's point of view. Read it left to right, one event at a time 💅
STATE
+-------------+----------------
| A | B
| No session | Session
| | established
EVENT | |
---------------+-------------+----------------
| 7.1.1 |
Receive | | X
Open PDU | ->B |
---------------+-------------+----------------
| | 7.1.9
Receive | X |
Close PDU | | ->A
---------------+-------------+----------------
Receive | | 7.1.5
Register PDU | X |
| | ->B
---------------+-------------+----------------
Receive | | 7.1.6
Unregister | X |
PDU | | ->B
---------------+-------------+----------------
Receive | |
Get PDU | |
GetNext PDU | |
GetBulk PDU | X | X
TestSet PDU | |
CommitSet PDU | |
UndoSet PDU | |
CleanupSet PDU | |
---------------+-------------+----------------
Receive | | 7.1.11
Notify PDU | X |
| | ->B
---------------+-------------+----------------
Receive Ping | | 7.1.12
PDU | X |
| | ->B
---------------+-------------+----------------
(continued next page)
---------------+-------------+----------------
Receive | | 7.1.2
IndexAllocate | X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.4
IndexDeallocate| X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.7
AddAgentxCaps | X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.8
RemoveAgentxCap| X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.2.4
Response PDU | X |
| | ->B
---------------+-------------+----------------
Receive | |
Other PDU | X | X
---------------+-------------+----------------8. Transport Mappings 🚚
The vibe is consistent across the board: the same AgentX PDU formats, encodings, and elements of procedure are used no matter which transport is underneath. ✨
8.1. AgentX over TCP 🌊
8.1.1. Well-known Values
The master agent accepts TCP connection requests on the well-known port 705. Subagents connect to the master agent using this port number. 🔌
8.1.2. Operation
Once a TCP connection is up, the AgentX peers use that connection to carry all AgentX PDUs. One TCP connection can host multiple AgentX sessions. AgentX PDUs get sent within an AgentX session, and the AgentX peers are the ones responsible for mapping the h.sessionID to a particular TCP connection. 🧵
All AgentX PDUs are handed to TCP one at a time, and each one is sent as the data portion of a TCP PDU.
8.2. AgentX over UNIX-domain Sockets 🦋
Lots of (BSD-derived) UNIX systems support the UNIX pathname address family (AF_UNIX) for socket communication. It's a handy way for processes on the same host to send and receive data to each other.
Mapping AgentX onto this transport is useful for environments that:
- wish to guarantee subagents are running on the same managed node as the master agent, and where
- sockets provide better performance than TCP or UDP, especially in the presence of heavy network I/O
8.2.1. Well-known Values
The master agent creates a well-known UNIX-domain socket endpoint called "/var/agentx/master". (It may create other endpoints that are specific to the implementation.) 🗂️
The endpoint name uses the character set encoding that's native to the managed node, and it represents a UNIX-domain stream (SOCK_STREAM) socket.
8.2.2. Operation
Once a connection has been established, the AgentX peers use it to carry all AgentX PDUs.
Multiple AgentX sessions may be established over the same connection. AgentX PDUs are sent within an AgentX session, and the AgentX peers are responsible for mapping the h.sessionID to a particular connection.
All AgentX PDUs are handed to the socket layer one at a time, to be sent in the data stream. 🌊
9. Security Considerations 🔐
Okay, this is the serious section, bestie. Read every word. 🙈
This memo defines a protocol between two processing entities. The master agent is assumed to authenticate received SNMP requests and to control access to management information. The master agent does these security operations on its own, separately from the subagent.
Security considerations come down to three questions:
- Is a particular subagent allowed to initiate a session with a particular master agent?
- During an AgentX session, is any SNMP security-related information (for example, community names) passed from the master agent to the subagent?
- During an AgentX session, what part of the MIB tree is this subagent allowed to register?
The answer to the third question is that a subagent can register any subtree, subject to the AgentX elements of procedure in section 7.1.5. Right now AgentX doesn't define any access control mechanism. The worry here is that a malicious subagent could register an unauthorized "sensitive" subtree. That subagent could then see modification requests aimed at those objects, or give its own clever answers to NMS queries and cause the NMS to do something that leads to information disclosure or other damage. 😱
The answer to the second question is: No.
Now we can answer the first question. AgentX has no mechanism for authorizing or refusing session initiations. That means controlling subagent access to the master agent may only be done at a lower layer (for example, the transport). 🔒
An AgentX subagent can connect to a master agent using either a network transport mechanism (for example, TCP), or a "local" mechanism (for example, shared memory or named pipes).
When a local transport mechanism is used and both the subagent and the master agent are running on the same host, connection authorization can be delegated to operating system features. The answer to the first security question then becomes: "If and only if the subagent has sufficient privileges, then the operating system will allow the connection".
If a network transport is used, there is currently no inherent security. Transport Layer Security or SSL could be used to control subagent connections, but that is beyond the scope of this document. 💀
So it is recommended that subagents always run on the same host as the master agent, and that operating system features be used to ensure that only properly authorized subagents can establish connections to the master agent. 🫶
10. Acknowledgements 💜
The initial development of this memo was heavily influenced by the DPI 2.0 specification, RFC 1592 [7].
This document was produced by the IETF Agent Extensibility (AgentX) Working Group, and it especially benefited from the contributions of these working group members: David Battle, Uri Blumenthal, Jeff Case, Maria Greene, Dave Keeney, Harmen van der Linde, Bob Natale, Randy Presuhn, Aleksey Romanov, Don Ryan, and Juergen Schoenwaelder. 🌸
The AgentX Working Group is chaired by:
Bob Natale
ACE*COMM Corporation
704 Quince Orchard Road
Gaithersburg MD 20878
Phone: +1-301-721-3000
Fax: +1-301-721-3001
EMail: bnatale@acecomm.com11. Authors' and Editor's Addresses 💌
Mike Daniele
Digital Equipment Corporation
110 Spit Brook Rd
Nashua, NH 03062
Phone: +1-603-881-1423
EMail: daniele@zk3.dec.com
Bert Wijnen
IBM Professional Services
Watsonweg 2
1423 ND Uithoorn
The Netherlands
Phone: +31-79-322-8316
EMail: wijnen@vnet.ibm.com
Dale Francisco (editor)
Cisco Systems
150 Castilian Dr
Goleta CA 93117
Phone: +1-805-961-3642
Fax: +1-805-961-3600
EMail: dfrancis@cisco.com12. References 📚
[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] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1902, January 1996.
[3] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1903, January 1996.
[4] 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] 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.
[6] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network Management Protocol", STD 15, RFC 1157, SNMP Research, Performance Systems International, MIT Laboratory for Computer Science, May 1990.
[7] Wijnen, B., Carpenter, G., Curran, K., Sehgal, A. and G. Waters, "Simple Network Management Protocol: Distributed Protocol Interface, Version 2.0", RFC 1592, March 1994.
[8] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework", RFC 1908, January 1996.
[9] Wijnen, B. and D. Levi, "V2ToV1: Mapping SNMPv2 onto SNMPv1 Within a Bilingual SNMP Agent", RFC 2089, January 1997.
[10] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1904, January 1996.
[11] McCloghrie, K. and F. Kastenholz, "Evolution of the Interfaces Group of MIB-II", RFC 1573, January 1994.
[12] Case, J., "FDDI Management Information Base", RFC 1285, January 1992.
[13] Application MIB Working Group, Krupczak, C., and J. Saperia, "Definitions of System-Level Managed Objects for Applications", draft-ietf-applmib-sysapplmib-08.txt, 15 Apr 1997.
13. Full Copyright Statement 💖
okay bestie, last stop 🎀 this is the legal bit, so I'm keeping the exact wording so nobody can say we changed the terms 💅
Copyright (C) The Internet Society (1998). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.the vibe check: you can copy and share the doc, and make derivative works that comment on it or explain it 🦋 but you can't edit the doc itself, except for standards work or translation 🫶 those permissions last forever ✨ and the doc comes "AS IS", with no warranties at all 😭 that's the end of the RFC, periodt 🌸
📦 where this page comes from
- ietf: rfc2257 1998-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms