idnits 2.17.1 draft-ietf-netconf-prot-12.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 4645. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4622. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4629. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4635. ** 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 : ---------------------------------------------------------------------------- -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? 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 (February 2006) is 6638 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 4385 -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' == Outdated reference: A later version (-06) exists of draft-ietf-netconf-ssh-04 -- Obsolete informational reference (is this intentional?): RFC 2246 (ref. '9') (Obsoleted by RFC 4346) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 12 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: August 5, 2006 February 2006 6 NETCONF Configuration Protocol 7 draft-ietf-netconf-prot-12 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 August 5, 2006. 34 Copyright Notice 36 Copyright (C) The Internet Society (2006). 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 . . . . . . . . . . . . . . . . . . . . . . . . 6 53 1.1. Protocol Overview . . . . . . . . . . . . . . . . . . . . 7 54 1.2. Capabilities . . . . . . . . . . . . . . . . . . . . . . 8 55 1.3. Separation of Configuration and State Data . . . . . . . 8 56 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 9 57 2.1. Connection-oriented operation . . . . . . . . . . . . . . 10 58 2.2. Authentication, Integrity, and Confidentiality . . . . . 10 59 2.3. Authentication . . . . . . . . . . . . . . . . . . . . . 10 60 2.4. Mandatory Transport Protocol . . . . . . . . . . . . . . 11 61 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 11 62 3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 11 63 3.2. No Document Type Declarations . . . . . . . . . . . . . . 11 64 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 4.1. Element . . . . . . . . . . . . . . . . . . . . . . 11 66 4.2. Element . . . . . . . . . . . . . . . . . . . 12 67 4.3. Element . . . . . . . . . . . . . . . . . . . 13 68 4.4. Element . . . . . . . . . . . . . . . . . . . . . . 16 69 4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 17 70 5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 17 71 5.1. Configuration Datastores . . . . . . . . . . . . . . . . 17 72 5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 17 73 6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 18 74 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18 75 6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 19 76 6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 19 77 6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 20 78 6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 20 79 6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 21 80 6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 21 81 6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 23 82 6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 23 83 6.4.1. No filter . . . . . . . . . . . . . . . . . . . . . . 23 84 6.4.2. Empty filter . . . . . . . . . . . . . . . . . . . . 24 85 6.4.3. Select the entire subtree . . . . . . . . . . 24 86 6.4.4. Select all elements within the 87 subtree . . . . . . . . . . . . . . . . . . . . . . . 26 88 6.4.5. One specific entry . . . . . . . . . . . . . . 27 89 6.4.6. Specific elements from a specific entry . . . 28 90 6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 29 91 6.4.8. Elements with attribute naming . . . . . . . . . . . 31 92 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 33 93 7.1. . . . . . . . . . . . . . . . . . . . . . . 33 94 7.2. . . . . . . . . . . . . . . . . . . . . . . 36 95 7.3. . . . . . . . . . . . . . . . . . . . . . . 43 96 7.4. . . . . . . . . . . . . . . . . . . . . . 45 97 7.5. . . . . . . . . . . . . . . . . . . . . . . . . . 45 98 7.6. . . . . . . . . . . . . . . . . . . . . . . . . 48 99 7.7. . . . . . . . . . . . . . . . . . . . . . . . . . . 49 100 7.8. . . . . . . . . . . . . . . . . . . . . . 51 101 7.9. . . . . . . . . . . . . . . . . . . . . . 52 102 8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 53 103 8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 54 104 8.2. Writable-Running Capability . . . . . . . . . . . . . . . 54 105 8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 55 106 8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 55 107 8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 55 108 8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 55 109 8.2.5. Modifications to Existing Operations . . . . . . . . 55 110 8.3. Candidate Configuration Capability . . . . . . . . . . . 55 111 8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 55 112 8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 56 113 8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 56 114 8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 56 115 8.3.5. Modifications to Existing Operations . . . . . . . . 58 116 8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 59 117 8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 59 118 8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 59 119 8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 60 120 8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 60 121 8.4.5. Modifications to Existing Operations . . . . . . . . 60 122 8.5. Rollback on Error Capability . . . . . . . . . . . . . . 60 123 8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 61 124 8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 61 125 8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 61 126 8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 61 127 8.5.5. Modifications to Existing Operations . . . . . . . . 61 128 8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 62 129 8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 62 130 8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 62 131 8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 62 132 8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 63 133 8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 64 134 8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 64 135 8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 64 136 8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 64 137 8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 64 138 8.7.5. Modifications to Existing Operations . . . . . . . . 64 139 8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 65 140 8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 65 141 8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65 142 8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 65 143 8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 66 144 8.8.5. Modifications to Existing Operations . . . . . . . . 66 145 8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 66 146 8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 66 147 8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 67 148 8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 67 149 8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 67 150 8.9.5. Modifications to Existing Operations . . . . . . . . 67 151 9. Security Considerations . . . . . . . . . . . . . . . . . . . 67 152 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 153 10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 69 154 10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 69 155 10.3. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 70 156 11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 71 157 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 158 12.1. Normative References . . . . . . . . . . . . . . . . . . 71 159 12.2. Informative References . . . . . . . . . . . . . . . . . 72 160 Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 72 161 Appendix B. XML Schema for NETCONF RPC and Protocol Operations . 76 162 Appendix C. Capability Template . . . . . . . . . . . . . . . . 88 163 C.1. capability-name (template) . . . . . . . . . . . . . . . 88 164 C.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 88 165 C.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 88 166 C.1.3. Capability Identifier . . . . . . . . . . . . . . . . 88 167 C.1.4. New Operations . . . . . . . . . . . . . . . . . . . 88 168 C.1.5. Modifications to Existing Operations . . . . . . . . 88 169 C.1.6. Interactions with Other Capabilities . . . . . . . . 88 170 Appendix D. Configuring Multiple Devices with NETCONF . . . . . 88 171 D.1. Operations on Individual Devices . . . . . . . . . . . . 88 172 D.1.1. Acquiring the Configuration Lock . . . . . . . . . . 89 173 D.1.2. Loading the Update . . . . . . . . . . . . . . . . . 89 174 D.1.3. Validating the Incoming Configuration . . . . . . . . 90 175 D.1.4. Checkpointing the Running Configuration . . . . . . . 91 176 D.1.5. Changing the Running Configuration . . . . . . . . . 92 177 D.1.6. Testing the New Configuration . . . . . . . . . . . . 92 178 D.1.7. Making the Change Permanent . . . . . . . . . . . . . 93 179 D.1.8. Releasing the Configuration Lock . . . . . . . . . . 93 180 D.2. Operations on Multiple Devices . . . . . . . . . . . . . 94 181 Appendix E. Deferred Features . . . . . . . . . . . . . . . . . 94 182 Appendix F. Change Log . . . . . . . . . . . . . . . . . . . . . 95 183 F.1. draft-ietf-netconf-prot-12 . . . . . . . . . . . . . . . 95 184 F.2. draft-ietf-netconf-prot-11 . . . . . . . . . . . . . . . 95 185 F.3. draft-ietf-netconf-prot-10 . . . . . . . . . . . . . . . 96 186 F.4. draft-ietf-netconf-prot-09 . . . . . . . . . . . . . . . 97 187 F.5. draft-ietf-netconf-prot-08 . . . . . . . . . . . . . . . 97 188 F.6. draft-ietf-netconf-prot-07 . . . . . . . . . . . . . . . 98 189 F.7. draft-ietf-netconf-prot-06 . . . . . . . . . . . . . . . 98 190 F.8. draft-ietf-netconf-prot-05 . . . . . . . . . . . . . . . 99 191 F.9. draft-ietf-netconf-prot-04 . . . . . . . . . . . . . . . 100 192 F.10. draft-ietf-netconf-prot-03 . . . . . . . . . . . . . . . 101 193 F.11. draft-ietf-netconf-prot-02 . . . . . . . . . . . . . . . 102 195 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 104 196 Intellectual Property and Copyright Statements . . . . . . . . . 105 198 1. Introduction 200 The NETCONF protocol defines a simple mechanism through which a 201 network device can be managed, configuration data information can be 202 retrieved, and new configuration data can be uploaded and 203 manipulated. The protocol allows the device to expose a full, 204 formal, application programming interface (API). Applications can 205 use this straight-forward API to send and receive full and partial 206 configuration data sets. 208 The NETCONF protocol uses a remote procedure call (RPC) paradigm. A 209 client encodes an RPC in XML [1] and sends it to a server using a 210 secure, connection-oriented session. The server responds with a 211 reply encoded in XML. The contents of both the request and the 212 response are fully described in XML DTDs or XML schemas, or both, 213 allowing both parties to recognize the syntax constraints imposed on 214 the exchange. 216 A key aspect of NETCONF is that it allows the functionality of the 217 management protocol to closely mirror the native functionality of the 218 device. This reduces implementation costs and allows timely access 219 to new features. In addition, applications can access both the 220 syntactic and semantic content of the device's native user interface. 222 NETCONF allows a client to discover the set of protocol extensions 223 supported by a server. These "capabilities" permit the client to 224 adjust its behavior to take advantage of the features exposed by the 225 device. The capability definitions can be easily extended in a 226 noncentralized manner. Standard and non-standard capabilities can be 227 defined with semantic and syntactic rigor. Capabilities are 228 discussed in Section 8. 230 The NETCONF protocol is a building block in a system of automated 231 configuration. XML is the lingua franca of interchange, providing a 232 flexible but fully specified encoding mechanism for hierarchical 233 content. NETCONF can be used in concert with XML-based 234 transformation technologies such as XSLT [8] to provide a system for 235 automated generation of full and partial configurations. The system 236 can query one or more databases for data about networking topologies, 237 links, policies, customers, and services. This data can be 238 transformed using one or more XSLT scripts from a task-oriented, 239 vendor-independent data schema into a form that is specific to the 240 vendor, product, operating system, and software release. The 241 resulting data can be passed to the device using the NETCONF 242 protocol. 244 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 245 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 246 document are to be interpreted as described in RFC 2119 [3]. 248 1.1. Protocol Overview 250 NETCONF uses a simple RPC-based mechanism to facilitate communication 251 between a client and a server. The client can be a script or 252 application typically running as part of a network manager. The 253 server is typically a network device. The terms "device" and 254 "server" are used interchangeably in this document, as are "client" 255 and "application". 257 A NETCONF session is the logical connection between a network 258 administrator or network configuration application and a network 259 device. A device MUST support at least one NETCONF session, and 260 SHOULD support multiple sessions. Global configuration attributes 261 can be changed during any authorized session, and the effects are 262 visible in all sessions. Session-specific attributes affect only the 263 session in which they are changed. 265 NETCONF can be conceptually partitioned into four layers: 267 Layer Example 268 +-------------+ +-----------------------------+ 269 (4) | Content | | Configuration data | 270 +-------------+ +-----------------------------+ 271 | | 272 +-------------+ +-----------------------------+ 273 (3) | Operations | | , | 274 +-------------+ +-----------------------------+ 275 | | 276 +-------------+ +-----------------------------+ 277 (2) | RPC | | , | 278 +-------------+ +-----------------------------+ 279 | | 280 +-------------+ +-----------------------------+ 281 (1) | Transport | | BEEP, SSH, SSL, console | 282 | Protocol | | | 283 +-------------+ +-----------------------------+ 285 1. The transport protocol layer provides a communication path 286 between the client and server. NETCONF can be layered over any 287 transport protocol that provides a set of basic requirements. 288 Section 2 discusses these requirements. 290 2. The RPC layer provides a simple, transport-independent framing 291 mechanism for encoding RPCs. Section 4 documents this protocol. 293 3. The operations layer defines a set of base operations invoked as 294 RPC methods with XML-encoded parameters. Section 7 details the 295 list of base operations. 297 4. The content layer is outside the scope of this document. Given 298 the current proprietary nature of the configuration data being 299 manipulated, the specification of this content depends on the 300 NETCONF implementation. It is expected that a separate effort to 301 specify a standard data definition language and standard content 302 will be undertaken. 304 1.2. Capabilities 306 A NETCONF capability is a set of functionality that supplements the 307 base NETCONF specification. The capability is identified by a 308 uniform resource identifier (URI). These URIs should follow the 309 guidelines as described in Section 8. 311 Capabilities augment the base operations of the device, describing 312 both additional operations and the content allowed inside operations. 313 The client can discover the server's capabilities and use any 314 additional operations, parameters, and content defined by those 315 capabilities. 317 The capability definition may name one or more dependent 318 capabilities. To support a capability, the server MUST support any 319 capabilities upon which it depends. 321 Section 8 defines the capabilities exchange that allows the client to 322 discover the server's capabilities. Section 8 also lists the set of 323 capabilities defined in this document. 325 Additional capabilities can be defined at any time in external 326 documents, allowing the set of capabilities to expand over time. 327 Standards bodies may define standardized capabilities and 328 implementations may define proprietary ones. A capability URI MUST 329 sufficiently distinguish the naming authority to avoid naming 330 collisions. 332 1.3. Separation of Configuration and State Data 334 The information that can be retrieved from a running system is 335 separated into two classes, configuration data and state data. 336 Configuration data is the set of writable data that is required to 337 transform a system from its initial default state into its current 338 state. State data is the additional data on a system that is not 339 configuration data such as read-only status information and collected 340 statistics. When a device is performing configuration operations a 341 number of problems would arise if state data were included: 343 o Comparisons of configuration data sets would be dominated by 344 irrelevant entries such as different statistics. 346 o Incoming data could contain nonsensical requests, such as attempts 347 to write read-only data. 349 o The data sets would be large. 351 o Archived data could contain values for read-only data items, 352 complicating the processing required to restore archived data. 354 To account for these issues, the NETCONF protocol recognizes the 355 difference between configuration data and state data and provides 356 operations for each. The operation retrieves 357 configuration data only while the operation retrieves 358 configuration and state data. 360 Note that the NETCONF protocol is focused on the information required 361 to get the device into its desired running state. The inclusion of 362 other important, persistent data is implementation specific. For 363 example, user files and databases are not treated as configuration 364 data by the NETCONF protocol. 366 If a local database of user authentication data is stored on the 367 device, whether it is included in configuration data is an 368 implementation dependent matter. 370 2. Transport Protocol Requirements 372 NETCONF uses an RPC-based communication paradigm. A client sends a 373 series of one or more RPC request operations, which cause the server 374 to respond with a corresponding series of RPC replies. 376 The NETCONF protocol can be layered on any transport protocol that 377 provides the required set of functionality. It is not bound to any 378 particular transport protocol, but allows a mapping to define how it 379 can be implemented over any specific protocol. 381 The transport protocol MUST provide a mechanism to indicate the 382 session type (client or server) to the NETCONF protocol layer. 384 This section details the characteristics that NETCONF requires from 385 the underlying transport protocol. 387 2.1. Connection-oriented operation 389 NETCONF is connection-oriented, requiring a persistent connection 390 between peers. This connection must provide reliable, sequenced data 391 delivery. 393 NETCONF connections are long-lived, persisting between protocol 394 operations. This allows the client to make changes to the state of 395 the connection that will persist for the lifetime of the connection. 396 For example, authentication information specified for a connection 397 remains in effect until the connection is closed. 399 In addition, resources requested from the server for a particular 400 connection MUST be automatically released when the connection closes, 401 making failure recovery simpler and more robust. For example, when a 402 lock is acquired by a client, the lock persists until either 403 explicitly released or the server determines that the connection has 404 been terminated. If a connection is terminated while the client 405 holds a lock, the server can perform any appropriate recovery. The 406 lock operation is further discussed in Section 7.5. 408 2.2. Authentication, Integrity, and Confidentiality 410 NETCONF connections must provide authentication, data integrity, and 411 confidentiality. NETCONF depends on the transport protocol for this 412 capability. A NETCONF peer assumes that an appropriate level of 413 security and confidentiality are provided independent of this 414 document. For example, connections may be encrypted in TLS [9] or 415 SSH [10], depending on the underlying protocol. 417 2.3. Authentication 419 NETCONF connections must be authenticated. The transport protocol is 420 responsible for authentication. The peer assumes that the 421 connection's authentication information has been validated by the 422 underlying protocol using sufficiently trustworthy mechanisms and 423 that the peer's identity has been sufficiently proven. 425 One goal of NETCONF is to provide a programmatic interface to the 426 device that closely follows the functionality of the device's native 427 interface. Therefore, it is expected that the underlying protocol 428 uses existing authentication mechanisms defined by the device. For 429 example, a device that supports RADIUS [11] should allow the use of 430 RADIUS to authenticate NETCONF sessions. 432 The authentication process should result in an identity whose 433 permissions are known to the device. These permissions MUST be 434 enforced during the remainder of the NETCONF session. 436 2.4. Mandatory Transport Protocol 438 A NETCONF implementation MUST support the SSH transport protocol 439 mapping [4]. 441 3. XML Considerations 443 XML serves as the encoding format for NETCONF, allowing complex 444 hierarchical data to be expressed in a text format that can be read, 445 saved, and manipulated with both traditional text tools and tools 446 specific to XML. 448 This section discusses a small number of XML-related considerations 449 pertaining to NETCONF. 451 3.1. Namespace 453 All NETCONF protocol elements are defined in the following namespace: 455 urn:ietf:params:xml:ns:netconf:base:1.0 457 NETCONF capability names MUST be URIs [5]. NETCONF capabilities are 458 discussed in Section 8. 460 3.2. No Document Type Declarations 462 Document type declarations MUST NOT appear in NETCONF content. 464 4. RPC Model 466 The NETCONF protocol uses an RPC-based communication model. NETCONF 467 peers use and elements to provide transport 468 protocol-independent framing of NETCONF requests and responses. 470 4.1. Element 472 The element is used to enclose a NETCONF request sent from the 473 client to the server. 475 The element has a mandatory attribute "message-id", which is an 476 arbitrary string chosen by the sender of the RPC that will commonly 477 encode a monotonically increasing integer. The receiver of the RPC 478 does not decode or interpret this string but simply saves it to use 479 as a "message-id" attribute in any resulting message. 480 For example: 482 484 485 486 487 489 If additional attributes are present in an element, a NETCONF 490 peer MUST return them unmodified in the element. 492 The name and parameters of an RPC are encoded as the contents of the 493 element. The name of the RPC is an element directly inside the 494 element, and any parameters are encoded inside this element. 496 The following example invokes a method called which 497 has two parameters, , with a value of "14", and 498 , with a value of "fred": 500 502 503 14 504 fred 505 506 508 The following example invokes a method with a parameter of "27606-0100": 511 513 514 27606-0100 515 516 518 The following example invokes the NETCONF method with no 519 parameters: 521 523 524 526 4.2. Element 528 The message is sent in response to a operation. 530 The element has a mandatory attribute "message-id", which 531 is equal to the "message-id" attribute of the for which this is 532 a response. 534 A NETCONF peer MUST also return any additional attributes included in 535 the element unmodified in the element. 537 The response name and response data are encoded as the contents of 538 the element. The name of the reply is an element 539 directly inside the element, and any data is encoded 540 inside this element. 542 For example: 544 The following element invokes the NETCONF method and 545 includes an additional attribute called "user-id". Note that the 546 "user-id" attribute is not in the NETCONF namespace. The returned 547 element returns the "user-id" attribute, as well as the 548 requested content. 550 554 555 557 561 562 563 564 566 4.3. Element 568 The element is sent in messages if an error 569 occurs during the processing of an request. 571 If a server encounters multiple errors during the processing of an 572 request, the MAY contain multiple 573 elements. However, a server is not required to detect or report more 574 than one element, if a request contains multiple errors. 575 A server is not required to check for particular error conditions in 576 a specific sequence. A server MUST return an element if 577 any error conditions occur during processing, and SHOULD return an 578 element if any warning conditions occur during 579 processing. 581 A server MUST NOT return application level or data model-specific 582 error information in an element for which the client does 583 not have sufficient access rights. 585 The element includes the following information: 587 error-type: Defines the conceptual layer that the error occurred. 588 Enumeration. One of: 590 * transport 592 * rpc 594 * protocol 596 * application 598 error-tag: Contains a string identifying the error condition. See 599 Appendix A for allowed values. 601 error-severity: Contains a string identifying the error severity, as 602 determined by the device. One of: 604 * error 606 * warning 608 error-app-tag: Contains a string identifying the data model-specific 609 or implementation-specific error condition, if one exists. This 610 element will not be present if no appropriate application error 611 tag can be associated with a particular error condition. 613 error-path: Contains the absolute XPath [2] expression identifying 614 the element path to the node which is associated with the error 615 being reported in a particular rpc-error element. This element 616 will not be present if no appropriate payload element can be 617 associated with a particular error condition, or if the 'bad- 618 element' QString returned in the 'error-info' container is 619 sufficient to identify the node associated with the error. When 620 the XPath expression is interpreted, the set of namespace 621 declarations are those in scope on the rpc-error element, 622 including the default namespace. 624 error-message: Contains a string suitable for human display which 625 describes the error condition. This element will not be present 626 if no appropriate message is provided for a particular error 627 condition. This element SHOULD include an xml:lang attribute as 628 defined in [1] and discussed in [12]. 630 error-info: Contains protocol-or data model-specific error content. 631 This element will not be present if no such error content is 632 provided for a particular error condition. The list in Appendix A 633 defines any mandatory error-info content for each error. After 634 any protocol-mandated content, a data model definition may mandate 635 certain application layer error information be included in the 636 error-info container. An implementation may include additional 637 elements to provide extended and/or implementation-specific 638 debugging information. 640 Appendix A enumerates the standard NETCONF errors. 642 Example: 644 An error is returned if an element is received without a 645 message-id attribute. Note that only in this case is it 646 acceptable for the NETCONF peer to omit the message-id attribute 647 in the element. 649 650 651 652 653 654 655 657 658 659 rpc 660 missing-attribute 661 error 662 663 message-id 664 rpc 665 666 667 668 The following illustrates the case of returning 669 multiple elements. 671 674 675 application 676 invalid-value 677 error 678 679 MTU value 25000 is not within range 256..9192 680 681 682 683 684 Ethernet0/0 685 25000 686 687 688 689 690 691 application 692 invalid-value 693 error 694 695 Invalid IP address for interface Ethernet1/0 696 697 698 699 700 Ethernet1/0 701
702 1.4 703 24 704
705 706 707 708 709 711 4.4. Element 713 The element is sent in messages if no errors or 714 warnings occurred during the processing of an request. For 715 example: 717 719 720 722 4.5. Pipelining 724 NETCONF requests MUST be processed serially by the managed 725 device. Additional requests MAY be sent before previous ones 726 have been completed. The managed device MUST send responses only in 727 the order the requests were received. 729 5. Configuration Model 731 NETCONF provides an initial set of operations and a number of 732 capabilities that can be used to extend the base. NETCONF peers 733 exchange device capabilities when the session is initiated as 734 described in Section 8.1. 736 5.1. Configuration Datastores 738 NETCONF defines the existence of one or more configuration datastores 739 and allows configuration operations on them. A configuration 740 datastore is defined as the complete set of configuration data that 741 is required to get a device from its initial default state into a 742 desired operational state. The configuration datastore does not 743 include state data or executive commands. 745 Only the configuration datastore is present in the base 746 model. Additional configuration datastores may be defined by 747 capabilities. Such configuration datastores are available only on 748 devices that advertise the capabilities. 750 o Running: The complete configuration currently active on the 751 network device. Only one configuration datastore of this type 752 exists on the device, and it is always present. NETCONF protocol 753 operations refer to this datastore using the element. 755 The capabilities in Section 8.3 and Section 8.7 define the 756 and configuration datastores, respectively. 758 5.2. Data Modeling 760 Data modeling and content issues are outside the scope of the NETCONF 761 protocol. An assumption is made that the device's data model is 762 well-known to the application and that both parties are aware of 763 issues such as the layout, containment, keying, lookup, replacement, 764 and management of the data, as well as any other constraints imposed 765 by the data model. 767 NETCONF carries configuration data inside the element that 768 is specific to device's data model. The protocol treats the contents 769 of that element as opaque data. The device uses capabilities to 770 announce the set of data models which the device implements. The 771 capability definition details the operation and constraints imposed 772 by data model. 774 Devices and managers may support multiple data models, including both 775 standard and proprietary data models. 777 6. Subtree Filtering 779 6.1. Overview 781 XML subtree filtering is a mechanism that allows an application to 782 select particular XML subtrees to include in the for a 783 or operation. A small set of filters for 784 inclusion, simple content exact-match, and selection is provided, 785 which allows some useful, but also very limited, selection 786 mechanisms. The agent does not need to utilize any data model- 787 specific semantics during processing, allowing for simple and 788 centralized implementation strategies. 790 Conceptually, a subtree filter is comprised of zero or more element 791 subtrees, which represent the filter selection criteria. At each 792 containment level within a subtree, the set of sibling nodes is 793 logically processed by the server to determine if its subtree (and 794 path of elements to the root) are included in the filter output. 796 All elements present in a particular subtree within a filter must 797 match associated nodes present in the server's conceptual data model. 798 XML namespaces may be specified (via 'xmlns' declarations) within the 799 filter data model. If so, the declared namespace must first exactly 800 match a namespace supported by the server. Note that prefix values 801 for qualified namespaces are not relevant when comparing filter 802 elements to elements in the underlying data model. Only data 803 associated with a specified namespace will be included in the filter 804 output. 806 Each node specified in a subtree filter represents an inclusive 807 filter. Only associated nodes in underlying data model(s) within the 808 specified configuration datastore on the server are selected by the 809 filter. A node must exactly match the namespace and hierarchy of 810 elements given in the filter data, except the filter absolute path 811 name is adjusted to start from the layer below . 813 Response messages contain only the subtrees selected by the filter. 814 Any selection criteria that were present in the request, within a 815 particular selected subtree, is also included in the response. Note 816 that some elements expressed in the filter as leaf nodes will be 817 expanded (i.e., subtrees included) in the filter output. Specific 818 data instances are not duplicated in the response in the event the 819 request contains multiple filter subtree expressions which select the 820 same data. 822 6.2. Subtree Filter Components 824 A subtree filter is comprised of XML elements and their XML 825 attributes. There are five types of components that may be present 826 in a subtree filter: 828 o Namespace Selection 830 o Attribute Match Expressions 832 o Containment Nodes 834 o Selection Nodes 836 o Content Match Nodes 838 6.2.1. Namespace Selection 840 If namespaces are used then the filter output will only include 841 elements from the specified namespace. A namespace is considered to 842 match (for filter purposes) if the content of the 'xmlns' attributes 843 are the same in the filter and the underlying data model. Note that 844 namespace selection cannot be used by itself. At least one element 845 must be specified in the filter any elements to be included in the 846 filter output. 848 Example: 850 851 852 854 In this example the element is a selection node, and only this 855 node and any child nodes (from the underlying data model) in the 856 'http://example.com/schema/1.2/config' namespace will be included in 857 the filter output. 859 6.2.2. Attribute Match Expressions 861 An attribute that appears in a subtree filter is part of an 862 "attribute match expression". Any number of (unqualified or 863 qualified) XML attributes may be present in any type of filter node. 864 In addition to the selection criteria normally applicable to that 865 node, the selected data must have matching values for every attribute 866 specified in the node. If an element is not defined to include a 867 specified attribute, then it is not selected in the filter output. 869 Example: 871 872 873 874 875 876 877 879 In this example the , and elements are 880 containment nodes, and 'ifName' is an attribute match expression. 881 Only 'interface' nodes in the 'http://example.com/schema/1.2/config' 882 namespace which have an 'ifName' attribute with the value 'eth0' and 883 occur within 'interfaces' nodes within 'top' nodes will be included 884 in the filter output. 886 6.2.3. Containment Nodes 888 Nodes which contain child elements within a subtree filter are called 889 "containment nodes". Each child element can be any type of node, 890 including another containment node. For each containment node 891 specified in a subtree filter, all data model instances which exactly 892 match the specified namespaces, element hierarchy, and any attribute 893 match expressions are included in the filter output. 895 Example: 897 898 899 900 901 903 In this example the element is a containment node. 905 6.2.4. Selection Nodes 907 An empty leaf node within a filter is called a "selection node", and 908 it represents an "explicit selection" filter on the underlying data 909 model. Presence of any selection nodes within a set of sibling nodes 910 will cause the filter to select the specified subtree(s), and 911 suppress automatic selection of the entire set of sibling nodes in 912 the underlying data model. For filtering purposes, an empty leaf 913 node can be declared with either an empty tag (e.g., ) or with 914 explicit start and end tags (e.g., ). Any whitespace 915 characters are ignored in this form. 917 Example: 919 920 921 922 923 925 In this example the element is a containment node, and the 926 element is a selection node. Only 'users' nodes in the 927 'http://example.com/schema/1.2/config' namespace, which occur within 928 a 'top' element that is the root of the configuration datastore will 929 be included in the filter output. 931 6.2.5. Content Match Nodes 933 A leaf node which contains simple content is called a "content match 934 node". It is used to select some or all of its sibling nodes for 935 filter output, and represents an exact-match filter on the leaf node 936 element content. The following constraints apply to content match 937 nodes: 939 o A content match node must not contain nested elements (i.e., must 940 resolve to a simpleType in XSD). 942 o Multiple content match nodes (i.e., sibling nodes) are logically 943 combined in an "AND" expression. 945 o Filtering of mixed content is not supported. 947 o Filtering of list content is not supported. 949 o Filtering of whitespace-only content is not supported. 951 o A content match node must contain non-whitespace characters. An 952 empty element (e.g., ) will be interpreted as a 953 selection node (e.g., ). 955 o Leading and trailing whitespace characters are ignored, but any 956 whitespace characters within a block of text characters are not 957 ignored or modified. 959 If all specified sibling content match nodes in a subtree filter 960 expression are 'true', then the filter output nodes are selected in 961 the following manner: 963 o Each content match node in the sibling set is included in the 964 filter output. 966 o If any containment nodes are present in the sibling set then they 967 are processed further, and included if any nested filter criteria 968 are also met. 970 o If any selection nodes are present in the sibling set then all of 971 them are included in the filter output. 973 o Otherwise (i.e., there are no selection or containment nodes in 974 the filter sibling set) all the nodes defined at this level in the 975 underlying data model (and their subtrees, if any) are returned in 976 the filter output. 978 If any of the sibling content match node tests are 'false', then no 979 further filter processing is performed on that sibling set, and none 980 of the sibling subtrees are selected by the filter, including the 981 content match node(s). 983 Example: 985 986 987 988 989 fred 990 991 992 993 995 In this example the and nodes are both containment 996 nodes, and is a content match node. Since no sibling nodes of 997 are specified (and therefore no containment or selection 998 nodes) all of the sibling nodes of are returned in the filter 999 output. Only 'user' nodes in the 1000 'http://example.com/schema/1.2/config' namespace, that match the 1001 element hierarchy and for which the element is equal to 'fred' 1002 will be included in the filter output. 1004 6.3. Subtree Filter Processing 1006 The filter output (the set of selected nodes) is initially empty. 1008 Each subtree filter can contain one or more data model fragments, 1009 which represent portions of the data model that should be selected 1010 (with all child nodes) in the filter output. 1012 Each subtree data fragment is compared by the server to the internal 1013 data models supported by the server. If the entire subtree data- 1014 fragment filter (starting from the root to the innermost element 1015 specified in the filter) exactly matches a corresponding portion of 1016 the supported data model, then that node and all its children are 1017 included in the result data. 1019 The server processes all nodes with the same parent node (sibling 1020 set) together, starting from the root to the leaf nodes. The root 1021 elements in the filter are considered to be in the same sibling set 1022 (assuming they are in the same namespace), even though they do not 1023 have a common parent. 1025 For each sibling set, the server determines which nodes are included 1026 (or potentially included) in the filter output, and which sibling 1027 subtrees are excluded (pruned) from the filter output. The server 1028 first determines which types of nodes are present in the sibling set, 1029 and processes the nodes according to the rules for their type. If 1030 any nodes in the sibling set are selected, then the process is 1031 recursively applied to the sibling sets of each selected node. The 1032 algorithm continues until all sibling sets in all subtrees specified 1033 in the filter have been processed. 1035 6.4. Subtree Filtering Examples 1037 6.4.1. No filter 1039 Leaving out the filter on the get operation returns the entire data 1040 model. 1042 1044 1045 1047 1049 1050 1051 1052 1054 6.4.2. Empty filter 1056 An empty filter will select nothing because no content match or 1057 selection nodes are present. This is not an error. The filter type 1058 attribute used in these examples is discussed further in Section 7.1. 1060 1062 1063 1064 1065 1066 1068 1070 1071 1072 1074 6.4.3. Select the entire subtree 1076 This filter in this example contains one selection node (), so 1077 just that subtree is selected by the filter. This example represents 1078 the fully-populated data model in most of the filter examples 1079 that follow. In a real data model, the would not 1080 likely be returned with the list of users for a particular host or 1081 network. 1083 NOTE: The filtering and configuration examples used in this document 1084 appear in the namespace "http://example.com/schema/1.2/config". The 1085 root element of this namespace is . The element and its 1086 descendents represent an example configuration data model only. 1088 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1103 1105 1106 1107 1108 1109 root 1110 superuser 1111 Charlie Root 1112 1113 1 1114 1 1115 1116 1117 1118 fred 1119 admin 1120 Fred Flintstone 1121 1122 2 1123 2 1124 1125 1126 1127 barney 1128 admin 1129 Barney Rubble 1130 1131 2 1132 3 1133 1134 1135 1136 1137 1138 1140 The following filter request would have produced the same result, but 1141 only because the container defines one child element 1142 (). 1144 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1160 6.4.4. Select all elements within the subtree 1162 This filter contains two containment nodes (, ), and one 1163 selector node (). All instances of the element in the 1164 same sibling set are selected in the filter output. The manager may 1165 need to know that is used as an instance identifier in this 1166 particular data structure, but the server does not need to know that 1167 meta-data in order to process the request. 1169 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1187 1189 1190 1191 1192 1193 root 1194 1195 1196 fred 1197 1198 1199 barney 1200 1201 1202 1203 1204 1206 6.4.5. One specific entry 1208 This filter contains two containment nodes (, ) and one 1209 content match node (). All instances of the sibling set 1210 containing for which the value of equals "fred" are 1211 selected in the filter output. 1213 1215 1216 1217 1218 1219 1220 1221 1222 1223 fred 1224 1225 1226 1227 1228 1229 1231 1233 1234 1235 1236 1237 fred 1238 admin 1239 Fred Flintstone 1240 1241 2 1242 2 1243 1244 1245 1246 1247 1248 1250 6.4.6. Specific elements from a specific entry 1252 This filter contains two containment nodes (, ), one 1253 content match node (), and two selector nodes (, ). All instances of the and elements in the 1255 same sibling set containing for which the value of 1256 equals "fred" are selected in the filter output. The 1257 element is not included because the sibling set contains selection 1258 nodes. 1260 1262 1263 1264 1265 1266 1267 1268 1269 1270 fred 1271 1272 1273 1274 1275 1276 1277 1278 1280 1282 1283 1284 1285 1286 fred 1287 admin 1288 Fred Flintstone 1289 1290 1291 1292 1293 1295 6.4.7. Multiple Subtrees 1297 This filter contains three subtrees (name=root, fred, barney) 1299 The "root" subtree filter contains two containment nodes (, 1300 ), one content match node (), and one selector node 1301 (). The subtree selection criteria is met, and just 1302 the company-info subtree for "root" is selected in the filter output. 1304 The "fred" subtree filter contains three containment nodes (, 1305 , ), one content match node (), and one 1306 selector node (). The subtree selection criteria is met, and 1307 just the element within the company-info subtree for "fred" is 1308 selected in the filter output. 1310 The "barney" subtree filter contains three containment nodes 1311 (, , ), two content match nodes (, 1312 ), and one selector node (). The subtree selection 1313 criteria is not met because user "barney" is not a "superuser", and 1314 the entire subtree for "barney" (including its parent entry) 1315 is excluded from the filter output. 1317 1319 1320 1321 1322 1323 1324 1325 1326 1327 root 1328 1329 1330 1331 fred 1332 1333 1334 1335 1336 1337 barney 1338 superuser 1339 1340 1341 1342 1343 1344 1345 1346 1347 1349 1351 1352 1353 1354 1355 root 1356 1357 1 1358 1 1359 1360 1361 1362 fred 1363 1364 2 1365 1366 1367 1368 1369 1370 1372 6.4.8. Elements with attribute naming 1374 In this example, the filter contains one containment node 1375 (), one attribute match expression (ifName), and one 1376 selector node (). All instances of the 1377 subtree that have an ifName attribute equal to "eth0" are selected in 1378 the filter output. The filter data elements and attributes must be 1379 qualified because the ifName attribute will not be considered part of 1380 the 'schema/1.2' namespace if it is unqualified. 1382 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1395 1397 1398 1399 1400 1401 45621 1402 774344 1403 1404 1405 1406 1407 1409 If ifName were a child node instead of an attribute, then the 1410 following request would produce similar results. 1412 1414 1415 1416 1417 1418 1419 eth0 1420 1421 1422 1423 1424 1425 1427 7. Protocol Operations 1429 The NETCONF protocol provides a small set of low-level operations to 1430 manage device configurations and retrieve device state information. 1431 The base protocol provides operations to retrieve, configure, copy, 1432 and delete configuration datastores. Additional operations are 1433 provided, based on the capabilities advertised by the device. 1435 The base protocol includes the following protocol operations: 1437 o get 1439 o get-config 1441 o edit-config 1443 o copy-config 1445 o delete-config 1447 o lock 1449 o unlock 1451 o close-session 1453 o kill-session 1455 A protocol operation may fail for various reasons, including 1456 "operation not supported". An initiator should not assume that any 1457 operation will always succeed. The return values in any RPC reply 1458 should be checked for error responses. 1460 The syntax and XML encoding of the protocol operations are formally 1461 defined in the XML schema in Appendix B. The following sections 1462 describe the semantics of each protocol operation. 1464 7.1. 1466 Description: 1468 Retrieve all or part of a specified configuration. 1470 Parameters: 1472 source: 1474 Name of the configuration datastore being queried, such as 1475 . 1477 filter: 1479 The filter element identifies the portions of the device 1480 configuration to retrieve. If this element is unspecified, the 1481 entire configuration is returned. 1483 The filter element may optionally contain a "type" attribute. 1484 This attribute indicates the type of filtering syntax used 1485 within the filter element. The default filtering mechanism in 1486 NETCONF is referred to as subtree filtering and is described in 1487 Section 6. The value "subtree" explicitly identifies this type 1488 of filtering. 1490 If the NETCONF peer supports the :xpath capability 1491 (Section 8.9), the value "xpath" may be used to indicate that 1492 the filter element contains an XPath expression. 1494 Positive Response: 1496 If the device can satisfy the request, the server sends an element containing a element with the results of the 1498 query. 1500 Negative Response: 1502 An element is included in the if the 1503 request cannot be completed for any reason. 1505 Example: To retrieve the entire subtree: 1507 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1521 1523 1524 1525 1526 1527 root 1528 superuser 1529 Charlie Root 1530 1531 1 1532 1 1533 1534 1535 1536 1537 1538 1539 1541 If the configuration is available in multiple formats, such as XML 1542 and text, an XML namespace can be used to specify which format is 1543 desired. In the following example, the client uses a specific 1544 element () in a specific namespace to indicate to the 1545 server the desire to receive the configuration in an alternative 1546 format. The server may support any number of distinct formats or 1547 views into the configuration data, with the client using the 1548 parameter to select between them. 1550 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1563 1565 1566 1567 1568 1569 1570 1572 Section 6 contains additional examples of subtree filtering. 1574 7.2. 1576 Description: 1578 The operation loads all or part of a specified 1579 configuration to the specified target configuration. This 1580 operation allows the new configuration to be expressed in several 1581 ways, such as using a local file, a remote file, or inline. If 1582 the target configuration does not exist, it will be created. If a 1583 NETCONF peer supports the :url capability (Section 8.8), the 1584 element can appear instead of the parameter and should 1585 identify a local configuration file. 1587 The device analyzes the source and target configurations and 1588 performs the requested changes. The target configuration is not 1589 necessarily replaced, as with the message. Instead 1590 the target configuration is changed in accordance with the 1591 source's data and requested operations. 1593 Attributes: 1595 operation: 1597 Elements in the subtree may contain an "operation" 1598 attribute. The attribute identifies the point in the 1599 configuration to perform the operation, and MAY appear on 1600 multiple elements throughout the subtree. 1602 If the operation attribute is not specified, the configuration 1603 is merged into the configuration datastore. 1605 The operation attribute has one of the following values: 1607 merge: The configuration data identified by the element 1608 containing this attribute is merged with the configuration 1609 at the corresponding level in the configuration datastore 1610 identified by the target parameter. This is the default 1611 behavior. 1613 replace: The configuration data identified by the element 1614 containing this attribute replaces any related configuration 1615 in the configuration datastore identified by the target 1616 parameter. Unlike a operation, which replaces 1617 the entire target configuration, only the configuration 1618 actually present in the config parameter is affected. 1620 create: The configuration data identified by the element 1621 containing this attribute is added to the configuration if 1622 and only if the configuration data does not already exist on 1623 the device. If the configuration data exists, an element is returned with an value of 1625 data-exists. 1627 delete: The configuration data identified by the element 1628 containing this attribute is deleted in the configuration 1629 datastore identified by the target parameter. 1631 Parameters: 1633 target: 1635 Name of the configuration datastore being edited, such as 1636 or . 1638 default-operation: 1640 Selects the default operation (as described in the "operation" 1641 attribute) for this request. The default value 1642 for the default-operation parameter is "merge". 1644 The default-operation parameter is optional, but if provided, 1645 must have one of the following values: 1647 merge: The configuration data in the parameter is 1648 merged with the configuration at the corresponding level in 1649 the target datastore. This is the default behavior. 1651 replace: The configuration data in the parameter 1652 completely replaces the configuration in the target 1653 datastore. This is useful for loading previously saved 1654 configuration data. 1656 none: The target datastore is unaffected by the configuration 1657 in the parameter, unless and until the incoming 1658 configuration data uses the "operation" attribute to request 1659 a different operation. If the configuration in the 1660 parameter contains data for which there is not a 1661 corresponding level in the target datastore, an 1662 is returned with an value of data-missing. 1663 Using "none" allows operations like "delete" to avoid 1664 unintentionally creating the parent hierarchy of the element 1665 to be deleted. 1667 test-option: 1669 The test-option element may be specified only if the device 1670 advertises the :validate capability (Section 8.6). 1672 The test-option element has one of the following values: 1674 test-then-set: Perform a validation test before attempting to 1675 set. If validation errors occur, do not perform the operation. This is the default test-option. 1678 set: Perform a set without a validation test first. 1680 error-option: 1682 The error-option element has one of the following values: 1684 stop-on-error: Abort the edit-config operation on first error. 1685 This is the default error-option. 1687 continue-on-error: Continue to process configuration data on 1688 error; error is recorded and negative response is generated 1689 if any errors occur. 1691 rollback-on-error: If an error condition occurs such that an 1692 error severity element is generated, the server 1693 will stop processing the edit-config operation and restore 1694 the specified configuration to its complete state at the 1695 start of this edit-config operation. This option requires 1696 the server to support the :rollback-on-error capability 1697 described in Section 8.5. 1699 config: 1701 A hierarchy of configuration data as defined by one of the 1702 device's data models. The contents MUST be placed in an 1703 appropriate namespace, to allow the device to detect the 1704 appropriate data model, and the contents MUST follow the 1705 constraints of that data model, as defined by its capability 1706 definition. Capabilities are discussed in Section 8. 1708 Positive Response: 1710 If the device was able to satisfy the request, an is 1711 sent containing an element. 1713 Negative Response: 1715 An response is sent if the request cannot be completed 1716 for any reason. 1718 Example: 1720 Set the MTU to 1500 on an interface named "Ethernet0/0" in the 1721 running configuration: 1723 1725 1726 1727 1728 1729 1730 1731 1732 Ethernet0/0 1733 1500 1734 1735 1736 1737 1738 1740 1742 1743 1745 Add an interface named "Ethernet0/0" to the running configuration, 1746 replacing any previous interface with that name: 1748 1750 1751 1752 1753 1754 1755 1756 1757 Ethernet0/0 1758 1500 1759
1760 192.0.2.4 1761 24 1762
1763 1764 1765 1766 1767 1769 1771 1772 1774 Delete the configuration for an interface named "Ethernet0/0" from 1775 the running configuration: 1777 1779 1780 1781 1782 1783 none 1784 1785 1786 1787 Ethernet0/0 1788 1789 1790 1791 1792 1794 1796 1797 1799 Delete interface 192.0.2.4 from an OSPF area (other interfaces 1800 configured in the same area are unaffected): 1802 1804 1805 1806 1807 1808 none 1809 1810 1811 1812 1813 1814 0.0.0.0 1815 1816 1817 192.0.2.4 1818 1819 1820 1821 1822 1823 1824 1825 1826 1828 1830 1831 1833 7.3. 1835 Description: 1837 Create or replace an entire configuration datastore with the 1838 contents of another complete configuration datastore. If the 1839 target datastore exists, it is overwritten. Otherwise, a new one 1840 is created, if allowed. 1842 If a NETCONF peer supports the :url capability (Section 8.8), the 1843 element can appear as the or parameter. 1845 Even if it advertises the :writable-running capability, a device 1846 may choose not to support the configuration datastore 1847 as the parameter of a operation. A device 1848 may choose not to support remote-to-remote copy operations, where 1849 both the and parameters use the element. 1851 If the source and target parameters identify the same URL or 1852 configuration datastore, an error MUST be returned with an error- 1853 tag containing invalid-value. 1855 Parameters: 1857 target: 1859 Name of the configuration datastore to use as the destination 1860 of the copy operation. 1862 source: 1864 Name of the configuration datastore to use as the source of the 1865 copy operation or the element containing the 1866 configuration subtree to copy. 1868 Positive Response: 1870 If the device was able to satisfy the request, an is 1871 sent that includes an element. 1873 Negative Response: 1875 An element is included within the if the 1876 request cannot be completed for any reason. 1878 Example: 1880 1882 1883 1884 1885 1886 1887 https://user@example.com:passphrase/cfg/new.txt 1888 1889 1890 1892 1894 1895 1897 7.4. 1899 Description: 1901 Delete a configuration datastore. The configuration 1902 datastore cannot be deleted. 1904 If a NETCONF peer supports the :url capability (Section 8.8), the 1905 element can appear as the parameter. 1907 Parameters: 1909 target: 1911 Name of the configuration datastore to delete. 1913 Positive Response: 1915 If the device was able to satisfy the request, an is 1916 sent that includes an element. 1918 Negative Response: 1920 An element is included within the if the 1921 request cannot be completed for any reason. 1923 Example: 1925 1927 1928 1929 1930 1931 1932 1934 1936 1937 1939 7.5. 1940 Description: 1942 The lock operation allows the client to lock the configuration 1943 system of a device. Such locks are intended to be short-lived and 1944 allow a client to make a change without fear of interaction with 1945 other NETCONF clients, non-NETCONF clients (e.g. SNMP and CLI 1946 scripts) and human users. 1948 An attempt to lock the configuration MUST fail if an existing 1949 session or other entity holds a lock on any portion of the lock 1950 target. 1952 When the lock is acquired, the server MUST prevent any changes to 1953 the locked resource other than those requested by this session. 1954 SNMP and CLI requests to modify the resource MUST fail with an 1955 appropriate error. 1957 The duration of the lock is defined as beginning when the lock is 1958 acquired and lasting until either the lock is released or the 1959 NETCONF session closes. The session closure may be explicitly 1960 performed by the client, or implicitly performed by the server 1961 based on criteria such as failure of the underlying transport, or 1962 simple inactivity timeout. This criteria is dependent on the 1963 implementation and the underlying transport. 1965 The lock operation takes a mandatory parameter, target. The 1966 target parameter names the configuration that will be locked. 1967 When a lock is active, using the operation on the 1968 locked configuration and using the locked configuration as a 1969 target of the operation will be disallowed by any 1970 other NETCONF session. Additionally, the system will ensure that 1971 these locked configuration resources will not be modified by other 1972 non-NETCONF management operations such as SNMP and CLI. The 1973 message (at the RPC layer) can be used to force the 1974 release of a lock owned by another NETCONF session. It is beyond 1975 the scope of this document to define how to break locks held by 1976 other entities. 1978 A lock MUST not be granted if any of the following conditions are 1979 true: 1981 * a lock is already held by another NETCONF session or another 1982 entity 1984 * the target configuration is and it has already been 1985 modified and these changes have not been committed or rolled 1986 back 1988 The server MUST respond with either an element or an . 1991 A lock will be released by the system if the session holding the 1992 lock is terminated for any reason. 1994 Parameters: 1996 target: 1998 Name of the configuration datastore to lock. 2000 Positive Response: 2002 If the device was able to satisfy the request, an is 2003 sent that contains an element. 2005 Negative Response: 2007 An element is included in the if the 2008 request cannot be completed for any reason. 2010 If the lock is already held, the element will be 2011 'lock-denied' and the element will include the 2012 of the lock owner. If the lock is held by a non- 2013 NETCONF entity, a of 0 (zero) is included. Note that 2014 any other entity performing a lock on even a partial piece of a 2015 target will prevent a NETCONF lock (which is global) from being 2016 obtained on that target. 2018 Example: 2020 The following example shows a successful acquisition of a lock. 2022 2024 2025 2026 2027 2028 2029 2031 2033 2034 2036 Example: 2038 The following example shows a failed attempt to acquire a lock 2039 when the lock is already in use. 2041 2043 2044 2045 2046 2047 2048 2050 2052 2053 protocol 2054 lock-denied 2055 error 2056 2057 Lock failed, lock is already held 2058 2059 2060 454 2061 2062 2063 2064 2066 7.6. 2068 Description: 2070 The unlock operation is used to release a configuration lock, 2071 previously obtained with the operation. 2073 An unlock operation will not succeed if any of the following 2074 conditions are true: 2076 * the specified lock is not currently active 2078 * the session issuing the operation is not the same 2079 session that obtained the lock 2081 The server MUST respond with either an element or an . 2084 Parameters: 2086 target: 2088 Name of the configuration datastore to unlock. 2090 A NETCONF client is not permitted to unlock a configuration 2091 datastore that it did not lock. 2093 Positive Response: 2095 If the device was able to satisfy the request, an is 2096 sent that contains an element. 2098 Negative Response: 2100 An element is included in the if the 2101 request cannot be completed for any reason. 2103 Example: 2105 2107 2108 2109 2110 2111 2112 2114 2116 2117 2119 7.7. 2121 Description: 2123 Retrieve running configuration and device state information. 2125 Parameters: 2127 filter: 2129 This parameter specifies the portion of the system 2130 configuration and state data to retrieve. If this parameter is 2131 empty, all the device configuration and state information is 2132 returned. 2134 The filter element may optionally contain a 'type' attribute. 2135 This attribute indicates the type of filtering syntax used 2136 within the filter element. The default filtering mechanism in 2137 NETCONF is referred to as subtree filtering and is described in 2138 Section 6. The value 'subtree' explicitly identifies this type 2139 of filtering. 2141 If the NETCONF peer supports the :xpath capability 2142 (Section 8.9), the value 'xpath' may be used to indicate that 2143 the filter element contains an XPath expression. 2145 Positive Response: 2147 If the device was able to satisfy the request, an is 2148 sent. The section contains the appropriate subset. 2150 Negative Response: 2152 An element is included in the if the 2153 request cannot be completed for any reason. 2155 Example: 2157 2159 2160 2161 2162 2163 2164 eth0 2165 2166 2167 2168 2169 2170 2172 2174 2175 2176 2177 2178 eth0 2179 45621 2180 774344 2181 2182 2183 2184 2185 2187 7.8. 2189 Description: 2191 Request graceful termination of a NETCONF session. 2193 When a NETCONF server receives a request, it will 2194 gracefully close the session. The server will release any locks 2195 and resources associated with the session and gracefully close any 2196 associated connections. Any NETCONF requests received after a 2197 request will be ignored. 2199 Positive Response: 2201 If the device was able to satisfy the request, an is 2202 sent that includes an element. 2204 Negative Response: 2206 An element is included in the if the 2207 request cannot be completed for any reason. 2209 Example: 2211 2213 2214 2216 2218 2219 2221 7.9. 2223 Description: 2225 Force the termination of a NETCONF session. 2227 When a NETCONF entity receives a request for an 2228 open session, it will abort any operations currently in process, 2229 release any locks and resources associated with the session and 2230 close any associated connections. 2232 If a NETCONF server receives a request while 2233 processing a confirmed commit (Section 8.4), it must restore the 2234 configuration to its state before the confirmed commit was issued. 2236 Otherwise, the operation does not roll back 2237 configuration or other device state modifications made by the 2238 entity holding the lock. 2240 Parameters: 2242 session-id: 2244 Session identifier of the NETCONF session to be terminated. If 2245 this value is equal to the current session ID, an 'invalid- 2246 value' error is returned. 2248 Positive Response: 2250 If the device was able to satisfy the request, an is 2251 sent that includes an element. 2253 Negative Response: 2255 An element is included in the if the 2256 request cannot be completed for any reason. 2258 Example: 2260 2262 2263 4 2264 2265 2267 2269 2270 2272 8. Capabilities 2274 This section defines a set of capabilities that a client or a server 2275 MAY implement. Each peer advertises its capabilities by sending them 2276 during an initial capabilities exchange. Each peer needs to 2277 understand only those capabilities that it might use and MUST ignore 2278 any capability received from the other peer that it does not require 2279 or does not understand. 2281 Additional capabilities can be defined using the template in 2282 Appendix C. Future capability definitions may be published as 2283 standards by standards bodies or published as proprietary extensions. 2285 A NETCONF capability is identified with a URI. The base capabilities 2286 are defined using URNs following the method described in RFC 3553 2287 [6]. Capabilities defined in this document have the following 2288 format: 2290 urn:ietf:params:netconf:capability:{name}:1.0 2292 where {name} is the name of the capability. Capabilities are often 2293 referenced in discussions and email using the shorthand :{name}. For 2294 example, the foo capability would have the formal name 2295 "urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo". 2296 The shorthand form MUST NOT be used inside the protocol. 2298 8.1. Capabilities Exchange 2300 Capabilities are advertised in messages sent by each peer during 2301 session establishment. When the NETCONF session is opened, each peer 2302 (both client and server) MUST send a element containing a 2303 list of that peer's capabilities. Each peer MUST send at least the 2304 base NETCONF capability, "urn:ietf:params:netconf:base:1.0". 2306 A server sending the element MUST include a 2307 element containing the session ID for this NETCONF session. A client 2308 sending the element MUST NOT include a element. 2310 A server receiving a element MUST NOT continue the 2311 NETCONF session. Similarly, a client that does not receive a 2312 element in the server's message MUST NOT 2313 continue the NETCONF session. In both cases the underlying transport 2314 should be closed. 2316 In the following example, a server advertises the base NETCONF 2317 capability, one NETCONF capability defined in the base NETCONF 2318 document, and one implementation-specific capability. 2320 2321 2322 2323 urn:ietf:params:netconf:base:1.0 2324 2325 2326 urn:ietf:params:netconf:capability:startup:1.0 2327 2328 2329 http:/example.net/router/2.3/myfeature 2330 2331 2332 4 2333 2335 Each peer sends its element simultaneously as soon as the 2336 connection is open. A peer MUST NOT wait to receive the capability 2337 set from the other side before sending its own set. 2339 8.2. Writable-Running Capability 2340 8.2.1. Description 2342 The :writable-running capability indicates that the device supports 2343 writes directly to the configuration datastore. In other 2344 words, the device supports edit-config and copy-config operations 2345 where the configuration is the target. 2347 8.2.2. Dependencies 2349 None. 2351 8.2.3. Capability Identifier 2353 The :writable-running capability is identified by the following 2354 capability string: 2356 urn:ietf:params:netconf:capability:writable-running:1.0 2358 8.2.4. New Operations 2360 None. 2362 8.2.5. Modifications to Existing Operations 2364 8.2.5.1. 2366 The :writable-running capability modifies the operation 2367 to accept the element as a . 2369 8.2.5.2. 2371 The :writable-running capability modifies the operation 2372 to accept the element as a . 2374 8.3. Candidate Configuration Capability 2376 8.3.1. Description 2378 The candidate configuration capability, :candidate, indicates that 2379 the device supports a candidate configuration datastore, which is 2380 used to hold configuration data that can be manipulated without 2381 impacting the device's current configuration. The candidate 2382 configuration is a full configuration data set that serves as a work 2383 place for creating and manipulating configuration data. Additions, 2384 deletions, and changes may be made to this data to construct the 2385 desired configuration data. A operation may be performed at 2386 any time that causes the device's running configuration to be set to 2387 the value of the candidate configuration. 2389 The operation effectively sets the running configuration to 2390 the current contents of the candidate configuration. While it could 2391 be modeled as a simple copy, it is done as a distinct operation for a 2392 number of reasons. In keeping high level concepts as first class 2393 operations, we allow developers to see more clearly both what the 2394 client is requesting and what the server must perform. This keeps 2395 the intentions more obvious, the special cases less complex, and the 2396 interactions between operations more straight-forward. For example, 2397 the :confirmed-commit capability (Section 8.4) would make no sense as 2398 a "copy confirmed" operation. 2400 The candidate configuration may be shared among multiple sessions. 2401 Unless a client has specific information that the candidate 2402 configuration is not shared, it must assume that other sessions may 2403 be able to modify the candidate configuration at the same time. It 2404 is therefore prudent for a client to lock the candidate configuration 2405 before modifying it. 2407 The client can discard any uncommitted changes to the candidate 2408 configuration by executing the operation. This 2409 operation reverts the contents of the candidate configuration to the 2410 contents of the running configuration. 2412 8.3.2. Dependencies 2414 None. 2416 8.3.3. Capability Identifier 2418 The :candidate capability is identified by the following capability 2419 string: 2421 urn:ietf:params:netconf:capability:candidate:1.0 2423 8.3.4. New Operations 2425 8.3.4.1. 2427 Description: 2429 When a candidate configuration's content is complete, the 2430 configuration data can be committed, publishing the data set to 2431 the rest of the device and requesting the device to conform to 2432 the behavior described in the new configuration. 2434 To commit the candidate configuration as the device's new 2435 current configuration, use the operation. 2437 The operation instructs the device to implement the 2438 configuration data contained in the candidate configuration. 2439 If the device is unable to commit all of the changes in the 2440 candidate configuration datastore, then the running 2441 configuration MUST remain unchanged. If the device does 2442 succeed in committing, the running configuration MUST be 2443 updated with the contents of the candidate configuration. 2445 If the system does not have the :candidate capability, the 2446 operation is not available. 2448 Positive Response: 2450 If the device was able to satisfy the request, an 2451 is sent that contains an element. 2453 Negative Response: 2455 An element is included in the if the 2456 request cannot be completed for any reason. 2458 Example: 2460 2462 2463 2465 2467 2468 2470 8.3.4.2. 2472 If the client decides that the candidate configuration should not be 2473 committed, the operation can be used to revert the 2474 candidate configuration to the current running configuration. 2476 2478 2479 2481 This operation discards any uncommitted changes by resetting the 2482 candidate configuration with the content of the running 2483 configuration. 2485 8.3.5. Modifications to Existing Operations 2487 8.3.5.1. , , , and 2489 The candidate configuration can be used as a source or target of any 2490 , , , or operation 2491 as a or parameter. The element is used 2492 to indicate the candidate configuration: 2494 2496 2497 2498 2499 2500 2501 2503 8.3.5.2. and 2505 The candidate configuration can be locked using the operation 2506 with the element as the parameter: 2508 2510 2511 2512 2513 2514 2515 2517 Similarly, the candidate configuration is unlocked using the 2518 element as the parameter: 2520 2522 2523 2524 2525 2526 2527 2529 When a client fails with outstanding changes to the candidate 2530 configuration, recovery can be difficult. To facilitate easy 2531 recovery, any outstanding changes are discarded when the lock is 2532 released, whether explicitly with the operation or 2533 implicitly from session failure. 2535 8.4. Confirmed Commit Capability 2537 8.4.1. Description 2539 The :confirmed-commit capability indicates that the server will 2540 support the and parameters for the 2541 protocol operation. See section Section 8.3 for further 2542 details on the operation. 2544 A confirmed commit operation MUST be reverted if a follow-up commit 2545 (called the "confirming commit") is not issued within 600 seconds (10 2546 minutes). The timeout period can be adjusted with the element. The confirming commit can itself include a 2548 parameter. 2550 If the session issuing the confirmed commit is terminated for any 2551 reason before the confirm timeout expires, the server MUST restore 2552 the configuration to its state before the confirmed commit was 2553 issued. 2555 If the device reboots for any reason before the confirm timeout 2556 expires, the server MUST restore the configuration to its state 2557 before the confirmed commit was issued. 2559 If a confirming commit is not issued, the device will revert its 2560 configuration to the state prior to the issuance of the confirmed 2561 commit. Note that any commit operation, including a commit which 2562 introduces additional changes to the configuration, will serve as a 2563 confirming commit. Thus to cancel a confirmed commit and revert 2564 changes without waiting for the confirm timeout to expire, the 2565 manager can explicitly restore the configuration to its state before 2566 the confirmed commit was issued. 2568 For shared configurations, this feature can cause other configuration 2569 changes (for example, via other NETCONF sessions) to be inadvertently 2570 altered or removed, unless the configuration locking feature is used 2571 (in other words, lock obtained before the edit-config operation is 2572 started). Therefore, it is strongly suggested that in order to use 2573 this feature with shared configuration databases, configuration 2574 locking should also be used. 2576 8.4.2. Dependencies 2578 The :confirmed-commit capability is only relevant if the :candidate 2579 capability is also supported. 2581 8.4.3. Capability Identifier 2583 The :confirmed-commit capability is identified by the following 2584 capability string: 2586 urn:ietf:params:netconf:capability:confirmed-commit:1.0 2588 8.4.4. New Operations 2590 None. 2592 8.4.5. Modifications to Existing Operations 2594 8.4.5.1. 2596 The :confirmed-commit capability allows 2 additional parameters to 2597 the operation. 2599 Parameters: 2601 confirmed: 2603 Perform a confirmed commit operation. 2605 confirm-timeout: 2607 Timeout period for confirmed commit, in seconds. If 2608 unspecified, the confirm timeout defaults to 600 seconds. 2610 Example: 2612 2614 2615 2616 120 2617 2618 2620 2622 2623 2625 8.5. Rollback on Error Capability 2626 8.5.1. Description 2628 This capability indicates that the server will support the 'rollback- 2629 on-error' value in the parameter to the 2630 operation. 2632 For shared configurations, this feature can cause other configuration 2633 changes (for example, via other NETCONF sessions) to be inadvertently 2634 altered or removed, unless the configuration locking feature is used 2635 (in other words, lock obtained before the edit-config operation is 2636 started). Therefore, it is strongly suggested that in order to use 2637 this feature with shared configuration databases, configuration 2638 locking must also be used. 2640 8.5.2. Dependencies 2642 None 2644 8.5.3. Capability Identifier 2646 The :rollback-on-error capability is identified by the following 2647 capability string: 2649 urn:ietf:params:netconf:capability:rollback-on-error:1.0 2651 8.5.4. New Operations 2653 None. 2655 8.5.5. Modifications to Existing Operations 2657 8.5.5.1. 2659 The :rollback-on-error capability allows the 'rollback-on-error' 2660 value to the parameter on the operation. 2662 2664 2665 2666 2667 2668 rollback-on-error 2669 2670 2671 2672 Ethernet0/0 2673 100000 2674 2675 2676 2677 2678 2680 2682 2683 2685 8.6. Validate Capability 2687 8.6.1. Description 2689 Validation consists of checking a candidate configuration for 2690 syntactical and semantic errors before applying the configuration to 2691 the device. 2693 If this capability is advertised, the device supports the 2694 protocol operation and checks at least for syntax errors. In 2695 addition, this capability supports the test-option parameter to the 2696 operation and, when it is provided, checks at least for 2697 syntax errors. 2699 8.6.2. Dependencies 2701 None. 2703 8.6.3. Capability Identifier 2705 The :validate capability is identified by the following capability 2706 string: 2708 urn:ietf:params:netconf:capability:validate:1.0 2710 8.6.4. New Operations 2712 8.6.4.1. 2714 Description: 2716 This protocol operation validates the contents of the specified 2717 configuration. 2719 Parameters: 2721 source: 2723 Name of the configuration datastore being validated, such as 2724 or the element containing the 2725 configuration subtree to validate. 2727 Positive Response: 2729 If the device was able to satisfy the request, an 2730 is sent that contains an element. 2732 Negative Response: 2734 An element is included in the if the 2735 request cannot be completed for any reason. 2737 A validate operation can fail for any of the following reasons: 2739 + Syntax errors 2741 + Missing parameters 2743 + References to undefined configuration data 2745 Example: 2747 2749 2750 2751 2752 2753 2754 2756 2758 2759 2761 8.7. Distinct Startup Capability 2763 8.7.1. Description 2765 The device supports separate running and startup configuration 2766 datastores. Operations which affect the running configuration will 2767 not be automatically copied to the startup configuration. An 2768 explicit operation from the to the 2769 must be invoked to update the startup configuration to the current 2770 contents of the running configuration. NETCONF protocol operations 2771 refer to the startup datastore using the element. 2773 8.7.2. Dependencies 2775 None. 2777 8.7.3. Capability Identifier 2779 The :startup capability is identified by the following capability 2780 string: 2782 urn:ietf:params:netconf:capability:startup:1.0 2784 8.7.4. New Operations 2786 None. 2788 8.7.5. Modifications to Existing Operations 2790 8.7.5.1. General 2792 The :startup capability adds the configuration datastore 2793 to arguments of several NETCONF operations. The server MUST support 2794 the following additional values: 2796 +--------------------+--------------------------+-------------------+ 2797 | Operation | Parameters | Notes | 2798 +--------------------+--------------------------+-------------------+ 2799 | | | | 2800 | | | | 2801 | | | | 2802 | | | | 2803 | | | If :validate is | 2804 | | | advertised | 2805 +--------------------+--------------------------+-------------------+ 2807 To save the startup configuration, use the copy-config operation to 2808 copy the configuration datastore to the 2809 configuration datastore. 2811 2813 2814 2815 2816 2817 2818 2819 2820 2821 2823 8.8. URL Capability 2825 8.8.1. Description 2827 The NETCONF peer has the ability to accept the element in 2828 and parameters. The capability is further 2829 identified by URL arguments indicating the URL schemes supported. 2831 8.8.2. Dependencies 2833 None. 2835 8.8.3. Capability Identifier 2837 The :url capability is identified by the following capability string: 2839 urn:ietf:params:netconf:capability:url:1.0?scheme={name,...} 2841 The :url capability URI MUST contain a "scheme" argument assigned a 2842 comma-separated list of scheme names indicating which schemes the 2843 NETCONF peer supports. For example: 2845 urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file 2847 8.8.4. New Operations 2849 None. 2851 8.8.5. Modifications to Existing Operations 2853 8.8.5.1. 2855 The :url capability modifies the operation to accept 2856 the element as an alternative to the parameter. If 2857 the element is specified, then it should identify a local 2858 configuration file. 2860 8.8.5.2. 2862 The :url capability modifies the operation to accept 2863 the element as the value of the the and the 2864 parameters. 2866 8.8.5.3. 2868 The :url capability modifies the operation to accept 2869 the element as the value of the the parameters. If 2870 this parameter contains a URL, then it should identify a local 2871 configuration file. 2873 8.8.5.4. 2875 The :url capability modifies the operation to accept the 2876 element as the value of the the parameter. 2878 8.9. XPath Capability 2880 8.9.1. Description 2882 The XPath capability indicates that the NETCONF peer supports the use 2883 of XPath expressions in the element. XPath is described in 2884 [2]. 2886 The XPath expression must return a node-set. 2888 The XPath expression is evaluated in a context where the context node 2889 is the root node, and the set of namespace declarations are those in 2890 scope on the filter element, including the default namespace. 2892 8.9.2. Dependencies 2894 None. 2896 8.9.3. Capability Identifier 2898 The :xpath capability is identified by the following capability 2899 string: 2901 urn:ietf:params:netconf:capability:xpath:1.0 2903 8.9.4. New Operations 2905 None. 2907 8.9.5. Modifications to Existing Operations 2909 8.9.5.1. and 2911 The :xpath capability modifies the and operations 2912 to accept the value "xpath" in the type attribute of the filter 2913 element. When the type attribute is set to "xpath", the contents of 2914 the filter element will be treated as an xpath expression and used to 2915 filter the returned data. 2917 For example: 2919 2921 2922 2923 2924 2925 2926 top/users/user[name="fred"] 2927 2928 2929 2931 9. Security Considerations 2933 This document does not specify an authorization scheme, as such a 2934 scheme should be tied to a meta-data model or a data model. 2935 Implementors SHOULD provide a comprehensive authorization scheme with 2936 NETCONF. 2938 Authorization of individual users via the NETCONF server may or may 2939 not map 1:1 to other interfaces. First, the data models may be 2940 incompatible. Second, it may be desirable to authorize based on 2941 mechanisms available in the transport protocol layer (TELNET, SSH, 2942 etc). 2944 In addition, operations on configurations may have unintended 2945 consequences if those operations are also not guarded by the global 2946 lock on the files or objects being operated upon. For instance, a 2947 partially complete access list could be committed from a candidate 2948 configuration unbeknownst to the owner of the lock of the candidate 2949 configuration, leading to either an insecure or inaccessible device 2950 if the lock on the candidate configuration does not also apply to the 2951 operation when applied to it. 2953 Configuration information is by its very nature sensitive. Its 2954 transmission in the clear and without integrity checking leaves 2955 devices open to classic eavesdropping attacks. Configuration 2956 information often contains passwords, user names, service 2957 descriptions, and topological information, all of which are 2958 sensitive. Because of this, this protocol should be implemented 2959 carefully with adequate attention to all manner of attack one might 2960 expect to experience with other management interfaces. 2962 The protocol, therefore, must minimally support options for both 2963 confidentiality and authentication. It is anticipated that the 2964 underlying protocol (SSH, BEEP, etc) will provide for both 2965 confidentiality and authentication, as is required. It is further 2966 expected that the identity of each end of a NETCONF session will be 2967 available to the other in order to determine authorization for any 2968 given request. One could also easily envision additional information 2969 such as transport and encryption methods being made available for 2970 purposes of authorization. NETCONF itself provide no means to 2971 reauthenticate, much less authenticate. All such actions occur at 2972 lower layers. 2974 Different environments may well allow different rights prior to and 2975 then after authentication. Thus, an authorization model is not 2976 specified in this document. When an operation is not properly 2977 authorized then a simple "access denied" is sufficient. Note that 2978 authorization information may be exchanged in the form of 2979 configuration information, which is all the more reason to ensure the 2980 security of the connection. 2982 That having been said, it is important to recognize that some 2983 operations are clearly more sensitive by nature than others. For 2984 instance, to the startup or running configurations is 2985 clearly not a normal provisioning operation, where-as 2986 is. Such global operations MUST disallow the changing of information 2987 that an individual does not have authorization to perform. For 2988 example, if a user A is not allowed to configure an IP address on an 2989 interface but user B has configured an IP address on an interface in 2990 the configuration, user A must not be allowed to commit 2991 the configuration. 2993 Similarly, just because someone says go write a configuration through 2994 the URL capability at a particular place does not mean that an 2995 element should do it without proper authorization. 2997 The operation will demonstrate that NETCONF is intended for 2998 use by systems that have at least some trust of the administrator. 2999 As specified in this document, it is possible to lock portions of a 3000 configuration that a principal might not otherwise have access to. 3001 After all, the entire configuration is locked. To mitigate this 3002 problem there are two approaches. It is possible to kill another 3003 NETCONF session programmatically from within NETCONF if one knows the 3004 session identifier of the offending session. The other possible way 3005 to break a lock is to provide an function within the device's native 3006 user interface. These two mechanisms suffer from a race condition 3007 that may be ameliorated by removing the offending user from an AAA 3008 server. However, such a solution is not useful in all deployment 3009 scenarios, such as those where SSH public/private key pairs are used. 3011 10. IANA Considerations 3013 10.1. NETCONF XML Namespace 3015 This document requests that IANA register a URI for the NETCONF XML 3016 namespace in the IETF XML registry [7]. 3018 Following the format in RFC 3688, the following registration is 3019 requested. 3021 URI: Please assign the URI "urn:ietf:params:xml:ns:netconf:base:1.0" 3022 for use by the NETCONF protocol. 3024 Registrant Contact: The IESG. 3026 XML: N/A, the requested URI is an XML namespace. 3028 10.2. NETCONF XML Schema 3030 This document requests that IANA register a URI for the NETCONF XML 3031 schema in the IETF XML registry [7]. 3033 Following the format in RFC 3688, the following registration is 3034 requested. 3036 URI: Please assign the URI "urn:ietf:params:xml:schema:netconf" for 3037 use by the NETCONF protocol. 3039 Registrant Contact: The IESG. 3041 XML: Appendix B of this document. 3043 10.3. NETCONF Capability URNs 3045 This document requests that IANA create a registry for allocating 3046 NETCONF capability identifiers. Additions to the registry require 3047 IETF Standards Action. 3049 The initial content of the registry will be the capability URNs 3050 defined in Section 8. 3052 Following the guidelines in RFC 3553 [6], IANA is requested to assign 3053 a NETCONF sub-namespace as follows: 3055 Registry name: netconf 3057 Specification: Section 8 of this document. 3059 Repository: The following table. 3061 +--------------------+----------------------------------------------+ 3062 | Index | Capability Identifier | 3063 +--------------------+----------------------------------------------+ 3064 | :writable-running | urn:ietf:params:netconf:capability:writable- | 3065 | | running:1.0 | 3066 | :candidate | urn:ietf:params:netconf:capability:candidate | 3067 | | :1.0 | 3068 | :confirmed-commit | urn:ietf:params:netconf:capability:confirmed | 3069 | | -commit:1.0 | 3070 | :rollback-on-error | urn:ietf:params:netconf:capability:rollback- | 3071 | | on-error:1.0 | 3072 | :validate | urn:ietf:params:netconf:capability:validate: | 3073 | | 1.0 | 3074 | :startup | urn:ietf:params:netconf:capability:startup:1 | 3075 | | .0 | 3076 | :url | urn:ietf:params:netconf:capability:url:1.0 | 3077 | :xpath | urn:ietf:params:netconf:capability:xpath:1.0 | 3078 +--------------------+----------------------------------------------+ 3080 Index value: The capability name. 3082 11. Authors and Acknowledgements 3084 This document was written by: 3086 Andy Bierman 3088 Ken Crozier, Cisco Systems 3090 Rob Enns, Juniper Networks 3092 Ted Goddard, IceSoft 3094 Eliot Lear, Cisco Systems 3096 Phil Shafer, Juniper Networks 3098 Steve Waldbusser 3100 Margaret Wasserman, ThingMagic 3102 The authors would like to acknowledge the members of the NETCONF 3103 working group. In particular, we would like to thank Wes Hardaker 3104 for his persistance and patience in assisting us with security 3105 considerations. We would also like to thank Randy Presuhn, Sharon 3106 Chisholm, Juergen Schoenwalder, Glenn Waters, David Perkins, Weijing 3107 Chen, Simon Leinen, Keith Allen and Dave Harrington for all of their 3108 valuable advice. 3110 12. References 3112 12.1. Normative References 3114 [1] Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, 3115 "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C 3116 REC REC-xml-20001006, October 2000. 3118 [2] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 3119 1.0", W3C REC REC-xpath-19991116, November 1999. 3121 [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement 3122 Levels", BCP 14, RFC 2119, March 1997. 3124 [4] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration 3125 Protocol over Secure Shell (SSH)", draft-ietf-netconf-ssh-04 3126 (work in progress), April 2005. 3128 [5] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3129 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 3130 January 2005. 3132 [6] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF 3133 URN Sub-namespace for Registered Protocol Parameters", BCP 73, 3134 RFC 3553, June 2003. 3136 [7] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3137 January 2004. 3139 12.2. Informative References 3141 [8] Clark, J., "XSL Transformations (XSLT) Version 1.0", W3C 3142 REC REC-xslt-19991116, November 1999. 3144 [9] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 3145 RFC 2246, January 1999. 3147 [10] Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", 3148 draft-ietf-secsh-architecture-22 (work in progress), 3149 March 2005. 3151 [11] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote 3152 Authentication Dial In User Service (RADIUS)", RFC 2865, 3153 June 2000. 3155 [12] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the 3156 Use of Extensible Markup Language (XML) within IETF Protocols", 3157 BCP 70, RFC 3470, January 2003. 3159 Appendix A. NETCONF Error List 3161 Tag: in-use 3162 Error-type: protocol, application 3163 Severity: error 3164 Error-info: none 3165 Description: The request requires a resource that already in use. 3167 Tag: invalid-value 3168 Error-type: protocol, application 3169 Severity: error 3170 Error-info: none 3171 Description: The request specifies an unacceptable value for one 3172 or more parameters. 3174 Tag: too-big 3175 Error-type: transport, rpc, protocol, application 3176 Severity: error 3177 Error-info: none 3178 Description: The request or response (that would be generated) is too 3179 large for the implementation to handle. 3181 Tag: missing-attribute 3182 Error-type: rpc, protocol, application 3183 Severity: error 3184 Error-info: : name of the missing attribute 3185 : name of the element that should 3186 contain the missing attribute 3187 Description: An expected attribute is missing 3189 Tag: bad-attribute 3190 Error-type: rpc, protocol, application 3191 Severity: error 3192 Error-info: : name of the attribute w/ bad value 3193 : name of the element that contains 3194 the attribute with the bad value 3195 Description: An attribute value is not correct; e.g., wrong type, 3196 out of range, pattern mismatch 3198 Tag: unknown-attribute 3199 Error-type: rpc, protocol, application 3200 Severity: error 3201 Error-info: : name of the unexpected attribute 3202 : name of the element that contains 3203 the unexpected attribute 3204 Description: An unexpected attribute is present 3206 Tag: missing-element 3207 Error-type: rpc, protocol, application 3208 Severity: error 3209 Error-info: : name of the missing element 3210 Description: An expected element is missing 3212 Tag: bad-element 3213 Error-type: rpc, protocol, application 3214 Severity: error 3215 Error-info: : name of the element w/ bad value 3216 Description: An element value is not correct; e.g., wrong type, 3217 out of range, pattern mismatch 3219 Tag: unknown-element 3220 Error-type: rpc, protocol, application 3221 Severity: error 3222 Error-info: : name of the unexpected element 3223 Description: An unexpected element is present 3224 Tag: unknown-namespace 3225 Error-type: rpc, protocol, application 3226 Severity: error 3227 Error-info: : name of the element that contains 3228 the unexpected namespace 3229 : name of the unexpected namespace 3230 Description: An unexpected namespace is present 3232 Tag: access-denied 3233 Error-type: rpc, protocol, application 3234 Severity: error 3235 Error-info: none 3236 Description: Access to the requested RPC, protocol operation, 3237 or data model is denied because authorization failed 3239 Tag: lock-denied 3240 Error-type: protocol 3241 Severity: error 3242 Error-info: : session ID of session holding the 3243 requested lock, or zero to indicate a non-NETCONF 3244 entity holds the lock 3245 Description: Access to the requested lock is denied because the 3246 lock is currently held by another entity 3248 Tag: resource-denied 3249 Error-type: transport, rpc, protocol, application 3250 Severity: error 3251 Error-info: none 3252 Description: Request could not be completed because of insufficient 3253 resources 3255 Tag: rollback-failed 3256 Error-type: protocol, application 3257 Severity: error 3258 Error-info: none 3259 Description: Request to rollback some configuration change (via 3260 rollback-on-error or discard-changes operations) was 3261 not completed for some reason. 3263 Tag: data-exists 3264 Error-type: application 3265 Severity: error 3266 Error-info: none 3267 Description: Request could not be completed because the relevant 3268 data model content already exists. For example, 3269 a 'create' operation was attempted on data which 3270 already exists. 3272 Tag: data-missing 3273 Error-type: application 3274 Severity: error 3275 Error-info: none 3276 Description: Request could not be completed because the relevant 3277 data model content does not exist. For example, 3278 a 'replace' or 'delete' operation was attempted on 3279 data which does not exist. 3281 Tag: operation-not-supported 3282 Error-type: rpc, protocol, application 3283 Severity: error 3284 Error-info: none 3285 Description: Request could not be completed because the requested 3286 operation is not supported by this implementation. 3288 Tag: operation-failed 3289 Error-type: rpc, protocol, application 3290 Severity: error 3291 Error-info: none 3292 Description: Request could not be completed because the requested 3293 operation failed for some reason not covered by 3294 any other error condition. 3296 Tag: partial-operation 3297 Error-type: application 3298 Severity: error 3299 Error-info: : identifies an element in the data model 3300 for which the requested operation has been completed 3301 for that node and all its child nodes. This element 3302 can appear zero or more times in the 3303 container. 3305 : identifies an element in the data model 3306 for which the requested operation has failed for that 3307 node and all its child nodes. This element 3308 can appear zero or more times in the 3309 container. 3311 : identifies an element in the data model 3312 for which the requested operation was not attempted for 3313 that node and all its child nodes. This element 3314 can appear zero or more times in the 3315 container. 3317 Description: Some part of the requested operation failed or was 3318 not attempted for some reason. Full cleanup has 3319 not been performed (e.g., rollback not supported) 3320 by the server. The error-info container is used 3321 to identify which portions of the application 3322 data model content for which the requested operation 3323 has succeeded (), failed (), 3324 or not attempted (). 3326 Appendix B. XML Schema for NETCONF RPC and Protocol Operations 3328 BEGIN 3330 3331 3337 3340 3342 3343 3344 This import accesses the xml: attribute groups for the 3345 xml:lang as declared on the error-message element. 3346 3347 3348 3349 3352 3353 3354 3355 3356 3357 3360 3361 3362 3363 3364 3365 3366 3367 3368 3371 3372 3373 3374 3375 3377 3380 3381 3382 3383 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3431 3433 3435 3437 3439 3441 3442 3443 3444 3446 3448 3449 3450 3451 3452 3453 3454 3455 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3469 3470 3471 3474 3475 3476 3477 3478 3479 3481 3485 3486 3487 3488 3489 3491 3492 3493 3494 3495 3498 3499 3500 3501 3502 3503 3504 3507 3508 3509 3510 3511 Use of the rollback-on-error value requires 3512 the :rollback-on-error capability. 3513 3514 3515 3516 3517 3518 3519 3520 3524 3525 3527 3530 3531 3532 3533 3534 3535 3538 3539 3540 3541 3542 3543 3546 3547 3548 3549 3550 Use of the xpath value requires the :xpath capability. 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3562 3563 3564 3565 3568 3569 3570 The startup datastore can be used only if the :startup 3571 capability is advertised. The candidate datastore can 3572 be used only if the :candidate datastore is advertised. 3573 3574 3575 3576 3578 3580 3582 3584 3587 3588 3589 3590 3591 3592 3593 3594 3595 3597 3600 3601 3602 3603 3604 3605 3607 3608 3611 3612 3613 3614 Use of the url element requires the :url capability. 3615 3616 3617 3618 3619 3620 3621 3624 3625 3626 3627 3628 3629 3630 3631 3634 3635 3636 3637 3638 3639 3640 3643 3644 3645 3646 3647 3648 3649 3652 3653 3654 3655 3656 3658 3660 3661 3662 3663 3664 3666 3669 3670 3671 3672 3673 3674 3675 Use of the test-option element requires the 3676 :validate capability. Use of the url element 3677 requires the :url capability. 3678 3679 3680 3682 3685 3688 3691 3692 3694 3696 3697 3698 3699 3700 3701 3704 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3719 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3733 3736 3737 3738 3739 3740 3742 3743 3744 3745 3746 3748 3751 3752 3753 3754 3755 3757 3758 3759 3760 3761 3763 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3777 3780 3781 3782 3783 The validate operation requires the :validate capability. 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3796 3799 3800 3801 3802 3803 3804 3805 3806 3807 The commit operation requires the :candidate capability. 3808 3809 3810 3811 3812 3813 3814 3815 Use of the confirmed and confirm-timeout elements 3816 requires the :confirmed-commit capability. 3817 3818 3819 3820 3823 3824 3825 3826 3827 3829 3832 3833 3834 3835 The discard-changes operation requires the 3836 :candidate capability. 3837 3838 3839 3840 3841 3842 3843 3846 3849 3850 3851 3852 3853 3854 3856 3859 3860 3861 3862 3863 3865 3866 3867 3868 3869 3871 3874 3875 3876 3877 3878 3879 3880 3882 3883 3884 3885 3887 3888 3889 3890 3892 END 3894 Appendix C. Capability Template 3896 C.1. capability-name (template) 3898 C.1.1. Overview 3900 C.1.2. Dependencies 3902 C.1.3. Capability Identifier 3904 The {name} capability is identified by following capability string: 3906 {capability uri} 3908 C.1.4. New Operations 3910 C.1.4.1. 3912 C.1.5. Modifications to Existing Operations 3914 C.1.5.1. 3916 If existing operations are not modified by this capability, this 3917 section may be omitted. 3919 C.1.6. Interactions with Other Capabilities 3921 If this capability does not interact with other capabilities, this 3922 section may be omitted. 3924 Appendix D. Configuring Multiple Devices with NETCONF 3926 D.1. Operations on Individual Devices 3928 Consider the work involved in performing a configuration update 3929 against a single individual device. In making a change to the 3930 configuration, the application needs to build trust that its change 3931 has been made correctly and that it has not impacted the operation of 3932 the device. The application (and the application user) should feel 3933 confident that their change has not damaged the network. 3935 Protecting each individual device consists of a number of steps: 3937 o Acquiring the configuration lock. 3939 o Loading the update. 3941 o Validating the incoming configuration. 3943 o Checkpointing the running configuration. 3945 o Changing the running configuration. 3947 o Testing the new configuration. 3949 o Making the change permanent (if desired). 3951 o Releasing the configuration lock. 3953 Let's look at the details of each step. 3955 D.1.1. Acquiring the Configuration Lock 3957 A lock should be acquired to prevent simultaneous updates from 3958 multiple sources. If multiple sources are affecting the device, the 3959 application is hampered in both testing of its change to the 3960 configuration and in recovery should the update fail. Acquiring a 3961 short-lived lock is a simple defense to prevent other parties from 3962 introducing unrelated changes. 3964 The lock can be acquired using the operation. 3966 3968 3969 3970 3971 3972 3973 3975 D.1.2. Loading the Update 3977 The configuration can be loaded onto the device without impacting the 3978 running system. If the :url capability is supported and lists "file" 3979 as a supported scheme, incoming changes can be placed in a local 3980 file. 3982 3984 3985 3986 file://incoming.conf 3987 3988 3989 3990 3991 3992 3993 3994 3996 If the :candidate capability is supported, the candidate 3997 configuration can be used. 3999 4001 4002 4003 4004 4005 4006 4007 4008 4009 4011 If the update fails, the user file can be deleted using the operation or the candidate configuration reverted using the 4013 operation. 4015 D.1.3. Validating the Incoming Configuration 4017 Before applying the incoming configuration, it is often useful to 4018 validate it. Validation allows the application to gain confidence 4019 that the change will succeed and simplifies recovery if it does not. 4021 If the device supports the :url capability and lists "file" as a 4022 supported scheme, use the operation with the 4023 parameter set to the proper user file: 4025 4027 4028 4029 file://incoming.conf 4030 4031 4032 4034 If the device supports the :candidate capability, some validation 4035 will be performed as part of loading the incoming configuration into 4036 the candidate. For full validation, either pass the 4037 parameter during the step given above, or use the 4038 operation with the parameter set to . 4040 4042 4043 4044 4045 4046 4047 4049 D.1.4. Checkpointing the Running Configuration 4051 The running configuration can be saved into a local file as a 4052 checkpoint before loading the new configuration. If the update 4053 fails, the configuration can be restored by reloading the checkpoint 4054 file. 4056 The checkpoint file can be created using the operation. 4058 4060 4061 4062 file://checkpoint.conf 4063 4064 4065 4066 4067 4068 4070 To restore the checkpoint file, reverse the source and target 4071 parameters. 4073 D.1.5. Changing the Running Configuration 4075 When the incoming configuration has been safely loaded onto the 4076 device and validated, it is ready to impact the running system. 4078 If the device supports the :url capability and lists "file" as a 4079 supported scheme, use the operation to merge the 4080 incoming configuration into the running configuration. 4082 4084 4085 4086 4087 4088 4089 file://incoming.conf 4090 4091 4092 4094 If the device supports the :candidate capability, use the 4095 operation to set the running configuration to the candidate 4096 configuration. Use the parameter to allow automatic 4097 reverting to the original configuration if connectivity to the device 4098 fails. 4100 4102 4103 4104 120 4105 4106 4108 D.1.6. Testing the New Configuration 4110 Now that the incoming configuration has been integrated into the 4111 running configuration, the application needs to gain trust that the 4112 change has affected the device in the way intended without affecting 4113 it negatively. 4115 To gain this confidence, the application can run tests of the 4116 operational state of the device. The nature of the test is dependent 4117 on the nature of the change and is outside the scope of this 4118 document. Such tests may include reachability from the system 4119 running the application (using ping), changes in reachability to the 4120 rest of the network (by comparing the device's routing table), or 4121 inspection of the particular change (looking for operational evidence 4122 of the BGP peer that was just added). 4124 D.1.7. Making the Change Permanent 4126 When the configuration change is in place and the application has 4127 sufficient faith in the proper function of this change, the 4128 application should make the change permanent. 4130 If the device supports the :startup capability, the current 4131 configuration can be saved to the startup configuration by using the 4132 startup configuration as the target of the operation. 4134 4136 4137 4138 4139 4140 4141 4142 4143 4144 4146 If the device supports the :candidate capability and a confirmed 4147 commit was requested, the confirming commit must be sent before the 4148 timeout expires. 4150 4152 4153 4155 D.1.8. Releasing the Configuration Lock 4157 When the configuration update is complete, the lock must be released, 4158 allowing other applications access to the configuration. 4160 Use the operation to release the configuration lock. 4162 4164 4165 4166 4167 4168 4170 4172 D.2. Operations on Multiple Devices 4174 When a configuration change requires updates across a number of 4175 devices, care should be taken to provide the required transaction 4176 semantics. The NETCONF protocol contains sufficient primitives upon 4177 which transaction-oriented operations can be built. Providing 4178 complete transactional semantics across multiple devices is 4179 prohibitively expensive, but the size and number of windows for 4180 failure scenarios can be reduced. 4182 There are two classes of multidevice operations. The first class 4183 allows the operation to fail on individual devices without requiring 4184 all devices to revert to their original state. The operation can be 4185 retried at a later time, or its failure simply reported to the user. 4186 A example of this class might be adding an NTP server. For this 4187 class of operations, failure avoidance and recovery are focused on 4188 the individual device. This means recovery of the device, reporting 4189 the failure, and perhaps scheduling another attempt. 4191 The second class is more interesting, requiring that the operation 4192 should complete on all devices or be fully reversed. The network 4193 should either be transformed into a new state or be reset to its 4194 original state. For example, a change to a VPN may require updates 4195 to a number of devices. Another example of this might be adding a 4196 class-of-service definition. Leaving the network in a state where 4197 only a portion of the devices have been updated with the new 4198 definition will lead to future failures when the definition is 4199 referenced. 4201 To give transactional semantics, the same steps used in single device 4202 operations listed above are used, but are performed in parallel 4203 across all devices. Configuration locks should be acquired on all 4204 target devices and kept until all devices are updated and the changes 4205 made permanent. Configuration changes should be uploaded and 4206 validation performed across all devices. Checkpoints should be made 4207 on each device. Then the running configuration can be changed, 4208 tested, and made permanent. If any of these steps fail, the previous 4209 configurations can be restored on any devices upon which it was 4210 changed. After the changes have been completely implemented or 4211 completely discarded, the locks on each device can be released. 4213 Appendix E. Deferred Features 4215 The following features have been deferred until a future revision of 4216 this document. 4218 o Granular locking of configuration objects. 4220 o Named configuration files/datastores. 4222 o Support for multiple NETCONF channels. 4224 o Asynchronous notifications. 4226 o Explicit protocol support for rollback of configuration changes to 4227 prior versions. 4229 Appendix F. Change Log 4231 RFC Editor: Please remove this section before RFC publication. 4233 F.1. draft-ietf-netconf-prot-12 4235 o s/as/instead of/ to indicate that the element can replace 4236 the element. 4238 o Add further discussion of element to section 5.2. 4240 o Expand description of config parameter to edit-config. 4242 o Update XSD to fix complaints from IBM XML schema checker. 4244 o Replace privacy with confidentiality. 4246 o Change "permission denied" to "access denied" in security 4247 considerations. 4249 o Update content for unknown-namespace error. 4251 F.2. draft-ietf-netconf-prot-11 4253 o Update authors and acknowledgements. 4255 o Clarify that restrictions on locking a modified configuration 4256 apply to the candidate configuration. 4258 o Update IANA considerations. New NETCONF capabilities require IETF 4259 Standards Action. 4261 o Target should be the first parameter to . 4263 o Maximum length of the message-id attribute is 4095. 4265 o Update Section 4.4 to indicate that is sent only if no errors 4266 OR WARNINGS occur. 4268 o Update type in XSD. 4270 o Update sections 8.9.1 and 4.3 to indicate what namespace 4271 declarations are in scope for XPath expressions. 4273 o is an unsignedInt with minimum of 1. 4275 o Added a section indicating data model issues are outside scope. 4277 o Minor clarifications to subtree filtering. 4279 o XML namespace in filter can be used to select different formats of 4280 configuration data frmo device. 4282 o More detail on why is a separate operation. 4284 o More detail on behavior of candidate configuration. 4286 o More detail on :startup capability. 4288 o Refer to the layer on which NETCONF rides as "transport" (rather 4289 than an inconsistent use of both transport and application). 4291 o URL capability uses URL "schemes". 4293 o New XSD ype SessionIdOrZero used in errors. 4295 o Change ignore-error to continue-on-error. 4297 F.3. draft-ietf-netconf-prot-10 4299 o Typo, s/modify/replace/ in data-missing error. 4301 o Update URI reference to RFC3986. 4303 o Update IANA considerations. New NETCONF capabilities require IETF 4304 approval. 4306 o Correct inconsistency in Section 7.1. parameter is 4307 mandatory. 4309 o Update Appendix C to use a placeholder for the capability URI. 4311 o Ask IANA to register (not assign) an XML namespace and schema URI 4312 in IANA considerations. 4314 o Remove errorInfoContent from XSD. 4316 o Clarify description of operation in Section 8.3. 4318 F.4. draft-ietf-netconf-prot-09 4320 o Minor spelling and grammar corrections. 4322 o Add a table enumerating all capability identifiers to IANA 4323 considerations. 4325 o Clarify that does in fact roll back changes if 4326 received during a confirmed commit. 4328 o In IANA considerations, request ...:netconf:base:1.0 as the 4329 NETCONF namespace. 4331 F.5. draft-ietf-netconf-prot-08 4333 o Second example was missing message-id attribute. 4335 o Fix namespace in section Section 6.2.2. 4337 o Fix namespaces in examples in sections 6.4.8 and 7.7. 4339 o Edit Section 6.2.3 for clarification. 4341 o Change "committed" to "running" in Section 8.3.4.2. 4343 o Convert example addresses to use the range 192.0.2.0/24. 4345 o Clarify optional support of as target of . 4347 o Clarify that does not restore configuration or 4348 device state. 4350 o Clarify that both client and server must send a element 4351 with capabilities. 4353 o NETCONF over SSH is mandatory. 4355 o Add IANA considerations. 4357 o Add BEGIN/END markers to NETCONF XML schema per RFC 3688. 4359 o NETCONF capability URNs should be in the protocol parameters 4360 namespace as described in RFC 3553. 4362 F.6. draft-ietf-netconf-prot-07 4364 o Add clarifying text to :confirmed-commit capability. 4366 o Change units of 'confirm-timeout' parameter to seconds. 4368 o Type confirm-timeout element as a positiveInteger in the XSD. 4370 o Update XSD to allow element in as required by 4371 :url capability. 4373 o Denote attribute names with single quotes in the text; some cases 4374 were missed. 4376 o Update to state that the server must not return data 4377 that the client has no access rights on. 4379 o [XMLDir] Moderate use of the term API. 4381 o [XMLDir] Clarify capability naming requirements in Section 3.1. 4383 o [XMLDir] Remove "DTD" acronym from Section 3.2. 4385 o [XMLDir] Remove # naming scheme from capability URNs. 4387 o Error code when a lock is in use is 'lock-denied'. 4389 F.7. draft-ietf-netconf-prot-06 4391 o Allow an xml:lang attribute in the tag. 4393 o Update XSD to permit artibrary attributes on and . 4396 o Add example showing retrieval of textual configuration to . 4399 o Indicate that URLs passed to should be local. 4401 o Update example to use https. 4403 o Update description to explicitly allow multiple elements. Add example. Update XSD. 4406 o Incorporate clarifying text on subtree filtering. 4408 o Annotate XSD with capability information. 4410 o Make error tags lower case separated with dashes. 4412 o Add unknown-namespace error tag. 4414 o Add text expliticly stating that a server must discontinue the 4415 NETCONF session if it receives a element, and 4416 similarly a client must discontinue if it does not receive one. 4418 F.8. draft-ietf-netconf-prot-05 4420 o Change XPATH to XPath. 4422 o Fix I-D nits (mostly long lines). 4424 o Remove "--" from XSD comments. 4426 o Add attribute where it was missing in 4427 examples. 4429 o Clarified Section 8.1 by indicating that each peer MUST send a 4430 element at session startup. 4432 o Typo propriety -> proprietary in Section 8. 4434 o Fix some bugs in examples. 4436 o Section 7.1: typo: change to in the positive 4437 response section. 4439 o Section 7.1: If is unspecified, the entire configuration 4440 is returned. If it is empty, nothing is returned. 4442 o Be explicit about being atomic. 4444 o s/MAY/SHOULD/ wrt supporting more than one NETCONF session. 4446 o Strengthen language to say that NETCONF requests MUST be processed 4447 serially. 4449 o Fix misspelling of "unbeknownst." 4451 o Change "Expect scripts" to "CLI scripts" in Section 7.5. 4453 o Change "system software" to "device" in Section 1.3. 4455 o The element must also include the session ID (issue I002). 4457 o Address all accepted clarifications from working group last call. 4458 See the NETCONF mailing list for details. 4460 o Address all closed issues from working group last call. See the 4461 NETCONF mailing list for details. 4463 F.9. draft-ietf-netconf-prot-04 4465 Refer to the NETCONF issue list for futher detail on the issue 4466 numbers below. The issue list is found at 4467 http://www.nextbeacon.com/netconf/. 4469 o Update security considerations (action from IETF 60). 4471 o Add type attribute on filter element (issue 14.1). 4473 o Add #xpath capability (issue 14.1). 4475 o for returns element, not 4476 element (issue 14.1). 4478 o Add detailed description of subtree filtering (issue 14.1.2). 4480 o Typo: change confirmed-timeout -> confirm-timeout in XSD. 4482 o Typo: correct misnaming of test-option parameter in text for the 4483 validate capability. 4485 o is now a mandatory parameter for and . 4486 There is no default target (action from IETF 60). 4488 o Remove XML schema for NETCONF state data (action from IETF 60). 4490 o Correct namespace handling a number of examples. The fix is to 4491 put the device's configuration under a top level tag called 4492 which is in the device's namespace. 4494 o Use message-id 101 everywhere. 4496 o Add default-operation parameter to (action from IETF 4497 60). 4499 o Fix examples in Appendix D. 4501 o Update and reformat protocol XSD. 4503 o Remove XML usage guidelines. Add a section on XML considerations 4504 covering the NETCONF namespace and no DTD restriction (action from 4505 IETF 60). 4507 F.10. draft-ietf-netconf-prot-03 4509 Refer to the NETCONF issue list for futher detail on the issue 4510 numbers below. The issue list is found at 4511 http://www.nextbeacon.com/netconf/. 4513 o Consistent naming of element. 4515 o Add #confirmed-commit capability (issue 10.3.2) 4517 o Use a URN for the NETCONF namespace (issue 11.1.2) and 4518 capabilities 4520 o Remove #manager capability (issue 11.2.1) 4522 o Remove #agent capability (issue 11.2.2) 4524 o Add "create" as a value for the operation attribute in (issue 13.3.1) 4527 o Add #rollback-on-error capability (issue 13.3.2) 4529 o Rename operation to . 4531 o Remove format parameter from two and one 4532 examples missed in the -02 draft (issue 13.3.3). 4534 o Add text indicating that the session-id is returned if the lock is 4535 already held (issue 13.12.3). Add example of this. 4537 o Remove parameter on the operation (issue 4538 13.16.1), all outstanding changes are to be discarded when the 4539 candidate configuration is unlocked. 4541 o Remove section 8.7, guidelines on namespace construction. 4543 o Add clarifying text regarding locks held by other entities. 4545 o Update the abstract. 4547 o Remove mention of the format parameter from the and 4548 operations and the XSD. 4550 o Updated security considerations section. 4552 o Removed terminology section, moved session description to protocol 4553 overview section. 4555 o New text describing . 4557 o Updated NETCONF protocol schema (to reflect new 4558 details, among other things). 4560 o Add parameter to and . Rename 4561 response the operation to . 4563 o Better description of the operation. 4565 o Add operation. 4567 o Removed format parameter to . 4569 o Removed restriction that a changed configuration 4570 datastore can't be locked. 4572 o Add note in section 2 that the transport protocol must provide an 4573 indication of session type (manager or agent) to the NETCONF 4574 layer. 4576 F.11. draft-ietf-netconf-prot-02 4578 Refer to the NETCONF issue list for futher detail on the issue 4579 numbers below. The issue list is found at 4580 http://www.nextbeacon.com/netconf/. 4582 o Remove , , and (issues 4583 12.1, 12.2, 12.3). 4585 o Remove channels (issues 3.*). 4587 o Remove notifications (issues 2.*, 4.2, 13.9, 13.10, 13.11). 4589 o Move version number to last component of the capability URI (issue 4590 11.1.1). 4592 o Remove format parameter from (issue 13.3.3). 4594 o Remove mention of #lock capability from Appendix D. Locking is a 4595 mandatory NETCONF operation. 4597 o Added text indicating that attributes received in should be 4598 echoed on (issue 16.1). 4600 o Reworded Section 7.3 to encourage always prefixing attributes with 4601 namespaces. 4603 Author's Address 4605 Rob Enns (editor) 4606 Juniper Networks 4607 1194 North Mathilda Ave 4608 Sunnyvale, CA 94089 4609 US 4611 Email: rpe@juniper.net 4613 Intellectual Property Statement 4615 The IETF takes no position regarding the validity or scope of any 4616 Intellectual Property Rights or other rights that might be claimed to 4617 pertain to the implementation or use of the technology described in 4618 this document or the extent to which any license under such rights 4619 might or might not be available; nor does it represent that it has 4620 made any independent effort to identify any such rights. Information 4621 on the procedures with respect to rights in RFC documents can be 4622 found in BCP 78 and BCP 79. 4624 Copies of IPR disclosures made to the IETF Secretariat and any 4625 assurances of licenses to be made available, or the result of an 4626 attempt made to obtain a general license or permission for the use of 4627 such proprietary rights by implementers or users of this 4628 specification can be obtained from the IETF on-line IPR repository at 4629 http://www.ietf.org/ipr. 4631 The IETF invites any interested party to bring to its attention any 4632 copyrights, patents or patent applications, or other proprietary 4633 rights that may cover technology that may be required to implement 4634 this standard. Please address the information to the IETF at 4635 ietf-ipr@ietf.org. 4637 Disclaimer of Validity 4639 This document and the information contained herein are provided on an 4640 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4641 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 4642 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 4643 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 4644 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4645 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4647 Copyright Statement 4649 Copyright (C) The Internet Society (2006). This document is subject 4650 to the rights, licenses and restrictions contained in BCP 78, and 4651 except as set forth therein, the authors retain all their rights. 4653 Acknowledgment 4655 Funding for the RFC Editor function is currently provided by the 4656 Internet Society.