INTERNET-DRAFT <draft-ietf-agentx-ext-pro-00.txt> Expire in six months Agent Extensibility (AgentX) Protocol Version 1 June 12, 1996 Mike Daniele Digital Equipment Corporation daniele@zk3.dec.com Dale Francisco (editor) StrataCom dfrancisco@strata.com Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Daniele/Francisco Expires December 1996 [Page 1] Draft Agent Extensibility (AgentX) Protocol June 1996 Table of Contents 1. Introduction 2. The SNMP framework 2.1 A Note on Terminology 3. Extending the MIB 3.1 Motivation For AgentX 4. The AgentX Framework 4.1 AgentX Roles 5. AgentX Encodings 5.1 Character Set Selection 5.2 Value Representation 6. Protocol Definitions 6.1 Common Constructs 6.1.1 RegionSpecifier 6.1.2 NamingScope 6.1.3 SearchRange 6.1.4 AgentX PDU Header 6.2 AgentX PDUs 7. Elements of Procedure 7.1 AgentX Administrative PDUs 7.1.1 The Open-PDU 7.1.2 The Register-PDU 7.1.2.1 Register-PDU Fields 7.1.2.2 Processing the Register-PDU 7.1.2.2.1 The AddRegion Procedure 7.1.2.2.2 Handling Duplicate Regions 7.1.3 The Unregister-PDU 7.1.3.1 Unregister-PDU Fields 7.1.3.2 Processing the Unregister-PDU 7.1.4 The Close-PDU 7.2 Processing Received SNMP Protocol Messages 7.2.1 Dispatching AgentX PDUs 7.2.1.1 GetRequest-PDU 7.2.1.2 GetNextRequest-PDU 7.2.1.3 GetBulkRequest-PDU 7.2.2 Subagent Processing of AgentX PDUs 7.2.2.1 Subagent Processing of the AgentX Get-PDU 7.2.2.2 Subagent Processing of the AgentX GetNext-PDU 7.2.2.3 Subagent Processing of the AgentX GetBulk-PDU 7.2.3 Master Agent Processing AgentX Responses 7.2.4 Sending the SNMP Response PDU 8. Master Agent Transport Mappings 9. Security Considerations 10. Acknowledgements 11. References Daniele/Francisco Expires December 1996 [Page 2] Draft Agent Extensibility (AgentX) Protocol June 1996 1. Introduction This memo defines a 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. 2. The SNMP Framework A management system contains: several (potentially many) nodes, each with a processing entity, termed an agent, which has access to management instrumentation; at least one management station; and, a management protocol, used to convey management information between the agents and management stations. Operations of the protocol are carried out under an administrative framework which defines authentication, authorization, access control, and privacy policies. Management stations execute management applications which monitor and control managed elements. Managed elements are devices such as hosts, routers, terminal servers, etc., which are monitored and controlled via access to their management information. Management information is viewed as a collection of managed objects, residing in a virtual information store, termed the Management Information Base (MIB). Collections of related objects are defined in MIB modules. These modules are written using a subset of OSI's Abstract Syntax Notation One (ASN.1) [1], termed the Structure of Management Information (SMI) [2]. 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 SMI [2] or the textual conventions based on the SMI [3]. 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. Daniele/Francisco Expires December 1996 [Page 3] Draft Agent Extensibility (AgentX) Protocol June 1996 For the purpose of exposition, the original Internet-standard Network Management Framework, as described in RFCs 1155 (STD 16), 1157 (STD 15), and 1212 (STD 16), is termed the SNMP version 1 framework (SNMPv1). The current framework, as described in RFCs 1902-1908, is termed the SNMP version 2 framework (SNMPv2). 3. Extending the MIB New MIB modules that extend the Internet-standard MIB are continuously being defined as the output of 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. Neither the SNMP version 1 or version 2 framework address how managed objects may be dynamically added to or removed from the agent view within a particular managed node. 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 Daniele/Francisco Expires December 1996 [Page 4] Draft Agent Extensibility (AgentX) Protocol June 1996 (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 A managed node contains a processing entity, called an agent, which has access to management information. Within the AgentX framework, an agent consists of both - a single processing entity called the master agent, which sends and receives SNMP protocol messages in an agent role (as specified by the SNMP version 1 and version 2 framework documents) but typically has little or no access to management information. - 0 or more processing entities called subagents, which do not send or receive SNMP protocol messages, but which have access to management information. The master and subagent entities communicate via AgentX protocol messages, as specified in this memo. While some of these protocol messages appear similar in syntax and semantics to the SNMP, it is important to remember that AgentX subagents are not themselves SNMP protocol entities. The internal operations of AgentX are invisible to an SNMP entity operating in a manager role. To the manager, the agent behaves exactly as would a non-extensible (monolithic) agent that had access to the same management instrumentation. This transparency to managers is a fundamental requirement of AgentX, and is what differentiates AgentX subagents from SNMP proxy agents. 4.1. AgentX Roles An entity acting in a master agent role performs the following functions: - Accepts logical connection requests from subagents. - Accepts registration of MIB regions by subagents. Daniele/Francisco Expires December 1996 [Page 5] Draft Agent Extensibility (AgentX) Protocol June 1996 - Sends and accepts SNMP protocol messages on the agent's specified transport addresses. - Implements the agent role Elements of Procedure specified for the administrative framework applicable to the SNMP protocol message, except where they specify performing management operations. (The application of MIB views, and the access control policy for the managed node, are implemented by the master agent.) - Provides instrumentation for the MIB objects defined in [5], and for any MIB objects relevant to any administrative framework it supports. - Sends and receives AgentX protocol messages to access management information, based on the current registry of MIB regions. An entity acting in a subagent role performs the following functions: - Registers MIB regions with the master agent. - Instantiates managed objects. - Binds MIB region OIDs (contained in AgentX protocol messages) to actual variable names. - Performs management operations on variables. - Initiates traps. 5. AgentX Encodings AgentX PDUs consist of a common, fixed-format header; an optional PDU-specific subheader; and optional, possibly variable-length data. The PDUs are not encoded using the BER [1], but are represented as a simple byte stream. Within the header and subheaders, numeric data is always encoded most significant byte (MSB) first. The length of this data is not transmitted explicitly since it is known by the packet format. Variable-length data within the subheaders is transmitted as null-terminated strings. The length of this data is not transmitted explicitly since it may be determined by the string's length. Object identifiers are represented within the subheaders as null-terminated, ASN.1 dotted notation strings. 5.1. Character Set Selection Daniele/Francisco Expires December 1996 [Page 6] Draft Agent Extensibility (AgentX) Protocol June 1996 Strings are represented in the native character set of the system on which the subagent resides. If this is not ASCII, the master agent must perform any required conversions. 5.2. Value Representation Variable bindings may be transmitted within the variable-length portion of some PDUs. This representation (called a VarBind) is as follows: VarBind +--------+------+--------------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+--------------------------------------------+ | X | var | v.name (OID, null-terminated, length L) | +--------+------+--------------------------------------------+ | X+L+1 | 1 | v.type | +--------+------+--------------------------------------------+ | X+L+2 | 2 | v.length (MSB first) | +--------+------+--------------------------------------------+ | X+L+4 | var | v.data (format depends on data type) | +--------+------+--------------------------------------------+ v.type indicates the variable binding's syntax, and must be one of the following values: Daniele/Francisco Expires December 1996 [Page 7] Draft Agent Extensibility (AgentX) Protocol June 1996 +-----------------------------------------------------------------+ | Table 17. Valid values for the Value Type field | +-------+---------------------------------------------------------+ | VALUE | VALUE TYPE | +-------+---------------------------------------------------------+ | 129 | SNMP_TYPE_Integer32 | +-------+---------------------------------------------------------+ | 2 | SNMP_TYPE_OCTET_STRING | +-------+---------------------------------------------------------+ | 3 | SNMP_TYPE_OBJECT_IDENTIFIER | +-------+---------------------------------------------------------+ | 4 | SNMP_TYPE_NULL (empty, no value) | +-------+---------------------------------------------------------+ | 5 | SNMP_TYPE_IpAddress | +-------+---------------------------------------------------------+ | 134 | SNMP_TYPE_Counter32 | +-------+---------------------------------------------------------+ | 135 | SNMP_TYPE_Gauge32 | +-------+---------------------------------------------------------+ | 136 | SNMP_TYPE_TimeTicks (1/100ths seconds) | +-------+---------------------------------------------------------+ | 9 | SNMP_TYPE_DisplayString | +-------+---------------------------------------------------------+ | 13 | SNMP_TYPE_Counter64 | +-------+---------------------------------------------------------+ | 14 | SNMP_TYPE_Opaque | +-------+---------------------------------------------------------+ | 15 | SNMP_TYPE_noSuchObject | +-------+---------------------------------------------------------+ | 16 | SNMP_TYPE_noSuchInstance | +-------+---------------------------------------------------------+ | 17 | SNMP_TYPE_endOfMibView | +-------+---------------------------------------------------------+ v.length is a 2-byte integer, MSB first, which indicates the number of octets of v.data. v.data is the actual value, and is encoded as follows: - 32-bit integers are 4-byte elements, MSB first. Example: '00000001'h represents 1. - 64-bit integers are 8-byte elements, MSB first. Example: '0000000100000001'h represents 4,294,967,297. - Object Identifiers are NULL terminated strings in the selected character set, representing the OID in ASN.1 dotted notation. The length includes the terminating NULL. Example ASCII: '312e332e362e312e322e312e312e312e3000'h represents "1.3.6.1.2.1.1.1.0" which is sysDescr.0. Example EBCDIC: 'f14bf34bf64bf14bf24bf14bf14bf14bf000'h represents Daniele/Francisco Expires December 1996 [Page 8] Draft Agent Extensibility (AgentX) Protocol June 1996 "1.3.6.1.2.1.1.1.0" which is sysDescr.0. - DisplayStrings are in the selected character set. The length specifies the length of the string. Example ASCII: '6162630d0a'h represents "abc\r\n", no NULL. Example EBCDIC: '8182830d25'h represents "abc\r\n", no NULL. - IpAddress, NsapAddress and Opaque are implicit OCTET_STRING, so they are octets (e.g. IpAddress in network byte order). - NULL has a zero length for the value, and no value data. - noSuchObject, noSuchInstance and endOfMibView are implicit NULL and represented as such. - BIT_STRING is an OCTET_STRING of the form uubbbb...bb, where the first octet (uu) is 0x00-0x07 and indicates the number of unused bits in the last octet (bb). The bb octets represent the bit string itself, where bit zero (0) comes first and so on. VarBindList is a contiguous list of VarBinds. 6. Protocol Definitions 6.1. Common Constructs 6.1.1. RegionSpecifier A RegionSpecifier is an object identifier that may optionally contain a range in place of exactly one of its sub-identifiers. The range is represented as "[" lower-bound "-" upper-bound "]". For example, "1.2.3.[4-7].8" is a valid RegionSpecifier. 6.1.2. NamingScope [TBD] Daniele/Francisco Expires December 1996 [Page 9] Draft Agent Extensibility (AgentX) Protocol June 1996 6.1.3. SearchRange SearchRange +--------+------+----------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+----------------------------------------+ ... +--------+------+--------------------------------------------+ | X | var | g.requested (null-terminated OID, len L) | +--------+------+--------------------------------------------+ | X+L+1 | var | g.limit (null-terminated OID) | +--------+------+--------------------------------------------+ g.requested is the name of a requested variable binding. g.limit is an optional object identifier derived by the master agent to limit the search done by a subagent. SearchRangeList is a contiguous list of SearchRanges. 6.1.4. AgentX PDU Header Header +--------+------+----------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+----------------------------------------+ | 0 | 4 | h.length (MSB first) | +--------+------+----------------------------------------+ | 2 | 4 | h.ID (MSB first) | +--------+------+----------------------------------------+ | 8 | 1 | h.major | +--------+------+----------------------------------------+ | 9 | 1 | h.minor | +--------+------+----------------------------------------+ | 10 | 1 | h.flags | +--------+------+----------------------------------------+ | 11 | 1 | h.type | +========+======+========================================+ h.length is the size in octets of the entire PDU, including the header. (HL is the length of the header itself.) h.ID is a monotonically increasing packet id that should be kept unique by the sending entity. h.major is the protocol major version. This memo specifies a value of 0. h.minor is the protocol minor version number. This memo specifies Daniele/Francisco Expires December 1996 [Page 10]
Draft Agent Extensibility (AgentX) Protocol June 1996 a value of 0. h.flags is a one-octet bitmask, bit 0 first, etc. Bit definitions are Bits Contain ---- ------- 0-3 SNMP version 4 Alone 5-7 reserved h.type is the PDU type, and must be one of the following values: +-----------------------------------------------------------------+ | Table 16. Valid values for the packet type field | +-------+---------------------------------------------------------+ | VALUE | PACKET TYPE | +-------+---------------------------------------------------------+ | 1 | AGENTX_GET | +-------+---------------------------------------------------------+ | 2 | AGENTX_GETNEXT | +-------+---------------------------------------------------------+ | 3 | AGENTX_SET | +-------+---------------------------------------------------------+ | 4 | AGENTX_TRAP | +-------+---------------------------------------------------------+ | 5 | AGENTX_RESPONSE | +-------+---------------------------------------------------------+ | 6 | AGENTX_REGISTER | +-------+---------------------------------------------------------+ | 7 | AGENTX_UNREGISTER | +-------+---------------------------------------------------------+ | 8 | AGENTX_OPEN | +-------+---------------------------------------------------------+ | 9 | AGENTX_CLOSE | +-------+---------------------------------------------------------+ | 10 | AGENTX_COMMIT | +-------+---------------------------------------------------------+ | 11 | AGENTX_UNDO | +-------+---------------------------------------------------------+ | 12 | AGENTX_GETBULK | +-------+---------------------------------------------------------+ | 13 | AGENTX_TRAPV2 (not yet used) | +-------+---------------------------------------------------------+ | 14 | AGENTX_INFORM (not yet used) | +-------+---------------------------------------------------------+ | 15 | AGENTX_ARE_YOU_THERE | +-------+---------------------------------------------------------+ Daniele/Francisco Expires December 1996 [Page 11]
Draft Agent Extensibility (AgentX) Protocol June 1996 6.2. AgentX PDUs Register-PDU +--------+------+----------------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+----------------------------------------------+ | 0 | | Header | +--------+------+----------------------------------------------+ | HL | 2 | r.priority (MSB first) | +--------+------+----------------------------------------------+ | HL+2 | 2 | r.timeout (MSB first) | +--------+------+----------------------------------------------+ | HL+4 | var | r.region (RegionSpecifier, length L) | +--------+------+----------------------------------------------+ |HL+4+L+1| var | r.context (NamingScope) | +--------+------+----------------------------------------------+ Unregister-PDU +--------+------+----------------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+----------------------------------------------+ | 0 | | Header | +--------+------+----------------------------------------------+ | HL | 1 | u.reason code | +--------+------+----------------------------------------------+ | HL+1 | var | u.region (RegionSpecifier, length L) | +--------+------+----------------------------------------------+ |HL+1+L+1| var | u.context (NamingScope) | +--------+------+----------------------------------------------+ Get-PDU +--------+------+----------------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+----------------------------------------------+ | 0 | | Header | +--------+------+----------------------------------------------+ | HL | var | g.context (NamingScope, length L) | +--------+------+----------------------------------------------+ | HL+L+1 | var | SearchRangeList | +--------+------+----------------------------------------------+ Daniele/Francisco Expires December 1996 [Page 12]
Draft Agent Extensibility (AgentX) Protocol June 1996 GetNext-PDU +--------+------+----------------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+----------------------------------------------+ | 0 | | Header | +--------+------+----------------------------------------------+ | HL | var | g.context (NamingScope, length L) | +--------+------+----------------------------------------------+ | HL+L+1 | var | SearchRangeList | +--------+------+----------------------------------------------+ GetBulk-PDU +--------+------+----------------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+----------------------------------------------+ | 0 | | Header | +--------+------+----------------------------------------------+ | HL | 4 | g.non_repeaters (MSB first) | +--------+------+----------------------------------------------+ | HL+4 | 4 | g.max_repetitions (MSB first) | +--------+------+----------------------------------------------+ | HL+8 | var | g.context (NamingScope, length L) | +--------+------+----------------------------------------------+ |HL+8+L+1| var | SearchRangeList | +--------+------+----------------------------------------------+ Response-PDU +--------+------+----------------------------------------------+ | OFFSET | SIZE | FIELD | +--------+------+----------------------------------------------+ | 0 | | Header | +--------+------+----------------------------------------------+ | HL | 4 | res.error_code (MSB first) | +--------+------+----------------------------------------------+ | HL+4 | 4 | res.error_index (MSB first) | +--------+------+----------------------------------------------+ | HL+8 | var | VarBindList | +--------+------+----------------------------------------------+ 7. Elements of Procedure This section describes the actions of protocol entities (master agents and subagents) implementing the AgentX protocol. Note, however, that it is not intended to constrain the internal architecture of any conformant implementation. Daniele/Francisco Expires December 1996 [Page 13]
Draft Agent Extensibility (AgentX) Protocol June 1996 The actions of AgentX protocol entities can be broadly categorized under two headings: processing AgentX administrative messages (e.g, connection requests from a subagent to a master agent); and processing SNMP messages (e.g., the coordinated actions of a master agent and one or more subagents in processing a received SNMP GetRequest-PDU). 7.1. Processing AgentX Administrative Messages This subsection describes the actions of AgentX protocol entities in processing AgentX administrative messages. Such messages include those involved in establishing and terminating a connection between a subagent and a master agent, and those by which a subagent communicates to a master agent which MIB subtrees it supports. 7.1.1. The Open-PDU [TBD] 7.1.2. The Register-PDU A Register-PDU is generated by a subagent for each region of the MIB variable naming tree (within a specific context) that it wishes to support. 7.1.2.1. Register-PDU Fields A Register-PDU contains the following fields: - r.region indicates a region of the MIB that a subagent wishes to support. It may be a fully-qualified instance name, a partial instance name, a MIB table or group, or ranges of any of these. The choice of what to register is implementation-specific; this memo does not specify permissible values. Standard practice however is for a subagent to register at the highest level of the naming tree that makes sense. Registration of fully-qualified instances is typically done only when a subagent can perform management operations only on particular rows of a conceptual table. Note that the RegionSpecifier syntax (see 6.1.1) permits registering a conceptual row in a single operation. For instance, "1.3.6.1.2.1.2.2.1.[1-22].7" would register row 7 of the RFC 1573 ifTable. - r.context is used by the subagent when identically named objects require a context to differentiate them. A null string indicates the default context. Daniele/Francisco Expires December 1996 [Page 14]
Draft Agent Extensibility (AgentX) Protocol June 1996 - r.priority is used by cooperating subagents to achieve a desired configuration when registering identical regions. The default value is 0 (no priority indicated). Higher numbers indicate higher priority. - r.timeout is the length of time, in centiseconds, that a master agent should allow to elapse after dispatching a message to a subagent before it regards the subagent as not responding. r.timeout applies only to messages that concern MIB objects within r.region. It overrides both the subagent-wide value (if any) indicated when the logical connection with the master agent was established, and the master agent's default timeout. The default value for r.timeout is 0 (no override). 7.1.2.2. Processing the Register-PDU When the master agent receives a Register-PDU, it processes it as follows: If an Open-PDU has not been received and successfully processed for this subagent, ignore the message [or send back error?]. Otherwise, the master agent adds this region to its registered OID space for that context, to be considered during the dispatching phase for subsequently received SNMP protocol messages. 7.1.2.2.1. The AddRegion Procedure In this region addition phase, RegionSpecifiers that contain subid ranges are processed as if the master agent had received multiple registrations, each containing no subid ranges. (For instance, "1.2.3.[4-6].7" is processed as if the master had received registrations whose RegionSpecifiers where "1.2.3.4.7", "1.2.3.5.7", and "1.2.3.6.7".) If r.region (R1) is a subtree of a currently registered region (R2), split R2 into 3 new regions (R2a, R2b, and R2c) such that R2b is an exact duplicate of R1. Now remove R2 and add R1, R2a, R2b, and R2c to the master agent's lexicographically ordered set of regions (the registered OID space). Note: Though newly-added regions R1 and R2b are identical in terms of the MIB objects they contain, they are registered by different subagents, possibly at different priorities. For instance, if subagent S2 registered `ip' (R2 is 1.3.6.1.2.1.4) and subagent S1 subsequently registered `ipNetToMediaTable' (R1 is 1.3.6.1.2.1.4.22), the resulting set of registered regions would be: 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) Daniele/Francisco Expires December 1996 [Page 15]
Draft Agent Extensibility (AgentX) Protocol June 1996 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2) If r.region (R1) overlaps one or more currently registered regions, then for each overlapped region (R2) split R1 into 3 new regions (R1a, R1b, R1c) such that R1b is an exact duplicate of R2. Add R1b and R2 into the lexicographically ordered set of regions. Apply the AddRegion operation to R1a and R1c (since they may overlap, or be subtrees of, other regions). For instance, given the currently registered regions in the example above, if subagent S3 now registers mib-2 (R1 is 1.3.6.1.2.1) the resulting set of regions would be: 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3) 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S2) 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S2) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S2) 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3) 1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3) Note that at registration time a region may be split into multiple regions due to pre-existing registrations, or as a result of any subsequent registration. This region splitting is transparent to subagents. Hence the master agent must always be able to associate any registered region with the information contained in its original Register-PDU. 7.1.2.2.2. Handling Duplicate Regions As a result of this registration algorithm there are likely to be duplicate regions (regions of identical MIB objects registered to different subagents) in the master agent's registered OID space. Whenever the master agent's dispatching algorithm (see 7.2.1, Dispatching AgentX PDUs) selects a duplicate region, the determination of which one to use proceeds as follows: 1) Choose the one whose original Register-PDU r.region contained the most subids, i.e., the most specific r.region. Note: A range subid is no "longer" (more specific) than a single subid. 2) If still ambiguous, choose the one whose original Register-PDU specified the highest priority. 3) If still ambiguous, choose the one whose original Register-PDU was received most recently. Daniele/Francisco Expires December 1996 [Page 16]
Draft Agent Extensibility (AgentX) Protocol June 1996 7.1.3. The Unregister-PDU The Unregister-PDU is sent by a subagent to remove a previously registered RegionSpecifier from the master agent's OID space. 7.1.3.1. Unregister-PDU Fields An Unregister-PDU contains the following fields: - u.reason - u.region indicates a previously-registered region of the MIB that a subagent no longer wishes to support. It may be a fully-qualified instance name, a partial instance name, a MIB table or group, or ranges of any of these. - u.context is used by the subagent when identically named objects require a context to differentiate them. A null string indicates the default context. 7.1.3.2. Processing the Unregister-PDU If u.region and u.context do not exactly match the values of r.region and r.context of a previously processed Register-PDU which was sent from this subagent, the request is rejected with an appropriate error response. Otherwise the master agent removes u.region from its registered OID space for u.context. If the original region had been split, all such related regions are removed. If this removal results in any contiguous regions that share a common original Register-PDU, they are agglomerated into a single region. For instance, given the example registry above, if subagent S2 unregisters `ip', the resulting registry would be: 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4 (by S3) 1.3.6.1.2.1.4 up to but not including 1.3.6.1.2.1.4.22 (by S3) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.1.5 (by S3) 1.3.6.1.2.1.5 up to but not including 1.3.6.1.2.2 (by S3) and after agglomeration; 1.3.6.1.2.1 up to but not including 1.3.6.1.2.1.4.22 (by S3) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S1) 1.3.6.1.2.1.4.22 up to but not including 1.3.6.1.2.1.4.23 (by S3) 1.3.6.1.2.1.4.23 up to but not including 1.3.6.1.2.2 (by S3) Daniele/Francisco Expires December 1996 [Page 17]
Draft Agent Extensibility (AgentX) Protocol June 1996 7.2. Processing Received SNMP Protocol Messages When an SNMP GetRequest, GetNextRequest, GetBulkRequest, or SetRequest protocol message is received by the master agent, the master agent implements the access control policy in effect at the managed node. In particular, the master agent implements the Elements of Procedure defined in section 4.1 of [6] that apply to receiving entities. [We can't refer to 1901, or v2u/v2* ?] If this processing results in a valid SNMP request PDU, then an SNMP response PDU is constructed from information gathered in the exchange of AgentX PDUs between the master agent and 1 or more subagents. Upon receipt and initial validation of an SNMP request PDU, a master agent uses the procedures described below to dispatch AgentX PDUs to the proper subagents, marshal the subagent responses, and construct an SNMP response PDU. 7.2.1 Dispatching AgentX PDUs Upon receipt and initial validation of an SNMP request PDU, a master agent uses the procedures described below to dispatch AgentX PDUs to the proper subagents. 7.2.1.1 GetRequest-PDU An SNMP Response-PDU is constructed whose fields all contain the same values as in the SNMP Request-PDU, except that the value of each variable binding is set to 'noSuchObject'. Each variable binding in the Request-PDU is processed in order, as follows: (1) Identify the target region. (2) Within a list of regions registered within the context indicated in the request PDU, and lexicographically ordered by RegionSpecifier, locate the RegionSpecifier that is identical to or is the closest lexicographical predecessor to the variable binding's name. (3) If no such region exists the variable binding is not processed further. (4) Identify the target subagent, which is the one that registered the target region. (5) If this is the first variable binding to be dispatched to the target subagent, create an AgentX Get-PDU for the subagent, with Daniele/Francisco Expires December 1996 [Page 18]
Draft Agent Extensibility (AgentX) Protocol June 1996 the header fields initialized as described in section 6.1.3, and the context in the Request-PDU encoded into g.context. (6) Add a SearchRange to the end of the target subagent's Get-PDU for this variable binding. (7) The variable binding's name is copied to g.requested. (8) g.limit is set to null. 7.2.1.2. GetNextRequest-PDU An SNMP Response-PDU is constructed whose fields all contain the same values as in the SNMP Request-PDU, except that the value of each variable binding is set to 'endOfMibView'. Each variable binding in the Request-PDU is processed in order, as follows: (1) Identify the target region. (2) Within a list of regions registered within the context indicated in the request PDU, and lexicographically ordered by RegionSpecifier, locate the longest RegionSpecifier of which the variable binding's name is a subtree. If no such region exists, locate the RegionSpecifier which is the first lexicographical successor to the variable binding's name. (3) If no such region exists the variable binding is not processed further. (4) Identify the target subagent, which is the one that registered the target region. (5) If this is the first variable binding to be dispatched to the target subagent, create an AgentX GetNext-PDU for the subagent, with the header fields initialized as described in section 6.1.3 and the context in the Request-PDU encoded into g.context. (6) Add a SearchRange to the end of the target subagent's GetNext-PDU for this variable binding. (7) The variable binding's name is copied to g.requested. (8) g.limit is set to the RegionSpecifier that is the first lexicographical successor to the target Regionspecifier, and that was not registered by the target subagent. If no such RegionSpecifier exists, g.limit is set to null. Daniele/Francisco Expires December 1996 [Page 19]
Draft Agent Extensibility (AgentX) Protocol June 1996 7.2.1.3. GetBulkRequest-PDU (Note: The outline of the following procedure is based closely on section 4.2.3, "The GetBulkRequest-PDU" of [4]. Please refer to it for details on the format of the SNMP GetBulkRequest-PDU itself.) An SNMP Response-PDU is constructed whose fields all contain the same values as in the SNMP Request-PDU. The SNMP Response-PDU contains N + (M * R) variable bindings whose values are set to `EndOfMibView', where N ("non-repeaters") is the minimum of: a) the value of the non-repeaters field in the request, and b) the number of variable bindings in the request M ("max-repetitions") is the value of the max-repetitions field in the request R ("repeaters") is the maximum of: a) number of variable bindings in the request - N, and b) zero Each variable binding in the Request-PDU is processed in order, as follows: (1) Identify the target region and target subagent, exactly as described for the GetNextRequest-PDU (7.2.1.2). (2) If this is the first variable binding to be dispatched to the target subagent during the processing of this Request-PDU, create an AgentX GetBulk-PDU for the subagent, with the header fields initialized as described in section 6.1.3 and the context and max_repetitions value in the request PDU encoded into g.context and g.max_repetitions. Set g.non_repeaters to 0. (3) Add a SearchRange to the end of the target subagent's GetBulk-PDU for this variable binding, as described for the GetNext-PDU. If the variable binding was within the non_repeaters range in the original Request-PDU, increment the value of g.non_repeaters. When all variable bindings have been processed, send any AgentX PDUs to their respective target subagents (at the transport endpoint used to initiate the subagent's logical connection). Calculate a timeout value for each target subagent that is the maximum of: - The master agent's default. - The subagent's default, as indicated by the subagent at connection establishment. Daniele/Francisco Expires December 1996 [Page 20]
Draft Agent Extensibility (AgentX) Protocol June 1996 - Any region-specific timeout values, as indicated by the subagent at registration. 7.2.2. Subagent Processing of AgentX Request PDUs When a subagent receives an AgentX Get-, GetNext-, or GetBulk-PDU, it performs the indicated management operations and returns a response PDU. The response PDU header fields are identical to the received request PDU except that, at the start of processing, the subagent initializes h.type to RESPONSE, res.error_code to `noError', res.error_index to 0, and the VarbindList to null. Each SearchRange in the request PDU is then processed in order, and a corresponding VarBind added to the response PDU as described below. If processing should fail for any reason not described below, res.error_code is set to `genError', res.error_index to the index of the failed SearchRange, the VarBindList is reset to null, and this response PDU is returned to the master agent. 7.2.2.1. Subagent Processing of the AgentX Get-PDU Upon the subagent's receipt of an AgentX Get-PDU, each variable binding in the request is processed in order as follows: 1) g.requested is copied to v.name. 2) If the value of g.requested exactly matches the name of a variable instantiated by this subagent within the indicated context, v.type, v.length, and v.data are encoded to represent the variable's syntax and value, as described in section 5.2. If the resulting VarBind's type is not part of the SNMPv1 SMI, and h.flags indicate this is an SNMPv1-style request, v.type is set to `noSuchObject', and v.length to 0. 3) Otherwise, if the value of g.requested does not match the OBJECT IDENTIFIER PREFIX of any variable instantiated within the indicated context, v.type is set to `noSuchObject' and v.length to 0. 4) Otherwise, v.type is set to `noSuchInstance' and v.length to 0. 7.2.2.2. Subagent Processing of the AgentX GetNext-PDU Upon the subagent's receipt of an AgentX GetNext-PDU, each variable binding in the request is processed in order as follows: 1) The subagent searches for a variable within the Daniele/Francisco Expires December 1996 [Page 21]
Draft Agent Extensibility (AgentX) Protocol June 1996 lexicographically ordered list of variable names for all variables it instantiates (without regard to registration of regions) within the indicated context, for which the following are all true: - The variable's name is the closest lexicographical successor to g.requested. - If g.limit is not null, the variable's name lexicographically precedes g.limit. - If h.flags indicates this is an SNMPv1 request, the variable's syntax is part of the SNMPv1 SMI. If all of these conditions are met, v.name is set to the located variable's name. v.type, v.length, and v.data are encoded to represent the variable's syntax and value, as described in section 5.2. 2) If no such variable exists, v.name is set to g.requested, v.type is set to `endOfMibView', and v.length to 0. 7.2.2.3. Subagent Processing of the AgentX GetBulk-PDU A maximum of N + (M * R) VarBinds are returned, where N equals g.non_repeaters, M equals g.max_repetitions, and R is (number of SearchRanges in the GETBULK request) - N. The first N SearchRanges are processed exactly as for the GetNext PDU. If M and R are both non-zero, the remaining R SearchRanges are processed iteratively to produce potentially many VarBinds. For each iteration i, such that i is greater than zero and less than or equal to M, and for each repeated SearchRange s, such that s is greater than zero and less than or equal to R, the (N+((i-1)*R)+s)-th VarBind is added to the response PDU as follows: 1) The subagent searches for a variable within the lexicographically ordered list of variable names for all variables it instantiates (without regard to registration of regions) within the indicated context, for which the following are all true: - The variable's name is the (i)-th lexicographical successor to the (N+s)-th requested OID. Daniele/Francisco Expires December 1996 [Page 22]
Draft Agent Extensibility (AgentX) Protocol June 1996 - If g.limit is not null, the variable's name lexicographically precedes g.limit. - If h.flags indicates this is an SNMPv1 request, the variable's syntax is part of the SNMPv1 SMI. If all of these conditions are met, v.name is set to the located variable's name. v.type, v.length, and v.data are encoded to represent the variable's syntax and value, as described in section 5.2. 2) If no such variable exists, v.type is set to `endOfMibView' and v.length to 0. v.name is set to v.name of the (N+((i-2)*R)+s)-th VarBind unless i is currently one, in which case it is set the value of g.requested in the (N+s)-th SearchRange. Note that further iterative processing should stop if for any iteration i, all s values of v.type are `EndofMibView'. When the AgentX response PDU has been generated, it is sent back to the master agent's transport endpoint from which the request was sent. 7.2.3. Master Agent Processing of AgentX Responses The master agent now marshals all subagent response PDUs and builds an SNMP response PDU. To do so, the master agent must be able to determine the corresponding variable binding (or error_index value) in the SNMP Response-PDU for each received AgentX VarBind (or res.error_index value). (Note in particular that a response PDU may contain more VarBinds than are required to complete the SNMP Response-PDU.) 1) If any subagent did not respond within its allotted time period, the SNMP Response PDU's error code is set to `genError' and its error index to the index of the variable binding corresponding to the first VarBind in the request PDU that was sent to this subagent. All other subagent response PDUs received due to processing this SNMP request are ignored. Processing is complete; the SNMP response PDU is sent. 2) Otherwise, if the h.ID field of the AgentX response PDU does not match that of the request PDU sent to this subagent, the PDU is ignored. 3) Otherwise, if res.error code is not `noError', the SNMP response PDU's error code is set to this value, and its error index to the Daniele/Francisco Expires December 1996 [Page 23]
Draft Agent Extensibility (AgentX) Protocol June 1996 index of the variable binding corresponding to the failed VarBind in the subagent's response PDU. All other response PDUs received due to processing this SNMP Request are ignored. Processing is complete; the SNMP Response PDU is sent. 4) Otherwise, the VarBinds in the RESPONSE PDU are processed as follows: Get If v.name is not within the relevant MIB view, the VarBind is ignored. (This determination is implementation-specific.) Otherwise, the name and value of the corresponding variable binding in the SNMP Response-PDU are updated with the contents of the VarBind. GetNext If v.name is not within the relevant MIB view, the VarBind is ignored. (This determination is implementation-specific.) Otherwise, the name and value of the corresponding variable binding in the SNMP Response-PDU are updated with the contents of the VarBind. 5) After all expected response PDUs have been processed, if any variable bindings still contain the value `endOfMibView', processing must continue: - For each such variable binding, a target region is identified which is the lexicographical successor to the target region for this variable binding on the last iteration. The target subagent is the one that registered the target region. - If this is the first variable binding to be dispatched to the target subagent (during this iteration), create an AgentX GetNext-PDU for the subagent, with the header fields initialized as described in section 6.1.3 and the context in the Request-PDU encoded into g.context. - Add a SearchRange to the end of the target subagent's GetNext-PDU for this variable binding. The variable binding's name is copied to g.requested. g.limit is set to the RegionSpecifier that is the first lexicographical successor to the target Regionspecifier, and that was not registered by the target subagent. If no such RegionSpecifier exists, g.limit is set to null. Daniele/Francisco Expires December 1996 [Page 24]
Draft Agent Extensibility (AgentX) Protocol June 1996 - The AgentX PDUs are sent, received, and processed according to section 7.2.3. - This process continues iteratively until a complete SNMP Response-PDU has been built, or until there remain no target region lexicographical successors. GetBulk If v.name is not within the relevant MIB view, the VarBind is ignored. (This determination is implementation-specific.) Otherwise, the name and value of the corresponding variable binding in the SNMP Response-PDU are updated with the contents of the VarBind. 5) If after all expected RESPONSE PDUs have been processed, any variable bindings still contain the value `endOfMibView', processing must continue: - For each such variable binding, a target region is identified which is the lexicographical successor to the target region for this variable binding on the last iteration. The target subagent is the one that registered the target region. - If this is the first variable binding to be dispatched to the target subagent (during this iteration), create an AgentX GetBulk-PDU for the subagent, with the header fields initialized as described in section 6.1.3 and the context from the Request-PDU encoded into g.context. - Set the value of g.non_repeaters and g.max_repetitions to 0. - Add a SearchRange to the end of the target subagent's GetBulk-PDU for this variable binding. - g.requested is set to v.name of the (last repeating) VarBind that was returned for this variable binding on the previous iteration. g.limit is set to the RegionSpecifier that is the first lexicographical successor to the target Regionspecifier, and that was not registered by the target subagent. If no such RegionSpecifier exists, g.limit is set to null. If the variable binding was within the non_repeaters range in the original Request-PDU, increment the value of Daniele/Francisco Expires December 1996 [Page 25]
Draft Agent Extensibility (AgentX) Protocol June 1996 g.non_repeaters. Otherwise, set the value of g.max_repetitions to the maximum of its current value, or the number of response variable bindings still required for this requested variable binding. - The AgentX PDUs are sent, received, and processed according to the procedures in section 7.2.3. - This process continues iteratively until a complete SNMP response PDU has been built, or until there are no target region lexicographical successors. 7.2.4. Sending the SNMP Response PDU Once the processing described in sections 7.2.1 - 7.2.3 is complete, there is an SNMP response PDU available. The master agent now implements the Elements of Procedure for the applicable version of the SNMP protocol in order to encapsulate the PDU into a message, and transmit it to the originator of the SNMP management request. Note that this may also involve altering the PDU contents for agents that support the SNMP version 1 framework. [Do we need to mention explicit mappings? For instance, for v2 Set error codes?] 8. Master Agent Transport Mappings [TBD] 9. Security Considerations Security issues are not discussed in this memo. 10. Acknowledgements The initial draft of this memo was heavily influenced by the DPI 2.0 specification [7]. This document was produced by the IETF Agent Extensibility (AgentX) Working Group. Daniele/Francisco Expires December 1996 [Page 26]
Draft Agent Extensibility (AgentX) Protocol June 1996 11. References [1] Information processing systems - Open Systems Interconnection - Specification of Abstract Syntax Notation One (ASN.1), International Organization for Standardization. International Standard 8824, (December, 1987). [2] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1902, January 1996. [3] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1903, January 1996. [4] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1905, January 1996. [5] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1907, January 1996. [6] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network Management Protocol", STD 15, RFC 1157, SNMP Research, Performance Systems International, MIT Laboratory for Computer Science, May 1990. [7] Wijnen, B., Carpenter, G., Curran, K., Sehgal, A., and G. Waters, "Simple Network Management Protocol: Distributed Protocol Interface, Version 2.0", RFC 1592, T.J. Watson Research Center, IBM Corp., Bell Northern Research, Ltd., March 1994. Daniele/Francisco Expires December 1996 [Page 27]
