Network Working Group M. Daniele Request for Comments: 2741 Compaq Computer Corporation Obsoletes: 2257 B. Wijnen Category: Standards Track T.J. Watson Research Center, IBM Corp. M. Ellison, Ed. Ellison Software Consulting, Inc. D. Francisco. Ed. Cisco Systems, Inc. January 2000 Agent Extensibility (AgentX) Protocol Version 1 Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract This memo defines a standardized framework for extensible SNMP agents. It defines processing entities called master agents and subagents, a protocol (AgentX) used to communicate between them, and the elements of procedure by which the extensible agent processes SNMP protocol messages. This memo obsoletes RFC 2257. Table of Contents 1. Introduction.....................................................4 2. The SNMP Management Framework....................................4 2.1. A Note on Terminology........................................5 3. Extending the MIB................................................5 3.1. Motivation for AgentX........................................6 4. AgentX Framework.................................................6 4.1. AgentX Roles.................................................7 4.2. Applicability................................................8 4.3. Design Features of AgentX....................................9 4.4. Non-Goals...................................................10 Daniele, et al. Standards Track [Page 1] RFC 2741 AgentX January 2000 5. AgentX Encodings................................................11 5.1. Object Identifier...........................................11 5.2. SearchRange.................................................13 5.3. Octet String................................................14 5.4. Value Representation........................................15 6. Protocol Definitions............................................17 6.1. AgentX PDU Header...........................................17 6.1.1. Context.................................................20 6.2. AgentX PDUs.................................................20 6.2.1. The agentx-Open-PDU.....................................20 6.2.2. The agentx-Close-PDU....................................22 6.2.3. The agentx-Register-PDU.................................23 6.2.4. The agentx-Unregister-PDU...............................27 6.2.5. The agentx-Get-PDU......................................29 6.2.6. The agentx-GetNext-PDU..................................30 6.2.7. The agentx-GetBulk-PDU..................................32 6.2.8. The agentx-TestSet-PDU..................................34 6.2.9. The agentx-CommitSet, -UndoSet, -CleanupSet PDUs........35 6.2.10. The agentx-Notify-PDU..................................36 6.2.11. The agentx-Ping-PDU....................................37 6.2.12. The agentx-IndexAllocate-PDU...........................37 6.2.13. The agentx-IndexDeallocate-PDU.........................38 6.2.14. The agentx-AddAgentCaps-PDU............................39 6.2.15. The agentx-RemoveAgentCaps-PDU.........................41 6.2.16. The agentx-Response-PDU................................43 7. Elements of Procedure...........................................45 7.1. Processing AgentX Administrative Messages...................45 7.1.1. Processing the agentx-Open-PDU..........................46 7.1.2. Processing the agentx-IndexAllocate-PDU.................47 7.1.3. Processing the agentx-IndexDeallocate-PDU...............49 7.1.4. Processing the agentx-Register-PDU......................50 7.1.4.1. Handling Duplicate and Overlapping Subtrees.........50 7.1.4.2. Registering Stuff...................................51 7.1.4.2.1. Registration Priority...........................51 7.1.4.2.2. Index Allocation................................51 7.1.4.2.3. Examples........................................53 7.1.5. Processing the agentx-Unregister-PDU....................55 7.1.6. Processing the agentx-AddAgentCaps-PDU..................55 7.1.7. Processing the agentx-RemoveAgentCaps-PDU...............55 7.1.8. Processing the agentx-Close-PDU.........................56 7.1.9. Detecting Connection Loss...............................56 7.1.10. Processing the agentx-Notify-PDU.......................56 7.1.11. Processing the agentx-Ping-PDU.........................57 7.2. Processing Received SNMP Protocol Messages..................58 7.2.1. Dispatching AgentX PDUs.................................58 7.2.1.1. agentx-Get-PDU......................................61 7.2.1.2. agentx-GetNext-PDU..................................61 7.2.1.3. agentx-GetBulk-PDU..................................62 Daniele, et al. Standards Track [Page 2] RFC 2741 AgentX January 2000 7.2.1.4. agentx-TestSet-PDU..................................63 7.2.1.5. Dispatch............................................64 7.2.2. Subagent Processing.....................................64 7.2.3. Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs65 7.2.3.1. Subagent Processing of the agentx-Get-PDU...........65 7.2.3.2. Subagent Processing of the agentx-GetNext-PDU.......66 7.2.3.3. Subagent Processing of the agentx-GetBulk-PDU.......66 7.2.4. Subagent Processing of agentx-TestSet, -CommitSet, -UndoSet, -CleanupSet-PDUs..............................67 7.2.4.1. Subagent Processing of the agentx-TestSet-PDU.......68 7.2.4.2. Subagent Processing of the agentx-CommitSet-PDU.....69 7.2.4.3. Subagent Processing of the agentx-UndoSet-PDU.......69 7.2.4.4. Subagent Processing of the agentx-CleanupSet-PDU....70 7.2.5. Master Agent Processing of AgentX Responses.............70 7.2.5.1. Common Processing of All AgentX Response PDUs.......70 7.2.5.2. Processing of Responses to agentx-Get-PDUs..........70 7.2.5.3. Processing of Responses to agentx-GetNext-PDU and agentx-GetBulk-PDU..................................71 7.2.5.4. Processing of Responses to agentx-TestSet-PDUs......72 7.2.5.5. Processing of Responses to agentx-CommitSet-PDUs....73 7.2.5.6. Processing of Responses to agentx-UndoSet-PDUs......74 7.2.6. Sending the SNMP Response-PDU...........................74 7.2.7. MIB Views...............................................74 7.3. State Transitions...........................................75 7.3.1. Set Transaction States..................................75 7.3.2. Transport Connection States.............................77 7.3.3. Session States..........................................78 8. Transport Mappings..............................................79 8.1. AgentX over TCP.............................................79 8.1.1. Well-known Values.......................................79 8.1.2. Operation...............................................79 8.2. AgentX over UNIX-domain Sockets.............................80 8.2.1. Well-known Values.......................................80 8.2.2. Operation...............................................80 9. Security Considerations.........................................81 10. Acknowledgements...............................................82 11. Authors' and Editor's Addresses................................83 12. References.....................................................84 13. Notices........................................................86 Appendix A. Changes relative to RFC 2257 ..........................87 Full Copyright Statement ..........................................91 Daniele, et al. Standards Track [Page 3] RFC 2741 AgentX January 2000 1. Introduction This memo defines a standardized framework for extensible SNMP agents. It defines processing entities called master agents and subagents, a protocol (AgentX) used to communicate between them, and the elements of procedure by which the extensible agent processes SNMP protocol messages. This memo obsoletes RFC 2257. It is worth noting that most of the changes are for the purpose of clarification. The only changes affecting AgentX protocol messages on the wire are: - The agentx-Notify-PDU and agentx-Close-PDU now generate an agentx-Response-PDU - Three new error codes are available: parseFailed(266), requestDenied(267), and processingError(268) Appendix A provides a detailed list of changes relative to RFC 2257. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [27]. 2. The SNMP Management Framework The SNMP Management Framework presently consists of five major components: An overall architecture, described in RFC 2571 [1]. Mechanisms for describing and naming objects and events for the purpose of management. The first version of this Structure of Management Information (SMI) is called SMIv1 and described in STD 16, RFC 1155 [2], STD 16, RFC 1212 [3] and RFC 1215 [4]. The second version, called SMIv2, is described in STD 58, RFC 2578 [5], STD 58, RFC 2579 [6] and STD 58, RFC 2580 [7]. Message protocols for transferring management information. The first version of the SNMP message protocol is called SNMPv1 and described in STD 15, RFC 1157 [8]. A second version of the SNMP message protocol, which is not an Internet standards track protocol, is called SNMPv2c and described in RFC 1901 [9] and RFC 1906 [10]. The third version of the message protocol is called SNMPv3 and described in RFC 1906 [10], RFC 2572 [11] and RFC 2574 [12]. Protocol operations for accessing management information. The first set of protocol operations and associated PDU formats is described in Daniele, et al. Standards Track [Page 4] RFC 2741 AgentX January 2000 STD 15, RFC 1157 [8]. A second set of protocol operations and associated PDU formats is described in RFC 1905 [13]. A set of fundamental applications described in RFC 2573 [14] and the view-based access control mechanism described in RFC 2575 [15]. A more detailed introduction to the current SNMP Management Framework can be found in RFC 2570 [16]. Managed objects are accessed via a virtual information store, termed the Management Information Base or MIB. Objects in the MIB are defined using the mechanisms defined in the SMI. 2.1. A Note on Terminology The term "variable" refers to an instance of a non-aggregate object type defined according to the conventions set forth in the SMIv2 (STD 58, RFC 2578, [5]) or the textual conventions based on the SMIv2 (STD 58, RFC 2579 [6]). The term "variable binding" normally refers to the pairing of the name of a variable and its associated value. However, if certain kinds of exceptional conditions occur during processing of a retrieval request, a variable binding will pair a name and an indication of that exception. A variable-binding list is a simple list of variable bindings. The name of a variable is an OBJECT IDENTIFIER, which is the concatenation of the OBJECT IDENTIFIER of the corresponding object type together with an OBJECT IDENTIFIER fragment identifying the instance. The OBJECT IDENTIFIER of the corresponding object-type is called the OBJECT IDENTIFIER prefix of the variable. 3. Extending the MIB New MIB modules that extend the Internet-standard MIB are continuously being defined by various IETF working groups. It is also common for enterprises or individuals to create or extend enterprise-specific or experimental MIBs. As a result, managed devices are frequently complex collections of manageable components that have been independently installed on a managed node. Each component provides instrumentation for the managed objects defined in the MIB module(s) it implements. The SNMP framework does not describe how the set of managed objects supported by a particular agent may be changed dynamically. Daniele, et al. Standards Track [Page 5] RFC 2741 AgentX January 2000 3.1. Motivation for AgentX This very real need to dynamically extend the management objects within a node has given rise to a variety of "extensible agents", which typically comprise - a "master" agent that is available on the standard transport address and that accepts SNMP protocol messages - a set of "subagents" that each contain management instrumentation - a protocol that operates between the master agent and subagents, permitting subagents to "connect" to the master agent, and the master agent to multiplex received SNMP protocol messages amongst the subagents. - a set of tools to aid subagent development, and a runtime (API) environment that hides much of the protocol operation between a subagent and the master agent. The wide deployment of extensible SNMP agents, coupled with the lack of Internet standards in this area, makes it difficult to field SNMP-manageable applications. A vendor may have to support several different subagent environments (APIs) in order to support different target platforms. It can also become quite cumbersome to configure subagents and (possibly multiple) master agents on a particular managed node. Specifying a standard protocol for agent extensibility (AgentX) provides the technical foundation required to solve both of these problems. Independently developed AgentX-capable master agents and subagents will be able to interoperate at the protocol level. Vendors can continue to differentiate their products in all other respects. 4. AgentX Framework Within the SNMP framework, a managed node contains a processing entity, called an agent, which has access to management information. Within the AgentX framework, an agent is further defined to consist of: Daniele, et al. Standards Track [Page 6] RFC 2741 AgentX January 2000 - a single processing entity called the master agent, which sends and receives SNMP protocol messages in an agent role (as specified by the SNMP framework documents) but typically has little or no direct access to management information. - zero or more processing entities called subagents, which are "shielded" from the SNMP protocol messages pr