RFC 2741
Agent Extensibility (AgentX) Protocol Version 1
Title Block 📜✨
okay bestie, RFC 2741 is here and it's a whole vibe 🎀 Here's the title block, all the important stuff up top:
- RFC number: 2741
- Title: Agent Extensibility (AgentX) Protocol Version 1
- Authors: M. Daniele (Compaq Computer Corporation); B. Wijnen (T.J. Watson Research Center, IBM Corp.); M. Ellison, Ed. (Ellison Software Consulting, Inc.); D. Francisco. Ed. (Cisco Systems, Inc.)
- Category: Standards Track
- Date: January 2000
- Obsoletes: RFC 2257 💅
- Updates: nothing is listed here
Status of This Memo 🌸
okay so this part is the official "what is this doc even vibe check 🙈 It says this document specifies an Internet standards track protocol for the Internet community, and it asks for discussion and suggestions for improvements. For the standardization state and status of this protocol, you check the current edition of the "Internet Official Protocol Standards" (STD 1). And distribution of this memo is unlimited, so share it as much as you want 🦋
Copyright Notice 🔥
Copyright (C) The Internet Society (2000). All Rights Reserved. Mine? Nope. Theirs. Respect the paperwork 💜
Abstract ✨
this is the elevator pitch bestie 🧚 This memo defines a standardized framework for extensible SNMP agents. It defines processing entities called master agents and subagents, a protocol (AgentX) used to communicate between them, and the elements of procedure by which the extensible agent processes SNMP protocol messages. This memo obsoletes RFC 2257.
Table of Contents 🍓
here's the whole map, copied exactly so nothing gets lost 🗺️
1. Introduction.....................................................4
2. The SNMP Management Framework....................................4
2.1. A Note on Terminology........................................5
3. Extending the MIB................................................5
3.1. Motivation for AgentX........................................6
4. AgentX Framework.................................................6
4.1. AgentX Roles.................................................7
4.2. Applicability................................................8
4.3. Design Features of AgentX....................................9
4.4. Non-Goals...................................................10
5. AgentX Encodings................................................11
5.1. Object Identifier...........................................11
5.2. SearchRange.................................................13
5.3. Octet String................................................14
5.4. Value Representation........................................15
6. Protocol Definitions............................................17
6.1. AgentX PDU Header...........................................17
6.1.1. Context.................................................20
6.2. AgentX PDUs.................................................20
6.2.1. The agentx-Open-PDU.....................................20
6.2.2. The agentx-Close-PDU....................................22
6.2.3. The agentx-Register-PDU.................................23
6.2.4. The agentx-Unregister-PDU...............................27
6.2.5. The agentx-Get-PDU......................................29
6.2.6. The agentx-GetNext-PDU..................................30
6.2.7. The agentx-GetBulk-PDU..................................32
6.2.8. The agentx-TestSet-PDU..................................34
6.2.9. The agentx-CommitSet, -UndoSet, -CleanupSet PDUs........35
6.2.10. The agentx-Notify-PDU..................................36
6.2.11. The agentx-Ping-PDU....................................37
6.2.12. The agentx-IndexAllocate-PDU...........................37
6.2.13. The agentx-IndexDeallocate-PDU.........................38
6.2.14. The agentx-AddAgentCaps-PDU............................39
6.2.15. The agentx-RemoveAgentCaps-PDU.........................41
6.2.16. The agentx-Response-PDU................................43
7. Elements of Procedure...........................................45
7.1. Processing AgentX Administrative Messages...................45
7.1.1. Processing the agentx-Open-PDU..........................46
7.1.2. Processing the agentx-IndexAllocate-PDU.................47
7.1.3. Processing the agentx-IndexDeallocate-PDU...............49
7.1.4. Processing the agentx-Register-PDU......................50
7.1.4.1. Handling Duplicate and Overlapping Subtrees.........50
7.1.4.2. Registering Stuff...................................51
7.1.4.2.1. Registration Priority...........................51
7.1.4.2.2. Index Allocation................................51
7.1.4.2.3. Examples........................................53
7.1.5. Processing the agentx-Unregister-PDU....................55
7.1.6. Processing the agentx-AddAgentCaps-PDU..................55
7.1.7. Processing the agentx-RemoveAgentCaps-PDU...............55
7.1.8. Processing the agentx-Close-PDU.........................56
7.1.9. Detecting Connection Loss...............................56
7.1.10. Processing the agentx-Notify-PDU.......................56
7.1.11. Processing the agentx-Ping-PDU.........................57
7.2. Processing Received SNMP Protocol Messages..................58
7.2.1. Dispatching AgentX PDUs.................................58
7.2.1.1. agentx-Get-PDU......................................61
7.2.1.2. agentx-GetNext-PDU..................................61
7.2.1.3. agentx-GetBulk-PDU..................................62
7.2.1.4. agentx-TestSet-PDU..................................63
7.2.1.5. Dispatch............................................64
7.2.2. Subagent Processing.....................................64
7.2.3. Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs65
7.2.3.1. Subagent Processing of the agentx-Get-PDU...........65
7.2.3.2. Subagent Processing of the agentx-GetNext-PDU.......66
7.2.3.3. Subagent Processing of the agentx-GetBulk-PDU.......66
7.2.4. Subagent Processing of agentx-TestSet, -CommitSet,
-UndoSet, -CleanupSet-PDUs..............................67
7.2.4.1. Subagent Processing of the agentx-TestSet-PDU.......68
7.2.4.2. Subagent Processing of the agentx-CommitSet-PDU.....69
7.2.4.3. Subagent Processing of the agentx-UndoSet-PDU.......69
7.2.4.4. Subagent Processing of the agentx-CleanupSet-PDU....70
7.2.5. Master Agent Processing of AgentX Responses.............70
7.2.5.1. Common Processing of All AgentX Response PDUs.......70
7.2.5.2. Processing of Responses to agentx-Get-PDUs..........70
7.2.5.3. Processing of Responses to agentx-GetNext-PDU and
agentx-GetBulk-PDU..................................71
7.2.5.4. Processing of Responses to agentx-TestSet-PDUs......72
7.2.5.5. Processing of Responses to agentx-CommitSet-PDUs....73
7.2.5.6. Processing of Responses to agentx-UndoSet-PDUs......74
7.2.6. Sending the SNMP Response-PDU...........................74
7.2.7. MIB Views...............................................74
7.3. State Transitions...........................................75
7.3.1. Set Transaction States..................................75
7.3.2. Transport Connection States.............................77
7.3.3. Session States..........................................78
8. Transport Mappings..............................................79
8.1. AgentX over TCP.............................................79
8.1.1. Well-known Values.......................................79
8.1.2. Operation...............................................79
8.2. AgentX over UNIX-domain Sockets.............................80
8.2.1. Well-known Values.......................................80
8.2.2. Operation...............................................80
9. Security Considerations.........................................81
10. Acknowledgements...............................................82
11. Authors' and Editor's Addresses................................83
12. References.....................................................84
13. Notices........................................................86
Appendix A. Changes relative to RFC 2257 ..........................87
Full Copyright Statement ..........................................911. Introduction ✨
this is where the plot starts bestie 🦋 This memo defines a standardized framework for extensible SNMP agents. It defines processing entities called master agents and subagents, a protocol (AgentX) used to communicate between them, and the elements of procedure by which the extensible agent processes SNMP protocol messages.
This memo obsoletes RFC 2257. Most of the changes are for clarification, so it's lowkey a cleanup glow-up 💖 The only changes that affect AgentX protocol messages on the wire are:
- The
agentx-Notify-PDUandagentx-Close-PDUnow generate anagentx-Response-PDU📨 - Three new error codes are available:
parseFailed(266),requestDenied(267), andprocessingError(268)💀
Appendix A has the full list of changes relative to RFC 2257, so go check it if you want the receipts 🧾
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [27]. these are the official BCP 14 key words, so they're extra serious ⚠️
2. The SNMP Management Framework 🌈
okay this section is basically the family tree of SNMP 🌳 The SNMP Management Framework presently consists of five major components:
Here's the first one, the overall architecture, described in RFC 2571 [1].
Next up are the mechanisms for describing and naming objects and events for the purpose of management. The first version of this Structure of Management Information (SMI) is called SMIv1 and described in STD 16, RFC 1155 [2], STD 16, RFC 1212 [3] and RFC 1215 [4]. The second version, called SMIv2, is described in STD 58, RFC 2578 [5], STD 58, RFC 2579 [6] and STD 58, RFC 2580 [7].
Then there are the message protocols for transferring management information. The first version of the SNMP message protocol is called SNMPv1 and described in STD 15, RFC 1157 [8]. A second version of the SNMP message protocol, which is not an Internet standards track protocol, is called SNMPv2c and described in RFC 1901 [9] and RFC 1906 [10]. The third version of the message protocol is called SNMPv3 and described in RFC 1906 [10], RFC 2572 [11] and RFC 2574 [12].
Next are the protocol operations for accessing management information. The first set of protocol operations and associated PDU formats is described in STD 15, RFC 1157 [8]. A second set of protocol operations and associated PDU formats is described in RFC 1905 [13].
Then there's a set of fundamental applications described in RFC 2573 [14] and the view-based access control mechanism described in RFC 2575 [15].
If you want a more detailed intro to the current SNMP Management Framework, check RFC 2570 [16] 📚
Last but not least, managed objects are accessed via a virtual information store, termed the Management Information Base or MIB. Objects in the MIB are defined using the mechanisms defined in the SMI. that's the framework, periodt 🌈👑
2.1. A Note on Terminology 🎀
okay so before we get into the good stuff, we need to agree on some words 💅 The word "variable" means one instance of a non-aggregate object type, made under the rules in SMIv2 (STD 58, RFC 2578, [5]) or the textual conventions built on SMIv2 (STD 58, RFC 2579 [6]). A "variable binding" usually means the pairing of a variable's name with its value 🦋 BUT if something weird happens while a retrieval request is being handled, the variable binding pairs the name with an indication of that exception instead. Plot twist 🙈
A variable-binding list is just a simple list of variable bindings 🌸
Now the name of a variable is an OBJECT IDENTIFIER, and it's built by sticking together two things: the OBJECT IDENTIFIER of the matching object type, plus an OBJECT IDENTIFIER fragment that identifies the instance. The OBJECT IDENTIFIER of that object type is called the OBJECT IDENTIFIER prefix of the variable ✨
3. Extending the MIB ✨
okay this part is giving "the MIB keeps growing and nobody can stop it" 😭 New MIB modules that extend the Internet-standard MIB keep getting defined by all sorts of IETF working groups. Enterprises and individuals also make their own enterprise-specific or experimental MIBs, and honestly, same 🫶
So managed devices end up being complicated collections of manageable components. Each one got installed on the managed node on its own, and each one provides instrumentation for the managed objects in the MIB module(s) it implements 🧚
The SNMP framework doesn't say how the set of managed objects an agent supports can change dynamically. Not its job, babe 💀
3.1. Motivation for AgentX 💜
so this need to extend management objects dynamically inside a node has led to a bunch of "extensible agents." They usually look like this:
- a "master" agent that lives on the standard transport address and accepts SNMP protocol messages
- a set of "subagents" that each hold management instrumentation
- a protocol that runs between the master agent and the subagents. It lets subagents "connect" to the master agent, and lets the master agent multiplex received SNMP protocol messages across the subagents
- a set of tools to help build subagents, plus a runtime (API) environment that hides most of the protocol work between a subagent and the master agent 🔥
Here's the problem 😤 Extensible SNMP agents are everywhere, but there aren't Internet standards for this area yet, so it's really hard to ship SNMP-manageable applications. A vendor might have to support several different subagent environments (APIs) just to cover different target platforms. Ugh.
Configuring subagents and (possibly multiple) master agents on one managed node can also get super cumbersome 💅
Specifying a standard protocol for agent extensibility (AgentX) gives us the technical foundation needed to fix both of these. Independently developed AgentX-capable master agents and subagents will be able to interoperate at the protocol level, and vendors can still stand out in every other way 🌈
4. AgentX Framework 🦋
within the SNMP framework, a managed node has a processing entity called an agent, and it has access to management information. Main character stuff 👑
Inside the AgentX framework, an agent is further defined as having:
- a single processing entity called the master agent. It sends and receives SNMP protocol messages in an agent role (as the SNMP framework documents describe), but it usually has little or no direct access to management information
- zero or more processing entities called subagents. They're "shielded" from the SNMP protocol messages the master agent processes, but they do have access to management information
The master and subagent entities talk to each other through AgentX protocol messages, as this memo specifies. Any other interfaces on these entities (if there are any), and their protocols, are out of scope for this document. Some AgentX protocol messages look similar in syntax and semantics to SNMP ones, but bear in mind that AgentX is not SNMP 🙈
The internal workings of AgentX are invisible to an SNMP entity acting in a manager role. From a manager's point of view, an extensible agent acts exactly like a non-extensible (monolithic) agent that has access to the same management instrumentation. It's giving seamless ✨
This transparency to managers is a fundamental requirement of AgentX, and it's what makes AgentX subagents different from SNMP proxy agents 💖
4.1. AgentX Roles 🧚
An entity acting in a master agent role does all of the following:
- 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 that applies to the SNMP protocol message, except where they call for performing management operations. (Applying MIB views and enforcing the access control policy for the managed node are done by the master agent 🔒)
- Provides instrumentation for the MIB objects defined in RFC 1907 [17], and for any MIB objects relevant to any administrative framework it supports.
- Sends and receives AgentX protocol messages to access management information, based on the current registry of MIB regions.
- Forwards notifications on behalf of subagents.
An entity acting in a subagent role does all of the following:
- Initiates AgentX sessions with the master agent.
- Registers MIB regions with the master agent.
- Instantiates managed objects.
- Binds OIDs within its registered MIB regions to actual variables.
- Performs management operations on variables.
- Initiates notifications.
4.2. Applicability 🌸
okay so the goal here is to specify the smallest amount of required behavior that gets the biggest benefit. Basically, cover a huge number of possible MIB implementations and configurations with minimum complexity and a low "cost of entry" 💅
Here are some typical usage scenarios, bestie:
- Subagents implement separate MIB modules. For example, subagent
A' implements "mib-2", and subagentB' implements "host-resources".
This is expected to be the most common subagent configuration 👑
- Subagents implement rows in a "simple table." A simple table is one where row creation isn't specified, and the MIB doesn't define an object that counts the entries in the table. Examples of simple tables are rdbmsDbTable, udpTable, and hrSWRunTable.
This is the most commonly defined type of MIB table, and it probably represents the next most typical configuration AgentX would support 🦋
- Subagents share MIBs along non-row partitions. Subagents register "chunks" of the MIB that represent multiple rows, because of how the MIB's index structure works. Examples include registering
ipNetToMediaEntry.n, wherenrepresents the ifIndex value for an interface the subagent implements, andtcpConnEntry.a.b.c.d, wherea.b.c.drepresents an IP address on an interface the subagent implements.
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 tables that allow row creation, for example the RMON historyControlTable. To implement row creation in such tables, at least one AgentX subagent must register at a point "higher" in the OID tree than an individual row (per AgentX's dispatching procedure).
- Subagents implement rows in tables whose MIB also defines an object that counts the entries in the table, for example the MIB-2 ifTable (because of ifNumber). The subagent that implements a counter object like ifNumber must go beyond AgentX to implement it correctly. This is an implementation issue, and most new MIB designs no longer include objects like this 💀
Scenarios in those last two categories were thought to happen somewhat rarely in configurations where subagents are independently implemented by different vendors. But a standard protocol has to focus on exactly the areas where multi-vendor interoperability must be assured 🫶
Also, note that it would be inefficient (because of 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 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). In other words, master agents are the only ones concerned with SNMP protocol operations and with the translations to and from AgentX protocol operations needed to carry them out. Subagents are the only ones concerned with management instrumentation. Neither should intrude on the other's territory 🧚
- A standard protocol and "rules of engagement" that enable interoperability between management instrumentation and extensible agents.
- Mechanisms that let independently developed subagents integrate into the extensible agent on a particular managed node, so they don't need to 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 that 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's likely that the master agent and all subagents will reside on the same host, and in those 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 ✨
Okay so, here's what AgentX is not trying to do, bestie 💅 (scope creep is NOT it):
- Subagent-to-subagent communication. Out of scope, lowkey because of the security ramifications and complexity involved. 💀
- Subagent access (via the master agent) to MIB variables. Not addressed, since various other mechanisms are already available and it was never a fundamental requirement 🫶
- The ability to accommodate every conceivable extensible agent configuration option. Honestly this was the most contentious part of building this protocol 😭 Some features that show up in certain commercial extensible agent products just aren't in AgentX. They can be useful or even vital in some setups, but the rough consensus was that they weren't appropriate for an Internet Standard, or not typically needed for independently developed subagents to coexist. The supported extensible agent configurations are described above, in Section 4.2, "Applicability" 🌸
Not gonna lie, future versions of AgentX might cover one or more of these "non-goals," or brand new goals that show up after more deployment experience 🔮 Watch this space ✨
5. AgentX Encodings 🦋
Okay, so AgentX PDUs are made of a common header followed by PDU-specific data of variable length. Here's the plot twist: unlike SNMP PDUs, they are not encoded using BER (as specified in ISO 8824 [18]). Instead they're sent as a contiguous byte stream 🌊 The data in that stream is laid out so it lines up naturally with the start of the PDU, which lets the processing entities grab integers directly. Slay 👑
The first four fields in the header are single-byte values. The third field, h.flags, has a bit called NETWORK_BYTE_ORDER, and that bit tells you the byte ordering of every multi-byte integer in the PDU, including the ones in the header itself. We'll get into the details in Section 6.1, "AgentX PDU Header," below 🎀
Here's how this memo draws PDUs (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 reserved for future use, and it must be zero-filled. No freestyling here 🙅♀️
5.1. Object Identifier 🌈
An object identifier is encoded as a 4-byte header, followed by a variable number of contiguous 4-byte fields that represent sub-identifiers. This representation is called an Object Identifier, and it looks like this 💖
Object Identifier
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | include | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Now the header fields, the main characters of this section 🎭
n_subid- The number (0-128) of sub-identifiers in the object identifier. A list of "n_subid" 4-byte sub-identifiers follows the 4-byte header, in order.
prefix- An unsigned value that shrinks the length of object identifier encodings, which is iconic behaviour ✨ A non-zero value "x" is read as the first sub-identifier after "internet" (1.3.6.1), and it implies a prefix "internet.x" on top of the actual sub-identifiers encoded in the Object Identifier. For example, a prefix field value of 2 implies the prefix "1.3.6.1.2". A value of 0 means there's no prefix on the sub-identifiers.
include- Only used when the Object Identifier is the start of a SearchRange, as described in section 5.2, "SearchRange" 🫧
sub-identifier 1, 2, ... n_subid- A 4-byte unsigned integer, encoded according to the header's
NETWORK_BYTE_ORDERbit 🔢
- A 4-byte unsigned integer, encoded according to the header's
A null Object Identifier is just the 4-byte header with every byte set to 0. Empty but make it iconic 🤍
Examples time! 🍓
First up, sysDescr.0 (1.3.6.1.2.1.1.1.0), which looks like this:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 4 | 2 | 0 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Next, 1.2.3.4, which looks like this:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 4 | 0 | 0 | 0 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 3 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+5.2. SearchRange 🔍
A SearchRange is made of two Object Identifiers. When the master agent talks to a subagent, it uses a SearchRange to pin down a requested variable binding. In GetNext and GetBulk operations, it also sets an upper bound on the names of managed object instances the subagent may send back in the reply 🎀
The first Object Identifier in a SearchRange, called the starting OID, marks the beginning of the range. It's frequently (but not necessarily) 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, the ending OID, marks the non-inclusive end of the range, and its include field is always 0. A null value for the ending OID means the SearchRange is unbounded 🌌
Example time! 🧁 To show a search range from 1.3.6.1.2.1.25.2 (inclusive) to 1.3.6.1.2.1.25.2.1 (exclusive), the SearchRange looks 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 series of bytes. It starts with a 4-byte integer (encoded according to the header's NETWORK_BYTE_ORDER bit) whose value is the number of octets in the string, and then comes the octets themselves. This whole representation is called an Octet String 💜
Here's the padding situation, and it's important 🚨 If the last octet doesn't end on a 4-byte offset from the start of the Octet String, padding bytes get appended so the following data stays aligned. This padding must be added even if the Octet String is the last item in the PDU. Padding bytes must be zero filled. No exceptions, periodt 💅
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 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. Empty but make it iconic 🤍
5.4. Value Representation 💖
okay so VarBinds are how we pack up a variable inside a PDU, and they can hang out in the variable-length part of some PDUs ✨. Each VarBind is a 2-byte type field, a name (which is an Object Identifier 🎀), and then the actual value data. Here's how it's laid out:
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 VarBind breakdown 🦋
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 🏷️v.data: the actual value, encoded like this:Integer,Counter32,Gauge32, andTimeTicksare encoded as 4 contiguous bytes, following the header'sNETWORK_BYTE_ORDERbit 🔢Counter64is encoded as 8 contiguous bytes, following the header'sNETWORK_BYTE_ORDERbit 🧮- Object Identifiers are encoded as described in section 5.1, Object Identifier 🎀
IpAddress,Opaque, and Octet String are all octet strings and are encoded as described in section 5.3, "Octet String", Octet String. Note that the octets used to representIpAddressare always ordered most significant to least significant 🌸- Value data ALWAYS follows v.name whenever v.type is one of the above types. These data bytes are present even if they won't be used (like in certain types of index allocation) 🙈
Null,noSuchObject,noSuchInstance, andendOfMibViewdo not contain any encoded value. Value data never follows v.name in these cases 💀
Also, the VarBind itself doesn't contain 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 🧠
A VarBindList is a contiguous list of VarBinds. Inside a VarBindList, each VarBind gets an index value: the first one is 1, the second is 2, and so on 🍓
6. Protocol Definitions 👑
6.1. AgentX PDU Header 🎀
The AgentX PDU header is a fixed-format, 20-octet structure, and it's giving very organized energy ✨
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version | h.type | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Every AgentX PDU header has these fields 💜
h.version: the version of the AgentX protocol (1 for this memo) 🦋h.type: the PDU type, which is 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)The PDU types for "administrative processing" are 1-4 and 12-17. The PDU types for "SNMP request processing" are 5-11 🗂️
h.flags: a bitmask, with bit 0 as the least significant bit. Here are the bit definitions 🚩
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, then network byte order (most significant byte first, "big endian") is used. If it's not set, then least significant byte first ("little endian") is used 🌈
The NETWORK_BYTE_ORDER bit applies to ALL AgentX PDUs 💅
The NON_DEFAULT_CONTEXT bit is only used in the AgentX PDUs described in section 6.1.1, "Context" 🧚
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 🫶 The session ID 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 this case, the master agent assigns a unique session ID and passes it back in the corresponding agentx-Response-PDU. From then on, that same session ID 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 session ID, each of these AgentX PDUs MUST contain the same transaction ID. Conversely, AgentX PDUs sent during a particular session that result from distinct SNMP management requests MUST have distinct transaction IDs, within the limits of the 32-bit field 🔐
Note that the transaction ID is NOT the same as the SNMP PDU's request-id (as described in section 4.1 of RFC 1905 [13]), and it's also NOT the same as the SNMP Message's msgID (as described in section 6.2 of RFC 2572 [11]). It can't be, either, since a master agent might receive SNMP requests with the same request-ids or msgIDs from different managers 🙅♀️
The transaction ID has no significance and no defined value in AgentX administrative PDUs, 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 this field 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 SNMPv1 or SNMPv2c, the community string may be used as an index into a local repository of configuration information, which may include community profiles or more complex context information. In SNMPv3 this notion of "context" is formalized (see section 3.3.1 in RFC 2571 [1]) 🗝️
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, then there's no context field in the PDU, and the operation refers to the default context. (This does NOT mean there's a zero-length Octet String. It means there's no Octet String present at all 🙃) If the NON_DEFAULT_CONTEXT bit is set, then a context field immediately follows the AgentX header, and the operation refers to that specific context. The context is represented as an Octet String, and 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. That context 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 the agentx-Open-PDU is the message a subagent sends when it wants to start an AgentX session with the master agent 💖 it's basically the subagent going "hi, can we be friends now?" 🦋
(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) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+The agentx-Open-PDU has these fields 🎀
o.timeout: the length of time, in seconds, that a master agent should let pass after sending a message on a session before it decides the subagent isn't responding. This is the default for the session, and it can be overridden by values tied to specific registered MIB regions. A value of 0 means there's no session-wide default at all 🌸o.id: an Object Identifier that identifies the subagent. Subagents that don't really support that concept can send a null Object Identifier 🧚o.descr: an Octet String holding a DisplayString that describes the subagent 💅
6.2.2. The agentx-Close-PDU 🦋
the agentx-Close-PDU is the goodbye message 😭 either a subagent or the master agent can send it to end an AgentX session, and it's very much a "we're done here" energy 💀
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (2) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| c.reason | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+The agentx-Close-PDU has this one field ✨
c.reason: an enumerated value that tells you why the master agent or subagent closed the AgentX session 🫶 this field can be one of these values:reasonOther(1): none of the following reasons 🌈reasonParseError(2): too many AgentX parse errors from the peer 🙈reasonProtocolError(3): too many AgentX protocol errors from the peer 🔥reasonTimeouts(4): too many timeouts waiting for the peer ⏳reasonShutdown(5): the sending entity is shutting down 🍓reasonByManager(6): due to a Set operation. this reason code can only be used by the master agent, in response to an SNMP management request 👑
6.2.3. The agentx-Register-PDU ✨
okay bestie, the agentx-Register-PDU is how a subagent says "hey master agent, I can handle this part of the MIB tree!" 🌸 A subagent makes one for each region of the MIB variable naming tree (within one or more contexts) it wants to support 💅
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (3) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.context) (OPTIONAL)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet String Length (L) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet 1 | Octet 2 | Octet 3 | Octet 4 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Octet L - 1 | Octet L | Padding (as required) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| r.timeout | r.priority | r.range_subid | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.subtree)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.upper_bound)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| optional upper-bound sub-identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+the agentx-Register-PDU has these fields, and they're all giving main character energy 👑
r.context: an optional non-default context 🎀
r.timeout: this is how long (in seconds) a master agent waits after sending a message on a session before it decides the subagent isn't responding ⏳ it only applies to messages about MIB objects inside r.subtree. it beats both the session's default value (if one was set when the AgentX session with the master agent got established) and the master agent's default timeout. the default for r.timeout is 0, which means no override 🦋
r.priority: a value from 1 to 255 that helps get the setup you want when different sessions register the same or overlapping regions 💜 subagents that don't know much about priority should register with the default of 127 💅
in the master agent's dispatching algorithm, smaller r.priority values win over larger ones. see section 7.1.4.1, "Handling Duplicate and Overlapping Subtrees", for the deets 🧚
r.subtree: an Object Identifier that names the basic subtree of a MIB region the subagent is supporting. "subtree" is used loosely here, so it could be a fully-qualified instance name, a partial instance name, a MIB table, a whole MIB, and so on ✨
what to register is up to the implementation, and this memo doesn't say which values are allowed 🤷♀️ the usual vibe is to register at the highest level of the naming tree that still makes sense 🌳 registering fully-qualified instances is usually only for when a subagent can only do management operations on particular rows of a conceptual table 🍓
if r.subtree is actually a fully qualified instance name, the INSTANCE_REGISTRATION bit in h.flags must be set. otherwise it must be cleared. the master agent can save this info to speed up later operational dispatching 🚀
r.range_subid: lets you specify a range in place of one of r.subtree's sub-identifiers 🌈 if this is 0, there's no range and no r.upper_bound field in the PDU. the MIB region being registered is just the single subtree named by r.subtree.
otherwise, the "r.range_subid"-th sub-identifier in r.subtree is a range lower bound, and the range upper bound sub-identifier (r.upper_bound) comes right after r.subtree. the MIB region being registered is then the union of the subtrees you get by enumerating that range 💖
note that r.range_subid is the 1-based index of that sub-identifier within the OID represented by r.subtree, even if r.subtree is encoded using a prefix. (see the example below 👀)
r.upper_bound: the upper bound of a sub-identifier's range. it's only there if r.range_subid isn't 0 💫
so r.range_subid and r.upper_bound are a shorthand for naming a MIB region. say r.subtree is the OID 1.3.6.1.2.1.2.2.1.1.7, r.range_subid is 10, and r.upper_bound is 22. the region can be written as 1.3.6.1.2.1.2.2.1.[1-22].7. registering it is the same as registering the union of these subtrees:
1.3.6.1.2.1.2.2.1.1.7
1.3.6.1.2.1.2.2.1.2.7
1.3.6.1.2.1.2.2.1.3.7
...
1.3.6.1.2.1.2.2.1.22.7one expected use is registering a conceptual row with a single PDU 🎀 in the example above, the region just happens to be row 7 of the RFC 1573 ifTable. the actual PDU would look like this:
(AgentX header)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.version (1) | h.type (3) | h.flags | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.sessionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.transactionID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.packetID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| h.payload_length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| r.timeout | r.priority | 10 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.subtree)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 6 | 2 | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 7 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(r.upper_bound)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 22 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+again, r.range_subid is 10 here, even though n_subid in r.subtree is only 6 🙈
r.range_subid can be used at any level within a subtree. it doesn't have to mean row-level registration 🌸 subagents can use this mechanism in whatever way is most convenient for their registrations 💅✨
6.2.4. The agentx-Unregister-PDU 🧚
okay so the agentx-Unregister-PDU is how a subagent says "bye, I'm done with this part of the MIB" 💅 It's sent to take back a MIB region that was previously registered on this session. no drama, just cleaning up after yourself 🫶
(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.subtree)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| n_subid | prefix | 0 | <reserved> |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #1 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sub-identifier #n_subid |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
(u.upper_bound)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| optional upper-bound sub-identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+An agentx-Unregister-PDU contains the following fields: ✨
u.context: an optional non-default context 🌸u.priority: the priority this region was originally registered at 👑u.subtree: the previously-registered region of the MIB that the subagent is no longer up for supporting 🦋u.range_subid: tells you a sub-identifier inu.subtreeis a range lower bound 💜u.upper_bound: the upper bound of that range sub-identifier. this one only shows up in the PDU ifu.range_subidis not 0 🎀
6.2.5. The agentx-Get-PDU 🍓
this one's the classic "hey, what's the value of this?" request 👀
(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 contains the following fields: 💖
g.context: an optional non-default context 🌈g.sr: a SearchRangeList with the variables requested for this session. inside the agentx-Get-PDU, the Ending OIDs within SearchRanges are null-valued Object Identifiers 🧚
6.2.6. The agentx-GetNext-PDU 🦋
the GetNext one is basically Get's cooler cousin 😎 same vibe, but it asks for whatever comes next
(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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
...An agentx-GetNext-PDU contains the following fields: 🎀
g.context: an optional non-default context 🍓g.sr: a SearchRangeList with the variables requested for this session 💜
6.2.7. The agentx-GetBulk-PDU 🦋
bestie, the GetBulk PDU is the one that grabs a whole batch of variables in one go, so you don't have to ask one at a time 🧺✨ It starts with the usual AgentX header, which looks like this:
(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)
...An agentx-GetBulk-PDU contains the following fields:
g.context: an optional non-default context.g.non_repeaters: the number of variables in the SearchRangeList that are not repeaters.g.max_repetitions: the maximum number of repetitions requested for repeating variables.g.sr: a SearchRangeList containing the requested variables for this session.
6.2.8. The agentx-TestSet-PDU 🧪
the TestSet PDU is how a subagent checks out the requested VarBinds before anything is actually committed 💅 It also starts with the AgentX header:
(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 contains the following fields:
t.context: an optional non-default context.t.vb: a VarBindList containing the requested VarBinds for this subagent.
6.2.9. The agentx-CommitSet, -UndoSet, -CleanupSet PDUs 🧹
these three are the cleanup crew, and they're super minimal 🫶 They're made of the AgentX header and nothing else:
(AgentX header)The agentx-CommitSet-, -UndoSet-, and -Cleanup-PDUs are used in processing an SNMP SetRequest operation.
6.2.10. The agentx-Notify-PDU 🔔
the Notify PDU is how a subagent tells the master agent to forward a notification, so it's basically the main character of trap delivery 👑
(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 the following fields:
n.context: an optional non-default context.n.vb: a VarBindList whose contents define the actual PDU to be sent. This memo places the following restrictions on its contents:- If the subagent supplies
sysUpTime.0, it must be present as the first varbind. snmpTrapOID.0must be present, as the second varbind ifsysUpTime.0was supplied, as the first if it was not.
- If the subagent supplies
6.2.11. The agentx-Ping-PDU 🏓
the Ping PDU is a little health check 💖 A subagent sends it to the master agent to see whether the master can still receive and send AgentX PDUs over their 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 the following field:
p.context: an optional non-default context.
Using p.context a subagent can retrieve the sysUpTime value for a specific context, if required. ⏱️
6.2.12. The agentx-IndexAllocate-PDU 🧁
the IndexAllocate PDU is how a subagent asks for a value for specific index objects 🍓 For suggested usage, check out section 7.1.4.2, "Registering Stuff".
(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 the following 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 ✨
okay so an agentx-IndexDeallocate-PDU is how a subagent says "hey, I'm done with these index values, you can release them" 🫶 it's basically the cleanup crew of the AgentX world 🧹✨ it's sent by a subagent to release index values that were previously allocated.
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 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 the following 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 this one is so iconic 💜 an agentx-AddAgentCaps-PDU is generated by a subagent to tell the master agent what its capabilities are for the session it's in. main character energy, honestly 👑
(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 contains the following fields 🦋
a.context: an optional non-default context 🍓a.id: an Object Identifier containing the value of an invocation of the AGENT-CAPABILITIES macro. The master agent exports this as a value of sysORID for the indicated context. 🔥 (quick recap: an AGENT-CAPABILITIES invocation is an object identifier describing a precise level of support for the MIB modules that are implemented. the full scoop on the macro and the sysORID values is in section 6 of STD 58, RFC 2580 [7] 📚)a.descr: an Octet String containing a DisplayString, used as the value of sysORDescr that goes with the sysORID value above 💜
6.2.15. The agentx-RemoveAgentCaps-PDU 🌈
and now the un-glow-up 🥺 an agentx-RemoveAgentCaps-PDU is generated by a subagent to ask the master agent to stop exporting a particular sysORID value. this value must have previously been advertised by the subagent in an agentx-AddAgentCaps-PDU for this session. no skipping steps, bestie 💅
(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 contains the following fields 🫶
a.context: an optional non-default context 💖a.id: an ObjectIdentifier containing the value of sysORID that should no longer be exported 🥀
6.2.16. The agentx-Response-PDU ✨
okay bestie, the Response PDU is the one that talks back 💅 here's its whole layout:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 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 each have their own job 🦋
h.sessionID: if this is answering an agentx-Open-PDU, it's carrying the brand-new, totally unique sessionID the master agent just handed out for this session ✨ Otherwise, it must be identical to the h.sessionID value in the PDU this one is replying to.
h.transactionID: it must be identical to the h.transactionID value in the PDU this is responding to. When the master agent replies to a subagent, the h.transactionID value doesn't mean anything, so the subagent can just ignore it 🙈
h.packetID: it must be identical to the h.packetID value in the PDU this is responding to 💜
res.sysUpTime: this is the current sysUpTime for the context named in the PDU being answered. It only matters in responses the master agent sends to a subagent for the administrative PDUs listed in section 6.1, "AgentX PDU Header". In an agentx response PDU from the subagent to the master agent, res.sysUpTime has no significance and the master agent ignores it, bestie 💀
res.error: this tells you the error status. Inside responses to the "administrative" PDU types listed in section 6.1, "AgentX PDU Header", the values are limited to these:
noAgentXError (0),
openFailed (256),
notOpen (257),
indexWrongType (258),
indexAlreadyAllocated (259),
indexNoneAvailable (260),
indexNotAllocated (261),
unsupportedContext (262),
duplicateRegistration (263),
unknownRegistration (264),
unknownAgentCaps (265),
parseError (266),
requestDenied (267),
processingError (268)Inside responses to the "SNMP request processing" PDU types listed in section 6.1, "AgentX PDU Header", the values may also include the ones defined for errors in the SNMPv2 PDU (RFC 1905 [13]) 🎀
res.index: in error cases, this is the index of the failed variable binding inside 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 res.index, depending on which AgentX PDU is being responded to. That data is specified in the subsequent elements of procedure 🌈
7. Elements of Procedure ✨
This section is all about what the protocol entities (master agents and subagents) actually do when they're implementing AgentX 👑 It's not trying to control how any conformant implementation is built inside, so you've got room to do your own thing.
The actions of AgentX protocol entities fall under two big headings, and each one gets its own explanation:
- processing AgentX administrative messages (e.g., registration requests from a subagent to a master agent); and
- 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
This subsection covers what AgentX protocol entities do when they process administrative messages 🍓 These include the messages for setting up and tearing down an AgentX session between a subagent and a master agent, the ones where a subagent asks for instance index values to be allocated, and the ones where a subagent tells a master agent which MIB regions it supports.
Each PDU type gets its own processing rules in its own section. A lot of these PDU types need the same first steps from the master agent, so that shared stuff is defined right here and then referenced wherever it's needed 🦋
Common Processing:
The master agent starts by processing a received AgentX PDU like this:
- An agentx-Response-PDU is created,
res.sysUpTimeis set to the value ofsysUpTime.0for the default context,res.erroris set tonoAgentXError, andres.indexis set to 0 ✨ - If the received PDU can't be parsed,
res.erroris set toparseError. Examples of a parse error are:- PDU length (
h.payload) too short to contain current construct (Object Identifier header indicates more sub-identifiers, VarBindv.typeindicates data follows, etc) - An unrecognized value is encountered for
h.type,v.type, etc.
- PDU length (
- Otherwise, if
h.sessionIDdoes not correspond to a currently established session with this subagent,res.erroris set tonotOpen🙈 - Otherwise, if the NON_DEFAULT_CONTEXT bit is set and the master agent does not support the indicated context,
res.erroris set tounsupportedContext. If the master agent does support the indicated context, the value ofres.sysUpTimeis set to the value ofsysUpTime.0for that context 🌸 - If resources can't be allocated or some other condition prevents processing,
res.erroris set toprocessingError💀 - At this point, if
res.erroris notnoAgentXError, the received PDU doesn't get processed any further. If the received PDU's header was successfully parsed, the AgentX-Response-PDU is sent back as the reply. If the received PDU contained a VarBindList that was successfully parsed, the AgentX-Response-PDU contains that identical VarBindList. If the received PDU's header wasn't successfully parsed, or for some other reason the master agent can't send a reply, processing is complete 🫶
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 👑
7.1.1. Processing the agentx-Open-PDU
When the master agent receives an agentx-Open-PDU, it processes it like this 🎀
- An agentx-Response-PDU is created,
res.sysUpTimeis set to the value ofsysUpTime.0for the default context,res.erroris set tonoAgentXError, andres.indexis set to 0 ✨ - If the received PDU can't be parsed,
res.erroris set toparseError💅 - Otherwise, if the master agent is unable to open an AgentX session for any reason,
res.erroris set toopenFailed😭 - Otherwise, the master agent assigns a sessionID to the new session and puts that value in the
h.sessionIDfield of the agentx-Response-PDU. This value must be unique among all existing open sessions 🦋
The master agent keeps some session-specific info from the PDU for this session:
- The NETWORK_BYTE_ORDER value in
h.flagsis retained. All subsequent AgentX protocol operations initiated by the master agent for this session must use this byte ordering and set this bit accordingly 💜 - The
o.timeoutvalue is used when calculating response timeout conditions for this session. This field is also referenced in the AgentX MIB (a work-in-progress) by theagentxSessionTimeoutobject 🌈 - The
o.idando.descrfields are used for informational purposes. These two fields are also referenced in the AgentX MIB (a work-in-progress) by theagentxSessionObjectIDobject, and by theagentxSessionDescrobject 🍓
The subagent typically sets the NETWORK_BYTE_ORDER bit to match its native byte ordering, and typically doesn't change the byte ordering for a session it has initiated. The master agent must be able to decode each PDU according to the h.flags NETWORK_BYTE_ORDER bit in that PDU, but it doesn't need to toggle its retained value for the session if the subagent changes its byte ordering 🧚
- The agentx-Response-PDU is sent with the
res.errorfield indicating the result of the session initiation 🫶
If processing was successful, an AgentX session is considered established between the master agent and the subagent 🎉 An AgentX session is a distinct channel for exchanging AgentX protocol messages between one master agent and one subagent, and it's qualified by the session-specific attributes listed in step 4 above. AgentX session establishment is always initiated by the subagent, and either the master agent or the subagent can terminate an AgentX session 💖
7.1.2. Processing the agentx-IndexAllocate-PDU ✨
okay so when the master agent gets an agentx-IndexAllocate-PDU 📨, it does the common stuff from section 7.1, "Processing AgentX Administrative Messages" first. If that leaves res.error as noAgentXError, then it keeps going like this 💅
- Each VarBind in the VarBindList gets processed until either all of them work or one fails 😭. If any VarBind fails, the agentx-Response-PDU gets sent back containing the original VarBindList, with res.index pointing at the failed VarBind and res.error set as described below. The other VarBinds get ignored, and no index values get allocated.
VarBinds get processed like this:
- v.name is the OID prefix of the MIB OBJECT-TYPE that a value is being allocated for.
- v.type is the syntax of that MIB OBJECT-TYPE.
- v.data is the specific index value being asked for. If the NEW_INDEX or the ANY_INDEX bit is set, the actual value in v.data gets ignored and an appropriate index value gets generated instead 🎀
a) If there are no currently allocated index values 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 currently allocated index values for v.name in the indicated context, but the syntax of those values 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, it means a specific index value is being requested. 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. The constraint is that this value must not have been allocated to any subagent since the last re-initialization of the master agent, even if it was released afterwards. If no such value can be generated, 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, with the constraint that this value isn't currently allocated to any subagent. If no such value can be generated, the VarBind fails and res.error is set to indexNoneAvailable 🦋
- If all VarBinds are processed successfully, the agentx-Response-PDU gets sent back with res.error set to
noAgentXError🎉 The VarBindList in the reply is identical to the one in the agentx-IndexAllocate-PDU, except that any VarBinds asking for a NEW_INDEX or ANY_INDEX value now have an appropriate value generated for them.
See section 7.1.4.2, "Registering Stuff" for more info on how subagents should do their index allocations 🧚
7.1.3. Processing the agentx-IndexDeallocate-PDU 🫶
When the master agent gets an agentx-IndexDeallocate-PDU, it runs the common processing from section 7.1, "Processing AgentX Administrative Messages" 📋 If that leaves res.error as noAgentXError, it keeps going like this:
- Each VarBind in the VarBindList gets processed until either all of them are successful or one fails. If any VarBind fails, the agentx-Response-PDU is sent back containing the original VarBindList, with res.index pointing at the failed VarBind and res.error set as described next. The other VarBinds get ignored, and no index values get released 🙅♀️
VarBinds get processed like this:
- v.name is the name of the index whose value is being released.
- v.type is the syntax of the index object.
- v.data is the specific index value to be released. The NEW_INDEX and ANY_INDEX bits get ignored here ✨
a) If the index value for the named index isn't currently allocated to this session, the VarBind fails and res.error is set to indexNotAllocated 😬
- If all VarBinds are processed successfully, res.error is set to
noAgentXErrorand the agentx-Response-PDU gets sent 🥳 The VarBindList in that reply is identical to the one in the agentx-IndexDeallocate-PDU.
All released index values are now available again 🌈 They can be used to satisfy later allocation requests for ANY_INDEX values, and also later allocation requests for that particular index value.
7.1.4. Processing the agentx-Register-PDU 📮
When the master agent gets an agentx-Register-PDU, it runs the common processing from section 7.1, "Processing AgentX Administrative Messages" 💜 If that leaves res.error as noAgentXError, the following happens:
If any of the union of subtrees defined by this MIB region is exactly the same as any subtree defined by a MIB region that's already registered in the indicated context, those subtrees are called "duplicate subtrees" 👯♀️
If any of the union of subtrees defined by this MIB region overlaps with, or is itself overlapped by, any subtree defined by a MIB region already registered in the indicated context, those subtrees are called "overlapping subtrees" 🔥
- If this registration would result in duplicate subtrees registered with the same value of r.priority, the request fails and an agentx-Response-PDU comes back with res.error set to
duplicateRegistration💀 - Otherwise, if the master agent doesn't want to permit this registration for implementation-specific reasons, the request fails and an agentx-Response-PDU comes back with res.error set to
requestDenied🙅♀️ - Otherwise, the agentx-Response-PDU comes back with res.error set to
noAgentXError🎀
The master agent adds this MIB region to its registration data store for the indicated context. It gets considered during the dispatching phase for SNMP protocol messages that arrive later 🦋
7.1.4.1. Handling Duplicate and Overlapping Subtrees 👑
As a result of this registration algorithm, there are likely to be duplicate and/or overlapping subtrees in the master agent's registration data store 🫠 Whenever the master agent's dispatching algorithm (see section 7.2.1, "Dispatching AgentX PDUs") figures out that there are multiple subtrees that could potentially contain the same MIB object instances, the master agent picks one to use. That one is called the 'authoritative region', and it gets picked like this:
- Choose the one whose original agentx-Register-PDU r.subtree contained the most subids, meaning the most specific r.subtree 🧠 Note: whether a range subid is present or absent has no bearing on how "specific" one object identifier is compared to another 💅
- If it's still ambiguous, there were duplicate subtrees. In that case, choose the one whose original agentx-Register-PDU specified the smaller value of r.priority 🌸
7.1.4.2. Registering Stuff 🎀
okay so this bit is where we get into how AgentX subagents actually use the agentx-IndexAllocate-PDU and agentx-Register-PDU together to get their configs just right 💅✨
7.1.4.2.1. Registration Priority 👑
the r.priority field in the agentx-Register-PDU is meant to be tweaked by human admins to get the subagent setup they want 🫶 usually this comes up when a legacy app registers a specific subtree, and some other (configurable) app might need to become the authoritative one for that same subtree. it's giving "let the new app take the crown" energy 😭
so when the same subtree gets registered on different sessions with different priorities, the session with the better priority (see section 7.1.4.1, "Handling Duplicate and Overlapping Subtrees") is the one that's authoritative. the other session just never gets dispatched to. no drama, it's literally just ignored 💀
this is super useful for the situation I just described, but it is not useful in other cases, especially when subagents share tables indexed by arbitrary values (more on that below) 🙈 in general, subagents should register using the default priority (127) 🌸
7.1.4.2.2. Index Allocation 🧚
index allocation is a service that an AgentX master agent provides. it gives generic support for sharing MIB conceptual tables between subagents who are assumed to have no clue about each other 🦋
the master agent keeps a database of index objects (OIDs) and, for each index, the values that have been allocated for it. it has no idea what MIB variables (if any) those index objects represent. it's literally just vibing with numbers 🔢
by convention, subagents use the MIB variable listed in the INDEX clause as the index object that values must be allocated for. for tables indexed by multiple variables, values may be allocated for each index (though this is frequently unnecessary, see example 2 below). the subagent may request allocation of:
- a) a specific index value
- b) an index value that is not currently allocated
- c) an index value that has never been allocated
the last two options reflect the uniqueness and constancy requirements that show up in lots of MIB specs for arbitrary integer indexes. think ifIndex in the IF-MIB (RFC 2233 [19]), snmpFddiSMTIndex in the FDDI MIB (RFC 1285 [20]), or sysApplInstallPkgIndex in the System Application MIB (RFC 2287 [21]). needing subagents to share tables with indexes like these is the main reason index allocation exists in AgentX 🎯
it's really important to note that index allocation and MIB region registration are not coupled in the master agent. the current state of index allocations doesn't get considered when processing registration requests, and the current registry doesn't get considered when processing index allocation requests. (this is mainly to accommodate non-AgentX subagents.) 🫣
AgentX subagents should follow the model of "first request allocation of an index, then register the corresponding region" 💖 that way, a successful index allocation gives a subagent a good hint (but no guarantee) of what it should be able to register. the registration can still fail with `duplicateRegistration' because some other subagent session already registered that row of the table. oof 😭
the recommended way for subagents to register conceptual rows in a shared table goes like this:
- Successfully allocate an index value.
- Use that value to fully qualify the MIB region(s), and attempt to register using the default priority.
- If the registration fails with `duplicateRegistration', deallocate the previously allocated index value(s) for this row and go to step 1).
index allocation is only necessary when the index in question is an arbitrary value, so the subagent has no other reasonable way to figure out which index values to use. when index values have intrinsic meaning, it's not expected that subagents will allocate their index values 🍓
for example, RFC 1514's table of running software processes (hrSWRunTable) is indexed by the system's native process identifier (pid). a subagent implementing the row of hrSWRunTable for its own process would simply register the region defining that row's object instances, no allocating index values needed ✨
7.1.4.2.3. Examples 🌈
Example 1:
A subagent implements an interface and wants to register a single row of the RFC 2233 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 tries 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, and the master agent will dispatch to this subagent correctly 🎉
if the registration failed with `duplicateRegistration', the subagent should deallocate the failed index, 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 is made up 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 💜
Example 4:
the Application Management MIB (RFC 2564 [22]) uses two objects to index several tables. a partial description of them is:
applSrvIndex OBJECT-TYPE
SYNTAX Unsigned32 (1..'ffffffff'h)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"An applSrvIndex is the system-unique identifier
of an instance of a service. The value is unique
not only across all instances of a given service,
but also across all services in a system."
applSrvName OBJECT-TYPE
SYNTAX SnmpAdminString
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The human-readable name of a service. Where
appropriate, as in the case where a service can
be identified in terms of a single protocol, the
strings should be established names such as those
assigned by IANA and found in STD 2 [23], or
defined by some other authority. In some cases
private conventions apply and the string should
in these cases be consistent with these
non-standard conventions. An applicability
statement may specify the service name(s) to be
used."since applSrvIndex is an arbitrary value, it would be reasonable for subagents to allocate values for this index. applSrvName, however, has intrinsic meaning, and any values a subagent would use should be known a priori. so it is not reasonable for subagents to allocate values of this index 🙅♀️
7.1.5. Processing the agentx-Unregister-PDU 🗑️
when the master agent receives an agentx-Unregister-PDU, it does the common processing described in section 7.1, "Processing AgentX Administrative Messages". if as a result res.error is `noAgentXError', processing continues like this:
- if u.subtree, u.priority, u.range_subid (and if u.range_subid is not 0, u.upper_bound), and the indicated context don't match an existing registration made during this session, the agentx-Response-PDU is returned with res.error set to `unknownRegistration'.
- otherwise, the agentx-Response-PDU is sent in reply with res.error set to `noAgentXError', and the previous registration is removed from the registration data store ✅
7.1.6. Processing the agentx-AddAgentCaps-PDU 🪄
when the master agent receives an agentx-AddAgentCaps-PDU, it does the common processing described in section 7.1, "Processing AgentX Administrative Messages". if as a result res.error is `noAgentXError', processing continues like this:
- the master agent adds this agent capabilities information to the sysORTable for the indicated context. an agentx-Response-PDU is sent in reply with res.error set to `noAgentXError' 🌟
7.1.7. Processing the agentx-RemoveAgentCaps-PDU 🧹
when the master agent receives an agentx-RemoveAgentCaps-PDU, it does the common processing described in section 7.1, "Processing AgentX Administrative Messages". if as a result res.error is `noAgentXError', processing continues like this:
- if the combination of a.id and the optional a.context doesn't represent a sysORTable entry that was added by this subagent during this session, the agentx-Response-PDU is returned with res.error set to `unknownAgentCaps'.
- otherwise the master agent deletes the corresponding sysORTable entry and sends the agentx-Response-PDU in reply, with res.error set to `noAgentXError' 💅
7.1.8. Processing the agentx-Close-PDU 🚪
when the master agent receives an agentx-Close-PDU, it does the common processing described in section 7.1, "Processing AgentX Administrative Messages", with the exception that step 4) is not performed since the agentx-Close-PDU does may not contain a context field. if as a result res.error is `noAgentXError', processing continues like this:
- the master agent closes the AgentX session as described below, and sends the agentx-Response-PDU in reply with res.error set to `noAgentXError':
- all MIB regions that were registered during this session are unregistered, as described in section 7.1.5, "Processing the agentx-Unregister-PDU".
- all index values allocated during this session are freed, as described in section 7.1.3, "Processing the agentx-IndexDeallocate-PDU".
- all sysORID values that were registered during this session are removed, as described in section 7.1.7, "Processing the agentx-RemoveAgentCaps-PDU".
the master agent doesn't keep state for closed sessions. if a subagent wants to re-establish a session after it has been closed, it needs to re-register MIB regions, agent capabilities, and so on 🔄
7.1.9. 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 section 7.1.8, "Processing the agentx-Close-PDU", step 1) 🥺
7.1.10. Processing the agentx-Notify-PDU 🔔
Okay bestie, so SNMPv1 trap info has to get mapped to (at minimum) a snmpTrapOID.0 value, same as 3.1.2 of RFC 1908 [24] describes. No cap, that's the baseline. ✨
When the master agent gets an agentx-Notify-PDU, it runs the common processing from section 7.1, "Processing AgentX Administrative Messages" 💅. If that leaves res.error as `noAgentXError', it keeps going like this:
1) If the first VarBind is sysUpTime.0:
- (a) if the second VarBind is not snmpTrapOID.0, res.error is set to `processingError' and res.index to 2
- (b) otherwise these two VarBinds are used as the first two VarBinds within the generated notification.
2) If the first VarBind is not sysUpTime.0:
- (a) if the first VarBind is not snmpTrapOID.0, res.error is set to `processingError' and res.index to 1
- (b) otherwise this VarBind is used for snmpTrapOID.0 within the generated notification, and the master agent uses the current value of sysUpTime.0 for the indicated context as sysUpTime.0 within the notification.
3) An agentx-Response-PDU is sent containing the original VarBindList, with res.error and res.index set as described above. If res.error is `noAgentXError', notifications get 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 [25]. If res.error indicates an error in processing, no notifications are generated. 🚫
Note that the master agent's successful response just means the agentx-Notify-PDU was received and validated. It does NOT mean any particular notifications were actually generated or received by notification targets. 🙈
7.1.11. Processing the agentx-Ping-PDU 🏓
When the master agent gets an agentx-Ping-PDU, it runs the common processing from section 7.1, "Processing AgentX Administrative Messages". If that leaves res.error as `noAgentXError', it does this:
1) An agentx-Response-PDU is sent in reply.
Now here's the vibe check 🫶. If a subagent isn't getting responses to its pings, or it can tell from the underlying transport that the master agent can't receive AgentX messages, then it eventually must start a brand-new AgentX session, re-register its MIB regions, etc. Main character reset energy 🔄.
7.2. Processing Received SNMP Protocol Messages 📨
When the master agent receives an SNMP GetRequest, GetNextRequest, GetBulkRequest, or SetRequest protocol message, it applies its access control policy first. Gatekeeping era 🛡️.
For SNMPv1 or SNMPv2c protocol messages, the master agent applies the Elements of Procedure from section 4.1 of STD 15, RFC 1157 [8] that apply to receiving entities. For SNMPv3, the master agent applies an Access Control Model, possibly the View-based Access Control Model (see RFC 2575 [15]), as described in section 3.1.2 and section 4.3 of RFC 2571 [1]. 🔐
For SNMPv1 and SNMPv2c, the master agent uses the community string as an index into a local repository of configuration information. That repository may include community profiles or more complex context information. For SNMPv3, the master agent uses the SNMP Context (see section 3.3.1 of RFC 2571 [1]) for these purposes. 🗂️
If applying the access control policy results in a valid SNMP request PDU, then an SNMP Response-PDU is built from information gathered in the exchange of AgentX PDUs between the master agent and one or more subagents. Once an SNMP request PDU has been received and initially validated, the master agent uses the procedures below to dispatch AgentX PDUs to the proper subagents, marshal the subagent responses, and construct an SNMP response PDU. It's giving teamwork 🧚.
7.2.1. Dispatching AgentX PDUs 🚚
Upon receipt and initial validation of an SNMP request PDU, the master agent uses the procedures below to dispatch AgentX PDUs to the proper subagents.
General Rules of Procedure
While processing a particular SNMP request, the master agent may send one or more AgentX PDUs on one or more subagent sessions. These rules of procedure apply in general to the AgentX master agent. PDU-specific rules are listed in the applicable sections. 📋
1) Honoring the registry
Okay so AgentX lets you register duplicate and overlapping regions 🌈. That means the master agent could get a value for a requested varbind from more than one registered MIB region.
The master agent must ensure that the value (or exception) actually returned in the SNMP response PDU is taken from the authoritative region (as defined in section 7.1.4.1, "Handling Duplicate and Overlapping Subtrees"). Only the authoritative one gets the crown 👑.
2) 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 possible reason for this would be if the current iteration has targeted instance-level registrations. 🎯
The master agent may choose to "scope" the possible instances a subagent returns by specifying an ending OID in the SearchRange. If that scoping is used, the ending OID would typically be the first lexicographical successor to the target region that was registered on a session other than the target session. Regardless of this choice, rule (1) must be obeyed. 📏
The master agent may require multiple request-response iterations on the same subagent session, to determine the final value of all requested variables. Iterate, iterate, iterate 🔁.
All AgentX PDUs sent on the session while processing a given SNMP request must contain identical values of transactionID. Each different SNMP request the master agent processes must present a unique value of transactionID (within the limits of the 32-bit field) to the session. Unique IDs only, no duplicates 🪪.
3) Number and order of variables sent per AgentX PDU
For Get/GetNext/GetBulk operations, at any stage of the possibly iterative process, 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. Order matters, periodt 💅.
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.
- 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 agentx-TestSet-PDU.
- c) When processing an SNMP Get, GetNext, or GetBulk request, the master agent may send a single AgentX PDU on the session with all applicable VarBinds, or multiple PDUs with single VarBinds, or something in between those extremes. The determination of which method to use in a particular case is implementation-specific. 🤷♀️
4) Timeout Values
The master agent chooses a timeout value for each MIB region being queried. The value comes from:
- 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, or, if the specified value is not practical, the master agent's implementation-specific default value ⏱️
When an AgentX PDU that references multiple MIB regions is dispatched, the timeout used for that PDU is the maximum of the timeouts determined for each of the referenced MIB regions. The biggest timeout wins 🏆.
5) 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 MIB region.
Within a lexicographically ordered set of registered MIB regions that are valid for the indicated context, locate the authoritative region (according to section 7.1.4.1, "Handling Duplicate and Overlapping Subtrees") that contains the binding's name. Finding the right region is the whole vibe 🔍.
(2) If no such region 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. This is called 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 processing this management request:
- Create an agentx-Get-PDU for this session, with the header fields initialized as described above (see section 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 ✨
okay so each variable binding in the SNMP request PDU gets handled one at a time, like a little checklist 💅
(1) Identify the target MIB region. Within a lexicographically ordered set of registered MIB regions that are valid for the indicated context, find the authoritative region (according to section 7.1.4.1, "Handling Duplicate and Overlapping Subtrees") that either:
a) contains the variable binding's name and is not a fully qualified instance, or
b) is the first lexicographical successor to the variable binding's name. 🎯
(2) If no such region exists, the variable binding doesn't get processed any further, and its value is set to `endOfMibView'. 🙈
(3) Figure out which subagent session that region was registered in. This is called the target session. 🦋
(4) If this is the first variable binding being dispatched over the target session during a request-response exchange that's part of handling this management request:
- Create an agentx-GetNext-PDU for that session, with its header fields set up the way we described above (see section 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 gets encoded into the starting OID, and the OID's "include" field is set to 0.
- If (1b) applies, the target region's r.subtree gets encoded into the starting OID, and its "include" field is set to 1. This is the recommended method, bestie. An implementation may choose to use a starting OID value that comes before r.subtree, but in that case the include bit must be 0. A starting OID value that comes after r.subtree is not permitted. 🚫
- The Ending OID for the SearchRange is encoded as either NULL, or a value that lexicographically comes after the Starting OID. This is an implementation-specific choice, depending on how the master agent wants to "scope" the instances it could get back. 🌸
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 [13]. Go check that out if you want the details on the format of the SNMP GetBulkRequest-PDU itself, it's a whole vibe 🧚)
Each variable binding in the request PDU is processed as follows:
(1) Identify the authoritative target region and target session, exactly the way it's described for the agentx-GetNext-PDU (see section 7.2.1.2, "agentx-GetNext-PDU"). 🎯
(2) If this is the first variable binding being dispatched over the target session during a request-response exchange that's part of handling this management request:
- Create an agentx-GetBulk-PDU for that session, with its header fields set up as described above (see section 6.1, "AgentX PDU Header"). 💖
(3) Add a SearchRange to the end of the target session's agentx-GetBulk-PDU for this variable binding, just like we do 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 too. 🫶
The value of g.max_repetitions in the agentx-GetBulk-PDU may be less than the value in the original request PDU, but it can't be greater. 📉
The master agent is allowed to make these adjustments for a few reasons: 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 that "as if simultaneous" feel for the SNMP SetRequest-PDU inside the extensible agent. The very 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 MIB region and target session exactly as described in section 7.2.1.1, "agentx-Get-PDU", step 1).
Within a lexicographically ordered set of OID ranges that are valid for the indicated context, find the authoritative range that contains the variable binding's name. 🔍
(2) If no such target region exists, this variable binding fails with an error of `notWritable'. Processing is complete for this request. 💀
(3) If this is the first variable binding being dispatched over the target session during a request-response exchange that's part of handling this management request:
- Create an agentx-TestSet-PDU for that session, with its header fields set up as described above (see section 6.1, "AgentX PDU Header"). 🎀
(4) Add a VarBind to the end of the target session's PDU for this variable binding, as described in section 5.4, "Value Representation". 🌈
Note that all VarBinds for a given session must be sent in a single agentx-TestSet-PDU. No splitting it up, okay? 🙅♀️
7.2.1.5. Dispatch 🚀
A timeout value gets calculated for each PDU that's going out. It's the maximum value of the timeouts figured out for each of the PDU's SearchRanges (as described above in section 7.2.1, "Dispatching AgentX PDUs", item 4). Each pending PDU gets mapped, through its h.sessionID value, to a particular transport domain/endpoint, as described in section 8 (Transport Mappings). 🦋
7.2.2. Subagent Processing 🌷
A subagent's first step with a received AgentX PDU looks like this:
- If the received PDU is an agentx-Response-PDU:
- If there are any errors while parsing or interpreting the PDU, it gets silently dropped. 🤫
- Otherwise, the response is matched to the original request via h.packetID, and handled in an implementation-specific manner. For example, if this response says there was an error trying to register a MIB region, the subagent may wish to register a different region, or log an error and halt, etc. 🛠️
- If the received PDU is any other type:
- An agentx-Response-PDU is created whose header fields are identical to the received request PDU, except that h.type is set to Response, res.error to `noError', res.index to 0, and the VarBindList to null. 🍰
- If the received PDU can't be parsed, res.error is set to `parseError'. 😬
- Otherwise, if h.sessionID doesn't match a currently established session, res.error is set to `notOpen'. 🚪
- At this point, if res.error is not `noError', the received PDU doesn't get processed any further. If the received PDU's header was parsed successfully, the AgentX-Response-PDU gets sent back as a reply. If the header wasn't parsed successfully, or for some other reason the subagent can't send a reply, processing is complete. 🛑
7.2.3. 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. 👑
When a subagent receives an agentx-Get-, GetNext-, or GetBulk-PDU, it does the management operations it was asked for and sends back an agentx-Response-PDU. 🔁
Each SearchRange in the request PDU's SearchRangeList is processed as described below, and a VarBind is added in the matching spot in the agentx-Response-PDU's VarbindList. If processing fails for any reason that isn't 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.3.1. Subagent Processing of the agentx-Get-PDU 🌟
When the subagent gets an agentx-Get-PDU, each SearchRange in the request is processed as follows:
(1) The starting OID is copied to v.name. 📋
(2) If the starting OID exactly matches the name of a variable this subagent has instantiated within the indicated context and session, v.type and v.data are encoded to represent that variable's syntax and value, as described in section 5.4, "Value Representation". ✨
(3) Otherwise, if the starting OID doesn't match the object identifier prefix of any variable instantiated within the indicated context and session, the VarBind is set to `noSuchObject', in the manner described in section 5.4, "Value Representation". 🙃
(4) Otherwise, the VarBind is set to `noSuchInstance' in the manner described in section 5.4, "Value Representation". 🫠
7.2.3.2. Subagent Processing of the agentx-GetNext-PDU 🔮
When the subagent gets an agentx-GetNext-PDU, each SearchRange in the request is processed as follows:
(1) The subagent searches the lexicographically ordered list of variable names for all the variables it instantiates (without caring about how regions are registered) within the indicated context and session, like this:
- 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 the starting OID, or the closest lexicographical successor to it.
- If the ending OID isn't null, the variable's name lexicographically comes before the ending OID.
If a variable is found, v.name is set to that variable's name. v.type and v.data are encoded to represent the variable's syntax and value, as described in section 5.4, "Value Representation". 🎉
(2) If the subagent can't locate an appropriate variable, 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". 🏁
7.2.3.3. Subagent Processing of the agentx-GetBulk-PDU 🎀
Okay bestie, GetBulk is where things get spicy 🌶️ A maximum of N + (M * R) VarBinds come back, where:
Nequalsg.non_repeaters,Mequalsg.max_repetitions, andRis (number of SearchRanges in the GetBulk request) -N.
The first N SearchRanges get processed exactly like the agentx-GetNext-PDU, so nothing new there 💅
If M and R are both non-zero, the remaining R SearchRanges get processed iteratively to make potentially many 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 every variable it instantiates (regardless of region registration 🦋) within the indicated context and session. It's looking for a variable where all of the following are true:
- The variable's name is the
(i)-th lexicographical successor to the(N+s)-th requested OID.
- The variable's name is the
(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 is 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
endOfMibView' as described in section 5.4, "Value Representation".v.nameis set tov.nameof the(N+((i-2)*R)+s)-th VarBind, unlessiis currently 1. In that case it is set to the value of the starting OID in the(N+s)`-th SearchRange 🫶
Note that further iterative processing should stop if:
- For any iteration
i, allsvalues ofv.typeare `endOfMibView'. - An AgentX transport constraint or other implementation-specific constraint is reached.
7.2.4. 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 the agentx-TestSet-PDU. Non-negotiable, no cap 👑
These four PDUs work together to perform the indicated management operation 🧚 An agentx-Response-PDU is sent in reply to each of the PDUs (except -CleanupSet) to tell the master agent the state of the operation.
The master agent must serialize Set transactions for each session. That is, a session need not handle multiple concurrent Set transactions. Lowkey a relief, honestly 💖
These Response-PDUs do not contain a VarBindList.
7.2.4.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 are all successful, or until one fails, as described in section 4.2.5 of RFC 1905 [13]. The subagent validates variables with respect to the context and session indicated in the testSet-PDU. Be thorough, bestie 🔍
If each VarBind is successful, the subagent has a further responsibility: it has to make sure all the resources (memory, write access, etc.) needed for a successful agentx-CommitSet operation are available. If that can't be guaranteed, the subagent should set res.error to `resourceUnavailable'. As a result of this validation step, an agentx-Response-PDU is sent in reply, and its res.error field is set to one of the following SNMPv2 PDU error-status values (see section 3, "Definitions", in RFC 1905 [13]):
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 is not `noError', the res.index field must be set to the index of the VarBind for which validation failed.
Implementing rigorous validation code may be one of the most demanding parts of subagent development. 😭 Implementors are strongly encouraged to get it right, so that the extensible agent avoids, if at all possible, having to return commitFailed' or undoFailed' during subsequent processing. Future-you will thank present-you 🌸
7.2.4.2. Subagent Processing of the agentx-CommitSet-PDU 🔥
The agentx-CommitSet-PDU tells the subagent to actually perform the management operation indicated by the previous TestSet-PDU (as described in the post-validation sections of 4.2.5 of RFC 1905 [13]). After carrying out the operation, the subagent sends an agentx-Response-PDU in reply, with its res.error field set to one of the following SNMPv2 PDU error-status values (see section 3, "Definitions", in RFC 1905 [13]):
noError (0),
commitFailed (14)If this value is `commitFailed', the res.index field must be set to the index of the VarBind (as it occurred in the agentx-TestSet-PDU) for which the operation failed. Otherwise, res.index is set to 0.
7.2.4.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 as described in section 4.2.5 of RFC 1905 [13].
After carrying out the undo process, the subagent sends an agentx-Response-PDU in reply, with its res.error field set to one of the following SNMPv2 PDU error-status values (see section 3, "Definitions", in RFC 1905 [13]):
noError (0),
undoFailed (15)If this value is `undoFailed', the res.index field must be set to the index of the VarBind (as it occurred in the agentx-TestSet-PDU) for which the operation failed. Otherwise, res.index is set to 0.
This PDU also signals the end of processing for the management operation started by the previous TestSet-PDU. The subagent should release resources, etc., as described in section 7.2.4.4, "Subagent Processing of the agentx-CleanupSet-PDU" 🧹
7.2.4.4. Subagent Processing of the agentx-CleanupSet-PDU 🌈
The agentx-CleanupSet-PDU signals the end of processing for the management operation requested in the previous TestSet-PDU. It's the subagent's cue that it may now release any resources it reserved to carry out the management request. No response is sent by the subagent 🤫
7.2.5. Master Agent Processing of AgentX Responses 👑
The master agent now marshals all subagent AgentX response PDUs and builds an SNMP response PDU. The next several subsections describe the initial processing of all subagent AgentX response PDUs, followed by the subsequent processing for each specific subagent Response. Think of it as a little assembly line 🍓
7.2.5.1. Common Processing of All AgentX Response PDUs 💜
- If a response is not received on a session within the timeout interval for this dispatch, it is treated as if the subagent had returned `genErr', and it's processed as described below.
A timeout can happen for a variety of reasons, and it does not necessarily mean the subagent has failed or is malfunctioning. So the master agent's response to a subagent timeout is implementation-specific, but with the following constraint:
A session that times out on three consecutive AgentX requests is considered unable to respond, and the master agent must close the AgentX session as described in section 7.1.8, "Processing the agentx-Close-PDU", step (2). Three strikes and you're out 💀
- Otherwise, the h.packetID, h.sessionID, and h.transactionID fields of the AgentX response PDU are used to correlate subagent responses. If the response does not pertain to this SNMP operation, it is ignored 🙈
- Otherwise, the responses are processed jointly to form the SNMP response PDU. ✨
7.2.5.2. Processing of Responses to agentx-Get-PDUs 🎀
After common processing of the subagent's response to an agentx-Get-PDU (see section 7.2.5.1, "Common Processing of All AgentX Response PDUs", above), processing continues with the following 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. If res.error contains an AgentX-specific value (e.g.parseError'), the SNMP response PDU's error code is set to genErr instead. Also, the SNMP response PDU's error index is set to the index of the variable binding corresponding to the failed VarBind in the subagent's AgentX response PDU.
All other AgentX response PDUs received due to processing this SNMP request are ignored. Processing is complete, and the SNMP Response PDU is ready to be sent (see section 7.2.6, "Sending the SNMP Response-PDU") 🦋
- Otherwise, the content of each VarBind in the AgentX response PDU is used to update the corresponding variable binding in the SNMP Response-PDU. 💖
7.2.5.3. Processing of Responses to agentx-GetNext-PDU and agentx-GetBulk-PDU ✨
Okay bestie, so once the common processing of the subagent's response to an agentx-GetNext-PDU or agentx-GetBulk-PDU is done (see section 7.2.5.1, "Common Processing of All AgentX Response PDUs", above), we keep going with these steps 💅
- For any received AgentX response PDU, if res.error is not
noError', the SNMP response PDU's error code gets set to that value. If res.error holds an AgentX specific value (e.g.parseError'), the error code gets set to genErr instead 🙈 The SNMP response PDU's error index also gets set to the index of the VarBind that matches the failed VarBind in the subagent's AgentX response PDU.
All the other AgentX response PDUs that came back for this SNMP request get ignored 🗑️ and we're done! The SNMP response PDU is ready to go out (see section 7.2.6, "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 🎀
Once all the expected AgentX response PDUs have been processed, if any VarBinds still have the value `endOfMibView' in their v.type fields, then processing must continue 😭
- A brand new round of AgentX request dispatching kicks off (as described in section 7.2.1.2, "agentx-GetNext-PDU"), but this time only the VarBinds whose v.type is `endOfMibView' get processed 🔁
- For each of those VarBinds, we find an authoritative target MIB region where the master agent expects to find suitable MIB variables 🔍 The target session is whichever session this new target region was registered on.
The starting OID in each SearchRange gets set to the v.name of the matching VarBind, and its "include" field is set to 0 🦋
- The transactionID has to be identical to the value used in the previous iteration 🫶
- The AgentX PDUs get sent on the target session(s), and their responses are received and processed using the steps in section 7.2.5, "Master Agent Processing of AgentX Responses" ✨
- This whole thing keeps looping until a complete SNMP Response-PDU has been built, or until there are no authoritative MIB regions left to query 🌈
Now, the r.subtree for the new target region from step 4) may not lexicographically succeed the r.subtree for the region that returned `endOfMibView'. Lowkey plot twist, right? 😳 Here's an example registry to show what I mean:
session A `mib-2' (1.3.6.1.2.1)
session B `ip' (1.3.6.1.2.1.4)
session C `tcp' (1.3.6.1.2.1.6)So if, while processing a GetNext-Request-PDU, session B returns `endOfMibView' for a variable name inside 1.3.6.1.2.1.4, the target MIB region from step 4) would be 1.3.6.1.2.1 (since it may contain variables whose names come before 1.3.6.1.2.1.6) 🧚
Also, if session A returned variables from inside 1.3.6.1.2.1.6, those variables must be discarded, because session A is NOT authoritative for that region 🚫 Main character energy for session C, honestly 👑
7.2.5.4. Processing of Responses to agentx-TestSet-PDUs 🎀
After common processing of the subagent's response to an agentx-TestSet-PDU (see section 7.2.5.1, "Common Processing of All AgentX Response PDUs", above), we continue with the further exchange of AgentX PDUs 💌 The value of h.transactionID in the agentx-CommitSet, -UndoSet, and -CleanupSet-PDUs has to be identical to the value sent in the testSet-PDU 🔐
The state transitions and PDU sequences are shown in section 7.3, "State Transitions" 🗺️
Every session that has been sent an agentx-TestSet-PDU for this particular transaction is called an "involved session" below 🫂
- If any target session's response is not `noError', all the other agentx-Response-PDUs received due to processing this SNMP request get ignored 🙅
An agentx-CleanupSet-PDU gets sent to all involved sessions. Processing is complete, and the SNMP response PDU gets constructed as described below in 7.2.6, "Sending the SNMP Response-PDU" 🧹
- Otherwise, an agentx-CommitSet-PDU gets sent to all involved sessions 🚀
7.2.5.5. Processing of Responses to agentx-CommitSet-PDUs 💖
After common processing of the subagent's response to an agentx-CommitSet-PDU (see section 7.2.5.1, "Common Processing of All AgentX Response PDUs", above), we continue with these steps:
- If any response is not
noError', the SNMP response PDU's error code is set to that value. If res.error contains an AgentX specific value (e.g.parseError'), the error code is set to genErr instead 😬 The SNMP response PDU's error index is set to the index of the VarBind that matches the failed VarBind in the agentx-TestSet-PDU.
An agentx-UndoSet-PDU is sent to each target session that got an agentx-CommitSet-PDU. An agentx-CleanupSet-PDU goes to the rest of the involved sessions 🧽
- Otherwise, an agentx-CleanupSet-PDU is sent to all involved sessions. Processing is complete, and the SNMP response PDU gets constructed as described below in section 7.2.6, "Sending the SNMP Response-PDU" ✨
7.2.5.6. Processing of Responses to agentx-UndoSet-PDUs 🌸
After common processing of the subagent's response to an agentx-UndoSet-PDU (see section 7.2.5.1, "Common Processing of All AgentX Response PDUs", above), we continue with these steps:
- If any response is `undoFailed', the SNMP response PDU's error code is set to that value. The SNMP response PDU's error index is also set to 0 💀
- Otherwise, if any response is not
noError', the SNMP response PDU's error code is set to that value. The SNMP response PDU's error index is set to the index of the VarBind that matches the failed VarBind in the agentx-TestSet-PDU. If res.error is an AgentX specific value (e.g.parseError'), the error code is set to genErr instead 🙈 - Otherwise, the SNMP response PDU's error code and error index were already set in section 7.2.5.5 step 1) 🫶
7.2.6. Sending the SNMP Response-PDU 📬
Once the processing in section 7.2.5, "Master Agent Processing of AgentX Responses" is done, 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 send it back to the originator of the SNMP management request. Note that this might involve changing the PDU contents (for instance, swapping out the original VarBinds if an error condition has to be returned) 🔄
The response PDU may also be altered so it works with the SNMPv1 PDU 🕰️ In those cases, the required PDU mapping is the one defined in RFC 2089 [25]. (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 comes back 🙃)
7.2.7. MIB Views 👀
AgentX subagents are not aware of MIB views, since view information is not contained in AgentX PDUs 🙅♀️
As said above, the procedures described in section 7, "Elements of Procedure", of this memo are not meant to constrain the internal architecture of any conformant implementation 🏗️ In particular, the master agent procedures described in section 7.2.1, "Dispatching AgentX PDUs" and in section 7.2.5, "Master Agent Processing of AgentX Responses" may be changed to optimize AgentX exchanges when implementing MIB views 🔧
Those optimizations are beyond the scope of this memo. But note that section 7.2.3, "Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs", defines subagent behavior in such a way that changes to SearchRanges may be used in those 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.4.1 | | | |
Receive | All varbinds | | | |
TestSet | OK? | X | X | X | X
PDU | Yes ->B | | | |
| No ->D | | | |
---------+---------------+--------------+---------+--------+--------
| | 7.2.4.2 | | |
Receive | | NoError? | | |
Commit- | X | Yes ->C | X | X | X
Set PDU | | No ->E | | |
---------+---------------+--------------+---------+--------+--------
Receive | | | 7.2.4.3 | |7.2.4.3
UndoSet | X | X | ->done | X | ->done
PDU | | | | |
---------+---------------+--------------+---------+--------+--------
Receive | | 7.2.4.4 | 7.2.4.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 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 may lead to 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 🦋
okay so this table is the master agent's point of view on how a transport connection gets set up and torn down 🔥 you read the EVENT column going down and the STATE columns going across, and the arrows (->B, ->A) tell you where things end up 💅
STATE
+--------------+--------------
| A | B
| No transport | Transport
| | connected
| |
EVENT | |
----------------+--------------+--------------
Transport | |
connect | ->B | X
indication | |
----------------+--------------+--------------
Receive | | if no resources
Open-PDU | | available
| | 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
| X |this transport
| |
| | ->A
----------------+--------------+--------------7.3.3. Session States 🎀
same energy here, but now we're zooming in on sessions 🧚 this one is also from the master agent's side, covering how a session gets set up and torn down ✨
STATE
+-------------+----------------
| A | B
| No session | Session
| | established
EVENT | |
---------------+-------------+----------------
| 7.1.1 |
Receive | | X
Open PDU | ->B |
---------------+-------------+----------------
| | 7.1.8
Receive | X |
Close PDU | | ->A
---------------+-------------+----------------
Receive | | 7.1.4
Register PDU | X |
| | ->B
---------------+-------------+----------------
Receive | | 7.1.5
Unregister | X |
PDU | | ->B
---------------+-------------+----------------
Receive | |
Get PDU | |
GetNext PDU | |
GetBulk PDU | X | X
TestSet PDU | |
CommitSet PDU | |
UndoSet PDU | |
CleanupSet PDU | |
---------------+-------------+----------------
Receive | | 7.1.10
Notify PDU | X |
| | ->B
---------------+-------------+----------------
Receive Ping | | 7.1.11
PDU | X |
| | ->B
---------------+-------------+----------------
(continued next page)
---------------+-------------+----------------
Receive | | 7.1.2
IndexAllocate | X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.3
IndexDeallocate| X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.6
AddAgentxCaps | X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.7
RemoveAgentxCap| X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.2.5
Response PDU | X |
| | ->B
---------------+-------------+----------------
Receive | |
Other PDU | X | X
---------------+-------------+----------------8. Transport Mappings 🌈
the AgentX PDU formats, encodings, and elements of procedure are the same no matter what transport is underneath 🫶 so the transport is just the delivery truck, the rules stay the same 🚚💖
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 use that port number to connect to the master agent 🧚
8.1.2. Operation
once a TCP connection is up, the AgentX peers use it to carry all AgentX PDUs 💅 you can run multiple AgentX sessions over the same TCP connection, and the PDUs go inside a session 🦋 the peers are the ones responsible for mapping the h.sessionID to a particular TCP connection, so it's on them to keep track 🫶
the AgentX entity must not "interleave" AgentX PDUs within the TCP byte stream 🙈 all the bytes of one PDU have to go out before any bytes of a different PDU do 💀 and the receiving entity has to be ready for TCP to hand over byte sequences that don't line up with PDU boundaries, so it can't assume the chunks match up neatly 😭
8.2. AgentX over UNIX-domain Sockets 🍓
lots of (BSD-derived) UNIX implementations support the UNIX pathname address family (AF_UNIX) for socket communication 💜 it's a super convenient way to send and receive data between processes on the same host 🎀
this mapping 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, implementation-specific endpoints too 🌈)
this endpoint name uses the character set encoding native to the managed node, and it represents a UNIX-domain stream (SOCK_STREAM) socket 🔥
8.2.2. Operation
once a connection is established, the AgentX peers use it to carry all AgentX PDUs 💖
you can run multiple AgentX sessions over the same connection, and AgentX PDUs are sent within an AgentX session 🦋 the peers are responsible for mapping the h.sessionID to a particular connection 🫶
the AgentX entity must not "interleave" AgentX PDUs within the socket byte stream 🙈 all the bytes of one PDU must be sent before any bytes of a different PDU 💀 the receiving entity must also be prepared for the socket to deliver byte sequences that don't coincide with PDU boundaries 😭
9. Security Considerations 🔐
okay bestie, this part is SERIOUS 💀 this memo defines a protocol between two processing entities, and the master agent is assumed to do the authentication of received SNMP requests and to control access to management information 👑 the master agent handles these security operations on its own, independently of the subagent 🛡️
there are three questions security has to answer:
- 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?
answer to question three: a subagent can register any subtree (subject to AgentX elements of procedure, section 7.1.4, "Processing the agentx-Register-PDU") 😬 right now AgentX has no access control mechanism defined 🚨 the concern is that a malicious subagent could register an unauthorized "sensitive" subtree and see modification requests to those objects 👀 or it could give its own clever answers to NMS queries and make the NMS do something that leads to information disclosure or other damage 💀
⚠️ this is the scary part: nothing in AgentX stops a sketchy subagent from registering sensitive subtrees, so watch what gets registered 😭
answer to question two: no 🙅♀️
now for question one 🎀 AgentX doesn't have a mechanism for authorizing or refusing session initiations 💅 so controlling subagent access to the master agent can only be done at a lower layer (e.g., transport) 🦋
a subagent can connect to a master agent using either a network transport mechanism (e.g., TCP), or a "local" mechanism (e.g., shared memory, named pipes) 🌸
when a local transport mechanism is used and both the subagent and master agent are running on the same host, connection authorization can be delegated to the 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, SSL, or IPsec SHOULD be used to control and protect subagent connections in this mode of operation 🔒
however, we RECOMMEND 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 [26] 🌈
this document was produced by the IETF Agent Extensibility (AgentX) Working Group, and it especially benefited from the contributions of the following working group members 🎀
David Battle, Uri Blumenthal, Jeff Case, Maria Greene, Lauren Heintz, Dave Keeney, Harmen van der Linde, Bob Natale, Aleksey Romanov, Don Ryan, and Juergen Schoenwaelder 🫶
an honorable mention goes to Randy Presuhn 🥹 for his numerous technical contributions to this specification, for his many answers on (and hosting of) the AgentX e-mail list and ftp site, and for the valued support and guidance he gave the Working Group chair 👏✨
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.com
11. Authors' and Editor's Addresses 🦋
Mike Daniele Compaq Computer Corporation 110 Spit Brook Rd Nashua, NH 03062
Phone: +1-603-881-1423 EMail: daniele@zk3.dec.com
Bert Wijnen IBM T.J.Watson Research Schagen 33 3461 GL Linschoten Netherlands
Phone: +31-348-432-794 EMail: wijnen@vnet.ibm.com
Mark Ellison (WG editor) Ellison Software Consulting, Inc. 38 Salem Road Atkinson, NH 03811
Phone: +1-603-362-9270 EMail: ellison@world.std.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.com
12. References 📚
Okay bestie, here's the full reading list 🦋 Every single one of these is cited somewhere in the spec, so don't skip any 💅
- [1] Harrington, D., Presuhn, R. and B. Wijnen, "An Architecture for Describing SNMP Management Frameworks", RFC 2571, April 1999.
- [2] Rose, M. and K. McCloghrie, "Structure and Identification of Management Information for TCP/IP-based Internets", STD 16, RFC 1155, May 1990.
- [3] Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD 16, RFC 1212, March 1991.
- [4] Rose, M., "A Convention for Defining Traps for use with the SNMP", RFC 1215, March 1991.
- [5] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999.
- [6] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999.
- [7] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Conformance Statements for SMIv2", STD 58, RFC 2580, April 1999.
- [8] Case, J., Fedor, M., Schoffstall, M. and J. Davin, "Simple Network Management Protocol", STD 15, RFC 1157, May 1990.
- [9] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Introduction to Community-based SNMPv2", RFC 1901, January 1996.
- [10] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1906, January 1996.
- [11] Case, J., Harrington D., Presuhn R. and B. Wijnen, "Message Processing and Dispatching for the Simple Network Management Protocol (SNMP)", RFC 2572, April 1999.
- [12] Blumenthal, U. and B. Wijnen, "User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3)", RFC 2574, April 1999.
- [13] 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.
- [14] Levi, D., Meyer, P. and B. Stewart, "SNMPv3 Applications", RFC 2573, April 1999.
- [15] Wijnen, B., Presuhn, R. and K. McCloghrie, "View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP)", RFC 2575, April 1999.
- [16] Case, J., Mundy, R., Partain, D. and B. Stewart, "Introduction to Version 3 of the Internet-standard Network Management Framework", RFC 2570, April 1999.
- [17] 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.
- [18] Information processing systems - Open Systems Interconnection - Specification of Abstract Syntax Notation One (ASN.1), International Organization for Standardization. International Standard 8824, (December, 1987).
- [19] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB using SMIv2", RFC 2233, November 1997.
- [20] Case, J., "FDDI Management Information Base", RFC 1285, January 1992.
- [21] Krupczak, C. and J. Saperia, "Definitions of System-Level Managed Objects for Applications", RFC 2287, April 1997.
- [22] Kalbfleisch, C., Krupczak, C., Presuhn, R. and J. Saperia, "Application Management MIB", RFC 2564, May 1999.
- [23] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1700, October 1994.
- [24] 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.
- [25] Wijnen, B. and D. Levi, "V2ToV1: Mapping SNMPv2 onto SNMPv1 Within a Bilingual SNMP Agent", RFC 2089, January 1997.
- [26] 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.
- [27] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
13. Notices 💌
Now for the legal-ish bit, but make it cute 🎀
The IETF doesn't take a side on whether any intellectual property or other rights apply to the tech in this doc, or whether you can get a license to use them. It also doesn't say it has gone looking for any of those rights 🫣 For the IETF's rules on rights in standards-track and standards-related docs, check BCP-11. Claims of rights that were filed for publication, promises to offer licenses, or the results of attempts to get a general license for implementers or users can all be requested from the IETF Secretariat 📬
The IETF also invites anyone to flag any copyrights, patents, patent applications, or other proprietary rights that might cover technology needed to practice this standard. Send that info to the IETF Executive Director 💜
A. Changes relative to RFC 2257 ✨
Changes on the wire: okay, these are the ones that actually change what goes over the wire, so pay attention bestie 👀
- The
agentx-Notify-PDUandagentx-Close-PDUnow generate anagentx-Response-PDU. 📨 - The
res.errorfield may contain three new error codes:parseFailed(266),requestDenied(267), andprocessingError(268). 🚨
Clarifications to the text of the memo: no wire changes here, just making the writing way clearer 💅
- Modified the text of step (4) in section 4.2, "Applicability", to separate the two concerns of row creation, and counters that count rows.
- The use of the
r.range_subidfield is more clearly defined in section 6.2.3, "The agentx-Register-PDU". - Default priority (127) for registration added to the description of
r.priorityin section 6.2.3, "The agentx-Register-PDU". - Made the distinction of "administrative processing" PDUs and "SNMP request processing" PDUs in section 6.1, "AgentX PDU Header", description of
h.type. This distinction is used in the Elements of Procedure relative to theres.sysuptimeandres.errorfields. 🧠 - Rewrote portions of text in section 6.2.3, "The agentx-Register-PDU", to be more explicit about the following points:
- There is a default registration priority of 127.
- Improved the description of
r.range_subid, independent of the prefix inr.region. - Improved description and examples of how to use the registration mechanism.
- Added a description for
r.upper_bound. - Changed
r.regiontor.subtree, because the text used the terms "region", "range", and "OID range" in too loose a fashion.r.subtreecan not represent anything more by itself than a simple subtree. In conjunction withr.range_subidandr.upper_bound, it can represent a "region", that is, a union of subtrees. 🌳
- Modified the text in section 6.2.4, "The agentx-Unregister-PDU", to include a description of
u.range_subidandu.upper_bound. - Added use of the
requestDeniederror code in section 7.1.4, "Processing the agentx-Register-PDU". - Removed text in section 7, "Elements of Procedure", on parse errors and protocol errors. 🗑️
- Added a new section, 7.1, "Processing AgentX Administrative Messages", which defines common processing and how to use the
parseErrorandprocessingErrorinstead of closing a session, and how to handle context. 🎀 - Removed the common processing text from the other administrative processing Elements of Procedure sections, and added a reference to section 7.1, "Processing AgentX Administrative Messages". The affected sections are:
- 7.1.2, "Processing the agentx-IndexAllocate-PDU"
- 7.1.3, "Processing the agentx-IndexDeallocate-PDU"
- 7.1.4, "Processing the agentx-Register-PDU"
- 7.1.5, "Processing the agentx-Unregister-PDU"
- 7.1.6, "Processing the agentx-AddAgentCaps-PDU"
- 7.1.7, "Processing the agentx-RemoveAgentCaps-PDU"
- 7.1.8, "Processing the agentx-Close-PDU"
- 7.1.10, "Processing the agentx-Notify-PDU"
- 7.1.11, "Processing the agentx-Ping-PDU"
- Reworked the text in section 7.1.1, "Processing the agentx-Open-PDU", to include new error codes, and, to eliminate reference to an indicated context.
- Modified the text in section 7.1.10, "Processing the agentx-Notify-PDU", to state that context checking is performed.
- Substantially modified the text in section 7.1.4.1, "Handling Duplicate and Overlapping Subtrees". 🔁
- Removed the section on "Using the agentx-IndexAllocate-PDU" and added section 7.1.4.2, "Registering Stuff". This change is intended to provide a more concise and a more cohesive description of how things are supposed to work. ✨
- Modified the test in section 7.1.5, "Processing the agentx-Unregister-PDU", to require a match on
u.range_subidand onu.upper_boundwhen these fields were applicable in the corresponding agentx-Register-PDU. - Removed all references to "splitting", and all uses of the term "OID range". The text now refers to regions or subtrees directly, and relies on rule (1), "Honoring the Registry", in section 7.2.1, "Dispatching AgentX PDUs". 👑
- Modified text in clause 4(c) of section 7.2.1, "Dispatching AgentX PDUs", clarifying that the master agent can use its implementation-specific default timeout value when the timeout value registered by the subagent is impractical.
- Added text in section 7.2.2, "Subagent Processing", describing common processing.
- Added an example to the text in section 7.2.5.3, "Processing of Responses to agentx-GetNext-PDU and agentx-GetBulk-PDU", and removed the definition of "contains" from this section.
- Modified text in step (1) of section 7.2.5.5, "Processing of Responses to agentx-CommitSet-PDUs", eliminating directive for master agent to ignore additional responses to agentx-CommitSet-PDUs after the first error response.
- Modified text in section 7.2.5.6, "Processing of Responses to agentx-UndoSet-PDUs", cleaning up commit/undo elements of procedure per feedback received on the AgentX email list. 📬
- Modified the text in section 8.1.2, "Operation", to explicitly prohibit interleaved sends, and, added a caution about exchanging AgentX messages via TCP. ⚠️
- Modified text to be more explicit that the OID in the agentx-Allocate-PDU is an OBJECT-TYPE and does not contain any instance sub-identifiers.
- Replaced the term "subagent" with the term "session" in many places throughout the text. 💜
- Modified the text relative to master agent processing of the agentx-TestSet-PDU, agentx-CommitSet-PDU, and the agentx-UndoSet-PDU to explicitly state that only "involved" sessions receive an agentx-CommitSet-PDU, and possibly, an agentx-UndoSet-PDU.
- Modified the text to use the term "transaction", instead of "packet" (and others), where appropriate. This helps distinguish the overall transaction from a particular sequence of packets or PDUs. 🧩
- Modified the text to explicitly state that a session is not required to support concurrent sets.
- Added section 13, "Notices". 📜
- Added text to section 1, Introduction, relative to BCP 14 key words.
- Modified text to section 9, Security Considerations, to include use of BCP 14 key words.
- Modified text to section 9, Security Considerations, to include IPSEC as a suggested Transport Layer Security. 🔐
Full Copyright Statement 💖
Copyright (C) The Internet Society (2000). All Rights Reserved. 🌈
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. 🫶
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 💀
Acknowledgement 🌸
Funding for the RFC Editor function is currently provided by the Internet Society. 💅
📦 where this page comes from
- ietf: rfc2741 2000-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms