idnits 2.17.1 draft-ietf-netconf-prot-07.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 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 4309. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4286. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4293. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4299. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. 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 1 instance of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: A lock MUST not be granted if any of the following conditions are true: -- 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 (June 29, 2005) is 6869 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) -- Looks like a reference, but probably isn't: 'XMLDir' on line 4060 -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' ** Obsolete normative reference: RFC 2246 (ref. '4') (Obsoleted by RFC 4346) ** Downref: Normative reference to an Informational RFC: RFC 1630 (ref. '5') ** Obsolete normative reference: RFC 2141 (ref. '6') (Obsoleted by RFC 8141) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Enns, Ed. 3 Internet-Draft Juniper Networks 4 Expires: December 31, 2005 June 29, 2005 6 NETCONF Configuration Protocol 7 draft-ietf-netconf-prot-07 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on December 31, 2005. 34 Copyright Notice 36 Copyright (C) The Internet Society (2005). 38 Abstract 40 The NETCONF configuration protocol defined in this document provides 41 mechanisms to install, manipulate, and delete the configuration of 42 network devices. It uses an Extensible Markup Language (XML) based 43 data encoding for the configuration data as well as the protocol 44 messages. The NETCONF protocol operations are realized on top of a 45 simple Remote Procedure Call (RPC) layer. 47 Please send comments to netconf@ops.ietf.org. To subscribe, use 48 netconf-request@ops.ietf.org. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 53 1.1 Protocol Overview . . . . . . . . . . . . . . . . . . . . 6 54 1.2 Capabilities . . . . . . . . . . . . . . . . . . . . . . . 7 55 1.3 Separation of Configuration and State Data . . . . . . . . 7 56 2. Application Protocol Requirements . . . . . . . . . . . . . . 8 57 2.1 Connection-oriented operation . . . . . . . . . . . . . . 9 58 2.2 Authentication, Integrity, and Privacy . . . . . . . . . . 9 59 2.3 Authentication . . . . . . . . . . . . . . . . . . . . . . 9 60 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . . 10 61 3.1 Namespace . . . . . . . . . . . . . . . . . . . . . . . . 10 62 3.2 No Document Type Declarations . . . . . . . . . . . . . . 10 63 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 10 64 4.1 Element . . . . . . . . . . . . . . . . . . . . . . 10 65 4.2 Element . . . . . . . . . . . . . . . . . . . 11 66 4.3 Element . . . . . . . . . . . . . . . . . . . 12 67 4.4 Element . . . . . . . . . . . . . . . . . . . . . . . 15 68 4.5 Pipelining . . . . . . . . . . . . . . . . . . . . . . . . 16 69 5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 16 70 5.1 Configuration Datastores . . . . . . . . . . . . . . . . . 16 71 6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 16 72 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 16 73 6.2 Subtree Filter Components . . . . . . . . . . . . . . . . 17 74 6.2.1 Namespace Selection . . . . . . . . . . . . . . . . . 18 75 6.2.2 Attribute Match Expressions . . . . . . . . . . . . . 18 76 6.2.3 Containment Nodes . . . . . . . . . . . . . . . . . . 19 77 6.2.4 Selection Nodes . . . . . . . . . . . . . . . . . . . 19 78 6.2.5 Content Match Nodes . . . . . . . . . . . . . . . . . 20 79 6.3 Subtree Filter Processing . . . . . . . . . . . . . . . . 21 80 6.4 Subtree Filtering Examples . . . . . . . . . . . . . . . . 22 81 6.4.1 No filter . . . . . . . . . . . . . . . . . . . . . . 22 82 6.4.2 Empty filter . . . . . . . . . . . . . . . . . . . . . 22 83 6.4.3 Select the entire subtree . . . . . . . . . . 23 84 6.4.4 Select all elements within the 85 subtree . . . . . . . . . . . . . . . . . . . . . . . 25 86 6.4.5 One specific entry . . . . . . . . . . . . . . 26 87 6.4.6 Specific elements from a specific entry . . . . 27 88 6.4.7 Multiple Subtrees . . . . . . . . . . . . . . . . . . 28 89 6.4.8 Elements with attribute naming . . . . . . . . . . . . 30 90 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 31 91 7.1 . . . . . . . . . . . . . . . . . . . . . . . 32 92 7.2 . . . . . . . . . . . . . . . . . . . . . . 35 93 7.3 . . . . . . . . . . . . . . . . . . . . . . 41 94 7.4 . . . . . . . . . . . . . . . . . . . . . 43 95 7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . 43 96 7.6 . . . . . . . . . . . . . . . . . . . . . . . . . 46 97 7.7 . . . . . . . . . . . . . . . . . . . . . . . . . . 47 98 7.8 . . . . . . . . . . . . . . . . . . . . . 49 99 7.9 . . . . . . . . . . . . . . . . . . . . . . 50 100 8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . 51 101 8.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . 51 102 8.2 Writable-Running Capability . . . . . . . . . . . . . . . 52 103 8.2.1 Description . . . . . . . . . . . . . . . . . . . . . 52 104 8.2.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 53 105 8.2.3 Capability and Namespace . . . . . . . . . . . . . . . 53 106 8.2.4 New Operations . . . . . . . . . . . . . . . . . . . . 53 107 8.2.5 Modifications to Existing Operations . . . . . . . . . 53 108 8.3 Candidate Configuration Capability . . . . . . . . . . . . 53 109 8.3.1 Description . . . . . . . . . . . . . . . . . . . . . 53 110 8.3.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 54 111 8.3.3 Capability and Namespace . . . . . . . . . . . . . . . 54 112 8.3.4 New Operations . . . . . . . . . . . . . . . . . . . . 54 113 8.3.5 Modifications to Existing Operations . . . . . . . . . 56 114 8.4 Confirmed Commit Capability . . . . . . . . . . . . . . . 56 115 8.4.1 Description . . . . . . . . . . . . . . . . . . . . . 56 116 8.4.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 57 117 8.4.3 Capability and Namespace . . . . . . . . . . . . . . . 57 118 8.4.4 New Operations . . . . . . . . . . . . . . . . . . . . 57 119 8.4.5 Modifications to Existing Operations . . . . . . . . . 57 120 8.5 Rollback on Error Capability . . . . . . . . . . . . . . . 58 121 8.5.1 Description . . . . . . . . . . . . . . . . . . . . . 58 122 8.5.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 58 123 8.5.3 Capability and Namespace . . . . . . . . . . . . . . . 59 124 8.5.4 New Operations . . . . . . . . . . . . . . . . . . . . 59 125 8.5.5 Modifications to Existing Operations . . . . . . . . . 59 126 8.6 Validate Capability . . . . . . . . . . . . . . . . . . . 59 127 8.6.1 Description . . . . . . . . . . . . . . . . . . . . . 60 128 8.6.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 60 129 8.6.3 Capability and Namespace . . . . . . . . . . . . . . . 60 130 8.6.4 New Operations . . . . . . . . . . . . . . . . . . . . 60 131 8.7 Distinct Startup Capability . . . . . . . . . . . . . . . 61 132 8.7.1 Description . . . . . . . . . . . . . . . . . . . . . 61 133 8.7.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 61 134 8.7.3 Capability and Namespace . . . . . . . . . . . . . . . 62 135 8.7.4 New Operations . . . . . . . . . . . . . . . . . . . . 62 136 8.7.5 Modifications to Existing Operations . . . . . . . . . 62 137 8.8 URL Capability . . . . . . . . . . . . . . . . . . . . . . 62 138 8.8.1 Description . . . . . . . . . . . . . . . . . . . . . 62 139 8.8.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 62 140 8.8.3 Capability and Namespace . . . . . . . . . . . . . . . 62 141 8.8.4 New Operations . . . . . . . . . . . . . . . . . . . . 63 142 8.8.5 Modifications to Existing Operations . . . . . . . . . 63 143 8.9 XPath Capability . . . . . . . . . . . . . . . . . . . . . 63 144 8.9.1 Description . . . . . . . . . . . . . . . . . . . . . 63 145 8.9.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 64 146 8.9.3 Capability and Namespace . . . . . . . . . . . . . . . 64 147 8.9.4 New Operations . . . . . . . . . . . . . . . . . . . . 64 148 8.9.5 Modifications to Existing Operations . . . . . . . . . 64 149 9. Security Considerations . . . . . . . . . . . . . . . . . . . 64 150 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 66 151 11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 66 152 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 67 153 12.1 Normative References . . . . . . . . . . . . . . . . . . . 67 154 12.2 Informative References . . . . . . . . . . . . . . . . . . 67 155 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 68 156 A. NETCONF Error List . . . . . . . . . . . . . . . . . . . . . . 68 157 B. XML Schema for NETCONF RPC and Protocol Operations . . . . . . 71 158 C. Capability Template . . . . . . . . . . . . . . . . . . . . . 82 159 C.1 capability-name (template) . . . . . . . . . . . . . . . . 83 160 C.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . 83 161 C.1.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 83 162 C.1.3 Capability and Namespace . . . . . . . . . . . . . . . 83 163 C.1.4 New Operations . . . . . . . . . . . . . . . . . . . . 83 164 C.1.5 Modifications to Existing Operations . . . . . . . . . 83 165 C.1.6 Interactions with Other Capabilities . . . . . . . . . 83 166 D. Configuring Multiple Devices with NETCONF . . . . . . . . . . 83 167 D.1 Operations on Individual Devices . . . . . . . . . . . . . 83 168 D.1.1 Acquiring the Configuration Lock . . . . . . . . . . . 84 169 D.1.2 Loading the Update . . . . . . . . . . . . . . . . . . 84 170 D.1.3 Validating the Incoming Configuration . . . . . . . . 85 171 D.1.4 Checkpointing the Running Configuration . . . . . . . 86 172 D.1.5 Changing the Running Configuration . . . . . . . . . . 87 173 D.1.6 Testing the New Configuration . . . . . . . . . . . . 87 174 D.1.7 Making the Change Permanent . . . . . . . . . . . . . 88 175 D.1.8 Releasing the Configuration Lock . . . . . . . . . . . 88 176 D.2 Operations on Multiple Devices . . . . . . . . . . . . . . 89 177 E. Deferred Features . . . . . . . . . . . . . . . . . . . . . . 90 178 F. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 90 179 F.1 draft-ietf-netconf-prot-07 . . . . . . . . . . . . . . . . 90 180 F.2 draft-ietf-netconf-prot-06 . . . . . . . . . . . . . . . . 91 181 F.3 draft-ietf-netconf-prot-05 . . . . . . . . . . . . . . . . 91 182 F.4 draft-ietf-netconf-prot-04 . . . . . . . . . . . . . . . . 92 183 F.5 draft-ietf-netconf-prot-03 . . . . . . . . . . . . . . . . 93 184 F.6 draft-ietf-netconf-prot-02 . . . . . . . . . . . . . . . . 95 185 Intellectual Property and Copyright Statements . . . . . . . . 96 187 1. Introduction 189 The NETCONF protocol defines a simple mechanism through which a 190 network device can be managed, configuration data information can be 191 retrieved, and new configuration data can be uploaded and 192 manipulated. The protocol allows the device to expose a full, 193 formal, application programming interface (API). Applications can 194 use this straight-forward API to send and receive full and partial 195 configuration data sets. 197 The NETCONF protocol uses a remote procedure call (RPC) paradigm. A 198 client encodes an RPC in XML [1] and sends it to a server using a 199 secure, connection-oriented session. The server responds with a 200 reply encoded in XML. The contents of both the request and the 201 response are fully described in XML DTDs or XML schemas, or both, 202 allowing both parties to recognize the syntax constraints imposed on 203 the exchange. 205 A key aspect of NETCONF is that it allows the functionality of the 206 management protocol to closely mirror the native functionality of the 207 device. This reduces implementation costs and allows timely access 208 to new features. In addition, applications can access both the 209 syntactic and semantic content of the device's native user interface. 211 NETCONF allows a client to discover the set of protocol extensions 212 supported by a server. These "capabilities" permit the client to 213 adjust its behavior to take advantage of the features exposed by the 214 device. The capability definitions can be easily extended in a 215 noncentralized manner. Standard and non-standard capabilities can be 216 defined with semantic and syntactic rigor. Capabilities are 217 discussed in Section 8. 219 The NETCONF protocol is a building block in a system of automated 220 configuration. XML is the lingua franca of interchange, providing a 221 flexible but fully specified encoding mechanism for hierarchical 222 content. NETCONF can be used in concert with XML-based 223 transformation technologies such as XSLT [9] to provide a system for 224 automated generation of full and partial configurations. The system 225 can query one or more databases for data about networking topologies, 226 links, policies, customers, and services. This data can be 227 transformed using one or more XSLT scripts from a task-oriented, 228 vendor-independent data schema into a form that is specific to the 229 vendor, product, operating system, and software release. The 230 resulting data can be passed to the device using the NETCONF 231 protocol. 233 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 234 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 235 document are to be interpreted as described in RFC 2119 [3]. 237 1.1 Protocol Overview 239 NETCONF uses a simple RPC-based mechanism to facilitate communication 240 between a client and a server. The client can be a script or 241 application typically running as part of a network manager. The 242 server is typically a network device. The terms "device" and 243 "server" are used interchangeably in this document, as are "client" 244 and "application". 246 A NETCONF session is the logical connection between a network 247 administrator or network configuration application and a network 248 device. A device MUST support at least one NETCONF session, and 249 SHOULD support multiple sessions. Global configuration attributes 250 can be changed during any authorized session, and the affects are 251 visible in all sessions. Session-specific attributes affect only the 252 session in which they are changed. 254 NETCONF can be conceptually partitioned into four layers: 256 Layer Example 257 +-------------+ +-----------------------------+ 258 (4) | Content | | Configuration data | 259 +-------------+ +-----------------------------+ 260 | | 261 +-------------+ +-----------------------------+ 262 (3) | Operations | | , | 263 +-------------+ +-----------------------------+ 264 | | 265 +-------------+ +-----------------------------+ 266 (2) | RPC | | , | 267 +-------------+ +-----------------------------+ 268 | | 269 +-------------+ +-----------------------------+ 270 (1) | Application | | BEEP, SSH, SSL, console | 271 | Protocol | | | 272 +-------------+ +-----------------------------+ 274 1. The application protocol layer provides a communication path 275 between the client and server. NETCONF can be layered over any 276 application protocol that provides a set of basic requirements. 277 Section 2 discusses these requirements. 279 2. The RPC layer provides a simple, transport-independent framing 280 mechanism for encoding RPCs. Section 4 documents this protocol. 282 3. The operations layer defines a set of base operations invoked as 283 RPC methods with XML-encoded parameters. Section 7 details the 284 list of base operations. 286 4. The content layer is outside the scope of this document. Given 287 the current proprietary nature of the configuration data being 288 manipulated, the specification of this content depends on the 289 NETCONF implementation. It is expected that a separate effort to 290 specify a standard data definition language and standard content 291 will be undertaken. 293 1.2 Capabilities 295 A NETCONF capability is a set of functionality that supplements the 296 base NETCONF specification. The capability is identified by a 297 uniform resource identifier (URI). These URIs should follow the 298 guidelines as described in Section 8. 300 Capabilities augment the base operations of the device, describing 301 both additional operations and the content allowed inside operations. 302 The client can discover the server's capabilities and use any 303 additional operations, parameters, and content defined by those 304 capabilities. 306 The capability definition may name one or more dependent 307 capabilities. To support a capability, the server MUST support any 308 capabilities upon which it depends. 310 Section 8 defines the capabilities exchange that allows the client to 311 discover the server's capabilities. Section 8 also lists the set of 312 capabilities defined in this document. 314 Additional capabilities can be defined at any time in external 315 documents, allowing the set of capabilities to expand over time. 316 Standards bodies may define standardized capabilities and 317 implementations may define proprietary ones. A capability URI MUST 318 sufficiently distinguish the naming authority to avoid naming 319 collisions. 321 1.3 Separation of Configuration and State Data 323 The information that can be retrieved from a running system is 324 separated into two classes, configuration data and state data. 325 Configuration data is the set of writable data that is required to 326 transform a system from its initial default state into its current 327 state. State data is the additional data on a system that is not 328 configuration data such as read-only status information and collected 329 statistics. When a device is performing configuration operations a 330 number of problems would arise if state data were included: 332 o Comparisons of configuration data sets would be dominated by 333 irrelevant entries such as different statistics. 335 o Incoming data could contain nonsensical requests, such as attempts 336 to write read-only data. 338 o The data sets would be large. 340 o Archived data could contain values for read-only data items, 341 complicating the processing required to restore archived data. 343 To account for these issues, the NETCONF protocol recognizes the 344 difference between configuration data and state data and provides 345 operations for each. The operation retrieves 346 configuration data only while the operation retrieves 347 configuration and state data. 349 Note that the NETCONF protocol is focused on the information required 350 to get the device into its desired running state. The inclusion of 351 other important, persistent data is implementation specific. For 352 example, user files and databases are not treated as configuration 353 data by the NETCONF protocol. 355 If a local database of user authentication data is stored on the 356 device, whether it is included in configuration data is an 357 implementation dependent matter. 359 2. Application Protocol Requirements 361 NETCONF uses an RPC-based communication paradigm. A client sends a 362 series of one or more RPC request operations, which cause the server 363 to respond with a corresponding series of RPC replies. 365 The NETCONF protocol can be layered on any application protocol that 366 provides the required set of functionality. It is not bound to any 367 particular application protocol, but allows a mapping to define how 368 it can be implemented over any specific protocol. 370 The application protocol MUST provide a mechanism to indicate the 371 session type (client or server) to the NETCONF protocol layer. 373 This section details the characteristics that NETCONF requires from 374 the underlying application protocol. 376 2.1 Connection-oriented operation 378 NETCONF is connection-oriented, requiring a persistent connection 379 between peers. This connection must provide reliable, sequenced data 380 delivery. 382 NETCONF connections are long-lived, persisting between protocol 383 operations. This allows the client to make changes to the state of 384 the connection that will persist for the lifetime of the connection. 385 For example, authentication information specified for a connection 386 remains in effect until the connection is closed. 388 In addition, resources requested from the server for a particular 389 connection MUST be automatically released when the connection closes, 390 making failure recovery simpler and more robust. For example, when a 391 lock is acquired by a client, the lock persists until either 392 explicitly released or the server determines that the connection has 393 been terminated. If a connection is terminated while the client 394 holds a lock, the server can perform any appropriate recovery. The 395 lock operation is further discussed in Section 7.5. 397 2.2 Authentication, Integrity, and Privacy 399 NETCONF connections must provide authentication, data integrity, and 400 privacy. NETCONF depends on the application protocol for this 401 capability. A NETCONF peer assumes that an appropriate level of 402 security and privacy are provided independent of this document. For 403 example, connections may be encrypted in TLS [4] or SSH [10], 404 depending on the underlying protocol. 406 2.3 Authentication 408 NETCONF connections must be authenticated. The application protocol 409 is responsible for authentication. The peer assumes that the 410 connection's authentication information has been validated by the 411 underlying protocol using sufficiently trustworthy mechanisms and 412 that the peer's identity has been sufficiently proven. 414 One goal of NETCONF is to provide a programmatic interface to the 415 device that closely follows the functionality of the device's native 416 interface. Therefore, it is expected that the underlying protocol 417 uses existing authentication mechanisms defined by the device. For 418 example, a device that supports RADIUS [7] should allow the use of 419 RADIUS to authenticate NETCONF sessions. 421 The authentication process should result in an identity whose 422 permissions are known to the device. These permissions MUST be 423 enforced during the remainder of the NETCONF session. 425 3. XML Considerations 427 XML serves as the encoding format for NETCONF, allowing complex 428 hierarchical data to be expressed in a text format that can be read, 429 saved, and manipulated with both traditional text tools and tools 430 specific to XML. 432 This section discusses a small number of XML-related considerations 433 pertaining to NETCONF. 435 3.1 Namespace 437 All NETCONF protocol elements are defined in the following namespace: 439 urn:ietf:params:xml:ns:netconf:base:1.0 441 NETCONF capability names MUST be URIs [5], and SHOULD be URNs [6]. 442 NETCONF capabilities are discussed in Section 8. 444 3.2 No Document Type Declarations 446 Document type declarations MUST NOT appear in NETCONF content. 448 4. RPC Model 450 The NETCONF protocol uses an RPC-based communication model. NETCONF 451 peers use and elements to provide application 452 protocol-independent framing of NETCONF requests and responses. 454 4.1 Element 456 The element is used to enclose a NETCONF request sent from the 457 client to the server. 459 The element has a mandatory attribute "message-id", which is an 460 arbitrary string chosen by the sender of the RPC that will commonly 461 encode a monotonically increasing integer. The receiver of the RPC 462 does not decode or interpret this string but simply saves it to use 463 as a "message-id" attribute in any resulting message. 464 For example: 466 468 469 470 471 473 If additional attributes are present in an element, a NETCONF 474 peer MUST return them unmodified in the element. 476 The name and parameters of an RPC are encoded as the contents of the 477 element. The name of the RPC is an element directly inside the 478 element, and any parameters are encoded inside this element. 480 The following example invokes a method called which 481 has two parameters, , with a value of "14", and 482 , with a value of "fred": 484 486 487 14 488 fred 489 490 492 The following example invokes a method with a parameter of "27606-0100": 495 497 498 27606-0100 499 500 502 The following example invokes the NETCONF method with no 503 parameters: 505 507 508 510 4.2 Element 512 The message is sent in response to a operation. 514 The element has a mandatory attribute "message-id", which 515 is equal to the "message-id" attribute of the for which this is 516 a response. 518 A NETCONF peer MUST also return any additional attributes included in 519 the element unmodified in the element. 521 The response name and response data are encoded as the contents of 522 the element. The name of the reply is an element 523 directly inside the element, and any data is encoded 524 inside this element. 526 For example: 528 The following element invokes the NETCONF method and 529 includes an additional attribute called "user-id". Note that the 530 "user-id" attribute is not in the NETCONF namespace. The returned 531 element returns the "user-id" attribute, as well as the 532 requested content. 534 538 539 541 545 546 547 548 550 4.3 Element 552 The element is sent in messages if an error 553 occurs during the processing of an request. 555 If a server encounters multiple errors during the processing of an 556 request, the MAY contain multiple 557 elements. However, a server is not required to detect or report more 558 than one element, if a request contains multiple errors. 559 A server is not required to check for particular error conditions in 560 a specific sequence. A server MUST return an element if 561 any error conditions occur during processing, and SHOULD return an 562 element if any warning conditions occur during 563 processing. 565 A server MUST NOT return application level or data model specific 566 error information in an element for which the client does 567 not have sufficient access rights. 569 The element includes the following information: 571 error-type: Defines the conceptual layer that the error occurred. 572 Enumeration. One of: 574 * transport 576 * rpc 578 * protocol 580 * application 582 error-tag: Contains a string identifying the error condition. See 583 Appendix A for allowed values. 585 error-severity: Contains a string identifying the error severity, as 586 determined by the device. One of: 588 * error 590 * warning 592 error-app-tag: Contains a string identifying the data model specific 593 or implementation specific error condition, if one exists. This 594 element will not be present if no appropriate application error 595 tag can be associated with a particular error condition. 597 error-path: Contains the absolute XPath [2] expression identifying 598 the element path to the node which is associated with the error 599 being reported in a particular rpc-error element. This element 600 will not be present if no appropriate payload element can be 601 associated with a particular error condition, or if the 'bad- 602 element' QString returned in the 'error-info' container is 603 sufficient to identify the node associated with the error. 605 error-message: Contains a string suitable for human display which 606 describes the error condition. This element will not be present 607 if no appropriate message is provided for a particular error 608 condition. This element SHOULD include an xml:lang attribute as 609 defined in [1] and discussed in [11]. 611 error-info: Contains protocol or data model specific error content. 612 This element will not be present if no such error content is 613 provided for a particular error condition. The list in Appendix A 614 defines any mandatory error-info content for each error. After 615 any protocol-mandated content, a data model definition may mandate 616 certain application layer error information be included in the 617 error-info container. An implementation may include additional 618 elements to provide extended and/or implementation-specific 619 debugging information. 621 Appendix A enumerates the standard NETCONF errors. 623 Example: 625 An error is returned if an element is received without a 626 message-id attribute. Note that only in this case is it 627 acceptable for the NETCONF peer to omit the message-id attribute 628 in the element. 630 631 632 633 634 635 636 638 639 640 rpc 641 missing-attribute 642 error 643 644 message-id 645 rpc 646 647 648 650 The following illustrates the case of returning 651 multiple elements. 653 655 656 application 657 invalid-value 658 error 659 660 MTU value 25000 is not within range 256..9192 661 662 663 664 665 Ethernet0/0 666 25000 667 668 669 670 671 672 application 673 invalid-value 674 error 675 676 Invalid IP address for interface Ethernet1/0 677 678 679 680 681 Ethernet1/0 682
683 1.4 684 24 685
686 687 688 689 690 692 4.4 Element 694 The element is sent in messages if no error occurred 695 during the processing of an request. For example: 697 699 701 703 4.5 Pipelining 705 NETCONF requests MUST be processed serially by the managed 706 device. Additional requests MAY be sent before previous ones 707 have been completed. The managed device MUST send responses only in 708 the order the requests were received. 710 5. Configuration Model 712 NETCONF provides an initial set of operations and a number of 713 capabilities that can be used to extend the base. NETCONF peers 714 exchange device capabilities when the session is initiated as 715 described in Section 8.1. 717 5.1 Configuration Datastores 719 NETCONF defines the existence of one or more configuration datastores 720 and allows configuration operations on them. A configuration 721 datastore is defined as the complete set of configuration data that 722 is required to get a device from its initial default state into a 723 desired operational state. The configuration datastore does not 724 include state data or executive commands. 726 Only the configuration datastore is present in the base 727 model. Additional configuration datastores may be defined by 728 capabilities. Such configuration datastores are available only on 729 devices that advertise the capabilities. 731 o Running: The complete configuration currently active on the 732 network device. Only one configuration datastore of this type 733 exists on the device, and it is always present. NETCONF protocol 734 operations refer to this datastore using the element. 736 The capabilities in Section 8.3 and Section 8.7 define the 737 and configuration datastores, respectively. 739 6. Subtree Filtering 741 6.1 Overview 743 XML subtree filtering is a mechanism that allows an application to 744 select particular XML subtrees to include in the for a 745 or operation. A small set of filters for 746 inclusion, simple content exact-match, and selection is provided, 747 which allows some useful, but also very limited selection mechanisms. 749 The agent does not need to utilize any data-model specific semantics 750 during processing, allowing for simple and centralized implementation 751 strategies. 753 Conceptually, a subtree filter is comprised of zero or more element 754 subtrees, which represent the filter selection criteria. At each 755 containment level within a subtree, the set of sibling nodes is 756 logically processed by the server to determine if its subtree (and 757 path to the root) are included in the filter output. 759 All elements present in a particular subtree within a filter must 760 match associated nodes present in the server's conceptual data model. 761 XML namespaces may be specified (via 'xmlns' declarations) within the 762 filter data model. If so, the declared namespace must first exactly 763 match a namespace supported by the server. Note that prefix values 764 for qualified namespaces are not relevant when comparing filter 765 elements to elements in the underlying data model. Only data 766 associated with a specified namespace will be included in the filter 767 output. 769 Each node specified in a subtree filter represents an inclusive 770 filter. Only associated nodes in underlying data model(s) within the 771 specified configuration datastore on the server are selected by the 772 filter. A node must exactly match the namespace and absolute path 773 name of the filter data, except the filter absolute path name is 774 adjusted to start from the layer below . 776 Response messages contain only the subtrees selected by the filter. 777 Any selection criteria that were present in the request, within a 778 particular selected subtree, is also included in the response. Note 779 that some elements expressed in the filter as leaf nodes will be 780 expanded (i.e., subtrees included) in the filter output. Specific 781 data instances are not duplicated in the response in the event the 782 request contains multiple filter subtree expressions which select the 783 same data. 785 6.2 Subtree Filter Components 787 A subtree filter is comprised of XML elements and their XML 788 attributes. There are five types of components that may be present 789 in a subtree filter: 791 o Namespace Selection 793 o Attribute Match Expressions 795 o Containment Nodes 796 o Selection Nodes 798 o Content Match Nodes 800 6.2.1 Namespace Selection 802 If namespaces are used then the filter output will only include 803 elements from the specified namespace. A namespace is considered to 804 match (for filter purposes) if the content of the 'xmlns' attributes 805 are the same in the filter and the underlying data model. Note that 806 namespace selection cannot be used by itself. At least one element 807 must be specified in the filter in order for any elements to selected 808 in the filter output. 810 Example: 812 813 814 816 In this example the element is a selection node, and only this 817 node and any child nodes (from the underlying data model) in the 818 'http://example.com/schema/1.2/config' namespace will be included in 819 the filter output. 821 6.2.2 Attribute Match Expressions 823 An attribute which appears in a subtree filter is part of an 824 "attribute match expression". Any number of (unqualified or 825 qualified) XML attributes may be present in any type of filter node. 826 In addition to the selection criteria normally applicable to that 827 node, the selected data must have matching values for every attribute 828 specified in the node. If an element is not defined to include a 829 specified attribute, then it is not selected in the filter output. 831 Example: 833 834 835 836 837 838 839 841 In this example the , and elements are 842 containment nodes, and 'ifName' is an attribute match expression. 844 Only nodes in the 'http://example.com/schema/1.2/config' namespace, 845 which match the absolute path '/top/interfaces/interface', and the 846 element has an 'ifName' attribute defined with the value 847 'eth0', will be included in the filter output, 849 6.2.3 Containment Nodes 851 Nodes which contain child elements within a subtree filter are called 852 "containment nodes". Each child element can be any type of node, 853 including another containment node. For each containment node 854 specified in a subtree filter, all data model instances which exactly 855 match the specified namespaces, absolute path, and any attribute 856 match expressions within this node, are included in the filter 857 output. 859 Example: 861 862 863 864 865 867 In this example the , element is a containment node, and the 868 element is a selection node. Only nodes in the 869 'http://example.com/schema/1.2/config' namespace, which match the 870 absolute path '/top/users' will be included in the filter output. 872 6.2.4 Selection Nodes 874 An empty leaf node within a filter is called a "selection node", and 875 it represents an "explicit selection" filter on the underlying data 876 model. Presence of any selection nodes within a set of sibling nodes 877 will cause the filter to select the specified subtree(s), and 878 suppress automatic selection of the entire set of sibling nodes in 879 the underlying data model. For filtering purposes, an empty leaf 880 node can be declared with either an empty tag (e.g., ) or with 881 explicit start and end tags (e.g., ). Any whitespace 882 characters are ignored in this form. 884 Example: 886 887 888 889 890 892 In this example the element is a containment node, and the 893 element is a selection node. Only nodes in the 894 'http://example.com/schema/1.2/config' namespace, which match the 895 absolute path '/top/users' will be included in the filter output. 897 6.2.5 Content Match Nodes 899 A leaf node which contains simple content is called a "content match 900 node". It is used to select some or all of its sibling nodes for 901 filter output, and represents an exact-match filter on the leaf node 902 element content. The following constraints apply to content match 903 nodes: 905 o A content match node must not contain nested elements (i.e., must 906 resolve to a simpleType in XSD). 908 o Multiple content match nodes (i.e., sibling nodes) are logically 909 combined in an "AND" expression. 911 o Filtering of mixed content is not supported. 913 o Filtering of list content is not supported. 915 o Filtering of whitespace only content is not supported. 917 o A content match node must contain non-whitespace characters. An 918 empty element (e.g., ) will interpreted as a selection 919 node (e.g., ). 921 o Leading and trailing whitespace characters are ignored, but any 922 whitespace characters within a block of text characters are not 923 ignored or modified. 925 If all specified sibling content match nodes in a subtree filter 926 expression are 'true', then the filter output nodes are selected in 927 the following manner: 929 o Each content match node in the sibling set is included in the 930 filter output. 932 o If any containment nodes are present in the sibling set then they 933 are processed further, and included if any nested filter criteria 934 is also met. 936 o If any selection nodes are present in the sibling set then all of 937 them are included in the filter output. 939 o Otherwise (i.e., there are no selection or containment nodes in 940 the filter sibling set) all the nodes defined at this level in the 941 underlying data model (and their subtrees, if any) are returned in 942 the filter output. 944 If any of the sibling content match node tests are 'false', then no 945 further filter processing is performed on that sibling set, and none 946 of the sibling subtrees are selected by the filter, including the 947 content match node(s). 949 Example: 951 952 953 954 955 fred 956 957 958 959 961 In this example the and nodes are both containment 962 nodes, and is a content match node. Since no sibling nodes of 963 are specified (and therefore no containment or selection 964 nodes) all of the sibling nodes of are returned in the filter 965 output. Only nodes in the 'http://example.com/schema/1.2/config' 966 namespace, which match the absolute path '/top/users/user', and for 967 which the element is equal to 'fred', will be included in the 968 filter output. 970 6.3 Subtree Filter Processing 972 The filter output (the set of selected nodes) is initially empty. 974 Each subtree filter can contain one or more data model fragments, 975 which represent portions of the data model which should be selected 976 (with all child nodes) in the filter output. 978 Each subtree data fragment is compared by the server to the internal 979 data models supported by the server. If the entire subtree data- 980 fragment filter (starting from the root to the innermost element 981 specified in the filter) exactly matches a corresponding portion of 982 the supported data model, then that node and all its children are 983 included in the result data. 985 The server processes all nodes with the same parent node (sibling 986 set) together, starting from the root to the leaf nodes. The root 987 elements in the filter are considered to be in the same sibling set 988 (assuming they are in the same namespace), even though they do not 989 have a common parent. 991 For each sibling set, the server determines which nodes are included 992 (or potentially included) in the filter output, and which sibling 993 subtrees are excluded (pruned) from the filter output. The server 994 first determines which types of nodes are present in the sibling set, 995 and processes the nodes according to the rules for their type. If 996 any nodes in the sibling set are selected, then the process is 997 recursively applied to the sibling sets of each selected node. The 998 algorithm continues until all sibling sets in all subtrees specified 999 in the filter have been processed. 1001 6.4 Subtree Filtering Examples 1003 6.4.1 No filter 1005 Leaving out the filter on the get operation returns the entire data 1006 model. 1008 1010 1011 1013 1015 1016 1017 1018 1020 6.4.2 Empty filter 1022 An empty filter will select nothing because no content match or 1023 selection nodes are present. This is not an error. The filter type 1024 attribute used in these examples is discussed further in Section 7.1. 1026 1028 1029 1030 1031 1032 1034 1036 1037 1038 1040 6.4.3 Select the entire subtree 1042 This filter in this example contains one selection node (), so 1043 just that subtree is selected by the filter. This example represents 1044 the fully-populated data model in most of the filter examples 1045 that follow. In a real data model, the would not 1046 likely be returned with the list of users for a particular host or 1047 network. 1049 NOTE: The filtering and configuration examples used in this document 1050 appear in the namespace "http://example.com/schema/1.2/config". The 1051 root element of this namespace is . The element and its 1052 descendents represent an example configuration data model only. 1054 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1068 1070 1071 1072 1073 1074 root 1075 superuser 1076 Charlie Root 1077 1078 1 1079 1 1080 1081 1082 1083 fred 1084 admin 1085 Fred Flintstone 1086 1087 2 1088 2 1089 1090 1091 1092 barney 1093 admin 1094 Barney Rubble 1095 1096 2 1097 3 1098 1099 1100 1101 1102 1103 1105 The following filter request would have produced the same result, but 1106 only because the container defines one child element () 1107 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1123 6.4.4 Select all elements within the subtree 1125 This filter contains two containment nodes (, ), and one 1126 selector node (). All instances of the element in the 1127 same sibling set are selected in the filter output. The manager may 1128 need to know that is used as an instance identifier in this 1129 particular data structure, but the server does not need to know that 1130 meta-data in order to process the request. 1132 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1150 1152 1153 1154 1155 1156 root 1157 1158 1159 fred 1160 1161 1162 barney 1163 1164 1165 1166 1167 1169 6.4.5 One specific entry 1171 This filter contains two containment nodes (, ) and one 1172 content match node (). All instances of the sibling set 1173 containing , for which the value of equals "fred", are 1174 selected in the filter output. 1176 1178 1179 1180 1181 1182 1183 1184 1185 1186 fred 1187 1188 1189 1190 1191 1192 1194 1196 1197 1198 1199 1200 fred 1201 admin 1202 Fred Flintstone 1203 1204 2 1205 2 1206 1207 1208 1209 1210 1211 1213 6.4.6 Specific elements from a specific entry 1215 This filter contains two containment nodes (, ), one 1216 content match node (), and two selector nodes (, ). All instances of the and elements in the 1218 same sibling set containing , for which the value of 1219 equals "fred", are selected in the filter output. The 1220 element is not included because the sibling set contains selection 1221 nodes. 1223 1225 1226 1227 1228 1229 1230 1231 1232 1233 fred 1234 1235 1236 1237 1238 1239 1240 1241 1243 1245 1246 1247 1248 1249 fred 1250 admin 1251 Fred Flintstone 1252 1253 1254 1255 1256 1258 6.4.7 Multiple Subtrees 1260 This filter contains three subtrees (name=root, fred, barney) 1262 The "root" subtree filter contains two containment nodes (, 1263 ), one content match node (), and one selector node 1264 (). The subtree selection criteria is met, and just 1265 the company-info subtree for "root" is selected in the filter output. 1267 The "fred" subtree filter contains three containment nodes (, 1268 , ), one content match node (), and one 1269 selector node (). The subtree selection criteria is met, and 1270 just the element within the company-info subtree for "fred" is 1271 selected in the filter output. 1273 The "barney" subtree filter contains three containment nodes 1274 (, , ), two content match nodes (, 1275 ), and one selector node (). The subtree selection 1276 criteria is not met because user "barney" is not a "superuser", and 1277 the entire subtree for "barney" (including its parent entry) 1278 is excluded from the filter output. 1280 1282 1283 1284 1285 1286 1287 1288 1289 1290 root 1291 1292 1293 1294 fred 1295 1296 1297 1298 1299 1300 barney 1301 superuser 1302 1303 1304 1305 1306 1307 1308 1309 1310 1312 1314 1315 1316 1317 1318 root 1319 1320 1 1321 1 1322 1323 1324 1325 fred 1326 1327 2 1328 1329 1330 1331 1332 1333 1335 6.4.8 Elements with attribute naming 1337 In this example, the filter contains one containment node 1338 (), one attribute match expression (ifName), and one 1339 selector node (). All instances of the 1340 subtree which have an ifName attribute equal to "eth0" are selected 1341 in the filter output. The filter data elements and attributes must 1342 be qualified because the ifName attribute will not be considered part 1343 of the 'schema/1.2' namespace if it is unqualified. 1345 1347 1348 1349 1350 1351 1352 1353 1354 1356 1358 1359 1360 1361 1362 45621 1363 774344 1364 1365 1366 1367 1368 1370 If ifName were a child node instead of an attribute, then the 1371 following request would produce similar results. 1373 1375 1376 1377 1378 1379 eth0 1380 1381 1382 1383 1384 1386 7. Protocol Operations 1388 The NETCONF protocol provides a small set of low-level operations to 1389 manage device configurations and retrieve device state information. 1390 The base protocol provides operations to retrieve, configure, copy, 1391 and delete configuration datastores. Additional operations are 1392 provided, based on the capabilities advertised by the device. 1394 The base protocol includes the following protocol operations: 1396 o get 1398 o get-config 1400 o edit-config 1402 o copy-config 1404 o delete-config 1406 o lock 1408 o unlock 1410 o close-session 1412 o kill-session 1414 A protocol operation may fail for various reasons, including 1415 "operation not supported". An initiator should not assume that any 1416 operation will always succeed. The return values in any RPC reply 1417 should be checked for error responses. 1419 The syntax and XML encoding of the protocol operations are formally 1420 defined in the XML schema in Appendix B. The following sections 1421 describe the semantics of each protocol operation. 1423 7.1 1425 Description: 1427 Retrieve all or part of a specified configuration. 1429 Parameters: 1431 source: 1433 Name of the configuration datastore being queried, such as 1434 . If this element is unspecified, the 1435 configuration is used. 1437 filter: 1439 The filter element identifies the portions of the device 1440 configuration to retrieve. If this element is unspecified, the 1441 entire configuration is returned. 1443 The filter element may optionally contain a "type" attribute. 1444 This attribute indicates the type of filtering syntax used 1445 within the filter element. The default filtering mechanism in 1446 NETCONF is referred to as subtree filtering and is described in 1447 Section 6. The value "subtree" explicitly identifies this type 1448 of filtering. 1450 If the NETCONF peer supports the :xpath capability 1451 (Section 8.9), the value "xpath" may be used to indicate that 1452 the filter element contains an XPath expression. 1454 Positive Response: 1456 If the device can satisfy the request, the server sends an element containing a element with the results of the 1458 query. 1460 Negative Response: 1462 An element is included in the if the 1463 request cannot be completed for any reason. 1465 Example: To retrieve the entire subtree: 1467 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1481 1483 1484 1485 1486 1487 root 1488 superuser 1489 Charlie Root 1490 1491 1 1492 1 1493 1494 1495 1496 1497 1498 1499 1501 If the configuration is available in multiple formats, such as XML 1502 and text, an XML namespace can be used to specify which format is 1503 desired. 1505 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1518 1520 1521 1522 1523 1524 1525 1527 Section 6 contains additional examples of subtree filtering. 1529 7.2 1531 Description: 1533 The operation loads all or part of a specified 1534 configuration to the specified target configuration. This 1535 operation allows the new configuration to be expressed in several 1536 ways, such as using a local file, a remote file, or inline. If 1537 the target configuration does not exist, it will be created. 1539 The device analyzes the source and target configurations and 1540 performs the requested changes. The target configuration is not 1541 necessarily replaced, as with the message. Instead 1542 the target configuration is changed in accordance with the 1543 source's data and requested operations. 1545 Attributes: 1547 operation: 1549 Elements in the subtree may contain an "operation" 1550 attribute. The attribute identifies the point in the 1551 configuration to perform the operation, and MAY appear on 1552 multiple elements throughout the subtree. 1554 If the operation attribute is not specified, the configuration 1555 is merged into the configuration datastore. 1557 The operation attribute has one of the following values: 1559 merge: The configuration data identified by the element 1560 containing this attribute is merged with the configuration 1561 at the corresponding level in the configuration datastore 1562 identified by the target parameter. This is the default 1563 behavior. 1565 replace: The configuration data identified by the element 1566 containing this attribute replaces any related configuration 1567 in the configuration datastore identified by the target 1568 parameter. Unlike a operation, which replaces 1569 the entire target configuration, only the configuration 1570 actually present in the config parameter is affected. 1572 create: The configuration data identified by the element 1573 containing this attribute is added to the configuration if 1574 and only if the configuration data does not already exist on 1575 the device. If the configuration data exists, an element is returned with an value of 1577 data-exists. 1579 delete: The configuration data identified by the element 1580 containing this attribute is deleted in the configuration 1581 datastore identified by the target parameter. 1583 Parameters: 1585 target: 1587 Configuration datastore being edited, such as or 1588 . 1590 default-operation: 1592 Selects the default operation (as described in the "operation" 1593 attribute) for this request. The default value 1594 for the default-operation parameter is "merge". 1596 The default-operation parameter is optional, but if provided, 1597 must have one of the following values: 1599 merge: The configuration data in the parameter is 1600 merged with the configuration at the corresponding level in 1601 the target datastore. This is the default behavior. 1603 replace: The configuration data in the parameter 1604 completely replaces the configuration in the target 1605 datastore. This is useful for loading previously saved 1606 configuration data. 1608 none: The target datastore is unaffected by the configuration 1609 in the parameter, unless and until the incoming 1610 configuration data uses the "operation" attribute to request 1611 a different operation. If the configuration in the 1612 parameter contains data for which there is not a 1613 corresponding level in the target datastore, an 1614 is returned with an value of data-missing. 1615 Using "none" allows operations like "delete" to avoid 1616 unintentionally creating the parent hierarchy of the element 1617 to be deleted. 1619 test-option: 1621 The test-option element may be specified only if the device 1622 advertises the :validate capability (Section 8.6). 1624 The test-option element has one of the following values: 1626 test-then-set: Perform a validation test before attempting to 1627 set. If validation errors occur, do not perform the operation. This is the default test-option. 1630 set: Perform a set without a validation test first. 1632 error-option: 1634 The error-option element has one of the following values: 1636 stop-on-error: Abort the edit-config operation on first error. 1637 This is the default error-option. 1639 ignore-error: Continue to process configuration data on error; 1640 error is recorded and negative response is generated if any 1641 errors occur. 1643 rollback-on-error: If an error condition occurs such that an 1644 error severity element is generated, the server 1645 will stop processing the edit-config operation and restore 1646 the specified configuration to its complete state at the 1647 start of this edit-config operation. This option requires 1648 the server to support the :rollback-on-error capability 1649 described in Section 8.5. 1651 config: 1653 Portion of the configuration subtree to edit. 1655 Positive Response: 1657 If the device was able to satisfy the request, an is 1658 sent containing an element. 1660 Negative Response: 1662 An response is sent if the request cannot be completed 1663 for any reason. 1665 Example: 1667 Set the MTU to 1500 on an interface named "Ethernet0/0" in the 1668 running configuration: 1670 1672 1673 1674 1675 1676 1677 1678 1679 Ethernet0/0 1680 1500 1681 1682 1683 1684 1685 1687 1689 1690 1691 Add an interface named "Ethernet0/0" to the running configuration, 1692 replacing any previous interface with that name: 1694 1696 1697 1698 1699 1700 1701 1702 1703 Ethernet0/0 1704 1500 1705
1706 1.2.3.4 1707 24 1708
1709 1710 1711 1712 1713 1715 1717 1718 1720 Delete the configuration for an interface named "Ethernet0/0" from 1721 the running configuration: 1723 1725 1726 1727 1728 1729 none 1730 1731 1732 1733 Ethernet0/0 1734 1735 1736 1737 1738 1740 1742 1743 1745 Delete interface 192.168.0.1 from an OSPF area (other interfaces 1746 configured in the same area are unaffected): 1748 1750 1751 1752 1753 1754 none 1755 1756 1757 1758 1759 1760 0.0.0.0 1761 1762 1763 192.168.0.1 1764 1765 1766 1767 1768 1769 1770 1771 1772 1774 1776 1777 1779 7.3 1781 Description: 1783 Create or replace an entire configuration datastore with the 1784 contents of another complete configuration datastore. If the 1785 target datastore exists, it is overwritten. Otherwise, a new one 1786 is created, if allowed. 1788 If a NETCONF peer supports the :url capability (Section 8.8), the 1789 element can appear as the or parameter. 1791 A device may choose not to support the configuration 1792 datastore as the parameter of a operation. 1793 A device may choose not to support remote to remote copy 1794 operations, where both the and parameters use 1795 the element. If the source and target parameters identify 1796 the same URL or configuration datastore, an error MUST be returned 1797 with an error-tag containing invalid-value. 1799 Parameters: 1801 source: 1803 The configuration datastore to use as the source of the copy 1804 operation or the element containing the configuration 1805 subtree to copy. 1807 target: 1809 The configuration datastore to use as the destination of the 1810 copy operation. 1812 Positive Response: 1814 If the device was able to satisfy the request, an is 1815 sent that includes an element. 1817 Negative Response: 1819 An element is included within the if the 1820 request cannot be completed for any reason. 1822 Example: 1824 1826 1827 1828 https://user@example.com:passphrase/cfg/new.txt 1829 1830 1831 1832 1833 1834 1836 1838 1839 1841 7.4 1843 Description: 1845 Delete a configuration datastore. The configuration 1846 datastore cannot be deleted. 1848 If a NETCONF peer supports the :url capability (Section 8.8), the 1849 element can appear as the parameter. 1851 Parameters: 1853 target: 1855 Name of the configuration datastore to delete. 1857 Positive Response: 1859 If the device was able to satisfy the request, an is 1860 sent that includes an element. 1862 Negative Response: 1864 An element is included within the if the 1865 request cannot be completed for any reason. 1867 Example: 1869 1871 1872 1873 1874 1875 1876 1878 1880 1881 1883 7.5 1884 Description: 1886 The lock operation allows the client to lock the configuration 1887 system of a device. Such locks are intended to be short-lived and 1888 allow a client to make a change without fear of interaction with 1889 other NETCONF clients, non-NETCONF clients (SNMP and CLI scripts) 1890 and human users. 1892 An attempt to lock the configuration MUST fail if an existing 1893 session or other entity holds a lock on any portion of the lock 1894 target. 1896 When the lock is acquired, the server MUST prevent any changes to 1897 the locked resource other than those requested by this session. 1898 SNMP and CLI requests to modify the resource MUST fail with an 1899 appropriate error. 1901 The duration of the lock is defined as beginning when the lock is 1902 acquired and lasting until either the lock is released or the 1903 NETCONF session closes. The session closure may be explicitly 1904 performed by the client, or implicitly performed by the server 1905 based on criteria such as failure of the underlying transport, or 1906 simple inactivity timeout. This criteria is dependent on the 1907 implementation and the underlying transport. 1909 The lock operation takes a mandatory parameter, target. The 1910 target parameter names the configuration that will be locked. 1911 When a lock is active, using the operation on the 1912 locked configuration and using the locked configuration as a 1913 target of the operation will be disallowed by any 1914 other NETCONF session. Additionally, the system will ensure that 1915 these locked configuration resources will not be modified by other 1916 non-NETCONF management operations such as SNMP and CLI. The 1917 message (at the RPC layer) can be used to force the 1918 release of a lock owned by another NETCONF session. It is beyond 1919 the scope of this document to define how to break locks held by 1920 other entities. 1922 A lock MUST not be granted if any of the following conditions are 1923 true: 1925 * a lock is already held by another NETCONF session or another 1926 entity 1928 * the target configuration has already been modified and these 1929 changes have not been committed or rolled back 1931 The server MUST respond with either an element or an . 1934 A lock will be released by the system if the session holding the 1935 lock is terminated for any reason. 1937 Parameters: 1939 target: 1941 Name of the configuration datastore to lock. 1943 Positive Response: 1945 If the device was able to satisfy the request, an is 1946 sent that contains an element. 1948 Negative Response: 1950 An element is included in the if the 1951 request cannot be completed for any reason. 1953 If the lock is already held, the element will be 1954 'lock-denied' and the element will include the 1955 of the lock owner. If the lock is held by a non- 1956 NETCONF entity, a of 0 (zero) is included. Note that 1957 any other entity performing a lock on even a partial piece of a 1958 target will prevent a NETCONF lock (which is global) from being 1959 obtained on that target. 1961 Example: 1963 The following example shows a successful acquisition of a lock. 1965 1967 1968 1969 1970 1971 1972 1974 1976 1977 1979 Example: 1981 The following example shows a failed attempt to acquire of a lock 1982 when the lock is already in use. 1984 1986 1987 1988 1989 1990 1991 1993 1995 1996 protocol 1997 lock-denied 1998 error 1999 2000 Lock failed, lock is already held 2001 2002 2003 454 2004 2005 2006 2007 2009 7.6 2011 Description: 2013 The unlock operation is used to release a configuration lock, 2014 previously obtained with the operation. 2016 An unlock operation will not succeed if any of the following 2017 conditions are true: 2019 * the specified lock is not currently active 2021 * the session issuing the operation is not the same 2022 session that obtained the lock 2024 The server MUST respond with either an element or an . 2027 Parameters: 2029 target: 2031 Name of the configuration datastore to unlock. 2033 A NETCONF client is not permitted to unlock a configuration 2034 datastore that it did not lock. 2036 Positive Response: 2038 If the device was able to satisfy the request, an is 2039 sent that contains an element. 2041 Negative Response: 2043 An element is included in the if the 2044 request cannot be completed for any reason. 2046 Example: 2048 2050 2051 2052 2053 2054 2055 2057 2059 2060 2062 7.7 2064 Description: 2066 Retrieve running configuration and device state information. 2068 Parameters: 2070 filter: 2072 This parameter specifies the portion of the system 2073 configuration and state data to retrieve. If this parameter is 2074 empty, all the device configuration and state information is 2075 returned. 2077 The filter element may optionally contain a 'type' attribute. 2078 This attribute indicates the type of filtering syntax used 2079 within the filter element. The default filtering mechanism in 2080 NETCONF is referred to as subtree filtering and is described in 2081 Section 6. The value 'subtree' explicitly identifies this type 2082 of filtering. 2084 If the NETCONF peer supports the :xpath capability 2085 (Section 8.9), the value 'xpath' may be used to indicate that 2086 the filter element contains an XPath expression. 2088 Positive Response: 2090 If the device was able to satisfy the request, an is 2091 sent. The section contains the appropriate subset. 2093 Negative Response: 2095 An element is included in the if the 2096 request cannot be completed for any reason. 2098 Example: 2100 2102 2103 2104 2105 2106 eth0 2107 2108 2109 2110 2111 2113 2115 2116 2117 2118 2119 eth0 2120 45621 2121 774344 2122 2123 2124 2125 2126 2128 7.8 2130 Description: 2132 Request graceful termination of a NETCONF session. 2134 When a NETCONF server receives a request, it will 2135 gracefully close the session. The server will release any locks 2136 and resources associated with the session and gracefully close any 2137 associated connections. Any NETCONF requests received after a 2138 request will be ignored. 2140 Positive Response: 2142 If the device was able to satisfy the request, an is 2143 sent that includes an element. 2145 Negative Response: 2147 An element is included in the if the 2148 request cannot be completed for any reason. 2150 Example: 2152 2154 2155 2157 2159 2160 2162 7.9 2164 Description: 2166 Force the termination of a NETCONF session. 2168 When a NETCONF entity receives a request for an 2169 open session, it will abort any operations currently in process, 2170 release any locks and resources associated with the session and 2171 close any associated connections. 2173 Parameters: 2175 session-id: 2177 Session identifier of the NETCONF session to be terminated. If 2178 this value is equal to the current session ID, an 'invalid- 2179 value' error is returned. 2181 Positive Response: 2183 If the device was able to satisfy the request, an is 2184 sent that includes an element. 2186 Negative Response: 2188 An element is included in the if the 2189 request cannot be completed for any reason. 2191 Example: 2193 2195 2196 4 2197 2198 2200 2202 2203 2205 8. Capabilities 2207 This section defines a set of capabilities that a client or a server 2208 MAY implement. Each peer advertises its capabilities by sending them 2209 during an initial capabilities exchange. Each peer needs to 2210 understand only those capabilities that it might use and must be able 2211 to process and ignore any capability received from the other peer 2212 that it does not require or does not understand. 2214 Additional capabilities can be defined using the template in 2215 Appendix C. Future capability definitions may be published as 2216 standards by standards bodies or published as proprietary extensions. 2218 A NETCONF capability is identified with a URI. The base capabilities 2219 are defined using URNs following the method described in RFC 3553 2220 [8]. Capabilities defined in this document have the following 2221 format: 2223 urn:ietf:params:xml:ns:netconf:capability:{name}:1.0 2225 where {name} is the name of the capability. Capabilities are often 2226 referenced in discussions and email using the shorthand :{name}. For 2227 example, the foo capability would have the formal name 2228 "urn:ietf:params:xml:ns:netconf:capability:foo:1.0" and be called 2229 ":foo". The shorthand form MUST NOT be used inside the protocol. 2231 8.1 Capabilities Exchange 2233 A NETCONF capability is a set of additional functionality implemented 2234 on top of the base NETCONF specification. The capability is 2235 distinguished by a URI. 2237 Capabilities are advertised in messages sent by each peer during 2238 session establishment. When the NETCONF session is opened, each peer 2239 MUST send a element containing a list of that peer's 2240 capabilities. Each peer MUST send at least the base NETCONF 2241 capability, "urn:ietf:params:xml:ns:netconf:base:1.0". 2243 A server sending the element MUST include a 2244 element containing the session ID for this NETCONF session. A client 2245 sending the element MUST NOT include a element. 2247 A server receiving a element MUST NOT continue the 2248 NETCONF session. Similarly, a client which does not receive a 2249 element in the server's message MUST NOT 2250 continue the NETCONF session. In both cases the underlying transport 2251 should be closed. 2253 In the following example, a server advertises the base NETCONF 2254 capability, one NETCONF capability defined in the base NETCONF 2255 document, and one implementation-specific capability. 2257 2258 2259 2260 urn:ietf:params:xml:ns:netconf:base:1.0 2261 2262 2263 urn:ietf:params:xml:ns:netconf:capability:startup:1.0 2264 2265 2266 http:/example.net/router/2.3/myfeature 2267 2268 2269 4 2270 2272 Each peer sends its element simultaneously as soon as the 2273 connection is open. A peer MUST NOT wait to receive the capability 2274 set from the other side before sending its own set. 2276 8.2 Writable-Running Capability 2278 8.2.1 Description 2280 The :writable-running capability indicates that the device supports 2281 writes directly to the configuration datastore. In other 2282 words, the device supports edit-config and copy-config operations 2283 where the configuration is the target. 2285 8.2.2 Dependencies 2287 None. 2289 8.2.3 Capability and Namespace 2291 The :writable-running capability is identified by the following 2292 capability string: 2294 urn:ietf:params:xml:ns:netconf:capability:writable-running:1.0 2296 8.2.4 New Operations 2298 None. 2300 8.2.5 Modifications to Existing Operations 2302 8.2.5.1 2304 The :writable-running capability modifies the operation 2305 to accept the element as a . 2307 8.2.5.2 2309 The :writable-running capability modifies the operation 2310 to accept the element as a . 2312 8.3 Candidate Configuration Capability 2314 8.3.1 Description 2316 The candidate configuration capability, :candidate, indicates that 2317 the device supports a candidate configuration datastore, which is 2318 used to hold configuration data that can manipulated without 2319 impacting the device's current configuration. The candidate 2320 configuration is a full configuration data set that serves as a work 2321 place for creating and manipulating configuration data. Additions, 2322 deletions, and changes may be made to this data to construct the 2323 desired configuration data. A operation may be performed at 2324 any time that causes the device's running configuration to be set to 2325 the value of the candidate configuration. 2327 The candidate configuration can be used as a source or target of any 2328 operation with a or parameter. The 2329 element is used to indicate the candidate configuration: 2331 2333 2334 2335 2336 2337 2338 2340 The candidate configuration may be shared among multiple sessions. 2341 Unless a client has specific information that the candidate 2342 configuration is not shared (for example, through another capability, 2343 e.g. :lock), it must assume that other sessions may be able to modify 2344 the candidate configuration at the same time. It is therefore 2345 prudent for a client to lock the candidate configuration before 2346 modifying it. 2348 The client can discard any changes since the last operation 2349 by executing the operation. The candidate 2350 configuration's content then reverts to the current committed 2351 configuration. 2353 8.3.2 Dependencies 2355 None. 2357 8.3.3 Capability and Namespace 2359 The :candidate capability is identified by the following capability 2360 string: 2362 urn:ietf:params:xml:ns:netconf:capability:candidate:1.0 2364 8.3.4 New Operations 2366 8.3.4.1 2368 Description: 2370 When a candidate configuration's content is complete, the 2371 configuration data can be committed, publishing the data set to 2372 the rest of the device and requesting the device to conform to 2373 the behavior described in the new configuration. 2375 To commit the candidate configuration as the device's new 2376 current configuration, use the operation. 2378 The operation instructs the device to implement the 2379 configuration data contained in the candidate configuration. 2380 If the device is unable to commit all of the changes in the 2381 candidate configuration datastore, then the running 2382 configuration MUST remain unchanged. If the device does 2383 succeed in committing, the running configuration MUST be 2384 updated with the contents of the candidate configuration. 2386 If the system does not have the :candidate capability, the 2387 operation is not available. 2389 Positive Response: 2391 If the device was able to satisfy the request, an 2392 is sent that contains an element. 2394 Negative Response: 2396 An element is included in the if the 2397 request cannot be completed for any reason. 2399 Example: 2401 2403 2404 2406 2408 2409 2411 8.3.4.2 2413 If the client decides that the candidate configuration should not be 2414 committed, the operation can be used to revert the 2415 candidate configuration to the current committed configuration. 2417 2419 2420 2422 This operation discards any uncommitted changes by reseting the 2423 candidate configuration with the content of the running 2424 configuration. 2426 8.3.5 Modifications to Existing Operations 2428 8.3.5.1 and 2430 The candidate configuration can be locked using the operation 2431 with the element as the parameter: 2433 2435 2436 2437 2438 2439 2440 2442 Similarly, the candidate configuration is unlocked using the 2443 element as the parameter: 2445 2447 2448 2449 2450 2451 2452 2454 When a client fails with outstanding changes to the candidate 2455 configuration, recovery can be difficult. To facilitate easy 2456 recovery, any outstanding changes are discarded when the lock is 2457 released, whether explicitly with the operation or 2458 implicitly from session failure. 2460 8.4 Confirmed Commit Capability 2462 8.4.1 Description 2464 The :confirmed-commit capability indicates that the server will 2465 support the and parameters for the 2466 protocol operation. See section Section 8.3 for further 2467 details on the operation. 2469 A confirmed commit operation MUST be reverted if a follow-up commit 2470 (called the "confirming commit") is not issued within 600 seconds (10 2471 minutes). The timeout period can be adjusted with the element. The confirming commit can itself include a 2473 parameter. 2475 If the session issuing the confirmed commit is terminated for any 2476 reason before the confirm timeout expires, the server MUST restore 2477 the configuration to its state before the confirmed commit was 2478 issued. 2480 If the device reboots for any reason before the confirm timeout 2481 expires, the server MUST restore the configuration to its state 2482 before the confirmed commit was issued. 2484 If a confirming commit is not issued, the device will revert its 2485 configuration to the state prior to the issuance of the confirmed 2486 commit. Note that any commit operation, including a commit which 2487 introduces additional changes to the configuration, will serve as a 2488 confirming commit. Thus to cancel a confirmed commit and revert 2489 changes without waiting for the confirm timeout to expire, the 2490 manager can explicitly restore the configuration to its state before 2491 the confirmed commit was issued. 2493 For shared configurations, this feature can cause other configuration 2494 changes (for example, via other NETCONF sessions) to be inadvertently 2495 altered or removed, unless the configuration locking feature is used 2496 (in other words, lock obtained before the edit-config operation is 2497 started). Therefore, it is strongly suggested that in order to use 2498 this feature with shared configuration databases, configuration 2499 locking should also be used. 2501 8.4.2 Dependencies 2503 The :confirmed-commit capability is only relevant if the :candidate 2504 capability is also supported. 2506 8.4.3 Capability and Namespace 2508 The :confirmed-commit capability is identified by the following 2509 capability string: 2511 urn:ietf:params:xml:ns:netconf:capability:confirmed-commit:1.0 2513 8.4.4 New Operations 2515 None. 2517 8.4.5 Modifications to Existing Operations 2519 8.4.5.1 2521 The :confirmed-commit capability allows 2 additional parameters to 2522 the operation. 2524 Parameters: 2526 confirmed: 2528 Perform a confirmed commit operation. 2530 confirm-timeout: 2532 Timeout period for confirmed commit, in seconds. If 2533 unspecified, the confirm timeout defaults to 600 seconds. 2535 Example: 2537 2539 2540 2541 120 2542 2543 2545 2547 2548 2550 8.5 Rollback on Error Capability 2552 8.5.1 Description 2554 This capability indicates that the server will support the 'rollback- 2555 on-error' value in the parameter to the 2556 operation. 2558 For shared configurations, this feature can cause other configuration 2559 changes (for example, via other NETCONF sessions) to be inadvertently 2560 altered or removed, unless the configuration locking feature is used 2561 (in other words, lock obtained before the edit-config operation is 2562 started). Therefore, it is strongly suggested that in order to use 2563 this feature with shared configuration databases, configuration 2564 locking must also be used. 2566 8.5.2 Dependencies 2568 None 2570 8.5.3 Capability and Namespace 2572 The :rollback-on-error capability is identified by the following 2573 capability string: 2575 urn:ietf:params:xml:ns:netconf:capability:rollback-on-error:1.0 2577 8.5.4 New Operations 2579 None. 2581 8.5.5 Modifications to Existing Operations 2583 8.5.5.1 2585 The :rollback-on-error capability allows the 'rollback-on-error' 2586 value to the parameter on the operation. 2588 2590 2591 2592 2593 2594 rollback-on-error 2595 2596 2597 2598 Ethernet0/0 2599 100000 2600 2601 2602 2603 2604 2606 2608 2609 2611 8.6 Validate Capability 2612 8.6.1 Description 2614 Validation consists of checking a candidate configuration for 2615 syntactical and semantic errors before applying the configuration to 2616 the device. 2618 If this capability is advertised, the device supports the 2619 protocol operation and checks at least for syntax errors. In 2620 addition, this capability supports the test-option parameter to the 2621 operation and, when it is provided, checks at least for 2622 syntax errors. 2624 8.6.2 Dependencies 2626 None. 2628 8.6.3 Capability and Namespace 2630 The :validate capability is identified by the following capability 2631 string: 2633 urn:ietf:params:xml:ns:netconf:capability:validate:1.0 2635 8.6.4 New Operations 2637 8.6.4.1 2639 Description: 2641 This protocol operation validates the contents of the specified 2642 configuration. 2644 Parameters: 2646 source: 2648 Name of the configuration datastore being validated, such as 2649 . 2651 Positive Response: 2653 If the device was able to satisfy the request, an 2654 is sent that contains an element. 2656 Negative Response: 2658 An element is included in the if the 2659 request cannot be completed for any reason. 2661 A validate operation can fail for any of the following reasons: 2663 + Syntax errors 2665 + Missing parameters 2667 + References to undefined configuration data 2669 Example: 2671 2673 2674 2675 2676 2677 2678 2680 2682 2683 2685 8.7 Distinct Startup Capability 2687 8.7.1 Description 2689 The device supports separate running and startup configuration 2690 datastores. Operations which affect the running configuration will 2691 not be automatically copied to the startup configuration. An 2692 explicit operation from the to the 2693 must be invoked to update the startup configuration to the current 2694 contents of the running configuration. NETCONF protocol operations 2695 refer to the startup datastore using the element. 2697 8.7.2 Dependencies 2699 None. 2701 8.7.3 Capability and Namespace 2703 The :startup capability is identified by the following capability 2704 string: 2706 urn:ietf:params:xml:ns:netconf:capability:startup:1.0 2708 8.7.4 New Operations 2710 None. 2712 8.7.5 Modifications to Existing Operations 2714 8.7.5.1 2716 To save the startup configuration, use the copy-config operation to 2717 copy the configuration datastore to the 2718 configuration datastore. 2720 2722 2723 2724 2725 2726 2727 2728 2729 2730 2732 8.8 URL Capability 2734 8.8.1 Description 2736 The NETCONF peer has the ability to accept the element in 2737 and parameters. The capability is further 2738 identified by URL arguments indicating the protocols supported. 2740 8.8.2 Dependencies 2742 None. 2744 8.8.3 Capability and Namespace 2746 The :url capability is identified by the following capability string: 2748 urn:ietf:params:xml:ns:netconf:capability:url:1.0?protocol={name,...} 2750 The :url capability URI MUST contain a "protocol" argument assigned a 2751 comma-separated list of protocol names indicating which protocols the 2752 NETCONF peer supports. For example: 2754 urn:ietf:params:xml:ns:netconf:capability:url: 2755 1.0?protocol=http,ftp,file 2757 8.8.4 New Operations 2759 None. 2761 8.8.5 Modifications to Existing Operations 2763 8.8.5.1 2765 The :url capability modifies the operation to accept 2766 the element as an alternative to the parameter. If 2767 the element is specified, then it should identify a local 2768 configuration file. 2770 8.8.5.2 2772 The :url capability modifies the operation to accept 2773 the element as the value of the the and the 2774 parameters. 2776 8.8.5.3 2778 The :url capability modifies the operation to accept 2779 the element as the value of the the parameters. If 2780 this parameter contains a URL, then it should identify a local 2781 configuration file. 2783 8.8.5.4 2785 The :url capability modifies the operation to accept the 2786 element as the value of the the parameter. 2788 8.9 XPath Capability 2790 8.9.1 Description 2792 The XPath capability indicates that the NETCONF peer supports the use 2793 of XPath expressions in the element. XPath is described in 2794 [2]. 2796 8.9.2 Dependencies 2798 None. 2800 8.9.3 Capability and Namespace 2802 The :xpath capability is identified by the following capability 2803 string: 2805 urn:ietf:params:xml:ns:netconf:capability:xpath:1.0 2807 8.9.4 New Operations 2809 None. 2811 8.9.5 Modifications to Existing Operations 2813 8.9.5.1 and 2815 The :xpath capability modifies the and operations 2816 to accept the value "xpath" in the type attribute of the filter 2817 element. When the type attribute is set to "xpath", the contents of 2818 the filter element will be treated as an xpath expression and used to 2819 filter the returned data. 2821 For example: 2823 2825 2826 2827 2828 2829 2830 top/users/user[name="fred"] 2831 2832 2833 2835 9. Security Considerations 2837 This document does not specify an authorization scheme, as such a 2838 scheme should be tied to a meta-data model or a data model. 2839 Implementators SHOULD provide a well thought out authorization scheme 2840 with NETCONF. 2842 Authorization of individual users via the NETCONF server may or may 2843 not map 1:1 to other interfaces. First, the data models may be 2844 incompatible. Second, it may be desirable to authorize based on 2845 mechanisms available in the application protocol layer (TELNET, SSH, 2846 etc). 2848 In addition, operations on configurations may have unintended 2849 consequences if those operations are also not guarded by the global 2850 lock on the files or objects being operated upon. For instance, a 2851 partially complete access list could be committed from a candidate 2852 configuration unbeknownst to the owner of the lock of the candidate 2853 configuration, leading to either an insecure or inaccessible device 2854 if the lock on the candidate configuration does not also apply to the 2855 operation when applied to it. 2857 Configuration information is by its very nature sensitive. Its 2858 transmission in the clear and without integrity checking leaves 2859 devices open to classic eavesdropping attacks. Configuration 2860 information often times contains passwords, user names, service 2861 descriptions, and topological information, all of which are 2862 sensitive. Because of this, this protocol should be implemented 2863 carefully with adequate attention to all manner of attack one might 2864 expect to experience with other management interfaces. 2866 The protocol, therefore, must minimally support options for both 2867 privacy and authentication. It is anticipated that the underlying 2868 protocol (SSH, BEEP, etc) will provide for both privacy and 2869 authentication, as is required. It is further expected that the 2870 identity of each end of a NETCONF session will be available to the 2871 other in order to determine authorization for any given request. One 2872 could also easily envision additional information such as transport 2873 and encryption methods being made available for purposes of 2874 authorization. NETCONF itself provide no means to reauthenticate, 2875 much less authenticate. All such actions occur at lower layers. 2877 Different environments may well allow different rights prior to and 2878 then after authentication. Thus, an authorization model is not 2879 specified in this document. When an operation is not properly 2880 authorized then a simple "permission denied" is sufficient. Note 2881 that authorization information may be exchanged in the form of 2882 configuration information, which is all the more reason to ensure the 2883 security of the connection. 2885 That having been said, it is important to recognize that some 2886 operations are clearly more sensitive by nature than others. For 2887 instance, to the startup or running configurations is 2888 clearly not a normal provisioning operation, where-as 2889 is. Such global operations MUST disallow the changing of information 2890 that an individual does not have authorization to perform. For 2891 example, if a user A is not allowed to configure an IP address on an 2892 interface but user B has configured an IP address on an interface in 2893 the configuration, user A must not be allowed to commit 2894 the configuration. 2896 Similarly, just because someone says go write a configuration through 2897 the URL capability at a particular place does not mean that an 2898 element should do it without proper authorization. 2900 The operation will demonstrate that use of NETCONF is intended 2901 for use by systems that have at least some trust of the 2902 administrator. As specified in this document, it is possible to lock 2903 portions of a configuration that a principle might not otherwise have 2904 access to. After all, the entire configuration is locked. To 2905 mitigate this problem there are two approaches. It is possible to 2906 kill another NETCONF session programmatically from within NETCONF if 2907 one knows the session identifier of the offending session. The other 2908 possible way to break a lock is to provide an function within the 2909 device's native user interface. These two mechanisms suffer from a 2910 race condition that may be ameliorated by removing the offending user 2911 from an AAA server. However, such a solution is not useful in all 2912 deployment scenarios, such as those where SSH public/private key 2913 pairs are used. 2915 10. IANA Considerations 2917 TBD. 2919 11. Authors and Acknowledgements 2921 This document was written by: 2923 Andy Bierman, Cisco Systems 2925 Ken Crozier, Cisco Systems 2927 Rob Enns, Juniper Networks 2929 Ted Goddard, IceSoft 2931 Eliot Lear, Cisco Systems 2933 Phil Shafer, Juniper Networks 2935 Steve Waldbusser 2936 Margaret Wasserman, ThingMagic 2938 The authors would like to acknowledge the members of the NETCONF 2939 working group. In particular, we would like to thank Wes Hardaker 2940 for his persistance and patience in assisting us with security 2941 considerations. We would also like to thank Randy Presuhn, Sharon 2942 Chisolm, Juergen Schoenwalder, Glenn Waters, David Perkins, Weijing 2943 Chen, Simon Leinen, Keith Allen and Dave Harrington for all of their 2944 valuable advice. 2946 12. References 2948 12.1 Normative References 2950 [1] Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, 2951 "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C 2952 REC REC-xml-20001006, October 2000. 2954 [2] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 2955 1.0", W3C REC REC-xpath-19991116, November 1999. 2957 [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement 2958 Levels", BCP 14, RFC 2119, March 1997. 2960 [4] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2961 RFC 2246, January 1999. 2963 [5] Berners-Lee, T., "Universal Resource Identifiers in WWW: A 2964 Unifying Syntax for the Expression of Names and Addresses of 2965 Objects on the Network as used in the World-Wide Web", RFC 1630, 2966 June 1994. 2968 [6] Moats, R., "URN Syntax", RFC 2141, May 1997. 2970 [7] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote 2971 Authentication Dial In User Service (RADIUS)", RFC 2865, 2972 June 2000. 2974 [8] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF 2975 URN Sub-namespace for Registered Protocol Parameters", BCP 73, 2976 RFC 3553, June 2003. 2978 12.2 Informative References 2980 [9] Clark, J., "XSL Transformations (XSLT) Version 1.0", W3C 2981 REC REC-xslt-19991116, November 1999. 2983 [10] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T., and S. 2985 Lehtinen, "SSH Protocol Architecture", 2986 draft-ietf-secsh-architecture-15 (work in progress), 2987 October 2003. 2989 [11] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the 2990 Use of Extensible Markup Language (XML) within IETF Protocols", 2991 BCP 70, RFC 3470, January 2003. 2993 Author's Address 2995 Rob Enns (editor) 2996 Juniper Networks 2997 1194 North Mathilda Ave 2998 Sunnyvale, CA 94089 2999 US 3001 Email: rpe@juniper.net 3003 Appendix A. NETCONF Error List 3005 Tag: in-use 3006 Error-type: protocol, application 3007 Severity: error 3008 Error-info: none 3009 Description: The request requires a resource that already in use. 3011 Tag: invalid-value 3012 Error-type: protocol, application 3013 Severity: error 3014 Error-info: none 3015 Description: The request specifies an unacceptable value for one 3016 or more parameters. 3018 Tag: too-big 3019 Error-type: transport, rpc, protocol, application 3020 Severity: error 3021 Error-info: none 3022 Description: The request or response (that would be generated) is too 3023 large for the implementation to handle. 3025 Tag: missing-attribute 3026 Error-type: rpc, protocol, application 3027 Severity: error 3028 Error-info: : name of the missing attribute 3029 : name of the element that should 3030 contain the missing attribute 3031 Description: An expected attribute is missing 3032 Tag: bad-attribute 3033 Error-type: rpc, protocol, application 3034 Severity: error 3035 Error-info: : name of the attribute w/ bad value 3036 : name of the element that contains 3037 the attribute with the bad value 3038 Description: An attribute value is not correct; e.g., wrong type, 3039 out of range, pattern mismatch 3041 Tag: unknown-attribute 3042 Error-type: rpc, protocol, application 3043 Severity: error 3044 Error-info: : name of the unexpected attribute 3045 : name of the element that contains 3046 the unexpected attribute 3047 Description: An unexpected attribute is present 3049 Tag: missing-element 3050 Error-type: rpc, protocol, application 3051 Severity: error 3052 Error-info: : name of the missing element 3053 Description: An expected element is missing 3055 Tag: bad-element 3056 Error-type: rpc, protocol, application 3057 Severity: error 3058 Error-info: : name of the element w/ bad value 3059 Description: An element value is not correct; e.g., wrong type, 3060 out of range, pattern mismatch 3062 Tag: unknown-element 3063 Error-type: rpc, protocol, application 3064 Severity: error 3065 Error-info: : name of the unexpected element 3066 Description: An unexpected element is present 3068 Tag: unknown-namespace 3069 Error-type: rpc, protocol, application 3070 Severity: error 3071 Error-info: Name of the unexpected namespace 3072 Description: An unexpected namespace is present 3074 Tag: access-denied 3075 Error-type: rpc, protocol, application 3076 Severity: error 3077 Error-info: none 3078 Description: Access to the requested RPC, protocol operation, 3079 or application data model is denied because 3080 authorization failed 3082 Tag: lock-denied 3083 Error-type: protocol 3084 Severity: error 3085 Error-info: : session ID of session holding the 3086 requested lock, or zero to indicate a non-NETCONF 3087 entity holds the lock 3088 Description: Access to the requested lock is denied because the 3089 lock is currently held by another entity 3091 Tag: resource-denied 3092 Error-type: transport, rpc, protocol, application 3093 Severity: error 3094 Error-info: none 3095 Description: Request could not be completed because of insufficient 3096 resources 3098 Tag: rollback-failed 3099 Error-type: protocol, application 3100 Severity: error 3101 Error-info: none 3102 Description: Request to rollback some configuration change (via 3103 rollback-on-error or discard-changes operations) was 3104 not completed for some reason. 3106 Tag: data-exists 3107 Error-type: application 3108 Severity: error 3109 Error-info: none 3110 Description: Request could not be completed because the relevant 3111 data model content already exists. For example, 3112 a 'create' operation was attempted on data which 3113 already exists. 3115 Tag: data-missing 3116 Error-type: application 3117 Severity: error 3118 Error-info: none 3119 Description: Request could not be completed because the relevant 3120 data model content does not exist. For example, 3121 a 'modify' or 'delete' operation was attempted on 3122 data which does not exist. 3124 Tag: operation-not-supported 3125 Error-type: rpc, protocol, application 3126 Severity: error 3127 Error-info: none 3128 Description: Request could not be completed because the requested 3129 operation is not supported by this implementation. 3131 Tag: operation-failed 3132 Error-type: rpc, protocol, application 3133 Severity: error 3134 Error-info: none 3135 Description: Request could not be completed because the requested 3136 operation failed for some reason not covered by 3137 any other error condition. 3139 Tag: partial-operation 3140 Error-type: application 3141 Severity: error 3142 Error-info: : identifies an element in the data model 3143 for which the requested operation has been completed 3144 for that node and all its child nodes. This element 3145 can appear zero or more times in the 3146 container. 3148 : identifies an element in the data model 3149 for which the requested operation has failed for that 3150 node and all its child nodes. This element 3151 can appear zero or more times in the 3152 container. 3154 : identifies an element in the data model 3155 for which the requested operation was not attempted for 3156 that node and all its child nodes. This element 3157 can appear zero or more times in the 3158 container. 3160 Description: Some part of the requested operation failed or was 3161 not attempted for some reason. Full cleanup has 3162 not been performed (e.g., rollback not supported) 3163 by the server. The error-info container is used 3164 to identify which portions of the application 3165 data model content for which the requested operation 3166 has succeeded (), failed (), 3167 or not attempted (). 3169 Appendix B. XML Schema for NETCONF RPC and Protocol Operations 3171 3172 3178 3181 3183 3184 3185 This import accesses the xml: attribute groups for the 3186 xml:lang as declared on the error-message element. 3187 3188 3189 3190 3193 3194 3195 3196 3197 3198 3201 3202 3203 3204 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3251 3253 3255 3257 3259 3261 3262 3263 3264 3265 3266 3267 3268 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3288 3289 3290 3291 3292 3293 3294 3298 3299 3300 3301 3302 3304 3305 3306 3307 3308 3311 3312 3313 3314 3315 3316 3317 3320 3321 3322 3323 3324 Use of the rollback-on-error value requires 3325 the :rollback-on-error capability. 3326 3327 3328 3329 3330 3331 3332 3333 3337 3338 3340 3343 3344 3345 3346 3347 3348 3351 3352 3353 3354 3355 3356 3359 3360 3361 3362 3363 Use of the xpath value requires the :xpath capability. 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3375 3376 3377 3378 3381 3382 3383 The startup datastore can be used only if the :startup 3384 capability is advertised. The candidate datastore can 3385 be used only if the :candidate datastore is advertised. 3386 3387 3388 3389 3391 3393 3395 3397 3400 3401 3402 3403 3404 3405 3406 3407 3408 3410 3413 3414 3415 3416 3417 3418 3419 3420 3423 3424 3425 3426 Use of the url element requires the :url capability. 3427 3428 3429 3430 3431 3432 3433 3436 3437 3438 3439 3440 3441 3442 3443 3446 3447 3448 3449 3450 3451 3452 3455 3456 3457 3458 3459 3460 3461 3464 3465 3466 3467 3468 3470 3472 3473 3474 3475 3476 3478 3481 3482 3483 3484 3485 3486 3487 Use of the test-option element requires the 3488 :validate capability. Use of the url element 3489 requires the :url capability. 3490 3491 3492 3494 3497 3500 3503 3504 3506 3508 3509 3510 3512 3513 3514 3516 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3531 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3545 3548 3549 3550 3551 3552 3554 3555 3556 3557 3558 3561 3564 3565 3566 3567 3568 3570 3571 3572 3573 3574 3576 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3590 3593 3594 3595 3596 The validate operation requires the :validate capability. 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3610 3613 3614 3615 3616 The commit operation requires the :candidate capability. 3617 3618 3619 3620 3621 3622 3623 3624 Use of the confirmed and confirm-timeout elements 3625 requires the :confirmed-commit capability. 3626 3627 3628 3629 3632 3633 3634 3635 3636 3638 3641 3642 3643 3644 The discard-changes operation requires the 3645 :candidate capability. 3646 3647 3648 3649 3650 3651 3652 3655 3659 3660 3661 3662 3663 3664 3666 3669 3670 3671 3672 3673 3675 3676 3677 3678 3679 3681 3684 3685 3686 3687 3688 3689 3690 3692 3693 3694 3695 3697 3698 3699 3700 3702 Appendix C. Capability Template 3703 C.1 capability-name (template) 3705 C.1.1 Overview 3707 C.1.2 Dependencies 3709 C.1.3 Capability and Namespace 3711 The {name} is identified by following capability string: 3713 urn:ietf:params:xml:ns:netconf:capability:{name}:1.0 3715 C.1.4 New Operations 3717 C.1.4.1 3719 C.1.5 Modifications to Existing Operations 3721 C.1.5.1 3723 If existing operations are not modified by this capability, this 3724 section may be omitted. 3726 C.1.6 Interactions with Other Capabilities 3728 If this capability does not interact with other capabilities, this 3729 section may be omitted. 3731 Appendix D. Configuring Multiple Devices with NETCONF 3733 D.1 Operations on Individual Devices 3735 Consider the work involved in performing a configuration update 3736 against a single individual device. In making a change to the 3737 configuration, the application needs to build trust that its change 3738 has been made correctly and that it has not impacted the operation of 3739 the device. The application (and the application user) should feel 3740 confident that their change has not damaged the network. 3742 Protecting each individual device consists of a number of steps: 3744 o Acquiring the configuration lock. 3746 o Loading the update. 3748 o Validating the incoming configuration. 3750 o Checkpointing the running configuration. 3752 o Changing the running configuration. 3754 o Testing the new configuration. 3756 o Making the change permanent (if desired). 3758 o Releasing the configuration lock. 3760 Let's look at the details of each step. 3762 D.1.1 Acquiring the Configuration Lock 3764 A lock should be acquired to prevent simultaneous updates from 3765 multiple sources. If multiple sources are affecting the device, the 3766 application is hampered in both testing of its change to the 3767 configuration and in recovery should the update fail. Acquiring a 3768 short-lived lock is a simple defense to prevent other parties from 3769 introducing unrelated changes. 3771 The lock can be acquired using the operation. 3773 3775 3776 3777 3778 3779 3780 3782 D.1.2 Loading the Update 3784 The configuration can be loaded onto the device without impacting the 3785 running system. If the :url capability is supported, incoming 3786 changes can be placed in a local file. 3788 3790 3791 3792 3793 3794 3795 3796 3797 file://incoming.conf 3798 3799 3800 3802 If the :candidate capability is supported, the candidate 3803 configuration can be used. 3805 3807 3808 3809 3810 3811 3812 3813 3814 3815 3817 If the update fails, the user file can be deleted using the operation or the candidate configuration reverted using the 3819 operation. 3821 D.1.3 Validating the Incoming Configuration 3823 Before applying the incoming configuration, it is often useful to 3824 validate it. Validation allows the application to gain confidence 3825 that the change will succeed and simplifies recovery if it does not. 3827 If the device supports the :url capability, use the 3828 operation with the parameter set to the proper user file: 3830 3832 3833 3834 file://incoming.conf 3835 3836 3837 3839 If the device supports the :candidate capability, some validation 3840 will be performed as part of loading the incoming configuration into 3841 the candidate. For full validation, either pass the 3842 parameter during the step given above, or use the 3843 operation with the parameter set to . 3845 3847 3848 3849 3850 3851 3852 3854 D.1.4 Checkpointing the Running Configuration 3856 The running configuration can be saved into a local file as a 3857 checkpoint before loading the new configuration. If the update 3858 fails, the configuration can be restored by reloading the checkpoint 3859 file. 3861 The checkpoint file can be created using the operation. 3863 3865 3866 3867 3868 3869 3870 file://checkpoint.conf 3871 3872 3873 3875 To restore the checkpoint file, reverse the source and target 3876 parameters. 3878 D.1.5 Changing the Running Configuration 3880 When the incoming configuration has been safely loaded onto the 3881 device and validated, it is ready to impact the running system. 3883 If the device supports the :url capability, use the 3884 operation to merge the incoming configuration into the running 3885 configuration. 3887 3889 3890 3891 3892 3893 3894 file://incoming.conf 3895 3896 3897 3899 If the device supports the :candidate capability, use the 3900 operation to set the running configuration to the candidate 3901 configuration. Use the parameter to allow automatic 3902 reverting to the original configuration if connectivity to the device 3903 fails. 3905 3907 3908 3909 120 3910 3911 3913 D.1.6 Testing the New Configuration 3915 Now that the incoming configuration has been integrated into the 3916 running configuration, the application needs to gain trust that the 3917 change has affected the device in the way intended without affecting 3918 it negatively. 3920 To gain this confidence, the application can run tests of the 3921 operational state of the device. The nature of the test is dependent 3922 on the nature of the change and is outside the scope of this 3923 document. Such tests may include reachability from the system 3924 running the application (using ping), changes in reachability to the 3925 rest of the network (by comparing the device's routing table), or 3926 inspection of the particular change (looking for operational evidence 3927 of the BGP peer that was just added). 3929 D.1.7 Making the Change Permanent 3931 When the configuration change is in place and the application has 3932 sufficient faith in the proper function of this change, the 3933 application should make the change permanent. 3935 If the device supports the :startup capability, the current 3936 configuration can be saved to the startup configuration by using the 3937 startup configuration as the target of the operation. 3939 3941 3942 3943 3944 3945 3946 3947 3948 3949 3951 If the device supports the :candidate capability and a confirmed 3952 commit was requested, the confirming commit must be sent before the 3953 timeout expires. 3955 3957 3958 3960 D.1.8 Releasing the Configuration Lock 3962 When the configuration update is complete, the lock must be released, 3963 allowing other applications access to the configuration. 3965 Use the operation to release the configuration lock. 3967 3969 3970 3971 3972 3973 3974 3976 D.2 Operations on Multiple Devices 3978 When a configuration change requires updates across a number of 3979 devices, care should be taken to provide the required transaction 3980 semantics. The NETCONF protocol contains sufficient primitives upon 3981 which transaction-oriented operations can be built. Providing 3982 complete transactional semantics across multiple devices is 3983 prohibitively expensive, but the size and number of windows for 3984 failure scenarios can be reduced. 3986 There are two classes of multidevice operations. The first class 3987 allows the operation to fail on individual devices without requiring 3988 all devices to revert to their original state. The operation can be 3989 retried at a later time, or its failure simply reported to the user. 3990 A example of this class might be adding an NTP server. For this 3991 class of operations, failure avoidance and recovery are focused on 3992 the individual device. This means recovery of the device, reporting 3993 the failure, and perhaps scheduling another attempt. 3995 The second class is more interesting, requiring that the operation 3996 should complete on all devices or be fully reversed. The network 3997 should either be transformed into a new state or be reset to its 3998 original state. For example, a change to a VPN may require updates 3999 to a number of devices. Another example of this might be adding a 4000 class-of-service definition. Leaving the network in a state where 4001 only a portion of the devices have been updated with the new 4002 definition will lead to future failures when the definition is 4003 referenced. 4005 To give transactional semantics, the same steps used in single device 4006 operations listed above are used, but are performed in parallel 4007 across all devices. Configuration locks should be acquired on all 4008 target devices and kept until all devices are updated and the changes 4009 made permanent. Configuration changes should be uploaded and 4010 validation performed across all devices. Checkpoints should be made 4011 on each device. Then the running configuration can be changed, 4012 tested, and made permanent. If any of these steps fail, the previous 4013 configurations can be restored on any devices upon which it was 4014 changed. After the changes have been completely implemented or 4015 completely discarded, the locks on each device can be released. 4017 Appendix E. Deferred Features 4019 The following features have been deferred until a future revision of 4020 this document. 4022 o Granular locking of configuration objects. 4024 o Named configuration files/datastores. 4026 o Support for multiple NETCONF channels. 4028 o Asynchronous notifications. 4030 o Explicit protocol support for rollback of configuration changes to 4031 prior versions. 4033 Appendix F. Change Log 4035 RFC Editor: Please remove this section before RFC publication. 4037 F.1 draft-ietf-netconf-prot-07 4039 o Add clarifying text to :confirmed-commit capability. 4041 o Change units of 'confirm-timeout' parameter to seconds. 4043 o Type confirm-timeout element as a positiveInteger in the XSD. 4045 o Update XSD to allow element in as required by 4046 :url capability. 4048 o Denote attribute names with single quotes in the text; some cases 4049 were missed. 4051 o Update to state that the server must not return data 4052 that the client has no access rights on. 4054 o [XMLDir] Moderate use of the term API. 4056 o [XMLDir] Clarify capability naming requirements in Section 3.1. 4058 o [XMLDir] Remove "DTD" acronym from Section 3.2. 4060 o [XMLDir] Remove # naming scheme from capability URNs. 4062 o Error code when a lock is in use is 'lock-denied'. 4064 F.2 draft-ietf-netconf-prot-06 4066 o Allow an xml:lang attribute in the tag. 4068 o Update XSD to permit artibrary attributes on and . 4071 o Add example showing retrieval of textual configuration to . 4074 o Indicate that URLs passed to should be local. 4076 o Update example to use https. 4078 o Update description to explicitly allow multiple elements. Add example. Update XSD. 4081 o Incorporate clarifying text on subtree filtering. 4083 o Annotate XSD with capability information. 4085 o Make error tags lower case separated with dashes. 4087 o Add unknown-namespace error tag. 4089 o Add text expliticly stating that a server must discontinue the 4090 NETCONF session if it receives a element, and 4091 similarly a client must discontinue if it does not receive one. 4093 F.3 draft-ietf-netconf-prot-05 4095 o Change XPATH to XPath. 4097 o Fix I-D nits (mostly long lines). 4099 o Remove "--" from XSD comments. 4101 o Add attribute where it was missing in 4102 examples. 4104 o Clarified Section 8.1 by indicating that each peer MUST send a 4105 element at session startup. 4107 o Typo propriety -> proprietary in Section 8. 4109 o Fix some bugs in examples. 4111 o Section 7.1: typo: change to in the positive 4112 response section. 4114 o Section 7.1: If is unspecified, the entire configuration 4115 is returned. If it is empty, nothing is returned. 4117 o Be explicit about being atomic. 4119 o s/MAY/SHOULD/ wrt supporting more than one NETCONF session. 4121 o Strengthen language to say that NETCONF requests MUST be processed 4122 serially. 4124 o Fix misspelling of "unbeknownst." 4126 o Change "Expect scripts" to "CLI scripts" in Section 7.5. 4128 o Change "system software" to "device" in Section 1.3. 4130 o The element must also include the session ID (issue I002). 4132 o Address all accepted clarifications from working group last call. 4133 See the NETCONF mailing list for details. 4135 o Address all closed issues from working group last call. See the 4136 NETCONF mailing list for details. 4138 F.4 draft-ietf-netconf-prot-04 4140 Refer to the NETCONF issue list for futher detail on the issue 4141 numbers below. The issue list is found at 4142 http://www.nextbeacon.com/netconf/. 4144 o Update security considerations (action from IETF 60). 4146 o Add type attribute on filter element (issue 14.1). 4148 o Add #xpath capability (issue 14.1). 4150 o for returns element, not 4151 element (issue 14.1). 4153 o Add detailed description of subtree filtering (issue 14.1.2). 4155 o Typo: change confirmed-timeout -> confirm-timeout in XSD. 4157 o Typo: correct misnaming of test-option parameter in text for the 4158 validate capability. 4160 o is now a mandatory parameter for and . 4161 There is no default target (action from IETF 60). 4163 o Remove XML schema for NETCONF state data (action from IETF 60). 4165 o Correct namespace handling a number of examples. The fix is to 4166 put the device's configuration under a top level tag called 4167 which is in the device's namespace. 4169 o Use message-id 101 everywhere. 4171 o Add default-operation parameter to (action from IETF 4172 60). 4174 o Fix examples in Appendix D. 4176 o Update and reformat protocol XSD. 4178 o Remove XML usage guidelines. Add a section on XML considerations 4179 covering the NETCONF namespace and no DTD restriction (action from 4180 IETF 60). 4182 F.5 draft-ietf-netconf-prot-03 4184 Refer to the NETCONF issue list for futher detail on the issue 4185 numbers below. The issue list is found at 4186 http://www.nextbeacon.com/netconf/. 4188 o Consistent naming of element. 4190 o Add #confirmed-commit capability (issue 10.3.2) 4192 o Use a URN for the NETCONF namespace (issue 11.1.2) and 4193 capabilities 4195 o Remove #manager capability (issue 11.2.1) 4197 o Remove #agent capability (issue 11.2.2) 4198 o Add "create" as a value for the operation attribute in (issue 13.3.1) 4201 o Add #rollback-on-error capability (issue 13.3.2) 4203 o Rename operation to . 4205 o Remove format parameter from two and one 4206 examples missed in the -02 draft (issue 13.3.3). 4208 o Add text indicating that the session-id is returned if the lock is 4209 already held (issue 13.12.3). Add example of this. 4211 o Remove parameter on the operation (issue 4212 13.16.1), all outstanding changes are to be discarded when the 4213 candidate configuration is unlocked. 4215 o Remove section 8.7, guidelines on namespace construction. 4217 o Add clarifying text regarding locks held by other entities. 4219 o Update the abstract. 4221 o Remove mention of the format parameter from the and 4222 operations and the XSD. 4224 o Updated security considerations section. 4226 o Removed terminology section, moved session description to protocol 4227 overview section. 4229 o New text describing . 4231 o Updated NETCONF protocol schema (to reflect new 4232 details, among other things). 4234 o Add parameter to and . Rename 4235 response the operation to . 4237 o Better description of the operation. 4239 o Add operation. 4241 o Removed format parameter to . 4243 o Removed restriction that a changed configuration 4244 datastore can't be locked. 4246 o Add note in section 2 that the application protocol must provide 4247 an indication of session type (manager or agent) to the NETCONF 4248 layer. 4250 F.6 draft-ietf-netconf-prot-02 4252 Refer to the NETCONF issue list for futher detail on the issue 4253 numbers below. The issue list is found at 4254 http://www.nextbeacon.com/netconf/. 4256 o Remove , , and (issues 4257 12.1, 12.2, 12.3). 4259 o Remove channels (issues 3.*). 4261 o Remove notifications (issues 2.*, 4.2, 13.9, 13.10, 13.11). 4263 o Move version number to last component of the capability URI (issue 4264 11.1.1). 4266 o Remove format parameter from (issue 13.3.3). 4268 o Remove mention of #lock capability from Appendix D. Locking is a 4269 mandatory NETCONF operation. 4271 o Added text indicating that attributes received in should be 4272 echoed on (issue 16.1). 4274 o Reworded Section 7.3 to encourage always prefixing attributes with 4275 namespaces. 4277 Intellectual Property Statement 4279 The IETF takes no position regarding the validity or scope of any 4280 Intellectual Property Rights or other rights that might be claimed to 4281 pertain to the implementation or use of the technology described in 4282 this document or the extent to which any license under such rights 4283 might or might not be available; nor does it represent that it has 4284 made any independent effort to identify any such rights. Information 4285 on the procedures with respect to rights in RFC documents can be 4286 found in BCP 78 and BCP 79. 4288 Copies of IPR disclosures made to the IETF Secretariat and any 4289 assurances of licenses to be made available, or the result of an 4290 attempt made to obtain a general license or permission for the use of 4291 such proprietary rights by implementers or users of this 4292 specification can be obtained from the IETF on-line IPR repository at 4293 http://www.ietf.org/ipr. 4295 The IETF invites any interested party to bring to its attention any 4296 copyrights, patents or patent applications, or other proprietary 4297 rights that may cover technology that may be required to implement 4298 this standard. Please address the information to the IETF at 4299 ietf-ipr@ietf.org. 4301 Disclaimer of Validity 4303 This document and the information contained herein are provided on an 4304 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4305 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 4306 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 4307 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 4308 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4309 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4311 Copyright Statement 4313 Copyright (C) The Internet Society (2005). This document is subject 4314 to the rights, licenses and restrictions contained in BCP 78, and 4315 except as set forth therein, the authors retain all their rights. 4317 Acknowledgment 4319 Funding for the RFC Editor function is currently provided by the 4320 Internet Society.