idnits 2.17.00 (12 Aug 2021) /tmp/idnits28864/draft-black-snmp-uri-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3667, Section 5.1 on line 19. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 796. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** The document seems to lack an RFC 3978 Section 5.5 (updated by RFC 4748) Disclaimer -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack an RFC 3979 Section 5, para. 1 IPR Disclosure Acknowledgement. ** The document seems to lack an RFC 3979 Section 5, para. 3 IPR Disclosure Invitation -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 27 instances of too long lines in the document, the longest one being 2 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 2004) is 6359 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC 3061' is defined on line 704, but no explicit reference was found in the text == Unused Reference: 'RFC 3414' is defined on line 711, but no explicit reference was found in the text == Unused Reference: 'RFC 1900' is defined on line 733, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Downref: Normative reference to an Informational RFC: RFC 3061 -- Obsolete informational reference (is this intentional?): RFC 1738 (Obsoleted by RFC 4248, RFC 4266) -- Obsolete informational reference (is this intentional?): RFC 2717 (Obsoleted by RFC 4395) -- Obsolete informational reference (is this intentional?): RFC 3291 (Obsoleted by RFC 4001) Summary: 10 errors (**), 0 flaws (~~), 6 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 URI Scheme for SNMP December 2004 3 Network Working Group D. Black 4 Internet Draft EMC Corporation 5 Document: draft-black-snmp-uri-09.txt K. McCloghrie 6 Expires: May 2005 Cisco Systems 7 J. Schoenwaelder 8 International University Bremen 9 December 2004 11 Uniform Resource Identifier (URI) Scheme for the 12 Simple Network Management Protocol (SNMP) 14 Status of this Memo 16 By submitting this Internet-Draft, I certify that any applicable 17 patent or other IPR claims of which I am aware have been 18 disclosed, or will be disclosed, and any of which I become aware 19 will be disclosed, in accordance with RFC 3668. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six 27 months and may be updated, replaced, or obsoleted by other 28 documents at any time. It is inappropriate to use Internet-Drafts 29 as reference material or to cite them other than as "work in 30 progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 Abstract 40 SNMP and the Internet Standard Management Framework are widely 41 used for management of communication devices, creating needs to 42 specify SNMP access (including access to SNMP MIB object 43 instances) from non-SNMP management environments. For example, 44 when out-of-band IP management is used via a separate management 45 interface (e.g., for a device that does not support in-band IP 46 access) there is a need for a uniform way to indicate how to 47 contact the device for management. URIs fit this need well, as 48 they allow a single text string to indicate a management access 49 communication endpoint for a wide variety of IP-based protocols. 51 This document defines a URI scheme so that SNMP can be designated 52 as the protocol used for management. The scheme also allows a URI 53 to designate one or more MIB object instances. 55 Conventions used in this document 57 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 58 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 59 in this document are to be interpreted as described in [RFC 2119]. 61 Table of Contents 63 1. Introduction...................................................2 64 2. Usage..........................................................3 65 3. Syntax of an SNMP URI..........................................4 66 3.1 Relative Reference Considerations..........................5 67 4. Semantics and Operations.......................................6 68 4.1 SNMP Service URIs..........................................6 69 4.2 SNMP Object URIs...........................................7 70 4.2.1 SNMP Object URI Data Access..........................8 71 4.3 OID Groups in SNMP URIs...................................10 72 4.4 Interoperability Considerations...........................10 73 5. Examples......................................................11 74 6. Security Considerations.......................................12 75 6.1 SNMP URI to SNMP Gateway Security Considerations..........13 76 7. IANA Considerations...........................................14 77 8. Change History (to be deleted prior to RFC publication).......14 78 9. Normative References..........................................15 79 10. Informative References.......................................15 80 11. Acknowledgments..............................................16 81 12. Copyright Notice and Disclaimers.............................16 82 13. Author's Addresses...........................................17 84 1. Introduction 86 SNMP and the Internet-Standard Management Framework were 87 originally devised to manage IP devices via in-band means where 88 management access is primarily via the same interface(s) used to 89 send and receive IP traffic. SNMP's wide adoption has resulted in 90 its use to manage communication devices that do not support in- 91 band IP access (e.g., Fibre Channel devices); a separate out-of- 92 band IP interface is often used for management. URIs provide a 93 convenient way to locate that interface and specify the protocol 94 to be used for management; one possible scenario is for an in-band 95 query to return a URI that indicates how the device is managed. 96 This document specifies a URI scheme to permit SNMP (including a 97 specific SNMP context) to be designated as the management protocol 98 by such a URI. This scheme also allows a URI to refer to specific 99 object instances within an SNMP MIB. 101 For a detailed overview of the documents that describe the current 102 Internet-Standard Management Framework, please refer to section 7 103 of [RFC 3410]. 105 2. Usage 107 There are two major classes of SNMP URI usage, configuration and 108 gateways between SNMP and other protocols that use SNMP URIs. 110 An SNMP URI used for configuration indicates the location of 111 management information as part of configuration of an application 112 containing an SNMP manager. The URI can be obtained from a 113 configuration file or may be provided by a managed device (see 114 Section 1 for an example). Management information is exchanged 115 between the SNMP manager and agent, but does not flow beyond the 116 manager, as shown in the following diagram: 118 *********** SNMP-Request ********* 119 * *================>* * 120 URI ---------->* Manager * * Agent * 121 * *<================* * 122 *********** SNMP-Response ********* 123 ^ 124 | 125 Other Config Info ------------+ 127 Additional configuration information (e.g., a security secret or 128 key) may be provided via an interface other than that used for the 129 URI. For example, when a managed device provides an SNMP URI in 130 an unprotected fashion, that device should not provide a secret or 131 key required to use the URI. The secret or key should instead be 132 pre-configured in or pre-authorized to the manager; see Section 6. 134 For gateway usage, clients employ SNMP URIs to request management 135 information via an SNMP URI to SNMP gateway (also called an SNMP 136 gateway in this document). The SNMP manager within the SNMP 137 gateway accesses the management information and returns it to the 138 requesting client, as shown in the following diagram: 140 SNMP gateway 141 ********** URI *********** SNMP-Request ********* 142 * *===========>* *================>* * 143 * Client * * Manager * * Agent * 144 * *<===========* *<================* * 145 ********** Info *********** SNMP-Response ********* 146 ^ 147 | 148 Other Config Info ------------+ 150 Additional configuration information (e.g., security secret(s) or 151 key(s)) may be provided via an interface other than that used for 152 the URI. For example, some types of security information, 153 including secrets and keys, should be pre-configured in or pre- 154 authorized to the manager rather than being provided by the 155 client; see Section 6. 157 3. Syntax of an SNMP URI 159 An SNMP URI has the following ABNF [RFC 2234] syntax, based on the 160 ABNF syntax rules for userinfo, host, port, and (path) segment in 161 [rfc2396bis] and the ABNF syntax rule for HEXDIG in [RFC 2234]: 163 snmp-uri = "snmp://" snmp-authority [ context [ oids ]] 165 snmp-authority = [ securityName "@" ] host [ ":" port ] 166 securityName = userinfo ; SNMP securityName 168 context = "/" contextName [ ";" contextEngineID ] 169 contextName = segment ; SNMP contextName 170 contextEngineID = 1*(HEXDIG HEXDIG) ; SNMP contextEngineID 172 oids = "/" ( oid / oid-group ) [ suffix ] 173 oid-group = "(" oid *( "," oid ) ")" 174 oid = < as specified by [RFC 3061] > 175 suffix = "+" / ".*" 177 The userinfo and (path) segment ABNF rules are reused for syntax 178 only. In contrast, host and port have both the syntax and 179 semantics specified in [rfc2396bis]. See [RFC 3411] for the 180 semantics of securityName, contextEngineID, and contextName. 182 The snmp-authority syntax matches the URI authority syntax in 183 section 3.2 of [rfc2396bis] with the additional restriction that 184 (when present) the userinfo component of an authority MUST be an 185 SNMP securityName. If the securityName is empty or not given, the 186 entity making use of an SNMP URI is expected to know what SNMP 187 securityName to use if one is required. Inclusion of 188 authentication information (e.g., passwords) in URIs has been 189 deprecated (see Section 3.2.1 of [rfc2396bis]), so any secret or 190 key required for SNMP access must be provided via other means that 191 may be out-of-band with respect to communication of the URI. If 192 the port is empty or not given, port 161 is assumed. 194 If the contextName is empty or not given, the zero-length string 195 ("") is assumed, as it is the default SNMP context. An SNMP 196 contextEngineID is a variable-format binary element that is 197 usually discovered by an SNMP manager. An SNMP URI encodes a 198 contextEngineID as hexadecimal digits corresponding to a sequence 199 of bytes. If the contextEngineID is empty or not given, the 200 context engine is to be discovered by querying the SNMP agent at 201 the specified host and port; see Section 4.1 below. The 202 contextEngineID component of the URI SHOULD be present if more 203 than one context engine at the designated host and port supports 204 the designated context. 206 An SNMP URI that designates the default SNMP context ("") MAY end 207 with the "/" character that introduces the contextName component. 208 An SNMP URI MUST NOT end with the "/" character that introduces an 209 oid or oid-group component, as the empty string is not a valid OID 210 for SNMP. 212 The encoding rules specified in [rfc2396bis] MUST be used for SNMP 213 URIs, including the use of percent encoding ("%" followed by two 214 hex digits) as needed to represent characters defined as reserved 215 in [rfc2396bis] and any characters not allowed in a URI. SNMP 216 permits any UTF-8 character to be used in a securityName or 217 contextName; all multi-byte UTF-8 characters in an SNMP URI MUST 218 be percent encoded as specified in Sections 2.1 and 2.5 of 219 [rfc2396bis]. These requirements are a consequence of reusing the 220 ABNF syntax rules for userinfo and segment from [rfc2396bis]. 222 SNMP URIs will generally be short enough to avoid implementation 223 string length limits (e.g., that may occur at 255 characters). 224 Such limits may be a concern for large OID groups; relative 225 references to URIs (see Section 4.2 of [rfc2396bis]) may provide 226 an alternative in some circumstances. 228 Use of IP addresses in SNMP URIs is acceptable in situations where 229 dependence on availability of DNS service is undesirable or must 230 be avoided; otherwise IP addresses should not be used (see [RFC 231 1900] for further explanation). 233 3.1 Relative Reference Considerations 235 Use of the SNMP default context (zero-length string) within an 236 SNMP URI can result in a second instance of "//" in the URI, e.g.: 238 snmp://// 240 This is allowed by [rfc2396bis] syntax; if a URI parser does not 241 handle the second "//" correctly, the parser is broken and needs 242 to be fixed. This example is important because use of the SNMP 243 default context in SNMP URIs is expected to be common. 245 On the other hand, the second occurrence of "//" in an absolute 246 SNMP URI affects usage of relative references to that URI (see 247 Section 4.2 of [rfc2396bis]) because a "//" at the start of a 248 relative reference always introduces a URI authority component 249 (host plus optional userinfo and/or port, see [rfc2396bis]). 250 Specifically, a relative reference of the form // will not 251 work because the "//" will cause to be parsed as a URI 252 authority, resulting in a syntax error when the parser fails to 253 find a host in . To avoid this problem, relative 254 references that start with "//" but do not contain a URI authority 255 component MUST NOT be used. Functionality equivalent to any such 256 forbidden relative reference can be obtained by prefixing "." or 257 ".." to the forbidden relative reference (e.g., ..//). The 258 prefix to use depends on the base URI. 260 4. Semantics and Operations 262 An SNMP URI that does not include any OIDs is called an SNMP 263 service URI because it designates a communication endpoint for 264 access to SNMP management service. An SNMP URI that includes one 265 or more OIDs is called an SNMP object URI because it designates 266 one or more object instances in an SNMP MIB. The expected means 267 of using an SNMP URI is to employ an SNMP manager to access the 268 SNMP context designated by the URI via the SNMP agent at the host 269 and port designated by the URI. 271 4.1 SNMP Service URIs 273 An SNMP service URI does not designate a data object, but rather 274 an SNMP context to be accessed by a service; the telnet URI scheme 275 [RFC 1738] is another example of URIs that designate service 276 access. If the contextName in the URI is empty or not given, 277 "" (the zero-length string) is assumed as it is the default SNMP 278 context. 280 If a contextEngineID is given in an SNMP service URI, the context 281 engine that it designates is to be used. If the contextEngineID 282 is empty or not given in the URI, the context engine is to be 283 discovered; the context engine to be used is the one that supports 284 the context designated by the URI. The contextEngineID component 285 of the URI SHOULD be present if more than one context engine at 286 the designated host and port supports the designated context. 288 Many common uses of SNMP URIs are expected to omit (i.e., default) 289 the contextEngineID because they do not involve accessing SNMP 290 proxy agents, the most common reason for multiple SNMP context 291 engines to exist at a single host and port. Specifically, when an 292 SNMP agent is local to the network interface that it manages, the 293 agent will usually have only one context engine, in which case it 294 is safe to omit the contextEngineID component of an SNMP URI. In 295 addition, many SNMP agents that are local to a network interface 296 support only the default SNMP context (zero-length string). 298 4.2 SNMP Object URIs 300 An SNMP object URI contains one or more OIDs. The URI is used by 301 first separating the OID or OID group (including its preceding 302 slash plus any parentheses and/or suffix), and then processing the 303 resulting SNMP service URI as specified in Section 4.1 (above) to 304 determine the SNMP context to be accessed. The OID or OID group 305 is then used to generate SNMP operations directed to that SNMP 306 context. 308 The semantics of an SNMP object URI depend on whether the OID or 309 OID group has a suffix and what that suffix is. There are three 310 possible formats; in each case, the MIB object instances are 311 designated within the SNMP context specified by the service URI 312 portion of the SNMP object URI. The semantics of an SNMP object 313 URI that contains a single OID are: 315 (1) An OID without a suffix designates the MIB object 316 instance named by the OID. 317 (2) An OID with a "+" suffix designates the lexically next 318 MIB object instance following the OID. 319 (3) An OID with a ".*" suffix designates the set of MIB 320 object instances for which the OID is a strict lexical prefix; 321 this does not include the MIB object instance named by the OID. 323 An OID group in an SNMP URI consists of a set of OIDs in 324 parentheses. In each case, the OID group semantics are the 325 extension of the single OID semantics to each OID in the group 326 (e.g., a URI with a "+" suffix designates the set of MIB object 327 instances consisting of the lexically next instance for each OID 328 in the OID group). 330 When there is a choice among URI formats to designate the same MIB 331 object instance or instances, the above list is in order of 332 preference (no suffix is most preferable) as it runs from most 333 precise to least precise. This is because an OID without a suffix 334 precisely designates an object instance, whereas a "+" suffix 335 designates the next object instance, which may change, and the 336 ".*" suffix could designate multiple object instances. Multiple 337 syntactically distinct SNMP URIs SHOULD NOT be used to designate 338 the same MIB object instance or set of instances as this may cause 339 unexpected results in URI-based systems that use string comparison 340 to test URIs for equality. 342 SNMP object URIs designate the data to be accessed, as opposed to 343 the specific SNMP operations to be used for access; Section 4.2.1 344 provides examples of how SNMP operations can be used to access 345 data for SNMP object URIs. Nonetheless, any applicable SNMP 346 operation, including GetBulk, MAY be used to access data for all 347 or part of one or more SNMP object URIs (e.g., via use of multiple 348 variable bindings in a single operation); it is not necessary to 349 use the specific operations described in Section 4.2.1 as long as 350 the results (returned variable bindings or error) could have been 351 obtained by following Section 4.2.1's descriptions. The use of 352 relative references that do not change the contextName (i.e., 353 ./) should be viewed as a hint that optimization of SNMP 354 access across multiple SNMP URIs may be possible. 356 An SNMP object URI MAY also be used to specify a MIB object 357 instance or instances to be written; this causes generation of an 358 SNMP Set operation instead of a Get. The "+" and ".*" suffixes 359 MUST NOT be used in this case; any attempt to do so is an error 360 that MUST NOT generate any SNMP Set operations. Values to be 361 written to the MIB object instance or instances are not specified 362 within an SNMP object URI. 364 SNMP object URIs designate data in SNMP MIBs, and hence do not 365 provide the means to generate all possible SNMP protocol 366 operations. For example, data access for an SNMP object URI 367 cannot directly generate either Snmpv2-Trap or InformRequest 368 notifications, although side effects of data access could cause 369 such notifications (depending on the MIB). In addition, whether 370 and how GetBulk is used for a SNMP object URI with a ".*" suffix 371 is implementation-specific. 373 4.2.1 SNMP Object URI Data Access 375 Data access based on an SNMP object URI returns an SNMP variable 376 binding for each MIB object instance designated by the URI or an 377 SNMP error if the operation fails. An SNMP variable binding binds 378 a variable name (OID) to a value or an SNMP exception (see [RFC 379 3416]). The SNMP operation or operations needed to access data 380 designated by an SNMP object URI depend on the OID or OID group 381 suffix or absence thereof. The following descriptions are not the 382 only method of performing data access for an SNMP object URI; any 383 suitable SNMP operations may be used as long as the results 384 (returned variable bindings or error) are functionally equivalent. 386 (1) For an OID or OID group without a suffix, an SNMP Get 387 operation is generated using each OID as a variable binding 388 name. If an SNMP error occurs, that error is the result 389 of URI data access, otherwise the returned variable binding or 390 bindings are the result of URI data access. Note that any 391 returned variable binding may contain an SNMP "noSuchObject" 392 or "noSuchInstance" exception. 394 (2) For an OID or OID group with a "+" suffix, an SNMP GetNext 395 operation is generated using each OID as a variable binding 396 name. If an SNMP error occurs, that error is the result 397 of URI data access, otherwise the returned variable binding 398 or bindings are the result of URI data access. Note that any 399 returned variable binding may contain an SNMP "endOfMibView" 400 exception. 402 (3) For an OID or OID group with a ".*" suffix, an SNMP GetNext 403 operation is initially generated using each OID as a variable 404 binding name. If the result is an SNMP error, that error is 405 the result of URI data access. If all returned variable 406 bindings contain either a) an OID for which the corresponding 407 URI OID is not a lexical prefix or b) an SNMP "endOfMibView" 408 exception, then the returned variable bindings are the 409 result of URI data access. 411 Otherwise the results of the GetNext operation are saved, and 412 another SNMP GetNext operation is generated using the newly 413 returned OIDs as variable binding names. This is repeated 414 (save the results and generate a GetNext with newly returned 415 OIDs as variable binding names) until all of the returned 416 variable bindings from a GetNext contain either a) an OID for 417 which the corresponding URI OID is not a lexical prefix or b) 418 an SNMP "endOfMibView" exception. The results from all of 419 the GetNext operations are combined to become the overall 420 result of URI data access; this may include variable bindings 421 whose OID is not a lexical extension of the corresponding URI 422 OID. If the OID subtrees (set of OIDs for which a specific URI 423 OID is a lexical prefix) are not the same size for all OIDs in 424 the OID group, the largest subtree determines when this 425 iteration ends. SNMP GetBulk operations MAY be used to 426 optimize this iterated access. 428 Whenever a returned variable binding contains an OID for which 429 the corresponding URI OID is not a lexical prefix or an SNMP 430 "endOfMibView" exception, iteration of that element of the 431 OID group MAY cease, reducing the number of variable bindings 432 used in subsequent GetNext operations. In this case the 433 results of URI data access for the SNMP URI will not consist 434 entirely of OID-group-sized sets of variable bindings. Even if 435 this does not occur, the last variable binding returned for 436 each member of the OID group will generally contain an SNMP 437 "endOfMibView" exception or an OID for which the corresponding 438 URI OID is not a lexical prefix. 440 4.3 OID Groups in SNMP URIs 442 Parenthesized OID groups in SNMP URIs are intended to support MIB 443 object instances for which access via a single SNMP operation is 444 required to ensure consistent results or otherwise desirable. 445 Therefore, the OIDs within an OID group in an SNMP URI SHOULD be 446 accessed by a single SNMP operation containing a variable binding 447 corresponding to each OID in the group. A specific example 448 involves the InetAddress and InetAddressType textual conventions 449 defined in [RFC 3291] where the format of an InetAddress instance 450 is specified by an associated InetAddressType instance. If two 451 such associated instances are read via separate SNMP operations, 452 the resulting values could be inconsistent (e.g., due to an 453 intervening Set) causing the InetAddress value to be incorrectly 454 interpreted. 456 This single operation requirement ("SHOULD") also applies to each 457 OID group resulting from iterated access for an SNMP URI with a 458 ".*" suffix. When members of an SNMP URI OID group differ in the 459 number of OIDs for which each is a lexical prefix, this iteration 460 may overrun by returning numerous variable bindings for which the 461 corresponding OID in the OID group is not a lexical prefix. Such 462 overrun can be avoided by using relative references within the 463 same context (i.e., ./.* ) when it is not important to access 464 multiple MIB object instances in a single SNMP operation. 466 4.4 Interoperability Considerations 468 This document defines a transport-independent "snmp" scheme that 469 is intended to accommodate SNMP transports other than UDP. UDP is 470 the default transport for access to information specified by an 471 SNMP URI for backwards compatibility with existing usage, but 472 other transports MAY be used. If more than one transport can be 473 used (e.g., SNMP over TCP [RFC 3430] in addition to SNMP over UDP) 474 the information or SNMP service access designated by an SNMP URI 475 SHOULD NOT depend on which transport is used (for SNMP over TCP, 476 this is implied by Section 2 of [RFC 3430]). 478 An SNMP URI designates use of SNMPv3 as specified by [RFC 3416], 479 [RFC 3417], and related documents, but older versions of SNMP MAY 480 be used in accordance with [RFC 3584] where usage of such older 481 versions is unavoidable. For SNMPv1 and SNMPv2c, the 482 securityName, contextName and contextEngineID elements of an SNMP 483 URI are mapped to/from the community name as described in [RFC 484 3584]. When the community name is kept secret as a weak form of 485 authentication, this mapping should be configured so that these 486 three elements do not reveal information about the community name. 487 If this is not done, then any SNMP URI component that would 488 disclose significant information about a secret community name 489 SHOULD be omitted. Note that some community names contain 490 reserved characters (e.g., "@") that require percent encoding when 491 used in an SNMP URI. SNMP versions (e.g., v3) have been omitted 492 from the SNMP URI scheme to permit use of older versions of SNMP, 493 as well as any possible future successor to SNMPv3. 495 5. Examples 497 snmp://example.com 499 This example designates the default SNMP context at the SNMP agent 500 at port 161 of host example.com . 502 snmp://tester5@example.com:8161 504 This example designates the default SNMP context at the SNMP agent 505 at port 8161 of host example.com and indicates that the SNMP 506 securityName "tester5" is to be used to access that agent. A 507 possible reason for use of a non-standard port is testing of a new 508 version of SNMP agent code. 510 snmp://example.com/bridge1 512 This example designates the "bridge1" SNMP context at example.com. 513 Because the contextEngineID component of the URI is omitted, there 514 SHOULD be at most one SNMP context engine at example.com that 515 supports the "bridge1" context. 517 snmp://example.com/bridge1;800002b804616263 519 This example designates the "bridge1" context at snmp.example.com 520 via the SNMP context engine 800002b804616263 (string 521 representation of a hexadecimal value). This avoids ambiguity if 522 any other context engine supports a "bridge1" context. The above 523 two examples are based on the figure in Section 3.3 of [RFC 3411]. 525 snmp://example.com//1.3.6.1.2.1.1.3.0 526 snmp://example.com//1.3.6.1.2.1.1.3+ 527 snmp://example.com//1.3.6.1.2.1.1.3.* 529 These three examples all designate the sysUpTime.0 object instance 530 in the SNMPv2-MIB or RFC1213-MIB for the default SNMP context ("") 531 at example.com as sysUpTime.0 is: 532 a) designated directly by OID 1.3.6.1.2.1.1.3.0, 533 b) the lexically next MIB object instance after the OID 534 1.3.6.1.2.1.1.3, and 535 c) the only MIB object instance whose OID has 1.3.6.1.2.1.1.3 536 as a lexical prefix. 538 These three examples are provided for illustrative purposes only, 539 as multiple syntactically distinct URIs SHOULD NOT be used to 540 designate the same MIB object instance in order to avoid 541 unexpected results in URI-based systems that use string comparison 542 to test URIs for equality. 544 snmp://example.com/bridge1/1.3.6.1.2.1.2.2.1.8.* 546 This example designates the ifOperStatus column of the IF-MIB in 547 the bridge1 SNMP context at example.com. 549 snmp://example.com//(1.3.6.1.2.1.2.2.1.7,1.3.6.1.2.1.2.2.1.8).* 551 This example designates all (ifAdminStatus, ifOperStatus) pairs in 552 the IF-MIB in the default SNMP context at example.com. 554 6. Security Considerations 556 An intended use of this URI scheme is designation of the location 557 of management access to communication devices. Such location 558 information may be considered sensitive in some environments, 559 making it important to control access to this information and 560 possibly even to encrypt when sending it over the network. All 561 uses of this URI scheme should provide security mechanisms 562 appropriate to the environments in which such uses are likely to 563 be deployed. 565 The SNMP architecture includes control of access to management 566 information (see Section 4.3 of [RFC 3411]). An SNMP URI does not 567 contain sufficient security information to obtain access in all 568 situations, as the SNMP URI syntax is incapable of encoding SNMP 569 securityModels, SNMP securityLevels, and credential or keying 570 information for SNMP securityNames. Other means are necessary to 571 provide such information; one possibility is out-of-band pre- 572 configuration of the SNMP manager, as shown in the diagrams in 573 Section 2. 575 By itself, the presence of a securityName in an SNMP URI MUST NOT 576 authorize use of that securityName to access management 577 information. Instead the SNMP manager SHOULD match the 578 securityName in the URI to an SNMP securityName and associated 579 security information that have been pre-authorized for use by the 580 manager. If an SNMP URI contains a securityName that the SNMP 581 manager is not authorized to use, SNMP operations for that URI 582 SHOULD NOT be generated. 584 SNMP versions prior to SNMPv3 did not include adequate security. 585 Even if the network itself is secure (for example via use of 586 IPsec), there is no control over who on the secure network is 587 allowed to access and GET/SET (read/change/create/delete) the 588 objects in MIB modules. It is RECOMMENDED that implementers 589 consider the security features as provided by the SNMPv3 framework 590 (see [RFC 3410], section 8 for an overview), including full 591 support for SNMPv3 cryptographic mechanisms (for authentication 592 and privacy). This is of additional importance for MIB elements 593 considered sensitive or vulnerable because GETs have side effects. 595 Further, deployment of SNMP versions prior to SNMPv3 is NOT 596 RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to 597 enable cryptographic security. It is then a customer/operator 598 responsibility to ensure that the SNMP entity giving access to a 599 MIB module instance is properly configured to give access to the 600 objects only to those principals (users) that have legitimate 601 rights to indeed GET or SET (read/change/create/delete) them. 603 6.1 SNMP URI to SNMP Gateway Security Considerations 605 Additional security considerations apply to SNMP gateways that 606 generate SNMP operations for SNMP URIs and return the results to 607 clients (see Section 2) because management information is 608 communicated beyond the SNMP framework. In general, an SNMP 609 gateway should have some knowledge of the structure and function 610 of the management information that it accesses via SNMP. Among 611 other benefits, this allows an SNMP gateway to avoid SNMP access 612 control failures because the gateway can reject an SNMP URI that 613 will cause such failures before generating any SNMP operations. 615 SNMP gateways SHOULD impose authorization or access control checks 616 on all clients. If an SNMP gateway does not impose authorization 617 or access controls, the gateway MUST NOT automatically obtain or 618 use SNMP authentication material for arbitrary securityNames, as 619 doing so would defeat SNMP's access controls. Instead, all SNMP 620 gateways SHOULD authenticate each client and check the client's 621 authorization to use a securityName in an SNMP URI before using 622 the securityName on behalf of that client. 624 An SNMP gateway is also responsible for ensuring that all of its 625 communication is appropriately secured. Specifically, an SNMP 626 gateway SHOULD ensure that communication of management information 627 with any client is protected to at least the SNMP securityLevel 628 used for the corresponding SNMP access (see Section 3.4.3 of [RFC 629 3411] for more information on securityLevel). If the client 630 provides SNMP security information, the SNMP gateway SHOULD 631 authenticate the client and SHOULD ensure that an authenticated 632 cryptographic integrity check is used for that communication to 633 prevent modification of the security information. In addition, if 634 a client provides any key or secret, the SNMP gateway SHOULD 635 ensure that encryption is used in addition to the integrity check 636 for that communication to prevent disclosure of keys or secrets. 638 There are management objects defined in SNMP MIBs whose MAX-ACCESS 639 is read-write and/or read-create. Such objects may be considered 640 sensitive or vulnerable in some network environments. SNMP 641 gateway support for SNMP SET operations in a non-secure 642 environment without proper protection can have a negative effect 643 on network operations. The individual MIB module specifications, 644 and especially their security considerations, should be consulted 645 for further information. 647 Some readable objects in some MIB modules (i.e., objects with a 648 MAX-ACCESS other than not-accessible) may be considered sensitive 649 or vulnerable in some network environments. It is thus important 650 to control even GET access to these objects via an SNMP gateway 651 and possibly to even encrypt the values of these objects when 652 sending them over the network. The individual MIB module 653 specifications, and especially their security considerations, 654 should be consulted for further information. This consideration 655 also applies to objects for which read operations have side 656 effects. 658 7. IANA Considerations 660 The IANA is asked to register the URL registration template found 661 in Appendix A in accordance with [RFC 2717]. 663 8. Change History (to be deleted prior to RFC publication) 665 -03: Update to reference rfc2396bis draft instead of RFC 2396. 666 Context and engine syntax changed to comply with rfc2396bis 667 authority component restrictions. Minor text editing. 668 -04: Remove "0x" engine prefix. Add discussion of relative 669 URI impacts of embedded //. Add OID groups to support 670 MIB object instances that need to be accessed together. 671 Always discard SNMP "no data" response exceptions. More edits. 672 -05: Spell out acronyms in title. Correct wording to refer to 673 SNMP exceptions. More editing. 674 -06: Change syntax component names to match SNMP terminology 675 (e.g., contextName, contextEngineID). Back out -04 change to 676 discard SNMP "no data" exceptions. Loosen requirements on 677 group iteration. Drop "engine=" to simplify syntax. 678 Rewrite ABNF for clarity and correctness. More editing. 679 -07: Yet more editing. Move data access details into a 680 separate subsection, and make it clear that functional 681 equivalence to their results is all that is required. Use 682 example.com consistently in all examples. 684 -08: Remove discussion of SNMP security models. Add warning 685 about avoiding disclosure of a community name when it's a 686 secret. Change "relative URI" to "relative reference" to match 687 final version of rfc2396bis. 688 -09: Expand security considerations section to cover SNMP URI 689 to SNMP gateways. Add usage section to help explain this. 691 9. Normative References 693 [rfc2396bis] Uniform Resource Identifiers (URI): Generic Syntax. 694 T. Berners-Lee, R. Fielding, L. Masinter. 695 Internet-Draft draft-fielding-uri-rfc2396bis-07.txt . 696 Work in Progress. September 2004. 698 [RFC 2119] Key words for use in RFCs to Indicate Requirement 699 Levels. S. Bradner. RFC 2119, BCP 14. March 1997. 701 [RFC 2234] Augmented BNF for Syntax Specifications: ABNF. 702 D. Crocker, Ed., P. Overell. RFC 2234. November 1997. 704 [RFC 3061] A URN Namespace of Object Identifiers. M. Mealling. 705 February 2001. 707 [RFC 3411] An Architecture for Describing Simple Network 708 Management Protocol (SNMP) Management Frameworks. 709 D. Harrington, R. Presuhn, B. Wijnen. December 2002. 711 [RFC 3414] User-based Security Model (USM) for version 3 of the 712 Simple Network Management Protocol (SNMPv3). 713 U. Blumenthal, B. Wijnen. RFC 3414. December 2002. 715 [RFC 3416] Version 2 of the Protocol Operations for the Simple 716 Network Management Protocol (SNMP). R. Presuhn, Ed. 717 RFC 3416. December 2002. 719 [RFC 3417] Transport Mappings for the Simple Network Management 720 Protocol (SNMP). R. Presuhn, Ed. RFC 3417. 721 December 2002. 723 [RFC 3584] Coexistence between Version 1, Version 2, and Version 3 724 of the Internet-standard Network Management Framework. 725 R. Frye, D. Levi, S. Routhier, B. Wijnen. RFC 3584. 726 August 2003. 728 10. Informative References 730 [RFC 1738] Uniform Resource Locators (URL). T. Berners-Lee, 731 L. Masinter, M. McCahill. RFC 1738. December 1994. 733 [RFC 1900] Renumbering Needs Work. B. Carpenter, Y. Rekhter. 734 RFC 1900. February 1996. 736 [RFC 2717] Registration Procedures for URL Scheme Names. R. Petke, 737 I. King. RFC 2717. November 1999. 739 [RFC 3291] Textual Conventions for Internet Network Addresses. 740 M. Daniele, B. Haberman, S. Routhier, 741 J. Schoenwaelder. RFC 3291. May 2002. 743 [RFC 3410] Introduction and Applicability Statements for Internet- 744 Standard Management Framework. J. Case, R. Mundy, 745 D. Partain, B. Stewart. RFC 3410. December 2002. 747 [RFC 3430] Simple Network Management Protocol Over Transmission 748 Control Protocol Transport Mapping. J. Schoenwaelder. 749 December 2002. 751 [RFC 3617] Uniform Resource Identifier (URI) Scheme and 752 Applicability Statement for the Trivial File Transfer 753 Protocol (TFTP). E. Lear. October 2003. 755 11. Acknowledgments 757 Portions of this document were adapted from Eliot Lear's TFTP URI 758 scheme specification [RFC 3617]. Portions of the security 759 considerations were adapted from the widely used security 760 considerations "boilerplate" for MIB modules. Comments from Ted 761 Hardie, Michael Mealing, Larry Masinter, Frank Strauss, Bert 762 Wijnen, Steve Bellovin, the mreview@ops.ietf.org mailing list and 763 the uri@w3c.org mailing list on earlier versions of this draft 764 have resulted in significant improvements and are gratefully 765 acknowledged. 767 12. Copyright Notice and Disclaimers 769 Copyright (C) The Internet Society (2004). This document is 770 subject to the rights, licenses and restrictions contained in BCP 771 78, and except as set forth therein, the authors retain all their 772 rights. 774 This document and the information contained herein are provided on 775 an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE 776 REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND 777 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, 778 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT 779 THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR 780 ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 781 PARTICULAR PURPOSE." 782 The IETF takes no position regarding the validity or scope of any 783 Intellectual Property Rights or other rights that might be claimed 784 to pertain to the implementation or use of the technology 785 described in this document or the extent to which any license 786 under such rights might or might not be available; nor does it 787 represent that it has made any independent effort to identify any 788 such rights. Information on the procedures with respect to rights 789 in RFC documents can be found in BCP 78 and BCP 79. 791 Copies of IPR disclosures made to the IETF Secretariat and any 792 assurances of licenses to be made available, or the result of an 793 attempt made to obtain a general license or permission for the use 794 of such proprietary rights by implementers or users of this 795 specification can be obtained from the IETF on-line IPR repository 796 at http://www.ietf.org/ipr. 798 The IETF invites any interested party to bring to its attention 799 any copyrights, patents or patent applications, or other 800 proprietary rights that may cover technology that may be required 801 to implement this standard. Please address the information to the 802 IETF at ietf-ipr@ietf.org." 804 13. Author's Addresses 806 David L. Black 807 EMC Corporation 808 176 South Street 809 Hopkinton, MA 01748 810 Phone: +1 (508) 293-7953 811 Email: black_david@emc.com 813 Keith McCloghrie 814 Cisco Systems, Inc. 815 170 West Tasman Drive 816 San Jose, CA USA 95134 817 Phone: +1 (408) 526-5260 818 Email: kzm@cisco.com 820 Juergen Schoenwaelder 821 International University Bremen 822 P.O. Box 750 561 823 28725 Bremen 824 Germany 825 Phone: +49 421 200 3587 826 Email: j.schoenwaelder@iu-bremen.de 828 Appendix A. Registration Template 830 URL scheme name: snmp 831 URL scheme syntax: Section 3 832 Character encoding considerations: Section 3 833 Intended usage: Sections 1 and 2 834 Applications and/or protocols which use this scheme: SNMP, all 835 versions, see [RFC 3410] and [RFC 3584]. Also SNMP over TCP, 836 see [RFC 3430]. 837 Interoperability considerations: Section 4.4 838 Security considerations: Section 6 839 Relevant publications: See [RFC 3410] for list. Also [RFC 3430] 840 and [RFC 3584]. 841 Contact: David L. Black, Section 13 842 Author/Change Controller: IESG