Request for Comments: 4088 EMC Corporation
Category: Standards Track K. McCloghrie
Cisco Systems
J. Schoenwaelder
International University Bremen
June 2005
Uniform Resource Identifier (URI) Scheme for the
Simple Network Management Protocol (SNMP)
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 (2005).
Abstract
The Simple Network Management Protocol (SNMP) and the Internet
Standard Management Framework are widely used for the management of
communication devices, creating a need 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), a uniform way to indicate how to
contact the device for management is needed. Uniform Resource
Identifiers (URIs) 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 URI scheme so that SNMP can be designated as
the protocol used for management. The scheme also allows a URI to
designate one or more MIB object instances.
Table of Contents
1. Introduction.................................................. 2
2. Usage......................................................... 3
3. Syntax of an SNMP URI......................................... 4
3.1. Relative Reference Considerations........................ 5
4. Semantics and Operations...................................... 6
4.1. SNMP Service URIs........................................ 6
4.2. SNMP Object URIs......................................... 7
4.2.1. SNMP Object URI Data Access....................... 8
4.3. OID Groups in SNMP URIs.................................. 10
4.4. Interoperability Considerations.......................... 10
5. Examples...................................................... 11
6. Security Considerations....................................... 12
6.1. SNMP URI to SNMP Gateway Security Considerations......... 13
7. IANA Considerations........................................... 14
8. Normative References.......................................... 14
9. Informative References........................................ 15
10. Acknowledgements............................................. 16
Appendix A. Registration Template................................ 17
1. Introduction
SNMP and the Internet-Standard Management Framework were originally
devised to manage IP devices via in-band means, in which 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 for
managing 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. URIs 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 URI 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 URI. This scheme
also allows a URI to refer to specific object instances within an
SNMP MIB.
For a detailed overview of the documents that describe the current
Internet-Standard Management Framework, please refer to Section 7 of
[RFC3410].
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 [RFC2119].
2. Usage
There are two major classes of SNMP URI usage: configuration and
gateways between SNMP and other protocols that use SNMP URIs.
An SNMP URI used for configuration indicates the location of
management information as part of the configuration of an application
containing an SNMP manager. The URI can be obtained from a
configuration file or may be provided by a managed device (see
Section 1 for an example). Management information is exchanged
between the SNMP manager and agent, but it does not flow beyond the
manager, as shown in the following diagram:
*********** SNMP-Request *********
* *================>* *
URI ---------->* Manager * * Agent *
* *<================* *
*********** SNMP-Response *********
^
|
Other Config Info ------------+
Additional configuration information (e.g., a security secret or key)
may be provided via an interface other than that used for the URI.
For example, when a managed device provides an SNMP URI in an
unprotected fashion, that device should not provide a secret or key
required to use the URI. The secret or key should instead be pre-
configured in or pre-authorized to the manager; see Section 6.
For gateway usage, clients employ SNMP URIs to request management
information via an SNMP URI to SNMP gateway (also called an SNMP
gateway in this document). The SNMP manager within the SNMP gateway
accesses the management information and returns it to the requesting
client, as shown in the following diagram:
SNMP gateway
********** URI *********** SNMP-Request *********
* *===========>* *================>* *
* Client * * Manager * * Agent *
* *<===========* *<================* *
********** Info *********** SNMP-Response *********
^
|
Other Config Info ------------+
Additional configuration information (e.g., security secrets or keys)
may be provided via an interface other than that used for the URI.
For example, some types of security information, including secrets
and keys, should be pre-configured in or pre-authorized to the
manager rather than be provided by the client; see Section 6.
3. Syntax of an SNMP URI
An SNMP URI has the following ABNF [RFC2234] syntax, based on the
ABNF syntax rules for userinfo, host, port, and (path) segment in
[RFC3986] and the ABNF syntax rule for HEXDIG in [RFC2234]:
snmp-uri = "snmp://" snmp-authority [ context [ oids ]]
snmp-authority = [ securityName "@" ] host [ ":" port ]
securityName = userinfo ; SNMP securityName
context = "/" contextName [ ";" contextEngineID ]
contextName = segment ; SNMP contextName
contextEngineID = 1*(HEXDIG HEXDIG) ; SNMP contextEngineID
oids = "/" ( oid / oid-group ) [ suffix ]
oid-group = "(" oid *( "," oid ) ")"
oid = < as specified by [RFC 3061] >
suffix = "+" / ".*"
The userinfo and (path) segment ABNF rules are reused for syntax
only. In contrast, host and port have both the syntax and semantics
specified in [RFC3986]. See [RFC3411] for the semantics of
securityName, contextEngineID, and contextName.
The snmp-authority syntax matches the URI authority syntax in Section
3.2 of [RFC3986], with the additional restriction that the userinfo
component of an authority (when present) MUST be an SNMP
securityName. If the securityName is empty or not given, the entity
making use of an SNMP URI is expected to know what SNMP securityName
to use if one is required. Inclusion of authentication information
(e.g., passwords) in URIs has been deprecated (see Section 3.2.1 of
[RFC3986]), so any secret or key required for SNMP access must be
provided via other means that may be out-of-band with respect to
communication of the URI. If the port is empty or not given, port
161 is assumed.
If the contextName is empty or not given, the zero-length 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. An SNMP URI encodes a contextEngineID
as hexadecimal digits corresponding to a sequence of bytes. If the
contextEngineID is empty or not given, the context engine is to be
discovered by querying the SNMP agent at the specified host and port;
see Section 4.1 below. The contextEngineID component of the URI
SHOULD be present if more than one context engine at the designated
host and port supports the designated context.
An SNMP URI that designates the default SNMP context ("") MAY end
with the "/" character that introduces the contextName component. An
SNMP URI MUST NOT end with the "/" character that introduces an oid
or oid-group component, as the empty string is not a valid OID for
SNMP.
The encoding rules specified in [RFC3986] MUST be used for SNMP URIs,
including the use of percent encoding ("%" followed by two hex
digits) as needed to represent characters defined as reserved in
[RFC3986] and any characters not allowed in a URI. SNMP permits any
UTF-8 character to be used in a securityName or contextName; all
multi-byte UTF-8 characters in an SNMP URI MUST be percent encoded as
specified in Sections 2.1 and 2.5 of [RFC3986]. These requirements
are a consequence of reusing the ABNF syntax rules for userinfo and
segment from [RFC3986].
SNMP URIs will generally be short enough to avoid implementation
string-length limits (e.g., that may occur at 255 characters). Such
limits may be a concern for large OID groups; relative references to
URIs (see Section 4.2 of [RFC3986]) may provide an alternative in
some circumstances.
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 [RFC1900]
for further explanation).
3.1. Relative Reference Considerations
Use of the SNMP default context (zero-length string) within an SNMP
URI can result in a second instance of "//" in the URI, such as the
following:
snmp://<host>//<oid>
This is allowed by [RFC3986] syntax; if a URI parser does not handle
the second "//" correctly, the parser is broken and needs to be
fixed. This example is important because use of the SNMP default
context in SNMP URIs is expected to be common.
On the other hand, the second occurrence of "//" in an absolute SNMP
URI affects usage of relative references to that URI (see Section 4.2
of [RFC3986]) because a "//" at the start of a relative reference
always introduces a URI authority component (host plus optional
userinfo and/or port; see [RFC3986]). Specifically, a relative
reference of the form //<oid2> will not work, because the "//" will
cause <oid2> to be parsed as a URI authority, resulting in a syntax
error when the parser fails to find a host in <oid2> . To avoid this
problem, relative references that start with "//" but do not contain
a URI authority component MUST NOT be used. Functionality equivalent
to any such forbidden relative reference can be obtained by prefixing
"." or ".." to the forbidden relative reference (e.g., ..//<oid2>).
The prefix to use depends on the base URI.
4. Semantics and Operations
An SNMP URI that does not include any OIDs is called an SNMP service
URI because it designates a communication endpoint for access to SNMP
management service. An SNMP URI that includes one or more OIDs is
called an SNMP object URI because it designates one or more object
instances in an SNMP MIB. The expected means of using an SNMP URI is
to employ 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.
4.1. SNMP Service URIs
An SNMP service URI does not designate a data object, but rather an
SNMP context to be accessed by a service; the telnet URI scheme
[RFC1738] is another example of URIs that designate service access.
If the contextName in the URI is empty or not given, "" (the zero-
length string) is assumed, as it is the default SNMP context.
If a contextEngineID is given in an SNMP service URI, the context
engine that it designates is to be used. If the contextEngineID is
empty or not given in the URI, the context engine is to be
discovered; the context engine to be used is the one that supports
the context designated by the URI. The contextEngineID component of
the URI SHOULD be present if more than one context engine at the
designated host and port supports the designated context.
Many common uses of SNMP URIs are expected to omit (i.e., default)
the contextEngineID because they do not involve SNMP proxy agents,
which are the most common reason for multiple SNMP context engines to
exist at a single host and port. Specifically, when an SNMP agent is
local to the network interface that it manages, the agent will
usually have only one context engine, in which case it is safe to
omit the contextEngineID component of an SNMP URI. In addition, many
SNMP agents that are local to a network interface support only the
default SNMP context (zero-length string).
4.2. SNMP Object URIs
An SNMP object URI contains one or more OIDs. The URI is used by
first separating the OID or OID group (including its preceding slash
plus any parentheses and suffix) and then processing the resulting
SNMP service URI as specified in Section 4.1 (above) to determine the
SNMP context to be accessed. The OID or OID group is then used to
generate SNMP operations directed to that SNMP context.
The semantics of an SNMP object URI depend on whether the OID or OID
group has a suffix and what that suffix is. There are three possible
formats; in each case, the MIB object instances are designated within
the SNMP context specified by the service URI portion of the SNMP
object URI. The semantics of an SNMP object URI that contains a
single OID are as follows:
(1) An OID without a suffix designates the MIB object instance
named by the OID.
(2) An OID with a "+" suffix designates the lexically next MIB
object instance following the OID.
(3) An OID with a ".*" suffix designates the set of MIB object
instances for which the OID is a strict lexical prefix; this
does not include the MIB object instance named by the OID.
An OID group in an SNMP URI consists of a set of OIDs in parentheses.
In each case, the OID group semantics are the extension of the single
OID semantics to each OID in the group (e.g., a URI with a "+" suffix
designates the set of MIB object instances consisting of the
lexically next instance for each OID in the OID group).
When there is a choice among URI formats to designate the same MIB
object instance or instances, 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. Multiple
syntactically distinct SNMP URIs SHOULD NOT be used to designate the
same MIB object instance or set of instances, as this may cause
unexpected results in URI-based systems that use string comparison to
test URIs for equality.
SNMP object URIs designate the data to be accessed, as opposed to the
specific SNMP operations to be used for access; Section 4.2.1
provides examples of how SNMP operations can be used to access data
for SNMP object URIs. Nonetheless, any applicable SNMP operation,
including GetBulk, MAY be used to access data for all or part of one
or more SNMP object URIs (e.g., via use of multiple variable bindings
in a single operation); it is not necessary to use the specific
operations described in Section 4.2.1 as long as the results
(returned variable bindings or error) could have been obtained by
following Section 4.2.1’s descriptions. The use of relative
references that do not change the contextName (i.e., ./<oid>) should
be viewed as a hint that optimization of SNMP access across multiple
SNMP URIs may be possible.
An SNMP object URI MAY also be used to specify a MIB object instance
or instances to be written; this causes generation of an SNMP Set
operation instead of a Get. The "+" and ".*" suffixes MUST NOT be
used in this case; any attempt to do so is an error that MUST NOT
generate any SNMP Set operations. Values to be written to the MIB
object instance or instances are not specified within an SNMP object
URI.
SNMP object URIs designate data in SNMP MIBs and hence do not provide
the means to generate all possible SNMP protocol operations. For
example, data access for an SNMP object URI cannot directly generate
either Snmpv2-Trap or InformRequest notifications, although side
effects of data access could cause such notifications (depending on
the MIB). In addition, whether and how GetBulk is used for an SNMP
object URI with a ".*" suffix is implementation specific.
4.2.1. SNMP Object URI Data Access
Data access based on an SNMP object URI returns an SNMP variable
binding for each MIB object instance designated by the URI, or an
SNMP error if the operation fails. An SNMP variable binding binds a
variable name (OID) to a value or an SNMP exception (see [RFC3416]).
The SNMP operation or operations needed to access data designated by
an SNMP object URI depend on the OID or OID group suffix or absence
thereof. The following descriptions are not the only method of
performing data access for an SNMP object URI; any suitable SNMP
operations may be used as long as the results (returned variable
bindings or error) are functionally equivalent.
(1) For an OID or OID group without a suffix, an SNMP Get
operation is generated using each OID as a variable binding
name. If an SNMP error occurs, that error is the result of
URI data access; otherwise, the returned variable binding or
bindings are the result of URI data access. Note that any
returned variable binding may contain an SNMP "noSuchObject"
or "noSuchInstance" exception.
(2) For an OID or OID group with a "+" suffix, an SNMP GetNext
operation is generated using each OID as a variable binding
name. If an SNMP error occurs, that error is the result of
URI data access; otherwise, the returned variable binding or
bindings are the result of URI data access. Note that any
returned variable binding may contain an SNMP "endOfMibView"
exception.
(3) For an OID or OID group with a ".*" suffix, an SNMP GetNext
operation is initially generated using each OID as a variable
binding name. If the result is an SNMP error, that error is
the result of URI data access. If all returned variable
bindings contain either a) an OID for which the corresponding
URI OID is not a lexical prefix or b) an SNMP "endOfMibView"
exception, then the returned variable bindings are the result
of URI data access.
Otherwise, the results of the GetNext operation are saved, and
another SNMP GetNext operation is generated using the newly
returned OIDs as variable binding names. This is repeated
(save the results and generate a GetNext with newly returned
OIDs as variable binding names) until all the returned
variable bindings from a GetNext contain either a) an OID for
which the corresponding URI OID is not a lexical prefix or b)
an SNMP "endOfMibView" exception. The results from all of the
GetNext operations are combined to become the overall result
of URI data access; this may include variable bindings whose
OID is not a lexical extension of the corresponding URI OID.
If the OID subtrees (set of OIDs for which a specific URI OID
is a lexical prefix) are not the same size for all OIDs in the
OID group, the largest subtree determines when this iteration
ends. SNMP GetBulk operations MAY be used to optimize this
iterated access.
Whenever a returned variable binding contains an OID for which
the corresponding URI OID is not a lexical prefix or an SNMP
"endOfMibView" exception, iteration of that element of the OID
group MAY cease, reducing the number of variable bindings used
in subsequent GetNext operations. In this case, the results
of URI data access for the SNMP URI will not consist entirely
of OID-group-sized sets of variable bindings. Even if this
does not occur, the last variable binding returned for each
member of the OID group will generally contain an SNMP
"endOfMibView" exception or an OID for which the corresponding
URI OID is not a lexical prefix.