idnits 2.17.1 draft-ietf-agentx-ext-pro-01.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-27) 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 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 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 8 longer pages, the longest (page 2) being 59 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 9 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1112: '... (u.context) OPTIONAL...' RFC 2119 keyword, line 1173: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1259: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1286: '... (g.context) OPTIONAL...' RFC 2119 keyword, line 1317: '... (t.context) OPTIONAL...' (3 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.) -- The document date (November 26, 1996) is 10014 days in the past. Is this intentional? 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: 'TBD' on line 3059 -- Looks like a reference, but probably isn't: '1-22' on line 1941 -- Looks like a reference, but probably isn't: '1-4' on line 1949 -- Looks like a reference, but probably isn't: '1-5' on line 1962 -- 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) -- Possible downref: Non-RFC (?) normative reference: ref. '5' ** 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) -- Possible downref: Non-RFC (?) normative reference: ref. '9' ** 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: 19 errors (**), 0 flaws (~~), 4 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT 2 3 Expire in six months 5 Agent Extensibility (AgentX) Protocol 6 Version 1 8 November 26, 1996 10 Mike Daniele 11 Digital Equipment Corporation 12 daniele@zk3.dec.com 14 Bert Wijnen 15 T.J. Watson Research Center, IBM Corp. 16 wijnen@vnet.ibm.com 18 Dale Francisco (editor) 19 Cisco Systems, Inc. 20 dfrancis@cisco.com 22 Status of this Memo 24 This document is an Internet-Draft. Internet-Drafts are working 25 documents of the Internet Engineering Task Force (IETF), its areas, 26 and its working groups. Note that other groups may also distribute 27 working documents as Internet-Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six 30 months and may be updated, replaced, or obsoleted by other documents 31 at any time. It is inappropriate to use Internet-Drafts as 32 reference material or to cite them other than as ``work in 33 progress.'' 35 To learn the current status of any Internet-Draft, please check the 36 ``1id-abstracts.txt'' listing contained in the Internet-Drafts 37 Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net 38 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 39 Rim). 41 Daniele/Wijnen Expires May 1977 [Page 1] 42 Draft Agent Extensibility (AgentX) Protocol November 1996 44 1 Introduction......................................................5 46 2 The SNMP Framework................................................5 47 2.1 A Note on Terminology.........................................5 49 3 Extending the MIB.................................................6 50 3.1 Motivation for AgentX.........................................6 52 4 AgentX Framework..................................................7 53 4.1 AgentX Roles..................................................7 54 4.2 Design Goals for AgentX.......................................8 56 5 AgentX Encodings..................................................9 57 5.1 Object Identifier............................................10 58 5.2 SearchRange..................................................12 59 5.3 Octet String.................................................13 60 5.4 Value Representation.........................................14 62 6 Protocol Definitions.............................................16 63 6.1 AgentX PDU Header............................................16 64 6.1.1 Context..................................................17 65 6.2 AgentX PDUs..................................................18 66 6.2.1 The agentx-Open-PDU......................................18 67 6.2.1.1 agentx-Open-PDU Fields...............................18 68 6.2.2 The agentx-Close-PDU.....................................19 69 6.2.2.1 agentx-Close-PDU Fields..............................20 70 6.2.3 The agentx-Register-PDU..................................21 71 6.2.3.1 agentx-Register-PDU Fields...........................22 72 6.2.4 The agentx-Unregister-PDU................................24 73 6.2.4.1 agentx-Unregister-PDU Fields.........................25 74 6.2.5 The agentx-Get-PDU.......................................26 75 6.2.5.1 agentx-Get-PDU Fields................................27 76 6.2.6 The agentx-GetNext-PDU...................................28 77 6.2.7 The agentx-GetBulk-PDU...................................29 78 6.2.8 The agentx-TestSet-PDU...................................30 79 6.2.8.1 agentx-TestSet-PDU Fields............................31 80 6.2.9 The agentx-CommitSet, -UndoSet, -CleanupSet, 81 and -Ping PDUs...........................................31 82 6.2.10 The agentx-Notify-PDU...................................32 83 6.2.10.1 agentx-Notify-PDU Fields............................32 84 6.2.11 The agentx-IndexAllocate-PDU............................33 85 6.2.11.1 agentx-IndexAllocate-PDU fields.....................33 86 6.2.12 The agentx-IndexDeallocate-PDU..........................34 87 6.2.12.1 agentx-IndexDeallocate-PDU fields...................34 88 6.2.13 The agentx-AddAgentCaps-PDU.............................35 89 6.2.13.1 agentx-AddAgentCaps-PDU Fields......................36 90 6.2.14 The agentx-RemoveAgentCaps-PDU..........................37 91 6.2.14.1 agentx-RemoveAgentCaps-PDU Fields...................37 92 6.2.15 The agentx-Response-PDU.................................38 93 6.2.15.1 agentx-Response-PDU Fields..........................38 95 Daniele/Wijnen Expires May 1977 [Page 2] 96 Draft Agent Extensibility (AgentX) Protocol November 1996 98 7 Elements of Procedure............................................39 99 7.1 Processing AgentX Administrative Messages....................39 100 7.1.1 Processing the agentx-Open-PDU...........................39 101 7.1.2 Processing the agentx-IndexAllocate-PDU..................40 102 7.1.3 Using the agentx-IndexAllocate-PDU.......................42 103 7.1.4 Processing the agentx-IndexDeallocate-PDU................43 104 7.1.5 Processing the agentx-Register-PDU.......................44 105 7.1.5.1 Handling Duplicate OID Ranges........................46 106 7.1.6 Processing the agentx-Unregister-PDU.....................47 107 7.1.7 Processing the agentx-AddAgentCaps-PDU...................47 108 7.1.8 Processing the agentx-RemoveAgentCaps-PDU................48 109 7.1.9 Processing the agentx-Close-PDU..........................48 110 7.1.10 Detecting Connection Loss...............................48 111 7.1.11 Processing the agentx-Notify-PDU........................48 112 7.1.12 Processing the agentx-Ping-PDU..........................49 113 7.2 Processing Received SNMP Protocol Messages...................49 114 7.2.1 Dispatching AgentX PDUs..................................50 115 7.2.1.1 agentx-Get-PDU.......................................50 116 7.2.1.2 agentx-GetNext-PDU...................................51 117 7.2.1.3 agentx-GetBulk-PDU...................................53 118 7.2.1.4 agentx-TestSet-PDU...................................54 119 7.2.1.5 Dispatch.............................................55 120 7.2.2 Subagent Processing of agentx-Get, GetNext, 121 GetBulk-PDUs.............................................55 122 7.2.2.1 Subagent Processing of the agentx-Get-PDU............56 123 7.2.2.2 Subagent Processing of the 124 agentx-GetNext-PDU...................................56 125 7.2.2.3 Subagent Processing of the 126 agentx-GetBulk-PDU...................................57 127 7.2.3 Subagent Processing of agentx-TestSet, 128 -CommitSet, -UndoSet, -CleanupSet-PDUs...................58 129 7.2.3.1 Subagent Processing of the 130 agentx-TestSet-PDU...................................59 131 7.2.3.2 Subagent Processing of the 132 agentx-CommitSet-PDU.................................60 133 7.2.3.3 Subagent Processing of the 134 agentx-UndoSet-PDU...................................60 135 7.2.3.4 Subagent Processing of the 136 agentx-CleanupSet-PDU................................60 137 7.2.4 Master Agent Processing of AgentX Responses..............60 138 7.2.4.1 Common Processing of All AgentX Response 139 PDUs.................................................61 140 7.2.4.2 Processing of Responses to agentx-Get-PDUs...........61 141 7.2.4.3 Processing of Responses to 142 agentx-GetNext- and agentx-GetBulk-PDUs..............62 143 7.2.4.4 Processing of Responses to 144 agentx-TestSet-PDUs..................................63 145 7.2.4.5 Processing of Responses to 146 agentx-CommitSet-PDUs................................64 147 7.2.4.6 Processing of Responses to 148 agentx-UndoSet-PDUs..................................64 150 Daniele/Wijnen Expires May 1977 [Page 3] 151 Draft Agent Extensibility (AgentX) Protocol November 1996 153 7.2.5 Sending the SNMP Response-PDU............................64 154 7.2.6 MIB Views................................................65 156 8 Transport Mappings...............................................65 157 8.1 AgentX over TCP..............................................65 158 8.1.1 Well-known Values........................................65 159 8.1.2 Operation................................................65 160 8.2 AgentX over UNIX-domain Sockets..............................65 161 8.2.1 Well-known Values........................................66 162 8.2.2 Operation................................................66 164 9 Security Considerations..........................................66 166 10 Acknowledgements................................................66 168 11 Questions and Issues............................................67 169 11.1 Design......................................................67 170 11.2 Miscellaneous Issues/Decisions..............................67 171 11.3 New in this version.........................................69 173 12 Authors' and Editor's Addresses.................................70 175 13 References......................................................70 177 Daniele/Wijnen Expires May 1977 [Page 4] 178 Draft Agent Extensibility (AgentX) Protocol November 1996 180 1. Introduction 182 This memo defines a framework for extensible SNMP agents. It defines 183 processing entities called master agents and subagents, a protocol 184 (AgentX) used to communicate between them, and the elements of 185 procedure by which the extensible agent processes SNMP protocol 186 messages. 188 2. The SNMP Framework 190 A management system contains: several (potentially many) nodes, 191 each with a processing entity, termed an agent, which has access to 192 management instrumentation; at least one management station; and, a 193 management protocol, used to convey management information between 194 the agents and management stations. Operations of the protocol are 195 carried out under an administrative framework which defines 196 authentication, authorization, access control, and privacy 197 policies. 199 Management stations execute management applications which monitor 200 and control managed elements. Managed elements are devices such as 201 hosts, routers, terminal servers, etc., which are monitored and 202 controlled via access to their management information. 204 Management information is viewed as a collection of managed objects, 205 residing in a virtual information store, termed the Management 206 Information Base (MIB). Collections of related objects are defined 207 in MIB modules. These modules are written using a subset of OSI's 208 Abstract Syntax Notation One (ASN.1) [1], termed the Structure of 209 Management Information (SMI) (see RFC 1902 [2]). 211 2.1. A Note on Terminology 213 The term "variable" refers to an instance of a non-aggregate 214 object type defined according to the conventions set forth in the 215 SMI (RFC 1902, [2]) or the textual conventions based on the SMI 216 (RFC 1903 [3]). The term "variable binding" normally refers to 217 the pairing of the name of a variable and its associated value. 218 However, if certain kinds of exceptional conditions occur during 219 processing of a retrieval request, a variable binding will pair a 220 name and an indication of that exception. 222 A variable-binding list is a simple list of variable bindings. 224 The name of a variable is an OBJECT IDENTIFIER, which is the 225 concatenation of the OBJECT IDENTIFIER of the corresponding object 226 type together with an OBJECT IDENTIFIER fragment identifying the 227 instance. The OBJECT IDENTIFIER of the corresponding object-type is 228 called the OBJECT IDENTIFIER prefix of the variable. 229 For the purpose of exposition, the original Internet-standard 231 Daniele/Wijnen Expires May 1977 [Page 5] 232 Draft Agent Extensibility (AgentX) Protocol November 1996 234 Network Management Framework, as described in RFCs 1155 (STD 16), 235 1157 (STD 15), and 1212 (STD 16), is termed the SNMP version 1 236 framework (SNMPv1). The current framework, as described in RFCs 237 1902-1908, is termed the SNMP version 2 framework (SNMPv2). 239 3. Extending the MIB 241 New MIB modules that extend the Internet-standard MIB are 242 continuously being defined by various IETF working groups. It is 243 also common for enterprises or individuals to create or extend 244 enterprise-specific or experimental MIBs. 246 As a result, managed devices are frequently complex collections of 247 manageable components that have been independently installed on a 248 managed node. Each component provides instrumentation for the 249 managed objects defined in the MIB module(s) it implements. 251 Neither the SNMP version 1 or version 2 framework addresses how 252 managed objects may be dynamically added to or removed from the 253 agent view within a particular managed node. 255 3.1. Motivation for AgentX 257 This very real need to dynamically extend the management objects 258 within a node has given rise to a variety of "extensible agents", 259 which typically comprise 261 - a "master" agent that is available on the standard transport 262 address and that accepts SNMP protocol messages 264 - a set of "subagents" that each contain management 265 instrumentation 267 - a protocol that operates between the master agent and subagents, 268 permitting subagents to "connect" to the master agent, and the 269 master agent to multiplex received SNMP protocol messages 270 amongst the subagents. 272 - a set of tools to aid subagent development, and a runtime (API) 273 environment that hides much of the protocol operation between a 274 subagent and the master agent. 276 The wide deployment of extensible SNMP agents, coupled with the 277 lack of Internet standards in this area, makes it difficult to field 278 SNMP-manageable applications. A vendor may have to support several 279 different subagent environments (APIs) in order to support different 280 target platforms. 282 It can also become quite cumbersome to configure subagents and 283 (possibly multiple) master agents on a particular managed node. 285 Daniele/Wijnen Expires May 1977 [Page 6] 286 Draft Agent Extensibility (AgentX) Protocol November 1996 288 Specifying a standard protocol for agent extensibility (AgentX) 289 provides the technical foundation required to solve both of 290 these problems. Independently developed AgentX-capable master 291 agents and subagents will be able to interoperate at the protocol 292 level. Vendors can continue to differentiate their products 293 in all other respects. 295 4. AgentX Framework 297 Within the SNMP framework, a managed node contains a processing 298 entity, called an agent, which has access to management 299 information. 301 Within the AgentX framework, an agent is further defined to 302 consist of 304 - a single processing entity called the master agent, which sends 305 and receives SNMP protocol messages in an agent role (as 306 specified by the SNMP version 1 and version 2 framework 307 documents) but typically has little or no direct access to 308 management information. 310 - 0 or more processing entities called subagents, which are 311 "shielded" from the SNMP protocol messages processed by the 312 master agent, but which have access to management information. 314 The master and subagent entities communicate via AgentX protocol 315 messages, as specified in this memo. Other interfaces (if any) on 316 these entities, and their associated protocols, are outside the 317 scope of this document. While some of the AgentX protocol messages 318 appear similar in syntax and semantics to the SNMP, bear in mind 319 that AgentX is not SNMP. 321 The internal operations of AgentX are invisible to an SNMP entity 322 operating in a manager role. From a manager's point of view, an 323 extensible agent behaves exactly as would a non-extensible 324 (monolithic) agent that has access to the same management 325 instrumentation. 327 This transparency to managers is a fundamental requirement of 328 AgentX, and is what differentiates AgentX subagents from SNMP proxy 329 agents. 331 4.1. AgentX Roles 333 An entity acting in a master agent role performs the following 334 functions: 336 - Accepts AgentX session establishment requests from subagents. 338 Daniele/Wijnen Expires May 1977 [Page 7] 339 Draft Agent Extensibility (AgentX) Protocol November 1996 341 - Accepts registration of MIB regions by subagents. 343 - Sends and accepts SNMP protocol messages on the agent's 344 specified transport addresses. 346 - Implements the agent role Elements of Procedure specified 347 for the administrative framework applicable to the SNMP 348 protocol message, except where they specify performing 349 management operations. (The application of MIB views, and 350 the access control policy for the managed node, are 351 implemented by the master agent.) 353 - Provides instrumentation for the MIB objects defined in RFC 354 1907 [5], and for any MIB objects relevant to any 355 administrative framework it supports. 357 - Sends and receives AgentX protocol messages to access 358 management information, based on the current registry of MIB 359 regions. 361 - Forwards notifications on behalf of subagents. 363 An entity acting in a subagent role performs the following functions: 365 - Initiates an AgentX session with the master agent. 367 - Registers MIB regions with the master agent. 369 - Instantiates managed objects. 371 - Binds OIDs within its registered MIB regions to actual 372 variables. 374 - Performs management operations on variables. 376 - Initiates notifications. 378 4.2. Design Goals for AgentX 380 The primary goals of the design described in this memo are to 382 1) Define a standard protocol and "rules of engagement" for 383 interoperability between management instrumentation and extensible 384 agents. 386 2) Provide a mechanism for independently developed subagents to 387 integrate into the extensible agent on a particular managed node 388 in such a way that they need not be aware of any other existing 389 subagents. 391 Daniele/Wijnen Expires May 1977 [Page 8] 392 Draft Agent Extensibility (AgentX) Protocol November 1996 394 As described below, support for index allocation, overlapping 395 registration, and the open registration method ("open" in the 396 sense that subagents are not required to know the state of 397 pre-existing registrations in order for registration to work) 398 provide such a mechanism. 400 3) Enhance performance where possible. Some of the design decisions 401 made with this in mind include: 403 - 32-bit alignment of data within PDUs 405 - Native byte-order encoding by subagents 407 - In any single request/response exchange between master agent 408 and subagent, all variable bindings targeted for a subagent 409 are included in a single AgentX PDU sent to that subagent. 411 Note: In some cases multiple request/response 412 exchanges may be required in order to process a 413 single management request; for example, in processing 414 some SNMP GetBulk or GetNext requests. 416 - Subagent returns a single response PDU, which contains as 417 much data as possible; its limits (for Next/Bulk) are its 418 own size constraints, or the upper bound on variable binding 419 names established by the master agent. 421 As a general architectural principle, this memo proposes that there 422 should be a division of labor between master agent and subagent: The 423 master agent is MIB ignorant and SNMP omniscient, while the subagent 424 is SNMP ignorant and MIB omniscient. That is, master agents are 425 exclusively concerned with SNMP operations and the translations to 426 and from AgentX protocol operations needed to carry them out, 427 subagents are exclusively concerned with management instrumentation, 428 and neither should intrude on the other's territory. 430 For questions and open issues, see section 11 at the end of this 431 memo. 433 5. AgentX Encodings 435 AgentX PDUs consist of a common header, followed by PDU-specific 436 data of variable length. Unlike SNMP PDUs, AgentX PDUs are not 437 encoded using the BER (as specified in ISO 8824 [1]), but are 438 transmitted as a contiguous byte stream. The data within this 439 stream is organized to provide natural alignment with respect to the 440 start of the PDU, permitting direct (integer) access by the 441 processing entities. 443 The fields in the header are always encoded in network byte order 445 Daniele/Wijnen Expires May 1977 [Page 9] 446 Draft Agent Extensibility (AgentX) Protocol November 1996 448 (most significant byte first), regardless of the setting of the 449 NETWORK_BYTE_ORDER flag in the h.flags field (see section 6.1). 450 Fields within the PDUs are encoded either most significant byte 451 first, or least significant byte first. The subagent selects which 452 byte ordering to use when it establishes an AgentX session. 454 PDUs are depicted in this memo using the following convention 455 (where byte 1 is the first transmitted byte): 457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 458 | byte 1 | byte 2 | byte 3 | byte 4 | 459 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 460 | byte 5 | byte 6 | byte 7 | byte 8 | 461 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 462 ... 464 Fields marked "" are reserved for future use and must be 465 zero-filled. 467 5.1. Object Identifier 469 An object identifier is encoded as a 4-byte header, followed by a 470 variable number of contiguous 4-byte fields representing 471 sub-identifiers. This representation (termed Object Identifier) is 472 as follows: 474 Object Identifier 476 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 477 | n_subid | prefix | include | | 478 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 479 | sub-identifier #1 | 480 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 481 ... 482 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 483 | sub-identifier #n_subid | 484 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 486 Object Identifier header fields: 488 n_subid 490 The number (0-128) of sub-identifiers in the object 491 identifier. An ordered list of `n_subid' 4-byte 492 sub-identifiers follows the 4-byte header. 494 prefix 496 An unsigned value used to reduce the length of object 498 Draft Agent Extensibility (AgentX) Protocol November 1996 500 identifier encodings. A non-zero value `x' is interpreted as 501 the first sub-identifier after `internet' (1.3.6.1), and 502 indicates an implicit prefix `internet.x' to the actual 503 sub-identifiers encoded in the Object Identifier. For 504 example, a prefix field value `2' indicates an implicit prefix 505 `1.3.6.1.2'. A value of 0 in the prefix field indicates there 506 is no prefix to the sub-identifiers. 508 include 510 Used only when the Object Identifier is the start of a 511 SearchRange. 513 Examples: 515 sysDescr.0 (1.3.6.1.2.1.1.1.0) 517 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 518 | 4 | 2 | 0 | 0 | 519 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 520 | 1 | 521 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 522 | 1 | 523 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 524 | 1 | 525 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 526 | 0 | 527 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 529 1.2.3.4 531 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 532 | 4 | 0 | 0 | 0 | 533 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 534 | 1 | 535 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 536 | 2 | 537 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 538 | 3 | 539 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 540 | 4 | 541 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 543 A null Object Identifier consists of the 4-byte header with all 544 bytes set to 0. 546 Draft Agent Extensibility (AgentX) Protocol November 1996 548 5.2. SearchRange 550 A SearchRange consists of two Object Identifiers. In its 551 communication with a subagent, the master agent uses a SearchRange 552 to identify a requested variable binding, and, in GetNext and 553 GetBulk operations, to set an upper bound on the names of managed 554 object instances the subagent may send in reply. 556 The first Object Identifier in a SearchRange (called the starting 557 OID) indicates the beginning of the range. It is frequently (but 558 not necessarily) the name of a requested variable binding. 560 The `include' field in this OID's header is a boolean value 561 indicating whether or not the starting OID is included in the range. 563 The second object identifier indicates the non-inclusive end of 564 the range, and its `include' field is always 0. 566 Example: To indicate a search range from 1.3.6.1.2.1.25.2 567 (inclusive) to 1.3.6.1.2.1.25.2.1 (exclusive), the SearchRange would 568 be 570 (start) 571 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 572 | 3 | 2 | 1 | 0 | 573 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 574 | 1 | 575 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 576 | 25 | 577 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 578 | 2 | 579 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 581 (end) 582 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 583 | 4 | 2 | 0 | 0 | 584 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 585 | 1 | 586 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 587 | 25 | 588 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 589 | 2 | 590 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 591 | 1 | 592 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 594 A SearchRangeList is a contiguous list of SearchRanges. 596 Draft Agent Extensibility (AgentX) Protocol November 1996 598 5.3. Octet String 600 An octet string is represented by a contiguous series of bytes, 601 beginning with a 4-byte integer whose value is the number of octets 602 in the octet string, followed by the octets themselves. This 603 representation is termed an Octet String. If the last octet does 604 not end on a 4-byte offset from the start of the Octet String, 605 padding bytes are appended to achieve alignment of following data. 606 This padding must be added even if the Octet String is the last item 607 in the PDU. Padding bytes must be zero filled. 609 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 610 | Octet String Length (L) | 611 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 612 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 613 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 614 ... 615 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 616 | Octet L - 1 | Octet L | Padding (as required) | 617 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 619 A null Octet String consists of a 4-byte length field set to 0. 621 Draft Agent Extensibility (AgentX) Protocol November 1996 623 5.4. Value Representation 625 Variable bindings may be encoded within the variable-length portion 626 of some PDUs. The representation of a variable binding (termed a 627 VarBind) consists of a 2-byte type field, a name (Object 628 Identifier), and the actual value data. 630 VarBind 632 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 633 | v.type | | 634 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 636 (v.name) 637 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 638 | n_subid | prefix | 0 | 0 | 639 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 640 | sub-identifier #1 | 641 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 642 ... 643 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 644 | sub-identifier #n_subid | 645 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 647 (v.data) 648 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 649 | data | 650 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 651 ... 652 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 653 | data | 654 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 656 VarBind fields: 658 v.type 660 Indicates the variable binding's syntax, and must be one of 661 the following (SNMPv2 SMI) values: 663 Integer (2), 664 Octet String (4), 665 Object Identifier (6), 666 IpAddress (64), 667 Counter32 (65), 668 Gauge32 (66), 669 TimeTicks (67), 670 Opaque (68), 671 Counter64 (70), 672 noSuchObject (128), 674 Draft Agent Extensibility (AgentX) Protocol November 1996 676 noSuchInstance (129), 677 endOfMibView (130) 679 v.name 681 The Object Identifier which names the variable. 683 v.data 685 The actual value, encoded as follows: 687 - Integer, Counter32, Gauge32, and TimeTicks are encoded as 688 4 contiguous bytes. If the subagent chose network byte 689 ordering (see 7.1.1., Processing the agentx-Open-PDU, 690 item 3), the bytes are ordered most significant to least 691 significant, otherwise they are ordered least significant 692 to most significant. 694 - Counter64 is encoded as 8 contiguous bytes. If the 695 subagent chose network byte ordering (see 7.1.1., 696 Processing the agentx-Open-PDU, item 3), the bytes are 697 ordered most significant to least significant, otherwise 698 they are ordered least significant to most significant. 700 - Object Identifiers are encoded as described in section 701 5.1, Object Identifier. 703 - IpAddress, Opaque, and Octet String are all octet strings 704 and are encoded as described in section 5.3, Octet String. 706 Value data always follows v.name whenever v.type is one 707 of the above types. These data bytes are present even if 708 they will not be used (as, for example, in certain types 709 of index allocation). 711 - noSuchObject, noSuchInstance, and endOfMibView do not 712 contain any encoded value. Value data never follows 713 v.name in these cases. 715 Note that the VarBind itself does not contain the value size. 716 That information is implied for the fixed-length types, and 717 explicitly contained in the encodings of variable-length types 718 (Object Identifier and Octet String). 720 A VarBindList is a contiguous list of VarBinds. 722 Draft Agent Extensibility (AgentX) Protocol November 1996 724 6. Protocol Definitions 726 6.1. AgentX PDU Header 728 The AgentX PDU header is a fixed-format, 12-octet structure, whose 729 data are always transmitted in network byte order: 731 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 732 | h.version | h.type | h.payload_length | 733 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 734 | h.ID | 735 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 736 | h.flags | | 737 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 739 An AgentX PDU header contains the following fields: 741 h.version 743 The version of the AgentX protocol (1 for this draft). 745 h.type 747 The PDU type; one of the following values: 749 agentx-Open-PDU (1), 750 agentx-Close-PDU (2), 751 agentx-Register-PDU (3), 752 agentx-Unregister-PDU (4), 753 agentx-Get-PDU (5), 754 agentx-GetNext-PDU (6), 755 agentx-GetBulk-PDU (7), 756 agentx-TestSet-PDU (8), 757 agentx-CommitSet-PDU (9), 758 agentx-UndoSet-PDU (10), 759 agentx-CleanupSet-PDU (11), 760 agentx-Notify-PDU (12), 761 agentx-Ping-PDU (13), 762 agentx-IndexAllocate-PDU (14), 763 agentx-IndexDeallocate-PDU (15), 764 agentx-AddAgentCaps-PDU (16), 765 agentx-RemoveAgentCaps-PDU (17), 766 agentx-Response-PDU (18) 768 h.payload_length 770 The size in octets of the PDU contents, excluding the 12-byte 771 header. As a result of the encoding schemes and PDU layouts, 772 this value will always be either 0, or a multiple of 4. 774 Draft Agent Extensibility (AgentX) Protocol November 1996 776 h.ID 778 A packet ID that should be kept unique by the sending entity. 779 The response to this PDU will contain the same value in its 780 h.ID field. Master agents typically increment this value for 781 each PDU sent, and wrap if the maximum value is reached. 783 h.flags 785 A bitmask, with bit 0 the leftmost bit. The bit definitions 786 are as follows: 788 Bit Definition 789 --- ---------- 790 0 INSTANCE_REGISTRATION 791 1 NEW_INDEX 792 2 ANY_INDEX 793 3 NON_DEFAULT_CONTEXT 794 4 NETWORK_BYTE_ORDER 795 5-15 (reserved) 797 6.1.1. Context 799 In the SNMPv1 or v2c frameworks, the community string may be used as 800 an index into a local repository of configuration information that 801 may include community profiles or more complex context information. 802 Future versions of the SNMP will likely formalize this notion of 803 "context". 805 AgentX provides a mechanism for transmitting a context specification 806 within relevant PDUs, but does not place any constraints on the 807 content of that specification. 809 An optional context field may be present in the agentx-Register-, 810 UnRegister-, AddAgentCaps-, RemoveAgentCaps-, Get-, GetNext-, 811 GetBulk-, and TestSet-PDUs. 813 If the NON_DEFAULT_CONTEXT bit in the AgentX header field h.flags is 814 clear, then there is no context field in the PDU, and the operation 815 refers to the default context. 817 If the NON_DEFAULT_CONTEXT bit is set, then a context field 818 immediately follows the AgentX header, and the operation refers 819 to that specific context. The context is represented as an Octet 820 String. There are no constraints on its length or contents. 822 Thus, all of these AgentX PDUs (that is, those listed immediately 823 above) refer to, or "indicate" a context, which is either the 824 default context, or a non-default context explicitly named in the 825 PDU. 827 Draft Agent Extensibility (AgentX) Protocol November 1996 829 6.2. AgentX PDUs 831 6.2.1. The agentx-Open-PDU 833 An agentx-Open-PDU is generated by a subagent to request 834 establishment of an AgentX session with the master agent. 836 (AgentX header) 837 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 838 | h.version (1) | h.type (1) | h.payload_length | 839 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 840 | h.ID | 841 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 842 | h.flags | | 843 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 845 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 846 | o.timeout | | 847 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 849 (o.id) 850 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 851 | n_subid | prefix | 0 | | 852 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 853 | subidentifier #1 | 854 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 855 ... | 856 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 857 | subidentifier #n_subid | 858 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 860 (o.descr) 861 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 862 | Octet String Length (L) | 863 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 864 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 865 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 866 ... 867 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 868 | Octet L - 1 | Octet L | Padding (as required) | 869 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 871 6.2.1.1. agentx-Open-PDU Fields 873 An agentx-Open-PDU contains the following fields: 875 o.timeout 877 The length of time, in seconds, that a master agent should 878 allow to elapse after dispatching a message to a subagent 880 Draft Agent Extensibility (AgentX) Protocol November 1996 882 before it regards the subagent as not responding. This is a 883 subagent-wide default value that may be overridden by values 884 associated with specific registered MIB regions. The default 885 value of `0' indicates that no subagent-wide value is 886 requested. 888 o.id 890 An Object Identifier that identifies the subagent. Subagents 891 that do not support such an notion may send a null Object 892 Identifier. 894 o.descr 896 An Octet String containing a DisplayString describing the 897 subagent. 899 6.2.2. The agentx-Close-PDU 901 An agentx-Close-PDU issued by either a subagent or the master 902 agent terminates an AgentX session. 904 (AgentX header) 906 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 907 | h.version (1) | h.type (2) | h.payload_length | 908 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 909 | h.ID | 910 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 911 | h.flags | | 912 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 914 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 915 | c.reason | | 916 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 918 Draft Agent Extensibility (AgentX) Protocol November 1996 920 6.2.2.1. agentx-Close-PDU Fields 922 An agentx-Close-PDU contains the following field: 924 c.reason 926 An enumerated value that gives the reason that the master 927 agent or subagent closed the AgentX session. This field may 928 take one of the following values: 930 reasonOther(1) 931 None of the following reasons 933 reasonProtocolError(2) 934 Too many AgentX protocol errors from peer 936 reasonTimeouts(3) 937 Too many timeouts waiting for peer 939 reasonShutdown(4) 940 Sending entity is shutting down 942 reasonByManager(5) 943 Due to Set operation 945 Draft Agent Extensibility (AgentX) Protocol November 1996 947 6.2.3. The agentx-Register-PDU 949 An agentx-Register-PDU is generated by a subagent for each region of 950 the MIB variable naming tree (within one or more contexts) that it 951 wishes to support. 953 (AgentX header) 954 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 955 | h.version (1) | h.type (3) | h.payload_length | 956 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 957 | h.ID | 958 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 959 | h.flags | | 960 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 962 (r.context) (OPTIONAL) 963 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 964 | Octet String Length (L) | 965 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 966 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 967 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 968 ... 969 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 970 | Octet L - 1 | Octet L | Padding (as required) | 971 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 973 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 974 | r.timeout | r.priority | r.range_subid | | 975 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 977 (r.region) 978 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 979 | n_subid | prefix | 0 | | 980 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 981 | sub-identifier #1 | 982 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 983 ... 984 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 985 | sub-identifier #n_subid | 986 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 988 (r.upper_bound) 989 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 990 | optional upper-bound sub-identifier | 991 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 993 Draft Agent Extensibility (AgentX) Protocol November 1996 995 6.2.3.1. agentx-Register-PDU Fields 997 An agentx-Register-PDU contains the following fields: 999 r.context 1001 An optional non-default context. 1003 r.timeout 1005 The length of time, in seconds, that a master agent should 1006 allow to elapse after dispatching a message to a subagent 1007 before it regards the subagent as not responding. r.timeout 1008 applies only to messages that concern MIB objects within 1009 r.region. It overrides both the subagent-wide value (if any) 1010 indicated when the AgentX session with the master agent was 1011 established, and the master agent's default timeout. The 1012 default value for r.timeout is `0' (no override). 1014 r.priority 1016 A value between 1 and 255, used to achieve a desired 1017 configuration when different subagents register identical or 1018 overlapping regions. Subagents with no particular knowledge 1019 of priority should register with the default value of `255' 1020 (lowest priority). 1022 In the master agent's dispatching algorithm, smaller 1023 values of r.priority take precedence over larger values, 1024 as described in section 7.1.5.1. 1026 r.region 1028 An Object Identifier that, in conjunction with r.range_subid, 1029 indicates a region of the MIB that a subagent wishes to 1030 support. It may be a fully-qualified instance name, a partial 1031 instance name, a MIB table, or ranges of any of these. 1033 The choice of what to register is implementation-specific; 1034 this memo does not specify permissible values. Standard 1035 practice however is for a subagent to register at the 1036 highest level of the naming tree that makes sense. 1037 Registration of fully-qualified instances is typically done 1038 only when a subagent can perform management operations only 1039 on particular rows of a conceptual table. 1041 If r.region is in fact a fully qualified instance name, the 1042 INSTANCE_REGISTRATION bit in h.flags must be set, otherwise it 1043 must be cleared. The master agent may save this information 1044 to optimize subsequent operational dispatching. 1046 Draft Agent Extensibility (AgentX) Protocol November 1996 1048 r.range_subid 1050 Permits specifying a range in place of one of r.region's 1051 sub-identifiers. If this value is 0, no range is specified. 1052 Otherwise the `r.range_subid'-th sub-identifier in 1053 r.region is a range lower bound, and the range upper 1054 bound sub-identifier (r.upper_bound) immediately follows 1055 r.region. 1057 This permits registering a conceptual row with a single 1058 PDU. For example, the following PDU would register row 1059 7 of the RFC 1573 ifTable (1.3.6.1.2.1.2.2.1.1-22.7): 1061 (AgentX header) 1062 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1063 | h.version (1) | h.type (3) | h.payload_length | 1064 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1065 | h.ID | 1066 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1067 | h.flags | | 1068 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1070 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1071 | r.timeout | r.priority | 5 | | 1072 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1074 (r.region) 1075 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1076 | 6 | 2 | 0 | | 1077 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1078 | 1 | 1079 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1080 | 2 | 1081 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1082 | 2 | 1083 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1084 | 1 | 1085 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1086 | 1 | 1087 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1088 | 7 | 1089 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1091 (r.upper_bound) 1092 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1093 | 22 | 1094 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1096 Draft Agent Extensibility (AgentX) Protocol November 1996 1098 6.2.4. The agentx-Unregister-PDU 1100 The agentx-Unregister-PDU is sent by a subagent to remove a 1101 previously registered MIB region from the master agent's OID space. 1103 (AgentX header) 1104 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1105 | h.version (1) | h.type (4) | h.payload_length | 1106 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1107 | h.ID | 1108 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1109 | h.flags | | 1110 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1112 (u.context) OPTIONAL 1113 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1114 | Octet String Length (L) | 1115 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1116 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1117 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1118 ... 1119 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1120 | Octet L - 1 | Octet L | Padding (as required) | 1121 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1123 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1124 | | u.range_subid | | 1125 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1127 (u.region) 1128 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1129 | n_subid | prefix | 0 | | 1130 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1131 | sub-identifier #1 | 1132 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1133 ... 1134 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1135 | sub-identifier #n_subid | 1136 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1138 (u.upper_bound) 1139 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1140 | optional upper-bound sub-identifier | 1141 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1143 Draft Agent Extensibility (AgentX) Protocol November 1996 1145 6.2.4.1. agentx-Unregister-PDU Fields 1147 An agentx-Unregister-PDU contains the following fields: 1149 u.context 1151 An optional non-default context. 1153 u.region 1155 Indicates a previously-registered region of the MIB that a 1156 subagent no longer wishes to support. It may be a 1157 fully-qualified instance name, a partial instance name, a MIB 1158 table or group, or ranges of any of these. 1160 Draft Agent Extensibility (AgentX) Protocol November 1996 1162 6.2.5. The agentx-Get-PDU 1164 (AgentX header) 1165 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1166 | h.version (1) | h.type (5) | h.payload_length | 1167 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1168 | h.ID | 1169 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1170 | h.flags | | 1171 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1173 (g.context) OPTIONAL 1174 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1175 | Octet String Length (L) | 1176 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1177 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1178 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1179 ... 1180 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1181 | Octet L - 1 | Octet L | Padding (as required) | 1182 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1184 (g.sr) 1186 (start 1) 1187 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1188 | n_subid | prefix | include | | 1189 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1190 | sub-identifier #1 | 1191 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1192 ... 1193 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1194 | sub-identifier #n_subid | 1195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1197 (end 1) 1198 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1199 | n_subid | prefix | 0 | | 1200 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1201 | sub-identifier #1 | 1202 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1203 ... 1204 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1205 | sub-identifier #n_subid | 1206 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1207 ... 1209 Draft Agent Extensibility (AgentX) Protocol November 1996 1211 (start n) 1212 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1213 | n_subid | prefix | include | | 1214 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1215 | sub-identifier #1 | 1216 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1217 ... 1218 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1219 | sub-identifier #n_subid | 1220 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1222 (end n) 1223 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1224 | n_subid | prefix | 0 | | 1225 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1226 | sub-identifier #1 | 1227 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1228 ... 1229 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1230 | sub-identifier #n_subid | 1231 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1233 6.2.5.1 agentx-Get-PDU Fields 1235 An agentx-Get-PDU contains the following fields: 1237 g.context 1239 An optional non-default context. 1241 g.sr 1243 A SearchRangeList containing the requested variables for this 1244 subagent. 1246 Draft Agent Extensibility (AgentX) Protocol November 1996 1248 6.2.6. The agentx-GetNext-PDU 1250 (AgentX header) 1251 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1252 | h.version (1) | h.type (6) | h.payload_length | 1253 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1254 | h.ID | 1255 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1256 | h.flags | | 1257 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1259 (g.context) OPTIONAL 1260 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1261 | Octet String Length (L) | 1262 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1263 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1264 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1265 ... 1266 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1267 | Octet L - 1 | Octet L | Padding (as required) | 1268 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1270 (g.sr) 1271 ... 1273 Draft Agent Extensibility (AgentX) Protocol November 1996 1275 6.2.7. The agentx-GetBulk-PDU 1277 (AgentX header) 1278 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1279 | h.version (1) | h.type (7) | h.payload_length | 1280 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1281 | h.ID | 1282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1283 | h.flags | | 1284 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1286 (g.context) OPTIONAL 1287 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1288 | Octet String Length (L) | 1289 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1290 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1291 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1292 ... 1293 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1294 | Octet L - 1 | Octet L | Padding (as required) | 1295 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1297 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1298 | g.non_repeaters | g.max_repetitions | 1299 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1301 (g.sr) 1302 ... 1304 Draft Agent Extensibility (AgentX) Protocol November 1996 1306 6.2.8. The agentx-TestSet-PDU 1308 (AgentX header) 1309 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1310 | h.version (1) | h.type (8) | h.payload_length | 1311 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1312 | h.ID | 1313 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1314 | h.flags | | 1315 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1317 (t.context) OPTIONAL 1318 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1319 | Octet String Length (L) | 1320 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1321 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1322 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1323 ... 1324 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1325 | Octet L - 1 | Octet L | Padding (as required) | 1326 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1328 (t.vb) 1330 (VarBind 1) 1331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1332 | v.type | | 1333 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1334 | n_subid | prefix | 0 | | 1335 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1336 | sub-identifier #1 | 1337 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1338 ... 1339 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1340 | sub-identifier #n_subid | 1341 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1342 | data | 1343 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1344 ... 1345 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1346 | data | 1347 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1348 ... 1350 Draft Agent Extensibility (AgentX) Protocol November 1996 1352 (VarBind n) 1353 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1354 | v.type | | 1355 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1356 | n_subid | prefix | 0 | | 1357 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1358 | sub-identifier #1 | 1359 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1360 ... 1361 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1362 | sub-identifier #n_subid | 1363 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1364 | data | 1365 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1366 ... 1367 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1368 | data | 1369 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1371 6.2.8.1. agentx-TestSet-PDU Fields 1373 An agentx-TestSet-PDU contains the following fields: 1375 t.context 1377 An optional non-default context. 1379 t.vb 1381 A VarBindList containing the requested variable bindings for 1382 this subagent. 1384 6.2.9. The agentx-CommitSet, -UndoSet, -CleanupSet, and -Ping PDUs 1386 These PDUs consist of the AgentX header only. 1388 The agentx-CommitSet-, -UndoSet-, and -Cleanup-PDUs are used in 1389 processing an SNMP SetRequest operation. 1391 The agentx-Ping-PDU is sent by a subagent to the master agent to 1392 monitor the master agent's ability to receive and send AgentX 1393 PDUs over their AgentX session. 1395 Draft Agent Extensibility (AgentX) Protocol November 1996 1397 6.2.10. The agentx-Notify-PDU 1399 An agentx-Notify-PDU is sent by a subagent to cause the master agent 1400 to forward a notification. 1402 (AgentX header) 1403 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1404 | h.version (1) | h.type (12) | h.payload_length | 1405 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1406 | h.ID | 1407 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1408 | h.flags | | 1409 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1411 (n.context) OPTIONAL 1412 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1413 | Octet String Length (L) | 1414 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1415 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1416 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1417 ... 1418 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1419 | Octet L - 1 | Octet L | Padding (as required) | 1420 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1422 (n.vb) 1423 ... 1425 6.2.10.1. agentx-Notify-PDU Fields 1427 An agentx-Notify-PDU contains the following fields: 1429 n.context 1431 An optional non-default context. 1433 n.vb 1435 A VarBindList whose contents define the actual PDU to be 1436 sent. This memo places the following restrictions on its 1437 contents: 1439 - If the subagent supplies sysUpTime.0, it must be 1440 present as the first varbind. 1442 - snmpTrapOID.0 must be present, as the second 1443 varbind if sysUpTime.0 was supplied, as the 1444 first if it was not. 1446 Draft Agent Extensibility (AgentX) Protocol November 1996 1448 6.2.11. The agentx-IndexAllocate-PDU 1450 An agentx-IndexAllocate-PDU is sent by a subagent to request 1451 allocation of a value for specific index objects. Refer to section 1452 7.1.3 (Using the agentx-IndexAllocate-PDU) for suggested usage. 1454 (AgentX header) 1455 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1456 | h.version (1) | h.type (14) | h.payload_length | 1457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1458 | h.ID | 1459 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1460 | h.flags | | 1461 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1463 (i.context) OPTIONAL 1464 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1465 | Octet String Length (L) | 1466 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1467 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1468 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1469 ... 1470 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1471 | Octet L - 1 | Octet L | Padding (as required) | 1472 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1474 (i.vb) 1475 ... 1477 6.2.11.1 agentx-IndexAllocate-PDU fields 1479 An agentx-IndexAllocate-PDU contains the following fields: 1481 i.context 1483 An optional non-default context. 1485 i.vb 1487 A VarBindList containing the index names and values requested 1488 for allocation. 1490 Draft Agent Extensibility (AgentX) Protocol November 1996 1492 6.2.12. The agentx-IndexDeallocate-PDU 1494 An agentx-IndexDeallocate-PDU is sent by a subagent to release 1495 previously allocated index values. 1497 (AgentX header) 1498 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1499 | h.version (1) | h.type (15) | h.payload_length | 1500 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1501 | h.ID | 1502 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1503 | h.flags | | 1504 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1506 (i.context) OPTIONAL 1507 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1508 | Octet String Length (L) | 1509 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1510 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1511 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1512 ... 1513 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1514 | Octet L - 1 | Octet L | Padding (as required) | 1515 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1517 (i.vb) 1518 ... 1520 6.2.12.1 agentx-IndexDeallocate-PDU fields 1522 An agentx-IndexDeallocate-PDU contains the following fields: 1524 i.context 1526 An optional non-default context. 1528 i.vb 1530 A VarBindList containing the index names and values to be 1531 released. 1533 Draft Agent Extensibility (AgentX) Protocol November 1996 1535 6.2.13. The agentx-AddAgentCaps-PDU 1537 An agentx-AddAgentCaps-PDU is generated by a subagent to inform the 1538 master agent of its agent capabilities. 1540 (AgentX header) 1541 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1542 | h.version (1) | h.type (16) | h.payload_length | 1543 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1544 | h.ID | 1545 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1546 | h.flags | | 1547 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1549 (a.context) (OPTIONAL) 1550 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1551 | Octet String Length (L) | 1552 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1553 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1554 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1555 ... 1556 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1557 | Octet L - 1 | Octet L | Optional Padding | 1558 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1560 (a.id) 1561 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1562 | n_subid | prefix | 0 | | 1563 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1564 | sub-identifier #1 | 1565 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1566 ... 1567 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1568 | sub-identifier #n_subid | 1569 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1571 (a.descr) 1572 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1573 | Octet String Length (L) | 1574 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1575 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1576 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1577 ... 1578 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1579 | Octet L - 1 | Octet L | Optional Padding | 1580 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1582 Draft Agent Extensibility (AgentX) Protocol November 1996 1584 6.2.13.1. agentx-AddAgentCaps-PDU Fields 1586 An agentx-AddAgentCaps-PDU contains the following fields: 1588 a.context 1590 An optional non-default context. 1592 a.id 1594 An Object Identifier containing the value of an invocation of 1595 the AGENT-CAPABILITIES macro, which the master agent exports 1596 as a value of sysORID for the indicated context. (Recall that 1597 the value of an invocation of an AGENT-CAPABILITIES macro is 1598 an object identifier that describes a precise level of support 1599 with respect to implemented MIB modules. A more complete 1600 discussion of the AGENT-CAPABILITIES macro and related sysORID 1601 values can be found in section 6 of RFC 1904 [10].) 1603 a.descr 1605 An Octet String containing a DisplayString to be used as the 1606 value of sysORDescr corresponding to the sysORID value above. 1608 Draft Agent Extensibility (AgentX) Protocol November 1996 1610 6.2.14. The agentx-RemoveAgentCaps-PDU 1612 An agentx-RemoveAgentCaps-PDU is generated by a subagent to request 1613 that the master agent stop exporting a particular value of sysORID. 1614 This value must have previously been advertised by the subagent in 1615 an agentx-AddAgentCaps-PDU. 1617 (AgentX header) 1618 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1619 | h.version (1) | h.type (17) | h.payload_length | 1620 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1621 | h.ID | 1622 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1623 | h.flags | | 1624 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1626 (a.context) (OPTIONAL) 1627 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1628 | Octet String Length (L) | 1629 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1630 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 1631 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1632 ... 1633 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1634 | Octet L - 1 | Octet L | Optional Padding | 1635 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1637 (a.id) 1638 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1639 | n_subid | prefix | 0 | | 1640 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1641 | sub-identifier #1 | 1642 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1643 ... 1644 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1645 | sub-identifier #n_subid | 1646 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1648 6.2.14.1. agentx-RemoveAgentCaps-PDU Fields 1650 An agentx-RemoveAgentCaps-PDU contains the following fields: 1652 a.context 1654 An optional non-default context. 1656 a.id 1658 An ObjectIdentifier containing the value of sysORID that 1659 should no longer be exported. 1661 Draft Agent Extensibility (AgentX) Protocol November 1996 1663 6.2.15. The agentx-Response-PDU 1665 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1666 | h.version (1) | h.type (18) | h.payload_length | 1667 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1668 | h.ID | 1669 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1670 | h.flags | | 1671 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1673 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1674 | res.error | res.index | 1675 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1676 ... 1678 (optional fields) 1680 6.2.15.1. agentx-Response-PDU Fields 1682 An agentx-Response-PDU contains the following fields: 1684 h.ID 1686 Must be identical to the h.ID value in the PDU to which this 1687 PDU is a response. 1689 h.flags 1691 This field is ignored during response PDU processing. 1693 res.error 1695 Indicates error status (including 'noError'). Values are 1696 limited to those defined for errors in the SNMPv2 SMI (RFC 1697 1905 [4]), and the following AgentX-specific values: 1699 alreadyOpen (256), 1700 openFailed (257), 1701 notOpen (258), 1702 indexUnsupportedType (259), 1703 indexWrongType (260), 1704 indexAlreadyAllocated (261), 1705 indexNoneAvailable (262), 1706 indexNotCurrentlyAllocated (263), 1707 unsupportedContext (264), 1708 duplicateRegistration (265), 1709 unknownRegistration (266), 1710 unknownAgentCaps (267) 1712 Draft Agent Extensibility (AgentX) Protocol November 1996 1714 res.index 1716 In error cases, this is the index of the failed variable 1717 binding within a received request PDU. 1719 Other data may follow these latter two fields, depending on 1720 which AgentX PDU is being responded to. These data are 1721 specified in the subsequent elements of procedure. 1723 7. Elements of Procedure 1725 This section describes the actions of protocol entities (master 1726 agents and subagents) implementing the AgentX protocol. Note, 1727 however, that it is not intended to constrain the internal 1728 architecture of any conformant implementation. 1730 The actions of AgentX protocol entities can be broadly categorized 1731 under two headings: 1733 (1) processing AgentX administrative messages (e.g, connection 1734 requests from a subagent to a master agent); and 1736 (2) processing SNMP messages (e.g., the coordinated actions of a 1737 master agent and one or more subagents in processing a 1738 received SNMP Get-PDU). 1740 7.1. Processing AgentX Administrative Messages 1742 This subsection describes the actions of AgentX protocol entities in 1743 processing AgentX administrative messages. Such messages include 1744 those involved in establishing and terminating an AgentX session 1745 between a subagent and a master agent, those by which a subagent 1746 requests allocation of instance index values, and those by which a 1747 subagent communicates to a master agent which MIB regions it 1748 supports. 1750 7.1.1. Processing the agentx-Open-PDU 1752 When the master agent receives an agentx-Open-PDU, it processes it 1753 as follows: 1755 1) If an AgentX session for this subagent has already been 1756 established (via an agentx-Open-PDU from the same transport 1757 endpoint), an agentx-Response-PDU is sent with res.error set 1758 to 'alreadyOpen'. 1760 2) If the master agent is unable to open an AgentX session for 1761 some other reason, it may refuse the session establishment 1762 request, sending in reply an agentx-Response-PDU whose 1763 res.error field is set to `openFailed'. 1765 Draft Agent Extensibility (AgentX) Protocol November 1996 1767 3) Otherwise, the master agent retains session-specific 1768 information from the PDU for this subagent: 1770 - The subagent sets the NETWORK_BYTE_ORDER bit to indicate its 1771 native byte ordering. If set, all numeric data transmitted 1772 during this AgentX session are in network byte order (most 1773 significant byte first), else they are transmitted least 1774 significant byte first. All PDUs exchanged over this AgentX 1775 session will use this byte ordering (including this Open-PDU 1776 and its Response-PDU). The Open-PDU is the only one for which 1777 the NETWORK_BYTE_ORDER bit has meaning; byte ordering is an 1778 attribute of the session, not of each subsequent PDU. 1780 (Note: The 12-byte AgentX header is always transmitted in 1781 network byte order regardless of how the rest of the PDU 1782 is transmitted.) 1784 - The o.timeout value is used in calculating timeout 1785 conditions for this subagent. 1787 - The o.id and o.descr fields are used to create an entry in 1788 the agentxSubAgentTable defined in [TBD]. 1790 4) An agentx-Response-PDU is sent with the res.error field 1791 set to `noError'. The 4 bytes immediately following the 1792 header are encoded with the value of sysUpTime.0 for the 1793 default context. 1795 At this point, an AgentX session is considered established between 1796 the master agent and the subagent. An AgentX session is a distinct 1797 channel for the exchange of AgentX protocol messages between a 1798 master agent and one subagent, qualified by the session-specific 1799 attributes listed in (3) above. Agentx session establishment is 1800 initiated by the subagent. An AgentX session can be terminated by 1801 either the master agent or the subagent. 1803 7.1.2. Processing the agentx-IndexAllocate-PDU 1805 When the master agent receives an agentx-IndexAllocate-PDU, it 1806 processes it as follows: 1808 1) If an AgentX session for this subagent has not been 1809 established, an agentx-Response-PDU is sent in reply with 1810 res.error set to `notOpen'. 1812 2) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 1813 supports only a default context, an agentx-Response-PDU is 1814 returned with res.error set to `unsupportedContext' and the 1815 requested allocation fails. 1817 3) Each VarBind in the VarBindList is processed until either all 1819 Draft Agent Extensibility (AgentX) Protocol November 1996 1821 are successful, or one fails. If any VarBind fails, an 1822 agentx-Response-PDU is sent in reply containing the original 1823 VarBindList, with res.index set to indicate the failed VarBind, 1824 and with res.error set as described subsequently. All other 1825 VarBinds are ignored; no index values are allocated. 1827 VarBinds are processed as follows: 1829 - v.name is the name of the index for which a value is to be 1830 allocated. 1832 - v.type is the syntax of the index object. 1834 - v.data indicates the specific index value requested. 1835 If the NEW_INDEX or the ANY_INDEX bit is set, the 1836 actual value in v.data is ignored and an appropriate index value 1837 is generated. 1839 a) If v.type is not supported by the master agent, the VarBind 1840 fails and res.error is set to `indexUnsupportedType'. 1842 Note: A master agent must support a v.type of INTEGER. 1844 b) If there are currently allocated index values for v.name 1845 in the indicated context, but the syntax of those values 1846 does not match v.type, the VarBind fails and res.error is 1847 set to `indexWrongType'. 1849 c) Otherwise, if both the NEW_INDEX and ANY_INDEX bits are 1850 clear, allocation of a specific index value is being 1851 requested. If the requested index is already allocated 1852 for v.name in the indicated context, the VarBind fails 1853 and res.error is set to `indexAlreadyAllocated'. 1855 d) Otherwise, if the NEW_INDEX bit is set, the master agent 1856 should generate the next available index value for v.name 1857 in the indicated context, with the constraint that this 1858 value must not have been allocated (even if subsequently 1859 released) to any subagent since the last re-initialization 1860 of the master agent. If no such value can be generated, 1861 the VarBind fails and res.error is set to `indexNoneAvailable'. 1863 e) Otherwise, if the ANY_INDEX bit is set, the master agent 1864 should generate an index value for v.name in the 1865 indicated context, with the constraint that this value is 1866 not currently allocated to any subagent. If no such value 1867 can be generated, then the VarBind fails and res.error is 1868 set to `indexNoneAvailable'. 1870 4) If all VarBinds are processed successfully, an 1871 agentx-Response-PDU is sent in reply with res.error set to 1873 Draft Agent Extensibility (AgentX) Protocol November 1996 1875 `noError'. A VarBindList is included that is identical to the 1876 one sent in the agentx-IndexAllocate-PDU, except that VarBinds 1877 requesting the next available index value are updated with an 1878 appropriate value. 1880 7.1.3. Using the agentx-IndexAllocate-PDU 1882 Index allocation is a service provided by an AgentX master agent. 1883 It provides generic support for sharing MIB conceptual tables among 1884 subagents who are assumed to have no knowledge of each other. 1886 Each subagent sharing a table should first request allocation of 1887 index values, then use those index values to qualify MIB regions in 1888 its subsequent registrations. 1890 The master agent maintains a database of index objects (OIDs), and, 1891 for each index, the values that have been allocated for it. It is 1892 unaware of what MIB variables (if any) the index objects represent. 1894 By convention, subagents use the MIB variable listed in the INDEX 1895 clause as the index object for which values must be allocated. For 1896 tables indexed by multiple variables, values may be allocated for 1897 each index (although this is frequently unnecessary; see example 2 1898 below). The subagent may request allocation of 1900 - a specific index value 1901 - an index value that is not currently allocated 1902 - an index value that has never been allocated 1904 The last two alternatives reflect the uniqueness and constancy 1905 requirements present in many MIB specifications for arbitrary 1906 integer indexes (e.g., ifIndex in the IF MIB (RFC 1573 [11]), 1907 snmpFddiSMTIndex in the FDDI MIB (RFC 1285 [12]), or 1908 sysApplInstallPkgIndex in the Application MIB [13]). The need for 1909 subagents to share tables using such indexes is the main motivation 1910 for index allocation in AgentX. 1912 Example 1: 1914 A subagent implements an interface, and wishes to register a 1915 single row of the RFC 1573 ifTable. It requests an allocation 1916 for the index object `ifIndex', for a value that has never been 1917 allocated (since ifIndex values must be unique). The master agent 1918 returns the value "7". 1920 The subagent now attempts to register row 7 of ifTable, by 1921 specifying a MIB region in the agentx-Register-PDU of 1922 1.3.6.1.2.1.2.2.1.[1-22].7. If the registration succeeds, no 1923 further processing is required. The master agent will dispatch 1924 to this subagent correctly. 1926 Draft Agent Extensibility (AgentX) Protocol November 1996 1928 But the registration may fail. Index allocation and MIB region 1929 registration are not coupled in the master agent. Some other 1930 subagent may have already registered ifTable row 7 without first 1931 having requested allocation of the index. The current state of 1932 index allocations is not considered when processing registration 1933 requests, and the current registry is not considered when 1934 processing index allocation requests. If subagents follow the 1935 model of "first request allocation of an index, then register the 1936 corresponding region", then a successful index allocation request 1937 gives a subagent a good hint (but no guarantee) of what it should 1938 be able to register. 1940 If the registration failed, the subagent should request allocation 1941 of a new index i, and attempt to register ifTable.[1-22].i, until 1942 successful. 1944 Example 2: 1946 This same subagent wishes to register ipNetToMediaTable rows 1947 corresponding to its interface (ifIndex i). Due to structure of 1948 this table, no further index allocation need be done. The 1949 subagent can register the MIB region ipNetToMediaTable.[1-4].i, 1950 It is claiming responsibility for all rows of the table whose 1951 value of ipNetToMediaIfIndex is i. 1953 Example 3: 1955 A network device consists of a set of processors, each of which 1956 accepts network connections for a unique set of ip addresses. 1957 Further, each processor contains a subagent that implements 1958 tcpConnTable. In order to represent tcpConnTable for the entire 1959 managed device, the subagents need to share tcpConnTable. 1961 In this case, no index allocation need be done at all. Each 1962 subagent can register a MIB region of tcpConnTable.[1-5].a.b.c.d, 1963 where a.b.c.d represents an unique IP address of the individual 1964 processor. 1966 Each subagent is claiming responsibility for the region of 1967 tcpConnTable where the value of tcpConnLocalAddress is a.b.c.d. 1969 7.1.4 Processing the agentx-IndexDeallocate-PDU 1971 When the master agent receives an agentx-IndexDeallocate-PDU, it 1972 processes it as follows: 1974 1) If an AgentX session for this subagent has not been 1975 established, an agentx-Response-PDU is sent in reply with 1976 res.error set to `notOpen'. 1978 2) Each VarBind in the VarBindList is processed until either all 1980 Draft Agent Extensibility (AgentX) Protocol November 1996 1982 are successful, or one fails. If any VarBind fails, an 1983 agentx-Response-PDU is sent in reply containing the original 1984 VarBindList, with res.index set to indicate the failed VarBind, 1985 and with res.error set as described subsequently. All other 1986 VarBinds are ignored; no index values are released. 1988 VarBinds are processed as follows: 1990 - v.name is the name of the index for which a value is to be 1991 released 1993 - v.type is the syntax of the index object 1995 - v.data indicates the specific index value to be released. 1996 The NEW_INDEX and ANY_INDEX bits are ignored and 1997 should be cleared. 1999 a) If the index value for the named index is not currently 2000 allocated to this subagent, the VarBind fails and res.error 2001 is set to `indexNotAllocated'. 2003 3) If all VarBinds are processed successfully, an agentx-Response-PDU 2004 is sent in reply with res.error set to `noError'. A VarBindList 2005 is included which is identical to the one sent in the 2006 agentx-IndexDeallocate-PDU. 2008 All released index values are now available, and may be used in 2009 response to subsequent allocation requests for ANY_INDEX 2010 values for the particular index. 2012 7.1.5. Processing the agentx-Register-PDU 2014 When the master agent receives an agentx-Register-PDU, it processes 2015 it as follows: 2017 1) If an AgentX session for this subagent has not been 2018 established, an agentx-Response-PDU is sent in reply with 2019 res.error set to `notOpen'. 2021 2) Characterize the request. 2023 If r.region (or any of its set of Object Identifiers, if r.range 2024 is non-zero) is exactly the same as any currently registered 2025 value of r.region (or any of its set of Object Identifiers), 2026 this registration is termed a duplicate region. 2028 If r.region (or any of its set of Object Identifiers, if r.range 2029 is non-zero) is a subtree of, or contains, any currently 2030 registered value of r.region (or any of its set of 2031 Object Identifiers), this registration is termed an overlapping 2032 region. 2034 Draft Agent Extensibility (AgentX) Protocol November 1996 2036 If the NON_DEFAULT_CONTEXT bit is set, this region is to be 2037 logically registered within the context indicated by r.context. 2038 Otherwise this region is to be logically registered within the 2039 default context. 2041 A registration that would result in a duplicate region with the 2042 same priority and within the same context as that of a current 2043 registration is termed a duplicate registration. 2045 3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent 2046 supports only a default context, an agentx-Response-PDU is 2047 returned with res.error set to `unsupportedContext' and the 2048 requested registration fails. 2050 Note: A conformant AgentX master agent must support the notion 2051 of a default context, and may support non-default contexts. 2053 4) Otherwise, if this is a duplicate registration, an 2054 agentx-Response-PDU is returned with res.error set to 2055 `duplicateRegistration', and the requested registration fails. 2057 5) Otherwise, an agentx-Response-PDU is returned with res.error 2058 set to `noError', and a 4-byte TimeTicks value following the 2059 header. The latter is the current value of sysUpTime.0 for 2060 the context that was indicated in the registration message. 2062 The master agent adds this region to its registered OID space for 2063 the indicated context, to be considered during the dispatching 2064 phase for subsequently received SNMP protocol messages. 2066 Note: The following algorithm describes maintaining a set of 2067 OID ranges derived from "splitting" registered regions. The 2068 algorithm for operational dispatching is also stated in terms of 2069 these OID ranges. 2071 These OID ranges are a useful explanatory device, but are not 2072 required for a correct implementation. 2074 - If r.region (R1) is a subtree of a currently registered 2075 region (R2), split R2 into 3 new regions (R2a, R2b, and R2c) 2076 such that R2b is an exact duplicate of R1. Now remove R2 and 2077 add R1, R2a, R2b, and R2c to the master agent's 2078 lexicographically ordered set of ranges (the registered OID 2079 space). Note: Though newly-added ranges R1 and R2b are 2080 identical in terms of the MIB objects they contain, they are 2081 registered by different subagents, possibly at different 2082 priorities. 2084 For instance, if subagent S2 registered `ip' (R2 is 2085 1.3.6.1.2.1.4) and subagent S1 subsequently registered 2086 `ipNetToMediaTable' (R1 is 1.3.6.1.2.1.4.22), the resulting 2088 Draft Agent Extensibility (AgentX) Protocol November 1996 2090 set of registered regions would be: 2092 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2) 2093 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2) 2094 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2095 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2) 2097 - If r.region (R1) overlaps one or more currently registered 2098 regions, then for each overlapped region (R2) split R1 into 3 2099 new ranges (R1a, R1b, R1c) such that R1b is an exact 2100 duplicate of R2. Add R1b and R2 into the lexicographically 2101 ordered set of regions. Apply (5) above iteratively to R1a and 2102 R1c (since they may overlap, or be subtrees of, other regions). 2104 For instance, given the currently registered regions in the 2105 example above, if subagent S3 now registers mib-2 (R1 is 2106 1.3.6.1.2.1) the resulting set of regions would be: 2108 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3) 2109 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2) 2110 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3) 2111 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2) 2112 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2113 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 2114 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2) 2115 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3) 2116 1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3) 2118 Note that at registration time a region may be split into multiple 2119 OID ranges due to pre-existing registrations, or as a result of any 2120 subsequent registration. This region splitting is transparent to 2121 subagents. Hence the master agent must always be able to associate 2122 any OID range with the information contained in its original 2123 agentx-Register-PDU. 2125 7.1.5.1. Handling Duplicate OID Ranges 2127 As a result of this registration algorithm there are likely to be 2128 duplicate OID ranges (regions of identical MIB objects registered to 2129 different subagents) in the master agent's registered OID space. 2130 Whenever the master agent's dispatching algorithm (see 7.2.1, 2131 Dispatching AgentX PDUs) selects a duplicate OID range, the 2132 determination of which one to use proceeds as follows: 2134 1) Choose the one whose original agentx-Register-PDU 2135 r.region contained the most subids, i.e., the most specific 2136 r.region. Note: The presence or absence of a range subid 2137 has no bearing on how "specific" one object identifier is 2138 compared to another. 2140 2) If still ambiguous, there were duplicate regions. Choose the 2142 Draft Agent Extensibility (AgentX) Protocol November 1996 2144 one whose original agentx-Register-PDU specified the smaller 2145 value of r.priority. 2147 7.1.6. Processing the agentx-Unregister-PDU 2149 1) If an AgentX session for this subagent has not been 2150 established, an agentx-Response-PDU is sent in reply with 2151 res.error set to `notOpen'. 2153 2) If u.region and the indicated context do not match an existing 2154 registration of this subagent, an agentx-Response-PDU is returned 2155 with res.error set to 'unknownRegistration'. 2157 3) Otherwise, an agentx-Response-PDU is sent in reply with res.error 2158 set to `noError', and the previous registration is removed: 2160 - The master agent removes u.region from its registered OID space 2161 within the indicated context. If the original region had been 2162 split, all such related regions are removed. 2164 For instance, given the example registry above, if subagent S2 2165 unregisters `ip', the resulting registry would be: 2167 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3) 2168 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3) 2169 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 2170 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 2171 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3) 2172 1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3) 2174 7.1.7. Processing the agentx-AddAgentCaps-PDU 2176 When the master agent receives an agentx-AddAgentCaps-PDU, 2177 it processes it as follows: 2179 1) If an AgentX session for this subagent has not been 2180 established, a agentx-Response-PDU is sent in reply with 2181 res.error set to `notOpen'. 2183 2) Otherwise, if the NON_DEFAULT_CONTEXT bit is set, and the master 2184 agent supports only a default context, an agentx-Response-PDU 2185 is returned with res.error set to `unsupportedContext'. 2187 3) Otherwise, the master agent adds the subagent's capabilities 2188 information to the sysORTable for the indicated context. An 2189 agentx-Response-PDU is sent in reply with res.error set to 2191 Draft Agent Extensibility (AgentX) Protocol November 1996 2193 `noError'. 2195 7.1.8. Processing the agentx-RemoveAgentCaps-PDU 2197 1) If an AgentX session for this subagent has not been 2198 established, an agentx-Response-PDU is sent in reply with 2199 res.error set to `notOpen'. 2201 2) If the combination of a.id and the optional a.context does not 2202 represent a sysORTable entry that was added by this subagent, 2203 an agentx-Response-PDU is returned with res.error set to 2204 'unknownAgentCaps'. 2206 3) Otherwise the master agent deletes the corresponding sysORTable 2207 entry and sends in reply an agentx-Response-PDU with res.error 2208 set to 'noError'. 2210 7.1.9. Processing the agentx-Close-PDU 2212 When the master agent receives an agentx-Close-PDU, it processes it 2213 as follows: 2215 1) If an AgentX session for this subagent has not been 2216 established, an agentx-Response-PDU is sent in reply with 2217 res.error set to `notOpen'. 2219 2) Otherwise, the master agent closes the AgentX session 2220 as described below. No agentx-Response-PDU is sent. 2222 - All MIB regions that have been registered by this subagent 2223 are unregistered, as described in 7.1.6. 2225 - All index values allocated to this subagent are freed, as 2226 described in section 7.1.4. 2228 - All sysORID values being exported on behalf of this subagent 2229 are removed, as described in section 7.1.8. 2231 When a subagent receives an agentx-Close-PDU, it must reestablish an 2232 AgentX session and reregister its MIB regions. 2234 7.1.10. Detecting Connection Loss 2236 If a master agent is able to detect (from the underlying transport) 2237 that a subagent cannot receive AgentX PDUs, it should close the 2238 AgentX session as described in 7.1.9, step (2). 2240 7.1.11. Processing the agentx-Notify-PDU 2242 A subagent sending SNMPv1 trap information must map this into 2243 (minimally) a value of snmpTrapOID.0, as described in 3.1.2 of 2245 Draft Agent Extensibility (AgentX) Protocol November 1996 2247 RFC 1908 [8]. 2249 When the master agent receives an agentx-Notify-PDU, it processes it 2250 as follows: 2252 1) If an AgentX session for this subagent has not been 2253 established, an agentx-Response-PDU is sent in reply with 2254 res.error set to `notOpen'. 2256 2) The VarBindList is parsed. If it does not contain a value for 2257 sysUpTime.0, the master agent supplies the current value of 2258 sysUpTime.0 for the indicated context. If the next VarBind 2259 (either the first or second VarBind; see section 6.2.10.1) 2260 is not snmpTrapOID.0, the master agent ceases further processing 2261 of the notification. 2263 3) Notifications are sent according to the implementation-specific 2264 configuration of the master agent. 2266 If SNMPv1 Trap PDUs are generated, the recommended mapping is as 2267 described in FYI V2ToV1 [9]. 2269 No agentx-Response-PDU is sent. 2271 7.1.12. Processing the agentx-Ping-PDU 2273 When the master agent receives an agentx-Ping-PDU, it processes it 2274 as follows: 2276 1) If an AgentX session for this subagent has not been 2277 established, an agentx-Response-PDU is sent in reply with 2278 res.error set to `notOpen'. 2280 2) Otherwise, an agentx-Response-PDU is sent, whose res.error 2281 field is noError(0), and containing no other data. 2283 If a subagent does not receive a response to its pings, or if it 2284 is able to detect (from the underlying transport) that the 2285 master agent is not able to receive AgentX messages, then it 2286 eventually must initiate a new AgentX session, re-register its 2287 regions, etc. 2289 7.2. Processing Received SNMP Protocol Messages 2291 When an SNMP GetRequest, GetNextRequest, GetBulkRequest, or 2292 SetRequest protocol message is received by the master agent, the 2293 master agent applies its access control policy. 2295 Draft Agent Extensibility (AgentX) Protocol November 1996 2297 In particular, for SNMPv1 or SNMPv2c PDUs, the master agent 2298 applies the Elements of Procedure defined in section 4.1 of RFC 2299 1157 [6] that apply to receiving entities. (For other versions 2300 of SNMP, the master agent applies the access control policy 2301 defined in the Elements of Procedure for those versions.) 2303 In the SNMPv1 or v2c frameworks, the master agent uses the community 2304 string as an index into a local repository of configuration 2305 information that may include community profiles or more complex 2306 context information. 2308 If application of the access control policy results in a valid SNMP 2309 request PDU, then an SNMP Response-PDU is constructed from 2310 information gathered in the exchange of AgentX PDUs between the 2311 master agent and one or more subagents. Upon receipt and initial 2312 validation of an SNMP request PDU, a master agent uses the 2313 procedures described below to dispatch AgentX PDUs to the proper 2314 subagents, marshal the subagent responses, and construct an SNMP 2315 response PDU. 2317 7.2.1. Dispatching AgentX PDUs 2319 Upon receipt and initial validation of an SNMP request PDU, a master 2320 agent uses the procedures described below to dispatch AgentX PDUs to 2321 the proper subagents. 2323 Note: In the following procedures, an object identifier is said to 2324 be "contained" within an OID range when both of the following 2325 are true: 2327 - The object identifier does not lexicographically precede 2328 the range. 2330 - The object identifier lexicographically precedes the end 2331 of the range. 2333 7.2.1.1. agentx-Get-PDU 2335 An SNMP Response-PDU is constructed whose fields all contain the 2336 same values as in the SNMP Request-PDU, except that the value of 2337 each variable binding is set to 'noSuchObject'. 2339 Each variable binding in the Request-PDU is processed in order, as 2340 follows: 2342 (1) Identify the target OID range. 2344 Within a lexicographically ordered set of OID ranges, valid for 2345 the indicated context, locate the region that contains the 2346 binding's name. 2348 Draft Agent Extensibility (AgentX) Protocol November 1996 2350 (2) If no such OID range exists the variable binding is not 2351 processed further, and retains its initialized value 2352 (`noSuchObject'). 2354 (3) Identify the single subagent responsible for this OID range, 2355 termed the target subagent. 2357 (4) Determine the timeout value for this OID range, which is 2359 a) the value specified during registration of the region 2360 containing the OID range, if it was non-zero 2362 b) otherwise, the value specified during the target 2363 subagent's AgentX session establishment, if it was non-zero 2365 c) otherwise, the master agent's default value 2367 (5) If this is the first variable binding to be dispatched to the 2368 target subagent in a request/response exchange entailed in the 2369 processing of this management request: 2371 - Create an agentx-Get-PDU for the subagent, with 2372 the header fields initialized as described above (see 6.1 2373 AgentX PDU Header). 2375 - If the master agent has determined that a specific 2376 non-default context is associated with the Request-PDU, 2377 that context is encoded into g.context and the 2378 NON_DEFAULT_CONTEXT bit is set in h.flags. 2380 Otherwise, no context Octet String is added to the PDU, and the 2381 NON_DEFAULT_CONTEXT bit is cleared. 2383 (6) Add a SearchRange to the end of the target subagent's PDU 2384 for this variable binding. 2386 - The variable binding's name is encoded into the starting OID. 2388 - The ending OID is encoded as null. 2390 7.2.1.2. agentx-GetNext-PDU 2392 An SNMP Response-PDU is constructed whose fields all contain the same 2393 values as in the SNMP Request-PDU, except that the value of each 2394 variable binding is set to 'endOfMibView'. 2396 Each variable binding in the Request-PDU is processed in order, as 2397 follows: 2399 Draft Agent Extensibility (AgentX) Protocol November 1996 2401 (1) Identify the target OID range. 2403 Within a lexicographically ordered set of OID ranges, valid for 2404 the indicated context, locate 2406 a) the OID range that contains the variable binding's name and 2407 is not a fully qualified instance, or 2409 b) the OID range that is the first lexicographical successor to 2410 the variable binding's name. 2412 (2) If no such OID range exists the variable binding is not processed 2413 further, and retains its initialized value (`endOfMibView'). 2415 (3) Identify the single subagent responsible for this OID range, 2416 termed the target subagent. 2418 (4) Determine the timeout value for this OID range, which is 2420 a) the value specified during registration of the region 2421 containing the OID range, if it was non-zero 2423 b) otherwise, the value specified during the target 2424 subagent's AgentX session establishment, if it was non-zero 2426 c) otherwise, the master agent's default value 2428 (5) If this is the first variable binding to be dispatched to the 2429 target subagent in a request/response exchange entailed in the 2430 processing of this management request: 2432 - Create an agentx-GetNext-PDU for the subagent, with 2433 the header fields initialized as described above (see 6.1 2434 AgentX PDU Header). 2436 - If the master agent has determined that a specific 2437 non-default context is associated with the Request-PDU, 2438 that context is encoded into g.context and the 2439 NON_DEFAULT_CONTEXT bit is set in h.flags. 2441 Otherwise, no context Octet String is added to the PDU, and the 2442 NON_DEFAULT_CONTEXT bit is cleared. 2444 (6) Add a SearchRange to the end of the target subagent's 2445 agentx-GetNext-PDU for this variable binding. 2447 - if (1a) applies, the variable binding's name is encoded 2448 into the starting OID, and the OID's `include' field 2449 is set to 0. 2451 - if (1b) applies, the target OID is encoded into the starting 2453 Draft Agent Extensibility (AgentX) Protocol November 1996 2455 OID, and its `include' field is set to 1. 2457 - the ending OID is encoded with the OID range that is the 2458 first lexicographical successor to the target OID range, and 2459 that was not registered by the target subagent. If no such 2460 OID range exists, it is encoded as a null OID. 2462 7.2.1.3. agentx-GetBulk-PDU 2464 (Note: The outline of the following procedure is based closely on 2465 section 4.2.3, "The GetBulkRequest-PDU" of RFC 1905 [4]. Please 2466 refer to it for details on the format of the SNMP GetBulkRequest-PDU 2467 itself.) 2469 An SNMP Response-PDU is constructed whose fields all contain the same 2470 values as in the SNMP Request-PDU. The SNMP Response-PDU contains 2471 N + (M * R) variable bindings whose values are set to `EndOfMibView', 2472 where 2474 N ("non-repeaters") is the minimum of: 2475 a) the value of the non-repeaters field in the request, and 2476 b) the number of variable bindings in the request 2478 M ("max-repetitions") is the value of the max-repetitions field 2479 in the request 2481 R ("repeaters") is the maximum of: 2482 a) (number of variable bindings in the request) - N, and 2483 b) zero 2485 Each variable binding in the Request-PDU is processed in order, as 2486 follows: 2488 (1) Identify the target OID range and target subagent, exactly as 2489 described for the agentx-GetNext-PDU (see 7.2.1.2). 2490 (2) If this is the first variable binding to be dispatched to the 2491 target subagent in a request/response exchange entailed in the 2492 processing of this management request: 2494 - Create an agentx-GetBulk-PDU for the subagent, with 2495 the header fields initialized as described above (see 6.1 2496 AgentX PDU Header). 2498 - If the master agent has determined that a specific 2499 non-default context is associated with the Request-PDU, 2500 that context is encoded into g.context and the 2501 NON_DEFAULT_CONTEXT bit is set in h.flags. 2503 Otherwise, no context Octet String is added to the PDU, and the 2504 NON_DEFAULT_CONTEXT bit is cleared. 2506 Draft Agent Extensibility (AgentX) Protocol November 1996 2508 - Set g.non_repeaters to 0. 2510 - g.max_repetitions is generally set to the max_repetitions 2511 value in the Request-PDU. However, the master agent may 2512 elect a smaller value based on the maximum possible size of a 2513 potential Response-PDU, known constraints of the AgentX 2514 transport, or any other implementation-specific constraint. 2516 (3) Add a SearchRange to the end of the target subagent's 2517 agentx-GetBulk-PDU for this variable binding, as described 2518 for the agentx-GetNext-PDU. If the variable binding was 2519 within the non_repeaters range in the original Request-PDU, 2520 increment the value of g.non_repeaters. 2522 7.2.1.4. agentx-TestSet-PDU 2524 AgentX employs the well-known test-commit-undo-cleanup phases 2525 to achieve "as if simultaneous" semantics of the SNMP SetRequest-PDU 2526 within the extensible agent. The initial phase involves 2527 the agentx-TestSet-PDU. 2529 An SNMP Response-PDU is constructed whose fields all contain the 2530 same values as in the SNMP Request-PDU. 2532 Each variable binding in the Request-PDU is processed in order, as 2533 follows: 2535 (1) Identify the target OID range. 2537 Within a lexicographically ordered set of OID ranges, valid for 2538 the indicated context, locate the range that contains the 2539 variable binding's name. 2541 (2) If no such OID range exists, the SNMP Response-PDU is modified to 2542 indicate this variable binding failed with `noAccess', and 2543 processing is complete for this request. 2545 (3) Identify the single subagent responsible for this OID range, 2546 termed the target subagent. 2548 (4) Determine the timeout value for this OID range, which is 2550 a) the value specified during registration of the region 2551 containing the OID range, if it was non-zero 2553 b) otherwise, the value specified during the target 2554 subagent's AgentX session establishment, if it was non-zero 2556 c) otherwise, the master agent's default value 2558 (5) If this is the first variable binding to be dispatched to the 2560 Draft Agent Extensibility (AgentX) Protocol November 1996 2562 target subagent in a request/response exchange entailed in the 2563 processing of this management request: 2565 - create an agentx-TestSet-PDU for the subagent, with 2566 the header fields initialized as described above (see 6.1 2567 AgentX PDU Header). 2569 - If the master agent has determined that a specific 2570 non-default context is associated with the Request-PDU, 2571 that context is encoded into t.context and the 2572 NON_DEFAULT_CONTEXT bit is set in h.flags. 2574 Otherwise, no context Octet String is added to the PDU, and the 2575 NON_DEFAULT_CONTEXT bit is cleared. 2577 (6) Add a VarBind to the end of the target subagent's PDU 2578 for this variable binding, as described in section 5.4. 2580 7.2.1.5. Dispatch 2582 A timeout value is calculated for each PDU to be sent, 2583 which is the maximum value of the timeouts associated for each of the 2584 PDU's SearchRanges (as described above). 2586 7.2.2. Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs 2588 When a subagent receives an agentx-Get-, GetNext-, or GetBulk-PDU, it 2589 performs the indicated management operations and returns an 2590 agentx-Response-PDU. 2592 The agentx-Response-PDU header fields are identical to the received 2593 request PDU except that, at the start of processing, the subagent 2594 initializes h.type to Response, res.error to `noError', 2595 res.error_index to 0, and the VarBindList to null. 2597 Each SearchRange in the request PDU's SearchRangeList is processed as 2598 described below, and a VarBind is added in the corresponding 2599 location of the agentx-Response-PDU's VarbindList. If processing 2600 should fail for any reason not described below, res.error is set to 2601 `genErr', res.error_index to the index of the failed SearchRange, 2602 the VarBindList is reset to null, and this agentx-Response-PDU is 2603 returned to the master agent. 2605 Draft Agent Extensibility (AgentX) Protocol November 1996 2607 7.2.2.1. Subagent Processing of the agentx-Get-PDU 2609 Upon the subagent's receipt of an agentx-Get-PDU, each SearchRange 2610 in the request is processed as follows: 2612 (1) The starting OID is copied to v.name. 2614 (2) If the starting OID exactly matches the name of a 2615 variable instantiated by this subagent within the indicated 2616 context, v.type and v.data are encoded to represent 2617 the variable's syntax and value, as described in section 5.4, 2618 Value Representation. 2620 (3) Otherwise, if the starting OID does not match the object 2621 identifier prefix of any variable instantiated within the 2622 indicated context, the VarBind is set to `noSuchObject', 2623 in the manner described in section 5.4, Value Representation. 2625 (4) Otherwise, the VarBind is set to `noSuchInstance' 2626 in the manner described in section 5.4, Value Representation. 2628 7.2.2.2. Subagent Processing of the agentx-GetNext-PDU 2630 Upon the subagent's receipt of an agentx-GetNext-PDU, each 2631 SearchRange in the request is processed as follows: 2633 (1) The subagent searches for a variable within the 2634 lexicographically ordered list of variable names for all 2635 variables it instantiates (without regard to registration of 2636 regions) within the indicated context, for which the following 2637 are all true: 2639 - if the `include' field of the starting OID is 0, the 2640 variable's name is the closest lexicographical successor to 2641 the starting OID. 2643 - if the `include' field of the starting OID is 1, the 2644 variable's name is either equal to, or the closest 2645 lexicographical successor to, the starting OID. 2647 - If the ending OID is not null, the variable's name 2648 lexicographically precedes the ending OID. 2650 If all of these conditions are met, v.name is set to the 2651 located variable's name. v.type and v.data are encoded to 2652 represent the variable's syntax and value, as described in 2653 section 5.4, Value Representation. 2655 (2) If no such variable exists, v.name is set to the starting OID, 2656 and the VarBind is set to `endOfMibView', in the manner described 2657 in section 5.4, Value Representation. 2659 Draft Agent Extensibility (AgentX) Protocol November 1996 2661 7.2.2.3. Subagent Processing of the agentx-GetBulk-PDU 2663 A maximum of N + (M * R) VarBinds are returned, where 2665 N equals g.non_repeaters, 2667 M equals g.max_repetitions, and 2669 R is (number of SearchRanges in the GetBulk request) - N. 2671 The first N SearchRanges are processed exactly as for the 2672 agentx-GetNext-PDU. 2674 If M and R are both non-zero, the remaining R SearchRanges are 2675 processed iteratively to produce potentially many VarBinds. For 2676 each iteration i, such that i is greater than zero and less than or 2677 equal to M, and for each repeated SearchRange s, such that s is 2678 greater than zero and less than or equal to R, the 2679 (N+((i-1)*R)+s)-th VarBind is added to the agentx-Response-PDU 2680 as follows: 2682 1) The subagent searches for a variable within the 2683 lexicographically ordered list of variable names for all 2684 variables it instantiates (without regard to registration of 2685 regions) within the indicated context, for which the following 2686 are all true: 2688 - The variable's name is the (i)-th lexicographical successor 2689 to the (N+s)-th requested OID. 2691 (Note that if i is 0 and the `include' field is 1, the 2692 variable's name may be equivalent to, or the first 2693 lexicographical successor to, the (N+s)-th requested OID.) 2695 - If the ending OID is not null, the variable's name 2696 lexicographically precedes the ending OID. 2698 If all of these conditions are met, v.name is set to the 2699 located variable's name. v.type and v.data are 2700 encoded to represent the variable's syntax and value, as 2701 described in section 5.4, Value Representation. 2703 2) If no such variable exists, the VarBind is set to 2704 `endOfMibView' as described in section 5.4, Value 2705 Representation. v.name is set to v.name of the 2706 (N+((i-2)*R)+s)-th VarBind unless i is currently 1, in which 2707 case it is set to the value of the starting OID in the (N+s)-th 2708 SearchRange. 2710 Draft Agent Extensibility (AgentX) Protocol November 1996 2712 Note that further iterative processing should stop if 2714 - For any iteration i, all s values of v.type are 2715 `endOfMibView'. 2717 - An AgentX transport constraint or other 2718 implementation-specific constraint is reached. 2720 7.2.3. Subagent Processing of agentx-TestSet, -CommitSet, -UndoSet, 2721 -CleanupSet-PDUs 2723 These four PDUs are used to collectively perform the indicated 2724 management operation. An agentx-Response-PDU is sent in reply to 2725 each of the PDUs, to inform the master agent of the state of the 2726 operation. 2728 The agentx-Response-PDU header fields are identical to the received 2729 request PDU except that, at the start of processing, the subagent 2730 initializes h.type to Response, res.error to `noError', and 2731 res.error_index to 0. 2733 These Response-PDUs do not contain a VarBindList. 2735 Draft Agent Extensibility (AgentX) Protocol November 1996 2737 7.2.3.1. Subagent Processing of the agentx-TestSet-PDU 2739 Upon the subagent's receipt of an agentx-TestSet-PDU, each VarBind 2740 in the PDU is validated until they are all successful, or until 2741 one fails, as described in section 4.2.5 of RFC 1905 [4]. 2743 If each VarBind is successful, the subagent has a further 2744 responsibility to ensure the availability of all resources (memory, 2745 write access, etc.) required for successfully carrying out a 2746 subsequent agentx-CommitSet operation. If this cannot be guaranteed, 2747 the subagent should set res.error to resourceUnavailable(13). 2749 As a result of this validation step, an agentx-Response-PDU 2750 is sent in reply whose res.error field is set to one of the 2751 following (SNMPv2 SMI) values: 2753 noError (0), 2754 genErr (5), 2755 noAccess (6), 2756 wrongType (7), 2757 wrongLength (8), 2758 wrongEncoding (9), 2759 wrongValue (10), 2760 noCreation (11), 2761 inconsistentValue (12), 2762 resourceUnavailable (13), 2763 notWritable (17), 2764 inconsistentName (18) 2766 If this value is not noError(0), the res.index field must be 2767 set to the index of the VarBind for which validation failed. 2769 Implementation of rigorous validation code may be one of the 2770 most demanding aspects of subagent development. Implementors 2771 are strongly encouraged to do this right, so as to avoid if at 2772 all possible the extensible agent's having to return "commitFailed" 2773 or "undoFailed" during subsequent processing. 2775 Draft Agent Extensibility (AgentX) Protocol November 1996 2777 7.2.3.2. Subagent Processing of the agentx-CommitSet-PDU 2779 The agentx-CommitSet-PDU indicates that the subagent should actually 2780 perform (as described in the post-validation sections of 4.2.5 of 2781 RFC 1905 [4]) the management operation indicated by the previous 2782 TestSet-PDU. 2784 After carrying out the management operation, the subagent sends in 2785 reply an agentx-Response-PDU whose res.error field is set to one of 2786 the following (SNMPv2 SMI) values: 2788 noError (0), 2789 commitFailed (14) 2791 If this value is commitFailed(14), the res.index field must be 2792 set to the index of the VarBind for which the operation failed. 2793 Otherwise res.index is set to 0. 2795 7.2.3.3. Subagent Processing of the agentx-UndoSet-PDU 2797 The agentx-UndoSet-PDU indicates that the subagent should undo 2798 the management operation requested in a preceding CommitSet-PDU. 2799 The undo process is as described in section 4.2.5 of RFC 1905 2800 [4]. 2802 After carrying out the undo process, the subagent sends in reply an 2803 agentx-Response-PDU whose res.index field is set to 0, and whose 2804 res.error field is set to one of the following (SNMPv2 SMI) values: 2806 noError (0), 2807 undoFailed (15) 2809 This ends subagent processing of the management request. 2811 7.2.3.4. Subagent Processing of the agentx-CleanupSet-PDU 2813 The agentx-CleanupSet-PDU signals the end of processing of the 2814 management operation requested in the previous CommitSet-PDU. This 2815 is an indication to the subagent that it may now release any 2816 resources it may have reserved in order to carry out the management 2817 request. 2819 No response is sent by the subagent. 2821 7.2.4. Master Agent Processing of AgentX Responses 2823 The master agent now marshals all subagent agentx-Response-PDUs and 2824 builds an SNMP Response-PDU. In the next several sub-sections, the 2825 initial processing of all subagent agentx-Response-PDUs is 2826 described, followed by descriptions of subsequent processing 2827 for each specific subagent Response. 2829 Draft Agent Extensibility (AgentX) Protocol November 1996 2831 7.2.4.1. Common Processing of All AgentX Response PDUs 2833 1) If a subagent does not respond within the timeout interval for 2834 this dispatch, it is treated as if the subagent had returned 2835 `genErr' and processed as described below. 2837 A timeout may be due to a variety of reasons, and does 2838 not necessarily denote a failed or malfunctioning 2839 subagent. As such, the master agent's response to a 2840 subagent timeout is implementation-specific, but with the 2841 following constraint: 2843 A subagent that times out on three consecutive requests 2844 is considered unable to respond, and the master agent 2845 must close the AgentX session as described in 2846 7.1.9, step (2). 2848 2) Otherwise, if the h.ID field of an agentx-Response-PDU does not 2849 match that of the request PDU sent to this subagent, the PDU is 2850 ignored. 2852 3) Otherwise, the responses are processed jointly to form the SNMP 2853 Response-PDU. 2855 7.2.4.2. Processing of Responses to agentx-Get-PDUs 2857 After common processing of the subagent's response to an 2858 agentx-Get-PDU (see 7.2.4.1 above), processing continues with 2859 the following steps: 2861 1) For any received agentx-Response-PDU, if res.error is not 2862 `noError', the SNMP response PDU's error code is set to this 2863 value, and its error index to the index of the variable binding 2864 corresponding to the failed VarBind in the subagent's 2865 agentx-Response-PDU. 2867 All other agentx-Response-PDUs received due to processing this 2868 SNMP Request are ignored. Processing is complete; the SNMP 2869 Response PDU is ready to be sent (see section 7.2.5, Sending 2870 the SNMP Response-PDU). 2872 2) Otherwise, the content of each VarBind in the agentx-Response-PDU 2873 is used to update the corresponding variable binding in the SNMP 2874 Response-PDU. 2876 Draft Agent Extensibility (AgentX) Protocol November 1996 2878 7.2.4.3. Processing of Responses to agentx-GetNext- and 2879 agentx-GetBulk-PDUs 2881 After common processing of the subagent's response to an 2882 agentx-GetNext-PDU or agentx-GetBulk-PDU (see 7.2.4.1 above), 2883 processing continues with the following steps: 2885 1) For any received agentx-Response-PDU, if res.error is not 2886 `noError', the SNMP response PDU's error code is set to this 2887 value, and its error index to the index of the variable binding 2888 corresponding to the failed VarBind in the subagent's 2889 agentx-Response-PDU. 2891 All other agentx-Response-PDUs received due to processing this 2892 SNMP Request are ignored. Processing is complete; the SNMP 2893 Response PDU is ready to be sent (see section 7.2.5, Sending 2894 the SNMP Response-PDU). 2896 2) Otherwise, the content of each VarBind in the agentx-Response-PDU 2897 is used to update the corresponding variable binding in the SNMP 2898 Response-PDU. 2900 After all expected agentx-Response-PDUs have been processed, if any 2901 variable bindings still contain the value `endOfMibView', processing 2902 must continue: 2904 3) For each such variable binding, a target OID range is 2905 identified which is the lexicographical successor to the 2906 target OID range for this variable binding on the last 2907 iteration. The target subagent is the one that registered 2908 the target OID range. 2910 4) If this is the first variable binding to be dispatched to the 2911 target subagent in this request/response exchange, create an 2912 agentx-GetNext or GetBulk-PDU for the subagent, with the 2913 header and context fields initialized as described previously 2914 for these PDUs. 2916 5a) For responses to agentx-GetNext-PDUs: 2918 i) Add a SearchRange to the end of the target subagent's 2919 PDU for this variable binding. The starting OID is set 2920 to the target OID range, and its `include' field is set to 1. 2921 The ending OID is set to the OID range that is the first 2922 lexicographical successor to the target OID range, and that 2923 was not registered by the target subagent. If no such 2924 OID range exists, the ending OID is set to null. 2926 Draft Agent Extensibility (AgentX) Protocol November 1996 2928 5b) For responses to agentx-GetBulk-PDUs: 2930 i) Set the value of g.non_repeaters and g.max_repetitions 2931 to 0. 2933 ii) Add a SearchRange to the end of the target subagent's 2934 PDU for this variable binding. The starting OID is set 2935 to the target OID range, and its `include' field is set to 1. 2936 The ending OID is set to the OID range that is the first 2937 lexicographical successor to the target OID range, and that 2938 was not registered by the target subagent. If no such 2939 OID range exists, the ending OID is set to null. 2941 iii) If the variable binding was within the non_repeaters range 2942 in the original Request-PDU, increment the value of 2943 g.non_repeaters. 2945 Otherwise, set the value of g.max_repetitions to the 2946 maximum of its current value, or the number of response 2947 variable bindings still required for this requested 2948 variable binding. 2950 6) The AgentX PDUs are sent to the subagent(s), and the responses 2951 are received and processed according to the steps described in 2952 section 7.2.4. 2954 7) This process continues iteratively until a complete SNMP 2955 Response-PDU has been built, or until there remain no 2956 target OID range lexicographical successors. 2958 << 2959 << TBD: Include example 2960 << 2962 7.2.4.4. Processing of Responses to agentx-TestSet-PDUs 2964 After common processing of the subagent's response to an 2965 agentx-TestSet-PDU (see 7.2.4.1 above), processing continues with the 2966 following steps: 2968 1) If any target subagent's response is not `noError', all other 2969 agentx-Response-PDUs received due to processing this SNMP 2970 Request are ignored. 2972 An agentx-CleanupSet-PDU is sent to each target subagent. 2974 Processing is complete; the SNMP Response-PDU is constructed as 2975 described below in 7.2.4.6, step (2). 2977 2) Otherwise an agentx-CommitSet-PDU is sent to each target 2978 subagent. 2980 Draft Agent Extensibility (AgentX) Protocol November 1996 2982 7.2.4.5. Processing of Responses to agentx-CommitSet-PDUs 2984 After common processing of the subagent's response to an 2985 agentx-CommitSet-PDU (see 7.2.4.1 above), processing continues with 2986 the following steps: 2988 1) If any response is not `noError', all other 2989 agentx-Response-PDUs received due to processing this SNMP 2990 Request are ignored. 2992 An agentx-UndoSet-PDU is sent to each target subagent. 2994 2) Otherwise an agentx-CleanupSet-PDU is sent to each target 2995 subagent. Processing is complete; the SNMP Response-PDU is 2996 constructed as described below in 7.2.4.6, step (2). 2998 7.2.4.6. Processing of Responses to agentx-UndoSet-PDUs 3000 After common processing of the subagent's response to an 3001 agentx-UndoSet-PDU (see 7.2.4.1 above), processing continues with the 3002 following steps: 3004 1) An agentx-CleanupSet-PDU is sent to each target subagent. 3006 2) If any response is not `noError' the SNMP response 3007 PDU's error code is set to this value, and its error index to the 3008 index of the variable binding corresponding to the failed VarBind 3009 in the agentx-TestSet-PDU. 3011 Otherwise the SNMP Response-PDU's error code is set to `noError' 3012 and its error index to 0. 3014 7.2.5. Sending the SNMP Response-PDU 3016 Once the processing described in sections 7.2.1 - 7.2.4 is 3017 complete, there is an SNMP Response-PDU available. The master agent 3018 now implements the Elements of Procedure for the applicable version 3019 of the SNMP protocol in order to encapsulate the PDU into a message, 3020 and transmit it to the originator of the SNMP management request. 3022 Note that this may involve altering the PDU contents (for instance, 3023 to replace the original variable bindings if an error condition is 3024 to be returned). 3026 The Response-PDU may also be altered in order to support the SNMP 3027 version 1 framework. In such cases the required mapping is that 3028 defined in FYI V2ToV1 [9]. (Note in particular that the rules for 3029 handling Counter64 syntax may require resending AgentX GetBulk or 3030 GetNext PDUs until a VarBind of suitable syntax is returned.) 3032 Draft Agent Extensibility (AgentX) Protocol November 1996 3034 7.2.6. MIB Views 3036 AgentX subagents are not aware of MIB views, since view information 3037 is not contained in AgentX PDUs. 3039 As stated above, the descriptions of procedures in section 7 of this 3040 memo are not intended to constrain the internal architecture of any 3041 conformant implementation. In particular, the master agent 3042 procedures described in sections 7.2.1 and 7.2.4 may be altered so 3043 as to optimize AgentX exchanges when implementing MIB views. 3045 Such optimizations are beyond the scope of this memo. But note that 3046 section 7.2.3 defines subagent behavior in such a way that alteration 3047 of SearchRanges may be used in such optimizations. 3049 8. Transport Mappings 3051 The same AgentX PDU formats, encodings, and elements of procedure 3052 are used regardless of the underlying transport. 3054 8.1. AgentX over TCP 3056 8.1.1. Well-known Values 3058 The master agent accepts TCP connection requests for the well-known 3059 port [TBD]. Subagents connect to the master agent using this 3060 port number. 3062 8.1.2. Operation 3064 Once a TCP connection has been established, the AgentX peers use 3065 this connection to carry all AgentX PDUs. Only a single logical 3066 connection may be established per transport connection. 3068 All AgentX PDUs are presented individually to the TCP, to be sent as 3069 the data portion of a TCP PDU. 3071 8.2. AgentX over UNIX-domain Sockets 3073 Many (BSD-derived) implementations of the UNIX operating system 3074 support the UNIX pathname address family (AF_UNIX) for socket 3075 communications. This provides a convenient method of sending and 3076 receiving data between processes on the same host. 3078 Mapping AgentX to this transport is useful for environments that 3080 - wish to guarantee subagents are running on the same 3081 managed node as the master agent, and where 3083 - sockets provide better performance than TCP or UDP, 3085 Draft Agent Extensibility (AgentX) Protocol November 1996 3087 especially in the presence of heavy network I/O 3089 8.2.1. Well-known Values 3091 The master agent creates a well-known UNIX-domain socket endpoint 3092 called "var/agentx/master". (It may create other, 3093 implementation-specific endpoints.) 3095 This endpoint name uses the character set encoding native to the 3096 managed node, and represents a UNIX-domain stream (SOCK_STREAM) 3097 socket. 3099 8.2.2. Operation 3101 Once a connection has been established, the AgentX peers use 3102 this connection to carry all AgentX PDUs. Only a single logical 3103 connection may be established per transport connection. 3105 All AgentX PDUs are presented individually to the socket layer, to 3106 be sent in the data stream. 3108 9. Security Considerations 3110 This memo defines a protocol between two processing entities, one of 3111 which (the master agent) is also assumed to perform authentication 3112 of received SNMP requests and to control access to management 3113 information. The master agent performs these security operations 3114 independently of the other processing entity (the subagent). 3116 Thus, security issues are outside the scope of this protocol 3117 definition. 3119 10. Acknowledgements 3121 The initial draft of this memo was heavily influenced by the DPI 3122 2.0 specification RFC 1592 [7]. 3124 This document was produced by the IETF Agent Extensibility 3125 (AgentX) Working Group, and benefited especially from the 3126 contributions of the following working group members: 3128 David Battle, Uri Blumenthal, Jeff Case, Maria Greene, 3129 Dave Keeney, Harmen van der Linde, Bob Natale, Randy Presuhn, 3130 Aleksey Romanov, Don Ryan, and Juergen Schoenwaelder. 3132 Draft Agent Extensibility (AgentX) Protocol November 1996 3134 11. Questions and Issues 3136 11.1 Design 3138 The consensus is to proceed with multiple variables per PDU. If we 3139 need to go back and revisit this, the thinking is to provide a 3140 choice at connection time, allowing the subagent to choose either one 3141 varbind per PDU or all varbinds per PDU. 3143 11.2 Miscellaneous Issues/Decisions 3145 1) How to transfer binary OIDs? 3147 The current encoding is unchanged in this version 3148 of this memo. 3150 2) Unionized registrations 3152 Removed by consensus in this version. 3154 3) Contexts 3156 Consensus was to remove "all". It's either the default, 3157 or non-default. Non-default is an Octet String of any length 3158 (including 0). 3160 4) sysUpTime 3162 Returned with the response to an Open or Register PDU. 3163 For Register, it's the value within the specified context. 3165 5) sysORTable 3167 This information moved to specific PDUs. 3169 6) SNMP version in the AgentX header 3171 Removed by consensus in this version. 3173 7) Options 3175 The following optional features are allowed by this memo. 3176 The decision of whether or not to support these features 3177 is implementation specific. 3179 Master agent: 3181 - Supporting non-default contexts 3183 - Supporting next-available-index allocation for 3184 non-integer indexes 3186 Draft Agent Extensibility (AgentX) Protocol November 1996 3188 Subagent: 3190 none 3192 8) Index allocation 3194 - There is currently no *guaranteed* mechanism for a 3195 subagent that closes its AgentX session to re-connect 3196 and acquire the previously allocated indexes. Is this a 3197 problem? 3199 9) States 3201 Haven't specified any yet; may need Test/Commit/Undo/cleanup to 3202 finish before other requests are forwarded to a subagent? 3204 10) SNMP request identifier 3206 In the normal case, AgentX processing results in a single agentx 3207 PDU being sent to any particular subagent while processing an 3208 SNMP request. It is possible however for a subagent to receive 3209 multiple PDUs during the processing of a single SNMP request. 3210 (Subs A and B each are dispatched to while processing a request. 3211 A returns endOfMibView for a variable and when the variable is 3212 redispatched, it get sent to B.) 3214 There is currently no information carried in AgentX that would 3215 inform the subagent that this PDU is part of processing the same 3216 SNMP request that a previous PDU was. 3218 We're not sure that this is an issue. Possible solutions 3219 discussed were: 3221 1) Add a request-id field to the request PDUs. 3223 2) Structure h.ID so that the first 3 bytes are unique packet 3224 ids, and the last byte counts the number of PDUs sent to a 3225 particular subagent per SNMP request. Thus h.ID is still 3226 always unique per packet, but carries an implicit notion of 3227 SNMP request id. 3229 3) Use a bit in h.flags to indicate NEW_SNMP_REQUEST or 3230 SAME_SNMP_REQUEST. (Won't work for master agents that 3231 service multiple SNMP requests concurrently.) 3233 11) Session ID 3235 We don't carry a session/connection identifier in the protocol. 3236 It's not an issue currently, because transports we've provided 3237 mappings for are connection oriented, and we've specified a 3238 single session per transport connection. So AgentX peers can map 3240 Draft Agent Extensibility (AgentX) Protocol November 1996 3242 transport information -> session. 3244 Mapping transport info -> AgentX sessions can be done for other 3245 transports as well (UDP, shared memory, etc.). So it seems like 3246 the use of a session identifier would ultimately be to support 3247 multiple AgentX sessions on a single transport connection (as in 3248 HTTP). 3250 From Don Ryan: 3252 The reason I added the Connection Identifier was to separate 3253 the subagent logical connection and transport connection. 3254 This allows connectionless protocol support but also helps 3255 limit the number of connections a subagent shim needs to 3256 open. Each connection to the shim can be represented as a 3257 logical connection to the AgentX master agent piggybacking on 3258 the same transport connection. I found it very useful myself. 3260 12) Traps 3262 What traps (if any) should be generated when subagents open/close 3263 or modify sysORTable? 3265 11.3 New in this version 3267 1) Octet String 3269 A specific encoding rule for octet strings. 3271 2) NETWORK_BYTE_ORDER bit 3273 Subagent declares its preferred (native) ordering in 3274 the Open-PDU. 3276 3) IndexDeallocate-PDU and "new vs. any" semantics for allocation 3277 requests. 3279 4) AddAgentCaps and RemoveAgentCaps PDUs for transmitting 3280 sysORTable information. 3282 5) Added (DPI) reason codes for Close-PDU. 3284 6) Removed reason code from Unregister-PDU. 3286 Draft Agent Extensibility (AgentX) Protocol November 1996 3288 12. Authors' and Editor's Addresses 3290 Mike Daniele 3291 Digital Equipment Corporation 3292 110 Spit Brook Rd 3293 Nashua, NH 03062 3295 EMail: daniele@zk3.dec.com 3297 Bert Wijnen 3298 IBM Professional Services 3299 Watsonweg 2 3300 1423 ND Uithoorn 3301 The Netherlands 3303 Phone: +31-79-322-8316 3304 EMail: wijnen@vnet.ibm.com 3306 Dale Francisco (editor) 3307 Cisco Systems 3308 150 Castilian Dr 3309 Goleta CA 93117 3311 Phone: +1-805-961-3642 3312 Fax: +1-805-961-3600 3313 EMail: dfrancis@cisco.com 3315 13. References 3317 [1] Information processing systems - Open Systems Interconnection - 3318 Specification of Abstract Syntax Notation One (ASN.1), 3319 International Organization for Standardization. International 3320 Standard 8824, (December, 1987). 3322 [2] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3323 S. Waldbusser, "Structure of Management Information for Version 2 3324 of the Simple Network Management Protocol (SNMPv2)", RFC 1902, 3325 January 1996. 3327 [3] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3328 S. Waldbusser, "Textual Conventions for Version 2 of the Simple 3329 Network Management Protocol (SNMPv2)", RFC 1903, January 1996. 3331 [4] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3332 S. Waldbusser, "Protocol Operations for Version 2 of the Simple 3333 Network Management Protocol (SNMPv2)", RFC 1905, January 1996. 3335 [5] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3336 Draft Agent Extensibility (AgentX) Protocol November 1996 3338 S. Waldbusser, "Management Information Base for Version 2 of the 3339 Simple Network Management Protocol (SNMPv2)", RFC 1907, 3340 January 1996. 3342 [6] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network 3343 Management Protocol", STD 15, RFC 1157, SNMP Research, Performance 3344 Systems International, MIT Laboratory for Computer Science, May 3345 1990. 3347 [7] Wijnen, B., Carpenter, G., Curran, K., Sehgal, A., and G. Waters, 3348 "Simple Network Management Protocol: Distributed Protocol 3349 Interface, Version 2.0", RFC 1592, T.J. Watson Research Center, 3350 IBM Corp., Bell Northern Research, Ltd., March 1994. 3352 [8] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3353 S. Waldbusser, "Coexistence between Version 1 and Version 2 of the 3354 Internet-standard Network Management Framework", RFC 1908, 3355 January 1996. 3357 [9] Wijnen, B., and Levi, D., "V2ToV1: Mapping SNMPv2 onto SNMPv1 3358 Within a Bilingual SNMP Agent", FYI ???, T.J. Watson Research 3359 Center, IBM Corp., SNMP Research, Inc., August 1996. 3361 [10] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and 3362 S. Waldbusser, "Conformance Statements for Version 2 of the 3363 Simple Network Management Protocol (SNMPv2)", RFC 1904, 3364 January 1996. 3366 [11] Interfaces MIB Working Group, McCloghrie, K., and F. Kastenholz, 3367 "Evolution of the Interfaces Group of MIB-II", RFC 1573, 3368 January 1994. 3370 [12] FDDI MIB Working Group, J. Case, "FDDI Management Information 3371 Base", RFC 1285, January 1992. 3373 [13] Application MIB Working Group, Krupczak, C., and J. Saperia, 3374 "Definitions of Managed Objects for Applications", 3375 draft-ietf-applmib-sysapplmib-05.txt, 11 Nov 1996. 3377 Draft Agent Extensibility (AgentX) Protocol November 1996