RFC 2741
Agent Extensibility (AgentX) Protocol Version 1
7.3. State Transitions
State diagrams are presented from the master agent's perspective for transport connection and session establishment, and from the subagent's perspective for Set transaction processing.7.3.1. Set Transaction States
The following table presents, from the subagent's perspective, the state transitions involved in Set transaction processing:
STATE
+---------------+--------------+---------+--------+--------
| A | B | C | D | E
| (Initial | TestOK | Commit | Test | Commit
| State) | | OK | Fail | Fail
| | | | |
EVENT | | | | |
---------+---------------+--------------+---------+--------+--------
| 7.2.4.1 | | | |
Receive | All varbinds | | | |
TestSet | OK? | X | X | X | X
PDU | Yes ->B | | | |
| No ->D | | | |
---------+---------------+--------------+---------+--------+--------
| | 7.2.4.2 | | |
Receive | | NoError? | | |
Commit- | X | Yes ->C | X | X | X
Set PDU | | No ->E | | |
---------+---------------+--------------+---------+--------+--------
Receive | | | 7.2.4.3 | |7.2.4.3
UndoSet | X | X | ->done | X | ->done
PDU | | | | |
---------+---------------+--------------+---------+--------+--------
Receive | | 7.2.4.4 | 7.2.4.4 |7.2.4.4 |
Cleanup- | X | ->done | ->done | ->done | X
Set PDU | | | | |
---------+---------------+--------------+---------+--------+--------
Session | | rollback | undo | |
Loss | ->done | ->done | ->done | ->done | ->done
---------+---------------+--------------+---------+--------+--------
There are three possible sequences that a subagent may follow for a
particular set transaction:
1) TestSet CommitSet CleanupSet
2) TestSet CommitSet UndoSet
3) TestSet CleanupSet
Note that a single PDU sequence may result in multiple paths through
the finite state machine (FSM). For example, the sequence
TestSet CommitSet UndoSet
may walk through either of these two state sequences:
(initial) TestOK CommitOK (done)
(initial) TestOK CommitFail (done)
7.3.2. Transport Connection States
The following table presents, from the master agent's perspective, the state transitions involved in transport connection setup and teardown: STATE +--------------+-------------- | A | B | No transport | Transport | | connected | | EVENT | | ----------------+--------------+-------------- Transport | | connect | ->B | X indication | | ----------------+--------------+-------------- Receive | | if no resources Open-PDU | | available | | reject, else | X | establish | | session | | | | ->B ----------------+--------------+-------------- Receive | | if matching Response-PDU | | session id, | | feed to that | X | session's FSM | | else ignore | | | | ->B ----------------+--------------+-------------- Receive other | | if matching PDUs | | session id, | | feed to that | X | session's FSM | | else reject | | | | ->B ----------------+--------------+-------------- Transport | |notify all disconnect | |sessions on indication | X |this transport | | | | ->A ----------------+--------------+--------------
7.3.3. Session States
The following table presents, from the master agent's perspective, the state transitions involved in session setup and teardown: STATE +-------------+---------------- | A | B | No session | Session | | established EVENT | | ---------------+-------------+---------------- | 7.1.1 | Receive | | X Open PDU | ->B | ---------------+-------------+---------------- | | 7.1.8 Receive | X | Close PDU | | ->A ---------------+-------------+---------------- Receive | | 7.1.4 Register PDU | X | | | ->B ---------------+-------------+---------------- Receive | | 7.1.5 Unregister | X | PDU | | ->B ---------------+-------------+---------------- Receive | | Get PDU | | GetNext PDU | | GetBulk PDU | X | X TestSet PDU | | CommitSet PDU | | UndoSet PDU | | CleanupSet PDU | | ---------------+-------------+---------------- Receive | | 7.1.10 Notify PDU | X | | | ->B ---------------+-------------+---------------- Receive Ping | | 7.1.11 PDU | X | | | ->B ---------------+-------------+---------------- (continued next page)
---------------+-------------+----------------
Receive | | 7.1.2
IndexAllocate | X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.3
IndexDeallocate| X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.6
AddAgentxCaps | X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.7
RemoveAgentxCap| X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.2.5
Response PDU | X |
| | ->B
---------------+-------------+----------------
Receive | |
Other PDU | X | X
---------------+-------------+----------------
8. Transport Mappings
The same AgentX PDU formats, encodings, and elements of procedure are
used regardless of the underlying transport.
8.1. AgentX over TCP
8.1.1. Well-known Values
The master agent accepts TCP connection requests for the well-known
port 705. Subagents connect to the master agent using this port
number.
8.1.2. Operation
Once a TCP connection has been established, the AgentX peers use this
connection to carry all AgentX PDUs. Multiple AgentX sessions may be
established using the same TCP connection. AgentX PDUs are sent
within an AgentX session. AgentX peers are responsible for mapping
the h.sessionID to a particular TCP connection.
The AgentX entity must not "interleave" AgentX PDUs within the TCP byte stream. All the bytes of one PDU must be sent before any bytes of a different PDU. The receiving entity must be prepared for TCP to deliver byte sequences that do not coincide with AgentX PDU boundaries.8.2. AgentX over UNIX-domain Sockets
Many (BSD-derived) implementations of the UNIX operating system support the UNIX pathname address family (AF_UNIX) for socket communications. This provides a convenient method of sending and receiving data between processes on the same host. Mapping AgentX to this transport is useful for environments that - wish to guarantee subagents are running on the same managed node as the master agent, and where - sockets provide better performance than TCP or UDP, especially in the presence of heavy network I/O8.2.1. Well-known Values
The master agent creates a well-known UNIX-domain socket endpoint called "/var/agentx/master". (It may create other, implementation- specific endpoints.) This endpoint name uses the character set encoding native to the managed node, and represents a UNIX-domain stream (SOCK_STREAM) socket.8.2.2. Operation
Once a connection has been established, the AgentX peers use this connection to carry all AgentX PDUs. Multiple AgentX sessions may be established using the same connection. AgentX PDUs are sent within an AgentX session. AgentX peers are responsible for mapping the h.sessionID to a particular connection. The AgentX entity must not "interleave" AgentX PDUs within the socket byte stream. All the bytes of one PDU must be sent before any bytes of a different PDU. The receiving entity must be prepared for the socket to deliver byte sequences that do not coincide with AgentX PDU boundaries.
9. Security Considerations
This memo defines a protocol between two processing entities, one of which (the master agent) is assumed to perform authentication of received SNMP requests and to control access to management information. The master agent performs these security operations independently of the other processing entity (the subagent). Security considerations require three questions to be answered: 1. Is a particular subagent allowed to initiate a session with a particular master agent? 2. During an AgentX session, is any SNMP security-related information (for example, community names) passed from the master agent to the subagent? 3. During an AgentX session, what part of the MIB tree is this subagent allowed to register? The answer to the third question is: A subagent can register any subtree (subject to AgentX elements of procedure, section 7.1.4, "Processing the agentx-Register-PDU"). Currently there is no access control mechanism defined in AgentX. A concern here is that a malicious subagent that registers an unauthorized "sensitive" subtree, could see modification requests to those objects, or by giving its own clever answer to NMS queries, could cause the NMS to do something that leads to information disclosure or other damage. The answer to the second question is: No. Now we can answer the first question. AgentX does not contain a mechanism for authorizing/refusing session initiations. Thus, controlling subagent access to the master agent may only be done at a lower layer (e.g., transport). An AgentX subagent can connect to a master agent using either a network transport mechanism (e.g., TCP), or a "local" mechanism (e.g., shared memory, named pipes). In the case where a local transport mechanism is used and both subagent and master agent are running on the same host, connection authorization can be delegated to the operating system features. The answer to the first security question then becomes: "If and only if the subagent has sufficient privileges, then the operating system will allow the connection".
If a network transport is used, currently there is no inherent security. Transport Layer Security, SSL, or IPsec SHOULD be used to control and protect subagent connections in this mode of operation. However, we RECOMMEND that subagents always run on the same host as the master agent and that operating system features be used to ensure that only properly authorized subagents can establish connections to the master agent.10. Acknowledgements
The initial development of this memo was heavily influenced by the DPI 2.0 specification RFC 1592 [26]. This document was produced by the IETF Agent Extensibility (AgentX) Working Group, and benefited especially from the contributions of the following working group members: David Battle, Uri Blumenthal, Jeff Case, Maria Greene, Lauren Heintz, Dave Keeney, Harmen van der Linde, Bob Natale, Aleksey Romanov, Don Ryan, and Juergen Schoenwaelder. An honorable mention is extended to Randy Presuhn in recognition for his numerous technical contributions to this specification; for his many answers provided on (and hosting of) the AgentX e-mail list and ftp site, and, for the valued support and guidance Randy provided to the Working Group chair. The AgentX Working Group is chaired by: Bob Natale ACE*COMM Corporation 704 Quince Orchard Road Gaithersburg, MD 20878 Phone: +1-301-721-3000 Fax: +1-301-721-3001 EMail: bnatale@acecomm.com
11. Authors' and Editor's Addresses
Mike Daniele Compaq Computer Corporation 110 Spit Brook Rd Nashua, NH 03062 Phone: +1-603-881-1423 EMail: daniele@zk3.dec.com Bert Wijnen IBM T.J.Watson Research Schagen 33 3461 GL Linschoten Netherlands Phone: +31-348-432-794 EMail: wijnen@vnet.ibm.com Mark Ellison (WG editor) Ellison Software Consulting, Inc. 38 Salem Road Atkinson, NH 03811 Phone: +1-603-362-9270 EMail: ellison@world.std.com Dale Francisco (editor) Cisco Systems 150 Castilian Dr Goleta CA 93117 Phone: +1-805-961-3642 Fax: +1-805-961-3600 EMail: dfrancis@cisco.com
12. References
[1] Harrington, D., Presuhn, R. and B. Wijnen, "An Architecture for Describing SNMP Management Frameworks", RFC 2571, April 1999. [2] Rose, M. and K. McCloghrie, "Structure and Identification of Management Information for TCP/IP-based Internets", STD 16, RFC 1155, May 1990. [3] Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD 16, RFC 1212, March 1991. [4] Rose, M., "A Convention for Defining Traps for use with the SNMP", RFC 1215, March 1991. [5] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [6] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. [7] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. and S. Waldbusser, "Conformance Statements for SMIv2", STD 58, RFC 2580, April 1999. [8] Case, J., Fedor, M., Schoffstall, M. and J. Davin, "Simple Network Management Protocol", STD 15, RFC 1157, May 1990. [9] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Introduction to Community-based SNMPv2", RFC 1901, January 1996. [10] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1906, January 1996. [11] Case, J., Harrington D., Presuhn R. and B. Wijnen, "Message Processing and Dispatching for the Simple Network Management Protocol (SNMP)", RFC 2572, April 1999. [12] Blumenthal, U. and B. Wijnen, "User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3)", RFC 2574, April 1999.
[13] 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. [14] Levi, D., Meyer, P. and B. Stewart, "SNMPv3 Applications", RFC 2573, April 1999. [15] Wijnen, B., Presuhn, R. and K. McCloghrie, "View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP)", RFC 2575, April 1999. [16] Case, J., Mundy, R., Partain, D. and B. Stewart, "Introduction to Version 3 of the Internet-standard Network Management Framework", RFC 2570, April 1999. [17] 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. [18] Information processing systems - Open Systems Interconnection - Specification of Abstract Syntax Notation One (ASN.1), International Organization for Standardization. International Standard 8824, (December, 1987). [19] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB using SMIv2", RFC 2233, November 1997. [20] Case, J., "FDDI Management Information Base", RFC 1285, January 1992. [21] Krupczak, C. and J. Saperia, "Definitions of System-Level Managed Objects for Applications", RFC 2287, April 1997. [22] Kalbfleisch, C., Krupczak, C., Presuhn, R. and J. Saperia, "Application Management MIB", RFC 2564, May 1999. [23] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1700, October 1994. [24] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Coexistence between Version 1 and Version 2 of the Internet- standard Network Management Framework", RFC 1908, January 1996. [25] Wijnen, B. and D. Levi, "V2ToV1: Mapping SNMPv2 onto SNMPv1 Within a Bilingual SNMP Agent", RFC 2089, January 1997.
[26] Wijnen, B., Carpenter, G., Curran, K., Sehgal, A. and G. Waters, "Simple Network Management Protocol: Distributed Protocol Interface, Version 2.0", RFC 1592, March 1994. [27] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.13. Notices
The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director.
A. Changes relative to RFC 2257
Changes on the wire: - The agentx-Notify-PDU and agentx-Close-PDU now generate an agentx-Response-PDU. - The res.error field may contain three new error codes: parseFailed(266), requestDenied(267), and processingError(268). Clarifications to the text of the memo: - Modified the text of step (4) in section 4.2, "Applicability" to separate the two concerns of row creation, and counters that count rows. - The use of the r.range_subid field is more clearly defined in section 6.2.3, "The agentx-Register-PDU". - Default priority (127) for registration added to the description of r.priority in section 6.2.3, "The agentx- Register-PDU". - Made the distinction of "administrative processing" PDUs and "SNMP request processing" PDUs in section 6.1, "AgentX PDU Header" description of h.type. This distinction is used in the Elements of Procedure relative to the res.sysuptime and res.error fields. - Rewrote portions of text in section 6.2.3, "The agentx- Register-PDU" to be more explicit about the following points: - There is a default registration priority of 127. - Improved the description of r.range_subid, independent of the prefix in r.region. - Improved description and examples of how to use the registration mechanism. - Added a description for r.upper_bound. - changed r.region to r.subtree (because the text used the terms "region", "range", and "OID range" in too loose a fashion. r.subtree can not represent anything more by itself than a simple subtree. In conjunction with r.range_subid and r.upper_bound, it can represent a "region", that is, a union of subtrees) - Modified the text in section 6.2.4, "The agentx-Unregister-PDU" to include a description of u.range_subid and u.upper_bound
- Added use of the `requestDenied' error code in section 7.1.4, "Processing the agentx-Register-PDU". - Removed text in section 7, "Elements of Procedure" on parse errors and protocol errors. - Added a new section, 7.1, "Processing AgentX Administrative Messages" which defines common processing and how to use the `parseError' and `processingError' instead of closing a session, and how to handle context. - Removed the common processing text from the other administrative processing Elements of Procedure sections, and added a reference to section 7.1, "Processing AgentX Administrative Messages". The affected sections are: - 7.1.2, "Processing the agentx-IndexAllocate-PDU" - 7.1.3, "Processing the agentx-IndexDeallocate-PDU" - 7.1.4, "Processing the agentx-Register-PDU" - 7.1.5, "Processing the agentx-Unregister-PDU" - 7.1.6, "Processing the agentx-AddAgentCaps-PDU" - 7.1.7, "Processing the agentx-RemoveAgentCaps-PDU" - 7.1.8, "Processing the agentx-Close-PDU" - 7.1.10, "Processing the agentx-Notify-PDU" - 7.1.11, "Processing the agentx-Ping-PDU" - Reworked the text in section 7.1.1, "Processing the agentx-Open-PDU" to include new error codes, and, to eliminate reference to an indicated context. - Modified the text in Section 7.1.10, "Processing the agentx-Notify-PDU" to state that context checking is performed. - Substantially modified the text in section 7.1.4.1, "Handling Duplicate and Overlapping Subtrees". - Removed the section on "Using the agentx-IndexAllocate-PDU" and added section 7.1.4.2, "Registering Stuff". This change is intended to provide a more concise and a more cohesive description of how things are supposed to work. - Modified the test in section 7.1.5, "Processing the agentx-Unregister-PDU" to require a match on u.range_subid and on u.upper_bound when these fields were applicable in the corresponding agentx-Register-PDU.
- Removed all references to "splitting", and all uses of the term
"OID range". The text now refers to regions or subtrees
directly, and relies on rule (1), "Honoring the Registry", in
section 7.2.1, "Dispatching AgentX PDUs".
- Modified text in clause 4(c) of section 7.2.1, "Dispatching
AgentX PDUs", clarifying that the master agent can use its
implementation-specific default timeout value when the timeout
value registered by the subagent is impractical.
- Added text in section 7.2.2, "Subagent Processing" describing
common processing.
- Added an example to the text in section 7.2.5.3, "Processing of
Responses to agentx-GetNext-PDU and agentx-GetBulk-PDU",
and, removed the definition of "contains" from this section.
- Modified text in step (1) of section 7.2.5.5, "Processing of
Responses to agentx-CommitSet-PDUs", eliminating directive for
master agent to ignore additional responses to
agentx-CommitSet-PDUs after the first error response.
- Modified text in section 7.2.5.6, "Processing of Responses to
agentx-UndoSet-PDUs", cleaning up commit/undo elements of
procedure per feedback received on the AgentX email list.
- Modified the text in section 8.1.2, "Operation" to explicitly
prohibit interleaved sends, and, added a caution about
exchanging AgentX messages via TCP.
- Modified text to be more explicit that the OID in the
agentx-Allocate-PDU is an OBJECT-TYPE and does not contain any
instance sub-identifiers.
- Replaced the term "subagent" with the term "session" in many
places throughout the text.
- Modified the text relative to master agent processing of the
agentx-TestSet-PDU, agentx-CommitSet-PDU, and the
agentx-UndoSet-PDU to explicitly state that only "involved"
sessions receive an agentx-CommitSet-PDU, and possibly, an
agentx-UndoSet-PDU.
- Modified the text to use the term "transaction", instead of
"packet" (and others), where appropriate. This helps
distinguish the overall transaction from a particular sequence
of packets or PDUs.
- Modified the text to explicitly state that a session is not
required to support concurrent sets.
- Added section 13, "Notices".
- Added text to section 1, Introduction, relative to BCP 14 key
words.
- Modified text to section 9, Security Considerations, to include
use of BCP 14 key words.
- Modified text to section 9, Security Considerations, to include
IPSEC as a suggested Transport Layer Security.
Full Copyright Statement Copyright (C) The Internet Society (2000). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.