idnits 2.17.1 draft-ietf-agentx-ext-pro-03.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-04-26) 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 2 instances of lines with control characters in the document. == There are 13 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 1219: '... (u.context) OPTIONAL...' RFC 2119 keyword, line 1275: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1347: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1420: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1453: '... (t.context) OPTIONAL...' (4 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- 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 2152 -- Looks like a reference, but probably isn't: '1-4' on line 2160 -- Looks like a reference, but probably isn't: '1-5' on line 2174 -- 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: 22 errors (**), 0 flaws (~~), 4 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 November 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..................................................22 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...................................34 69 6.2.8 The agentx-TestSet-PDU...................................35 70 6.2.9 The agentx-CommitSet, -UndoSet, -CleanupSet 71 PDUs.....................................................36 72 6.2.10 The agentx-Notify-PDU...................................37 73 6.2.11 The agentx-Ping-PDU.....................................38 74 6.2.12 The agentx-IndexAllocate-PDU............................39 75 6.2.13 The agentx-IndexDeallocate-PDU..........................40 76 6.2.14 The agentx-AddAgentCaps-PDU.............................41 77 6.2.15 The agentx-RemoveAgentCaps-PDU..........................43 78 6.2.16 The agentx-Response-PDU.................................44 80 7 Elements of Procedure............................................46 81 7.1 Processing AgentX Administrative Messages....................46 82 7.1.1 Processing the agentx-Open-PDU...........................47 83 7.1.2 Processing the agentx-IndexAllocate-PDU..................48 84 7.1.3 Using the agentx-IndexAllocate-PDU.......................49 85 7.1.4 Processing the agentx-IndexDeallocate-PDU................51 86 7.1.5 Processing the agentx-Register-PDU.......................52 87 7.1.5.1 Handling Duplicate OID Ranges........................54 88 7.1.6 Processing the agentx-Unregister-PDU.....................54 90 Daniele/Wijnen Expires November 1997 [Page 2] 91 7.1.7 Processing the agentx-AddAgentCaps-PDU...................55 92 7.1.8 Processing the agentx-RemoveAgentCaps-PDU................56 93 7.1.9 Processing the agentx-Close-PDU..........................56 94 7.1.10 Detecting Connection Loss...............................57 95 7.1.11 Processing the agentx-Notify-PDU........................57 96 7.1.12 Processing the agentx-Ping-PDU..........................58 97 7.2 Processing Received SNMP Protocol Messages...................58 98 7.2.1 Dispatching AgentX PDUs..................................59 99 7.2.1.1 agentx-Get-PDU.......................................61 100 7.2.1.2 agentx-GetNext-PDU...................................62 101 7.2.1.3 agentx-GetBulk-PDU...................................62 102 7.2.1.4 agentx-TestSet-PDU...................................63 103 7.2.1.5 Dispatch.............................................64 104 7.2.2 Subagent Processing of agentx-Get, GetNext, 105 GetBulk-PDUs.............................................64 106 7.2.2.1 Subagent Processing of the agentx-Get-PDU............64 107 7.2.2.2 Subagent Processing of the 108 agentx-GetNext-PDU...................................65 109 7.2.2.3 Subagent Processing of the 110 agentx-GetBulk-PDU...................................65 111 7.2.3 Subagent Processing of agentx-TestSet, 112 -CommitSet, -UndoSet, -CleanupSet-PDUs...................67 113 7.2.3.1 Subagent Processing of the 114 agentx-TestSet-PDU...................................67 115 7.2.3.2 Subagent Processing of the 116 agentx-CommitSet-PDU.................................68 117 7.2.3.3 Subagent Processing of the 118 agentx-UndoSet-PDU...................................68 119 7.2.3.4 Subagent Processing of the 120 agentx-CleanupSet-PDU................................69 121 7.2.4 Master Agent Processing of AgentX Responses..............69 122 7.2.4.1 Common Processing of All AgentX Response 123 PDUs.................................................69 124 7.2.4.2 Processing of Responses to agentx-Get-PDUs...........69 125 7.2.4.3 Processing of Responses to 126 agentx-GetNext-PDU and agentx-GetBulk-PDU............70 127 7.2.4.4 Processing of Responses to 128 agentx-TestSet-PDUs..................................71 129 7.2.4.5 Processing of Responses to 130 agentx-CommitSet-PDUs................................71 131 7.2.4.6 Processing of Responses to 132 agentx-UndoSet-PDUs..................................72 133 7.2.5 Sending the SNMP Response-PDU............................72 134 7.2.6 MIB Views................................................72 135 7.3 State Transitions............................................73 136 7.3.1 Set Transaction States...................................73 137 7.3.2 Transport Connection States..............................75 138 7.3.3 Session States...........................................76 140 8 Transport Mappings...............................................77 141 8.1 AgentX over TCP..............................................77 143 Daniele/Wijnen Expires November 1997 [Page 3] 144 8.1.1 Well-known Values........................................77 145 8.1.2 Operation................................................77 146 8.2 AgentX over UNIX-domain Sockets..............................77 147 8.2.1 Well-known Values........................................78 148 8.2.2 Operation................................................78 150 9 Security Considerations..........................................78 152 10 Acknowledgements................................................79 154 11 Authors' and Editor's Addresses.................................80 156 12 References......................................................80 158 Daniele/Wijnen Expires November 1997 [Page 4] 159 1. Introduction 161 This memo defines a standardized framework for extensible SNMP 162 agents. It defines processing entities called master agents 163 and subagents, a protocol (AgentX) used to communicate between 164 them, and the elements of procedure by which the extensible agent 165 processes SNMP protocol messages. 167 2. The SNMP Framework 169 A management system contains: several (potentially many) nodes, 170 each with a processing entity, termed an agent, which has access to 171 management instrumentation; at least one management station; and, a 172 management protocol, used to convey management information between 173 the agents and management stations. Operations of the protocol are 174 carried out under an administrative framework which defines 175 authentication, authorization, access control, and privacy 176 policies. 178 Management stations execute management applications which monitor 179 and control managed elements. Managed elements are devices such as 180 hosts, routers, terminal servers, etc., which are monitored and 181 controlled via access to their management information. 183 Management information is viewed as a collection of managed objects, 184 residing in a virtual information store, termed the Management 185 Information Base (MIB). Collections of related objects are defined 186 in MIB modules. These modules are written using a subset of OSI's 187 Abstract Syntax Notation One (ASN.1) [1], termed the Structure of 188 Management Information (SMI) (see RFC 1902 [2]). 190 2.1. A Note on Terminology 192 The term "variable" refers to an instance of a non-aggregate 193 object type defined according to the conventions set forth in the 194 SMI (RFC 1902, [2]) or the textual conventions based on the SMI 195 (RFC 1903 [3]). The term "variable binding" normally refers to 196 the pairing of the name of a variable and its associated value. 197 However, if certain kinds of exceptional conditions occur during 198 processing of a retrieval request, a variable binding will pair a 199 name and an indication of that exception. 201 A variable-binding list is a simple list of variable bindings. 203 The name of a variable is an OBJECT IDENTIFIER, which is the 204 concatenation of the OBJECT IDENTIFIER of the corresponding object 205 type together with an OBJECT IDENTIFIER fragment identifying the 206 instance. The OBJECT IDENTIFIER of the corresponding object-type is 207 called the OBJECT IDENTIFIER prefix of the variable. 208 For the purpose of exposition, the original Internet-standard 210 Daniele/Wijnen Expires November 1997 [Page 5] 211 Network Management Framework, as described in RFCs 1155 (STD 16), 212 1157 (STD 15), and 1212 (STD 16), is termed the SNMP version 1 213 framework (SNMPv1). The current framework, as described in RFCs 214 1902-1908, is termed the SNMP version 2 framework (SNMPv2). 216 3. Extending the MIB 218 New MIB modules that extend the Internet-standard MIB are 219 continuously being defined by various IETF working groups. It is 220 also common for enterprises or individuals to create or extend 221 enterprise-specific or experimental MIBs. 223 As a result, managed devices are frequently complex collections of 224 manageable components that have been independently installed on a 225 managed node. Each component provides instrumentation for the 226 managed objects defined in the MIB module(s) it implements. 228 Neither the SNMP version 1 or version 2 framework addresses how 229 managed objects may be dynamically added to or removed from the 230 agent view within a particular managed node. 232 3.1. Motivation for AgentX 234 This very real need to dynamically extend the management objects 235 within a node has given rise to a variety of "extensible agents", 236 which typically comprise 238 - a "master" agent that is available on the standard transport 239 address and that accepts SNMP protocol messages 241 - a set of "subagents" that each contain management 242 instrumentation 244 - a protocol that operates between the master agent and subagents, 245 permitting subagents to "connect" to the master agent, and the 246 master agent to multiplex received SNMP protocol messages 247 amongst the subagents. 249 - a set of tools to aid subagent development, and a runtime (API) 250 environment that hides much of the protocol operation between a 251 subagent and the master agent. 253 The wide deployment of extensible SNMP agents, coupled with the 254 lack of Internet standards in this area, makes it difficult to field 255 SNMP-manageable applications. A vendor may have to support several 256 different subagent environments (APIs) in order to support different 257 target platforms. 259 It can also become quite cumbersome to configure subagents and 260 (possibly multiple) master agents on a particular managed node. 262 Daniele/Wijnen Expires November 1997 [Page 6] 263 Specifying a standard protocol for agent extensibility (AgentX) 264 provides the technical foundation required to solve both of 265 these problems. Independently developed AgentX-capable master 266 agents and subagents will be able to interoperate at the protocol 267 level. Vendors can continue to differentiate their products 268 in all other respects. 270 4. AgentX Framework 272 Within the SNMP framework, a managed node contains a processing 273 entity, called an agent, which has access to management 274 information. 276 Within the AgentX framework, an agent is further defined to 277 consist of 279 - a single processing entity called the master agent, which sends 280 and receives SNMP protocol messages in an agent role (as 281 specified by the SNMP version 1 and version 2 framework 282 documents) but typically has little or no direct access to 283 management information. 285 - 0 or more processing entities called subagents, which are 286 "shielded" from the SNMP protocol messages processed by the 287 master agent, but which have access to management information. 289 The master and subagent entities communicate via AgentX protocol 290 messages, as specified in this memo. Other interfaces (if any) on 291 these entities, and their associated protocols, are outside the 292 scope of this document. While some of the AgentX protocol messages 293 appear similar in syntax and semantics to the SNMP, bear in mind 294 that AgentX is not SNMP. 296 The internal operations of AgentX are invisible to an SNMP entity 297 operating in a manager role. From a manager's point of view, an 298 extensible agent behaves exactly as would a non-extensible 299 (monolithic) agent that has access to the same management 300 instrumentation. 302 This transparency to managers is a fundamental requirement of 303 AgentX, and is what differentiates AgentX subagents from SNMP proxy 304 agents. 306 Daniele/Wijnen Expires November 1997 [Page 7] 307 4.1. AgentX Roles 309 An entity acting in a master agent role performs the following 310 functions: 312 - Accepts AgentX session establishment requests from subagents. 314 - Accepts registration of MIB regions by subagents. 316 - Sends and accepts SNMP protocol messages on the agent's 317 specified transport addresses. 319 - Implements the agent role Elements of Procedure specified 320 for the administrative framework applicable to the SNMP 321 protocol message, except where they specify performing 322 management operations. (The application of MIB views, and 323 the access control policy for the managed node, are 324 implemented by the master agent.) 326 - Provides instrumentation for the MIB objects defined in RFC 327 1907 [5], and for any MIB objects relevant to any 328 administrative framework it supports. 330 - Sends and receives AgentX protocol messages to access 331 management information, based on the current registry of MIB 332 regions. 334 - Forwards notifications on behalf of subagents. 336 An entity acting in a subagent role performs the following functions: 338 - Initiates an AgentX session with the master agent. 340 - Registers MIB regions with the master agent. 342 - Instantiates managed objects. 344 - Binds OIDs within its registered MIB regions to actual 345 variables. 347 - Performs management operations on variables. 349 - Initiates notifications. 351 Daniele/Wijnen Expires November 1997 [Page 8] 352 4.2 Applicability 354 It is intended that this draft specify the smallest amount of 355 required behavior necessary to achieve the largest benefit, 356 that is, to cover a very large number of possible MIB 357 implementations and configurations with minimum complexity and low 358 "cost of entry". 360 This section discusses several typical usage scenarios. 362 1) Subagents implement separate MIB modules--for example, 363 subagent A implements "mib-2", subagent b implements 364 "host-resources". 366 It is anticipated that this will be the most common subagent 367 configuration. 369 2) Subagents implement rows in a "simple table". A simple table 370 is one in which row creation is not specified, and for which 371 the MIB does not define an object that counts entries in the 372 table. Examples of simple tables are rdbmsDbTable, udpTable, 373 and hrSWRunTable. 375 This is the most commonly defined type of MIB table, and 376 probably represents the next most typical configuration 377 that AgentX would support. 379 3) Subagents share MIBs along non-row partitions. Subagents 380 register "chunks" of the MIB that represent multiple rows, 381 due to the nature of the MIB's index structure. Examples 382 include registering ipNetToMediaEntry.n, where n represents 383 the ifIndex value for an interface implemented by the subagent, 384 and tcpConnEntry.a.b.c.d, where a.b.c.d represents an IP 385 address on an interface implemented by the subagent. 387 AgentX supports these three common configurations, and all 388 permutations of them, completely. The consensus is that they 389 comprise a very large majority of current and likely future uses 390 of multi-vendor extensible agent configurations. 392 4) Subagents implement rows in "complex tables". Complex tables 393 here are defined as tables permitting row creation, or whose 394 MIB also defines an object that counts entries in the table. 395 Examples include the MIB-2 ifTable (due to ifNumber), and the 396 RMON historyControlTable. 398 The subagent that implements such a counter object (like 399 ifNumber) must go beyond AgentX to correctly implement it. 400 This is an implementation issue (and most new MIB designs 401 no longer include such objects). 403 Daniele/Wijnen Expires November 1997 [Page 9] 404 To implement row creation in such tables, at least one AgentX 405 subagent must register at a point "higher" in the OID tree 406 than an individual row (per AgentX's dispatching procedure). 407 Again, this is an implementation issue. 409 Scenarios in this category were thought to occur somewhat 410 rarely in configurations where subagents are independently 411 implemented by different vendors. The focus of a standard 412 protocol, however, must be in just those areas where multi- 413 vendor interoperability must be assured. 415 Note that it would be inefficient (due to AgentX registration 416 overhead) to share a table among AgentX subagents if the table 417 contains very dynamic instances, and each subagent registers fully 418 qualified instances. ipRouteTable could be an example of such a 419 table in some environments. 421 4.3. Design Features of AgentX 423 The primary features of the design described in this memo are 425 1) A general architectural division of labor between master 426 agent and subagent: The master agent is MIB ignorant and 427 SNMP omniscient, while the subagent is SNMP ignorant and 428 MIB omniscient. That is, master agents, exclusively, are 429 concerned with SNMP protocol operations and the translations 430 to and from AgentX protocol operations needed to carry them 431 out; subagents are exclusively concerned with management 432 instrumentation; and neither should intrude on the other's 433 territory. 435 2) A standard protocol and "rules of engagement" to enable 436 interoperability between management instrumentation and 437 extensible agents. 439 3) Mechanisms for independently developed subagents to 440 integrate into the extensible agent on a particular 441 managed node in such a way that they need not be aware 442 of any other existing subagents. 444 4) A simple, deterministic registry and dispatching algorithm. 445 For a given extensible agent configuration, there is a single 446 subagent who is "authoritative" for any particular region of 447 the MIB (where "region" may extend from an entire MIB down 448 to a single object-instance). 450 5) Performance considerations. It is likely that the master 451 agent and all subagents will reside on the same host, and 452 in such cases AgentX is more a form of inter-process 453 communication than a traditional communications protocol. 454 Some of the design decisions made with this in mind include: 456 - 32-bit alignment of data within PDUs 458 - Native byte-order encoding by subagents 460 - Large AgentX PDU payload sizes. 461 4.4 Non-Goals 463 1) Subagent-to-subagent communication. This is out of scope, 464 due to the security ramifications and complexity involved. 466 2) Subagent access (via the master agent) to MIB variables. 467 This is not addressed, since various other mechanisms 468 are available and it was not a fundamental requirement. 470 3) The ability to accommodate every conceivable extensible 471 agent configuration option. This was the most contentious 472 aspect in the drafting of this protocol. In essence, 473 certain features currently available in some commercial 474 extensible agent products are not included in AgentX. 475 Although useful or even vital in some implementation 476 strategies, the rough consensus was that these features 477 were not appropriate for an Internet Standard, or not 478 typically required for independently developed subagents 479 to coexist. The set of supported extensible agent 480 configurations is described above, in Section 4.2. 482 Some possible future version of the AgentX protocol may provide 483 coverage for one or more of these "non-goals" or for new goals 484 that might be identified after greater deployment experience. 486 5. AgentX Encodings 488 AgentX PDUs consist of a common header, followed by PDU-specific 489 data of variable length. Unlike SNMP PDUs, AgentX PDUs are not 490 encoded using the BER (as specified in ISO 8824 [1]), but are 491 transmitted as a contiguous byte stream. The data within this 492 stream is organized to provide natural alignment with respect to 493 the start of the PDU, permitting direct (integer) access by the 494 processing entities. 496 The first four fields in the header are single-byte values. 497 A bit (NETWORK_BYTE_ORDER) in the third field (h.flags) is 498 used to indicate the byte ordering of all multi-byte integer 499 values in the PDU, including those which follow in the header 500 itself. This is described in more detail in Section 6.1, 501 "AgentX PDU Header", below. 503 PDUs are depicted in this memo using the following convention 504 (where byte 1 is the first transmitted byte): 506 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 507 | byte 1 | byte 2 | byte 3 | byte 4 | 508 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 509 | byte 5 | byte 6 | byte 7 | byte 8 | 510 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 511 ... 513 Fields marked "" are reserved for future use and must be 514 zero-filled. 516 5.1. Object Identifier 518 An object identifier is encoded as a 4-byte header, followed by a 519 variable number of contiguous 4-byte fields representing 520 sub-identifiers. This representation (termed Object Identifier) is 521 as follows: 523 Object Identifier 525 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 526 | n_subid | prefix | include | | 527 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 528 | sub-identifier #1 | 529 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 530 ... 531 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 532 | sub-identifier #n_subid | 533 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 534 Object Identifier header fields: 536 n_subid 538 The number (0-128) of sub-identifiers in the object 539 identifier. An ordered list of "n_subid" 4-byte 540 sub-identifiers follows the 4-byte header. 542 prefix 544 An unsigned value used to reduce the length of object 545 identifier encodings. A non-zero value "x" is interpreted as 546 the first sub-identifier after "internet" (1.3.6.1), and 547 indicates an implicit prefix "internet.x" to the actual 548 sub-identifiers encoded in the Object Identifier. For 549 example, a prefix field value 2 indicates an implicit prefix 550 "1.3.6.1.2". A value of 0 in the prefix field indicates there 551 is no prefix to the sub-identifiers. 553 include 555 Used only when the Object Identifier is the start of a 556 SearchRange, as described in section 5.2. 558 A null Object Identifier consists of the 4-byte header with all 559 bytes set to 0. 561 Examples: 563 sysDescr.0 (1.3.6.1.2.1.1.1.0) 565 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 566 | 4 | 2 | 0 | 0 | 567 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 568 | 1 | 569 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 570 | 1 | 571 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 572 | 1 | 573 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 574 | 0 | 575 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 577 1.2.3.4 579 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 580 | 4 | 0 | 0 | 0 | 581 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 582 | 1 | 583 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 584 | 2 | 585 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 586 | 3 | 587 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 588 | 4 | 589 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 591 5.2. SearchRange 593 A SearchRange consists of two Object Identifiers. In its 594 communication with a subagent, the master agent uses a SearchRange 595 to identify a requested variable binding, and, in GetNext and 596 GetBulk operations, to set an upper bound on the names of managed 597 object instances the subagent may send in reply. 599 The first Object Identifier in a SearchRange (called the starting 600 OID) indicates the beginning of the range. It is frequently (but 601 not necessarily) the name of a requested variable binding. 603 The "include" field in this OID's header is a boolean value 604 (0 or 1) indicating whether or not the starting OID is included in 605 the range. 607 The second object identifier indicates the non-inclusive end of 608 the range, and its "include" field is always 0. 610 Example: To indicate a search range from 1.3.6.1.2.1.25.2 611 (inclusive) to 1.3.6.1.2.1.25.2.1 (exclusive), the SearchRange would 612 be 614 (start) 615 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 616 | 3 | 2 | 1 | 0 | 617 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 618 | 1 | 619 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 620 | 25 | 621 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 622 | 2 | 623 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 625 (end) 626 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 627 | 4 | 2 | 0 | 0 | 628 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 629 | 1 | 630 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 631 | 25 | 632 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 633 | 2 | 634 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 635 | 1 | 636 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 638 A SearchRangeList is a contiguous list of SearchRanges. 640 5.3. Octet String 642 An octet string is represented by a contiguous series of bytes, 643 beginning with a 4-byte integer whose value is the number of octets 644 in the octet string, followed by the octets themselves. This 645 representation is termed an Octet String. If the last octet does 646 not end on a 4-byte offset from the start of the Octet String, 647 padding bytes are appended to achieve alignment of following data. 648 This padding must be added even if the Octet String is the last item 649 in the PDU. Padding bytes must be zero filled. 651 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 652 | Octet String Length (L) | 653 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 654 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 655 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 656 ... 657 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 658 | Octet L - 1 | Octet L | Padding (as required) | 659 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 661 A null Octet String consists of a 4-byte length field set to 0. 663 5.4. Value Representation 665 Variable bindings may be encoded within the variable-length portion 666 of some PDUs. The representation of a variable binding (termed a 667 VarBind) consists of a 2-byte type field, a name (Object 668 Identifier), and the actual value data. 670 VarBind 672 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 673 | v.type | | 674 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 676 (v.name) 677 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 678 | n_subid | prefix | 0 | 0 | 679 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 680 | sub-identifier #1 | 681 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 682 ... 683 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 684 | sub-identifier #n_subid | 685 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 687 (v.data) 688 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 689 | data | 690 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 691 ... 692 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 693 | data | 694 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 695 VarBind fields: 697 v.type 699 Indicates the variable binding's syntax, and must be one of 700 the following values: 702 Integer (2), 703 Octet String (4), 704 Null (5), 705 Object Identifier (6), 706 IpAddress (64), 707 Counter32 (65), 708 Gauge32 (66), 709 TimeTicks (67), 710 Opaque (68), 711 Counter64 (70), 712 noSuchObject (128), 713 noSuchInstance (129), 714 endOfMibView (130) 716 v.name 718 The Object Identifier which names the variable. 720 v.data 722 The actual value, encoded as follows: 724 - Integer, Counter32, Gauge32, and TimeTicks are encoded as 725 4 contiguous bytes. If the NETWORK_BYTE_ORDER bit is set 726 in h.flags, the bytes are ordered most significant to least 727 significant, otherwise they are ordered least significant 728 to most significant. 730 - Counter64 is encoded as 8 contiguous bytes. If the 731 NETWORK_BYTE_ORDER bit is set in h.flags, the bytes are 732 ordered most significant to least significant, otherwise 733 they are ordered least significant to most significant. 735 - Object Identifiers are encoded as described in section 736 5.1, Object Identifier. 738 - IpAddress, Opaque, and Octet String are all octet strings 739 and are encoded as described in section 5.3, Octet String. 741 Value data always follows v.name whenever v.type is one 742 of the above types. These data bytes are present even if 743 they will not be used (as, for example, in certain types 744 of index allocation). 746 - Null, noSuchObject, noSuchInstance, and endOfMibView do not 747 contain any encoded value. Value data never follows 748 v.name in these cases. 750 Note that the VarBind itself does not contain the value size. 751 That information is implied for the fixed-length types, and 752 explicitly contained in the encodings of variable-length types 753 (Object Identifier and Octet String). 755 A VarBindList is a contiguous list of VarBinds. Within a 756 VarBindList, a particular VarBind is identified by an index value. 757 The first VarBind in a VarBindList has index value 1, the second 758 has index value 2, and so on. 760 6. Protocol Definitions 762 6.1. AgentX PDU Header 764 The AgentX PDU header is a fixed-format, 20-octet structure: 766 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 767 | h.version | h.type | h.flags | | 768 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 769 | h.sessionID | 770 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 771 | h.transactionID | 772 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 773 | h.packetID | 774 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 775 | h.payload_length | 776 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 778 An AgentX PDU header contains the following fields: 780 h.version 782 The version of the AgentX protocol (1 for this draft). 784 h.type 786 The PDU type; one of the following values: 788 agentx-Open-PDU (1), 789 agentx-Close-PDU (2), 790 agentx-Register-PDU (3), 791 agentx-Unregister-PDU (4), 792 agentx-Get-PDU (5), 793 agentx-GetNext-PDU (6), 794 agentx-GetBulk-PDU (7), 795 agentx-TestSet-PDU (8), 796 agentx-CommitSet-PDU (9), 797 agentx-UndoSet-PDU (10), 798 agentx-CleanupSet-PDU (11), 799 agentx-Notify-PDU (12), 800 agentx-Ping-PDU (13), 801 agentx-IndexAllocate-PDU (14), 802 agentx-IndexDeallocate-PDU (15), 803 agentx-AddAgentCaps-PDU (16), 804 agentx-RemoveAgentCaps-PDU (17), 805 agentx-Response-PDU (18) 807 h.flags 809 A bitmask, with bit 0 the least significant bit. The bit 810 definitions are as follows: 812 Bit Definition 813 --- ---------- 814 0 INSTANCE_REGISTRATION 815 1 NEW_INDEX 816 2 ANY_INDEX 817 3 NON_DEFAULT_CONTEXT 818 4 NETWORK_BYTE_ORDER 819 5-7 (reserved) 821 The NETWORK_BYTE_ORDER bit applies to all multi-byte 822 integer values in the entire AgentX packet, including 823 the remaining header fields. If set, then network byte 824 order (most significant byte first; "big endian") is 825 used. If not set, then least significant byte first 826 ("little endian") is used. 828 The NETWORK_BYTE_ORDER bit applies to all AgentX PDUs. 830 The NON_DEFAULT_CONTEXT bit is used only in the AgentX PDUs 831 described in section 6.1.1. 833 The NEW_INDEX and ANY_INDEX bits are used only within the 834 agentx-IndexAllocate-, and -IndexDeallocate-PDUs. 836 The INSTANCE_REGISTRATION bit is used only within the 837 agentx-Register-PDU. 839 h.sessionID 841 The session ID uniquely identifies a session over 842 which AgentX PDUs are exchanged between a subagent and 843 the master agent. The session ID has no significance 844 and no defined value in the agentx-Open-PDU sent by a 845 subagent to open a session with the master agent; in 846 this case, the master agent will assign a unique 847 sessionID that it will pass back in the corresponding 848 agentx-Response-PDU. From that point on, that same 849 sessionID will appear in every AgentX PDU exchanged 850 over that session between the master and the subagent. 851 A subagent may establish multiple AgentX sessions by 852 sending multiple agentx-Open-PDUs to the master agent. 854 In master agents that support multiple transport 855 protocols, the sessionID should be globally unique 856 rather than unique just to a particular transport. 858 h.transactionID 860 The transaction ID uniquely identifies, for a given 861 session, the single SNMP management request (and single 862 SNMP PDU) with which an AgentX PDU is associated. If 863 a single SNMP management request results in multiple 864 AgentX PDUs being sent by the master agent with the same 865 sessionID, each of these AgentX PDUs must contain the 866 same transaction ID; conversely, AgentX PDUs sent during 867 a particular session, that result from distinct SNMP 868 management requests, must have distinct transaction IDs 869 (within the limits of the 32-bit field). 871 Note that the transaction ID is not the same as the SNMP 872 PDU's request-id (as described in section 4.1 of RFC 873 1905 [4]), nor can it be, since a master agent might 874 receive SNMP requests with the same request-ids from 875 different managers. 877 The transaction ID has no significance and no defined 878 value in AgentX administrative PDUs, i.e., AgentX 879 PDUs that are not associated with an SNMP management 880 request. 882 h.packetID 884 A packet ID generated by the sender for all AgentX PDUs 885 except the agentx-Response-PDU. In an agentx-Response-PDU, 886 the packet ID must be the same as that in the received 887 AgentX PDU to which it is a response. A master agent 888 might use this field to associate subagent response PDUs 889 with their corresponding request PDUs. A subagent might 890 use this field to correlate responses to multiple 891 (batched) registrations. 893 h.payload_length 895 The size in octets of the PDU contents, excluding the 896 20-byte header. As a result of the encoding schemes 897 and PDU layouts, this value will always be either 0, 898 or a multiple of 4. 900 6.1.1. Context 902 In the SNMPv1 or v2c frameworks, the community string may be used as 903 an index into a local repository of configuration information that 904 may include community profiles or more complex context information. 905 Future versions of the SNMP will likely formalize this notion of 906 "context". 908 AgentX provides a mechanism for transmitting a context specification 909 within relevant PDUs, but does not place any constraints on the 910 content of that specification. 912 An optional context field may be present in the agentx-Register-, 913 UnRegister-, AddAgentCaps-, RemoveAgentCaps-, Get-, GetNext-, 914 GetBulk-, IndexAllocate-, IndexDeallocate-, Notify-, TestSet-, 915 and Ping- PDUs. 917 If the NON_DEFAULT_CONTEXT bit in the AgentX header field h.flags is 918 clear, then there is no context field in the PDU, and the operation 919 refers to the default context. 921 If the NON_DEFAULT_CONTEXT bit is set, then a context field 922 immediately follows the AgentX header, and the operation refers 923 to that specific context. The context is represented as an Octet 924 String. There are no constraints on its length or contents. 926 Thus, all of these AgentX PDUs (that is, those listed immediately 927 above) refer to, or "indicate" a context, which is either the 928 default context, or a non-default context explicitly named in the 929 PDU. 931 6.2. AgentX PDUs 933 6.2.1. The agentx-Open-PDU 935 An agentx-Open-PDU is generated by a subagent to request 936 establishment of an AgentX session with the master agent. 938 (AgentX header) 940 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 941 | h.version (1) | h.type (1) | h.flags | | 942 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 943 | h.sessionID | 944 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 945 | h.transactionID | 946 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 947 | h.packetID | 948 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 949 | h.payload_length | 950 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 952 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 953 | o.timeout | | 954 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 956 (o.id) 957 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 958 | n_subid | prefix | 0 | | 959 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 960 | subidentifier #1 | 961 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 962 ... | 963 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 964 | subidentifier #n_subid | 965 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 967 (o.descr) 968 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 969 | Octet String Length (L) | 970 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 971 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 972 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 973 ... 974 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 975 | Octet L - 1 | Octet L | Padding (as required) | 976 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 977 An agentx-Open-PDU contains the following fields: 979 o.timeout 981 The length of time, in seconds, that a master agent should 982 allow to elapse after dispatching a message to a subagent 983 before it regards the subagent as not responding. This is a 984 subagent-wide default value that may be overridden by values 985 associated with specific registered MIB regions. The default 986 value of 0 indicates that no subagent-wide value is 987 requested. 989 o.id 991 An Object Identifier that identifies the subagent. Subagents 992 that do not support such an notion may send a null Object 993 Identifier. 995 o.descr 997 An Octet String containing a DisplayString describing the 998 subagent. 1000 6.2.2. The agentx-Close-PDU 1002 An agentx-Close-PDU issued by either a subagent or the master 1003 agent terminates an AgentX session. 1005 (AgentX header) 1006 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1007 | h.version (1) | h.type (2) | h.flags | | 1008 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1009 | h.sessionID | 1010 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1011 | h.transactionID | 1012 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1013 | h.packetID | 1014 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1015 | h.payload_length | 1016 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1018 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1019 | c.reason | | 1020 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1021 An agentx-Close-PDU contains the following field: 1023 c.reason 1025 An enumerated value that gives the reason that the master 1026 agent or subagent closed the AgentX session. This field may 1027 take one of the following values: 1029 reasonOther(1) 1030 None of the following reasons 1032 reasonParseError(2) 1033 Too many AgentX parse errors from peer 1035 reasonProtocolError(3) 1036 Too many AgentX protocol errors from peer 1038 reasonTimeouts(4) 1039 Too many timeouts waiting for peer 1041 reasonShutdown(5) 1042 Sending entity is shutting down 1044 reasonByManager(6) 1045 Due to Set operation; this reason code can 1046 be used only by the master agent, in response 1047 to an SNMP management request. 1049 6.2.3. The agentx-Register-PDU 1051 An agentx-Register-PDU is generated by a subagent for each region of 1052 the MIB variable naming tree (within one or more contexts) that it 1053 wishes to support. 1055 (AgentX header) 1056 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1057 | h.version (1) | h.type (3) | h.flags | | 1058 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1059 | h.sessionID | 1060 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1061 | h.transactionID | 1062 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1063 | h.packetID | 1064 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1065 | h.payload_length | 1066 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1068 (r.context) (OPTIONAL) 1069 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1070 | Octet String Length (L) | 1071 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1072 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1073 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1074 ... 1075 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1076 | Octet L - 1 | Octet L | Padding (as required) | 1077 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1079 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1080 | r.timeout | r.priority | r.range_subid | | 1081 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1083 (r.region) 1084 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1085 | n_subid | prefix | 0 | | 1086 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1087 | sub-identifier #1 | 1088 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1089 ... 1090 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1091 | sub-identifier #n_subid | 1092 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1094 (r.upper_bound) 1095 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1096 | optional upper-bound sub-identifier | 1097 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1099 An agentx-Register-PDU contains the following fields: 1101 r.context 1103 An optional non-default context. 1105 r.timeout 1107 The length of time, in seconds, that a master agent should 1108 allow to elapse after dispatching a message to a subagent 1109 before it regards the subagent as not responding. r.timeout 1110 applies only to messages that concern MIB objects within 1111 r.region. It overrides both the subagent-wide value (if any) 1112 indicated when the AgentX session with the master agent was 1113 established, and the master agent's default timeout. The 1114 default value for r.timeout is 0 (no override). 1116 r.priority 1118 A value between 1 and 255, used to achieve a desired 1119 configuration when different subagents register identical or 1120 overlapping regions. Subagents with no particular knowledge 1121 of priority should register with the default value of 255 1122 (lowest priority). 1124 In the master agent's dispatching algorithm, smaller 1125 values of r.priority take precedence over larger values, 1126 as described in section 7.1.5.1. 1128 r.region 1130 An Object Identifier that, in conjunction with r.range_subid, 1131 indicates a region of the MIB that a subagent wishes to 1132 support. It may be a fully-qualified instance name, a partial 1133 instance name, a MIB table, an entire MIB, or ranges of any of 1134 these. 1136 The choice of what to register is implementation-specific; 1137 this memo does not specify permissible values. Standard 1138 practice however is for a subagent to register at the 1139 highest level of the naming tree that makes sense. 1140 Registration of fully-qualified instances is typically done 1141 only when a subagent can perform management operations only 1142 on particular rows of a conceptual table. 1144 If r.region is in fact a fully qualified instance name, the 1145 INSTANCE_REGISTRATION bit in h.flags must be set, otherwise it 1146 must be cleared. The master agent may save this information 1147 to optimize subsequent operational dispatching. 1149 r.range_subid 1151 Permits specifying a range in place of one of r.region's 1152 sub-identifiers. If this value is 0, no range is specified. 1153 Otherwise the "r.range_subid"-th sub-identifier in 1154 r.region is a range lower bound, and the range upper 1155 bound sub-identifier (r.upper_bound) immediately follows 1156 r.region. 1158 This permits registering a conceptual row with a single 1159 PDU. For example, the following PDU would register row 1160 7 of the RFC 1573 ifTable (1.3.6.1.2.1.2.2.1.1-22.7): 1162 (AgentX header) 1163 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1164 | h.version (1) | h.type (3) | h.flags | | 1165 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1166 | h.sessionID | 1167 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1168 | h.transactionID | 1169 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1170 | h.packetID | 1171 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1172 | h.payload_length | 1173 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1175 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1176 | r.timeout | r.priority | 5 | | 1177 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1179 (r.region) 1180 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1181 | 6 | 2 | 0 | | 1182 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1183 | 1 | 1184 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1185 | 2 | 1186 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1187 | 2 | 1188 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1189 | 1 | 1190 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1191 | 1 | 1192 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1193 | 7 | 1194 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1196 (r.upper_bound) 1197 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1198 | 22 | 1199 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1201 6.2.4. The agentx-Unregister-PDU 1203 The agentx-Unregister-PDU is sent by a subagent to remove a 1204 previously registered MIB region from the master agent's OID space. 1206 (AgentX header) 1207 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1208 | h.version (1) | h.type (4) | h.flags | | 1209 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1210 | h.sessionID | 1211 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1212 | h.transactionID | 1213 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1214 | h.packetID | 1215 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1216 | h.payload_length | 1217 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1219 (u.context) OPTIONAL 1220 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1221 | Octet String Length (L) | 1222 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1223 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1224 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1225 ... 1226 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1227 | Octet L - 1 | Octet L | Padding (as required) | 1228 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1230 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1231 | | u.range_subid | | 1232 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1234 (u.region) 1235 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1236 | n_subid | prefix | 0 | | 1237 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1238 | sub-identifier #1 | 1239 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1240 ... 1241 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1242 | sub-identifier #n_subid | 1243 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1245 (u.upper_bound) 1246 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1247 | optional upper-bound sub-identifier | 1248 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1249 An agentx-Unregister-PDU contains the following fields: 1251 u.context 1253 An optional non-default context. 1255 u.region 1257 Indicates a previously-registered region of the MIB that a 1258 subagent no longer wishes to support. 1260 6.2.5. The agentx-Get-PDU 1262 (AgentX header) 1263 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1264 | h.version (1) | h.type (5) | h.flags | | 1265 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1266 | h.sessionID | 1267 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1268 | h.transactionID | 1269 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1270 | h.packetID | 1271 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1272 | h.payload_length | 1273 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1275 (g.context) OPTIONAL 1276 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1277 | Octet String Length (L) | 1278 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1279 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1280 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1281 ... 1282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1283 | Octet L - 1 | Octet L | Padding (as required) | 1284 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1286 (g.sr) 1288 (start 1) 1289 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1290 | n_subid | prefix | include | | 1291 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1292 | sub-identifier #1 | 1293 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1294 ... 1295 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1296 | sub-identifier #n_subid | 1297 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1299 (end 1) 1300 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1301 | 0 | 0 | 0 | 0 | 1302 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1303 ... 1304 (start n) 1305 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1306 | n_subid | prefix | include | | 1307 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1308 | sub-identifier #1 | 1309 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1310 ... 1312 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1313 | sub-identifier #n_subid | 1314 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1316 (end n) 1317 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1318 | 0 | 0 | 0 | 0 | 1319 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1321 An agentx-Get-PDU contains the following fields: 1323 g.context 1325 An optional non-default context. 1327 g.sr 1329 A SearchRangeList containing the requested variables for this 1330 subagent. 1332 6.2.6. The agentx-GetNext-PDU 1334 (AgentX header) 1335 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1336 | h.version (1) | h.type (6) | h.flags | | 1337 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1338 | h.sessionID | 1339 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1340 | h.transactionID | 1341 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1342 | h.packetID | 1343 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1344 | h.payload_length | 1345 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1347 (g.context) OPTIONAL 1348 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1349 | Octet String Length (L) | 1350 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1351 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1352 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1353 ... 1354 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1355 | Octet L - 1 | Octet L | Padding (as required) | 1356 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1358 (g.sr) 1359 (start 1) 1360 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1361 | n_subid | prefix | include | | 1362 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1363 | sub-identifier #1 | 1364 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1365 ... 1366 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1367 | sub-identifier #n_subid | 1368 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1370 (end 1) 1371 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1372 | n_subid | prefix | 0 | | 1373 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1374 | sub-identifier #1 | 1375 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1376 ... 1377 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1378 | sub-identifier #n_subid | 1379 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1380 ... 1382 (start n) 1383 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1384 | n_subid | prefix | include | | 1385 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1386 | sub-identifier #1 | 1387 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1388 ... 1389 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1390 | sub-identifier #n_subid | 1391 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1393 (end n) 1394 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1395 | n_subid | prefix | 0 | | 1396 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1397 | sub-identifier #1 | 1398 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1399 ... 1400 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1401 | sub-identifier #n_subid | 1402 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1403 ... 1405 6.2.7. The agentx-GetBulk-PDU 1407 (AgentX header) 1408 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1409 | h.version (1) | h.type (7) | h.flags | | 1410 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1411 | h.sessionID | 1412 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1413 | h.transactionID | 1414 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1415 | h.packetID | 1416 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1417 | h.payload_length | 1418 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1420 (g.context) OPTIONAL 1421 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1422 | Octet String Length (L) | 1423 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1424 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1425 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1426 ... 1427 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1428 | Octet L - 1 | Octet L | Padding (as required) | 1429 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1431 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1432 | g.non_repeaters | g.max_repetitions | 1433 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1435 (g.sr) 1436 ... 1438 6.2.8. The agentx-TestSet-PDU 1440 (AgentX header) 1441 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1442 | h.version (1) | h.type (8) | h.flags | | 1443 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1444 | h.sessionID | 1445 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1446 | h.transactionID | 1447 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1448 | h.packetID | 1449 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1450 | h.payload_length | 1451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1453 (t.context) OPTIONAL 1454 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1455 | Octet String Length (L) | 1456 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1457 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1458 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1459 ... 1460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1461 | Octet L - 1 | Octet L | Padding (as required) | 1462 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1464 (t.vb) 1466 (VarBind 1) 1467 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1468 | v.type | | 1469 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1470 | n_subid | prefix | 0 | | 1471 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1472 | sub-identifier #1 | 1473 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1474 ... 1475 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1476 | sub-identifier #n_subid | 1477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1478 | data | 1479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1480 ... 1481 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1482 | data | 1483 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1484 ... 1486 (VarBind n) 1487 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1488 | v.type | | 1489 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1490 | n_subid | prefix | 0 | | 1491 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1492 | sub-identifier #1 | 1493 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1494 ... 1495 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1496 | sub-identifier #n_subid | 1497 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1498 | data | 1499 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1500 ... 1501 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1502 | data | 1503 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1505 An agentx-TestSet-PDU contains the following fields: 1507 t.context 1509 An optional non-default context. 1511 t.vb 1513 A VarBindList containing the requested VarBinds for 1514 this subagent. 1516 6.2.9. The agentx-CommitSet, -UndoSet, -CleanupSet PDUs 1518 These PDUs consist of the AgentX header only. 1520 The agentx-CommitSet-, -UndoSet-, and -Cleanup-PDUs are 1521 used in processing an SNMP SetRequest operation. 1523 6.2.10. The agentx-Notify-PDU 1525 An agentx-Notify-PDU is sent by a subagent to cause the master agent 1526 to forward a notification. 1528 (AgentX header) 1529 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1530 | h.version (1) | h.type (12) | h.flags | | 1531 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1532 | h.sessionID | 1533 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1534 | h.transactionID | 1535 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1536 | h.packetID | 1537 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1538 | h.payload_length | 1539 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1541 (n.context) OPTIONAL 1542 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1543 | Octet String Length (L) | 1544 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1545 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1546 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1547 ... 1548 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1549 | Octet L - 1 | Octet L | Padding (as required) | 1550 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1552 (n.vb) 1553 ... 1555 An agentx-Notify-PDU contains the following fields: 1557 n.context 1559 An optional non-default context. 1561 n.vb 1563 A VarBindList whose contents define the actual PDU to be 1564 sent. This memo places the following restrictions on its 1565 contents: 1567 - If the subagent supplies sysUpTime.0, it must be 1568 present as the first varbind. 1570 - snmpTrapOID.0 must be present, as the second 1571 varbind if sysUpTime.0 was supplied, as the 1572 first if it was not. 1574 6.2.11 The agentx-Ping-PDU 1576 The agentx-Ping-PDU is sent by a subagent to the master agent to 1577 monitor the master agent's ability to receive and send AgentX 1578 PDUs over their AgentX session. 1580 (AgentX header) 1581 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1582 | h.version (1) | h.type (13) | h.flags | | 1583 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1584 | h.sessionID | 1585 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1586 | h.transactionID | 1587 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1588 | h.packetID | 1589 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1590 | h.payload_length | 1591 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1593 (p.context) OPTIONAL 1594 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1595 | Octet String Length (L) | 1596 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1597 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1598 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1599 ... 1600 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1601 | Octet L - 1 | Octet L | Padding (as required) | 1602 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1604 An agentx-Ping-PDU may contain the following field: 1606 p.context 1608 An optional non-default context. 1610 Using p.context a subagent can retrieve the sysUpTime value 1611 for a specific context, if required. 1613 6.2.12. The agentx-IndexAllocate-PDU 1615 An agentx-IndexAllocate-PDU is sent by a subagent to request 1616 allocation of a value for specific index objects. Refer to section 1617 7.1.3 (Using the agentx-IndexAllocate-PDU) for suggested usage. 1619 (AgentX header) 1620 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1621 | h.version (1) | h.type (14) | h.flags | | 1622 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1623 | h.sessionID | 1624 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1625 | h.transactionID | 1626 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1627 | h.packetID | 1628 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1629 | h.payload_length | 1630 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1632 (i.context) OPTIONAL 1633 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1634 | Octet String Length (L) | 1635 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1636 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1637 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1638 ... 1639 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1640 | Octet L - 1 | Octet L | Padding (as required) | 1641 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1643 (i.vb) 1644 ... 1646 An agentx-IndexAllocate-PDU contains the following fields: 1648 i.context 1650 An optional non-default context. 1652 i.vb 1654 A VarBindList containing the index names and values requested 1655 for allocation. 1657 6.2.13. The agentx-IndexDeallocate-PDU 1659 An agentx-IndexDeallocate-PDU is sent by a subagent to release 1660 previously allocated index values. 1662 (AgentX header) 1663 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1664 | h.version (1) | h.type (15) | h.flags | | 1665 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1666 | h.sessionID | 1667 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1668 | h.transactionID | 1669 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1670 | h.packetID | 1671 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1672 | h.payload_length | 1673 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1675 (i.context) OPTIONAL 1676 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1677 | Octet String Length (L) | 1678 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1679 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1680 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1681 ... 1682 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1683 | Octet L - 1 | Octet L | Padding (as required) | 1684 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1686 (i.vb) 1687 ... 1689 An agentx-IndexDeallocate-PDU contains the following fields: 1691 i.context 1693 An optional non-default context. 1695 i.vb 1697 A VarBindList containing the index names and values to be 1698 released. 1700 6.2.14. The agentx-AddAgentCaps-PDU 1702 An agentx-AddAgentCaps-PDU is generated by a subagent to inform the 1703 master agent of its agent capabilities. 1705 (AgentX header) 1706 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1707 | h.version (1) | h.type (16) | h.flags | | 1708 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1709 | h.sessionID | 1710 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1711 | h.transactionID | 1712 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1713 | h.packetID | 1714 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1715 | h.payload_length | 1716 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1718 (a.context) (OPTIONAL) 1719 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1720 | Octet String Length (L) | 1721 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1722 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1723 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1724 ... 1725 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1726 | Octet L - 1 | Octet L | Optional Padding | 1727 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1729 (a.id) 1730 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1731 | n_subid | prefix | 0 | | 1732 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1733 | sub-identifier #1 | 1734 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1735 ... 1736 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1737 | sub-identifier #n_subid | 1738 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1740 (a.descr) 1741 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1742 | Octet String Length (L) | 1743 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1744 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1745 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1746 ... 1747 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1748 | Octet L - 1 | Octet L | Optional Padding | 1749 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1751 An agentx-AddAgentCaps-PDU contains the following fields: 1753 a.context 1755 An optional non-default context. 1757 a.id 1759 An Object Identifier containing the value of an invocation of 1760 the AGENT-CAPABILITIES macro, which the master agent exports 1761 as a value of sysORID for the indicated context. (Recall that 1762 the value of an invocation of an AGENT-CAPABILITIES macro is 1763 an object identifier that describes a precise level of support 1764 with respect to implemented MIB modules. A more complete 1765 discussion of the AGENT-CAPABILITIES macro and related sysORID 1766 values can be found in section 6 of RFC 1904 [10].) 1768 a.descr 1770 An Octet String containing a DisplayString to be used as the 1771 value of sysORDescr corresponding to the sysORID value above. 1773 6.2.15. The agentx-RemoveAgentCaps-PDU 1775 An agentx-RemoveAgentCaps-PDU is generated by a subagent to request 1776 that the master agent stop exporting a particular value of sysORID. 1777 This value must have previously been advertised by the subagent in 1778 an agentx-AddAgentCaps-PDU. 1780 (AgentX header) 1781 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1782 | h.version (1) | h.type (17) | h.flags | | 1783 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1784 | h.sessionID | 1785 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1786 | h.transactionID | 1787 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1788 | h.packetID | 1789 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1790 | h.payload_length | 1791 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1793 (a.context) (OPTIONAL) 1794 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1795 | Octet String Length (L) | 1796 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1797 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1798 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1799 ... 1800 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1801 | Octet L - 1 | Octet L | Optional Padding | 1802 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1804 (a.id) 1805 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1806 | n_subid | prefix | 0 | | 1807 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1808 | sub-identifier #1 | 1809 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1810 ... 1811 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1812 | sub-identifier #n_subid | 1813 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1814 An agentx-RemoveAgentCaps-PDU contains the following fields: 1816 a.context 1818 An optional non-default context. 1820 a.id 1822 An ObjectIdentifier containing the value of sysORID that 1823 should no longer be exported. 1825 6.2.16. The agentx-Response-PDU 1827 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1828 | h.version (1) | h.type (18) | h.flags | | 1829 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1830 | h.sessionID | 1831 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1832 | h.transactionID | 1833 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1834 | h.packetID | 1835 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1836 | h.payload_length | 1837 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1839 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1840 | res.sysUpTime | 1841 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1842 | res.error | res.index | 1843 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1844 ... 1846 An agentx-Response-PDU contains the following fields: 1848 h.sessionID 1850 If this is a response to a agentx-Open-PDU, then it 1851 contains the new and unique sessionID (as assigned by 1852 the master agent) for this session. 1854 Otherwise it must be identical to the h.sessionID 1855 value in the PDU to which this PDU is a response. 1857 h.transactionID 1859 Must be identical to the h.transactionID value in the PDU to 1860 which this PDU is a response. 1862 In an agentx response PDU from the master agent to the 1863 subagent, the value of h.transactionID has no significance 1864 and can be ignored by the subagent. 1866 h.packetID 1868 Must be identical to the h.packetID value in the PDU to 1869 which this PDU is a response. 1871 res.sysUpTime 1873 This field contains the current value of sysUpTime for 1874 the indicated context. It is relevant only in agentx 1875 response PDUs sent from the master agent to a subagent in 1876 response to the following agentx PDUs: 1878 agentx-Open-PDU (1), 1879 agentx-Close-PDU (2), 1880 agentx-Register-PDU (3), 1881 agentx-Unregister-PDU (4), 1882 agentx-Ping-PDU (13), 1883 agentx-IndexAllocate-PDU (14), 1884 agentx-IndexDeallocate-PDU (15), 1885 agentx-AddAgentCaps-PDU (16), 1886 agentx-RemoveAgentCaps-PDU (17) 1888 In an agentx response PDU from the subagent to the master 1889 agent, the value of res.sysUpTime has no significance and 1890 is ignored by the master agent. 1892 res.error 1894 Indicates error status (including `noError'). Values are 1895 limited to those defined for errors in the SNMPv2 SMI (RFC 1896 1905 [4]), and the following AgentX-specific values: 1898 openFailed (256), 1899 notOpen (257), 1900 indexWrongType (258), 1901 indexAlreadyAllocated (259), 1902 indexNoneAvailable (260), 1903 indexNotAllocated (261), 1904 unsupportedContext (262), 1905 duplicateRegistration (263), 1906 unknownRegistration (264), 1907 unknownAgentCaps (265) 1909 res.index 1911 In error cases, this is the index of the failed variable 1912 binding within a received request PDU. (Note: As explained in 1913 section 5.4, Value Representation, the index values of 1914 variable bindings within a variable binding list are 1-based.) 1915 Other data may follow these latter two fields, depending on 1916 which AgentX PDU is being responded to. These data are 1917 specified in the subsequent elements of procedure. 1919 7. Elements of Procedure 1921 This section describes the actions of protocol entities (master 1922 agents and subagents) implementing the AgentX protocol. Note, 1923 however, that it is not intended to constrain the internal 1924 architecture of any conformant implementation. 1926 Specific error conditions and associated actions are described in 1927 various places. Other error conditions not specifically mentioned 1928 fall into one of two categories, "parse" errors and "protocol" 1929 errors. 1931 A parse error occurs when a receiving entity cannot decode the PDU. 1932 For instance, a VarBind contains an unknown type, or a PDU contains 1933 a malformed Object Identifier. 1935 A protocol error occurs when a receiving entity can parse a PDU, but 1936 the resulting data is unspecified. For instance, an 1937 agentx-Response-PDU is successfully parsed, but contains an unknown 1938 res.error value. 1940 An implementation may choose either to ignore such messages, or to 1941 close the session on which they are received, using the appropriate 1942 reason code as defined in the agentx-Close-PDU. 1944 The actions of AgentX protocol entities can be broadly categorized 1945 under two headings, each of which is described separately: 1947 (1) processing AgentX administrative messages (e.g., connection 1948 requests from a subagent to a master agent); and 1950 (2) processing SNMP messages (e.g., the coordinated actions of a 1951 master agent and one or more subagents in processing a 1952 received SNMP Get-PDU). 1954 7.1. Processing AgentX Administrative Messages 1956 This subsection describes the actions of AgentX protocol entities 1957 in processing AgentX administrative messages. Such messages 1958 include those involved in establishing and terminating an AgentX 1959 session between a subagent and a master agent, those by which a 1960 subagent requests allocation of instance index values, and those 1961 by which a subagent communicates to a master agent which MIB 1962 regions it supports. 1964 7.1.1. Processing the agentx-Open-PDU 1966 When the master agent receives an agentx-Open-PDU, it processes 1967 it as follows: 1969 1) An agentx-Response-PDU is created and res.sysUpTime is set to 1970 the value of sysUpTime.0 for the indicated context. 1972 2) If the master agent is unable to open an AgentX session for 1973 any reason, it may refuse the session establishment request, 1974 sending in reply the agentx-Response-PDU, with res.error 1975 field set to `openFailed'. 1977 3) Otherwise: The master agent assigns a sessionID to the new 1978 session and puts the value in the h.sessionID field of the 1979 agentx-Response-PDU. This value must be unique among all 1980 existing open sessions. 1982 4) The master agent retains session-specific information 1983 from the PDU for this subagent: 1985 - The NETWORK_BYTE_ORDER value in h.flags is retained. 1986 All subsequent AgentX protocol operations initiated by 1987 the master agent for this session must use this byte 1988 ordering and set this bit accordingly. 1990 The subagent typically sets this bit to correspond to 1991 its native byte ordering, and typically does not vary 1992 byte ordering for an initiated session. The master 1993 agent must be able to decode each PDU according to its 1994 h.flag NETWORK_BYTE_ORDER bit, but does not need to 1995 toggle its retained value for the session if the 1996 subagent varies its byte ordering. 1998 - The o.timeout value is used in calculating timeout 1999 conditions for this subagent. 2001 - The o.id and o.descr fields are used for informational 2002 purposes. (Such purposes are implementation-specific 2003 for now, and may be used in a possible future standard 2004 AgentX MIB.) 2006 5) The agentx-Response-PDU is sent with the res.error field 2007 set to `noError'. 2009 At this point, an AgentX session is considered established between 2010 the master agent and the subagent. An AgentX session is a distinct 2011 channel for the exchange of AgentX protocol messages between a 2012 master agent and one subagent, qualified by the session-specific 2013 attributes listed in 4) above. AgentX session establishment is 2014 initiated by the subagent. An AgentX session can be terminated 2015 by either the master agent or the subagent. 2017 7.1.2. Processing the agentx-IndexAllocate-PDU 2019 When the master agent receives an agentx-IndexAllocate-PDU, it 2020 processes it as follows: 2022 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2023 the value of sysUpTime.0 for the default context. 2025 2) If h.sessionID does not correspond to a currently established 2026 session with this subagent, the agentx-Response-PDU is sent 2027 in reply with res.error set to `notOpen'. 2029 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2030 supports only a default context, the agentx-Response-PDU is 2031 returned with res.error set to `unsupportedContext', and the 2032 requested allocation fails. Otherwise: The value of 2033 res.sysUpTime is set to the value of sysUpTime.0 for the 2034 indicated context. 2036 4) Each VarBind in the VarBindList is processed until either all 2037 are successful, or one fails. If any VarBind fails, the 2038 agentx-Response-PDU is sent in reply containing the original 2039 VarBindList, with res.index set to indicate the failed VarBind, 2040 and with res.error set as described subsequently. All other 2041 VarBinds are ignored; no index values are allocated. 2043 VarBinds are processed as follows: 2045 - v.name is the name of the index for which a value is to be 2046 allocated. 2048 - v.type is the syntax of the index object. 2050 - v.data indicates the specific index value requested. 2051 If the NEW_INDEX or the ANY_INDEX bit is set, the actual 2052 value in v.data is ignored and an appropriate index value 2053 is generated. 2055 a) If there are no currently allocated index values for v.name 2056 in the indicated context, and v.type does not correspond to 2057 a valid index type value, the VarBind fails and res.error 2058 is set to `indexWrongType'. 2060 b) If there are currently allocated index values for v.name 2061 in the indicated context, but the syntax of those values 2062 does not match v.type, the VarBind fails and res.error is 2063 set to `indexWrongType'. 2065 c) Otherwise, if both the NEW_INDEX and ANY_INDEX bits are 2066 clear, allocation of a specific index value is being 2067 requested. If the requested index is already allocated 2068 for v.name in the indicated context, the VarBind fails 2069 and res.error is set to `indexAlreadyAllocated'. 2071 d) Otherwise, if the NEW_INDEX bit is set, the master agent 2072 should generate the next available index value for v.name 2073 in the indicated context, with the constraint that this 2074 value must not have been allocated (even if subsequently 2075 released) to any subagent since the last re-initialization 2076 of the master agent. If no such value can be generated, 2077 the VarBind fails and res.error is set to `indexNoneAvailable'. 2079 e) Otherwise, if the ANY_INDEX bit is set, the master agent 2080 should generate an index value for v.name in the 2081 indicated context, with the constraint that this value is 2082 not currently allocated to any subagent. If no such value 2083 can be generated, then the VarBind fails and res.error is 2084 set to `indexNoneAvailable'. 2086 5) If all VarBinds are processed successfully, the 2087 agentx-Response-PDU is sent in reply with res.error set to 2088 `noError'. A VarBindList is included that is identical to the 2089 one sent in the agentx-IndexAllocate-PDU, except that VarBinds 2090 requesting a NEW_INDEX or ANY_INDEX value are generated with an 2091 appropriate value. 2093 7.1.3. Using the agentx-IndexAllocate-PDU 2095 Index allocation is a service provided by an AgentX master agent. 2096 It provides generic support for sharing MIB conceptual tables among 2097 subagents who are assumed to have no knowledge of each other. 2099 Each subagent sharing a table should first request allocation of 2100 index values, then use those index values to qualify MIB regions in 2101 its subsequent registrations. 2103 The master agent maintains a database of index objects (OIDs), and, 2104 for each index, the values that have been allocated for it. It is 2105 unaware of what MIB variables (if any) the index objects represent. 2107 By convention, subagents use the MIB variable listed in the INDEX 2108 clause as the index object for which values must be allocated. For 2109 tables indexed by multiple variables, values may be allocated for 2110 each index (although this is frequently unnecessary; see example 2 2111 below). The subagent may request allocation of 2113 - a specific index value 2114 - an index value that is not currently allocated 2115 - an index value that has never been allocated 2117 The last two alternatives reflect the uniqueness and constancy 2118 requirements present in many MIB specifications for arbitrary 2119 integer indexes (e.g., ifIndex in the IF MIB (RFC 1573 [11]), 2120 snmpFddiSMTIndex in the FDDI MIB (RFC 1285 [12]), or 2121 sysApplInstallPkgIndex in the Application MIB [13]). The need for 2122 subagents to share tables using such indexes is the main motivation 2123 for index allocation in AgentX. 2125 Example 1: 2127 A subagent implements an interface, and wishes to register a 2128 single row of the RFC 1573 ifTable. It requests an allocation 2129 for the index object "ifIndex", for a value that has never been 2130 allocated (since ifIndex values must be unique). The master agent 2131 returns the value "7". 2133 The subagent now attempts to register row 7 of ifTable, by 2134 specifying a MIB region in the agentx-Register-PDU of 2135 1.3.6.1.2.1.2.2.1.[1-22].7. If the registration succeeds, no 2136 further processing is required. The master agent will dispatch 2137 to this subagent correctly. 2139 But the registration may fail. Index allocation and MIB region 2140 registration are not coupled in the master agent. Some other 2141 subagent may have already registered ifTable row 7 without first 2142 having requested allocation of the index. The current state of 2143 index allocations is not considered when processing registration 2144 requests, and the current registry is not considered when 2145 processing index allocation requests. If subagents follow the 2146 model of "first request allocation of an index, then register the 2147 corresponding region", then a successful index allocation request 2148 gives a subagent a good hint (but no guarantee) of what it should 2149 be able to register. 2151 If the registration failed, the subagent should request allocation 2152 of a new index i, and attempt to register ifTable.[1-22].i, until 2153 successful. 2155 Example 2: 2157 This same subagent wishes to register ipNetToMediaTable rows 2158 corresponding to its interface (ifIndex i). Due to structure of 2159 this table, no further index allocation need be done. The 2160 subagent can register the MIB region ipNetToMediaTable.[1-4].i, 2161 It is claiming responsibility for all rows of the table whose 2162 value of ipNetToMediaIfIndex is i. 2164 Example 3: 2166 A network device consists of a set of processors, each of which 2167 accepts network connections for a unique set of IP addresses. 2169 Further, each processor contains a subagent that implements 2170 tcpConnTable. In order to represent tcpConnTable for the entire 2171 managed device, the subagents need to share tcpConnTable. 2173 In this case, no index allocation need be done at all. Each 2174 subagent can register a MIB region of tcpConnTable.[1-5].a.b.c.d, 2175 where a.b.c.d represents an unique IP address of the individual 2176 processor. 2178 Each subagent is claiming responsibility for the region of 2179 tcpConnTable where the value of tcpConnLocalAddress is a.b.c.d. 2181 7.1.4 Processing the agentx-IndexDeallocate-PDU 2183 When the master agent receives an agentx-IndexDeallocate-PDU, it 2184 processes it as follows: 2186 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2187 the value of sysUpTime.0 for the default context. 2189 2) If h.sessionID does not correspond to a currently 2190 established session with this subagent, the 2191 agentx-Response-PDU is sent in reply with res.error set 2192 to `notOpen'. 2194 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2195 supports only a default context, the agentx-Response-PDU is 2196 returned with res.error set to `unsupportedContext', and the 2197 requested allocation fails. Otherwise: The value of 2198 res.sysUpTime is set to the value of sysUpTime.0 for the 2199 indicated context. 2201 4) Each VarBind in the VarBindList is processed until either all 2202 are successful, or one fails. If any VarBind fails, the 2203 agentx-Response-PDU is sent in reply, containing the original 2204 VarBindList, with res.index set to indicate the failed VarBind, 2205 and with res.error set as described subsequently. All other 2206 VarBinds are ignored; no index values are released. 2208 VarBinds are processed as follows: 2210 - v.name is the name of the index for which a value is to be 2211 released 2213 - v.type is the syntax of the index object 2215 - v.data indicates the specific index value to be released. 2216 The NEW_INDEX and ANY_INDEX bits are ignored. 2218 a) If the index value for the named index is not currently 2219 allocated to this subagent, the VarBind fails and res.error 2220 is set to `indexNotAllocated'. 2222 5) If all VarBinds are processed successfully, res.error is 2223 set to `noError' and the agentx-Response-PDU is sent. 2224 A VarBindList is included which is identical to the one 2225 sent in the agentx-IndexDeallocate-PDU. 2227 All released index values are now available, and may be 2228 used in response to subsequent allocation requests for 2229 ANY_INDEX values for the particular index. 2231 7.1.5. Processing the agentx-Register-PDU 2233 When the master agent receives an agentx-Register-PDU, it processes 2234 it as follows: 2236 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2237 the value of sysUpTime.0 for the default context. 2239 2) If h.sessionID does not correspond to a currently 2240 established session with this subagent, the 2241 agentx-Response-PDU is sent in reply with res.error set 2242 to `notOpen'. 2244 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2245 supports only a default context, the agentx-Response-PDU is 2246 returned with res.error set to `unsupportedContext', and the 2247 requested allocation fails. Otherwise: The value of 2248 res.sysUpTime is set to the value of sysUpTime.0 for the 2249 indicated context. 2251 Note: Non-default contexts might be added on the fly by 2252 the master agent, or the master agent might require 2253 such non-default contexts to be pre-configured. 2254 The choice is implementation-specific. 2256 4) Characterize the request. 2258 If r.region (or any of its set of Object Identifiers, if r.range 2259 is non-zero) is exactly the same as any currently registered 2260 value of r.region (or any of its set of Object Identifiers), 2261 this registration is termed a duplicate region. 2263 If r.region (or any of its set of Object Identifiers, if r.range 2264 is non-zero) is a subtree of, or contains, any currently 2265 registered value of r.region (or any of its set of 2266 Object Identifiers), this registration is termed an overlapping 2267 region. 2269 If the NON_DEFAULT_CONTEXT bit is set, this region is to be 2270 logically registered within the context indicated by r.context. 2272 Otherwise this region is to be logically registered within the 2273 default context. 2275 A registration that would result in a duplicate region with the 2276 same priority and within the same context as that of a current 2277 registration is termed a duplicate registration. 2279 5) Otherwise, if this is a duplicate registration, the 2280 agentx-Response-PDU is returned with res.error set to 2281 `duplicateRegistration', and the requested registration fails. 2283 6) Otherwise, the agentx-Response-PDU is returned with res.error 2284 set to `noError'. 2286 The master agent adds this region to its registered OID space for 2287 the indicated context, to be considered during the dispatching 2288 phase for subsequently received SNMP protocol messages. 2290 Note: The following algorithm describes maintaining a set of 2291 OID ranges derived from "splitting" registered regions. The 2292 algorithm for operational dispatching is also stated in terms of 2293 these OID ranges. 2295 These OID ranges are a useful explanatory device, but are not 2296 required for a correct implementation. 2298 - If r.region (R1) is a subtree of a currently registered 2299 region (R2), split R2 into 3 new regions (R2a, R2b, and R2c) 2300 such that R2b is an exact duplicate of R1. Now remove R2 and 2301 add R1, R2a, R2b, and R2c to the master agent's 2302 lexicographically ordered set of ranges (the registered OID 2303 space). Note: Though newly-added ranges R1 and R2b are 2304 identical in terms of the MIB objects they contain, they are 2305 registered by different subagents, possibly at different 2306 priorities. 2308 For instance, if subagent S2 registered "ip" (R2 is 2309 1.3.6.1.2.1.4) and subagent S1 subsequently registered 2310 "ipNetToMediaTable" (R1 is 1.3.6.1.2.1.4.22), the resulting 2311 set of registered regions would be: 2313 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2) 2314 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2) 2315 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2316 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2) 2318 - If r.region (R1) overlaps one or more currently registered 2319 regions, then for each overlapped region (R2) split R1 into 3 2320 new ranges (R1a, R1b, R1c) such that R1b is an exact 2321 duplicate of R2. Add R1b and R2 into the lexicographically 2322 ordered set of regions. Apply (5) above iteratively to R1a and 2323 R1c (since they may overlap, or be subtrees of, other regions). 2325 For instance, given the currently registered regions in the 2326 example above, if subagent S3 now registers mib-2 (R1 is 2327 1.3.6.1.2.1) the resulting set of regions would be: 2329 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3) 2330 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2) 2331 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3) 2332 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2) 2333 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2334 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 2335 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2) 2336 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3) 2337 1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3) 2339 Note that at registration time a region may be split into multiple 2340 OID ranges due to pre-existing registrations, or as a result of any 2341 subsequent registration. This region splitting is transparent to 2342 subagents. Hence the master agent must always be able to associate 2343 any OID range with the information contained in its original 2344 agentx-Register-PDU. 2346 7.1.5.1. Handling Duplicate OID Ranges 2348 As a result of this registration algorithm there are likely to be 2349 duplicate OID ranges (regions of identical MIB objects registered to 2350 different subagents) in the master agent's registered OID space. 2351 Whenever the master agent's dispatching algorithm (see 7.2.1, 2352 Dispatching AgentX PDUs) selects a duplicate OID range, the 2353 determination of which one to use proceeds as follows: 2355 1) Choose the one whose original agentx-Register-PDU 2356 r.region contained the most subids, i.e., the most specific 2357 r.region. Note: The presence or absence of a range subid 2358 has no bearing on how "specific" one object identifier is 2359 compared to another. 2361 2) If still ambiguous, there were duplicate regions. Choose the 2362 one whose original agentx-Register-PDU specified the smaller 2363 value of r.priority. 2365 7.1.6. Processing the agentx-Unregister-PDU 2367 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2368 the value of sysUpTime.0 for the default context. 2370 2) If h.sessionID does not correspond to a currently 2371 established session with this subagent, the 2372 agentx-Response-PDU is sent in reply with res.error set 2373 to `notOpen'. 2375 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2376 supports only a default context, the agentx-Response-PDU is 2377 returned with res.error set to `unsupportedContext', and the 2378 requested allocation fails. Otherwise: The value of 2379 res.sysUpTime is set to the value of sysUpTime.0 for the 2380 indicated context. 2382 4) If u.region and the indicated context do not match an existing 2383 registration made during this session, the agentx-Response-PDU 2384 is returned with res.error set to `unknownRegistration'. 2386 5) Otherwise, the agentx-Response-PDU is sent in reply with res.error 2387 set to `noError', and the previous registration is removed: 2389 - The master agent removes u.region from its registered OID space 2390 within the indicated context. If the original region had been 2391 split, all such related regions are removed. 2393 For instance, given the example registry above, if subagent S2 2394 unregisters "ip", the resulting registry would be: 2396 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3) 2397 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3) 2398 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2399 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 2400 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3) 2401 1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3) 2403 7.1.7. Processing the agentx-AddAgentCaps-PDU 2405 When the master agent receives an agentx-AddAgentCaps-PDU, 2406 it processes it as follows: 2408 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2409 the value of sysUpTime.0 for the default context. 2411 2) If h.sessionID does not correspond to a currently 2412 established session with this subagent, the 2413 agentx-Response-PDU is sent in reply with res.error set 2414 to `notOpen'. 2416 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2417 supports only a default context, the agentx-Response-PDU is 2418 returned with res.error set to `unsupportedContext', and the 2419 requested allocation fails. Otherwise: The value of 2420 res.sysUpTime is set to the value of sysUpTime.0 for the 2421 indicated context. 2423 4) Otherwise, the master agent adds the subagent's capabilities 2424 information to the sysORTable for the indicated context. An 2425 agentx-Response-PDU is sent in reply with res.error set to 2426 `noError'. 2428 7.1.8. Processing the agentx-RemoveAgentCaps-PDU 2430 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2431 the value of sysUpTime.0 for the default context. 2433 2) If h.sessionID does not correspond to a currently 2434 established session with this subagent, the 2435 agentx-Response-PDU is sent in reply with res.error set 2436 to `notOpen'. 2438 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2439 supports only a default context, the agentx-Response-PDU is 2440 returned with res.error set to `unsupportedContext', and the 2441 requested allocation fails. Otherwise: The value of 2442 res.sysUpTime is set to the value of sysUpTime.0 for the 2443 indicated context. 2445 4) If the combination of a.id and the optional a.context does not 2446 represent a sysORTable entry that was added by this subagent, 2447 during this session, the agentx-Response-PDU is returned with 2448 res.error set to `unknownAgentCaps'. 2450 5) Otherwise the master agent deletes the corresponding sysORTable 2451 entry and sends in reply the agentx-Response-PDU, with res.error 2452 set to `noError'. 2454 7.1.9. Processing the agentx-Close-PDU 2456 When the master agent receives an agentx-Close-PDU, it processes it 2457 as follows: 2459 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2460 the value of sysUpTime.0 for the default context. 2462 2) If h.sessionID does not correspond to a currently 2463 established session with this subagent, the 2464 agentx-Response-PDU is sent in reply with res.error set 2465 to `notOpen'. 2467 3) Otherwise, the master agent closes the AgentX session 2468 as described below. No agentx-Response-PDU is sent. 2470 - All MIB regions that have been registered during this session 2471 are unregistered, as described in 7.1.6. 2473 - All index values allocated during this session are freed, as 2474 described in section 7.1.4. 2476 - All sysORID values that were registered during this session 2477 are removed, as described in section 7.1.8. 2479 The master agent does not maintain state for closed sessions. 2480 If a subagent wishes to re-establish a session after receiving 2481 an agentx-Close-PDU, it needs to re-register MIB regions, agent 2482 capabilities, etc. 2484 7.1.10. Detecting Connection Loss 2486 If a master agent is able to detect (from the underlying transport) 2487 that a subagent cannot receive AgentX PDUs, it should close all 2488 affected AgentX sessions as described in 7.1.9, step 3). 2490 7.1.11. Processing the agentx-Notify-PDU 2492 A subagent sending SNMPv1 trap information must map this into 2493 (minimally) a value of snmpTrapOID.0, as described in 3.1.2 of 2494 RFC 1908 [8]. 2496 The master agent processes the agentx-Notify-PDU as follows: 2498 1) If h.sessionID does not correspond to a currently 2499 established session with this subagent, an 2500 agentx-Response-PDU is sent in reply with res.error set 2501 to `notOpen', and res.sysUpTime set to the value of 2502 sysUpTime.0 for the indicated context. 2504 2) The VarBindList is parsed. If it does not contain a value for 2505 sysUpTime.0, the master agent supplies the current value of 2506 sysUpTime.0 for the indicated context. If the next VarBind 2507 (either the first or second VarBind; see section 6.2.10.1) 2508 is not snmpTrapOID.0, the master agent ceases further processing 2509 of the notification. 2511 3) Notifications are sent according to the implementation-specific 2512 configuration of the master agent. 2514 If SNMPv1 Trap PDUs are generated, the recommended mapping is as 2515 described in RFC 2089 [9]. 2517 Except in the case of a `notOpen' error as described in 2518 (1) above, no agentx-Response-PDU is sent to the subagent 2519 when the master agent finishes processing the notification. 2521 7.1.12. Processing the agentx-Ping-PDU 2523 When the master agent receives an agentx-Ping-PDU, it processes it 2524 as follows: 2526 1) An agentx-Response-PDU is created and res.sysUpTime is set to 2527 the value of sysUpTime.0 for the default context. 2529 2) If h.sessionID does not correspond to a currently 2530 established session with this subagent, the 2531 agentx-Response-PDU is sent in reply with res.error set 2532 to `notOpen'. 2534 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2535 supports only a default context, the agentx-Response-PDU is 2536 returned with res.error set to `unsupportedContext'. 2537 Otherwise: The value of res.sysUpTime is set to the value 2538 of sysUpTime.0 for the indicated context. 2540 4) The agentx-Response-PDU is sent, with res.error set to 2541 `noError'. 2543 If a subagent does not receive a response to its pings, or if it 2544 is able to detect (from the underlying transport) that the 2545 master agent is not able to receive AgentX messages, then it 2546 eventually must initiate a new AgentX session, re-register its 2547 regions, etc. 2549 7.2. Processing Received SNMP Protocol Messages 2551 When an SNMP GetRequest, GetNextRequest, GetBulkRequest, or 2552 SetRequest protocol message is received by the master agent, the 2553 master agent applies its access control policy. 2555 In particular, for SNMPv1 or SNMPv2c PDUs, the master agent 2556 applies the Elements of Procedure defined in section 4.1 of RFC 2557 1157 [6] that apply to receiving entities. (For other versions 2558 of SNMP, the master agent applies the access control policy 2559 defined in the Elements of Procedure for those versions.) 2561 In the SNMPv1 or v2c frameworks, the master agent uses the community 2562 string as an index into a local repository of configuration 2563 information that may include community profiles or more complex 2564 context information. 2566 If application of the access control policy results in a valid SNMP 2567 request PDU, then an SNMP Response-PDU is constructed from 2568 information gathered in the exchange of AgentX PDUs between the 2569 master agent and one or more subagents. Upon receipt and initial 2570 validation of an SNMP request PDU, a master agent uses the 2571 procedures described below to dispatch AgentX PDUs to the proper 2572 subagents, marshal the subagent responses, and construct an SNMP 2573 response PDU. 2575 7.2.1. Dispatching AgentX PDUs 2577 Upon receipt and initial validation of an SNMP request PDU, a master 2578 agent uses the procedures described below to dispatch AgentX PDUs to 2579 the proper subagents. 2581 Note: In the following procedures, an object identifier is said to 2582 be "contained" within an OID range when both of the following 2583 are true: 2585 - The object identifier does not lexicographically precede 2586 the range. 2588 - The object identifier lexicographically precedes the end 2589 of the range. 2591 General Rules of Procedure 2593 While processing a particular SNMP request, the master agent may 2594 send one or more AgentX PDUs to one or more subagents. The 2595 following rules of procedure apply in general to the AgentX master 2596 agent. PDU-specific rules are listed in the applicable sections. 2598 1) Honoring the registry 2600 Because AgentX supports overlapping registrations, it is 2601 possible for the master agent to obtain a value for a requested 2602 varbind from within multiple registered MIB regions. 2604 The master agent must ensure that the value (or exception) 2605 actually returned in the SNMP response PDU is taken from the 2606 authoritative region (as defined in section 7.1.5.1). 2608 2) GetNext and GetBulk Processing 2610 The master agent may choose to send agentx-Get-PDUs while 2611 servicing an SNMP GetNextRequest-PDU. The master agent may 2612 choose to send agentx-Get-PDUs or agentx-GetNext-PDUs while 2613 servicing an SNMP GetBulkRequest-PDU. One possible reason for 2614 this would be if the current iteration has targeted 2615 instance-level registrations. 2617 The master agent may or may not choose to "scope" the possible 2618 instances returned by a subagent through the use of the ending 2619 OID in the SearchRange. A typical usage of this field would be 2620 to encode the ending OID with the registered MIB region that is 2621 the first lexicographical successor to the target OID range, 2622 and that was not registered by the target subagent. 2624 Regardless of this choice, rule (1) must be obeyed. 2626 The master agent may require multiple request-response 2627 iterations on the same subagent session, to determine the 2628 final value of all requested variables. 2630 All AgentX PDUs sent on the session while processing a given 2631 SNMP request must contain identical values of transactionID. 2632 Each different SNMP request processed by the master agent must 2633 present a unique value of transactionID (within the limits of 2634 the 32-bit field) to the session. 2636 3) Number and order of variables sent per AgentX PDU 2638 For Get/GetNext/GetBulk operations, at any stage of the 2639 possibly iterative process, the master agent may need to 2640 dispatch several SearchRanges to a particular subagent 2641 session. The master agent may send one, some, or all 2642 of the SearchRanges in a single AgentX PDU. 2644 The master agent must ensure that the correct contents 2645 and ordering of the VarBindList in the SNMP Response-PDU 2646 are maintained. 2648 The following rules govern the number of VarBinds in a 2649 given AgentX PDU: 2651 a) The subagent must support processing of AgentX PDUs 2652 with multiple VarBinds. 2654 b) When processing an SNMP Set request, the master agent 2655 must send all of the VarBinds applicable to a particular 2656 subagent session in a single Test/Set transaction. 2658 c) When processing an SNMP Get, GetNext, or GetBulk request, 2659 the master agent may send a single AgentX PDU to the 2660 subagent with all applicable VarBinds, or multiple 2661 PDUs with single VarBinds, or something in between 2662 those extremes. The determination of which method to 2663 use in a particular case is implementation-specific. 2665 4) Timeout Values 2667 The master agent chooses a timeout value for each MIB region 2668 being queried, which is 2670 a) the value specified during registration of the MIB region, 2671 if it was non-zero 2673 b) otherwise, the value specified during establishment of 2674 the session in which this region was subsequently 2675 registered, if that value was non-zero. 2677 c) otherwise, the master agent's default value 2679 When an AgentX PDU that references multiple MIB regions is 2680 dispatched, the timeout value used for the PDU is the maximum 2681 value of the timeouts so determined for each of the referenced 2682 MIB regions. 2684 5) Context 2686 If the master agent has determined that a specific non-default 2687 context is associated with the request PDU, that context is 2688 encoded into the AgentX PDU's context field and the 2689 NON_DEFAULT_CONTEXT bit is set in h.flags. 2691 Otherwise, no context Octet String is added to the PDU, and the 2692 NON_DEFAULT_CONTEXT bit is cleared. 2694 7.2.1.1. agentx-Get-PDU 2696 Each variable binding in the SNMP request PDU is processed as 2697 follows: 2699 (1) Identify the target OID range. 2701 Within a lexicographically ordered set of OID ranges, valid for 2702 the indicated context, locate the region that contains the 2703 binding's name. 2705 (2) If no such OID range exists the variable binding is not 2706 processed further, and its value is set to `noSuchObject'. 2708 (3) Identify the subagent session in which this region was 2709 registered, termed the target session. 2711 (4) If this is the first variable binding to be dispatched over 2712 the target session in a request-response exchange entailed 2713 in the processing of this management request: 2715 - Create an agentx-Get-PDU for this session, with the header 2716 fields initialized as described above (see 6.1 AgentX PDU 2717 Header). 2719 (5) Add a SearchRange to the end of the target session's PDU 2720 for this variable binding. 2722 - The variable binding's name is encoded into the starting OID. 2724 - The ending OID is encoded as null. 2726 7.2.1.2. agentx-GetNext-PDU 2728 Each variable binding in the SNMP request PDU is processed as 2729 follows: 2731 (1) Identify the target OID range. 2733 Within a lexicographically ordered set of OID ranges, valid for 2734 the indicated context, locate 2736 a) the OID range that contains the variable binding's name and 2737 is not a fully qualified instance, or 2739 b) the OID range that is the first lexicographical successor to 2740 the variable binding's name. 2742 (2) If no such OID range exists the variable binding is not processed 2743 further, and its value is set to `endOfMibView'. 2745 (3) Identify the subagent session in which this region was 2746 registered, termed the target session. 2748 (4) If this is the first variable binding to be dispatched over the 2749 target session in a request-response exchange entailed in the 2750 processing of this management request: 2752 - Create an agentx-GetNext-PDU for the session, with 2753 the header fields initialized as described above (see 6.1 2754 AgentX PDU Header). 2756 (5) Add a SearchRange to the end of the target session's 2757 agentx-GetNext-PDU for this variable binding. 2759 - if (1a) applies, the variable binding's name is encoded 2760 into the starting OID, and the OID's "include" field 2761 is set to 0. 2763 - if (1b) applies, the target OID is encoded into the starting 2764 OID, and its "include" field is set to 1. 2766 7.2.1.3. agentx-GetBulk-PDU 2768 (Note: The outline of the following procedure is based closely on 2769 section 4.2.3, "The GetBulkRequest-PDU" of RFC 1905 [4]. Please 2770 refer to it for details on the format of the SNMP GetBulkRequest-PDU 2771 itself.) 2773 Each variable binding in the request PDU is processed as follows: 2775 (1) Identify the target OID range and target session, exactly as 2776 described for the agentx-GetNext-PDU (see 7.2.1.2). 2778 (2) If this is the first variable binding to be dispatched over the 2779 target session in a request-response exchange entailed in the 2780 processing of this management request: 2782 - Create an agentx-GetBulk-PDU for the session, with 2783 the header fields initialized as described above (see 6.1 2784 AgentX PDU Header). 2786 (3) Add a SearchRange to the end of the target session's 2787 agentx-GetBulk-PDU for this variable binding, as described 2788 for the agentx-GetNext-PDU. If the variable binding was 2789 a non-repeater in the original request PDU, it must be a 2790 non-repeater in the agentx-GetBulk-PDU. 2792 The value of g.max_repetitions in the agentx-GetBulk-PDU may be less 2793 than (but not greater than) the value in the original request PDU. 2795 The master agent may make such alterations due to simple sanity 2796 checking, optimizations for the current iteration based on the 2797 registry, the maximum possible size of a potential Response-PDU, 2798 known constraints of the AgentX transport, or any other 2799 implementation-specific constraint. 2801 7.2.1.4. agentx-TestSet-PDU 2803 AgentX employs test-commit-undo-cleanup phases 2804 to achieve "as if simultaneous" semantics of the SNMP SetRequest-PDU 2805 within the extensible agent. The initial phase involves 2806 the agentx-TestSet-PDU. 2808 Each variable binding in the request PDU is processed in order, as 2809 follows: 2811 (1) Identify the target OID range. 2813 Within a lexicographically ordered set of OID ranges, valid for 2814 the indicated context, locate the range that contains the 2815 variable binding's name. 2817 (2) If no such OID range exists, this variable binding fails with an 2818 error of `notWritable'. Processing is complete for this 2819 request. 2821 (3) Identify the single subagent responsible for this OID range, 2822 termed the target subagent, and the applicable session, 2823 termed the target session. 2825 (4) If this is the first variable binding to be dispatched over 2826 the target session in a request-response exchange entailed 2827 in the processing of this management request: 2829 - create an agentx-TestSet-PDU for the session, with the 2830 header fields initialized as described above (see 6.1 2831 AgentX PDU Header). 2833 (5) Add a VarBind to the end of the target session's PDU 2834 for this variable binding, as described in section 5.4. 2836 Note that all VarBinds applicable to a given session must be 2837 sent in a single agentx-TestSet-PDU. 2839 7.2.1.5. Dispatch 2841 A timeout value is calculated for each PDU to be sent, which is the 2842 maximum value of the timeouts determined for each of the PDU's 2843 SearchRanges (as described above in 7.2.1 Dispatching AgentX PDUs, 2844 item 4). Each pending PDU is mapped (via its h.sessionID value) to a 2845 particular transport domain/endpoint, as described in section 8 2846 (Transport Mappings). 2848 7.2.2. Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs 2850 A conformant AgentX subagent must support the agentx-Get, -GetNext, 2851 and -GetBulk PDUs, and must support multiple variables being supplied 2852 in each PDU. 2854 When a subagent receives an agentx-Get-, GetNext-, or GetBulk-PDU, it 2855 performs the indicated management operations and returns an 2856 agentx-Response-PDU. 2858 The agentx-Response-PDU header fields are identical to the received 2859 request PDU except that, at the start of processing, the subagent 2860 initializes h.type to Response, res.error to `noError', 2861 res.index to 0, and the VarBindList to null. 2863 Each SearchRange in the request PDU's SearchRangeList is processed as 2864 described below, and a VarBind is added in the corresponding 2865 location of the agentx-Response-PDU's VarbindList. If processing 2866 should fail for any reason not described below, res.error is set to 2867 `genErr', res.index to the index of the failed SearchRange, 2868 the VarBindList is reset to null, and this agentx-Response-PDU is 2869 returned to the master agent. 2871 7.2.2.1. Subagent Processing of the agentx-Get-PDU 2873 Upon the subagent's receipt of an agentx-Get-PDU, each SearchRange 2874 in the request is processed as follows: 2876 (1) The starting OID is copied to v.name. 2878 (2) If the starting OID exactly matches the name of a 2879 variable instantiated by this subagent within the indicated 2880 context and session, v.type and v.data are encoded to represent 2881 the variable's syntax and value, as described in section 5.4, 2882 Value Representation. 2884 (3) Otherwise, if the starting OID does not match the object 2885 identifier prefix of any variable instantiated within the 2886 indicated context and session, the VarBind is set to 2887 `noSuchObject', in the manner described in section 5.4, 2888 Value Representation. 2890 (4) Otherwise, the VarBind is set to `noSuchInstance' 2891 in the manner described in section 5.4, Value Representation. 2893 7.2.2.2. Subagent Processing of the agentx-GetNext-PDU 2895 Upon the subagent's receipt of an agentx-GetNext-PDU, each 2896 SearchRange in the request is processed as follows: 2898 (1) The subagent searches for a variable within the 2899 lexicographically ordered list of variable names for all 2900 variables it instantiates (without regard to registration of 2901 regions) within the indicated context and session, for which 2902 the following are all true: 2904 - if the "include" field of the starting OID is 0, the 2905 variable's name is the closest lexicographical successor to 2906 the starting OID. 2908 - if the "include" field of the starting OID is 1, the 2909 variable's name is either equal to, or the closest 2910 lexicographical successor to, the starting OID. 2912 - If the ending OID is not null, the variable's name 2913 lexicographically precedes the ending OID. 2915 If all of these conditions are met, v.name is set to the 2916 located variable's name. v.type and v.data are encoded to 2917 represent the variable's syntax and value, as described in 2918 section 5.4, Value Representation. 2920 (2) If no such variable exists, v.name is set to the starting OID, 2921 and the VarBind is set to `endOfMibView', in the manner described 2922 in section 5.4, Value Representation. 2924 7.2.2.3. Subagent Processing of the agentx-GetBulk-PDU 2926 A maximum of N + (M * R) VarBinds are returned, where 2928 N equals g.non_repeaters, 2929 M equals g.max_repetitions, and 2931 R is (number of SearchRanges in the GetBulk request) - N. 2933 The first N SearchRanges are processed exactly as for the 2934 agentx-GetNext-PDU. 2936 If M and R are both non-zero, the remaining R SearchRanges are 2937 processed iteratively to produce potentially many VarBinds. For 2938 each iteration i, such that i is greater than zero and less than or 2939 equal to M, and for each repeated SearchRange s, such that s is 2940 greater than zero and less than or equal to R, the 2941 (N+((i-1)*R)+s)-th VarBind is added to the agentx-Response-PDU 2942 as follows: 2944 1) The subagent searches for a variable within the 2945 lexicographically ordered list of variable names for all 2946 variables it instantiates (without regard to registration of 2947 regions) within the indicated context and session, for which 2948 the following are all true: 2950 - The variable's name is the (i)-th lexicographical successor 2951 to the (N+s)-th requested OID. 2953 (Note that if i is 0 and the "include" field is 1, the 2954 variable's name may be equivalent to, or the first 2955 lexicographical successor to, the (N+s)-th requested OID.) 2957 - If the ending OID is not null, the variable's name 2958 lexicographically precedes the ending OID. 2960 If all of these conditions are met, v.name is set to the 2961 located variable's name. v.type and v.data are 2962 encoded to represent the variable's syntax and value, as 2963 described in section 5.4, Value Representation. 2965 2) If no such variable exists, the VarBind is set to 2966 `endOfMibView' as described in section 5.4, Value 2967 Representation. v.name is set to v.name of the 2968 (N+((i-2)*R)+s)-th VarBind unless i is currently 1, in which 2969 case it is set to the value of the starting OID in the (N+s)-th 2970 SearchRange. 2972 Note that further iterative processing should stop if 2974 - For any iteration i, all s values of v.type are 2975 `endOfMibView'. 2977 - An AgentX transport constraint or other 2978 implementation-specific constraint is reached. 2980 7.2.3. Subagent Processing of agentx-TestSet, -CommitSet, -UndoSet, 2981 -CleanupSet-PDUs 2983 A conformant AgentX subagent must support the agentx-TestSet, 2984 -CommitSet, -UndoSet, and -CleanupSet PDUs, and must support multiple 2985 variables being supplied in each PDU. 2987 These four PDUs are used to collectively perform the indicated 2988 management operation. An agentx-Response-PDU is sent in reply to 2989 each of the PDUs, to inform the master agent of the state of the 2990 operation. 2992 The agentx-Response-PDU header fields are identical to the received 2993 request PDU except that, at the start of processing, the subagent 2994 initializes h.type to Response, res.error to `noError', and 2995 res.index to 0. 2997 These Response-PDUs do not contain a VarBindList. 2999 7.2.3.1. Subagent Processing of the agentx-TestSet-PDU 3001 Upon the subagent's receipt of an agentx-TestSet-PDU, each VarBind 3002 in the PDU is validated until they are all successful, or until one 3003 fails, as described in section 4.2.5 of RFC 1905 [4]. The subagent 3004 validates variables with respect to the context and session 3005 indicated in the testSet-PDU. 3007 If each VarBind is successful, the subagent has a further 3008 responsibility to ensure the availability of all resources (memory, 3009 write access, etc.) required for successfully carrying out a 3010 subsequent agentx-CommitSet operation. If this cannot be guaranteed, 3011 the subagent should set res.error to `resourceUnavailable'. 3013 As a result of this validation step, an agentx-Response-PDU 3014 is sent in reply whose res.error field is set to one of the 3015 following (SNMPv2 SMI) values: 3017 noError (0), 3018 genErr (5), 3019 noAccess (6), 3020 wrongType (7), 3021 wrongLength (8), 3022 wrongEncoding (9), 3023 wrongValue (10), 3024 noCreation (11), 3025 inconsistentValue (12), 3026 resourceUnavailable (13), 3027 notWritable (17), 3028 inconsistentName (18) 3030 If this value is not `noError', the res.index field must be 3031 set to the index of the VarBind for which validation failed. 3033 Implementation of rigorous validation code may be one of the 3034 most demanding aspects of subagent development. Implementors 3035 are strongly encouraged to do this right, so as to avoid if at 3036 all possible the extensible agent's having to return `commitFailed' 3037 or `undoFailed' during subsequent processing. 3039 7.2.3.2. Subagent Processing of the agentx-CommitSet-PDU 3041 The agentx-CommitSet-PDU indicates that the subagent should actually 3042 perform (as described in the post-validation sections of 4.2.5 of 3043 RFC 1905 [4]) the management operation indicated by the previous 3044 TestSet-PDU. 3045 After carrying out the management operation, the subagent sends in 3046 reply an agentx-Response-PDU whose res.error field is set to one of 3047 the following (SNMPv2 SMI) values: 3049 noError (0), 3050 commitFailed (14) 3052 If this value is `commitFailed', the res.index field must be 3053 set to the index of the VarBind for which the operation failed. 3054 Otherwise res.index is set to 0. 3056 7.2.3.3. Subagent Processing of the agentx-UndoSet-PDU 3058 The agentx-UndoSet-PDU indicates that the subagent should undo 3059 the management operation requested in a preceding CommitSet-PDU. 3060 The undo process is as described in section 4.2.5 of RFC 1905 3061 [4]. 3063 After carrying out the undo process, the subagent sends in reply an 3064 agentx-Response-PDU whose res.index field is set to 0, and whose 3065 res.error field is set to one of the following (SNMPv2 SMI) values: 3067 noError (0), 3068 undoFailed (15) 3070 If this value is `undoFailed', the res.index field must be 3071 set to the index of the VarBind for which the operation failed. 3072 Otherwise res.index is set to 0. 3074 This PDU also signals the end of processing of the management 3075 operation initiated by the previous TestSet-PDU. The subagent 3076 should release resources, etc. as described in section 7.2.3.4. 3078 7.2.3.4. Subagent Processing of the agentx-CleanupSet-PDU 3080 The agentx-CleanupSet-PDU signals the end of processing of the 3081 management operation requested in the previous TestSet-PDU. This 3082 is an indication to the subagent that it may now release any 3083 resources it may have reserved in order to carry out the management 3084 request. 3086 No response is sent by the subagent. 3088 7.2.4. Master Agent Processing of AgentX Responses 3090 The master agent now marshals all subagent AgentX response PDUs and 3091 builds an SNMP response PDU. In the next several subsections, the 3092 initial processing of all subagent AgentX response PDUs is 3093 described, followed by descriptions of subsequent processing 3094 for each specific subagent Response. 3096 7.2.4.1. Common Processing of All AgentX Response PDUs 3098 1) If a subagent does not respond within the timeout interval for 3099 this dispatch, it is treated as if the subagent had returned 3100 `genErr' and processed as described below. 3102 A timeout may be due to a variety of reasons, and does 3103 not necessarily denote a failed or malfunctioning 3104 subagent. As such, the master agent's response to a 3105 subagent timeout is implementation-specific, but with the 3106 following constraint: 3108 A subagent that times out on three consecutive requests 3109 is considered unable to respond, and the master agent 3110 must close the AgentX session as described in 3111 7.1.9, step (2). 3113 2) Otherwise, the h.packetID, h.sessionID, and h.transactionID 3114 fields of the AgentX response PDU are used to correlate subagent 3115 responses. If the response does not pertain to this SNMP 3116 operation, it is ignored. 3118 3) Otherwise, the responses are processed jointly to form the SNMP 3119 response PDU. 3121 7.2.4.2. Processing of Responses to agentx-Get-PDUs 3123 After common processing of the subagent's response to an 3124 agentx-Get-PDU (see 7.2.4.1 above), processing continues with 3125 the following steps: 3127 1) For any received AgentX response PDU, if res.error is not 3128 `noError', the SNMP response PDU's error code is set to this 3129 value, and its error index to the index of the variable binding 3130 corresponding to the failed VarBind in the subagent's 3131 AgentX response PDU. 3133 All other AgentX response PDUs received due to processing this 3134 SNMP request are ignored. Processing is complete; the SNMP 3135 Response PDU is ready to be sent (see section 7.2.5, Sending 3136 the SNMP Response-PDU). 3138 2) Otherwise, the content of each VarBind in the AgentX response PDU 3139 is used to update the corresponding variable binding in the SNMP 3140 Response-PDU. 3142 7.2.4.3. Processing of Responses to agentx-GetNext-PDU and 3143 agentx-GetBulk-PDU 3145 After common processing of the subagent's response to an 3146 agentx-GetNext-PDU or agentx-GetBulk-PDU (see 7.2.4.1 above), 3147 processing continues with the following steps: 3149 1) For any received AgentX response PDU, if res.error is not 3150 `noError', the SNMP response PDU's error code is set to this 3151 value, and its error index to the index of the VarBind 3152 corresponding to the failed VarBind in the subagent's 3153 AgentX response PDU. 3155 All other AgentX response PDUs received due to processing this 3156 SNMP request are ignored. Processing is complete; the SNMP 3157 response PDU is ready to be sent (see section 7.2.5, Sending 3158 the SNMP Response PDU). 3160 2) Otherwise, the content of each VarBind in the AgentX response 3161 PDU is used to update the corresponding VarBind in the SNMP 3162 response PDU. 3164 After all expected AgentX response PDUs have been processed, if 3165 any VarBinds still contain the value `endOfMibView' in their 3166 v.type fields, processing must continue: 3168 3) A new iteration of AgentX request dispatching is initiated 3169 (as described in section 7.2.1.1), in which only those 3170 VarBinds whose v.type is `endOfMibView' are processed. 3172 4) For each such VarBind, a target OID range is identified 3173 which is the lexicographical successor to the target OID 3174 range for this VarBind on the last iteration. The target 3175 subagent is the one that registered the target OID range. 3176 The target session is the one in which the target OID range 3177 was registered. 3179 If an agentx-GetNext- or GetBulk-PDU is being dispatched, 3180 the starting OID in the SearchRanges is set to the target 3181 OID range, and its "include" field is set to 1. 3183 5) The value of transactionID must be identical to the value 3184 used during the previous iteration. 3186 6) The AgentX PDUs are sent to the subagent(s), and the responses 3187 are received and processed according to the steps described in 3188 section 7.2.4. 3190 7) This process continues iteratively until a complete SNMP 3191 Response-PDU has been built, or until there remain no 3192 target OID range lexicographical successors. 3194 7.2.4.4. Processing of Responses to agentx-TestSet-PDUs 3196 After common processing of the subagent's response to an 3197 agentx-TestSet-PDU (see 7.2.4.1 above), processing continues with 3198 the further exchange of AgentX PDUs. The value of h.transactionID 3199 in the agentx-CommitSet, -UndoSet, and -CleanupSet-PDUs must be 3200 identical to the value sent in the testSet-PDU. 3202 The state transitions and PDU sequences are depicted in section 7.3. 3204 1) If any target subagent's response is not `noError', all other 3205 agentx-Response-PDUs received due to processing this SNMP 3206 request are ignored. 3208 An agentx-CleanupSet-PDU is sent to each target subagent that has 3209 been sent a agentx-TestSet-PDU. 3211 Processing is complete; the SNMP response PDU is constructed as 3212 described below in 7.2.4.6, step (2). 3214 2) Otherwise an agentx-CommitSet-PDU is sent to each target 3215 subagent. 3217 7.2.4.5. Processing of Responses to agentx-CommitSet-PDUs 3219 After common processing of the subagent's response to an 3220 agentx-CommitSet-PDU (see 7.2.4.1 above), processing continues with 3221 the following steps: 3223 1) If any response is not `noError', all other 3224 agentx-Response-PDUs received due to processing this SNMP 3225 request are ignored. 3227 An agentx-UndoSet-PDU is sent to each target subagent that has 3228 been sent a agentx-CommitSet-PDU. All other subagents are sent a 3229 agentx-CleanupSet-PDU. 3231 2) Otherwise an agentx-CleanupSet-PDU is sent to each target 3232 subagent. Processing is complete; the SNMP response PDU is 3233 constructed as described below in 7.2.4.6, step (2). 3235 7.2.4.6. Processing of Responses to agentx-UndoSet-PDUs 3237 After common processing of the subagent's response to an 3238 agentx-UndoSet-PDU (see 7.2.4.1 above), processing continues with the 3239 following steps: 3241 1) If any response is not `noError' the SNMP response 3242 PDU's error code is set to this value, and its error index to the 3243 index of the VarBind corresponding to the failed VarBind 3244 in the agentx-TestSet-PDU. 3246 Otherwise the SNMP response PDU's error code is set to `noError' 3247 and its error index to 0. 3249 7.2.5. Sending the SNMP Response-PDU 3251 Once the processing described in sections 7.2.1 - 7.2.4 is 3252 complete, there is an SNMP response PDU available. The master agent 3253 now implements the Elements of Procedure for the applicable version 3254 of the SNMP protocol in order to encapsulate the PDU into a message, 3255 and transmit it to the originator of the SNMP management request. 3256 Note that this may involve altering the PDU contents (for instance, 3257 to replace the original VarBinds if an error condition is 3258 to be returned). 3260 The response PDU may also be altered in order to support the SNMP 3261 version 1 framework. In such cases the required mapping is that 3262 defined in RFC 2089 [9]. (Note in particular that the rules for 3263 handling Counter64 syntax may require re-sending AgentX GetBulk 3264 or GetNext PDUs until a VarBind of suitable syntax is returned.) 3266 7.2.6. MIB Views 3268 AgentX subagents are not aware of MIB views, since view information 3269 is not contained in AgentX PDUs. 3271 As stated above, the descriptions of procedures in section 7 of this 3272 memo are not intended to constrain the internal architecture of any 3273 conformant implementation. In particular, the master agent 3274 procedures described in sections 7.2.1 and 7.2.4 may be altered so 3275 as to optimize AgentX exchanges when implementing MIB views. 3277 Such optimizations are beyond the scope of this memo. But note that 3278 section 7.2.3 defines subagent behavior in such a way that alteration 3279 of SearchRanges may be used in such optimizations. 3281 7.3. State Transitions 3283 State diagrams are presented from the master agent's perspective 3284 for transport connection and session establishment, and from the 3285 subagent's perspective for Set transaction processing. 3287 7.3.1. Set Transaction States 3289 The following table presents, from the subagent's perspective, 3290 the state transitions involved in Set transaction processing: 3292 STATE 3293 +----------------+--------------+---------+--------+-------- 3294 | A | B | C | D | E 3295 | (Initial | TestOK | Commit | Test | Commit 3296 | State) | | OK | Fail | Fail 3297 | | | | | 3298 EVENT | | | | | 3299 ---------+----------------+--------------+---------+--------+-------- 3300 | 7.2.3.1 | | | | 3301 Receive | All varbinds | | | | 3302 TestSet | OK? | X | X | X | X 3303 PDU | Yes ->B | | | | 3304 | No ->D | | | | 3305 ---------+----------------+--------------+---------+--------+-------- 3306 | | 7.2.3.2 | | | 3307 Receive | | NoError? | | | 3308 Commit- | X | Yes ->C | X | X | X 3309 Set PDU | | No ->E | | | 3310 ---------+----------------+--------------+---------+--------+-------- 3311 Receive | | | 7.2.3.3 | |7.2.4.5 3312 UndoSet | X | X | ->done | X | ->done 3313 PDU | | | | | 3314 ---------+----------------+--------------+---------+--------+-------- 3315 Receive | | 7.2.4.4 | 7.2.3.4 |7.2.4.4 | 3316 Cleanup- | X | ->done | ->done | ->done | X 3317 Set PDU | | | | | 3318 ---------+----------------+--------------+---------+--------+-------- 3319 Session | | rollback | undo | | 3320 Loss | ->done | ->done | ->done | ->done | ->done 3321 ---------+----------------+--------------+---------+--------+-------- 3323 There are three possible sequences that a subagent may follow for a 3324 particular set transaction: 3326 1) TestSet CommitSet CleanupSet 3327 2) TestSet CommitSet UndoSet 3328 3) TestSet CleanupSet 3330 Note that a single PDU sequence may result in multiple paths through 3331 the FSM. For example, the sequence 3332 TestSet CommitSet UndoSet 3334 may walk through either of these two state sequences: 3336 (initial) TestOK CommitOK (done) 3337 (initial) TestOK CommitFail (done) 3339 7.3.2 Transport Connection States 3341 The following table presents, from the master agent's perspective, 3342 the state transitions involved in transport connection setup 3343 and teardown: 3345 STATE 3346 +--------------+-------------- 3347 | A | B 3348 | No transport | Transport 3349 | | connected 3350 | | 3351 EVENT | | 3352 ----------------+--------------+-------------- 3353 Transport | | 3354 connect | ->B | X 3355 indication | | 3356 ----------------+--------------+-------------- 3357 Receive | | if duplicate 3358 Open-PDU | | session id, 3359 | | reject, else 3360 | X | establish 3361 | | session 3362 | | 3363 | | ->B 3364 ----------------+--------------+-------------- 3365 Receive | | if matching 3366 Response-PDU | | session id, 3367 | | feed to that 3368 | X | session's FSM 3369 | | else ignore 3370 | | 3371 | | ->B 3372 ----------------+--------------+-------------- 3373 Receive other | | if matching 3374 PDUs | | session id, 3375 | | feed to that 3376 | X | session's FSM 3377 | | else reject 3378 | | 3379 | | ->B 3380 ----------------+--------------+-------------- 3381 Transport | |notify all 3382 disconnect | |sessions on 3383 indication | X |this transport 3384 | | 3385 | | ->A 3386 ----------------+--------------+-------------- 3388 7.3.3 Session States 3390 The following table presents, from the master agent's perspective, 3391 the state transitions involved in session setup and teardown: 3393 STATE 3394 +-------------+---------------- 3395 | A | B 3396 | No session | Session 3397 | | established 3398 EVENT | | 3399 ---------------+-------------+---------------- 3400 | 7.1.1 | 3401 Receive | | X 3402 Open PDU | ->B | 3403 ---------------+-------------+---------------- 3404 | | 7.1.9 3405 Receive | X | 3406 Close PDU | | ->A 3407 ---------------+-------------+---------------- 3408 Receive | | 7.1.5 3409 Register PDU | X | 3410 | | ->B 3411 ---------------+-------------+---------------- 3412 Receive | | 7.1.6 3413 Unregister | X | 3414 PDU | | ->B 3415 ---------------+-------------+---------------- 3416 Receive | | 3417 Get PDU | | 3418 GetNext PDU | | 3419 GetBulk PDU | X | X 3420 TestSet PDU | | 3421 CommitSet PDU | | 3422 UndoSet PDU | | 3423 CleanupSet PDU | | 3424 ---------------+-------------+---------------- 3425 Receive | | 7.1.11 3426 Notify PDU | X | 3427 | | ->B 3428 ---------------+-------------+---------------- 3429 Receive Ping | | 7.1.12 3430 PDU | X | 3431 | | ->B 3432 ---------------+-------------+---------------- 3433 Receive | | 7.1.2 3434 IndexAllocate | X | 3435 PDU | | ->B 3436 ---------------+-------------+---------------- 3437 (continued next page) 3438 ---------------+-------------+---------------- 3439 Receive | | 7.1.4 3440 IndexDeallocate| X | 3441 PDU | | ->B 3442 ---------------+-------------+---------------- 3443 Receive | | 7.1.7 3444 AddAgentxCaps | X | 3445 PDU | | ->B 3446 ---------------+-------------+---------------- 3447 Receive | | 7.1.8 3448 RemoveAgentxCap| X | 3449 PDU | | ->B 3450 ---------------+-------------+---------------- 3451 Receive | | 7.2.4 3452 Response PDU | X | 3453 | | ->B 3454 ---------------+-------------+---------------- 3455 Receive | | 3456 Other PDU | X | X 3457 ---------------+-------------+---------------- 3459 8. Transport Mappings 3461 The same AgentX PDU formats, encodings, and elements of procedure 3462 are used regardless of the underlying transport. 3464 8.1. AgentX over TCP 3466 8.1.1. Well-known Values 3468 The master agent accepts TCP connection requests for the well-known 3469 port 705. Subagents connect to the master agent using this port 3470 number. 3472 8.1.2. Operation 3474 Once a TCP connection has been established, the AgentX peers use 3475 this connection to carry all AgentX PDUs. Multiple AgentX sessions 3476 may be established using the same TCP connection. AgentX PDUs are 3477 sent within an AgentX session. AgentX peers are responsible for 3478 mapping the h.sessionID to a particular TCP connection. 3480 All AgentX PDUs are presented individually to the TCP, to be sent as 3481 the data portion of a TCP PDU. 3483 8.2. AgentX over UNIX-domain Sockets 3485 Many (BSD-derived) implementations of the UNIX operating system 3486 support the UNIX pathname address family (AF_UNIX) for socket 3487 communications. This provides a convenient method of sending and 3488 receiving data between processes on the same host. 3490 Mapping AgentX to this transport is useful for environments that 3492 - wish to guarantee subagents are running on the same 3493 managed node as the master agent, and where 3495 - sockets provide better performance than TCP or UDP, 3496 especially in the presence of heavy network I/O 3498 8.2.1. Well-known Values 3500 The master agent creates a well-known UNIX-domain socket endpoint 3501 called "/var/agentx/master". (It may create other, implementation- 3502 specific endpoints.) 3504 This endpoint name uses the character set encoding native to the 3505 managed node, and represents a UNIX-domain stream (SOCK_STREAM) 3506 socket. 3508 8.2.2. Operation 3510 Once a connection has been established, the AgentX peers use 3511 this connection to carry all AgentX PDUs. 3513 Multiple AgentX sessions may be established using the same 3514 connection. AgentX PDUs are sent within an AgentX session. AgentX 3515 peers are responsible for mapping the h.sessionID to a particular 3516 connection. 3518 All AgentX PDUs are presented individually to the socket layer, to 3519 be sent in the data stream. 3521 9. Security Considerations 3523 This memo defines a protocol between two processing entities, 3524 one of which (the master agent) is assumed to perform 3525 authentication of received SNMP requests and to control access 3526 to management information. The master agent performs these 3527 security operations independently of the other processing 3528 entity (the subagent). 3530 Security considerations require three questions to be answered: 3532 1. Is a particular subagent allowed to initiate a session with a 3533 particular master agent? 3535 2. During an AgentX session, is any SNMP security-related 3536 information (for example, community names) passed from the 3537 master agent to the subagent? 3539 3. During an AgentX session, what part of the MIB tree is this 3540 subagent allowed to register? 3542 The answer to the third question is: A subagent can register any 3543 subtree (subject to AgentX elements of procedure, section 7.1.5). 3544 Currently there is no access control mechanism 3545 defined in AgentX. A concern here is that a malicious subagent 3546 that registers an unauthorized "sensitive" subtree, could see 3547 modification requests to those objects, or by giving its own 3548 clever answer to NMS queries, could cause the NMS to do something 3549 that leads to information disclosure or other damage. 3551 The answer to the second question is: No. 3553 Now we can answer the first question. 3554 AgentX does not contain a mechanism for authorizing/refusing session 3555 initiations. Thus, controlling subagent access to the master 3556 agent may only be done at a lower layer (e.g., transport). 3558 An AgentX subagent can connect to a master agent 3559 using either a network transport mechanism (e.g., TCP), or a "local" 3560 mechanism (e.g., shared memory, named pipes). 3562 In the case where a local transport mechanism is used and both 3563 subagent and master agent are running on the same host, connection 3564 authorization can be delegated to the operating system features. 3565 The answer to the first security question then becomes: 3566 "If and only if the subagent has sufficient privileges, then the 3567 operating system will allow the connection". 3569 If a network transport is used, currently there is no inherent 3570 security. Transport Layer Security or SSL could be used 3571 to control subagent connections, but that is beyond the scope 3572 of this document. 3574 Thus it is recommended that subagents always run on the same 3575 host as the master agent and that operating system features be 3576 used to ensure that only properly authorized subagents 3577 can establish connections to the master agent. 3579 10. Acknowledgements 3581 The initial draft of this memo was heavily influenced by the DPI 3582 2.0 specification RFC 1592 [7]. 3584 This document was produced by the IETF Agent Extensibility 3585 (AgentX) Working Group, and benefited especially from the 3586 contributions of the following working group members: 3588 David Battle, Uri Blumenthal, Jeff Case, Maria Greene, 3589 Dave Keeney, Harmen van der Linde, Bob Natale, Randy Presuhn, 3590 Aleksey Romanov, Don Ryan, and Juergen Schoenwaelder. 3592 The AgentX Working Group is chaired by: 3594 Bob Natale 3595 ACE*COMM Corporation 3596 704 Quince Orchard Road 3597 Gaithersburg MD 20878 3599 Phone: +1-301-721-3000 3600 Fax: +1-301-721-3001 3601 EMail: bnatale@acecomm.com 3603 11. Authors' and Editor's Addresses 3605 Mike Daniele 3606 Digital Equipment Corporation 3607 110 Spit Brook Rd 3608 Nashua, NH 03062 3610 Phone: +1-603-881-1423 3611 EMail: daniele@zk3.dec.com 3613 Bert Wijnen 3614 IBM Professional Services 3615 Watsonweg 2 3616 1423 ND Uithoorn 3617 The Netherlands 3619 Phone: +31-79-322-8316 3620 EMail: wijnen@vnet.ibm.com 3622 Dale Francisco (editor) 3623 Cisco Systems 3624 150 Castilian Dr 3625 Goleta CA 93117 3627 Phone: +1-805-961-3642 3628 Fax: +1-805-961-3600 3629 EMail: dfrancis@cisco.com 3631 12. References 3633 [1] Information processing systems - Open Systems Interconnection - 3634 Specification of Abstract Syntax Notation One (ASN.1), 3635 International Organization for Standardization. International 3636 Standard 8824, (December, 1987). 3638 [2] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3639 S. Waldbusser, "Structure of Management Information for Version 2 3640 of the Simple Network Management Protocol (SNMPv2)", RFC 1902, 3641 January 1996. 3643 [3] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3644 S. Waldbusser, "Textual Conventions for Version 2 of the Simple 3645 Network Management Protocol (SNMPv2)", RFC 1903, January 1996. 3647 [4] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3648 S. Waldbusser, "Protocol Operations for Version 2 of the Simple 3649 Network Management Protocol (SNMPv2)", RFC 1905, January 1996. 3651 [5] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3652 S. Waldbusser, "Management Information Base for Version 2 of the 3653 Simple Network Management Protocol (SNMPv2)", RFC 1907, 3654 January 1996. 3656 [6] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network 3657 Management Protocol", STD 15, RFC 1157, SNMP Research, Performance 3658 Systems International, MIT Laboratory for Computer Science, May 3659 1990. 3661 [7] Wijnen, B., Carpenter, G., Curran, K., Sehgal, A., and G. Waters, 3662 "Simple Network Management Protocol: Distributed Protocol 3663 Interface, Version 2.0", RFC 1592, T.J. Watson Research Center, 3664 IBM Corp., Bell Northern Research, Ltd., March 1994. 3666 [8] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3667 S. Waldbusser, "Coexistence between Version 1 and Version 2 of the 3668 Internet-standard Network Management Framework", RFC 1908, 3669 January 1996. 3671 [9] Wijnen, B., and Levi, D., "V2ToV1: Mapping SNMPv2 onto SNMPv1 3672 Within a Bilingual SNMP Agent", RFC 2089, T.J. Watson Research 3673 Center, IBM Corp., SNMP Research, Inc., January 1997. 3675 [10] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3676 S. Waldbusser, "Conformance Statements for Version 2 of the 3677 Simple Network Management Protocol (SNMPv2)", RFC 1904, 3678 January 1996. 3680 [11] Interfaces MIB Working Group, McCloghrie, K., and F. Kastenholz, 3681 "Evolution of the Interfaces Group of MIB-II", RFC 1573, 3682 January 1994. 3684 [12] FDDI MIB Working Group, J. Case, "FDDI Management Information 3685 Base", RFC 1285, January 1992. 3687 [13] Application MIB Working Group, Krupczak, C., and J. Saperia, 3688 "Definitions of Managed Objects for Applications", 3689 draft-ietf-applmib-sysapplmib-05.txt, 11 Nov 1996.