URI Scheme for SNMP February 2004
Network Working Group D.Black
Internet Draft EMC Corporation
Document: draft-black-snmp-uri-03.txt K. McCloghrie
Expires: August 2004 Cisco Systems
J. Schoenwaelder
International University Bremen
February 2004
URI Scheme for SNMP
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
SNMP and the Internet-Standard Management Framework are widely
used for management of communication devices, creating needs to
specify SNMP access (including access to SNMP MIB object
instances) from non-SNMP management environments. For example,
when out-of-band IP management is used via a separate management
interface (e.g., for a device that does not support in-band IP
access), there is a need for a uniform way to indicate how to
contact the device for management. URLs fit this need well, as
they allow a single text string to indicate a management access
communication endpoint for a wide variety of IP-based protocols.
This document defines a simple URI scheme so that SNMP can be
designated as the protocol used for management. This scheme also
allows URI specification of individual MIB object instances.
Black Expires - August 2004 [Page 1]
URI Scheme for SNMP February 2004
Conventions used in this document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in [RFC 2119].
Table of Contents
1. Introduction...................................................2
2. Syntax of an SNMP URI..........................................3
3. Semantics and Operations.......................................4
3.1 SNMP Service URIs..........................................4
3.2 SNMP Object URIs...........................................5
3.3 Interoperability Considerations............................7
4. Examples.......................................................7
5. Security Considerations........................................8
6. IANA Considerations............................................9
7. Change History (to be deleted prior to RFC publication)........9
8. Normative References..........................................10
9. Informative References........................................10
10. Acknowledgments..............................................11
11. Author's Addresses...........................................11
1. Introduction
SNMP and the Internet-Standard Management Framework were
originally devised to manage IP devices via in-band means where
management access is primarily via the same interface(s) used to
send and receive IP traffic. SNMP's wide adoption has resulted in
its use to manage communication devices that do not support in-
band IP access (e.g., Fibre Channel devices); a separate out-of-
band IP interface is often used for management. URLs provide a
convenient way to locate that interface and specify the protocol
to be used for management; one possible scenario is for an in-band
query to return a text string URL that indicates how the device is
managed. This document specifies a URI scheme to permit SNMP
(including a specific SNMP context) to be designated as the
management protocol by such a URL. The scheme contains OPTIONAL
extensions that allow a URI to refer to specific information
within an SNMP MIB.
Black Expires - August 2004 [Page 2]
URI Scheme for SNMP February 2004
2. Syntax of an SNMP URI
An SNMP URI has the following ABNF [RFC 2234] syntax:
snmp_URI = "snmp:" "//" [ user "@" ] host [ ":" port ]
[ "/" context [ ";" "engine=" engine ]
[ "/" oid [ "+" | ".*" ] ] ]
user = < SNMP user name as specified by [RFC 3414] >
host = < as specified by [rfc2396bis] >
port = < as specified by [rfc2396bis] >
engine = "0x" hex [ (hex)* ] ; SNMP contextEngineID as
; specified by [RFC 3411] with a "0x" prefix
hex = < Hex digit, as specified by [rfc2396bis] >
context = < SNMP context name as specified by [RFC 3411] >
oid = < OID as specified by [RFC 3061] >
The [ user "@" ] host [ ":" port ] portion of the above syntax
matches the URI authority component as defined in section 3 of
[2396bis] and adds the additional restriction that (if present)
the user element (userinfo in [rfc2396bis]) MUST be an SNMP user
name. If the user is empty or not given, the entity making use of
an SNMP URI is expected to know what SNMP user name to use if one
is required. If the port is empty or not given, port 161 is
assumed. If the context is empty or not given, the empty string
("") is assumed, as it is the default SNMP context.
An SNMP contextEngineID is a variable-format binary element that
is usually discovered by an SNMP Manager. If the engine is empty
or not given, the engine is to be discovered by interrogating the
SNMP Agent at the specified host and port; see Section 3.1.
ISSUE: When context and engine are not given, the above syntax
results in "//" following the authority component (e.g.,
snmp://<host>//<oid>). If this is a problem, the following syntax
is an alternative that could replace the above syntax:
snmp_URI = "snmp:" "//" [ user "@" ] host [ ":" port ]
[ "/" "context=" context
[ ";" "engine=" engine ] ]
[ "/" oid [ "+" | ".*" ] ]
It differs from the above syntax by using "context=" to introduce
SNMP contexts, and omitting the '/' that introduces the context
component when the default (empty string) context is used.
The encoding rules specified in [rfc2396bis] apply to SNMP URIs,
including the use of percent encoding ('%' character plus two hex
digits) to represent reserved and non-US-ASCII characters. SNMP
allows any UTF-8 character to be used in the user name and context
Black Expires - August 2004 [Page 3]
URI Scheme for SNMP February 2004
name strings. For the user and context elements of an SNMP URI,
UTF-8 characters outside the set of unreserved US-ASCII characters
(see [rfc2396bis], Section 2.3) MUST be percent encoded as
specified in [rfc2396bis] (Section 2.1), and all bytes of multi-
byte UTF-8 characters MUST be percent encoded, one byte at a time.
SNMP URIs will generally be short enough to avoid implementation
string length limits (e.g., that may occur at 255 characters).
Use of IP addresses in SNMP URIs is acceptable in situations where
dependence on availability of DNS service is undesirable or must
be avoided; otherwise IP addresses should not be used (see [RFC
1900] for further explanation).
3. Semantics and Operations
An SNMP URI that does not include an oid is called an SNMP service
URI because it designates a communication endpoint for access to
SNMP management service. An SNMP URI that includes an oid is
called an SNMP object URI because it designates one or more object
instances in an SNMP MIB.
For a detailed overview of the documents that describe the current
Internet-Standard Management Framework, please refer to section 7
of [RFC 3410].
3.1 SNMP Service URIs
An SNMP service URI does not designate a data object, but rather
an interactive service that accesses an SNMP context; the telnet
URI scheme [RFC 1738] is another example of using a URI to
designate a service. The expected means of accessing information
designated by an SNMP service URI is to use an SNMP Manager to
access the SNMP context designated by the URI via the SNMP Agent
at the host and port designated by the URI; if the context is
empty or not given, "" (the empty string) is assumed as it is the
default SNMP context.
If an engine is given in the URI, the context is to be accessed
via that SNMP engine. If the engine is empty or not given in the
URI, the engine is to be discovered; the engine to be used is the
one that supports the designated context. The engine component of
the URI SHOULD be present if more than one engine at the
designated host and port supports the designated context.
The most common uses of SNMP URIs are expected to omit (i.e.,
default) both engine and context. SNMP proxy agents are the most
likely reason for multiple SNMP engines to exist at a single host
and port; when an SNMP Agent is local to the transport endpoint
that it manages, it will usually have only one engine and it is
Black Expires - August 2004 [Page 4]
URI Scheme for SNMP February 2004
generally safe to omit the engine component of an SNMP URI when
there is no SNMP proxy involved. In many cases, only the default
SNMP context (empty string) exists at this engine.
3.2 SNMP Object URIs
An SNMP object URI contains an oid component. The URI is used by
first separating the oid component (including any suffix), and
processing the resulting SNMP service URI as specified in Section
3.1 to determine the SNMP context to be accessed. The engine
component SHOULD be present if more than one engine at the
designated host and port that supports the designated context.
The oid component is then used to generate SNMP operations
directed to that SNMP context.
The semantics of an SNMP object URI depend on whether the oid has
a suffix and what that suffix is. There are three possibilities;
in each case, the designation is within the SNMP context specified
by the service URI portion of the SNMP object URI:
(1) An oid without a suffix designates the MIB object instance
named by that oid.
(2) An oid with a "+" suffix designates the lexically next MIB
object instance following that oid.
(3) An oid with a ".*" suffix designates the set of MIB object
instances for which that oid is a lexical prefix.
When there is a choice among syntax formats to designate the same
MIB object instance, the above list is in order of preference (no
suffix is most preferable) as it runs from most precise to least
precise. This is because an oid without a suffix precisely
designates an object instance, whereas a "+" suffix designates the
next object instance, which may change, and the ".*" suffix could
designate multiple object instances. Use of multiple
syntactically distinct URIs to designate the same MIB object
instance is NOT RECOMMENDED as it may cause unexpected results in
URI-based systems that use string comparison to test URIs for
equality.
An SNMP URI can also be used to designate a MIB object instance to
be written via an SNMP Set operation; the oid MUST NOT have a
suffix in this case, and the data to be written is not given
within the URI.
The SNMP operation or operations generated to access the data
designated by an SNMP object URI depend on the oid suffix or
absence thereof:
(1) For an OID without a suffix, an SNMP Get operation is
Black Expires - August 2004 [Page 5]
URI Scheme for SNMP February 2004
generated using the OID as a variable binding name. The result
of URI data access is the result of the generated operation.
Note that SNMP errors, and the values "noSuchObject" and
"noSuchInstance" are possible results; see [RFC 3416].
(2) For an OID with a "+" suffix, an SNMP Get Next operation is
generated using the OID as a variable binding name. The result
of URI data access is the result of the generated operation.
Note that SNMP errors and the "endOfMibView" value are possible
results in this case; see [RFC 3416].
(3) For an OID with a ".*" suffix, an SNMP Get Next operation is
generated using the OID as a variable binding name. If the
result is an SNMP error, that error is the result of URI data
access. If the resulting variable binding contains an OID for
which the original OID is not a lexical prefix, the result of
URI data access is the value "noSuchObject". If the resulting
variable binding contains an "endOfMibView" value, that value
is the result of URI data access. In all three cases, URI data
access processing is complete.
Otherwise, an SNMP Get Next operation is generated using the
newly returned OID as a variable binding name; this is
iterated until the Get Next variable binding returns an OID for
which the original OID is not a lexical prefix, or returns an
"endOfMibView" value or returns an SNMP error. The result of
URI data access is the set of resulting variable bindings (oids
and values) that do not contain "endOfMibView" values.
SNMP Get Bulk operations MAY be used to optimize case (3). A
single SNMP operation MAY be used to access data for all or part
of multiple SNMP URIs (e.g., via use of multiple variable bindings
in a single operation). Implementations should regard use of
relative object URIs that do not change context (i.e., ./oid) as
hints that optimization is possible, but the SNMP URI scheme does
not provide any means of specifying such optimizations.
When format (1) is used to specify a MIB object instance to be
written, an SNMP Set operation is generated instead of a Get.
Formats (2) and (3) (i.e., the "+" and ".*" oid suffixes) MUST NOT
be used to specify write actions; any attempt to perform a write
based on these two SNMP object URI formats is an error and MUST
NOT generate any SNMP Set operations.
Black Expires - August 2004 [Page 6]
URI Scheme for SNMP February 2004
3.3 Interoperability Considerations
This document defines a transport-independent "snmp:" scheme that
is intended to accommodate SNMP transports other than UDP. UDP is
the default transport for access to information specified by an
"snmp:" URI for backwards compatibility with existing usage, but
other transports MAY be used. If more than one transport can be
used (e.g., SNMP over TCP [RFC 3430] in addition to SNMP over UDP)
the information or SNMP service access designated by an SNMP URI
SHOULD NOT depend on which transport is used (for SNMP over TCP,
this is implied by Section 2 of [RFC 3430]).
An SNMP URI designates use of SNMPv3 as specified by [RFC 3416],
[RFC 3417] and related documents, but older versions of SNMP MAY
be used for access designated by an SNMP URI in accordance with
[RFC 3584] where usage of such older versions is unavoidable.
SNMP versions (e.g., v3) have been omitted from these URI schemes
for forwards compatibility with any possible future successor to
SNMPv3.
4. Examples
snmp://snmp.example.com
This example designates the default SNMP context at the SNMP Agent
at UDP port 161 of host snmp.example.com .
snmp://tester5@snmp.example.com:8161
This example designates the default SNMP context at the SNMP Agent
at UDP port 8161 of host snmp.example.com and indicates that the
SNMP user name "tester5" is to be used to access that Agent. A
possible reason for use of a non-standard port is testing of a new
version of SNMP Agent code.
snmp://snmp.example.com/bridge1
This example designates the "bridge1" SNMP context at
snmp.example.com. Because the engine component of the URI is
omitted, there SHOULD be at most one SNMP context engine at
snmp.example.com that supports the "bridge1" context.
snmp://snmp.example.com/bridge1;engine=0x800002b804616263
This also designates the "bridge1" context at snmp.example.com via
the SNMP contextEngineID 0x800002b804616263. This avoids
ambiguity if some other context engine also supports a "bridge1"
Black Expires - August 2004 [Page 7]
URI Scheme for SNMP February 2004
context. The above two examples are based on the figure in
Section 3.3 of [RFC 3411].
snmp://snmp.example.com//1.3.6.1.2.1.1.3.0
snmp://snmp.example.com//1.3.6.1.2.1.1.3+
snmp://snmp.example.com//1.3.6.1.2.1.1.3.*
These three examples all designate the sysUpTime.0 object instance
in the SNMPv2-MIB for the default SNMP context ("") at
snmp.example.com as sysUpTime.0 is:
a) designated directly by oid 1.3.6.1.2.1.1.3.0,
b) the lexically next MIB object instance after the oid
1.3.6.1.2.1.1.3, and
c) the only MIB object instance whose oid has 1.3.6.1.2.1.1.3
as a lexical prefix.
These three examples are provided for illustrative purposes only,
as use of multiple syntactically distinct URIs to designate the
same MIB object instance is NOT RECOMMENDED because it may cause
unexpected results in URI-based systems that use string comparison
to test URIs for equality.
snmp://snmp.example.com/bridge1/1.3.6.1.2.1.2.2.1.8.*
This example designates the ifOperStatus column of the IF-MIB in
the bridge1 SNMP context at snmp.example.com.
5. Security Considerations
An intended use of this URI scheme is designation of the location
of management access to communication devices. Such location
information may be considered sensitive in some environments,
making it important to control even read access to that
information and possibly even to encrypt it when sending it over
the network. All uses of this URI scheme should provide security
mechanisms appropriate to the environments in which such uses are
likely to be deployed.
There are management objects defined in SNMP MIBs whose MAX-ACCESS
is read-write and/or read-create. Such objects may be considered
sensitive or vulnerable in some network environments. The support
for SNMP SET operations in a non-secure environment without proper
protection can have a negative effect on network operations. The
individual MIB module specifications, and especially their
security considerations, should be consulted for further
information.
Some readable objects in some MIB modules (i.e., objects with a
MAX-ACCESS other than not-accessible) may be considered sensitive
or vulnerable in some network environments. It is thus important
Black Expires - August 2004 [Page 8]
URI Scheme for SNMP February 2004
to control even GET and/or NOTIFY access to these objects and
possibly to even encrypt the values of these objects when sending
them over the network via SNMP. The individual MIB module
specifications, and especially their security considerations,
should be consulted for further information. This consideration
also applies to readable objects for which read operations have
side effects.
SNMP versions prior to SNMPv3 did not include adequate security.
Even if the network itself is secure (for example via use of
IPsec), there is no control over who on the secure network is
allowed to access and GET/SET (read/change/create/delete) the
objects in MIB modules. It is RECOMMENDED that implementers
consider the security features as provided by the SNMPv3 framework
(see [RFC 3410], section 8 for an overview), including full
support for SNMPv3 cryptographic mechanisms (for authentication
and privacy). This is of additional importance for MIB elements
considered sensitive or vulnerable because GETs have side effects.
Further, deployment of SNMP versions prior to SNMPv3 is NOT
RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to
enable cryptographic security. It is then a customer/operator
responsibility to ensure that the SNMP entity giving access to a
MIB module instance is properly configured to give access to the
objects only to those principals (users) that have legitimate
rights to indeed GET or SET (change/create/delete) them.
6. IANA Considerations
The IANA is asked to register the URL registration template found
in Appendix A in accordance with [RFC 2717].
7. Change History (to be deleted prior to RFC publication)
-00: Initial version - user, host and port only.
-01: Initial attempt to add engine, context, and oid, plus
support for alternate (non-UDP) transports.
-02: Reworked engine, context, and oid syntax. Made URI scheme
transport-independent. Added more examples. Significant text
editing and rearrangement.
-03: Updated to base on rfc2396bis draft instead of RFC 2396.
This caused the context and engine syntax to change again, as
the rfc2396bis draft has additional restrictions on the
the authority component of a URI. Minor text editing.
Black Expires - August 2004 [Page 9]
URI Scheme for SNMP February 2004
8. Normative References
[rfc2396bis] Uniform Resource Identifiers (URI): Generic Syntax.
T. Berners-Lee, R. Fielding, L. Masinter.
Internet-Draft draft-fielding-uri-rfc2396bis.
Work in Progress. February 2004.
[RFC 2119] Key words for use in RFCs to Indicate Requirement
Levels. S. Bradner. RFC 2119, BCP 14. March 1997.
[RFC 2234] Augmented BNF for Syntax Specifications: ABNF.
D. Crocker, Ed., P. Overell. RFC 2234. November 1997.
[RFC 3061] A URN Namespace of Object Identifiers. M. Mealling.
February 2001.
[RFC 3411] An Architecture for Describing Simple Network
Management Protocol (SNMP) Management Frameworks.
D. Harrington, R. Presuhn, B. Wijnen. December 2002.
[RFC 3414] User-based Security Model (USM) for version 3 of the
Simple Network Management Protocol (SNMPv3).
U. Blumenthal, B. Wijnen. RFC 3414. December 2002.
[RFC 3416] Version 2 of the Protocol Operations for the Simple
Network Management Protocol (SNMP). R. Presuhn, Ed.
RFC 3416. December 2002.
[RFC 3417] Transport Mappings for the Simple Network Management
Protocol (SNMP). R. Presuhn, Ed. RFC 3417.
December 2002.
[RFC 3584] Coexistence between Version 1, Version 2, and Version 3
of the Internet-standard Network Management Framework.
R. Frye, D. Levi, S. Routhier, B. Wijnen. RFC 3584.
August 2003.
9. Informative References
[RFC 1738] Uniform Resource Locators (URL). T. Berners-Lee,
L. Masinter, M. McCahill. RFC 1738. December 1994.
[RFC 1900] Renumbering Needs Work. B. Carpenter, Y. Rekhter.
RFC 1900. February 1996.
[RFC 2026] The Internet Standards Process -- Revision 3.
S. Bradner. RFC 2026, BCP 9. October 1996.
Black Expires - August 2004 [Page 10]
URI Scheme for SNMP February 2004
[RFC 2717] Registration Procedures for URL Scheme Names. R. Petke,
I. King. RFC 2717. November 1999.
[RFC 3410] Introduction and Applicability Statements for Internet-
Standard Management Framework. J. Case, R. Mundy,
D. Partain, B. Stewart. RFC 3410. December 2002.
[RFC 3430] Simple Network Management Protocol Over Transmission
Control Protocol Transport Mapping. J. Schoenwaelder.
December 2002.
[RFC 3617] Uniform Resource Identifier (URI) Scheme and
Applicability Statement for the Trivial File Transfer
Protocol (TFTP). E. Lear. October 2003.
10. Acknowledgments
Significant portions of this draft were adapted from Eliot Lear's
TFTP URI scheme specification [RFC 3617]. The security
considerations text was adapted from the widely used security
considerations "boilerplate" for MIB modules. Comments from Ted
Hardie, Michael Mealing, Larry Masinter and the uri@w3c.org
mailing list on earlier versions of this draft have resulted in
significant improvements and are gratefully acknowledged.
11. Author's Addresses
David L. Black
EMC Corporation
176 South Street
Hopkinton, MA 01748
Phone: +1 (508) 293-7953
Email: black_david@emc.com
Keith McCloghrie
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA USA 95134
Phone: +1 (408) 526-5260
Email: kzm@cisco.com
Juergen Schoenwaelder
International University Bremen
P.O. Box 750 561
28725 Bremen
Germany
Phone: +49 421 200 3587
Email: j.schoenwaelder@iu-bremen.de
Black Expires - August 2004 [Page 11]
URI Scheme for SNMP February 2004
Appendix A. Registration Template
URL scheme name: snmp
URL scheme syntax: Section 2
Character encoding considerations: Section 2
Intended usage: Section 1
Applications and/or protocols which use this scheme: SNMP, all
versions, see [RFC 3410] and [RFC 3584]
Interoperability considerations: Section 3.3
Security considerations: Section 5
Relevant publications: See [RFC 3410] for list
Contact: David L. Black, Section 11
Author/Change Controller: IESG
Black Expires - August 2004 [Page 12]
