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/O
8.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 RFC1592 [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", RFC2571, 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,
RFC1212, March 1991.
[4] Rose, M., "A Convention for Defining Traps for use with the
SNMP", RFC1215, 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, RFC2578, April 1999.
[6] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose,
M. and S. Waldbusser, "Textual Conventions for SMIv2", STD 58,
RFC2579, April 1999.
[7] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose,
M. and S. Waldbusser, "Conformance Statements for SMIv2", STD
58, RFC2580, April 1999.
[8] Case, J., Fedor, M., Schoffstall, M. and J. Davin, "Simple
Network Management Protocol", STD 15, RFC1157, May 1990.
[9] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
"Introduction to Community-based SNMPv2", RFC1901, January
1996.
[10] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
"Transport Mappings for Version 2 of the Simple Network
Management Protocol (SNMPv2)", RFC1906, January 1996.
[11] Case, J., Harrington D., Presuhn R. and B. Wijnen, "Message
Processing and Dispatching for the Simple Network Management
Protocol (SNMP)", RFC2572, April 1999.
[12] Blumenthal, U. and B. Wijnen, "User-based Security Model (USM)
for version 3 of the Simple Network Management Protocol
(SNMPv3)", RFC2574, April 1999.
[13] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser, "Protocol
Operations for Version 2 of the Simple Network Management
Protocol (SNMPv2)", RFC1905, 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)", RFC2575, April 1999.
[16] Case, J., Mundy, R., Partain, D. and B. Stewart, "Introduction
to Version 3 of the Internet-standard Network Management
Framework", RFC2570, 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)", RFC1907, 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", RFC2233, November 1997.
[20] Case, J., "FDDI Management Information Base", RFC1285, January
1992.
[21] Krupczak, C. and J. Saperia, "Definitions of System-Level
Managed Objects for Applications", RFC2287, April 1997.
[22] Kalbfleisch, C., Krupczak, C., Presuhn, R. and J. Saperia,
"Application Management MIB", RFC2564, 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", RFC1908, January 1996.
[25] Wijnen, B. and D. Levi, "V2ToV1: Mapping SNMPv2 onto SNMPv1
Within a Bilingual SNMP Agent", RFC2089, January 1997.
[26] Wijnen, B., Carpenter, G., Curran, K., Sehgal, A. and G.
Waters, "Simple Network Management Protocol: Distributed
Protocol Interface, Version 2.0", RFC1592, March 1994.
[27] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC2119, 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 RFC2257
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 RFCEditor function is currently provided by the
Internet Society.