idnits 2.17.1 draft-ietf-agentx-ext-pro-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 8 longer pages, the longest (page 2) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 9 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1192: '... (u.context) OPTIONAL...' RFC 2119 keyword, line 1250: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1322: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1351: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1384: '... (t.context) OPTIONAL...' (4 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 3300 has weird spacing: '...ll) and autho...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1-22' on line 2058 -- Looks like a reference, but probably isn't: '1-4' on line 2066 -- Looks like a reference, but probably isn't: '1-5' on line 2079 -- Possible downref: Non-RFC (?) normative reference: ref. '1' ** Obsolete normative reference: RFC 1902 (ref. '2') (Obsoleted by RFC 2578) ** Obsolete normative reference: RFC 1903 (ref. '3') (Obsoleted by RFC 2579) ** Obsolete normative reference: RFC 1905 (ref. '4') (Obsoleted by RFC 3416) ** Obsolete normative reference: RFC 1907 (ref. '5') (Obsoleted by RFC 3418) ** Downref: Normative reference to an Historic RFC: RFC 1157 (ref. '6') ** Downref: Normative reference to an Experimental RFC: RFC 1592 (ref. '7') ** Obsolete normative reference: RFC 1908 (ref. '8') (Obsoleted by RFC 2576) ** Obsolete normative reference: RFC 2089 (ref. '9') (Obsoleted by RFC 2576) ** Obsolete normative reference: RFC 1904 (ref. '10') (Obsoleted by RFC 2580) ** Obsolete normative reference: RFC 1573 (ref. '11') (Obsoleted by RFC 2233) ** Downref: Normative reference to an Historic RFC: RFC 1285 (ref. '12') == Outdated reference: A later version (-08) exists of draft-ietf-applmib-sysapplmib-05 Summary: 21 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Agent Extensibility (AgentX) Protocol 3 Version 1 5 7 Mike Daniele 8 Digital Equipment Corporation 9 daniele@zk3.dec.com 11 Bert Wijnen 12 T.J. Watson Research Center, IBM Corp. 13 wijnen@vnet.ibm.com 15 Dale Francisco (editor) 16 Cisco Systems, Inc. 17 dfrancis@cisco.com 19 Status of this Memo 21 This document is an Internet-Draft. Internet-Drafts are working 22 documents of the Internet Engineering Task Force (IETF), its areas, 23 and its working groups. Note that other groups may also distribute 24 working documents as Internet-Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six 27 months and may be updated, replaced, or obsoleted by other documents 28 at any time. It is inappropriate to use Internet-Drafts as 29 reference material or to cite them other than as "work in progress". 31 To learn the current status of any Internet-Draft, please check the 32 "1id-abstracts.txt" listing contained in the Internet-Drafts 33 Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net 34 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 35 Rim). 37 Daniele/Wijnen Expires September 1997 [Page 1] 38 1 Introduction......................................................5 40 2 The SNMP Framework................................................5 41 2.1 A Note on Terminology.........................................5 43 3 Extending the MIB.................................................6 44 3.1 Motivation for AgentX.........................................6 46 4 AgentX Framework..................................................7 47 4.1 AgentX Roles..................................................8 48 4.2 Applicability.................................................9 49 4.3 Design Features of AgentX....................................10 50 4.4 Non-Goals....................................................11 52 5 AgentX Encodings.................................................12 53 5.1 Object Identifier............................................12 54 5.2 SearchRange..................................................14 55 5.3 Octet String.................................................16 56 5.4 Value Representation.........................................17 58 6 Protocol Definitions.............................................19 59 6.1 AgentX PDU Header............................................19 60 6.1.1 Context..................................................21 61 6.2 AgentX PDUs..................................................23 62 6.2.1 The agentx-Open-PDU......................................23 63 6.2.2 The agentx-Close-PDU.....................................24 64 6.2.3 The agentx-Register-PDU..................................26 65 6.2.4 The agentx-Unregister-PDU................................29 66 6.2.5 The agentx-Get-PDU.......................................31 67 6.2.6 The agentx-GetNext-PDU...................................32 68 6.2.7 The agentx-GetBulk-PDU...................................33 69 6.2.8 The agentx-TestSet-PDU...................................34 70 6.2.9 The agentx-CommitSet, -UndoSet, -CleanupSet 71 PDUs.....................................................35 72 6.2.10 The agentx-Notify-PDU...................................36 73 6.2.11 The agentx-Ping-PDU.....................................37 74 6.2.12 The agentx-IndexAllocate-PDU............................38 75 6.2.13 The agentx-IndexDeallocate-PDU..........................39 76 6.2.14 The agentx-AddAgentCaps-PDU.............................40 77 6.2.15 The agentx-RemoveAgentCaps-PDU..........................42 78 6.2.16 The agentx-Response-PDU.................................43 80 7 Elements of Procedure............................................45 81 7.1 Processing AgentX Administrative Messages....................45 82 7.1.1 Processing the agentx-Open-PDU...........................45 83 7.1.2 Processing the agentx-IndexAllocate-PDU..................46 84 7.1.3 Using the agentx-IndexAllocate-PDU.......................48 85 7.1.4 Processing the agentx-IndexDeallocate-PDU................49 86 7.1.5 Processing the agentx-Register-PDU.......................50 87 7.1.5.1 Handling Duplicate OID Ranges........................53 88 7.1.6 Processing the agentx-Unregister-PDU.....................53 90 Daniele/Wijnen Expires September 1997 [Page 2] 91 7.1.7 Processing the agentx-AddAgentCaps-PDU...................54 92 7.1.8 Processing the agentx-RemoveAgentCaps-PDU................54 93 7.1.9 Processing the agentx-Close-PDU..........................55 94 7.1.10 Detecting Connection Loss...............................55 95 7.1.11 Processing the agentx-Notify-PDU........................55 96 7.1.12 Processing the agentx-Ping-PDU..........................56 97 7.2 Processing Received SNMP Protocol Messages...................57 98 7.2.1 Dispatching AgentX PDUs..................................57 99 7.2.1.1 agentx-Get-PDU.......................................59 100 7.2.1.2 agentx-GetNext-PDU...................................60 101 7.2.1.3 agentx-GetBulk-PDU...................................61 102 7.2.1.4 agentx-TestSet-PDU...................................62 103 7.2.1.5 Dispatch.............................................62 104 7.2.2 Subagent Processing of agentx-Get, GetNext, 105 GetBulk-PDUs.............................................63 106 7.2.2.1 Subagent Processing of the agentx-Get-PDU............63 107 7.2.2.2 Subagent Processing of the 108 agentx-GetNext-PDU...................................63 109 7.2.2.3 Subagent Processing of the 110 agentx-GetBulk-PDU...................................64 111 7.2.3 Subagent Processing of agentx-TestSet, 112 -CommitSet, -UndoSet, -CleanupSet-PDUs...................65 113 7.2.3.1 Subagent Processing of the 114 agentx-TestSet-PDU...................................66 115 7.2.3.2 Subagent Processing of the 116 agentx-CommitSet-PDU.................................66 117 7.2.3.3 Subagent Processing of the 118 agentx-UndoSet-PDU...................................67 119 7.2.3.4 Subagent Processing of the 120 agentx-CleanupSet-PDU................................67 121 7.2.4 Master Agent Processing of AgentX Responses..............67 122 7.2.4.1 Common Processing of All AgentX Response 123 PDUs.................................................67 124 7.2.4.2 Processing of Responses to agentx-Get-PDUs...........68 125 7.2.4.3 Processing of Responses to 126 agentx-GetNext-PDU and agentx-GetBulk-PDU............68 127 7.2.4.4 Processing of Responses to 128 agentx-TestSet-PDUs..................................69 129 7.2.4.5 Processing of Responses to 130 agentx-CommitSet-PDUs................................70 131 7.2.4.6 Processing of Responses to 132 agentx-UndoSet-PDUs..................................70 133 7.2.5 Sending the SNMP Response-PDU............................70 134 7.2.6 MIB Views................................................71 136 8 Transport Mappings...............................................71 137 8.1 AgentX over TCP..............................................71 138 8.1.1 Well-known Values........................................71 139 8.1.2 Operation................................................71 140 8.2 AgentX over UNIX-domain Sockets..............................72 141 8.2.1 Well-known Values........................................72 143 Daniele/Wijnen Expires September 1997 [Page 3] 144 8.2.2 Operation................................................72 146 9 Security Considerations..........................................72 148 10 Acknowledgements................................................74 150 11 Authors' and Editor's Addresses.................................74 152 12 References......................................................75 154 Daniele/Wijnen Expires September 1997 [Page 4] 155 1. Introduction 157 This memo defines a standardized framework for extensible SNMP 158 agents. It defines processing entities called master agents 159 and subagents, a protocol (AgentX) used to communicate between 160 them, and the elements of procedure by which the extensible agent 161 processes SNMP protocol messages. 163 2. The SNMP Framework 165 A management system contains: several (potentially many) nodes, 166 each with a processing entity, termed an agent, which has access to 167 management instrumentation; at least one management station; and, a 168 management protocol, used to convey management information between 169 the agents and management stations. Operations of the protocol are 170 carried out under an administrative framework which defines 171 authentication, authorization, access control, and privacy 172 policies. 174 Management stations execute management applications which monitor 175 and control managed elements. Managed elements are devices such as 176 hosts, routers, terminal servers, etc., which are monitored and 177 controlled via access to their management information. 179 Management information is viewed as a collection of managed objects, 180 residing in a virtual information store, termed the Management 181 Information Base (MIB). Collections of related objects are defined 182 in MIB modules. These modules are written using a subset of OSI's 183 Abstract Syntax Notation One (ASN.1) [1], termed the Structure of 184 Management Information (SMI) (see RFC 1902 [2]). 186 2.1. A Note on Terminology 188 The term "variable" refers to an instance of a non-aggregate 189 object type defined according to the conventions set forth in the 190 SMI (RFC 1902, [2]) or the textual conventions based on the SMI 191 (RFC 1903 [3]). The term "variable binding" normally refers to 192 the pairing of the name of a variable and its associated value. 193 However, if certain kinds of exceptional conditions occur during 194 processing of a retrieval request, a variable binding will pair a 195 name and an indication of that exception. 197 A variable-binding list is a simple list of variable bindings. 199 The name of a variable is an OBJECT IDENTIFIER, which is the 200 concatenation of the OBJECT IDENTIFIER of the corresponding object 201 type together with an OBJECT IDENTIFIER fragment identifying the 202 instance. The OBJECT IDENTIFIER of the corresponding object-type is 203 called the OBJECT IDENTIFIER prefix of the variable. 204 For the purpose of exposition, the original Internet-standard 206 Daniele/Wijnen Expires September 1997 [Page 5] 207 Network Management Framework, as described in RFCs 1155 (STD 16), 208 1157 (STD 15), and 1212 (STD 16), is termed the SNMP version 1 209 framework (SNMPv1). The current framework, as described in RFCs 210 1902-1908, is termed the SNMP version 2 framework (SNMPv2). 212 3. Extending the MIB 214 New MIB modules that extend the Internet-standard MIB are 215 continuously being defined by various IETF working groups. It is 216 also common for enterprises or individuals to create or extend 217 enterprise-specific or experimental MIBs. 219 As a result, managed devices are frequently complex collections of 220 manageable components that have been independently installed on a 221 managed node. Each component provides instrumentation for the 222 managed objects defined in the MIB module(s) it implements. 224 Neither the SNMP version 1 or version 2 framework addresses how 225 managed objects may be dynamically added to or removed from the 226 agent view within a particular managed node. 228 3.1. Motivation for AgentX 230 This very real need to dynamically extend the management objects 231 within a node has given rise to a variety of "extensible agents", 232 which typically comprise 234 - a "master" agent that is available on the standard transport 235 address and that accepts SNMP protocol messages 237 - a set of "subagents" that each contain management 238 instrumentation 240 - a protocol that operates between the master agent and subagents, 241 permitting subagents to "connect" to the master agent, and the 242 master agent to multiplex received SNMP protocol messages 243 amongst the subagents. 245 - a set of tools to aid subagent development, and a runtime (API) 246 environment that hides much of the protocol operation between a 247 subagent and the master agent. 249 The wide deployment of extensible SNMP agents, coupled with the 250 lack of Internet standards in this area, makes it difficult to field 251 SNMP-manageable applications. A vendor may have to support several 252 different subagent environments (APIs) in order to support different 253 target platforms. 255 It can also become quite cumbersome to configure subagents and 256 (possibly multiple) master agents on a particular managed node. 258 Daniele/Wijnen Expires September 1997 [Page 6] 259 Specifying a standard protocol for agent extensibility (AgentX) 260 provides the technical foundation required to solve both of 261 these problems. Independently developed AgentX-capable master 262 agents and subagents will be able to interoperate at the protocol 263 level. Vendors can continue to differentiate their products 264 in all other respects. 266 4. AgentX Framework 268 Within the SNMP framework, a managed node contains a processing 269 entity, called an agent, which has access to management 270 information. 272 Within the AgentX framework, an agent is further defined to 273 consist of 275 - a single processing entity called the master agent, which sends 276 and receives SNMP protocol messages in an agent role (as 277 specified by the SNMP version 1 and version 2 framework 278 documents) but typically has little or no direct access to 279 management information. 281 - 0 or more processing entities called subagents, which are 282 "shielded" from the SNMP protocol messages processed by the 283 master agent, but which have access to management information. 285 The master and subagent entities communicate via AgentX protocol 286 messages, as specified in this memo. Other interfaces (if any) on 287 these entities, and their associated protocols, are outside the 288 scope of this document. While some of the AgentX protocol messages 289 appear similar in syntax and semantics to the SNMP, bear in mind 290 that AgentX is not SNMP. 292 The internal operations of AgentX are invisible to an SNMP entity 293 operating in a manager role. From a manager's point of view, an 294 extensible agent behaves exactly as would a non-extensible 295 (monolithic) agent that has access to the same management 296 instrumentation. 298 This transparency to managers is a fundamental requirement of 299 AgentX, and is what differentiates AgentX subagents from SNMP proxy 300 agents. 302 Daniele/Wijnen Expires September 1997 [Page 7] 303 4.1. AgentX Roles 305 An entity acting in a master agent role performs the following 306 functions: 308 - Accepts AgentX session establishment requests from subagents. 310 - Accepts registration of MIB regions by subagents. 312 - Sends and accepts SNMP protocol messages on the agent's 313 specified transport addresses. 315 - Implements the agent role Elements of Procedure specified 316 for the administrative framework applicable to the SNMP 317 protocol message, except where they specify performing 318 management operations. (The application of MIB views, and 319 the access control policy for the managed node, are 320 implemented by the master agent.) 322 - Provides instrumentation for the MIB objects defined in RFC 323 1907 [5], and for any MIB objects relevant to any 324 administrative framework it supports. 326 - Sends and receives AgentX protocol messages to access 327 management information, based on the current registry of MIB 328 regions. 330 - Forwards notifications on behalf of subagents. 332 An entity acting in a subagent role performs the following functions: 334 - Initiates an AgentX session with the master agent. 336 - Registers MIB regions with the master agent. 338 - Instantiates managed objects. 340 - Binds OIDs within its registered MIB regions to actual 341 variables. 343 - Performs management operations on variables. 345 - Initiates notifications. 347 Daniele/Wijnen Expires September 1997 [Page 8] 348 4.2 Applicability 350 It is intended that this draft specify the smallest amount of 351 required behavior necessary to achieve the largest benefit, 352 that is, to cover a very large number of possible MIB 353 implementations and configurations with minimum complexity and low 354 "cost of entry". 356 This section discusses several typical usage scenarios. 358 1) Subagents implement separate MIB modules--for example, 359 subagent A implements "mib-2", subagent b implements 360 "host-resources". 362 It is anticipated that this will be the most common subagent 363 configuration. 365 2) Subagents implement rows in a "simple table". A simple table 366 is one in which row creation is not specified, and for which 367 the MIB does not define an object that counts entries in the 368 table. Examples of simple tables are rdbmsDbTable, udpTable, 369 and hrSWRunTable. 371 This is the most commonly defined type of MIB table, and 372 probably represents the next most typical configuration 373 that AgentX would support. 375 3) Subagents share MIBs along non-row partitions. Subagents 376 register "chunks" of the MIB that represent multiple rows, 377 due to the nature of the MIB's index structure. Examples 378 include registering ipNetToMediaEntry.n, where n represents 379 the ifIndex value for an interface implemented by the subagent, 380 and tcpConnEntry.a.b.c.d, where a.b.c.d represents an IP 381 address on an interface implemented by the subagent. 383 AgentX supports these three common configurations, and all 384 permutations of them, completely. The consensus is that they 385 comprise a very large majority of current and likely future uses 386 of multi-vendor extensible agent configurations. 388 4) Subagents implement rows in "complex tables". Complex tables 389 here are defined as tables permitting row creation, or whose 390 MIB also defines an object that counts entries in the table. 391 Examples include the MIB-2 ifTable (due to ifNumber), and the 392 RMON historyControlTable. 394 The subagent that implements such a counter object (like 395 ifNumber) must go beyond AgentX to correctly implement it. 396 This is an implementation issue (and most new MIB designs 397 no longer include such objects). 399 Daniele/Wijnen Expires September 1997 [Page 9] 400 To implement row creation in such tables, at least one AgentX 401 subagent must register at a point "higher" in the OID tree 402 than an individual row (per AgentX's dispatching procedure). 403 Again, this is an implementation issue. 405 Scenarios in this category were thought to occur somewhat 406 rarely in configurations where subagents are independently 407 implemented by different vendors. The focus of a standard 408 protocol, however, must be in just those areas where multi- 409 vendor interoperability must be assured. 411 4.3. Design Features of AgentX 413 The primary features of the design described in this memo are 415 1) A general architectural division of labor between master 416 agent and subagent: The master agent is MIB ignorant and 417 SNMP omniscient, while the subagent is SNMP ignorant and 418 MIB omniscient. That is, master agents, exclusively, are 419 concerned with SNMP protocol operations and the translations 420 to and from AgentX protocol operations needed to carry them 421 out; subagents are exclusively concerned with management 422 instrumentation; and neither should intrude on the other's 423 territory. 425 2) A standard protocol and "rules of engagement" to enable 426 interoperability between management instrumentation and 427 extensible agents. 429 3) Mechanisms for independently developed subagents to 430 integrate into the extensible agent on a particular 431 managed node in such a way that they need not be aware 432 of any other existing subagents. 434 4) A simple, deterministic registry and dispatching algorithm. 435 For a given extensible agent configuration, there is a single 436 subagent who is "authoritative" for any particular region of 437 the MIB (where "region" may extend from an entire MIB down 438 to a single object-instance). 440 5) Performance considerations. It is likely that the master 441 agent and all subagents will reside on the same host, and 442 in such cases AgentX is more a form of inter-process 443 communication than a traditional communications protocol. 444 Some of the design decisions made with this in mind include: 446 - 32-bit alignment of data within PDUs 448 - Native byte-order encoding by subagents 450 - Large AgentX PDU payload sizes. 452 4.4 Non-Goals 454 1) Subagent-to-subagent communication. This is out of scope, 455 due to the security ramifications and complexity involved. 457 2) Subagent access (via the master agent) to MIB variables. 458 This is not addressed, since various other mechanisms 459 are available and it was not a fundamental requirement. 461 3) The ability to accommodate every conceivable extensible 462 agent configuration option. This was the most contentious 463 aspect in the drafting of this protocol. In essence, 464 certain features currently available in some commercial 465 extensible agent products are not included in AgentX. 466 Although useful or even vital in some implementation 467 strategies, the rough consensus was that these features 468 were not appropriate for an Internet Standard, or not 469 typically required for independently developed subagents 470 to coexist. The set of supported extensible agent 471 configurations is described above, in Section 4.2. 473 Some possible future version of the AgentX protocol may provide 474 coverage for one or more of these "non-goals" or for new goals 475 that might be identified after greater deployment experience. 477 5. AgentX Encodings 479 AgentX PDUs consist of a common header, followed by PDU-specific 480 data of variable length. Unlike SNMP PDUs, AgentX PDUs are not 481 encoded using the BER (as specified in ISO 8824 [1]), but are 482 transmitted as a contiguous byte stream. The data within this 483 stream is organized to provide natural alignment with respect to 484 the start of the PDU, permitting direct (integer) access by the 485 processing entities. 487 The first four fields in the header are single-byte values. 488 A bit (NETWORK_BYTE_ORDER) in the third field (h.flags) is 489 used to indicate the byte ordering of all multi-byte integer 490 values in the PDU, including those which follow in the header 491 itself. This is described in more detail in Section 6.1, 492 "AgentX PDU Header", below. 494 PDUs are depicted in this memo using the following convention 495 (where byte 1 is the first transmitted byte): 497 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 498 | byte 1 | byte 2 | byte 3 | byte 4 | 499 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 500 | byte 5 | byte 6 | byte 7 | byte 8 | 501 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 502 ... 504 Fields marked "" are reserved for future use and must be 505 zero-filled. 507 5.1. Object Identifier 509 An object identifier is encoded as a 4-byte header, followed by a 510 variable number of contiguous 4-byte fields representing 511 sub-identifiers. This representation (termed Object Identifier) is 512 as follows: 514 Object Identifier 516 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 517 | n_subid | prefix | include | | 518 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 519 | sub-identifier #1 | 520 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 521 ... 522 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 523 | sub-identifier #n_subid | 524 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 525 Object Identifier header fields: 527 n_subid 529 The number (0-128) of sub-identifiers in the object 530 identifier. An ordered list of "n_subid" 4-byte 531 sub-identifiers follows the 4-byte header. 533 prefix 535 An unsigned value used to reduce the length of object 536 identifier encodings. A non-zero value "x" is interpreted as 537 the first sub-identifier after "internet" (1.3.6.1), and 538 indicates an implicit prefix "internet.x" to the actual 539 sub-identifiers encoded in the Object Identifier. For 540 example, a prefix field value 2 indicates an implicit prefix 541 "1.3.6.1.2". A value of 0 in the prefix field indicates there 542 is no prefix to the sub-identifiers. 544 include 546 Used only when the Object Identifier is the start of a 547 SearchRange. 549 Examples: 551 sysDescr.0 (1.3.6.1.2.1.1.1.0) 553 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 554 | 4 | 2 | 0 | 0 | 555 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 556 | 1 | 557 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 558 | 1 | 559 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 560 | 1 | 561 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 562 | 0 | 563 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 565 1.2.3.4 567 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 568 | 4 | 0 | 0 | 0 | 569 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 570 | 1 | 571 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 572 | 2 | 573 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 574 | 3 | 575 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 576 | 4 | 577 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 579 A null Object Identifier consists of the 4-byte header with all 580 bytes set to 0. 582 5.2. SearchRange 584 A SearchRange consists of two Object Identifiers. In its 585 communication with a subagent, the master agent uses a SearchRange 586 to identify a requested variable binding, and, in GetNext and 587 GetBulk operations, to set an upper bound on the names of managed 588 object instances the subagent may send in reply. 590 The first Object Identifier in a SearchRange (called the starting 591 OID) indicates the beginning of the range. It is frequently (but 592 not necessarily) the name of a requested variable binding. 594 The "include" field in this OID's header is a Boolean value 595 indicating whether or not the starting OID is included in the range. 597 The second object identifier indicates the non-inclusive end of 598 the range, and its "include" field is always 0. 600 Example: To indicate a search range from 1.3.6.1.2.1.25.2 601 (inclusive) to 1.3.6.1.2.1.25.2.1 (exclusive), the SearchRange would 602 be 604 (start) 605 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 606 | 3 | 2 | 1 | 0 | 607 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 608 | 1 | 609 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 610 | 25 | 611 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 612 | 2 | 613 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 615 (end) 616 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 617 | 4 | 2 | 0 | 0 | 618 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 619 | 1 | 620 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 621 | 25 | 622 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 623 | 2 | 624 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 625 | 1 | 626 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 628 A SearchRangeList is a contiguous list of SearchRanges. 630 5.3. Octet String 632 An octet string is represented by a contiguous series of bytes, 633 beginning with a 4-byte integer whose value is the number of octets 634 in the octet string, followed by the octets themselves. This 635 representation is termed an Octet String. If the last octet does 636 not end on a 4-byte offset from the start of the Octet String, 637 padding bytes are appended to achieve alignment of following data. 638 This padding must be added even if the Octet String is the last item 639 in the PDU. Padding bytes must be zero filled. 641 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 642 | Octet String Length (L) | 643 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 644 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 645 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 646 ... 647 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 648 | Octet L - 1 | Octet L | Padding (as required) | 649 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 651 A null Octet String consists of a 4-byte length field set to 0. 653 5.4. Value Representation 655 Variable bindings may be encoded within the variable-length portion 656 of some PDUs. The representation of a variable binding (termed a 657 VarBind) consists of a 2-byte type field, a name (Object 658 Identifier), and the actual value data. 660 VarBind 662 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 663 | v.type | | 664 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 666 (v.name) 667 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 668 | n_subid | prefix | 0 | 0 | 669 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 670 | sub-identifier #1 | 671 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 672 ... 673 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 674 | sub-identifier #n_subid | 675 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 677 (v.data) 678 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 679 | data | 680 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 681 ... 682 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 683 | data | 684 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 685 VarBind fields: 687 v.type 689 Indicates the variable binding's syntax, and must be one of 690 the following (SNMPv2 SMI) values: 692 Integer (2), 693 Octet String (4), 694 Object Identifier (6), 695 IpAddress (64), 696 Counter32 (65), 697 Gauge32 (66), 698 TimeTicks (67), 699 Opaque (68), 700 Counter64 (70), 701 noSuchObject (128), 702 noSuchInstance (129), 703 endOfMibView (130) 705 v.name 707 The Object Identifier which names the variable. 709 v.data 711 The actual value, encoded as follows: 713 - Integer, Counter32, Gauge32, and TimeTicks are encoded as 714 4 contiguous bytes. If the subagent chose network byte 715 ordering (see 7.1.1., Processing the agentx-Open-PDU, 716 item 3), the bytes are ordered most significant to least 717 significant, otherwise they are ordered least significant 718 to most significant. 720 - Counter64 is encoded as 8 contiguous bytes. If the 721 subagent chose network byte ordering (see 7.1.1., 722 Processing the agentx-Open-PDU, item 3), the bytes are 723 ordered most significant to least significant, otherwise 724 they are ordered least significant to most significant. 726 - Object Identifiers are encoded as described in section 727 5.1, Object Identifier. 729 - IpAddress, Opaque, and Octet String are all octet strings 730 and are encoded as described in section 5.3, Octet String. 732 Value data always follows v.name whenever v.type is one 733 of the above types. These data bytes are present even if 734 they will not be used (as, for example, in certain types 735 of index allocation). 737 - noSuchObject, noSuchInstance, and endOfMibView do not 738 contain any encoded value. Value data never follows 739 v.name in these cases. 741 Note that the VarBind itself does not contain the value size. 742 That information is implied for the fixed-length types, and 743 explicitly contained in the encodings of variable-length types 744 (Object Identifier and Octet String). 746 A VarBindList is a contiguous list of VarBinds. 748 6. Protocol Definitions 750 6.1. AgentX PDU Header 752 The AgentX PDU header is a fixed-format, 20-octet structure: 754 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 755 | h.version | h.type | h.flags | | 756 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 757 | h.sessionID | 758 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 759 | h.transactionID | 760 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 761 | h.packetID | 762 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 763 | h.payload_length | 764 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 766 An AgentX PDU header contains the following fields: 768 h.version 770 The version of the AgentX protocol (1 for this draft). 772 h.type 774 The PDU type; one of the following values: 776 agentx-Open-PDU (1), 777 agentx-Close-PDU (2), 778 agentx-Register-PDU (3), 779 agentx-Unregister-PDU (4), 780 agentx-Get-PDU (5), 781 agentx-GetNext-PDU (6), 782 agentx-GetBulk-PDU (7), 783 agentx-TestSet-PDU (8), 784 agentx-CommitSet-PDU (9), 785 agentx-UndoSet-PDU (10), 786 agentx-CleanupSet-PDU (11), 787 agentx-Notify-PDU (12), 788 agentx-Ping-PDU (13), 789 agentx-IndexAllocate-PDU (14), 790 agentx-IndexDeallocate-PDU (15), 791 agentx-AddAgentCaps-PDU (16), 792 agentx-RemoveAgentCaps-PDU (17), 793 agentx-Response-PDU (18) 795 h.flags 797 A bitmask, with bit 0 the leftmost bit. The bit definitions 798 are as follows: 800 Bit Definition 801 --- ---------- 802 0 INSTANCE_REGISTRATION 803 1 NEW_INDEX 804 2 ANY_INDEX 805 3 NON_DEFAULT_CONTEXT 806 4 NETWORK_BYTE_ORDER 807 5-7 (reserved) 809 The NETWORK_BYTE_ORDER bit applies to all multi-byte 810 integer values in the entire AgentX packet, including 811 the remaining header fields. If set, then network byte 812 order (most significant byte first; "big endian") is 813 used. If not set, then the host byte order (which may 814 be either "big endian" or "little endian", depending 815 upon the processor architecture) is used. 817 h.sessionID 819 The session ID uniquely identifies a session over 820 which AgentX PDUs are exchanged between a subagent and 821 the master agent. The session ID has no significance 822 and no defined value in the agentx-Open-PDU sent by a 823 subagent to open a session with the master agent; in 824 this case, the master agent will assign a unique 825 sessionID that it will pass back in the corresponding 826 agentx-Response-PDU. From that point on, that same 827 sessionID will appear in every AgentX PDU exchanged 828 over that session between the master and the subagent. 829 A subagent may establish multiple AgentX sessions by 830 sending multiple agentx-Open-PDUs to the master agent. 832 In master agents that support multiple transport 833 protocols, the sessionID should be globally unique 834 rather than unique just to a particular transport. 836 h.transactionID 838 The transaction ID uniquely identifies, for a given 839 session, the single SNMP management request (and single 840 SNMP PDU) with which an AgentX PDU is associated. If 841 a single SNMP management request results in multiple 842 AgentX PDUs being sent by the master agent with the same 843 sessionID, each of these AgentX PDUs must contain the 844 same transaction ID; conversely, AgentX PDUs sent during 845 a particular session, that result from distinct SNMP 846 management requests, must have distinct transaction IDs 847 (within the limits of the 32-bit field). 849 Note that the transaction ID is not the same as the SNMP 850 PDU's request-id (as described in section 4.1 of RFC 851 1905 [4]), nor can it be, since a master agent might 852 receive SNMP requests with the same request-ids from 853 different managers. 855 The transaction ID has no significance and no defined 856 value in AgentX administrative PDUs, i.e., AgentX 857 PDUs that are not associated with an SNMP management 858 request. 860 h.packetID 862 A packet ID generated by the sender for all AgentX PDUs 863 except the agentx-Response-PDU. In an agentx-Response-PDU, 864 the packet ID must be the same as that in the received 865 AgentX PDU to which it is a response. A master agent 866 might use this field to associate subagent response PDUs 867 with their corresponding request PDUs. A subagent might 868 use this field to correlate responses to multiple 869 (batched) registrations. 871 h.payload_length 873 The size in octets of the PDU contents, excluding the 874 20-byte header. As a result of the encoding schemes 875 and PDU layouts, this value will always be either 0, 876 or a multiple of 4. 878 6.1.1. Context 880 In the SNMPv1 or v2c frameworks, the community string may be used as 881 an index into a local repository of configuration information that 882 may include community profiles or more complex context information. 883 Future versions of the SNMP will likely formalize this notion of 884 "context". 886 AgentX provides a mechanism for transmitting a context specification 887 within relevant PDUs, but does not place any constraints on the 888 content of that specification. 890 An optional context field may be present in the agentx-Register-, 891 UnRegister-, AddAgentCaps-, RemoveAgentCaps-, Get-, GetNext-, 892 GetBulk-, TestSet-, and Ping- PDUs. 894 If the NON_DEFAULT_CONTEXT bit in the AgentX header field h.flags is 895 clear, then there is no context field in the PDU, and the operation 896 refers to the default context. 898 If the NON_DEFAULT_CONTEXT bit is set, then a context field 899 immediately follows the AgentX header, and the operation refers 900 to that specific context. The context is represented as an Octet 901 String. There are no constraints on its length or contents. 903 Thus, all of these AgentX PDUs (that is, those listed immediately 904 above) refer to, or "indicate" a context, which is either the 905 default context, or a non-default context explicitly named in the 906 PDU. 908 6.2. AgentX PDUs 910 6.2.1. The agentx-Open-PDU 912 An agentx-Open-PDU is generated by a subagent to request 913 establishment of an AgentX session with the master agent. 915 (AgentX header) 917 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 918 | h.version (1) | h.type (1) | h.flags | | 919 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 920 | h.sessionID | 921 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 922 | h.transactionID | 923 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 924 | h.packetID | 925 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 926 | h.payload_length | 927 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 929 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 930 | o.timeout | | 931 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 933 (o.id) 934 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 935 | n_subid | prefix | 0 | | 936 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 937 | subidentifier #1 | 938 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 939 ... | 940 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 941 | subidentifier #n_subid | 942 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 944 (o.descr) 945 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 946 | Octet String Length (L) | 947 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 948 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 949 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 950 ... 951 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 952 | Octet L - 1 | Octet L | Padding (as required) | 953 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 954 An agentx-Open-PDU contains the following fields: 956 o.timeout 958 The length of time, in seconds, that a master agent should 959 allow to elapse after dispatching a message to a subagent 960 before it regards the subagent as not responding. This is a 961 subagent-wide default value that may be overridden by values 962 associated with specific registered MIB regions. The default 963 value of 0 indicates that no subagent-wide value is 964 requested. 966 o.id 968 An Object Identifier that identifies the subagent. Subagents 969 that do not support such an notion may send a null Object 970 Identifier. 972 o.descr 974 An Octet String containing a DisplayString describing the 975 subagent. 977 6.2.2. The agentx-Close-PDU 979 An agentx-Close-PDU issued by either a subagent or the master 980 agent terminates an AgentX session. 982 (AgentX header) 983 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 984 | h.version (1) | h.type (2) | h.flags | | 985 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 986 | h.sessionID | 987 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 988 | h.transactionID | 989 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 990 | h.packetID | 991 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 992 | h.payload_length | 993 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 995 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 996 | c.reason | | 997 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 998 An agentx-Close-PDU contains the following field: 1000 c.reason 1002 An enumerated value that gives the reason that the master 1003 agent or subagent closed the AgentX session. This field may 1004 take one of the following values: 1006 reasonOther(1) 1007 None of the following reasons 1009 reasonProtocolError(2) 1010 Too many AgentX protocol errors from peer 1012 reasonTimeouts(3) 1013 Too many timeouts waiting for peer 1015 reasonShutdown(4) 1016 Sending entity is shutting down 1018 reasonByManager(5) 1019 Due to Set operation; this reason code can 1020 be used only by the master agent, in response 1021 to an SNMP management request. 1023 6.2.3. The agentx-Register-PDU 1025 An agentx-Register-PDU is generated by a subagent for each region of 1026 the MIB variable naming tree (within one or more contexts) that it 1027 wishes to support. 1029 (AgentX header) 1030 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1031 | h.version (1) | h.type (3) | h.flags | | 1032 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1033 | h.sessionID | 1034 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1035 | h.transactionID | 1036 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1037 | h.packetID | 1038 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1039 | h.payload_length | 1040 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1042 (r.context) (OPTIONAL) 1043 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1044 | Octet String Length (L) | 1045 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1046 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1047 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1048 ... 1049 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1050 | Octet L - 1 | Octet L | Padding (as required) | 1051 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1053 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1054 | r.timeout | r.priority | r.range_subid | | 1055 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1057 (r.region) 1058 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1059 | n_subid | prefix | 0 | | 1060 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1061 | sub-identifier #1 | 1062 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1063 ... 1064 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1065 | sub-identifier #n_subid | 1066 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1068 (r.upper_bound) 1069 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1070 | optional upper-bound sub-identifier | 1071 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1073 An agentx-Register-PDU contains the following fields: 1075 r.context 1077 An optional non-default context. 1079 r.timeout 1081 The length of time, in seconds, that a master agent should 1082 allow to elapse after dispatching a message to a subagent 1083 before it regards the subagent as not responding. r.timeout 1084 applies only to messages that concern MIB objects within 1085 r.region. It overrides both the subagent-wide value (if any) 1086 indicated when the AgentX session with the master agent was 1087 established, and the master agent's default timeout. The 1088 default value for r.timeout is 0 (no override). 1090 r.priority 1092 A value between 1 and 255, used to achieve a desired 1093 configuration when different subagents register identical or 1094 overlapping regions. Subagents with no particular knowledge 1095 of priority should register with the default value of 255 1096 (lowest priority). 1098 In the master agent's dispatching algorithm, smaller 1099 values of r.priority take precedence over larger values, 1100 as described in section 7.1.5.1. 1102 r.region 1104 An Object Identifier that, in conjunction with r.range_subid, 1105 indicates a region of the MIB that a subagent wishes to 1106 support. It may be a fully-qualified instance name, a partial 1107 instance name, a MIB table, or ranges of any of these. 1109 The choice of what to register is implementation-specific; 1110 this memo does not specify permissible values. Standard 1111 practice however is for a subagent to register at the 1112 highest level of the naming tree that makes sense. 1113 Registration of fully-qualified instances is typically done 1114 only when a subagent can perform management operations only 1115 on particular rows of a conceptual table. 1117 If r.region is in fact a fully qualified instance name, the 1118 INSTANCE_REGISTRATION bit in h.flags must be set, otherwise it 1119 must be cleared. The master agent may save this information 1120 to optimize subsequent operational dispatching. 1122 r.range_subid 1124 Permits specifying a range in place of one of r.region's 1125 sub-identifiers. If this value is 0, no range is specified. 1126 Otherwise the "r.range_subid"-th sub-identifier in 1127 r.region is a range lower bound, and the range upper 1128 bound sub-identifier (r.upper_bound) immediately follows 1129 r.region. 1131 This permits registering a conceptual row with a single 1132 PDU. For example, the following PDU would register row 1133 7 of the RFC 1573 ifTable (1.3.6.1.2.1.2.2.1.1-22.7): 1135 (AgentX header) 1136 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1137 | h.version (1) | h.type (3) | h.flags | | 1138 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1139 | h.sessionID | 1140 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1141 | h.transactionID | 1142 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1143 | h.packetID | 1144 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1145 | h.payload_length | 1146 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1148 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1149 | r.timeout | r.priority | 5 | | 1150 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1152 (r.region) 1153 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1154 | 6 | 2 | 0 | | 1155 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1156 | 1 | 1157 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1158 | 2 | 1159 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1160 | 2 | 1161 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1162 | 1 | 1163 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1164 | 1 | 1165 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1166 | 7 | 1167 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1169 (r.upper_bound) 1170 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1171 | 22 | 1172 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1174 6.2.4. The agentx-Unregister-PDU 1176 The agentx-Unregister-PDU is sent by a subagent to remove a 1177 previously registered MIB region from the master agent's OID space. 1179 (AgentX header) 1180 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1181 | h.version (1) | h.type (4) | h.flags | | 1182 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1183 | h.sessionID | 1184 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1185 | h.transactionID | 1186 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1187 | h.packetID | 1188 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1189 | h.payload_length | 1190 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1192 (u.context) OPTIONAL 1193 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1194 | Octet String Length (L) | 1195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1196 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1197 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1198 ... 1199 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1200 | Octet L - 1 | Octet L | Padding (as required) | 1201 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1203 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1204 | | u.range_subid | | 1205 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1207 (u.region) 1208 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1209 | n_subid | prefix | 0 | | 1210 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1211 | sub-identifier #1 | 1212 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1213 ... 1214 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1215 | sub-identifier #n_subid | 1216 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1218 (u.upper_bound) 1219 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1220 | optional upper-bound sub-identifier | 1221 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1222 An agentx-Unregister-PDU contains the following fields: 1224 u.context 1226 An optional non-default context. 1228 u.region 1230 Indicates a previously-registered region of the MIB that a 1231 subagent no longer wishes to support. It may be a 1232 fully-qualified instance name, a partial instance name, a MIB 1233 table or group, or ranges of any of these. 1235 6.2.5. The agentx-Get-PDU 1237 (AgentX header) 1238 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1239 | h.version (1) | h.type (5) | h.flags | | 1240 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1241 | h.sessionID | 1242 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1243 | h.transactionID | 1244 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1245 | h.packetID | 1246 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1247 | h.payload_length | 1248 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1250 (g.context) OPTIONAL 1251 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1252 | Octet String Length (L) | 1253 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1254 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1255 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1256 ... 1257 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1258 | Octet L - 1 | Octet L | Padding (as required) | 1259 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1261 (g.sr) 1263 (start 1) 1264 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1265 | n_subid | prefix | include | | 1266 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1267 | sub-identifier #1 | 1268 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1269 ... 1270 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1271 | sub-identifier #n_subid | 1272 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1274 (end 1) 1275 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1276 | 0 | 0 | 0 | 0 | 1277 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1278 ... 1279 (start n) 1280 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1281 | n_subid | prefix | include | | 1282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1283 | sub-identifier #1 | 1284 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1285 ... 1287 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1288 | sub-identifier #n_subid | 1289 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1291 (end n) 1292 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1293 | 0 | 0 | 0 | 0 | 1294 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1296 An agentx-Get-PDU contains the following fields: 1298 g.context 1300 An optional non-default context. 1302 g.sr 1304 A SearchRangeList containing the requested variables for this 1305 subagent. 1307 6.2.6. The agentx-GetNext-PDU 1309 (AgentX header) 1310 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1311 | h.version (1) | h.type (6) | h.flags | | 1312 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1313 | h.sessionID | 1314 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1315 | h.transactionID | 1316 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1317 | h.packetID | 1318 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1319 | h.payload_length | 1320 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1322 (g.context) OPTIONAL 1323 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1324 | Octet String Length (L) | 1325 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1326 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1327 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1328 ... 1329 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1330 | Octet L - 1 | Octet L | Padding (as required) | 1331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1333 (g.sr) 1334 ... 1336 6.2.7. The agentx-GetBulk-PDU 1338 (AgentX header) 1339 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1340 | h.version (1) | h.type (7) | h.flags | | 1341 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1342 | h.sessionID | 1343 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1344 | h.transactionID | 1345 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1346 | h.packetID | 1347 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1348 | h.payload_length | 1349 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1351 (g.context) OPTIONAL 1352 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1353 | Octet String Length (L) | 1354 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1355 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1356 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1357 ... 1358 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1359 | Octet L - 1 | Octet L | Padding (as required) | 1360 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1362 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1363 | g.non_repeaters | g.max_repetitions | 1364 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1366 (g.sr) 1367 ... 1369 6.2.8. The agentx-TestSet-PDU 1371 (AgentX header) 1372 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1373 | h.version (1) | h.type (8) | h.flags | | 1374 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1375 | h.sessionID | 1376 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1377 | h.transactionID | 1378 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1379 | h.packetID | 1380 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1381 | h.payload_length | 1382 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1384 (t.context) OPTIONAL 1385 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1386 | Octet String Length (L) | 1387 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1388 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1389 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1390 ... 1391 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1392 | Octet L - 1 | Octet L | Padding (as required) | 1393 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1395 (t.vb) 1397 (VarBind 1) 1398 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1399 | v.type | | 1400 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1401 | n_subid | prefix | 0 | | 1402 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1403 | sub-identifier #1 | 1404 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1405 ... 1406 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1407 | sub-identifier #n_subid | 1408 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1409 | data | 1410 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1411 ... 1412 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1413 | data | 1414 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1415 ... 1417 (VarBind n) 1418 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1419 | v.type | | 1420 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1421 | n_subid | prefix | 0 | | 1422 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1423 | sub-identifier #1 | 1424 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1425 ... 1426 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1427 | sub-identifier #n_subid | 1428 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1429 | data | 1430 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1431 ... 1432 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1433 | data | 1434 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1436 An agentx-TestSet-PDU contains the following fields: 1438 t.context 1440 An optional non-default context. 1442 t.vb 1444 A VarBindList containing the requested VarBinds for 1445 this subagent. 1447 6.2.9. The agentx-CommitSet, -UndoSet, -CleanupSet PDUs 1449 These PDUs consist of the AgentX header only. 1451 The agentx-CommitSet-, -UndoSet-, and -Cleanup-PDUs are 1452 used in processing an SNMP SetRequest operation. 1454 6.2.10. The agentx-Notify-PDU 1456 An agentx-Notify-PDU is sent by a subagent to cause the master agent 1457 to forward a notification. 1459 (AgentX header) 1460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1461 | h.version (1) | h.type (12) | h.flags | | 1462 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1463 | h.sessionID | 1464 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1465 | h.transactionID | 1466 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1467 | h.packetID | 1468 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1469 | h.payload_length | 1470 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1472 (n.context) OPTIONAL 1473 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1474 | Octet String Length (L) | 1475 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1476 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1478 ... 1479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1480 | Octet L - 1 | Octet L | Padding (as required) | 1481 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1483 (n.vb) 1484 ... 1486 An agentx-Notify-PDU contains the following fields: 1488 n.context 1490 An optional non-default context. 1492 n.vb 1494 A VarBindList whose contents define the actual PDU to be 1495 sent. This memo places the following restrictions on its 1496 contents: 1498 - If the subagent supplies sysUpTime.0, it must be 1499 present as the first varbind. 1501 - snmpTrapOID.0 must be present, as the second 1502 varbind if sysUpTime.0 was supplied, as the 1503 first if it was not. 1505 6.2.11 The agentx-Ping-PDU 1507 The agentx-Ping-PDU is sent by a subagent to the master agent to 1508 monitor the master agent's ability to receive and send AgentX 1509 PDUs over their AgentX session. 1511 (AgentX header) 1512 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1513 | h.version (1) | h.type (13) | h.flags | | 1514 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1515 | h.sessionID | 1516 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1517 | h.transactionID | 1518 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1519 | h.packetID | 1520 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1521 | h.payload_length | 1522 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1524 (p.context) OPTIONAL 1525 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1526 | Octet String Length (L) | 1527 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1528 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1529 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1530 ... 1531 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1532 | Octet L - 1 | Octet L | Padding (as required) | 1533 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1535 An agentx-Ping-PDU may contain the following field: 1537 p.context 1539 An optional non-default context. 1541 Using p.context a subagent can retrieve the sysUpTime value 1542 for a specific context, if required. 1544 6.2.12. The agentx-IndexAllocate-PDU 1546 An agentx-IndexAllocate-PDU is sent by a subagent to request 1547 allocation of a value for specific index objects. Refer to section 1548 7.1.3 (Using the agentx-IndexAllocate-PDU) for suggested usage. 1550 (AgentX header) 1551 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1552 | h.version (1) | h.type (14) | h.flags | | 1553 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1554 | h.sessionID | 1555 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1556 | h.transactionID | 1557 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1558 | h.packetID | 1559 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1560 | h.payload_length | 1561 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1563 (i.context) OPTIONAL 1564 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1565 | Octet String Length (L) | 1566 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1567 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1568 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1569 ... 1570 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1571 | Octet L - 1 | Octet L | Padding (as required) | 1572 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1574 (i.vb) 1575 ... 1577 An agentx-IndexAllocate-PDU contains the following fields: 1579 i.context 1581 An optional non-default context. 1583 i.vb 1585 A VarBindList containing the index names and values requested 1586 for allocation. 1588 6.2.13. The agentx-IndexDeallocate-PDU 1590 An agentx-IndexDeallocate-PDU is sent by a subagent to release 1591 previously allocated index values. 1593 (AgentX header) 1594 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1595 | h.version (1) | h.type (15) | h.flags | | 1596 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1597 | h.sessionID | 1598 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1599 | h.transactionID | 1600 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1601 | h.packetID | 1602 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1603 | h.payload_length | 1604 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1606 (i.context) OPTIONAL 1607 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1608 | Octet String Length (L) | 1609 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1610 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1611 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1612 ... 1613 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1614 | Octet L - 1 | Octet L | Padding (as required) | 1615 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1617 (i.vb) 1618 ... 1620 An agentx-IndexDeallocate-PDU contains the following fields: 1622 i.context 1624 An optional non-default context. 1626 i.vb 1628 A VarBindList containing the index names and values to be 1629 released. 1631 6.2.14. The agentx-AddAgentCaps-PDU 1633 An agentx-AddAgentCaps-PDU is generated by a subagent to inform the 1634 master agent of its agent capabilities. 1636 (AgentX header) 1637 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1638 | h.version (1) | h.type (16) | h.flags | | 1639 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1640 | h.sessionID | 1641 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1642 | h.transactionID | 1643 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1644 | h.packetID | 1645 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1646 | h.payload_length | 1647 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1649 (a.context) (OPTIONAL) 1650 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1651 | Octet String Length (L) | 1652 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1653 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1654 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1655 ... 1656 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1657 | Octet L - 1 | Octet L | Optional Padding | 1658 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1660 (a.id) 1661 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1662 | n_subid | prefix | 0 | | 1663 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1664 | sub-identifier #1 | 1665 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1666 ... 1667 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1668 | sub-identifier #n_subid | 1669 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1671 (a.descr) 1672 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1673 | Octet String Length (L) | 1674 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1675 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1676 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1677 ... 1678 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1679 | Octet L - 1 | Octet L | Optional Padding | 1680 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1682 An agentx-AddAgentCaps-PDU contains the following fields: 1684 a.context 1686 An optional non-default context. 1688 a.id 1690 An Object Identifier containing the value of an invocation of 1691 the AGENT-CAPABILITIES macro, which the master agent exports 1692 as a value of sysORID for the indicated context. (Recall that 1693 the value of an invocation of an AGENT-CAPABILITIES macro is 1694 an object identifier that describes a precise level of support 1695 with respect to implemented MIB modules. A more complete 1696 discussion of the AGENT-CAPABILITIES macro and related sysORID 1697 values can be found in section 6 of RFC 1904 [10].) 1699 a.descr 1701 An Octet String containing a DisplayString to be used as the 1702 value of sysORDescr corresponding to the sysORID value above. 1704 6.2.15. The agentx-RemoveAgentCaps-PDU 1706 An agentx-RemoveAgentCaps-PDU is generated by a subagent to request 1707 that the master agent stop exporting a particular value of sysORID. 1708 This value must have previously been advertised by the subagent in 1709 an agentx-AddAgentCaps-PDU. 1711 (AgentX header) 1712 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1713 | h.version (1) | h.type (17) | h.flags | | 1714 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1715 | h.sessionID | 1716 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1717 | h.transactionID | 1718 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1719 | h.packetID | 1720 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1721 | h.payload_length | 1722 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1724 (a.context) (OPTIONAL) 1725 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1726 | Octet String Length (L) | 1727 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1728 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1729 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1730 ... 1731 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1732 | Octet L - 1 | Octet L | Optional Padding | 1733 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1735 (a.id) 1736 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1737 | n_subid | prefix | 0 | | 1738 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1739 | sub-identifier #1 | 1740 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1741 ... 1742 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1743 | sub-identifier #n_subid | 1744 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1745 An agentx-RemoveAgentCaps-PDU contains the following fields: 1747 a.context 1749 An optional non-default context. 1751 a.id 1753 An ObjectIdentifier containing the value of sysORID that 1754 should no longer be exported. 1756 6.2.16. The agentx-Response-PDU 1758 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1759 | h.version (1) | h.type (18) | h.flags | | 1760 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1761 | h.sessionID | 1762 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1763 | h.transactionID | 1764 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1765 | h.packetID | 1766 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1767 | h.payload_length | 1768 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1770 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1771 | res.sysUpTime | 1772 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1773 | res.error | res.index | 1774 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1775 ... 1777 An agentx-Response-PDU contains the following fields: 1779 h.sessionID 1781 If this is a response to a agentx-Open-PDU, then it 1782 contains the new and unique sessionID (as assigned by 1783 the master agent) for this session. 1785 Otherwise it must be identical to the h.sessionID 1786 value in the PDU to which this PDU is a response. 1788 h.transactionID 1790 Must be identical to the h.transactionID value in the PDU to 1791 which this PDU is a response. 1793 In an agentx response PDU from the master agent to the 1794 subagent, the value of h.transactionID has no significance 1795 and can be ignored by the subagent. 1797 h.packetID 1799 Must be identical to the h.packetID value in the PDU to 1800 which this PDU is a response. 1802 res.sysUpTime 1804 This field contains the current value of sysUpTime for 1805 the indicated context. It is relevant only in agentx 1806 response PDUs sent from the master agent to a subagent in 1807 response to the following agentx PDUs: 1809 agentx-Open-PDU (1), 1810 agentx-Close-PDU (2), 1811 agentx-Register-PDU (3), 1812 agentx-Unregister-PDU (4), 1813 agentx-Ping-PDU (13), 1814 agentx-IndexAllocate-PDU (14), 1815 agentx-IndexDeallocate-PDU (15), 1816 agentx-AddAgentCaps-PDU (16), 1817 agentx-RemoveAgentCaps-PDU (17) 1819 In an agentx response PDU from the subagent to the master 1820 agent, the value of res.sysUpTime has no significance and 1821 is ignored by the master agent. 1823 res.error 1825 Indicates error status (including 'noError'). Values are 1826 limited to those defined for errors in the SNMPv2 SMI (RFC 1827 1905 [4]), and the following AgentX-specific values: 1829 openFailed (256), 1830 notOpen (257), 1831 indexWrongType (258), 1832 indexAlreadyAllocated (259), 1833 indexNoneAvailable (260), 1834 indexNotAllocated (261), 1835 unsupportedContext (262), 1836 duplicateRegistration (263), 1837 unknownRegistration (264), 1838 unknownAgentCaps (265) 1840 res.index 1842 In error cases, this is the index of the failed variable 1843 binding within a received request PDU. 1845 Other data may follow these latter two fields, depending on 1846 which AgentX PDU is being responded to. These data are 1847 specified in the subsequent elements of procedure. 1849 7. Elements of Procedure 1851 This section describes the actions of protocol entities (master 1852 agents and subagents) implementing the AgentX protocol. Note, 1853 however, that it is not intended to constrain the internal 1854 architecture of any conformant implementation. 1856 The actions of AgentX protocol entities can be broadly categorized 1857 under two headings: 1859 (1) processing AgentX administrative messages (e.g., connection 1860 requests from a subagent to a master agent); and 1862 (2) processing SNMP messages (e.g., the coordinated actions of a 1863 master agent and one or more subagents in processing a 1864 received SNMP Get-PDU). 1866 7.1. Processing AgentX Administrative Messages 1868 This subsection describes the actions of AgentX protocol entities 1869 in processing AgentX administrative messages. Such messages 1870 include those involved in establishing and terminating an AgentX 1871 session between a subagent and a master agent, those by which a 1872 subagent requests allocation of instance index values, and those 1873 by which a subagent communicates to a master agent which MIB 1874 regions it supports. 1876 7.1.1. Processing the agentx-Open-PDU 1878 When the master agent receives an agentx-Open-PDU, it processes 1879 it as follows: 1881 1) An agentx-Response-PDU is created and res.sysUpTime is set to 1882 the value of sysUpTime.0 for the indicated context. 1884 2) If the master agent is unable to open an AgentX session for 1885 any reason, it may refuse the session establishment request, 1886 sending in reply the agentx-Response-PDU, with res.error 1887 field set to "openFailed". 1889 3) Otherwise: The master agent assigns a sessionID to the new 1890 session and puts the value in the h.sessionID field of the 1891 agentx-Response-PDU. This value must be unique among all 1892 existing open sessions. 1894 4) The master agent retains session-specific information 1895 from the PDU for this subagent: 1897 - The NETWORK_BYTE_ORDER value in h.flags is retained 1898 for use in all AgentX protocol operations initiated 1899 by the master agent for this session. All subsequent 1900 AgentX PDUs exchanged over this session must have the 1901 NETWORK_BYTE_ORDER bit in h.flags set to this value, 1902 and must encode multibyte integers accordingly. 1904 - The o.timeout value is used in calculating timeout 1905 conditions for this subagent. 1907 - The o.id and o.descr fields are used for informational 1908 purposes. (Such purposes are implementation-specific 1909 for now, and may be used in a possible future standard 1910 AgentX MIB.) 1912 5) The agentx-Response-PDU is sent with the res.error field 1913 set to "noError". 1915 At this point, an AgentX session is considered established between 1916 the master agent and the subagent. An AgentX session is a distinct 1917 channel for the exchange of AgentX protocol messages between a 1918 master agent and one subagent, qualified by the session-specific 1919 attributes listed in 4) above. AgentX session establishment is 1920 initiated by the subagent. An AgentX session can be terminated 1921 by either the master agent or the subagent. 1923 7.1.2. Processing the agentx-IndexAllocate-PDU 1925 When the master agent receives an agentx-IndexAllocate-PDU, it 1926 processes it as follows: 1928 1) An agentx-Response-PDU is created and res.sysUpTime is set to 1929 the value of sysUpTime.0 for the default context. 1931 2) If h.sessionID does not correspond to a currently established 1932 session with this subagent, the agentx-Response-PDU is sent 1933 in reply with res.error set to "notOpen". 1935 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 1936 supports only a default context, the agentx-Response-PDU is 1937 returned with res.error set to "unsupportedContext", and the 1938 requested allocation fails. Otherwise: The value of 1939 res.sysUpTime is set to the value of sysUpTime.0 for the 1940 indicated context. 1942 4) Each VarBind in the VarBindList is processed until either all 1943 are successful, or one fails. If any VarBind fails, the 1944 agentx-Response-PDU is sent in reply containing the original 1945 VarBindList, with res.index set to indicate the failed VarBind, 1946 and with res.error set as described subsequently. All other 1947 VarBinds are ignored; no index values are allocated. 1949 VarBinds are processed as follows: 1951 - v.name is the name of the index for which a value is to be 1952 allocated. 1954 - v.type is the syntax of the index object. 1956 - v.data indicates the specific index value requested. 1957 If the NEW_INDEX or the ANY_INDEX bit is set, the actual 1958 value in v.data is ignored and an appropriate index value 1959 is generated. 1961 a) If there are no currently allocated index values for v.name 1962 in the indicated context, and v.type does not correspond to 1963 a valid index type value, the VarBind fails and res.error 1964 is set to "indexWrongType". 1966 b) If there are currently allocated index values for v.name 1967 in the indicated context, but the syntax of those values 1968 does not match v.type, the VarBind fails and res.error is 1969 set to "indexWrongType". 1971 c) Otherwise, if both the NEW_INDEX and ANY_INDEX bits are 1972 clear, allocation of a specific index value is being 1973 requested. If the requested index is already allocated 1974 for v.name in the indicated context, the VarBind fails 1975 and res.error is set to "indexAlreadyAllocated". 1977 d) Otherwise, if the NEW_INDEX bit is set, the master agent 1978 should generate the next available index value for v.name 1979 in the indicated context, with the constraint that this 1980 value must not have been allocated (even if subsequently 1981 released) to any subagent since the last re-initialization 1982 of the master agent. If no such value can be generated, 1983 the VarBind fails and res.error is set to "indexNoneAvailable". 1985 e) Otherwise, if the ANY_INDEX bit is set, the master agent 1986 should generate an index value for v.name in the 1987 indicated context, with the constraint that this value is 1988 not currently allocated to any subagent. If no such value 1989 can be generated, then the VarBind fails and res.error is 1990 set to "indexNoneAvailable". 1992 5) If all VarBinds are processed successfully, the 1993 agentx-Response-PDU is sent in reply with res.error set to 1994 "noError". A VarBindList is included that is identical to the 1995 one sent in the agentx-IndexAllocate-PDU, except that VarBinds 1996 requesting a NEW_INDEX or ANY_INDEX value are updated with an 1997 appropriate value. 1999 7.1.3. Using the agentx-IndexAllocate-PDU 2001 Index allocation is a service provided by an AgentX master agent. 2002 It provides generic support for sharing MIB conceptual tables among 2003 subagents who are assumed to have no knowledge of each other. 2005 Each subagent sharing a table should first request allocation of 2006 index values, then use those index values to qualify MIB regions in 2007 its subsequent registrations. 2009 The master agent maintains a database of index objects (OIDs), and, 2010 for each index, the values that have been allocated for it. It is 2011 unaware of what MIB variables (if any) the index objects represent. 2013 By convention, subagents use the MIB variable listed in the INDEX 2014 clause as the index object for which values must be allocated. For 2015 tables indexed by multiple variables, values may be allocated for 2016 each index (although this is frequently unnecessary; see example 2 2017 below). The subagent may request allocation of 2019 - a specific index value 2020 - an index value that is not currently allocated 2021 - an index value that has never been allocated 2023 The last two alternatives reflect the uniqueness and constancy 2024 requirements present in many MIB specifications for arbitrary 2025 integer indexes (e.g., ifIndex in the IF MIB (RFC 1573 [11]), 2026 snmpFddiSMTIndex in the FDDI MIB (RFC 1285 [12]), or 2027 sysApplInstallPkgIndex in the Application MIB [13]). The need for 2028 subagents to share tables using such indexes is the main motivation 2029 for index allocation in AgentX. 2031 Example 1: 2033 A subagent implements an interface, and wishes to register a 2034 single row of the RFC 1573 ifTable. It requests an allocation 2035 for the index object "ifIndex", for a value that has never been 2036 allocated (since ifIndex values must be unique). The master agent 2037 returns the value "7". 2039 The subagent now attempts to register row 7 of ifTable, by 2040 specifying a MIB region in the agentx-Register-PDU of 2041 1.3.6.1.2.1.2.2.1.[1-22].7. If the registration succeeds, no 2042 further processing is required. The master agent will dispatch 2043 to this subagent correctly. 2045 But the registration may fail. Index allocation and MIB region 2046 registration are not coupled in the master agent. Some other 2047 subagent may have already registered ifTable row 7 without first 2048 having requested allocation of the index. The current state of 2049 index allocations is not considered when processing registration 2050 requests, and the current registry is not considered when 2051 processing index allocation requests. If subagents follow the 2052 model of "first request allocation of an index, then register the 2053 corresponding region", then a successful index allocation request 2054 gives a subagent a good hint (but no guarantee) of what it should 2055 be able to register. 2057 If the registration failed, the subagent should request allocation 2058 of a new index i, and attempt to register ifTable.[1-22].i, until 2059 successful. 2061 Example 2: 2063 This same subagent wishes to register ipNetToMediaTable rows 2064 corresponding to its interface (ifIndex i). Due to structure of 2065 this table, no further index allocation need be done. The 2066 subagent can register the MIB region ipNetToMediaTable.[1-4].i, 2067 It is claiming responsibility for all rows of the table whose 2068 value of ipNetToMediaIfIndex is i. 2070 Example 3: 2072 A network device consists of a set of processors, each of which 2073 accepts network connections for a unique set of IP addresses. 2074 Further, each processor contains a subagent that implements 2075 tcpConnTable. In order to represent tcpConnTable for the entire 2076 managed device, the subagents need to share tcpConnTable. 2078 In this case, no index allocation need be done at all. Each 2079 subagent can register a MIB region of tcpConnTable.[1-5].a.b.c.d, 2080 where a.b.c.d represents an unique IP address of the individual 2081 processor. 2083 Each subagent is claiming responsibility for the region of 2084 tcpConnTable where the value of tcpConnLocalAddress is a.b.c.d. 2086 7.1.4 Processing the agentx-IndexDeallocate-PDU 2088 When the master agent receives an agentx-IndexDeallocate-PDU, it 2089 processes it as follows: 2091 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2092 the value of sysUpTime.0 for the default context. 2094 2) If h.sessionID does not correspond to a currently 2095 established session with this subagent, the 2096 agentx-Response-PDU is sent in reply with res.error set 2097 to "notOpen". 2099 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2100 supports only a default context, the agentx-Response-PDU is 2101 returned with res.error set to "unsupportedContext", and the 2102 requested allocation fails. Otherwise: The value of 2103 res.sysUpTime is set to the value of sysUpTime.0 for the 2104 indicated context. 2106 4) Each VarBind in the VarBindList is processed until either all 2107 are successful, or one fails. If any VarBind fails, the 2108 agentx-Response-PDU is sent in reply, containing the original 2109 VarBindList, with res.index set to indicate the failed VarBind, 2110 and with res.error set as described subsequently. All other 2111 VarBinds are ignored; no index values are released. 2113 VarBinds are processed as follows: 2115 - v.name is the name of the index for which a value is to be 2116 released 2118 - v.type is the syntax of the index object 2120 - v.data indicates the specific index value to be released. 2121 The NEW_INDEX and ANY_INDEX bits are ignored and should 2122 be cleared. 2124 a) If the index value for the named index is not currently 2125 allocated to this subagent, the VarBind fails and res.error 2126 is set to "indexNotAllocated". 2128 5) If all VarBinds are processed successfully, res.error is 2129 set to "noError" and the agentx-Response-PDU is sent. 2130 A VarBindList is included which is identical to the one 2131 sent in the agentx-IndexDeallocate-PDU. 2133 All released index values are now available, and may be 2134 used in response to subsequent allocation requests for 2135 ANY_INDEX values for the particular index. 2137 7.1.5. Processing the agentx-Register-PDU 2139 When the master agent receives an agentx-Register-PDU, it processes 2140 it as follows: 2142 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2143 the value of sysUpTime.0 for the default context. 2145 2) If h.sessionID does not correspond to a currently 2146 established session with this subagent, the 2147 agentx-Response-PDU is sent in reply with res.error set 2148 to "notOpen". 2150 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2151 supports only a default context, the agentx-Response-PDU is 2152 returned with res.error set to "unsupportedContext", and the 2153 requested allocation fails. Otherwise: The value of 2154 res.sysUpTime is set to the value of sysUpTime.0 for the 2155 indicated context. 2157 Note: Non-default contexts might be added on the fly by 2158 the master agent, or the master agent might require 2159 such non-default contexts to be pre-configured. 2160 The choice is implementation-specific. 2162 4) Characterize the request. 2164 If r.region (or any of its set of Object Identifiers, if r.range 2165 is non-zero) is exactly the same as any currently registered 2166 value of r.region (or any of its set of Object Identifiers), 2167 this registration is termed a duplicate region. 2169 If r.region (or any of its set of Object Identifiers, if r.range 2170 is non-zero) is a subtree of, or contains, any currently 2171 registered value of r.region (or any of its set of 2172 Object Identifiers), this registration is termed an overlapping 2173 region. 2175 If the NON_DEFAULT_CONTEXT bit is set, this region is to be 2176 logically registered within the context indicated by r.context. 2177 Otherwise this region is to be logically registered within the 2178 default context. 2180 A registration that would result in a duplicate region with the 2181 same priority and within the same context as that of a current 2182 registration is termed a duplicate registration. 2184 5) Otherwise, if this is a duplicate registration, the 2185 agentx-Response-PDU is returned with res.error set to 2186 "duplicateRegistration", and the requested registration fails. 2188 6) Otherwise, the agentx-Response-PDU is returned with res.error 2189 set to "noError". 2191 The master agent adds this region to its registered OID space for 2192 the indicated context, to be considered during the dispatching 2193 phase for subsequently received SNMP protocol messages. 2195 Note: The following algorithm describes maintaining a set of 2196 OID ranges derived from "splitting" registered regions. The 2197 algorithm for operational dispatching is also stated in terms of 2198 these OID ranges. 2200 These OID ranges are a useful explanatory device, but are not 2201 required for a correct implementation. 2203 - If r.region (R1) is a subtree of a currently registered 2204 region (R2), split R2 into 3 new regions (R2a, R2b, and R2c) 2205 such that R2b is an exact duplicate of R1. Now remove R2 and 2206 add R1, R2a, R2b, and R2c to the master agent's 2207 lexicographically ordered set of ranges (the registered OID 2208 space). Note: Though newly-added ranges R1 and R2b are 2209 identical in terms of the MIB objects they contain, they are 2210 registered by different subagents, possibly at different 2211 priorities. 2213 For instance, if subagent S2 registered "ip" (R2 is 2214 1.3.6.1.2.1.4) and subagent S1 subsequently registered 2215 "ipNetToMediaTable" (R1 is 1.3.6.1.2.1.4.22), the resulting 2216 set of registered regions would be: 2218 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2) 2219 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2) 2220 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2221 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2) 2223 - If r.region (R1) overlaps one or more currently registered 2224 regions, then for each overlapped region (R2) split R1 into 3 2225 new ranges (R1a, R1b, R1c) such that R1b is an exact 2226 duplicate of R2. Add R1b and R2 into the lexicographically 2227 ordered set of regions. Apply (5) above iteratively to R1a and 2228 R1c (since they may overlap, or be subtrees of, other regions). 2230 For instance, given the currently registered regions in the 2231 example above, if subagent S3 now registers mib-2 (R1 is 2232 1.3.6.1.2.1) the resulting set of regions would be: 2234 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3) 2235 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2) 2236 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3) 2237 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2) 2238 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2239 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 2240 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2) 2241 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3) 2242 1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3) 2244 Note that at registration time a region may be split into multiple 2245 OID ranges due to pre-existing registrations, or as a result of any 2246 subsequent registration. This region splitting is transparent to 2247 subagents. Hence the master agent must always be able to associate 2248 any OID range with the information contained in its original 2249 agentx-Register-PDU. 2251 7.1.5.1. Handling Duplicate OID Ranges 2253 As a result of this registration algorithm there are likely to be 2254 duplicate OID ranges (regions of identical MIB objects registered to 2255 different subagents) in the master agent's registered OID space. 2256 Whenever the master agent's dispatching algorithm (see 7.2.1, 2257 Dispatching AgentX PDUs) selects a duplicate OID range, the 2258 determination of which one to use proceeds as follows: 2260 1) Choose the one whose original agentx-Register-PDU 2261 r.region contained the most subids, i.e., the most specific 2262 r.region. Note: The presence or absence of a range subid 2263 has no bearing on how "specific" one object identifier is 2264 compared to another. 2266 2) If still ambiguous, there were duplicate regions. Choose the 2267 one whose original agentx-Register-PDU specified the smaller 2268 value of r.priority. 2270 7.1.6. Processing the agentx-Unregister-PDU 2272 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2273 the value of sysUpTime.0 for the default context. 2275 2) If h.sessionID does not correspond to a currently 2276 established session with this subagent, the 2277 agentx-Response-PDU is sent in reply with res.error set 2278 to "notOpen". 2280 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2281 supports only a default context, the agentx-Response-PDU is 2282 returned with res.error set to "unsupportedContext", and the 2283 requested allocation fails. Otherwise: The value of 2284 res.sysUpTime is set to the value of sysUpTime.0 for the 2285 indicated context. 2287 4) If u.region and the indicated context do not match an existing 2288 registration made during this session, the agentx-Response-PDU 2289 is returned with res.error set to "unknownRegistration". 2291 5) Otherwise, the agentx-Response-PDU is sent in reply with res.error 2292 set to "noError", and the previous registration is removed: 2294 - The master agent removes u.region from its registered OID space 2295 within the indicated context. If the original region had been 2296 split, all such related regions are removed. 2298 For instance, given the example registry above, if subagent S2 2299 unregisters "ip", the resulting registry would be: 2301 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3) 2302 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3) 2303 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2304 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 2305 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3) 2306 1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3) 2308 7.1.7. Processing the agentx-AddAgentCaps-PDU 2310 When the master agent receives an agentx-AddAgentCaps-PDU, 2311 it processes it as follows: 2313 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2314 the value of sysUpTime.0 for the default context. 2316 2) If h.sessionID does not correspond to a currently 2317 established session with this subagent, the 2318 agentx-Response-PDU is sent in reply with res.error set 2319 to "notOpen". 2321 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2322 supports only a default context, the agentx-Response-PDU is 2323 returned with res.error set to "unsupportedContext", and the 2324 requested allocation fails. Otherwise: The value of 2325 res.sysUpTime is set to the value of sysUpTime.0 for the 2326 indicated context. 2328 4) Otherwise, the master agent adds the subagent's capabilities 2329 information to the sysORTable for the indicated context. An 2330 agentx-Response-PDU is sent in reply with res.error set to 2331 "noError". 2333 7.1.8. Processing the agentx-RemoveAgentCaps-PDU 2335 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2336 the value of sysUpTime.0 for the default context. 2338 2) If h.sessionID does not correspond to a currently 2339 established session with this subagent, the 2340 agentx-Response-PDU is sent in reply with res.error set 2341 to "notOpen". 2343 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2344 supports only a default context, the agentx-Response-PDU is 2345 returned with res.error set to "unsupportedContext", and the 2346 requested allocation fails. Otherwise: The value of 2347 res.sysUpTime is set to the value of sysUpTime.0 for the 2348 indicated context. 2350 4) If the combination of a.id and the optional a.context does not 2351 represent a sysORTable entry that was added by this subagent, 2352 during this session, the agentx-Response-PDU is returned with 2353 res.error set to "unknownAgentCaps". 2355 5) Otherwise the master agent deletes the corresponding sysORTable 2356 entry and sends in reply the agentx-Response-PDU, with res.error 2357 set to "noError". 2359 7.1.9. Processing the agentx-Close-PDU 2361 When the master agent receives an agentx-Close-PDU, it processes it 2362 as follows: 2364 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2365 the value of sysUpTime.0 for the default context. 2367 2) If h.sessionID does not correspond to a currently 2368 established session with this subagent, the 2369 agentx-Response-PDU is sent in reply with res.error set 2370 to "notOpen". 2372 3) Otherwise, the master agent closes the AgentX session 2373 as described below. No agentx-Response-PDU is sent. 2375 - All MIB regions that have been registered during this session 2376 are unregistered, as described in 7.1.6. 2378 - All index values allocated during this session are freed, as 2379 described in section 7.1.4. 2381 - All sysORID values that were registered during this session 2382 are removed, as described in section 7.1.8. 2384 The master agent does not maintain state for closed sessions. 2385 If a subagent wishes to re-establish a session after receiving 2386 an agentx-Close-PDU, it needs to re-register MIB regions, agent 2387 capabilities, etc. 2389 7.1.10. Detecting Connection Loss 2391 If a master agent is able to detect (from the underlying transport) 2392 that a subagent cannot receive AgentX PDUs, it should close all 2393 affected AgentX sessions as described in 7.1.9, step 3). 2395 7.1.11. Processing the agentx-Notify-PDU 2397 A subagent sending SNMPv1 trap information must map this into 2398 (minimally) a value of snmpTrapOID.0, as described in 3.1.2 of 2399 RFC 1908 [8]. 2401 The master agent processes the agentx-Notify-PDU as follows: 2403 1) If h.sessionID does not correspond to a currently 2404 established session with this subagent, an 2405 agentx-Response-PDU is sent in reply with res.error set 2406 to "notOpen", and res.sysUpTime set to the value of 2407 sysUpTime.0 for the indicated context. 2409 2) The VarBindList is parsed. If it does not contain a value for 2410 sysUpTime.0, the master agent supplies the current value of 2411 sysUpTime.0 for the indicated context. If the next VarBind 2412 (either the first or second VarBind; see section 6.2.10.1) 2413 is not snmpTrapOID.0, the master agent ceases further processing 2414 of the notification. 2416 3) Notifications are sent according to the implementation-specific 2417 configuration of the master agent. 2419 If SNMPv1 Trap PDUs are generated, the recommended mapping is as 2420 described in RFC 2089 [9]. 2422 Except in the case of a "notOpen" error as described in 2423 (1) above, no agentx-Response-PDU is sent to the subagent 2424 when the master agent finishes processing the notification. 2426 7.1.12. Processing the agentx-Ping-PDU 2428 When the master agent receives an agentx-Ping-PDU, it processes it 2429 as follows: 2431 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2432 the value of sysUpTime.0 for the default context. 2434 2) If h.sessionID does not correspond to a currently 2435 established session with this subagent, the 2436 agentx-Response-PDU is sent in reply with res.error set 2437 to "notOpen". 2439 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2440 supports only a default context, the agentx-Response-PDU is 2441 returned with res.error set to "unsupportedContext", and the 2442 requested allocation fails. Otherwise: The value of 2443 res.sysUpTime is set to the value of sysUpTime.0 for the 2444 indicated context. 2446 4) The agentx-Response-PDU is sent, with res.error set to 2447 "noError". 2449 If a subagent does not receive a response to its pings, or if it 2450 is able to detect (from the underlying transport) that the 2451 master agent is not able to receive AgentX messages, then it 2452 eventually must initiate a new AgentX session, re-register its 2453 regions, etc. 2455 7.2. Processing Received SNMP Protocol Messages 2457 When an SNMP GetRequest, GetNextRequest, GetBulkRequest, or 2458 SetRequest protocol message is received by the master agent, the 2459 master agent applies its access control policy. 2461 In particular, for SNMPv1 or SNMPv2c PDUs, the master agent 2462 applies the Elements of Procedure defined in section 4.1 of RFC 2463 1157 [6] that apply to receiving entities. (For other versions 2464 of SNMP, the master agent applies the access control policy 2465 defined in the Elements of Procedure for those versions.) 2467 In the SNMPv1 or v2c frameworks, the master agent uses the community 2468 string as an index into a local repository of configuration 2469 information that may include community profiles or more complex 2470 context information. 2472 If application of the access control policy results in a valid SNMP 2473 request PDU, then an SNMP Response-PDU is constructed from 2474 information gathered in the exchange of AgentX PDUs between the 2475 master agent and one or more subagents. Upon receipt and initial 2476 validation of an SNMP request PDU, a master agent uses the 2477 procedures described below to dispatch AgentX PDUs to the proper 2478 subagents, marshal the subagent responses, and construct an SNMP 2479 response PDU. 2481 7.2.1. Dispatching AgentX PDUs 2483 Upon receipt and initial validation of an SNMP request PDU, a master 2484 agent uses the procedures described below to dispatch AgentX PDUs to 2485 the proper subagents. 2487 Note: In the following procedures, an object identifier is said to 2488 be "contained" within an OID range when both of the following 2489 are true: 2491 - The object identifier does not lexicographically precede 2492 the range. 2494 - The object identifier lexicographically precedes the end 2495 of the range. 2497 General Rules of Procedure 2499 While processing a particular SNMP request, the master agent may 2500 send one or more AgentX PDUs to one or more subagents. The 2501 following rules of procedure apply in general to the AgentX master 2502 agent. PDU-specific rules are listed in the applicable sections. 2504 1) Honoring the registry 2506 Because AgentX supports overlapping registrations, it is 2507 possible for the master agent to obtain a value for a requested 2508 varbind from within multiple registered MIB regions. 2510 The master agent must ensure that the value (or exception) 2511 actually returned in the SNMP response PDU is taken from the 2512 authoritative region (as defined in section 7.1.5.1). 2514 2) GetNext and GetBulk Processing 2516 The master agent may choose to send agentx-Get-PDUs while 2517 servicing an SNMP GetNextRequest-PDU. The master agent may 2518 choose to send agentx-Get-PDUs or agentx-GetNext-PDUs while 2519 servicing an SNMP GetBulkRequest-PDU. One possible reason for 2520 this would be if the current iteration has targeted 2521 instance-level registrations. 2523 The master agent may or may not choose to "scope" the possible 2524 instances returned by a subagent through the use of the ending 2525 OID in the SearchRange. A typical usage of this field would be 2526 to encode the ending OID with the registered MIB region that is 2527 the first lexicographical successor to the target OID range, 2528 and that was not registered by the target subagent. 2529 Regardless of this choice, rule (1) must be obeyed. 2531 The master agent may require multiple request-response 2532 iterations on the same subagent session, to determine the 2533 final value of all requested variables. 2535 All AgentX PDUs sent on the session while processing a given 2536 SNMP request must contain identical values of transactionID. 2537 Each different SNMP request processed by the master agent must 2538 present a unique value of transactionID (within the limits of 2539 the 32-bit field) to the session. 2541 3) Number and order of variables sent per AgentX PDU 2543 For Get/GetNext/GetBulk operations, at any stage of the 2544 possibly iterative process, the master agent may need to 2545 dispatch several SearchRanges to a particular subagent 2546 session. The master agent may send one, some, or all 2547 of the SearchRanges in a single AgentX PDU. 2549 The master agent must ensure that the correct contents 2550 and ordering of the VarBindList in the SNMP Response-PDU 2551 are maintained. 2553 The following rules govern the number of VarBinds in a 2554 given AgentX PDU: 2556 a) The subagent must support processing of AgentX PDUs 2557 with multiple VarBinds. 2559 b) When processing an SNMP Set request, the master agent 2560 must send all of the VarBinds applicable to a particular 2561 subagent session in a single Test/Set transaction. 2563 c) When processing an SNMP Get, GetNext, or GetBulk request, 2564 the master agent may send a single AgentX PDU to the 2565 subagent with all applicable VarBinds, or multiple 2566 PDUs with single VarBinds, or something in between 2567 those extremes. The determination of which method to 2568 use in a particular case is implementation-specific. 2570 4) Timeout Values 2572 The master agent chooses a timeout value for each MIB region 2573 being queried, which is 2575 a) the value specified during registration of the MIB region, 2576 if it was non-zero 2578 b) otherwise, the value specified during establishment of 2579 the session in which this region was subsequently 2580 registered, if that value was non-zero. 2582 c) otherwise, the master agent's default value 2584 When an AgentX PDU that references multiple MIB regions is 2585 dispatched, the timeout value used for the PDU is the maximum 2586 value of the timeouts so determined for each of the referenced 2587 MIB regions. 2589 5) Context 2591 If the master agent has determined that a specific non-default 2592 context is associated with the request PDU, that context is 2593 encoded into the AgentX PDU's context field and the 2594 NON_DEFAULT_CONTEXT bit is set in h.flags. 2596 Otherwise, no context Octet String is added to the PDU, and the 2597 NON_DEFAULT_CONTEXT bit is cleared. 2599 7.2.1.1. agentx-Get-PDU 2601 Each variable binding in the SNMP request PDU is processed as 2602 follows: 2604 (1) Identify the target OID range. 2606 Within a lexicographically ordered set of OID ranges, valid for 2607 the indicated context, locate the region that contains the 2608 binding's name. 2610 (2) If no such OID range exists the variable binding is not 2611 processed further, and its value is set to "noSuchObject". 2613 (3) Identify the subagent session in which this region was 2614 registered, termed the target session. 2616 (4) If this is the first variable binding to be dispatched over 2617 the target session in a request-response exchange entailed 2618 in the processing of this management request: 2620 - Create an agentx-Get-PDU for this session, with the header 2621 fields initialized as described above (see 6.1 AgentX PDU 2622 Header). 2624 (5) Add a SearchRange to the end of the target session's PDU 2625 for this variable binding. 2627 - The variable binding's name is encoded into the starting OID. 2629 - The ending OID is encoded as null. 2631 7.2.1.2. agentx-GetNext-PDU 2633 Each variable binding in the SNMP request PDU is processed as 2634 follows: 2636 (1) Identify the target OID range. 2638 Within a lexicographically ordered set of OID ranges, valid for 2639 the indicated context, locate 2641 a) the OID range that contains the variable binding's name and 2642 is not a fully qualified instance, or 2644 b) the OID range that is the first lexicographical successor to 2645 the variable binding's name. 2647 (2) If no such OID range exists the variable binding is not processed 2648 further, and its value is set to "endOfMibView". 2650 (3) Identify the subagent session in which this region was 2651 registered, termed the target session. 2653 (4) If this is the first variable binding to be dispatched over the 2654 target session in a request-response exchange entailed in the 2655 processing of this management request: 2657 - Create an agentx-GetNext-PDU for the session, with 2658 the header fields initialized as described above (see 6.1 2659 AgentX PDU Header). 2661 (5) Add a SearchRange to the end of the target session's 2662 agentx-GetNext-PDU for this variable binding. 2664 - if (1a) applies, the variable binding's name is encoded 2665 into the starting OID, and the OID's "include" field 2666 is set to 0. 2668 - if (1b) applies, the target OID is encoded into the starting 2669 OID, and its "include" field is set to 1. 2671 7.2.1.3. agentx-GetBulk-PDU 2673 (Note: The outline of the following procedure is based closely on 2674 section 4.2.3, "The GetBulkRequest-PDU" of RFC 1905 [4]. Please 2675 refer to it for details on the format of the SNMP GetBulkRequest-PDU 2676 itself.) 2678 Each variable binding in the request PDU is processed as follows: 2680 (1) Identify the target OID range and target session, exactly as 2681 described for the agentx-GetNext-PDU (see 7.2.1.2). 2683 (2) If this is the first variable binding to be dispatched over the 2684 target session in a request-response exchange entailed in the 2685 processing of this management request: 2687 - Create an agentx-GetBulk-PDU for the session, with 2688 the header fields initialized as described above (see 6.1 2689 AgentX PDU Header). 2691 (3) Add a SearchRange to the end of the target session's 2692 agentx-GetBulk-PDU for this variable binding, as described 2693 for the agentx-GetNext-PDU. If the variable binding was 2694 a non-repeater in the original request PDU, it must be a 2695 non-repeater in the agentx-GetBulk-PDU. 2697 The value of g.non_repeaters in the agentx-GetBulk-PDU may be 2698 greater than (but not less than) the value in the original 2699 request PDU. 2701 The value of g.max_repetitions in the agentx-GetBulk-PDU may be less 2702 than (but not greater than) the value in the original request PDU. 2704 The master agent may make such alterations due to simple sanity 2705 checking, optimizations for the current iteration based on the 2706 registry, the maximum possible size of a potential Response-PDU, 2707 known constraints of the AgentX transport, or any other 2708 implementation-specific constraint. 2710 7.2.1.4. agentx-TestSet-PDU 2712 AgentX employs the well-known test-commit-undo-cleanup phases 2713 to achieve "as if simultaneous" semantics of the SNMP SetRequest-PDU 2714 within the extensible agent. The initial phase involves 2715 the agentx-TestSet-PDU. 2717 Each variable binding in the request PDU is processed in order, as 2718 follows: 2720 (1) Identify the target OID range. 2722 Within a lexicographically ordered set of OID ranges, valid for 2723 the indicated context, locate the range that contains the 2724 variable binding's name. 2726 (2) If no such OID range exists, the SNMP Response-PDU must 2727 indicate that this variable binding failed with "noAccess". 2728 Processing is complete for this request. 2730 (3) Identify the single subagent responsible for this OID range, 2731 termed the target subagent, and the applicable session, 2732 termed the target session. 2734 (4) If this is the first variable binding to be dispatched over 2735 the target session in a request-response exchange entailed 2736 in the processing of this management request: 2738 - create an agentx-TestSet-PDU for the session, with the 2739 header fields initialized as described above (see 6.1 2740 AgentX PDU Header). 2742 (5) Add a VarBind to the end of the target session's PDU 2743 for this variable binding, as described in section 5.4. 2745 Note that all VarBinds applicable to a given session must be 2746 sent in a single agentx-TestSet-PDU. 2748 7.2.1.5. Dispatch 2750 A timeout value is calculated for each PDU to be sent, which is the 2751 maximum value of the timeouts determined for each of the PDU's 2752 SearchRanges (as described above in 7.2.1 Dispatching AgentX PDUs, 2753 item 4). Each pending PDU is mapped (via its h.sessionID value) to a 2754 particular transport domain/endpoint, as described in section 8 2755 (Transport Mappings). 2757 7.2.2. Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs 2759 A conformant AgentX subagent must support the agentx-Get, -GetNext, 2760 and -GetBulk PDUs, and must support multiple variables being supplied 2761 in each PDU. 2763 When a subagent receives an agentx-Get-, GetNext-, or GetBulk-PDU, it 2764 performs the indicated management operations and returns an 2765 agentx-Response-PDU. 2767 The agentx-Response-PDU header fields are identical to the received 2768 request PDU except that, at the start of processing, the subagent 2769 initializes h.type to Response, res.error to "noError", 2770 res.index to 0, and the VarBindList to null. 2772 Each SearchRange in the request PDU's SearchRangeList is processed as 2773 described below, and a VarBind is added in the corresponding 2774 location of the agentx-Response-PDU's VarbindList. If processing 2775 should fail for any reason not described below, res.error is set to 2776 "genErr", res.index to the index of the failed SearchRange, 2777 the VarBindList is reset to null, and this agentx-Response-PDU is 2778 returned to the master agent. 2780 7.2.2.1. Subagent Processing of the agentx-Get-PDU 2782 Upon the subagent's receipt of an agentx-Get-PDU, each SearchRange 2783 in the request is processed as follows: 2785 (1) The starting OID is copied to v.name. 2787 (2) If the starting OID exactly matches the name of a 2788 variable instantiated by this subagent within the indicated 2789 context and session, v.type and v.data are encoded to represent 2790 the variable's syntax and value, as described in section 5.4, 2791 Value Representation. 2793 (3) Otherwise, if the starting OID does not match the object 2794 identifier prefix of any variable instantiated within the 2795 indicated context and session, the VarBind is set to 2796 "noSuchObject", in the manner described in section 5.4, 2797 Value Representation. 2799 (4) Otherwise, the VarBind is set to "noSuchInstance" 2800 in the manner described in section 5.4, Value Representation. 2802 7.2.2.2. Subagent Processing of the agentx-GetNext-PDU 2804 Upon the subagent's receipt of an agentx-GetNext-PDU, each 2805 SearchRange in the request is processed as follows: 2807 (1) The subagent searches for a variable within the 2808 lexicographically ordered list of variable names for all 2809 variables it instantiates (without regard to registration of 2810 regions) within the indicated context and session, for which 2811 the following are all true: 2813 - if the "include" field of the starting OID is 0, the 2814 variable's name is the closest lexicographical successor to 2815 the starting OID. 2817 - if the "include" field of the starting OID is 1, the 2818 variable's name is either equal to, or the closest 2819 lexicographical successor to, the starting OID. 2821 - If the ending OID is not null, the variable's name 2822 lexicographically precedes the ending OID. 2824 If all of these conditions are met, v.name is set to the 2825 located variable's name. v.type and v.data are encoded to 2826 represent the variable's syntax and value, as described in 2827 section 5.4, Value Representation. 2829 (2) If no such variable exists, v.name is set to the starting OID, 2830 and the VarBind is set to "endOfMibView", in the manner described 2831 in section 5.4, Value Representation. 2833 7.2.2.3. Subagent Processing of the agentx-GetBulk-PDU 2835 A maximum of N + (M * R) VarBinds are returned, where 2837 N equals g.non_repeaters, 2839 M equals g.max_repetitions, and 2841 R is (number of SearchRanges in the GetBulk request) - N. 2843 The first N SearchRanges are processed exactly as for the 2844 agentx-GetNext-PDU. 2846 If M and R are both non-zero, the remaining R SearchRanges are 2847 processed iteratively to produce potentially many VarBinds. For 2848 each iteration i, such that i is greater than zero and less than or 2849 equal to M, and for each repeated SearchRange s, such that s is 2850 greater than zero and less than or equal to R, the 2851 (N+((i-1)*R)+s)-th VarBind is added to the agentx-Response-PDU 2852 as follows: 2854 1) The subagent searches for a variable within the 2855 lexicographically ordered list of variable names for all 2856 variables it instantiates (without regard to registration of 2857 regions) within the indicated context and session, for which 2858 the following are all true: 2860 - The variable's name is the (i)-th lexicographical successor 2861 to the (N+s)-th requested OID. 2863 (Note that if i is 0 and the "include" field is 1, the 2864 variable's name may be equivalent to, or the first 2865 lexicographical successor to, the (N+s)-th requested OID.) 2867 - If the ending OID is not null, the variable's name 2868 lexicographically precedes the ending OID. 2870 If all of these conditions are met, v.name is set to the 2871 located variable's name. v.type and v.data are 2872 encoded to represent the variable's syntax and value, as 2873 described in section 5.4, Value Representation. 2875 2) If no such variable exists, the VarBind is set to 2876 "endOfMibView" as described in section 5.4, Value 2877 Representation. v.name is set to v.name of the 2878 (N+((i-2)*R)+s)-th VarBind unless i is currently 1, in which 2879 case it is set to the value of the starting OID in the (N+s)-th 2880 SearchRange. 2882 Note that further iterative processing should stop if 2884 - For any iteration i, all s values of v.type are 2885 "endOfMibView". 2887 - An AgentX transport constraint or other 2888 implementation-specific constraint is reached. 2890 7.2.3. Subagent Processing of agentx-TestSet, -CommitSet, -UndoSet, 2891 -CleanupSet-PDUs 2893 A conformant AgentX subagent must support the agentx-TestSet, 2894 -CommitSet, -UndoSet, and -CleanupSet PDUs, and must support multiple 2895 variables being supplied in each PDU. 2897 These four PDUs are used to collectively perform the indicated 2898 management operation. An agentx-Response-PDU is sent in reply to 2899 each of the PDUs, to inform the master agent of the state of the 2900 operation. 2902 The agentx-Response-PDU header fields are identical to the received 2903 request PDU except that, at the start of processing, the subagent 2904 initializes h.type to Response, res.error to "noError", and 2905 res.index to 0. 2907 These Response-PDUs do not contain a VarBindList. 2909 7.2.3.1. Subagent Processing of the agentx-TestSet-PDU 2911 Upon the subagent's receipt of an agentx-TestSet-PDU, each VarBind 2912 in the PDU is validated until they are all successful, or until one 2913 fails, as described in section 4.2.5 of RFC 1905 [4]. The subagent 2914 validates variables with respect to the context and session 2915 indicated in the testSet-PDU. 2917 If each VarBind is successful, the subagent has a further 2918 responsibility to ensure the availability of all resources (memory, 2919 write access, etc.) required for successfully carrying out a 2920 subsequent agentx-CommitSet operation. If this cannot be guaranteed, 2921 the subagent should set res.error to resourceUnavailable(13). 2923 As a result of this validation step, an agentx-Response-PDU 2924 is sent in reply whose res.error field is set to one of the 2925 following (SNMPv2 SMI) values: 2927 noError (0), 2928 genErr (5), 2929 noAccess (6), 2930 wrongType (7), 2931 wrongLength (8), 2932 wrongEncoding (9), 2933 wrongValue (10), 2934 noCreation (11), 2935 inconsistentValue (12), 2936 resourceUnavailable (13), 2937 notWritable (17), 2938 inconsistentName (18) 2940 If this value is not noError(0), the res.index field must be 2941 set to the index of the VarBind for which validation failed. 2943 Implementation of rigorous validation code may be one of the 2944 most demanding aspects of subagent development. Implementors 2945 are strongly encouraged to do this right, so as to avoid if at 2946 all possible the extensible agent's having to return "commitFailed" 2947 or "undoFailed" during subsequent processing. 2949 7.2.3.2. Subagent Processing of the agentx-CommitSet-PDU 2951 The agentx-CommitSet-PDU indicates that the subagent should actually 2952 perform (as described in the post-validation sections of 4.2.5 of 2953 RFC 1905 [4]) the management operation indicated by the previous 2954 TestSet-PDU. 2956 After carrying out the management operation, the subagent sends in 2957 reply an agentx-Response-PDU whose res.error field is set to one of 2958 the following (SNMPv2 SMI) values: 2960 noError (0), 2961 commitFailed (14) 2963 If this value is commitFailed(14), the res.index field must be 2964 set to the index of the VarBind for which the operation failed. 2965 Otherwise res.index is set to 0. 2967 7.2.3.3. Subagent Processing of the agentx-UndoSet-PDU 2969 The agentx-UndoSet-PDU indicates that the subagent should undo 2970 the management operation requested in a preceding CommitSet-PDU. 2971 The undo process is as described in section 4.2.5 of RFC 1905 2972 [4]. 2974 After carrying out the undo process, the subagent sends in reply an 2975 agentx-Response-PDU whose res.index field is set to 0, and whose 2976 res.error field is set to one of the following (SNMPv2 SMI) values: 2978 noError (0), 2979 undoFailed (15) 2981 If this value is undoFailed(14), the res.index field must be 2982 set to the index of the VarBind for which the operation failed. 2983 Otherwise res.index is set to 0. 2985 7.2.3.4. Subagent Processing of the agentx-CleanupSet-PDU 2987 The agentx-CleanupSet-PDU signals the end of processing of the 2988 management operation requested in the previous CommitSet-PDU. This 2989 is an indication to the subagent that it may now release any 2990 resources it may have reserved in order to carry out the management 2991 request. 2993 No response is sent by the subagent. 2995 7.2.4. Master Agent Processing of AgentX Responses 2997 The master agent now marshals all subagent AgentX response PDUs and 2998 builds an SNMP response PDU. In the next several subsections, the 2999 initial processing of all subagent AgentX response PDUs is 3000 described, followed by descriptions of subsequent processing 3001 for each specific subagent Response. 3003 7.2.4.1. Common Processing of All AgentX Response PDUs 3005 1) If a subagent does not respond within the timeout interval for 3006 this dispatch, it is treated as if the subagent had returned 3007 "genErr" and processed as described below. 3009 A timeout may be due to a variety of reasons, and does 3010 not necessarily denote a failed or malfunctioning 3011 subagent. As such, the master agent's response to a 3012 subagent timeout is implementation-specific, but with the 3013 following constraint: 3015 A subagent that times out on three consecutive requests 3016 is considered unable to respond, and the master agent 3017 must close the AgentX session as described in 3018 7.1.9, step (2). 3020 2) Otherwise, the h.packetID, h.sessionID, and h.transactionID 3021 fields of the AgentX response PDU are used to correlate subagent 3022 responses. If the response does not pertain to this SNMP 3023 operation, it is ignored. 3025 3) Otherwise, the responses are processed jointly to form the SNMP 3026 response PDU. 3028 7.2.4.2. Processing of Responses to agentx-Get-PDUs 3030 After common processing of the subagent's response to an 3031 agentx-Get-PDU (see 7.2.4.1 above), processing continues with 3032 the following steps: 3034 1) For any received AgentX response PDU, if res.error is not 3035 "noError", the SNMP response PDU's error code is set to this 3036 value, and its error index to the index of the variable binding 3037 corresponding to the failed VarBind in the subagent's 3038 AgentX response PDU. 3040 All other AgentX response PDUs received due to processing this 3041 SNMP request are ignored. Processing is complete; the SNMP 3042 Response PDU is ready to be sent (see section 7.2.5, Sending 3043 the SNMP Response-PDU). 3045 2) Otherwise, the content of each VarBind in the AgentX response PDU 3046 is used to update the corresponding variable binding in the SNMP 3047 Response-PDU. 3049 7.2.4.3. Processing of Responses to agentx-GetNext-PDU and 3050 agentx-GetBulk-PDU 3052 After common processing of the subagent's response to an 3053 agentx-GetNext-PDU or agentx-GetBulk-PDU (see 7.2.4.1 above), 3054 processing continues with the following steps: 3056 1) For any received AgentX response PDU, if res.error is not 3057 "noError", the SNMP response PDU's error code is set to this 3058 value, and its error index to the index of the VarBind 3059 corresponding to the failed VarBind in the subagent's 3060 AgentX response PDU. 3062 All other AgentX response PDUs received due to processing this 3063 SNMP request are ignored. Processing is complete; the SNMP 3064 response PDU is ready to be sent (see section 7.2.5, Sending 3065 the SNMP Response PDU). 3067 2) Otherwise, the content of each VarBind in the AgentX response 3068 PDU is used to update the corresponding VarBind in the SNMP 3069 response PDU. 3071 After all expected AgentX response PDUs have been processed, if 3072 any VarBinds still contain the value "endOfMibView" in their 3073 v.type fields, processing must continue: 3075 3) A new iteration of AgentX request dispatching is initiated 3076 (as described in section 7.2.1.1), in which only those 3077 VarBinds whose v.type is "endOfMibView" are processed. 3079 4) For each such VarBind, a target OID range is identified 3080 which is the lexicographical successor to the target OID 3081 range for this VarBind on the last iteration. The target 3082 subagent is the one that registered the target OID range. 3083 The target session is the one in which the target OID range 3084 was registered. 3086 If an agentx-GetNext- or GetBulk-PDU is being dispatched, 3087 the starting OID in the SearchRanges is set to the target 3088 OID range, and its "include" field is set to 1. 3090 5) The value of transactionID must be identical to the value 3091 used during the previous iteration. 3093 6) The AgentX PDUs are sent to the subagent(s), and the responses 3094 are received and processed according to the steps described in 3095 section 7.2.4. 3097 7) This process continues iteratively until a complete SNMP 3098 Response-PDU has been built, or until there remain no 3099 target OID range lexicographical successors. 3101 7.2.4.4. Processing of Responses to agentx-TestSet-PDUs 3103 After common processing of the subagent's response to an 3104 agentx-TestSet-PDU (see 7.2.4.1 above), processing continues with 3105 the further exchange of AgentX PDUs. The value of h.transactionID 3106 in the agentx-CommitSet, -UndoSet, and -CleanupSet-PDUs must be 3107 identical to the value sent in the testSet-PDU. 3109 1) If any target subagent's response is not "noError", all other 3110 agentx-Response-PDUs received due to processing this SNMP 3111 request are ignored. 3113 An agentx-CleanupSet-PDU is sent to each target subagent. 3115 Processing is complete; the SNMP response PDU is constructed as 3116 described below in 7.2.4.6, step (2). 3118 2) Otherwise an agentx-CommitSet-PDU is sent to each target 3119 subagent. 3121 7.2.4.5. Processing of Responses to agentx-CommitSet-PDUs 3123 After common processing of the subagent's response to an 3124 agentx-CommitSet-PDU (see 7.2.4.1 above), processing continues with 3125 the following steps: 3127 1) If any response is not "noError", all other 3128 agentx-Response-PDUs received due to processing this SNMP 3129 request are ignored. 3131 An agentx-UndoSet-PDU is sent to each target subagent. 3133 2) Otherwise an agentx-CleanupSet-PDU is sent to each target 3134 subagent. Processing is complete; the SNMP response PDU is 3135 constructed as described below in 7.2.4.6, step (2). 3137 7.2.4.6. Processing of Responses to agentx-UndoSet-PDUs 3139 After common processing of the subagent's response to an 3140 agentx-UndoSet-PDU (see 7.2.4.1 above), processing continues with the 3141 following steps: 3143 1) An agentx-CleanupSet-PDU is sent to each target subagent. 3145 2) If any response is not "noError" the SNMP response 3146 PDU's error code is set to this value, and its error index to the 3147 index of the VarBind corresponding to the failed VarBind 3148 in the agentx-TestSet-PDU. 3150 Otherwise the SNMP response PDU's error code is set to "noError" 3151 and its error index to 0. 3153 7.2.5. Sending the SNMP Response-PDU 3155 Once the processing described in sections 7.2.1 - 7.2.4 is 3156 complete, there is an SNMP response PDU available. The master agent 3157 now implements the Elements of Procedure for the applicable version 3158 of the SNMP protocol in order to encapsulate the PDU into a message, 3159 and transmit it to the originator of the SNMP management request. 3161 Note that this may involve altering the PDU contents (for instance, 3162 to replace the original VarBinds if an error condition is 3163 to be returned). 3165 The response PDU may also be altered in order to support the SNMP 3166 version 1 framework. In such cases the required mapping is that 3167 defined in RFC 2089 [9]. (Note in particular that the rules for 3168 handling Counter64 syntax may require re-sending AgentX GetBulk 3169 or GetNext PDUs until a VarBind of suitable syntax is returned.) 3171 7.2.6. MIB Views 3173 AgentX subagents are not aware of MIB views, since view information 3174 is not contained in AgentX PDUs. 3176 As stated above, the descriptions of procedures in section 7 of this 3177 memo are not intended to constrain the internal architecture of any 3178 conformant implementation. In particular, the master agent 3179 procedures described in sections 7.2.1 and 7.2.4 may be altered so 3180 as to optimize AgentX exchanges when implementing MIB views. 3182 Such optimizations are beyond the scope of this memo. But note that 3183 section 7.2.3 defines subagent behavior in such a way that alteration 3184 of SearchRanges may be used in such optimizations. 3186 8. Transport Mappings 3188 The same AgentX PDU formats, encodings, and elements of procedure 3189 are used regardless of the underlying transport. 3191 8.1. AgentX over TCP 3193 8.1.1. Well-known Values 3195 The master agent accepts TCP connection requests for the well-known 3196 port 705. Subagents connect to the master agent using this port 3197 number. 3199 8.1.2. Operation 3201 Once a TCP connection has been established, the AgentX peers use 3202 this connection to carry all AgentX PDUs. Multiple AgentX sessions 3203 may be established using the same TCP connection. AgentX PDUs are 3204 sent within an AgentX session. AgentX peers are responsible for 3205 mapping the h.sessionID to a particular TCP connection. 3207 All AgentX PDUs are presented individually to the TCP, to be sent as 3208 the data portion of a TCP PDU. 3210 8.2. AgentX over UNIX-domain Sockets 3212 Many (BSD-derived) implementations of the UNIX operating system 3213 support the UNIX pathname address family (AF_UNIX) for socket 3214 communications. This provides a convenient method of sending and 3215 receiving data between processes on the same host. 3217 Mapping AgentX to this transport is useful for environments that 3219 - wish to guarantee subagents are running on the same 3220 managed node as the master agent, and where 3222 - sockets provide better performance than TCP or UDP, 3223 especially in the presence of heavy network I/O 3225 8.2.1. Well-known Values 3227 The master agent creates a well-known UNIX-domain socket endpoint 3228 called "var/agentx/master". (It may create other, implementation- 3229 specific endpoints.) 3231 This endpoint name uses the character set encoding native to the 3232 managed node, and represents a UNIX-domain stream (SOCK_STREAM) 3233 socket. 3235 8.2.2. Operation 3237 Once a connection has been established, the AgentX peers use 3238 this connection to carry all AgentX PDUs. 3240 Multiple AgentX sessions may be established using the same 3241 connection. AgentX PDUs are sent within an AgentX session. AgentX 3242 peers are responsible for mapping the h.sessionID to a particular 3243 connection. 3245 All AgentX PDUs are presented individually to the socket layer, to 3246 be sent in the data stream. 3248 9. Security Considerations 3250 This memo defines a protocol between two processing entities, 3251 one of which (the master agent) is also assumed to perform 3252 authentication of received SNMP requests and to control access 3253 to management information. The master agent performs these 3254 security operations independently of the other processing 3255 entity (the subagent). 3257 Security considerations require two questions to be answered: 3259 1. Is a particular subagent allowed to connect to a 3260 particular master agent? 3262 2. If so, then what part of the MIB tree is this subagent 3263 allowed to "cover"? 3265 Via the AgentX protocol, a subagent might connect to a master agent 3266 using either a network transport mechanism (e.g., TCP), or a "local" 3267 mechanism (e.g., shared memory, named pipes). 3269 In the case where a local transport mechanism is used and both 3270 subagent and master agent are running on the same box, security 3271 can be delegated to the operating system features. The answer to 3272 the first security question above becomes trivial: "If and only 3273 if the subagent has sufficient privileges, then the operating system 3274 will allow the connection". The answer to the second question 3275 is: "As long as the subagent is authorized to connect we allow 3276 it to cover any part of the MIB" (subject to controls within 3277 the SNMP and AgentX protocols). 3279 If a network transport is used, and/or the subagent and master agent 3280 are running on different hosts, then it is required that the 3281 transport mechanism utilized provide its own security. 3282 Transport Layer Security or SSL is suggested as offering 3283 adequate protection, identifying the subagents by their OIDs, 3284 and the master agent by its AgentID (this is necessary 3285 for the purpose of security key ownership). 3287 When the subagent and master agent are running on the same host, 3288 authorization issues can be ignored. If the box owner (root 3289 privileges) wishes to start a subagent that wants to handle 3290 some MIB groups, the decision is his and no security issues 3291 arise. 3293 Thus it is recommended that subagents run always on the same 3294 box as the Master Agent. If an insecure network layer transport 3295 must be used, that constitutes a potential exposure. 3297 However, when the owners of the subagent and master agent 3298 entities are different, we need to be able to provide both 3299 authentication (i.e., whether this subagent is allowed to 3300 talk to us at all) and authorization (i.e. what part of the 3301 MIB tree we may parcel out to this subagent). 3303 When the connection is being established, mutual authentication 3304 between master agent and subagent is required. TLS allows that. 3306 Even though actual cryptographic services (message integrity, 3307 source authentication, confidentiality and such) can be handled 3308 by the TLS (or SSL) layer, authorization has to be done here in 3309 AgentX, so that independent implementations of AgentX master 3310 agents and subagents may interoperate securely. 3312 This case is still problematic because we (the community) have 3313 not yet decided how to accommodate all the permutations of legal 3314 registration features of AgentX in, for example, some table of 3315 authorized connections, that should indicate: "Subagent 1.3.x.y 3316 ...is allowed to talk to us (a given master agent) and we permit 3317 it to handle the following MIBs...". 3319 For now, the resolution is that if security between a master 3320 agent and one or more subagents is critical in a particular 3321 application, then those components should all reside on the 3322 same machine, and for TCP they should only use the loopback 3323 address or an SSL connection. For the UNIX domain the access 3324 rights can be delegated to the underlying operating system 3325 features. 3327 10. Acknowledgements 3329 The initial draft of this memo was heavily influenced by the DPI 3330 2.0 specification RFC 1592 [7]. 3332 This document was produced by the IETF Agent Extensibility 3333 (AgentX) Working Group, and benefited especially from the 3334 contributions of the following working group members: 3336 David Battle, Uri Blumenthal, Jeff Case, Maria Greene, 3337 Dave Keeney, Harmen van der Linde, Bob Natale, Randy Presuhn, 3338 Aleksey Romanov, Don Ryan, and Juergen Schoenwaelder. 3340 The AgentX Working Group is chaired by: 3342 Bob Natale 3343 ACE*COMM Corporation 3344 704 Quince Orchard Road 3345 Gaithersburg MD 20878 3347 Phone: +1-301-721-3000 3348 Fax: +1-301-721-3001 3349 EMail: bnatale@acecomm.com 3351 11. Authors' and Editor's Addresses 3353 Mike Daniele 3354 Digital Equipment Corporation 3355 110 Spit Brook Rd 3356 Nashua, NH 03062 3358 Phone: +1-603-881-1423 3359 EMail: daniele@zk3.dec.com 3360 Bert Wijnen 3361 IBM Professional Services 3362 Watsonweg 2 3363 1423 ND Uithoorn 3364 The Netherlands 3366 Phone: +31-79-322-8316 3367 EMail: wijnen@vnet.ibm.com 3369 Dale Francisco (editor) 3370 Cisco Systems 3371 150 Castilian Dr 3372 Goleta CA 93117 3374 Phone: +1-805-961-3642 3375 Fax: +1-805-961-3600 3376 EMail: dfrancis@cisco.com 3378 12. References 3380 [1] Information processing systems - Open Systems Interconnection - 3381 Specification of Abstract Syntax Notation One (ASN.1), 3382 International Organization for Standardization. International 3383 Standard 8824, (December, 1987). 3385 [2] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3386 S. Waldbusser, "Structure of Management Information for Version 2 3387 of the Simple Network Management Protocol (SNMPv2)", RFC 1902, 3388 January 1996. 3390 [3] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3391 S. Waldbusser, "Textual Conventions for Version 2 of the Simple 3392 Network Management Protocol (SNMPv2)", RFC 1903, January 1996. 3394 [4] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3395 S. Waldbusser, "Protocol Operations for Version 2 of the Simple 3396 Network Management Protocol (SNMPv2)", RFC 1905, January 1996. 3398 [5] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3399 S. Waldbusser, "Management Information Base for Version 2 of the 3400 Simple Network Management Protocol (SNMPv2)", RFC 1907, 3401 January 1996. 3403 [6] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network 3404 Management Protocol", STD 15, RFC 1157, SNMP Research, Performance 3405 Systems International, MIT Laboratory for Computer Science, May 3406 1990. 3408 [7] Wijnen, B., Carpenter, G., Curran, K., Sehgal, A., and G. Waters, 3409 "Simple Network Management Protocol: Distributed Protocol 3410 Interface, Version 2.0", RFC 1592, T.J. Watson Research Center, 3411 IBM Corp., Bell Northern Research, Ltd., March 1994. 3413 [8] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3414 S. Waldbusser, "Coexistence between Version 1 and Version 2 of the 3415 Internet-standard Network Management Framework", RFC 1908, 3416 January 1996. 3418 [9] Wijnen, B., and Levi, D., "V2ToV1: Mapping SNMPv2 onto SNMPv1 3419 Within a Bilingual SNMP Agent", RFC 2089, T.J. Watson Research 3420 Center, IBM Corp., SNMP Research, Inc., January 1997. 3422 [10] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3423 S. Waldbusser, "Conformance Statements for Version 2 of the 3424 Simple Network Management Protocol (SNMPv2)", RFC 1904, 3425 January 1996. 3427 [11] Interfaces MIB Working Group, McCloghrie, K., and F. Kastenholz, 3428 "Evolution of the Interfaces Group of MIB-II", RFC 1573, 3429 January 1994. 3431 [12] FDDI MIB Working Group, J. Case, "FDDI Management Information 3432 Base", RFC 1285, January 1992. 3434 [13] Application MIB Working Group, Krupczak, C., and J. Saperia, 3435 "Definitions of Managed Objects for Applications", 3436 draft-ietf-applmib-sysapplmib-05.txt, 11 Nov 1996.