tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 2257


Pages: 80
Top     in Index     Prev     Next
 

Agent Extensibility (AgentX) Protocol Version 1

Part 1 of 3, p. 1 to 19
None       Next RFC Part

Obsoleted by:    2741


Top       ToC       Page 1 
Network Working Group                                         M. Daniele
Request for Comments: 2257                 Digital Equipment Corporation
Category: Standards Track                                      B. Wijnen
                                  T.J. Watson Research Center, IBM Corp.
                                                       D. Francisco, Ed.
                                                     Cisco Systems, Inc.
                                                            January 1998

                 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 (1998).  All Rights Reserved.

Table of Contents

   1 Introduction......................................................4

   2 The SNMP Framework................................................4
     2.1 A Note on Terminology.........................................4

   3 Extending the MIB.................................................5
     3.1 Motivation for AgentX.........................................5

   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

   5 AgentX Encodings.................................................10
     5.1 Object Identifier............................................11
     5.2 SearchRange..................................................13
     5.3 Octet String.................................................14
     5.4 Value Representation.........................................14

   6 Protocol Definitions.............................................16
     6.1 AgentX PDU Header............................................16

Top      ToC       Page 2 
       6.1.1 Context..................................................19
     6.2 AgentX PDUs..................................................20
       6.2.1 The agentx-Open-PDU......................................20
       6.2.2 The agentx-Close-PDU.....................................21
       6.2.3 The agentx-Register-PDU..................................22
       6.2.4 The agentx-Unregister-PDU................................25
       6.2.5 The agentx-Get-PDU.......................................27
       6.2.6 The agentx-GetNext-PDU...................................29
       6.2.7 The agentx-GetBulk-PDU...................................30
       6.2.8 The agentx-TestSet-PDU...................................31
       6.2.9 The agentx-CommitSet, -UndoSet, -CleanupSet
             PDUs.....................................................33
       6.2.10 The agentx-Notify-PDU...................................33
       6.2.11 The agentx-Ping-PDU.....................................34
       6.2.12 The agentx-IndexAllocate-PDU............................35
       6.2.13 The agentx-IndexDeallocate-PDU..........................36
       6.2.14 The agentx-AddAgentCaps-PDU.............................37
       6.2.15 The agentx-RemoveAgentCaps-PDU..........................38
       6.2.16 The agentx-Response-PDU.................................39

   7 Elements of Procedure............................................41
     7.1 Processing AgentX Administrative Messages....................42
       7.1.1 Processing the agentx-Open-PDU...........................42
       7.1.2 Processing the agentx-IndexAllocate-PDU..................43
       7.1.3 Using the agentx-IndexAllocate-PDU.......................45
       7.1.4 Processing the agentx-IndexDeallocate-PDU................47
       7.1.5 Processing the agentx-Register-PDU.......................48
         7.1.5.1 Handling Duplicate OID Ranges........................50
       7.1.6 Processing the agentx-Unregister-PDU.....................51
       7.1.7 Processing the agentx-AddAgentCaps-PDU...................51
       7.1.8 Processing the agentx-RemoveAgentCaps-PDU................52
       7.1.9 Processing the agentx-Close-PDU..........................52
       7.1.10 Detecting Connection Loss...............................53
       7.1.11 Processing the agentx-Notify-PDU........................53
       7.1.12 Processing the agentx-Ping-PDU..........................54
     7.2 Processing Received SNMP Protocol Messages...................54
       7.2.1 Dispatching AgentX PDUs..................................55
         7.2.1.1 agentx-Get-PDU.......................................57
         7.2.1.2 agentx-GetNext-PDU...................................58
         7.2.1.3 agentx-GetBulk-PDU...................................59
         7.2.1.4 agentx-TestSet-PDU...................................60
         7.2.1.5 Dispatch.............................................60
       7.2.2 Subagent Processing of agentx-Get, GetNext,
             GetBulk-PDUs.............................................61
         7.2.2.1 Subagent Processing of the agentx-Get-PDU............61
         7.2.2.2 Subagent Processing of the
                 agentx-GetNext-PDU...................................62

Top      ToC       Page 3 
         7.2.2.3 Subagent Processing of the
                 agentx-GetBulk-PDU...................................62
       7.2.3 Subagent Processing of agentx-TestSet,
             -CommitSet, -UndoSet, -CleanupSet-PDUs...................63
         7.2.3.1 Subagent Processing of the
                 agentx-TestSet-PDU...................................64
         7.2.3.2 Subagent Processing of the
                 agentx-CommitSet-PDU.................................65
         7.2.3.3 Subagent Processing of the
                 agentx-UndoSet-PDU...................................65
         7.2.3.4 Subagent Processing of the
                 agentx-CleanupSet-PDU................................65
       7.2.4 Master Agent Processing of AgentX Responses..............66
         7.2.4.1 Common Processing of All AgentX Response
                 PDUs.................................................66
         7.2.4.2 Processing of Responses to agentx-Get-PDUs...........66
         7.2.4.3 Processing of Responses to
                 agentx-GetNext-PDU and agentx-GetBulk-PDU............67
         7.2.4.4 Processing of Responses to
                 agentx-TestSet-PDUs..................................68
         7.2.4.5 Processing of Responses to
                 agentx-CommitSet-PDUs................................68
         7.2.4.6 Processing of Responses to
                 agentx-UndoSet-PDUs..................................69
       7.2.5 Sending the SNMP Response-PDU............................69
       7.2.6 MIB Views................................................69
     7.3 State Transitions............................................70
       7.3.1 Set Transaction States...................................70
       7.3.2 Transport Connection States..............................71
       7.3.3 Session States...........................................73

   8 Transport Mappings...............................................74
     8.1 AgentX over TCP..............................................74
       8.1.1 Well-known Values........................................74
       8.1.2 Operation................................................74
     8.2 AgentX over UNIX-domain Sockets..............................75
       8.2.1 Well-known Values........................................75
       8.2.2 Operation................................................75

   9 Security Considerations..........................................76

   10 Acknowledgements................................................77

   11 Authors' and Editor's Addresses.................................77

   12 References......................................................78

   13 Full Copyright Statement........................................80

Top      ToC       Page 4 
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.

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) (see RFC 1902 [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 (RFC
   1902, [2]) or the textual conventions based on the SMI (RFC 1903
   [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

Top      ToC       Page 5 
   instance.  The OBJECT IDENTIFIER of the corresponding object-type is
   called the OBJECT IDENTIFIER prefix of the variable.  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 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.

   Neither the SNMP version 1 nor version 2 framework describes how the
   set of managed objects supported by a particular agent may be changed
   dynamically.

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.

Top      ToC       Page 6 
   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

      - 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 direct access to
        management information.

      - 0 or more processing entities called subagents, which are
        "shielded" from the SNMP protocol messages processed by the
        master agent, but which have access to management information.

   The master and subagent entities communicate via AgentX protocol
   messages, as specified in this memo.  Other interfaces (if any) on
   these entities, and their associated protocols, are outside the scope
   of this document.  While some of the AgentX protocol messages appear
   similar in syntax and semantics to the SNMP, bear in mind that AgentX
   is not SNMP.

   The internal operations of AgentX are invisible to an SNMP entity
   operating in a manager role.  From a manager's point of view, an
   extensible agent behaves exactly as would a non-extensible
   (monolithic) agent that has access to the same management
   instrumentation.

Top      ToC       Page 7 
   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 AgentX session establishment requests from subagents.

      - Accepts registration of MIB regions by subagents.

      - 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 RFC
        1907 [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.

      - Forwards notifications on behalf of subagents.

   An entity acting in a subagent role performs the following functions:

      - Initiates an AgentX session with the master agent.

      - Registers MIB regions with the master agent.

      - Instantiates managed objects.

      - Binds OIDs within its registered MIB regions to actual
        variables.

      - Performs management operations on variables.

      - Initiates notifications.

Top      ToC       Page 8 
4.2  Applicability

   It is intended that this memo specify the smallest amount of required
   behavior necessary to achieve the largest benefit, that is, to cover
   a very large number of possible MIB implementations and
   configurations with minimum complexity and low "cost of entry".

   This section discusses several typical usage scenarios.

   1) Subagents implement separate MIB modules--for example,
      subagent A implements "mib-2", subagent b implements "host-
      resources".

      It is anticipated that this will be the most common subagent
      configuration.

   2) Subagents implement rows in a "simple table".  A simple table
      is one in which row creation is not specified, and for which the
      MIB does not define an object that counts entries in the table.
      Examples of simple tables are rdbmsDbTable, udpTable, and
      hrSWRunTable.

      This is the most commonly defined type of MIB table, and probably
      represents the next most typical configuration that AgentX would
      support.

   3) Subagents share MIBs along non-row partitions.  Subagents
      register "chunks" of the MIB that represent multiple rows, due to
      the nature of the MIB's index structure.  Examples include
      registering ipNetToMediaEntry.n, where n represents the ifIndex
      value for an interface implemented by the subagent, and
      tcpConnEntry.a.b.c.d, where a.b.c.d represents an IP address on an
      interface implemented by the subagent.

   AgentX supports these three common configurations, and all
   permutations of them, completely.  The consensus is that they
   comprise a very large majority of current and likely future uses of
   multi-vendor extensible agent configurations.

   4) Subagents implement rows in "complex tables".  Complex tables
      here are defined as tables permitting row creation, or whose MIB
      also defines an object that counts entries in the table.  Examples
      include the MIB-2 ifTable (due to ifNumber), and the RMON
      historyControlTable.

Top      ToC       Page 9 
   The subagent that implements such a counter object (like ifNumber)
   must go beyond AgentX to correctly implement it.  This is an
   implementation issue (and most new MIB designs no longer include such
   objects).

   To implement row creation in such tables, at least one AgentX
   subagent must register at a point "higher" in the OID tree than an
   individual row (per AgentX's dispatching procedure).  Again, this is
   an implementation issue.

   Scenarios in this category were thought to occur somewhat rarely in
   configurations where subagents are independently implemented by
   different vendors.  The focus of a standard protocol, however, must
   be in just those areas where multi- vendor interoperability must be
   assured.

   Note that it would be inefficient (due to AgentX registration
   overhead) to share a table among AgentX subagents if the table
   contains very dynamic instances, and each subagent registers fully
   qualified instances.  ipRouteTable could be an example of such a
   table in some environments.

4.3.  Design Features of AgentX

   The primary features of the design described in this memo are:

   1) A general architectural division of labor between master agent
      and subagent: The master agent is MIB ignorant and SNMP
      omniscient, while the subagent is SNMP ignorant and MIB omniscient
      (for the MIB variables it instantiates).  That is, master agents,
      exclusively, are concerned with SNMP protocol operations and the
      translations to and from AgentX protocol operations needed to
      carry them out; subagents are exclusively concerned with
      management instrumentation; and neither should intrude on the
      other's territory.

   2) A standard protocol and "rules of engagement" to enable
      interoperability between management instrumentation and extensible
      agents.

   3) Mechanisms for independently developed subagents to
      integrate into the extensible agent on a particular managed node
      in such a way that they need not be aware of any other existing
      subagents.

Top      ToC       Page 10 
   4) A simple, deterministic registry and dispatching algorithm.
      For a given extensible agent configuration, there is a single
      subagent who is "authoritative" for any particular region of the
      MIB (where "region" may extend from an entire MIB down to a single
      object-instance).

   5) Performance considerations.  It is likely that the master
      agent and all subagents will reside on the same host, and in such
      cases AgentX is more a form of inter-process communication than a
      traditional communications protocol.

      Some of the design decisions made with this in mind include:

         - 32-bit alignment of data within PDUs

         - Native byte-order encoding by subagents

         - Large AgentX PDU payload sizes.

4.4  Non-Goals

   1) Subagent-to-subagent communication.  This is out of scope,
      due to the security ramifications and complexity involved.

   2) Subagent access (via the master agent) to MIB variables.
      This is not addressed, since various other mechanisms are
      available and it was not a fundamental requirement.

   3) The ability to accommodate every conceivable extensible
      agent configuration option. This was the most contentious aspect
      in the development of this protocol.  In essence, certain features
      currently available in some commercial extensible agent products
      are not included in AgentX.  Although useful or even vital in some
      implementation strategies, the rough consensus was that these
      features were not appropriate for an Internet Standard, or not
      typically required for independently developed subagents to
      coexist.  The set of supported extensible agent configurations is
      described above, in Section 4.2.

   Some possible future version of the AgentX protocol may provide
   coverage for one or more of these "non-goals" or for new goals that
   might be identified after greater deployment experience.

5.  AgentX Encodings

   AgentX PDUs consist of a common header, followed by PDU-specific data
   of variable length.  Unlike SNMP PDUs, AgentX PDUs are not encoded
   using the BER (as specified in ISO 8824 [1]), but are transmitted as

Top      ToC       Page 11 
   a contiguous byte stream.  The data within this stream is organized
   to provide natural alignment with respect to the start of the PDU,
   permitting direct (integer) access by the processing entities.

   The first four fields in the header are single-byte values.  A bit
   (NETWORK_BYTE_ORDER) in the third field (h.flags) is used to indicate
   the byte ordering of all multi-byte integer values in the PDU,
   including those which follow in the header itself.  This is described
   in more detail in Section 6.1, "AgentX PDU Header", below.

   PDUs are depicted in this memo using the following convention (where
   byte 1 is the first transmitted byte):

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  byte 1       |  byte 2       |  byte 3       |  byte 4       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  byte 5       |  byte 6       |  byte 7       |  byte 8       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Fields marked "<reserved>" are reserved for future use and must be
   zero-filled.

5.1.  Object Identifier

   An object identifier is encoded as a 4-byte header, followed by a
   variable number of contiguous 4-byte fields representing sub-
   identifiers.  This representation (termed Object Identifier) is as
   follows:

   Object Identifier

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  n_subid      |  prefix       |  include      |  <reserved>   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       sub-identifier #1                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       sub-identifier #n_subid                 |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Object Identifier header fields:

      n_subid

         The number (0-128) of sub-identifiers in the object identifier.
         An ordered list of "n_subid" 4-byte sub-identifiers follows the
         4-byte header.

Top      ToC       Page 12 
      prefix

         An unsigned value used to reduce the length of object
         identifier encodings.  A non-zero value "x" is interpreted as
         the first sub-identifier after "internet" (1.3.6.1), and
         indicates an implicit prefix "internet.x" to the actual sub-
         identifiers encoded in the Object Identifier.  For example, a
         prefix field value 2 indicates an implicit prefix "1.3.6.1.2".
         A value of 0 in the prefix field indicates there is no prefix
         to the sub-identifiers.

      include

         Used only when the Object Identifier is the start of a
         SearchRange, as described in section 5.2.

   A null Object Identifier consists of the 4-byte header with all bytes
   set to 0.

   Examples:

   sysDescr.0 (1.3.6.1.2.1.1.1.0)

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 4             | 2             | 0             | 0             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 0                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   1.2.3.4

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 4             | 0             | 0             | 0             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 2                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 3                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 4                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Top      ToC       Page 13 
5.2.  SearchRange

   A SearchRange consists of two Object Identifiers.  In its
   communication with a subagent, the master agent uses a SearchRange to
   identify a requested variable binding, and, in GetNext and GetBulk
   operations, to set an upper bound on the names of managed object
   instances the subagent may send in reply.

   The first Object Identifier in a SearchRange (called the starting
   OID) indicates the beginning of the range.  It is frequently (but not
   necessarily) the name of a requested variable binding.

   The "include" field in this OID's header is a boolean value (0 or 1)
   indicating whether or not the starting OID is included in the range.

   The second object identifier indicates the non-inclusive end of the
   range, and its "include" field is always 0.

   Example:  To indicate a search range from 1.3.6.1.2.1.25.2
   (inclusive) to 1.3.6.1.2.1.25.2.1 (exclusive), the SearchRange would
   be

   (start)
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 3             | 2             | 1             |       0       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 25                                                            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 2                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   (end)
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 4             | 2             | 0             |       0       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 25                                                            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 2                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1                                                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   A SearchRangeList is a contiguous list of SearchRanges.

Top      ToC       Page 14 
5.3.  Octet String

   An octet string is represented by a contiguous series of bytes,
   beginning with a 4-byte integer whose value is the number of octets
   in the octet string, followed by the octets themselves.  This
   representation is termed an Octet String.  If the last octet does not
   end on a 4-byte offset from the start of the Octet String, padding
   bytes are appended to achieve alignment of following data.  This
   padding must be added even if the Octet String is the last item in
   the PDU.  Padding bytes must be zero filled.

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                     Octet String Length (L)                   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Octet 1      |  Octet 2      |   Octet 3     |   Octet 4     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Octet L - 1  |  Octet L      |       Padding (as required)   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   A null Octet String consists of a 4-byte length field set to 0.

5.4.  Value Representation

   Variable bindings may be encoded within the variable-length portion
   of some PDUs.  The representation of a variable binding (termed a
   VarBind) consists of a 2-byte type field, a name (Object Identifier),
   and the actual value data.

   VarBind

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          v.type               |          <reserved>           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   (v.name)
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  n_subid      |  prefix       |      0        |       0       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       sub-identifier #1                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       sub-identifier #n_subid                 |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Top      ToC       Page 15 
   (v.data)
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       data                                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       data                                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   VarBind fields:

   v.type

         Indicates the variable binding's syntax, and must be one of
         the following values:

                     Integer                  (2),
                     Octet String             (4),
                     Null                     (5),
                     Object Identifier        (6),
                     IpAddress               (64),
                     Counter32               (65),
                     Gauge32                 (66),
                     TimeTicks               (67),
                     Opaque                  (68),
                     Counter64               (70),
                     noSuchObject           (128),
                     noSuchInstance         (129),
                     endOfMibView           (130)

   v.name

         The Object Identifier which names the variable.

   v.data

         The actual value, encoded as follows:

          - Integer, Counter32, Gauge32, and TimeTicks are encoded as
            4 contiguous bytes.  If the NETWORK_BYTE_ORDER bit is set
            in h.flags, the bytes are ordered most significant to least
            significant, otherwise they are ordered least significant
            to most significant.

          - Counter64 is encoded as 8 contiguous bytes.  If the
            NETWORK_BYTE_ORDER bit is set in h.flags, the bytes are
            ordered most significant to least significant, otherwise
            they are ordered least significant to most significant.

Top      ToC       Page 16 
          - Object Identifiers are encoded as described in section
            5.1, Object Identifier.

          - IpAddress, Opaque, and Octet String are all octet strings
            and are encoded as described in section 5.3, Octet String.

            Value data always follows v.name whenever v.type is one
            of the above types.  These data bytes are present even if
            they will not be used (as, for example, in certain types
            of index allocation).

          - Null, noSuchObject, noSuchInstance, and endOfMibView do not
            contain any encoded value.  Value data never follows
            v.name in these cases.

         Note that the VarBind itself does not contain the value size.
         That information is implied for the fixed-length types, and
         explicitly contained in the encodings of variable-length types
         (Object Identifier and Octet String).

   A VarBindList is a contiguous list of VarBinds.  Within a
   VarBindList, a particular VarBind is identified by an index value.
   The first VarBind in a VarBindList has index value 1, the second
   has index value 2, and so on.

6.  Protocol Definitions

6.1.  AgentX PDU Header

   The AgentX PDU header is a fixed-format, 20-octet structure:

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   h.version   |    h.type     |    h.flags    |  <reserved>   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          h.sessionID                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        h.transactionID                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          h.packetID                           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        h.payload_length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   An AgentX PDU header contains the following fields:

      h.version

         The version of the AgentX protocol (1 for this memo).

Top      ToC       Page 17 
      h.type

         The PDU type; one of the following values:

              agentx-Open-PDU             (1),
              agentx-Close-PDU            (2),
              agentx-Register-PDU         (3),
              agentx-Unregister-PDU       (4),
              agentx-Get-PDU              (5),
              agentx-GetNext-PDU          (6),
              agentx-GetBulk-PDU          (7),
              agentx-TestSet-PDU          (8),
              agentx-CommitSet-PDU        (9),
              agentx-UndoSet-PDU         (10),
              agentx-CleanupSet-PDU      (11),
              agentx-Notify-PDU          (12),
              agentx-Ping-PDU            (13),
              agentx-IndexAllocate-PDU   (14),
              agentx-IndexDeallocate-PDU (15),
              agentx-AddAgentCaps-PDU    (16),
              agentx-RemoveAgentCaps-PDU (17),
              agentx-Response-PDU        (18)

      h.flags

         A bitmask, with bit 0 the least significant bit.  The bit
         definitions are as follows:

                 Bit             Definition
                 ---             ----------
                 0               INSTANCE_REGISTRATION
                 1               NEW_INDEX
                 2               ANY_INDEX
                 3               NON_DEFAULT_CONTEXT
                 4               NETWORK_BYTE_ORDER
                 5-7             (reserved)

         The NETWORK_BYTE_ORDER bit applies to all multi-byte integer
         values in the entire AgentX packet, including the remaining
         header fields.  If set, then network byte order (most
         significant byte first; "big endian") is used.  If not set,
         then least significant byte first ("little endian") is used.

         The NETWORK_BYTE_ORDER bit applies to all AgentX PDUs.

         The NON_DEFAULT_CONTEXT bit is used only in the AgentX PDUs
         described in section 6.1.1.

Top      ToC       Page 18 
         The NEW_INDEX and ANY_INDEX bits are used only within the
         agentx-IndexAllocate-, and -IndexDeallocate-PDUs.

         The INSTANCE_REGISTRATION bit is used only within the agentx-
         Register-PDU.

      h.sessionID

         The session ID uniquely identifies a session over which AgentX
         PDUs are exchanged between a subagent and the master agent.
         The session ID has no significance and no defined value in the
         agentx-Open-PDU sent by a subagent to open a session with the
         master agent; in this case, the master agent will assign a
         unique sessionID that it will pass back in the corresponding
         agentx-Response-PDU.  From that point on, that same sessionID
         will appear in every AgentX PDU exchanged over that session
         between the master and the subagent.  A subagent may establish
         multiple AgentX sessions by sending multiple agentx-Open-PDUs
         to the master agent.

         In master agents that support multiple transport protocols, the
         sessionID should be globally unique rather than unique just to
         a particular transport.

      h.transactionID

         The transaction ID uniquely identifies, for a given session,
         the single SNMP management request (and single SNMP PDU) with
         which an AgentX PDU is associated.  If a single SNMP management
         request results in multiple AgentX PDUs being sent by the
         master agent with the same sessionID, each of these AgentX PDUs
         must contain the same transaction ID; conversely, AgentX PDUs
         sent during a particular session, that result from distinct
         SNMP management requests, must have distinct transaction IDs
         within the limits of the 32-bit field).

         Note that the transaction ID is not the same as the SNMP PDU's
         request-id (as described in section 4.1 of RFC 1905 [4]), nor
         can it be, since a master agent might receive SNMP requests
         with the same request-ids from different managers.

         The transaction ID has no significance and no defined value in
         AgentX administrative PDUs, i.e., AgentX PDUs that are not
         associated with an SNMP management request.

Top      ToC       Page 19 
      h.packetID

         A packet ID generated by the sender for all AgentX PDUs except
         the agentx-Response-PDU. In an agentx-Response-PDU, the packet
         ID must be the same as that in the received AgentX PDU to which
         it is a response.  A master agent might use this field to
         associate subagent response PDUs with their corresponding
         request PDUs.  A subagent might use this field to correlate
         responses to multiple (batched) registrations.

      h.payload_length

         The size in octets of the PDU contents, excluding the 20-byte
         header.  As a result of the encoding schemes and PDU layouts,
         this value will always be either 0, or a multiple of 4.

6.1.1.  Context

   In the SNMPv1 or v2c frameworks, the community string may be used as
   an index into a local repository of configuration information that
   may include community profiles or more complex context information.
   Future versions of the SNMP will likely formalize this notion of
   "context".

   AgentX provides a mechanism for transmitting a context specification
   within relevant PDUs, but does not place any constraints on the
   content of that specification.

   An optional context field may be present in the agentx-Register-,
   UnRegister-, AddAgentCaps-, RemoveAgentCaps-, Get-, GetNext-,
   GetBulk-, IndexAllocate-, IndexDeallocate-, Notify-, TestSet-, and
   Ping- PDUs.

   If the NON_DEFAULT_CONTEXT bit in the AgentX header field h.flags is
   clear, then there is no context field in the PDU, and the operation
   refers to the default context.

   If the NON_DEFAULT_CONTEXT bit is set, then a context field
   immediately follows the AgentX header, and the operation refers to
   that specific context.  The context is represented as an Octet
   String.  There are no constraints on its length or contents.

   Thus, all of these AgentX PDUs (that is, those listed immediately
   above) refer to, or "indicate" a context, which is either the default
   context, or a non-default context explicitly named in the PDU.


Next RFC Part