idnits 2.17.1 draft-ietf-netconf-4741bis-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. 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 IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 14, 2011) is 4785 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) == Outdated reference: A later version (-08) exists of draft-ietf-netconf-rfc4742bis-07 ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) -- Obsolete informational reference (is this intentional?): RFC 4741 (Obsoleted by RFC 6241) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 4 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 Obsoletes: 4741 (if approved) M. Bjorklund, Ed. 5 Intended status: Standards Track Tail-f Systems 6 Expires: September 15, 2011 J. Schoenwaelder, Ed. 7 Jacobs University 8 A. Bierman, Ed. 9 Brocade 10 March 14, 2011 12 Network Configuration Protocol (NETCONF) 13 draft-ietf-netconf-4741bis-10 15 Abstract 17 The Network Configuration Protocol (NETCONF) defined in this document 18 provides mechanisms to install, manipulate, and delete the 19 configuration of network devices. It uses an Extensible Markup 20 Language (XML)-based data encoding for the configuration data as well 21 as the protocol messages. The NETCONF protocol operations are 22 realized as Remote Procedure Calls (RPC). This document obsoletes 23 RFC 4741. 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on September 15, 2011. 42 Copyright Notice 44 Copyright (c) 2011 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 This document may contain material from IETF Documents or IETF 58 Contributions published or made publicly available before November 59 10, 2008. The person(s) controlling the copyright in some of this 60 material may not have granted the IETF Trust the right to allow 61 modifications of such material outside the IETF Standards Process. 62 Without obtaining an adequate license from the person(s) controlling 63 the copyright in such materials, this document may not be modified 64 outside the IETF Standards Process, and derivative works of it may 65 not be created outside the IETF Standards Process, except to format 66 it for publication as an RFC or to translate it into languages other 67 than English. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 72 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 73 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8 74 1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . 10 75 1.4. Separation of Configuration and State Data . . . . . . . 10 76 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 12 77 2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 12 78 2.2. Authentication, Integrity, and Confidentiality . . . . . 12 79 2.3. Mandatory Transport Protocol . . . . . . . . . . . . . . 13 80 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 14 81 3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 14 82 3.2. Document Type Declarations . . . . . . . . . . . . . . . 14 83 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 15 84 4.1. Element . . . . . . . . . . . . . . . . . . . . . . 15 85 4.2. Element . . . . . . . . . . . . . . . . . . . 16 86 4.3. Element . . . . . . . . . . . . . . . . . . . 17 87 4.4. Element . . . . . . . . . . . . . . . . . . . . . . 20 88 4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 21 89 5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 22 90 5.1. Configuration Datastores . . . . . . . . . . . . . . . . 22 91 5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 22 92 6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 23 93 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 23 94 6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 23 95 6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 24 96 6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 24 97 6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 25 98 6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 25 99 6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 26 100 6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 27 101 6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 28 102 6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 28 103 6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 28 104 6.4.3. Select the Entire Subtree . . . . . . . . . . 29 105 6.4.4. Select All Elements within the 106 Subtree . . . . . . . . . . . . . . . . . . . . . . . 31 107 6.4.5. One Specific Entry . . . . . . . . . . . . . . 32 108 6.4.6. Specific Elements from a Specific Entry . . . 33 109 6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 34 110 6.4.8. Elements with Attribute Naming . . . . . . . . . . . 36 111 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 38 112 7.1. . . . . . . . . . . . . . . . . . . . . . . 38 113 7.2. . . . . . . . . . . . . . . . . . . . . . . 40 114 7.3. . . . . . . . . . . . . . . . . . . . . . . 47 115 7.4. . . . . . . . . . . . . . . . . . . . . . 49 116 7.5. . . . . . . . . . . . . . . . . . . . . . . . . . 49 117 7.6. . . . . . . . . . . . . . . . . . . . . . . . . 52 118 7.7. . . . . . . . . . . . . . . . . . . . . . . . . . . 53 119 7.8. . . . . . . . . . . . . . . . . . . . . . 55 120 7.9. . . . . . . . . . . . . . . . . . . . . . 56 121 8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 58 122 8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 58 123 8.2. Writable-Running Capability . . . . . . . . . . . . . . . 59 124 8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 59 125 8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 59 126 8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 59 127 8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 60 128 8.2.5. Modifications to Existing Operations . . . . . . . . 60 129 8.3. Candidate Configuration Capability . . . . . . . . . . . 60 130 8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 60 131 8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 61 132 8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 61 133 8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 61 134 8.3.5. Modifications to Existing Operations . . . . . . . . 62 135 8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 63 136 8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 63 137 8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65 138 8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 65 139 8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 65 140 8.4.5. Modifications to Existing Operations . . . . . . . . 66 141 8.5. Rollback on Error Capability . . . . . . . . . . . . . . 68 142 8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 68 143 8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 69 144 8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 69 145 8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 69 146 8.5.5. Modifications to Existing Operations . . . . . . . . 69 147 8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 70 148 8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 70 149 8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 70 150 8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 70 151 8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 70 152 8.6.5. Modifications to Existing Operations . . . . . . . . 71 153 8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 71 154 8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 71 155 8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 72 156 8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 72 157 8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 72 158 8.7.5. Modifications to Existing Operations . . . . . . . . 72 159 8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 73 160 8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 73 161 8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 73 162 8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 73 163 8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 73 164 8.8.5. Modifications to Existing Operations . . . . . . . . 73 166 8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 74 167 8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 74 168 8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 75 169 8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 75 170 8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 75 171 8.9.5. Modifications to Existing Operations . . . . . . . . 75 172 9. Security Considerations . . . . . . . . . . . . . . . . . . . 77 173 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 174 10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 79 175 10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 79 176 10.3. NETCONF YANG Module . . . . . . . . . . . . . . . . . . . 79 177 10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 79 178 11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 81 179 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 180 12.1. Normative References . . . . . . . . . . . . . . . . . . 82 181 12.2. Informative References . . . . . . . . . . . . . . . . . 83 182 Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 84 183 Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 88 184 Appendix C. YANG Module for NETCONF Protocol Operations . . . . 93 185 Appendix D. Capability Template . . . . . . . . . . . . . . . . 113 186 D.1. capability-name (template) . . . . . . . . . . . . . . . 113 187 D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 113 188 D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 113 189 D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 113 190 D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 113 191 D.1.5. Modifications to Existing Operations . . . . . . . . 113 192 D.1.6. Interactions with Other Capabilities . . . . . . . . 113 193 Appendix E. Configuring Multiple Devices with NETCONF . . . . . 114 194 E.1. Operations on Individual Devices . . . . . . . . . . . . 114 195 E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 114 196 E.1.2. Checkpointing the Running Configuration . . . . . . . 115 197 E.1.3. Loading and Validating the Incoming Configuration. . 116 198 E.1.4. Changing the Running Configuration . . . . . . . . . 116 199 E.1.5. Testing the New Configuration . . . . . . . . . . . . 117 200 E.1.6. Making the Change Permanent . . . . . . . . . . . . . 117 201 E.1.7. Releasing the Configuration Lock . . . . . . . . . . 118 202 E.2. Operations on Multiple Devices . . . . . . . . . . . . . 119 203 Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 120 204 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 121 206 1. Introduction 208 The NETCONF protocol defines a simple mechanism through which a 209 network device can be managed, configuration data information can be 210 retrieved, and new configuration data can be uploaded and 211 manipulated. The protocol allows the device to expose a full, formal 212 application programming interface (API). Applications can use this 213 straightforward API to send and receive full and partial 214 configuration data sets. 216 The NETCONF protocol uses a remote procedure call (RPC) paradigm. A 217 client encodes an RPC in XML [W3C.REC-xml-20001006] and sends it to a 218 server using a secure, connection-oriented session. The server 219 responds with a reply encoded in XML. The contents of both the 220 request and the response are fully described in XML DTDs or XML 221 schemas, or both, allowing both parties to recognize the syntax 222 constraints imposed on the exchange. 224 A key aspect of NETCONF is that it allows the functionality of the 225 management protocol to closely mirror the native functionality of the 226 device. This reduces implementation costs and allows timely access 227 to new features. In addition, applications can access both the 228 syntactic and semantic content of the device's native user interface. 230 NETCONF allows a client to discover the set of protocol extensions 231 supported by a server. These "capabilities" permit the client to 232 adjust its behavior to take advantage of the features exposed by the 233 device. The capability definitions can be easily extended in a 234 noncentralized manner. Standard and non-standard capabilities can be 235 defined with semantic and syntactic rigor. Capabilities are 236 discussed in Section 8. 238 The NETCONF protocol is a building block in a system of automated 239 configuration. XML is the lingua franca of interchange, providing a 240 flexible but fully specified encoding mechanism for hierarchical 241 content. NETCONF can be used in concert with XML-based 242 transformation technologies, such as XSLT [W3C.REC-xslt-19991116], to 243 provide a system for automated generation of full and partial 244 configurations. The system can query one or more databases for data 245 about networking topologies, links, policies, customers, and 246 services. This data can be transformed using one or more XSLT 247 scripts from a task-oriented, vendor-independent data schema into a 248 form that is specific to the vendor, product, operating system, and 249 software release. The resulting data can be passed to the device 250 using the NETCONF protocol. 252 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 253 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 254 document are to be interpreted as described in RFC 2119 [RFC2119]. 256 1.1. Terminology 258 o candidate configuration datastore: A configuration datastore that 259 can be manipulated without impacting the device's current 260 configuration and that can be committed to the running 261 configuration datastore. Not all devices support a candidate 262 configuration datastore. 264 o capability: A functionality that supplements the base NETCONF 265 specification. 267 o client: A client invokes protocol operations on a server. In 268 addition, a client can subscribe to receive notifications from a 269 server. 271 o configuration data: Configuration data is the set of writable data 272 that is required to transform a system from its initial default 273 state into its current state. 275 o datastore: A conceptual place to store and access information. A 276 datastore might be implemented, for example, using files, a 277 database, flash memory locations or combinations thereof. 279 o configuration datastore: A configuration datastore is defined as 280 the datastore holding the complete set of configuration data that 281 is required to get a device from its initial default state into a 282 desired operational state. 284 o message: A protocol element sent over a session. Messages are 285 well-formed XML documents. 287 o notification: A server initiated message indicating that a certain 288 event has been recognized by the server. 290 o protocol operation: A specific remote procedure call, as used 291 within the NETCONF protocol. 293 o remote procedure call: A remote procedure call (RPC), realized by 294 exchanging and messages. 296 o running configuration datastore: A configuration datastore holding 297 the complete configuration currently active on the device. The 298 running configuration datastore always exists. 300 o server: A server executes protocol operations invoked by a client. 301 In addition, a server can send notifications to a client. 303 o session: Client and server exchange messages using a secure, 304 connection-oriented session. 306 o startup configuration datastore: The configuration datastore 307 holding the configuration loaded by the device when it boots. 308 Only present on devices that separate the startup configuration 309 datastore from the running configuration datastore. 311 o state data: State data is the additional data on a system that is 312 not configuration data such as read-only status information and 313 collected statistics. 315 o user: The authenticated identity of the client. The authenticated 316 identity of a client is commonly referred to as the NETCONF 317 username. 319 1.2. Protocol Overview 321 NETCONF uses a simple RPC-based mechanism to facilitate communication 322 between a client and a server. The client can be a script or 323 application typically running as part of a network manager. The 324 server is typically a network device. The terms "device" and 325 "server" are used interchangeably in this document, as are "client" 326 and "application". 328 A NETCONF session is the logical connection between a network 329 administrator or network configuration application and a network 330 device. A device MUST support at least one NETCONF session and 331 SHOULD support multiple sessions. Global configuration attributes 332 can be changed during any authorized session, and the effects are 333 visible in all sessions. Session-specific attributes affect only the 334 session in which they are changed. 336 NETCONF can be conceptually partitioned into four layers as shown in 337 Figure 1. 339 Layer Example 340 +-------------+ +-----------------+ +----------------+ 341 (4) | Content | | Configuration | | Notification | 342 | | | data | | data | 343 +-------------+ +-----------------+ +----------------+ 344 | | | 345 +-------------+ +-----------------+ | 346 (3) | Operations | | | | 347 | | | | | 348 +-------------+ +-----------------+ | 349 | | | 350 +-------------+ +-----------------+ +----------------+ 351 (2) | Messages | | , | | | 352 | | | | | | 353 +-------------+ +-----------------+ +----------------+ 354 | | | 355 +-------------+ +-----------------------------------------+ 356 (1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... | 357 | Transports | | | 358 +-------------+ +-----------------------------------------+ 360 Figure 1: NETCONF Protocol Layers 362 1. The Secure Transport layer provides a communication path between 363 the client and server. NETCONF can be layered over any transport 364 protocol that provides a set of basic requirements. Section 2 365 discusses these requirements. 367 2. The Messages layer provides a simple, transport-independent 368 framing mechanism for encoding RPCs and notifications. Section 4 369 documents the RPC messages, and [RFC5717] documents 370 notifications. 372 3. The Operations layer defines a set of base protocol operations 373 invoked as RPC methods with XML-encoded parameters. Section 7 374 details the list of base protocol operations. 376 4. The Content layer is outside the scope of this document. It is 377 expected that separate efforts to standardize NETCONF data models 378 will be undertaken. 380 The YANG data modeling language [RFC6020] has been developed for 381 specifying NETCONF data models and protocol operations, covering the 382 Operations and the Content layers of Figure 1. 384 1.3. Capabilities 386 A NETCONF capability is a set of functionality that supplements the 387 base NETCONF specification. The capability is identified by a 388 uniform resource identifier (URI) [RFC3986]. 390 Capabilities augment the base operations of the device, describing 391 both additional operations and the content allowed inside operations. 392 The client can discover the server's capabilities and use any 393 additional operations, parameters, and content defined by those 394 capabilities. 396 The capability definition might name one or more dependent 397 capabilities. To support a capability, the server MUST support any 398 capabilities upon which it depends. 400 Section 8 defines the capabilities exchange that allows the client to 401 discover the server's capabilities. Section 8 also lists the set of 402 capabilities defined in this document. 404 Additional capabilities can be defined at any time in external 405 documents, allowing the set of capabilities to expand over time. 406 Standards bodies can define standardized capabilities, and 407 implementations can define proprietary ones. A capability URI MUST 408 sufficiently distinguish the naming authority to avoid naming 409 collisions. 411 1.4. Separation of Configuration and State Data 413 The information that can be retrieved from a running system is 414 separated into two classes, configuration data and state data. 415 Configuration data is the set of writable data that is required to 416 transform a system from its initial default state into its current 417 state. State data is the additional data on a system that is not 418 configuration data such as read-only status information and collected 419 statistics. When a device is performing configuration operations, a 420 number of problems would arise if state data were included: 422 o Comparisons of configuration data sets would be dominated by 423 irrelevant entries such as different statistics. 425 o Incoming data could contain nonsensical requests, such as attempts 426 to write read-only data. 428 o The data sets would be large. 430 o Archived data could contain values for read-only data items, 431 complicating the processing required to restore archived data. 433 To account for these issues, the NETCONF protocol recognizes the 434 difference between configuration data and state data and provides 435 operations for each. The operation retrieves 436 configuration data only, while the operation retrieves 437 configuration and state data. 439 Note that the NETCONF protocol is focused on the information required 440 to get the device into its desired running state. The inclusion of 441 other important, persistent data is implementation specific. For 442 example, user files and databases are not treated as configuration 443 data by the NETCONF protocol. 445 For example, if a local database of user authentication data is 446 stored on the device, it is an implementation-dependent matter 447 whether it is included in configuration data. 449 2. Transport Protocol Requirements 451 NETCONF uses an RPC-based communication paradigm. A client sends a 452 series of one or more RPC request messages, which cause the server to 453 respond with a corresponding series of RPC reply messages. 455 The NETCONF protocol can be layered on any transport protocol that 456 provides the required set of functionality. It is not bound to any 457 particular transport protocol, but allows a mapping to define how it 458 can be implemented over any specific protocol. 460 The transport protocol MUST provide a mechanism to indicate the 461 session type (client or server) to the NETCONF protocol layer. 463 This section details the characteristics that NETCONF requires from 464 the underlying transport protocol. 466 2.1. Connection-Oriented Operation 468 NETCONF is connection-oriented, requiring a persistent connection 469 between peers. This connection MUST provide reliable, sequenced data 470 delivery. NETCONF connections are long-lived, persisting between 471 protocol operations. 473 In addition, resources requested from the server for a particular 474 connection MUST be automatically released when the connection closes, 475 making failure recovery simpler and more robust. For example, when a 476 lock is acquired by a client, the lock persists until either it is 477 explicitly released or the server determines that the connection has 478 been terminated. If a connection is terminated while the client 479 holds a lock, the server can perform any appropriate recovery. The 480 operation is further discussed in Section 7.5. 482 2.2. Authentication, Integrity, and Confidentiality 484 NETCONF connections MUST provide authentication, data integrity, 485 confidentiality, and replay protection. NETCONF depends on the 486 transport protocol for this capability. A NETCONF peer assumes that 487 appropriate levels of security and confidentiality are provided 488 independently of this document. For example, connections could be 489 encrypted using TLS [RFC5246] or SSH [RFC4251], depending on the 490 underlying protocol. 492 NETCONF connections MUST be authenticated. The transport protocol is 493 responsible for authentication of the server to the client and 494 authentication of the client to the server. A NETCONF peer assumes 495 that the connection's authentication information has been validated 496 by the underlying transport protocol using sufficiently trustworthy 497 mechanisms and that the peer's identity has been sufficiently proven. 499 One goal of NETCONF is to provide a programmatic interface to the 500 device that closely follows the functionality of the device's native 501 interface. Therefore, it is expected that the underlying protocol 502 uses existing authentication mechanisms available on the device. For 503 example, a NETCONF server on a device that supports RADIUS [RFC2865] 504 might allow the use of RADIUS to authenticate NETCONF sessions. 506 The authentication process MUST result in an authenticated client 507 identity whose permissions are known to the server. The 508 authenticated identity of a client is commonly referred to as the 509 NETCONF username. The username is a string of characters that match 510 the "Char" production from section 2.2 of [W3C.REC-xml-20001006] . 511 The algorithm used to derive the username is transport protocol 512 specific and in addition specific to the authentication mechanism 513 used by the transport protocol. The transport protocol MUST provide 514 a username to be used by the other NETCONF layers. 516 The access permissions of a given client, identified by its NETCONF 517 username, are part of the configuration of the NETCONF server. These 518 permissions MUST be enforced during the remainder of the NETCONF 519 session. The details how access control is configured is outside the 520 scope of this document. 522 2.3. Mandatory Transport Protocol 524 A NETCONF implementation MUST support the SSH transport protocol 525 mapping [I-D.ietf-netconf-rfc4742bis]. 527 3. XML Considerations 529 XML serves as the encoding format for NETCONF, allowing complex 530 hierarchical data to be expressed in a text format that can be read, 531 saved, and manipulated with both traditional text tools and tools 532 specific to XML. 534 All NETCONF messages MUST be well-formed XML, encoded in UTF-8 535 [RFC3629]. If a peer receives an message that is not well- 536 formed XML or not encoded in UTF-8, it SHOULD reply with a 537 "malformed-message" error. If a reply cannot be sent for any reason, 538 the server MUST terminate the session. 540 A NETCONF message MAY begin with an XML declaration (see section 2.8 541 of [W3C.REC-xml-20001006]). 543 This section discusses a small number of XML-related considerations 544 pertaining to NETCONF. 546 3.1. Namespace 548 All NETCONF protocol elements are defined in the following namespace: 550 urn:ietf:params:xml:ns:netconf:base:1.0 552 NETCONF capability names MUST be URIs [RFC3986]. NETCONF 553 capabilities are discussed in Section 8. 555 3.2. Document Type Declarations 557 Document type declarations (see section 2.8 of 558 [W3C.REC-xml-20001006]) MUST NOT appear in NETCONF content. 560 4. RPC Model 562 The NETCONF protocol uses an RPC-based communication model. NETCONF 563 peers use and elements to provide transport 564 protocol-independent framing of NETCONF requests and responses. 566 The syntax and XML encoding of the Messages layer RPCs are formally 567 defined in the XML schema in Appendix B. 569 4.1. Element 571 The element is used to enclose a NETCONF request sent from the 572 client to the server. 574 The element has a mandatory attribute "message-id", which is a 575 string chosen by the sender of the RPC that will commonly encode a 576 monotonically increasing integer. The receiver of the RPC does not 577 decode or interpret this string but simply saves it to be used as a 578 "message-id" attribute in any resulting message. The 579 sender MUST ensure that the "message-id" value is normalized 580 according to the XML attribute value normalization rules defined in 581 [W3C.REC-xml-20001006] if the sender wants the string to be returned 582 unmodified. For example: 584 586 587 588 589 591 If additional attributes are present in an element, a NETCONF 592 peer MUST return them unmodified in the element. This 593 includes any "xmlns" attributes. 595 The name and parameters of an RPC are encoded as the contents of the 596 element. The name of the RPC is an element directly inside the 597 element, and any parameters are encoded inside this element. 599 The following example invokes a method called , which 600 has two parameters, , with a value of "14", and 601 , with a value of "fred": 603 605 606 14 607 fred 608 609 611 The following example invokes a method with a 612 parameter of "27606-0100": 614 616 617 27606-0100 618 619 621 The following example invokes the NETCONF method with no 622 parameters: 624 626 627 629 4.2. Element 631 The message is sent in response to an message. 633 The element has a mandatory attribute "message-id", which 634 is equal to the "message-id" attribute of the for which this is 635 a response. 637 A NETCONF server MUST also return any additional attributes included 638 in the element unmodified in the element. 640 The response data is encoded as one or more child elements to the 641 element. 643 For example: 645 The following element invokes the NETCONF method and 646 includes an additional attribute called "user-id". Note that the 647 "user-id" attribute is not in the NETCONF namespace. The returned 648 element returns the "user-id" attribute, as well as the 649 requested content. 651 655 656 658 662 663 664 665 667 4.3. Element 669 The element is sent in messages if an error 670 occurs during the processing of an request. 672 If a server encounters multiple errors during the processing of an 673 request, the MAY contain multiple 674 elements. However, a server is not required to detect or report more 675 than one element, if a request contains multiple errors. 676 A server is not required to check for particular error conditions in 677 a specific sequence. A server MUST return an element if 678 any error conditions occur during processing. 680 A server MUST NOT return application-level- or data-model-specific 681 error information in an element for which the client does 682 not have sufficient access rights. 684 The element includes the following information: 686 error-type: Defines the conceptual layer that the error occurred. 687 Enumeration. One of: 689 * transport (layer: Secure Transport) 691 * rpc (layer: Messages) 693 * protocol (layer: Operations) 695 * application (layer: Content) 697 error-tag: Contains a string identifying the error condition. See 698 Appendix A for allowed values. 700 error-severity: Contains a string identifying the error severity, as 701 determined by the device. One of: 703 * error 705 * warning 707 Note that there are no values defined in this document 708 which utilize the "warning" enumeration. This is reserved for 709 future use. 711 error-app-tag: Contains a string identifying the data-model-specific 712 or implementation-specific error condition, if one exists. This 713 element will not be present if no appropriate application error 714 tag can be associated with a particular error condition. If a 715 data-model specific and a implementation-specific error-app-tag 716 both exist, then the data-model specific value MUST be used by the 717 server. 719 error-path: Contains the absolute XPath [W3C.REC-xpath-19991116] 720 expression identifying the element path to the node that is 721 associated with the error being reported in a particular 722 element. This element will not be present if no 723 appropriate payload element or datastore node can be associated 724 with a particular error condition. 726 The XPath expression is interpreted in the following context: 728 * The set of namespace declarations are those in scope on the 729 element. 731 * The set of variable bindings is empty. 733 * The function library is the core function library. 735 The context node depends on the node associated with the error 736 being reported: 738 * If a payload element can be associated with the error, the 739 context node is the rpc request's document node (i.e., the 740 element). 742 * Otherwise, the context node is the root of all data models, 743 i.e., the node which has the top-level nodes from all data 744 models as children. 746 error-message: Contains a string suitable for human display that 747 describes the error condition. This element will not be present 748 if no appropriate message is provided for a particular error 749 condition. This element SHOULD include an "xml:lang" attribute as 750 defined in [W3C.REC-xml-20001006] and discussed in [RFC3470]. 752 error-info: Contains protocol- or data-model-specific error content. 753 This element will not be present if no such error content is 754 provided for a particular error condition. The list in Appendix A 755 defines any mandatory error-info content for each error. After 756 any protocol-mandated content, a data model definition MAY mandate 757 that certain application-layer error information be included in 758 the error-info container. An implementation MAY include 759 additional elements to provide extended and/or implementation- 760 specific debugging information. 762 Appendix A enumerates the standard NETCONF errors. 764 Example: 766 An error is returned if an element is received without a 767 "message-id" attribute. Note that only in this case is it 768 acceptable for the NETCONF peer to omit the "message-id" attribute 769 in the element. 771 772 773 774 775 776 777 779 780 781 rpc 782 missing-attribute 783 error 784 785 message-id 786 rpc 787 788 789 791 The following illustrates the case of returning multiple 792 elements. 794 Note that the data models used in the examples in this section use 795 the element to distinguish between multiple instances of the 796 element. 798 801 802 application 803 invalid-value 804 error 805 806 /t:top/t:interface[t:name="Ethernet0/0"]/t:mtu 807 808 809 MTU value 25000 is not within range 256..9192 810 811 812 813 application 814 invalid-value 815 error 816 817 /t:top/t:interface[t:name="Ethernet1/0"]/t:address/t:name 818 819 820 Invalid IP address for interface Ethernet1/0 821 822 823 825 4.4. Element 827 The element is sent in messages if no errors or 828 warnings occurred during the processing of an request, and no 829 data was returned from the operation. For example: 831 833 834 836 4.5. Pipelining 838 NETCONF requests MUST be processed serially by the managed 839 device. Additional requests MAY be sent before previous ones 840 have been completed. The managed device MUST send responses only in 841 the order the requests were received. 843 5. Configuration Model 845 NETCONF provides an initial set of operations and a number of 846 capabilities that can be used to extend the base. NETCONF peers 847 exchange device capabilities when the session is initiated as 848 described in Section 8.1. 850 5.1. Configuration Datastores 852 NETCONF defines the existence of one or more configuration datastores 853 and allows configuration operations on them. A configuration 854 datastore is defined as the complete set of configuration data that 855 is required to get a device from its initial default state into a 856 desired operational state. The configuration datastore does not 857 include state data or executive commands. 859 The running configuration datastore holds the complete configuration 860 currently active on the network device. Only one configuration 861 datastore of this type exists on the device, and it is always 862 present. NETCONF protocol operations refer to this datastore using 863 the element. 865 Only the configuration datastore is present in the base 866 model. Additional configuration datastores MAY be defined by 867 capabilities. Such configuration datastores are available only on 868 devices that advertise the capabilities. 870 The capabilities in Sections 8.3 and 8.7 define the and 871 configuration datastores, respectively. 873 5.2. Data Modeling 875 Data modeling and content issues are outside the scope of the NETCONF 876 protocol. An assumption is made that the device's data model is 877 well-known to the application and that both parties are aware of 878 issues such as the layout, containment, keying, lookup, replacement, 879 and management of the data, as well as any other constraints imposed 880 by the data model. 882 NETCONF carries configuration data inside the element that 883 is specific to device's data model. The protocol treats the contents 884 of that element as opaque data. The device uses capabilities to 885 announce the set of data models that the device implements. The 886 capability definition details the operation and constraints imposed 887 by data model. 889 Devices and managers can support multiple data models, including both 890 standard and proprietary data models. 892 6. Subtree Filtering 894 6.1. Overview 896 XML subtree filtering is a mechanism that allows an application to 897 select particular XML subtrees to include in the for a 898 or operation. A small set of filters for 899 inclusion, simple content exact-match, and selection is provided, 900 which allows some useful, but also very limited, selection 901 mechanisms. The server does not need to utilize any data-model- 902 specific semantics during processing, allowing for simple and 903 centralized implementation strategies. 905 Conceptually, a subtree filter is comprised of zero or more element 906 subtrees, which represent the filter selection criteria. At each 907 containment level within a subtree, the set of sibling nodes is 908 logically processed by the server to determine if its subtree and 909 path of elements to the root are included in the filter output. 911 Each node specified in a subtree filter represents an inclusive 912 filter. Only associated nodes in underlying data model(s) within the 913 specified datastore on the server are selected by the filter. A node 914 is selected if it matches the selection criteria and hierarchy of 915 elements given in the filter data, except that the filter absolute 916 path name is adjusted to start from the layer below . 918 Response messages contain only the subtrees selected by the filter. 919 Any selection criteria that were present in the request, within a 920 particular selected subtree, are also included in the response. Note 921 that some elements expressed in the filter as leaf nodes will be 922 expanded (i.e., subtrees included) in the filter output. Specific 923 data instances are not duplicated in the response in the event that 924 the request contains multiple filter subtree expressions that select 925 the same data. 927 6.2. Subtree Filter Components 929 A subtree filter is comprised of XML elements and their XML 930 attributes. There are five types of components that can be present 931 in a subtree filter: 933 o Namespace Selection 935 o Attribute Match Expressions 937 o Containment Nodes 938 o Selection Nodes 940 o Content Match Nodes 942 6.2.1. Namespace Selection 944 A namespace is considered to match (for filter purposes) if the XML 945 namespace associated with a particular node within the 946 element is the same as in the underlying data model. Note that 947 namespace selection cannot be used by itself. At least one element 948 MUST be specified in the filter if any elements are to be included in 949 the filter output. 951 An XML namespace wildcard mechanism is defined for subtree filtering. 952 If an element within the element is not qualified by a 953 namespace (e.g., xmlns=""), then the server MUST evaluate all the XML 954 namespaces it supports, when processing that subtree filter node. 955 This wildcard mechanism is not applicable to XML attributes. 957 Note that prefix values for qualified namespaces are not relevant 958 when comparing filter elements to elements in the underlying data 959 model. 961 Example: 963 964 965 967 In this example, the element is a selection node, and only this 968 node in the "http://example.com/schema/1.2/config" namespace and any 969 child nodes (from the underlying data model) will be included in the 970 filter output. 972 6.2.2. Attribute Match Expressions 974 An attribute that appears in a subtree filter is part of an 975 "attribute match expression". Any number of (unqualified or 976 qualified) XML attributes MAY be present in any type of filter node. 977 In addition to the selection criteria normally applicable to that 978 node, the selected data MUST have matching values for every attribute 979 specified in the node. If an element is not defined to include a 980 specified attribute, then it is not selected in the filter output. 982 Example: 984 985 986 987 988 989 990 992 In this example, the , and elements are containment 993 nodes, the element is a selection node, and "ifName" is 994 an attribute match expression. Only "interface" nodes in the 995 "http://example.com/schema/1.2/config" namespace that have an 996 "ifName" attribute with the value "eth0" and occur within 997 "interfaces" nodes within "top" nodes will be included in the filter 998 output. 1000 6.2.3. Containment Nodes 1002 Nodes that contain child elements within a subtree filter are called 1003 "containment nodes". Each child element can be any type of node, 1004 including another containment node. For each containment node 1005 specified in a subtree filter, all data model instances that exactly 1006 match the specified namespaces, element hierarchy, and any attribute 1007 match expressions are included in the filter output. 1009 Example: 1011 1012 1013 1014 1015 1017 In this example, the element is a containment node. 1019 6.2.4. Selection Nodes 1021 An empty leaf node within a filter is called a "selection node", and 1022 it represents an "explicit selection" filter on the underlying data 1023 model. Presence of any selection nodes within a set of sibling nodes 1024 will cause the filter to select the specified subtree(s) and suppress 1025 automatic selection of the entire set of sibling nodes in the 1026 underlying data model. For filtering purposes, an empty leaf node 1027 can be declared either with an empty tag (e.g., ) or with 1028 explicit start and end tags (e.g., ). Any whitespace 1029 characters are ignored in this form. 1031 Example: 1033 1034 1035 1036 1037 1039 In this example, the element is a containment node, and the 1040 element is a selection node. Only "users" nodes in the 1041 "http://example.com/schema/1.2/config" namespace that occur within a 1042 element that is the root of the configuration datastore will be 1043 included in the filter output. 1045 6.2.5. Content Match Nodes 1047 A leaf node that contains simple content is called a "content match 1048 node". It is used to select some or all of its sibling nodes for 1049 filter output, and it represents an exact-match filter on the leaf 1050 node element content. The following constraints apply to content 1051 match nodes: 1053 o A content match node MUST NOT contain nested elements. 1055 o Multiple content match nodes (i.e., sibling nodes) are logically 1056 combined in an "AND" expression. 1058 o Filtering of mixed content is not supported. 1060 o Filtering of list content is not supported. 1062 o Filtering of whitespace-only content is not supported. 1064 o A content match node MUST contain non-whitespace characters. An 1065 empty element (e.g., ) will be interpreted as a 1066 selection node (e.g., ). 1068 o Leading and trailing whitespace characters are ignored, but any 1069 whitespace characters within a block of text characters are not 1070 ignored or modified. 1072 If all specified sibling content match nodes in a subtree filter 1073 expression are "true", then the filter output nodes are selected in 1074 the following manner: 1076 o Each content match node in the sibling set is included in the 1077 filter output. 1079 o If any containment nodes are present in the sibling set, then they 1080 are processed further and included if any nested filter criteria 1081 are also met. 1083 o If any selection nodes are present in the sibling set, then all of 1084 them are included in the filter output. 1086 o If any sibling nodes of the selection node are instance identifier 1087 components for a conceptual data structure (e.g., list key leaf), 1088 then they MAY also be included in the filter output. 1090 o Otherwise (i.e., there are no selection or containment nodes in 1091 the filter sibling set), all the nodes defined at this level in 1092 the underlying data model (and their subtrees, if any) are 1093 returned in the filter output. 1095 If any of the sibling content match node tests are "false", then no 1096 further filter processing is performed on that sibling set, and none 1097 of the sibling subtrees are selected by the filter, including the 1098 content match node(s). 1100 Example: 1102 1103 1104 1105 1106 fred 1107 1108 1109 1110 1112 In this example, the and nodes are both containment 1113 nodes, and is a content match node. Since no sibling nodes of 1114 are specified (and therefore no containment or selection 1115 nodes), all of the sibling nodes of are returned in the filter 1116 output. Only "user" nodes in the 1117 "http://example.com/schema/1.2/config" namespace that match the 1118 element hierarchy and for which the element is equal to "fred" 1119 will be included in the filter output. 1121 6.3. Subtree Filter Processing 1123 The filter output (the set of selected nodes) is initially empty. 1125 Each subtree filter can contain one or more data model fragments, 1126 which represent portions of the data model that will be selected 1127 (with all child nodes) in the filter output. 1129 Each subtree data fragment is compared by the server to the internal 1130 data models supported by the server. If the entire subtree data- 1131 fragment filter (starting from the root to the innermost element 1132 specified in the filter) exactly matches a corresponding portion of 1133 the supported data model, then that node and all its children are 1134 included in the result data. 1136 The server processes all nodes with the same parent node (sibling 1137 set) together, starting from the root to the leaf nodes. The root 1138 elements in the filter are considered in the same sibling set 1139 (assuming they are in the same namespace), even though they do not 1140 have a common parent. 1142 For each sibling set, the server determines which nodes are included 1143 (or potentially included) in the filter output, and which sibling 1144 subtrees are excluded (pruned) from the filter output. The server 1145 first determines which types of nodes are present in the sibling set 1146 and processes the nodes according to the rules for their type. If 1147 any nodes in the sibling set are selected, then the process is 1148 recursively applied to the sibling sets of each selected node. The 1149 algorithm continues until all sibling sets in all subtrees specified 1150 in the filter have been processed. 1152 6.4. Subtree Filtering Examples 1154 6.4.1. No Filter 1156 Leaving out the filter on the operation returns the entire data 1157 model. 1159 1161 1162 1164 1166 1167 1168 1169 1171 6.4.2. Empty Filter 1173 An empty filter will select nothing because no content match or 1174 selection nodes are present. This is not an error. The 1175 element's "type" attribute used in these examples is discussed 1176 further in Section 7.1. 1178 1180 1181 1182 1183 1184 1186 1188 1189 1190 1192 6.4.3. Select the Entire Subtree 1194 The filter in this example contains one selection node (), so 1195 just that subtree is selected by the filter. This example represents 1196 the fully-populated data model in most of the filter examples 1197 that follow. In a real data model, the would not 1198 likely be returned with the list of users for a particular host or 1199 network. 1201 NOTE: The filtering and configuration examples used in this document 1202 appear in the namespace "http://example.com/schema/1.2/config". The 1203 root element of this namespace is . The element and its 1204 descendents represent an example configuration data model only. 1206 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1220 1222 1223 1224 1225 1226 root 1227 superuser 1228 Charlie Root 1229 1230 1 1231 1 1232 1233 1234 1235 fred 1236 admin 1237 Fred Flintstone 1238 1239 2 1240 2 1241 1242 1243 1244 barney 1245 admin 1246 Barney Rubble 1247 1248 2 1249 3 1250 1251 1252 1253 1254 1255 1257 The following filter request would have produced the same result, but 1258 only because the container defines one child element 1259 (). 1261 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1277 6.4.4. Select All Elements within the Subtree 1279 This filter contains two containment nodes (, ) and one 1280 selection node (). All instances of the element in the 1281 same sibling set are selected in the filter output. The client might 1282 need to know that is used as an instance identifier in this 1283 particular data structure, but the server does not need to know that 1284 meta-data in order to process the request. 1286 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1304 1306 1307 1308 1309 1310 root 1311 1312 1313 fred 1314 1315 1316 barney 1317 1318 1319 1320 1321 1323 6.4.5. One Specific Entry 1325 This filter contains two containment nodes (, ) and one 1326 content match node (). All instances of the sibling set 1327 containing for which the value of equals "fred" are 1328 selected in the filter output. 1330 1332 1333 1334 1335 1336 1337 1338 1339 1340 fred 1341 1342 1343 1344 1345 1346 1348 1350 1351 1352 1353 1354 fred 1355 admin 1356 Fred Flintstone 1357 1358 2 1359 2 1360 1361 1362 1363 1364 1365 1367 6.4.6. Specific Elements from a Specific Entry 1369 This filter contains two containment nodes (, ), one 1370 content match node (), and two selection nodes (, 1371 ). All instances of the and elements 1372 in the same sibling set containing for which the value of 1373 equals "fred" are selected in the filter output. The 1374 element is not included because the sibling set 1375 contains selection nodes. 1377 1379 1380 1381 1382 1383 1384 1385 1386 1387 fred 1388 1389 1390 1391 1392 1393 1394 1395 1397 1399 1400 1401 1402 1403 fred 1404 admin 1405 Fred Flintstone 1406 1407 1408 1409 1410 1412 6.4.7. Multiple Subtrees 1414 This filter contains three subtrees (name=root, fred, barney). 1416 The "root" subtree filter contains two containment nodes (, 1417 ), one content match node (), and one selection node 1418 (). The subtree selection criteria is met, and just 1419 the company-info subtree for "root" is selected in the filter output. 1421 The "fred" subtree filter contains three containment nodes (, 1422 , ), one content match node (), and one 1423 selection node (). The subtree selection criteria is met, and 1424 just the element within the company-info subtree for "fred" is 1425 selected in the filter output. 1427 The "barney" subtree filter contains three containment nodes 1428 (, , ), two content match nodes (, 1429 ), and one selection node (). The subtree selection 1430 criteria is not met because user "barney" is not a "superuser", and 1431 the entire subtree for "barney" (including its parent entry) 1432 is excluded from the filter output. 1434 1436 1437 1438 1439 1440 1441 1442 1443 1444 root 1445 1446 1447 1448 fred 1449 1450 1451 1452 1453 1454 barney 1455 superuser 1456 1457 1458 1459 1460 1461 1462 1463 1464 1466 1468 1469 1470 1471 1472 root 1473 1474 1 1475 1 1476 1477 1478 1479 fred 1480 1481 2 1482 1483 1484 1485 1486 1487 1489 6.4.8. Elements with Attribute Naming 1491 In this example, the filter contains one containment node 1492 (), one attribute match expression ("ifName"), and one 1493 selection node (). All instances of the 1494 subtree that have an "ifName" attribute equal to "eth0" are selected 1495 in the filter output. The filter data elements and attributes are 1496 qualified because the "ifName" attribute will not be considered part 1497 of the "schema/1.2" namespace if it is unqualified. 1499 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1512 1514 1515 1516 1517 1518 45621 1519 774344 1520 1521 1522 1523 1524 1526 If "ifName" were a child node instead of an attribute, then the 1527 following request would produce similar results. 1529 1531 1532 1533 1534 1535 1536 eth0 1537 1538 1539 1540 1541 1542 1544 7. Protocol Operations 1546 The NETCONF protocol provides a small set of low-level operations to 1547 manage device configurations and retrieve device state information. 1548 The base protocol provides operations to retrieve, configure, copy, 1549 and delete configuration datastores. Additional operations are 1550 provided, based on the capabilities advertised by the device. 1552 The base protocol includes the following protocol operations: 1554 o get 1556 o get-config 1558 o edit-config 1560 o copy-config 1562 o delete-config 1564 o lock 1566 o unlock 1568 o close-session 1570 o kill-session 1572 A protocol operation can fail for various reasons, including 1573 "operation not supported". An initiator SHOULD NOT assume that any 1574 operation will always succeed. The return values in any RPC reply 1575 SHOULD be checked for error responses. 1577 The syntax and XML encoding of the protocol operations are formally 1578 defined in the YANG module in Appendix C. The following sections 1579 describe the semantics of each protocol operation. 1581 7.1. 1583 Description: 1585 Retrieve all or part of a specified configuration datastore. 1587 Parameters: 1589 source: 1591 Name of the configuration datastore being queried, such as 1592 . 1594 filter: 1596 This parameter identifies the portions of the device 1597 configuration datastore to retrieve. If this parameter is not 1598 present, the entire configuration is returned. 1600 The element MAY optionally contain a "type" attribute. 1601 This attribute indicates the type of filtering syntax used 1602 within the element. The default filtering mechanism 1603 in NETCONF is referred to as subtree filtering and is described 1604 in Section 6. The value "subtree" explicitly identifies this 1605 type of filtering. 1607 If the NETCONF peer supports the :xpath capability 1608 (Section 8.9), the value "xpath" MAY be used to indicate that 1609 the "select" attribute on the element contains an 1610 XPath expression. 1612 Positive Response: 1614 If the device can satisfy the request, the server sends an 1615 element containing a element with the results 1616 of the query. 1618 Negative Response: 1620 An element is included in the if the 1621 request cannot be completed for any reason. 1623 Example: To retrieve the entire subtree: 1625 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1639 1641 1642 1643 1644 1645 root 1646 superuser 1647 Charlie Root 1648 1649 1 1650 1 1651 1652 1653 1654 1655 1656 1657 1659 Section 6 contains additional examples of subtree filtering. 1661 7.2. 1663 Description: 1665 The operation loads all or part of a specified 1666 configuration to the specified target configuration datastore. 1667 This operation allows the new configuration to be expressed in 1668 several ways, such as using a local file, a remote file, or 1669 inline. If the target configuration datastore does not exist, it 1670 will be created. 1672 If a NETCONF peer supports the :url capability (Section 8.8), the 1673 element can appear instead of the parameter. 1675 The device analyzes the source and target configurations and 1676 performs the requested changes. The target configuration is not 1677 necessarily replaced, as with the message. Instead, 1678 the target configuration is changed in accordance with the 1679 source's data and requested operations. 1681 If the operation contains multiple sub-operations 1682 which apply to the same conceptual node in the underlying data 1683 model, then the result of the operation is undefined (i.e., 1684 outside the scope of the NETCONF protocol). 1686 Attributes: 1688 operation: 1690 Elements in the subtree MAY contain an "operation" 1691 attribute. The attribute identifies the point in the 1692 configuration to perform the operation and MAY appear on 1693 multiple elements throughout the subtree. 1695 If the "operation" attribute is not specified, the 1696 configuration is merged into the configuration datastore. 1698 The "operation" attribute has one of the following values: 1700 merge: The configuration data identified by the element 1701 containing this attribute is merged with the configuration 1702 at the corresponding level in the configuration datastore 1703 identified by the parameter. This is the default 1704 behavior. 1706 replace: The configuration data identified by the element 1707 containing this attribute replaces any related configuration 1708 in the configuration datastore identified by the 1709 parameter. If no such configuration data exists in the 1710 configuration datastore, it is created. Unlike a 1711 operation, which replaces the entire target 1712 configuration, only the configuration actually present in 1713 the parameter is affected. 1715 create: The configuration data identified by the element 1716 containing this attribute is added to the configuration if 1717 and only if the configuration data does not already exist in 1718 the configuration datastore. If the configuration data 1719 exists, an element is returned with an 1720 value of "data-exists". 1722 delete: The configuration data identified by the element 1723 containing this attribute is deleted from the configuration 1724 if and only if the configuration data currently exists in 1725 the configuration datastore. If the configuration data does 1726 not exist, an element is returned with an 1727 value of "data-missing". 1729 remove: The configuration data identified by the element 1730 containing this attribute is deleted from the configuration 1731 if the configuration data currently exists in the 1732 configuration datastore. If the configuration data does not 1733 exist, the "remove" operation is silently ignored by the 1734 server. 1736 Parameters: 1738 target: 1740 Name of the configuration datastore being edited, such as 1741 or . 1743 default-operation: 1745 Selects the default operation (as described in the "operation" 1746 attribute) for this request. The default value 1747 for the parameter is "merge". 1749 The parameter is optional, but if provided, 1750 it has one of the following values: 1752 merge: The configuration data in the parameter is 1753 merged with the configuration at the corresponding level in 1754 the target datastore. This is the default behavior. 1756 replace: The configuration data in the parameter 1757 completely replaces the configuration in the target 1758 datastore. This is useful for loading previously saved 1759 configuration data. 1761 none: The target datastore is unaffected by the configuration 1762 in the parameter, unless and until the incoming 1763 configuration data uses the "operation" attribute to request 1764 a different operation. If the configuration in the 1765 parameter contains data for which there is not a 1766 corresponding level in the target datastore, an 1767 is returned with an value of data-missing. 1768 Using "none" allows operations like "delete" to avoid 1769 unintentionally creating the parent hierarchy of the element 1770 to be deleted. 1772 test-option: 1774 The element MAY be specified only if the device 1775 advertises the :validate:1.1 capability (Section 8.6). 1777 The element has one of the following values: 1779 test-then-set: Perform a validation test before attempting to 1780 set. If validation errors occur, do not perform the 1781 operation. This is the default test-option. 1783 set: Perform a set without a validation test first. 1785 test-only: Perform only the validation test, without 1786 attempting to set. 1788 error-option: 1790 The element has one of the following values: 1792 stop-on-error: Abort the edit-config operation on first error. 1793 This is the default error-option. 1795 continue-on-error: Continue to process configuration data on 1796 error; error is recorded, and negative response is generated 1797 if any errors occur. 1799 rollback-on-error: If an error condition occurs such that an 1800 error severity element is generated, the server 1801 will stop processing the edit-config operation and restore 1802 the specified configuration to its complete state at the 1803 start of this edit-config operation. This option requires 1804 the server to support the :rollback-on-error capability 1805 described in Section 8.5. 1807 config: 1809 A hierarchy of configuration data as defined by one of the 1810 device's data models. The contents MUST be placed in an 1811 appropriate namespace, to allow the device to detect the 1812 appropriate data model, and the contents MUST follow the 1813 constraints of that data model, as defined by its capability 1814 definition. Capabilities are discussed in Section 8. 1816 Positive Response: 1818 If the device was able to satisfy the request, an is 1819 sent containing an element. 1821 Negative Response: 1823 An response is sent if the request cannot be completed 1824 for any reason. 1826 Example: 1828 The examples in this section utilize a simple data 1829 model, in which multiple instances of the element can 1830 be present, and an instance is distinguished by the element 1831 within each element. 1833 Set the MTU to 1500 on an interface named "Ethernet0/0" in the 1834 running configuration: 1836 1838 1839 1840 1841 1842 1843 1844 1845 Ethernet0/0 1846 1500 1847 1848 1849 1850 1851 1853 1855 1856 1858 Add an interface named "Ethernet0/0" to the running configuration, 1859 replacing any previous interface with that name: 1861 1863 1864 1865 1866 1867 1868 1869 1870 Ethernet0/0 1871 1500 1872
1873 192.0.2.4 1874 24 1875
1876 1877 1878 1879 1880 1882 1884 1885 1887 Delete the configuration for an interface named "Ethernet0/0" from 1888 the running configuration: 1890 1892 1893 1894 1895 1896 none 1897 1898 1899 1900 Ethernet0/0 1901 1902 1903 1904 1905 1907 1909 1910 1912 Delete interface 192.0.2.4 from an OSPF area (other interfaces 1913 configured in the same area are unaffected): 1915 1917 1918 1919 1920 1921 none 1922 1923 1924 1925 1926 1927 0.0.0.0 1928 1929 1930 192.0.2.4 1931 1932 1933 1934 1935 1936 1937 1938 1939 1941 1943 1944 1946 7.3. 1948 Description: 1950 Create or replace an entire configuration datastore with the 1951 contents of another complete configuration datastore. If the 1952 target datastore exists, it is overwritten. Otherwise, a new one 1953 is created, if allowed. 1955 If a NETCONF peer supports the :url capability (Section 8.8), the 1956 element can appear as the or parameter. 1958 Even if it advertises the :writable-running capability, a device 1959 MAY choose not to support the configuration datastore 1960 as the parameter of a operation. A device 1961 MAY choose not to support remote-to-remote copy operations, where 1962 both the and parameters use the element. 1964 If the and parameters identify the same URL or 1965 configuration datastore, an error MUST be returned with an error- 1966 tag containing "invalid-value". 1968 Parameters: 1970 target: 1972 Name of the configuration datastore to use as the destination 1973 of the operation. 1975 source: 1977 Name of the configuration datastore to use as the source of the 1978 operation, or the element containing the 1979 complete configuration to copy. 1981 Positive Response: 1983 If the device was able to satisfy the request, an is 1984 sent that includes an element. 1986 Negative Response: 1988 An element is included within the if the 1989 request cannot be completed for any reason. 1991 Example: 1993 1995 1996 1997 1998 1999 2000 https://user:password@example.com/cfg/new.txt 2001 2002 2003 2005 2007 2008 2010 7.4. 2012 Description: 2014 Delete a configuration datastore. The configuration 2015 datastore cannot be deleted. 2017 If a NETCONF peer supports the :url capability (Section 8.8), the 2018 element can appear as the parameter. 2020 Parameters: 2022 target: 2024 Name of the configuration datastore to delete. 2026 Positive Response: 2028 If the device was able to satisfy the request, an is 2029 sent that includes an element. 2031 Negative Response: 2033 An element is included within the if the 2034 request cannot be completed for any reason. 2036 Example: 2038 2040 2041 2042 2043 2044 2045 2047 2049 2050 2052 7.5. 2053 Description: 2055 The operation allows the client to lock the entire 2056 configuration datastore system of a device. Such locks are 2057 intended to be short-lived and allow a client to make a change 2058 without fear of interaction with other NETCONF clients, non- 2059 NETCONF clients (e.g., SNMP and command line interface (CLI) 2060 scripts), and human users. 2062 An attempt to lock the configuration datastore MUST fail if an 2063 existing session or other entity holds a lock on any portion of 2064 the lock target. 2066 When the lock is acquired, the server MUST prevent any changes to 2067 the locked resource other than those requested by this session. 2068 SNMP and CLI requests to modify the resource MUST fail with an 2069 appropriate error. 2071 The duration of the lock is defined as beginning when the lock is 2072 acquired and lasting until either the lock is released or the 2073 NETCONF session closes. The session closure can be explicitly 2074 performed by the client, or implicitly performed by the server 2075 based on criteria such as failure of the underlying transport, 2076 simple inactivity timeout, or detection of abusive behavior on the 2077 part of the client . This criteria is dependent on the 2078 implementation and the underlying transport. 2080 The operation takes a mandatory parameter, . The 2081 parameter names the configuration datastore that will be 2082 locked. When a lock is active, using the operation 2083 on the locked configuration datastore and using the locked 2084 configuration as a target of the operation will be 2085 disallowed by any other NETCONF session. Additionally, the system 2086 will ensure that these locked configuration resources will not be 2087 modified by other non-NETCONF management operations such as SNMP 2088 and CLI. The operation can be used to force the 2089 release of a lock owned by another NETCONF session. It is beyond 2090 the scope of this document to define how to break locks held by 2091 other entities. 2093 A lock MUST NOT be granted if either of the following conditions 2094 is true: 2096 * A lock is already held by any NETCONF session or another 2097 entity. 2099 * The target configuration is , it has already been 2100 modified, and these changes have not been committed or rolled 2101 back. 2103 The server MUST respond with either an element or an 2104 . 2106 A lock will be released by the system if the session holding the 2107 lock is terminated for any reason. 2109 Parameters: 2111 target: 2113 Name of the configuration datastore to lock. 2115 Positive Response: 2117 If the device was able to satisfy the request, an is 2118 sent that contains an element. 2120 Negative Response: 2122 An element is included in the if the 2123 request cannot be completed for any reason. 2125 If the lock is already held, the element will be 2126 "lock-denied" and the element will include the 2127 of the lock owner. If the lock is held by a non- 2128 NETCONF entity, a of 0 (zero) is included. Note that 2129 any other entity performing a lock on even a partial piece of a 2130 target will prevent a NETCONF lock (which is global) from being 2131 obtained on that target. 2133 Example: 2135 The following example shows a successful acquisition of a lock. 2137 2139 2140 2141 2142 2143 2144 2146 2148 2150 2152 Example: 2154 The following example shows a failed attempt to acquire a lock 2155 when the lock is already in use. 2157 2159 2160 2161 2162 2163 2164 2166 2168 2169 protocol 2170 lock-denied 2171 error 2172 2173 Lock failed, lock is already held 2174 2175 2176 454 2177 2178 2179 2180 2182 7.6. 2184 Description: 2186 The operation is used to release a configuration lock, 2187 previously obtained with the operation. 2189 An operation will not succeed if any of the following 2190 conditions are true: 2192 * the specified lock is not currently active 2194 * the session issuing the operation is not the same 2195 session that obtained the lock 2197 The server MUST respond with either an element or an 2198 . 2200 Parameters: 2202 target: 2204 Name of the configuration datastore to unlock. 2206 A NETCONF client is not permitted to unlock a configuration 2207 datastore that it did not lock. 2209 Positive Response: 2211 If the device was able to satisfy the request, an is 2212 sent that contains an element. 2214 Negative Response: 2216 An element is included in the if the 2217 request cannot be completed for any reason. 2219 Example: 2221 2223 2224 2225 2226 2227 2228 2230 2232 2233 2235 7.7. 2237 Description: 2239 Retrieve running configuration and device state information. 2241 Parameters: 2243 filter: 2245 This parameter specifies the portion of the system 2246 configuration and state data to retrieve. If this parameter is 2247 not present, all the device configuration and state information 2248 is returned. 2250 The element MAY optionally contain a "type" attribute. 2251 This attribute indicates the type of filtering syntax used 2252 within the element. The default filtering mechanism 2253 in NETCONF is referred to as subtree filtering and is described 2254 in Section 6. The value "subtree" explicitly identifies this 2255 type of filtering. 2257 If the NETCONF peer supports the :xpath capability 2258 (Section 8.9), the value "xpath" MAY be used to indicate that 2259 the "select" attribute of the element contains an 2260 XPath expression. 2262 Positive Response: 2264 If the device was able to satisfy the request, an is 2265 sent. The section contains the appropriate subset. 2267 Negative Response: 2269 An element is included in the if the 2270 request cannot be completed for any reason. 2272 Example: 2274 2276 2277 2278 2279 2280 2281 eth0 2282 2283 2284 2285 2286 2287 2289 2291 2292 2293 2294 2295 eth0 2296 45621 2297 774344 2298 2299 2300 2301 2302 2304 7.8. 2306 Description: 2308 Request graceful termination of a NETCONF session. 2310 When a NETCONF server receives a request, it will 2311 gracefully close the session. The server will release any locks 2312 and resources associated with the session and gracefully close any 2313 associated connections. Any NETCONF requests received after a 2314 request will be ignored. 2316 Positive Response: 2318 If the device was able to satisfy the request, an is 2319 sent that includes an element. 2321 Negative Response: 2323 An element is included in the if the 2324 request cannot be completed for any reason. 2326 Example: 2328 2330 2331 2333 2335 2336 2338 7.9. 2340 Description: 2342 Force the termination of a NETCONF session. 2344 When a NETCONF entity receives a request for an 2345 open session, it will abort any operations currently in process, 2346 release any locks and resources associated with the session, and 2347 close any associated connections. 2349 If a NETCONF server receives a request while 2350 processing a confirmed commit (Section 8.4), it MUST restore the 2351 configuration to its state before the confirmed commit was issued. 2353 Otherwise, the operation does not roll back 2354 configuration or other device state modifications made by the 2355 entity holding the lock. 2357 Parameters: 2359 session-id: 2361 Session identifier of the NETCONF session to be terminated. If 2362 this value is equal to the current session ID, an 2363 "invalid-value" error is returned. 2365 Positive Response: 2367 If the device was able to satisfy the request, an is 2368 sent that includes an element. 2370 Negative Response: 2372 An element is included in the if the 2373 request cannot be completed for any reason. 2375 Example: 2377 2379 2380 4 2381 2382 2384 2386 2387 2389 8. Capabilities 2391 This section defines a set of capabilities that a client or a server 2392 MAY implement. Each peer advertises its capabilities by sending them 2393 during an initial capabilities exchange. Each peer needs to 2394 understand only those capabilities that it might use and MUST ignore 2395 any capability received from the other peer that it does not require 2396 or does not understand. 2398 Additional capabilities can be defined using the template in 2399 Appendix D. Future capability definitions can be published as 2400 standards by standards bodies or published as proprietary extensions. 2402 A NETCONF capability is identified with a URI. The base capabilities 2403 are defined using URNs following the method described in RFC 3553 2404 [RFC3553]. Capabilities defined in this document have the following 2405 format: 2407 urn:ietf:params:netconf:capability:{name}:1.x 2409 where {name} is the name of the capability. Capabilities are often 2410 referenced in discussions and email using the shorthand :{name}, or 2411 :{name}:{version} if the capability exists in multiple versions. For 2412 example, the foo capability would have the formal name 2413 "urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo". 2414 The shorthand form MUST NOT be used inside the protocol. 2416 8.1. Capabilities Exchange 2418 Capabilities are advertised in messages sent by each peer during 2419 session establishment. When the NETCONF session is opened, each peer 2420 (both client and server) MUST send a element containing a 2421 list of that peer's capabilities. Each peer MUST send at least the 2422 base NETCONF capability, "urn:ietf:params:netconf:base:1.1". A peer 2423 MAY include capabilities for previous NETCONF versions, to indicate 2424 that it supports multiple protocol versions. 2426 Both NETCONF peers MUST verify that the other peer has advertised a 2427 common protocol version. When comparing protocol version capability 2428 URIs, only the base part is used, in the event any parameters are 2429 encoded at the end of the URI string. If no protocol version 2430 capability in common is found, the NETCONF peer MUST NOT continue the 2431 session. If more than one protocol version URI in common is present, 2432 then the highest numbered (most recent) protocol version MUST be used 2433 by both peers. 2435 A server sending the element MUST include a 2436 element containing the session ID for this NETCONF session. A client 2437 sending the element MUST NOT include a element. 2439 A server receiving a message with a element MUST 2440 terminate the NETCONF session. Similarly, a client that does not 2441 receive a element in the server's message MUST 2442 terminate the NETCONF session (without first sending a 2443 ). 2445 In the following example, a server advertises the base NETCONF 2446 capability, one NETCONF capability defined in the base NETCONF 2447 document, and one implementation-specific capability. 2449 2450 2451 2452 urn:ietf:params:netconf:base:1.1 2453 2454 2455 urn:ietf:params:netconf:capability:startup:1.0 2456 2457 2458 http://example.net/router/2.3/myfeature 2459 2460 2461 4 2462 2464 Each peer sends its element simultaneously as soon as the 2465 connection is open. A peer MUST NOT wait to receive the capability 2466 set from the other side before sending its own set. 2468 8.2. Writable-Running Capability 2470 8.2.1. Description 2472 The :writable-running capability indicates that the device supports 2473 direct writes to the configuration datastore. In other 2474 words, the device supports and operations 2475 where the configuration is the target. 2477 8.2.2. Dependencies 2479 None. 2481 8.2.3. Capability Identifier 2483 The :writable-running capability is identified by the following 2484 capability string: 2486 urn:ietf:params:netconf:capability:writable-running:1.0 2488 8.2.4. New Operations 2490 None. 2492 8.2.5. Modifications to Existing Operations 2494 8.2.5.1. 2496 The :writable-running capability modifies the operation 2497 to accept the element as a . 2499 8.2.5.2. 2501 The :writable-running capability modifies the operation 2502 to accept the element as a . 2504 8.3. Candidate Configuration Capability 2506 8.3.1. Description 2508 The candidate configuration capability, :candidate, indicates that 2509 the device supports a candidate configuration datastore, which is 2510 used to hold configuration data that can be manipulated without 2511 impacting the device's current configuration. The candidate 2512 configuration is a full configuration data set that serves as a work 2513 place for creating and manipulating configuration data. Additions, 2514 deletions, and changes can be made to this data to construct the 2515 desired configuration data. A operation MAY be performed at 2516 any time that causes the device's running configuration to be set to 2517 the value of the candidate configuration. 2519 The operation effectively sets the running configuration to 2520 the current contents of the candidate configuration. While it could 2521 be modeled as a simple copy, it is done as a distinct operation for a 2522 number of reasons. In keeping high-level concepts as first class 2523 operations, we allow developers to see more clearly both what the 2524 client is requesting and what the server must perform. This keeps 2525 the intentions more obvious, the special cases less complex, and the 2526 interactions between operations more straightforward. For example, 2527 the :confirmed-commit:1.1 capability (Section 8.4) would make no 2528 sense as a "copy confirmed" operation. 2530 The candidate configuration can be shared among multiple sessions. 2531 Unless a client has specific information that the candidate 2532 configuration is not shared, it MUST assume that other sessions are 2533 able to modify the candidate configuration at the same time. It is 2534 therefore prudent for a client to lock the candidate configuration 2535 before modifying it. 2537 The client can discard any uncommitted changes to the candidate 2538 configuration by executing the operation. This 2539 operation reverts the contents of the candidate configuration to the 2540 contents of the running configuration. 2542 8.3.2. Dependencies 2544 None. 2546 8.3.3. Capability Identifier 2548 The :candidate capability is identified by the following capability 2549 string: 2551 urn:ietf:params:netconf:capability:candidate:1.0 2553 8.3.4. New Operations 2555 8.3.4.1. 2557 Description: 2559 When a candidate configuration's content is complete, the 2560 configuration data can be committed, publishing the data set to 2561 the rest of the device and requesting the device to conform to 2562 the behavior described in the new configuration. 2564 To commit the candidate configuration as the device's new 2565 current configuration, use the operation. 2567 The operation instructs the device to implement the 2568 configuration data contained in the candidate configuration. 2569 If the device is unable to commit all of the changes in the 2570 candidate configuration datastore, then the running 2571 configuration MUST remain unchanged. If the device does 2572 succeed in committing, the running configuration MUST be 2573 updated with the contents of the candidate configuration. 2575 If the running or candidate configuration is currently locked 2576 by a different session, the operation MUST fail with 2577 an value of "in-use". 2579 If the system does not have the :candidate capability, the 2580 operation is not available. 2582 Positive Response: 2584 If the device was able to satisfy the request, an 2585 is sent that contains an element. 2587 Negative Response: 2589 An element is included in the if the 2590 request cannot be completed for any reason. 2592 Example: 2594 2596 2597 2599 2601 2602 2604 8.3.4.2. 2606 If the client decides that the candidate configuration is not to be 2607 committed, the operation can be used to revert the 2608 candidate configuration to the current running configuration. 2610 2612 2613 2615 This operation discards any uncommitted changes by resetting the 2616 candidate configuration with the content of the running 2617 configuration. 2619 8.3.5. Modifications to Existing Operations 2621 8.3.5.1. , , , and 2623 The candidate configuration can be used as a source or target of any 2624 , , , or operation 2625 as a or parameter. The element is used 2626 to indicate the candidate configuration: 2628 2630 2631 2632 2633 2634 2635 2637 8.3.5.2. and 2639 The candidate configuration can be locked using the operation 2640 with the element as the parameter: 2642 2644 2645 2646 2647 2648 2649 2651 Similarly, the candidate configuration is unlocked using the 2652 element as the parameter: 2654 2656 2657 2658 2659 2660 2661 2663 When a client fails with outstanding changes to the candidate 2664 configuration, recovery can be difficult. To facilitate easy 2665 recovery, any outstanding changes are discarded when the lock is 2666 released, whether explicitly with the operation or 2667 implicitly from session failure. 2669 8.4. Confirmed Commit Capability 2671 8.4.1. Description 2673 The :confirmed-commit:1.1 capability indicates that the server will 2674 support the operation and the , 2675 , , and parameters for the 2676 operation. See Section 8.3 for further details on the 2677 operation. 2679 A confirmed commit operation MUST be reverted if a confirming commit 2680 is not issued within the timeout period (by default 600 seconds = 10 2681 minutes). The confirming commit is a operation without the 2682 parameter. The timeout period can be adjusted with the 2683 parameter. If a follow-up confirmed commit 2684 operation is issued before the timer expires, the timer is reset to 2685 the new value (600 seconds by default). Both the confirming commit 2686 and a follow-up confirmed commit operation MAY introduce additional 2687 changes to the configuration. 2689 If the element is not given in the confirmed commit 2690 operation, any follow-up commit and the confirming commit MUST be 2691 issued on the same session that issued the confirmed commit. If the 2692 element is given in the confirmed commit operation, a 2693 follow-up commit and the confirming commit can be given on any 2694 session, and they MUST include a element with a value 2695 equal to the given value of the element. 2697 If the server also advertises the :startup capability, a 2698 from running to startup is also necessary to save the 2699 changes to startup. 2701 If the session issuing the confirmed commit is terminated for any 2702 reason before the confirm timeout expires, the server MUST restore 2703 the configuration to its state before the confirmed commit was 2704 issued, unless the confirmed commit also included a 2705 element. 2707 If the device reboots for any reason before the confirm timeout 2708 expires, the server MUST restore the configuration to its state 2709 before the confirmed commit was issued. 2711 If a confirming commit is not issued, the device will revert its 2712 configuration to the state prior to the issuance of the confirmed 2713 commit. To cancel a confirmed commit and revert changes without 2714 waiting for the confirm timeout to expire, the client can explicitly 2715 restore the configuration to its state before the confirmed commit 2716 was issued, by using the operation. 2718 For shared configurations, this feature can cause other configuration 2719 changes (for example, via other NETCONF sessions) to be inadvertently 2720 altered or removed, unless the configuration locking feature is used 2721 (in other words, the lock is obtained before the 2722 operation is started). Therefore, it is strongly suggested that in 2723 order to use this feature with shared configuration datastores, 2724 configuration locking SHOULD also be used. 2726 Version 1.0 of this capability was defined in [RFC4741]. Version 1.1 2727 is defined in this document, and extends version 1.0 by adding a new 2728 operation, , and two new optional parameters, 2729 and . For backwards compatibility with old 2730 clients, servers confirming to this specification MAY advertise 2731 version 1.0 in addition to version 1.1. 2733 8.4.2. Dependencies 2735 The :confirmed-commit:1.1 capability is only relevant if the 2736 :candidate capability is also supported. 2738 8.4.3. Capability Identifier 2740 The :confirmed-commit:1.1 capability is identified by the following 2741 capability string: 2743 urn:ietf:params:netconf:capability:confirmed-commit:1.1 2745 8.4.4. New Operations 2747 8.4.4.1. 2749 Description: 2751 Cancels an ongoing confirmed commit. If the 2752 parameter is not given, the operation MUST be 2753 issued on the same session that issued the confirmed commit. 2755 Parameters: 2757 persist-id: 2759 Cancels a persistent confirmed commit. The value MUST be 2760 equal to the value given in the parameter to the 2761 operation. If the value does not match, the 2762 operation fails with an "invalid-value" error. 2764 Positive Response: 2766 If the device was able to satisfy the request, an 2767 is sent that contains an element. 2769 Negative Response: 2771 An element is included in the if the 2772 request cannot be completed for any reason. 2774 Example: 2776 2778 2779 2780 2781 2783 2785 2786 2788 2790 2791 2793 2795 2796 2798 8.4.5. Modifications to Existing Operations 2800 8.4.5.1. 2802 The :confirmed-commit:1.1 capability allows 4 additional parameters 2803 to the operation. 2805 Parameters: 2807 confirmed: 2809 Perform a confirmed commit operation. 2811 confirm-timeout: 2813 Timeout period for confirmed commit, in seconds. If 2814 unspecified, the confirm timeout defaults to 600 seconds. 2816 persist: 2818 Make the confirmed commit survive a session termination, and 2819 set a token on the ongoing confirmed commit. 2821 persist-id: 2823 Used to issue a follow-up confirmed commit or a confirming 2824 commit from any session, with the token from the previous 2825 commit operation. 2827 Example: 2829 2831 2832 2833 120 2834 2835 2837 2839 2840 2842 Example: 2844 2845 2847 2848 2849 IQ,d4668 2850 2851 2853 2855 2856 2858 2860 2862 2863 IQ,d4668 2864 2865 2867 2869 2870 2872 8.5. Rollback on Error Capability 2874 8.5.1. Description 2876 This capability indicates that the server will support the 2877 "rollback-on-error" value in the parameter to the 2878 operation. 2880 For shared configurations, this feature can cause other configuration 2881 changes (for example, via other NETCONF sessions) to be inadvertently 2882 altered or removed, unless the configuration locking feature is used 2883 (in other words, the lock is obtained before the 2884 operation is started). Therefore, it is strongly suggested that in 2885 order to use this feature with shared configuration datastores, 2886 configuration locking also be used. 2888 8.5.2. Dependencies 2890 None 2892 8.5.3. Capability Identifier 2894 The :rollback-on-error capability is identified by the following 2895 capability string: 2897 urn:ietf:params:netconf:capability:rollback-on-error:1.0 2899 8.5.4. New Operations 2901 None. 2903 8.5.5. Modifications to Existing Operations 2905 8.5.5.1. 2907 The :rollback-on-error capability allows the "rollback-on-error" 2908 value to the parameter on the operation. 2910 2912 2913 2914 2915 2916 rollback-on-error 2917 2918 2919 2920 Ethernet0/0 2921 100000 2922 2923 2924 2925 2926 2928 2930 2931 2933 8.6. Validate Capability 2935 8.6.1. Description 2937 Validation consists of checking a complete configuration for 2938 syntactical and semantic errors before applying the configuration to 2939 the device. 2941 If this capability is advertised, the device supports the 2942 protocol operation and checks at least for syntax errors. In 2943 addition, this capability supports the parameter to the 2944 operation and, when it is provided, checks at least for 2945 syntax errors. 2947 Version 1.0 of this capability was defined in [RFC4741]. Version 1.1 2948 is defined in this document, and extends version 1.0 by adding a new 2949 value, "test-only", to the parameter of the 2950 operation. For backwards compatibility with old 2951 clients, servers confirming to this specification MAY advertise 2952 version 1.0 in addition to version 1.1. 2954 8.6.2. Dependencies 2956 None. 2958 8.6.3. Capability Identifier 2960 The :validate:1.1 capability is identified by the following 2961 capability string: 2963 urn:ietf:params:netconf:capability:validate:1.1 2965 8.6.4. New Operations 2967 8.6.4.1. 2969 Description: 2971 This protocol operation validates the contents of the specified 2972 configuration. 2974 Parameters: 2976 source: 2978 Name of the configuration datastore to validate, such as 2979 , or the element containing the complete 2980 configuration to validate. 2982 Positive Response: 2984 If the device was able to satisfy the request, an 2985 is sent that contains an element. 2987 Negative Response: 2989 An element is included in the if the 2990 request cannot be completed for any reason. 2992 A operation can fail for a number of reasons, such 2993 as syntax errors, missing parameters, references to undefined 2994 configuration data or any other violations of rules established 2995 by the underlying data model. 2997 Example: 2999 3001 3002 3003 3004 3005 3006 3008 3010 3011 3013 8.6.5. Modifications to Existing Operations 3015 8.6.5.1. 3017 The :validate:1.1 capability modifies the operation to 3018 accept the parameter. 3020 8.7. Distinct Startup Capability 3022 8.7.1. Description 3024 The device supports separate running and startup configuration 3025 datastores. The startup configuration is loaded by the device when 3026 it boots. Operations that affect the running configuration will not 3027 be automatically copied to the startup configuration. An explicit 3028 operation from the to the is used 3029 to update the startup configuration to the current contents of the 3030 running configuration. NETCONF protocol operations refer to the 3031 startup datastore using the element. 3033 8.7.2. Dependencies 3035 None. 3037 8.7.3. Capability Identifier 3039 The :startup capability is identified by the following capability 3040 string: 3042 urn:ietf:params:netconf:capability:startup:1.0 3044 8.7.4. New Operations 3046 None. 3048 8.7.5. Modifications to Existing Operations 3050 8.7.5.1. General 3052 The :startup capability adds the configuration datastore 3053 to arguments of several NETCONF operations. The server MUST support 3054 the following additional values: 3056 +--------------------+--------------------------+-------------------+ 3057 | Operation | Parameters | Notes | 3058 +--------------------+--------------------------+-------------------+ 3059 | | | | 3060 | | | | 3061 | | | | 3062 | | | | 3063 | | | | 3064 | | | | 3065 | | | | 3066 | | | | 3067 | | | If :validate:1.1 | 3068 | | | is advertised | 3069 | | | | 3070 | | | Resets the device | 3071 | | | to its factory | 3072 | | | defaults | 3073 +--------------------+--------------------------+-------------------+ 3075 To save the startup configuration, use the operation to 3076 copy the configuration datastore to the 3077 configuration datastore. 3079 3081 3082 3083 3084 3085 3086 3087 3088 3089 3091 8.8. URL Capability 3093 8.8.1. Description 3095 The NETCONF peer has the ability to accept the element in 3096 and parameters. The capability is further 3097 identified by URL arguments indicating the URL schemes supported. 3099 8.8.2. Dependencies 3101 None. 3103 8.8.3. Capability Identifier 3105 The :url capability is identified by the following capability string: 3107 urn:ietf:params:netconf:capability:url:1.0?scheme={name,...} 3109 The :url capability URI MUST contain a "scheme" argument assigned a 3110 comma-separated list of scheme names indicating which schemes the 3111 NETCONF peer supports. For example: 3113 urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file 3115 8.8.4. New Operations 3117 None. 3119 8.8.5. Modifications to Existing Operations 3121 8.8.5.1. 3123 The :url capability modifies the operation to accept 3124 the element as an alternative to the parameter. 3126 The file that the url refers to contains the configuration data 3127 hierarchy to be modified, encoded in XML under the element 3128 in the "urn:ietf:params:xml:ns:netconf:base:1.0" namespace. 3130 8.8.5.2. 3132 The :url capability modifies the operation to accept 3133 the element as the value of the and the 3134 parameters. 3136 The file that the url refers to contains the complete datastore, 3137 encoded in XML under the element in the 3138 "urn:ietf:params:xml:ns:netconf:base:1.0" namespace. 3140 8.8.5.3. 3142 The :url capability modifies the operation to accept 3143 the element as the value of the parameters. 3145 8.8.5.4. 3147 The :url capability modifies the operation to accept the 3148 element as the value of the parameter. 3150 8.9. XPath Capability 3152 8.9.1. Description 3154 The XPath capability indicates that the NETCONF peer supports the use 3155 of XPath expressions in the element. XPath is described in 3156 [W3C.REC-xpath-19991116]. 3158 The data model used in the XPath expression is the same as that used 3159 in XPath 1.0 [W3C.REC-xpath-19991116], with the same extension for 3160 root node children as used by XSLT 1.0 [W3C.REC-xslt-19991116] 3161 (section 3.1). Specifically, it means that the root node MAY have 3162 any number of element nodes as its children. 3164 The XPath expression is evaluated in the following context: 3166 o The set of namespace declarations are those in scope on the 3167 element. 3169 o The set of variable bindings is defined by the data model. If no 3170 such variable bindings are defined, the set is empty. 3172 o The function library is the core function library, plus any 3173 functions defined by the data model. 3175 o The context node is the root node. 3177 The XPath expression MUST return a node set. If it does not return a 3178 node set, the operation fails with an "invalid-value" error. 3180 The response message contains the subtrees selected by the filter 3181 expression. For each such subtree, the path from the data model root 3182 node down to the subtree, including any elements or attributes 3183 necessary to uniquely identify the subtree, are included in the 3184 response message. Specific data instances are not duplicated in the 3185 respone. 3187 8.9.2. Dependencies 3189 None. 3191 8.9.3. Capability Identifier 3193 The :xpath capability is identified by the following capability 3194 string: 3196 urn:ietf:params:netconf:capability:xpath:1.0 3198 8.9.4. New Operations 3200 None. 3202 8.9.5. Modifications to Existing Operations 3204 8.9.5.1. and 3206 The :xpath capability modifies the and operations 3207 to accept the value "xpath" in the "type" attribute of the 3208 element. When the "type" attribute is set to "xpath", a "select" 3209 attribute MUST be present on the element. The "select" 3210 attribute will be treated as an XPath expression and used to filter 3211 the returned data. The element itself MUST be empty in this 3212 case. 3214 The XPath result for the select expression MUST be a node-set. Each 3215 node in the node-set MUST correspond to a node in underlying data 3216 model. In order to properly identify each node, the following 3217 encoding rules are defined: 3219 o All ancestor nodes of the result node MUST be encoded first, so 3220 the element returned in the reply contains only fully- 3221 specified sub-trees, according to the underlying data model. 3223 o If any sibling or ancestor nodes of the result node are needed to 3224 identify a particular instance within a conceptual data structure, 3225 then these nodes MUST also be encoded in the response. 3227 For example: 3229 3231 3232 3233 3234 3235 3236 3239 3240 3242 3244 3245 3246 3247 3248 fred 3249 3250 2 3251 3252 3253 3254 3255 3256 3258 9. Security Considerations 3260 This section provides security considerations for the base NETCONF 3261 message layer and the base operations of the NETCONF protocol. 3262 Security considerations for the NETCONF transports are provided in 3263 the transport documents and security considerations for the content 3264 manipulated by NETCONF can be found in the documents defining data 3265 models. 3267 This document does not specify an authorization scheme, as such a 3268 scheme will likely be tied to a meta-data model or a data model. 3269 Implementors SHOULD provide a comprehensive authorization scheme with 3270 NETCONF. 3272 Authorization of individual users via the NETCONF server may or may 3273 not map 1:1 to other interfaces. First, the data models might be 3274 incompatible. Second, it could be desirable to authorize based on 3275 mechanisms available in the secure transport layer (SSH, BEEP, etc). 3277 In addition, operations on configurations could have unintended 3278 consequences if those operations are also not guarded by the global 3279 lock on the files or objects being operated upon. For instance, a 3280 partially complete access list could be committed from a candidate 3281 configuration unbeknownst to the owner of the lock of the candidate 3282 configuration, leading to either an insecure or inaccessible device 3283 if the lock on the candidate configuration does not also apply to the 3284 operation when applied to it. 3286 Configuration information is by its very nature sensitive. Its 3287 transmission in the clear and without integrity checking leaves 3288 devices open to classic eavesdropping and false data injection 3289 attacks. Configuration information often contains passwords, user 3290 names, service descriptions, and topological information, all of 3291 which are sensitive. Because of this, this protocol SHOULD be 3292 implemented carefully with adequate attention to all manner of attack 3293 one might expect to experience with other management interfaces. 3295 The protocol, therefore, MUST minimally support options for both 3296 confidentiality and authentication. It is anticipated that the 3297 underlying protocol (SSH, BEEP, etc) will provide for both 3298 confidentiality and authentication, as is required. It is further 3299 expected that the identity of each end of a NETCONF session will be 3300 available to the other in order to determine authorization for any 3301 given request. One could also easily envision additional 3302 information, such as transport and encryption methods, being made 3303 available for purposes of authorization. NETCONF itself provide no 3304 means to re-authenticate, much less authenticate. All such actions 3305 occur at lower layers. 3307 Different environments may well allow different rights prior to and 3308 then after authentication. Thus, an authorization model is not 3309 specified in this document. When an operation is not properly 3310 authorized, a simple "access denied" is sufficient. Note that 3311 authorization information can be exchanged in the form of 3312 configuration information, which is all the more reason to ensure the 3313 security of the connection. 3315 That having been said, it is important to recognize that some 3316 operations are clearly more sensitive by nature than others. For 3317 instance, to the startup or running configurations is 3318 clearly not a normal provisioning operation, whereas 3319 is. Such global operations MUST disallow the changing of information 3320 that an individual does not have authorization to perform. For 3321 example, if a user A is not allowed to configure an IP address on an 3322 interface but user B has configured an IP address on an interface in 3323 the configuration, user A MUST NOT be allowed to commit 3324 the configuration. 3326 Similarly, just because someone says "go write a configuration 3327 through the URL capability at a particular place", this does not mean 3328 that an element will do it without proper authorization. 3330 The operation will demonstrate that NETCONF is intended for 3331 use by systems that have at least some trust of the administrator. 3332 As specified in this document, it is possible to lock portions of a 3333 configuration that a principal might not otherwise have access to. 3334 After all, the entire configuration is locked. To mitigate this 3335 problem, there are two approaches. It is possible to kill another 3336 NETCONF session programmatically from within NETCONF if one knows the 3337 session identifier of the offending session. The other possible way 3338 to break a lock is to provide an function within the device's native 3339 user interface. These two mechanisms suffer from a race condition 3340 that could be ameliorated by removing the offending user from an AAA 3341 server. However, such a solution is not useful in all deployment 3342 scenarios, such as those where SSH public/private key pairs are used. 3344 10. IANA Considerations 3346 10.1. NETCONF XML Namespace 3348 This document registers a URI for the NETCONF XML namespace in the 3349 IETF XML registry [RFC3688]. 3351 IANA is requested to update the allocation of the following URI to 3352 reference this document when it is published as an RFC. 3354 URI: urn:ietf:params:xml:ns:netconf:base:1.0 3356 Registrant Contact: The IESG. 3358 XML: N/A, the requested URI is an XML namespace. 3360 10.2. NETCONF XML Schema 3362 This document registers a URI for the NETCONF XML schema in the IETF 3363 XML registry [RFC3688]. 3365 IANA is requested to update the allocation of the following URI to 3366 reference this document when it is published as an RFC. 3368 URI: urn:ietf:params:xml:schema:netconf 3370 Registrant Contact: The IESG. 3372 XML: Appendix B of this document. 3374 10.3. NETCONF YANG Module 3376 This document registers a YANG module in the YANG Module Names 3377 registry [RFC6020]. 3379 name: ietf-netconf 3380 namespace: urn:ietf:params:xml:ns:netconf:base:1.0 3381 prefix: nc 3382 reference: RFCXXXX 3384 10.4. NETCONF Capability URNs 3386 IANA has created and will maintain a registry "Network Configuration 3387 Protocol (NETCONF) Capability URNs" that allocates NETCONF capability 3388 identifiers. Additions to the registry require IETF Standards 3389 Action. 3391 IANA is requested to update the allocations of the following 3392 capabilities to reference this document when it is published as an 3393 RFC. 3395 +--------------------+----------------------------------------------+ 3396 | Index | Capability Identifier | 3397 +--------------------+----------------------------------------------+ 3398 | :writable-running | urn:ietf:params:netconf:capability:writable- | 3399 | | running:1.0 | 3400 | | | 3401 | :candidate | urn:ietf:params:netconf:capability:candidate | 3402 | | :1.0 | 3403 | | | 3404 | :rollback-on-error | urn:ietf:params:netconf:capability:rollback- | 3405 | | on-error:1.0 | 3406 | | | 3407 | :startup | urn:ietf:params:netconf:capability:startup:1 | 3408 | | .0 | 3409 | | | 3410 | :url | urn:ietf:params:netconf:capability:url:1.0 | 3411 | | | 3412 | :xpath | urn:ietf:params:netconf:capability:xpath:1.0 | 3413 +--------------------+----------------------------------------------+ 3415 IANA is requested to add the following capabilities to the registry: 3417 +---------------------+---------------------------------------------+ 3418 | Index | Capability Identifier | 3419 +---------------------+---------------------------------------------+ 3420 | :base:1.1 | urn:ietf:params:netconf:base:1.1 | 3421 | | | 3422 | :confirmed-commit:1 | urn:ietf:params:netconf:capability:confirme | 3423 | .1 | d-commit:1.1 | 3424 | | | 3425 | :validate:1.1 | urn:ietf:params:netconf:capability:validate | 3426 | | :1.1 | 3427 +---------------------+---------------------------------------------+ 3429 11. Authors and Acknowledgements 3431 This document was written by: 3433 Andy Bierman 3435 Ken Crozier, Cisco Systems 3437 Rob Enns, Juniper Networks 3439 Ted Goddard, IceSoft 3441 Eliot Lear, Cisco Systems 3443 Phil Shafer, Juniper Networks 3445 Steve Waldbusser 3447 Margaret Wasserman, ThingMagic 3449 The authors would like to acknowledge the members of the NETCONF 3450 working group. In particular, we would like to thank Wes Hardaker 3451 for his persistence and patience in assisting us with security 3452 considerations. We would also like to thank Randy Presuhn, Sharon 3453 Chisholm, Glenn Waters, David Perkins, Weijing Chen, Simon Leinen, 3454 Keith Allen, Dave Harrington, Ladislav Lhotka, Tom Petch, and Kent 3455 Watsen for all of their valuable advice. 3457 12. References 3459 12.1. Normative References 3461 [W3C.REC-xml-20001006] 3462 Bray, T., Sperberg-McQueen, C., Paoli, J., and E. Maler, 3463 "Extensible Markup Language (XML) 1.0 (Second Edition)", 3464 World Wide Web Consortium FirstEdition REC-xml-20001006, 3465 October 2000, 3466 . 3468 [W3C.REC-xpath-19991116] 3469 DeRose, S. and J. Clark, "XML Path Language (XPath) 3470 Version 1.0", World Wide Web Consortium 3471 Recommendation REC-xpath-19991116, November 1999, 3472 . 3474 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3475 Requirement Levels", BCP 14, RFC 2119, March 1997. 3477 [I-D.ietf-netconf-rfc4742bis] 3478 Wasserman, M. and T. Goddard, "Using the NETCONF 3479 Configuration Protocol over Secure Shell (SSH)", 3480 draft-ietf-netconf-rfc4742bis-07 (work in progress), 3481 February 2011. 3483 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3484 Resource Identifier (URI): Generic Syntax", STD 66, 3485 RFC 3986, January 2005. 3487 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 3488 IETF URN Sub-namespace for Registered Protocol 3489 Parameters", BCP 73, RFC 3553, June 2003. 3491 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3492 10646", STD 63, RFC 3629, November 2003. 3494 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3495 January 2004. 3497 [RFC5717] Lengyel, B. and M. Bjorklund, "Partial Lock Remote 3498 Procedure Call (RPC) for NETCONF", RFC 5717, 3499 December 2009. 3501 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3502 Network Configuration Protocol (NETCONF)", RFC 6020, 3503 October 2010. 3505 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 3506 October 2010. 3508 12.2. Informative References 3510 [W3C.REC-xslt-19991116] 3511 Clark, J., "XSL Transformations (XSLT) Version 1.0", World 3512 Wide Web Consortium Recommendation REC-xslt-19991116, 3513 November 1999, 3514 . 3516 [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, 3517 "Remote Authentication Dial In User Service (RADIUS)", 3518 RFC 2865, June 2000. 3520 [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for 3521 the Use of Extensible Markup Language (XML) 3522 within IETF Protocols", BCP 70, RFC 3470, January 2003. 3524 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 3525 Protocol Architecture", RFC 4251, January 2006. 3527 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 3528 December 2006. 3530 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3531 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3533 Appendix A. NETCONF Error List 3535 This section is normative. 3537 For each error-tag, the valid error-type and error-severity values 3538 are listed, together with any mandatory error-info, if any. 3540 error-tag: in-use 3541 error-type: protocol, application 3542 error-severity: error 3543 error-info: none 3544 Description: The request requires a resource that already is in 3545 use. 3547 error-tag: invalid-value 3548 error-type: protocol, application 3549 error-severity: error 3550 error-info: none 3551 Description: The request specifies an unacceptable value for one 3552 or more parameters. 3554 error-tag: too-big 3555 error-type: transport, rpc, protocol, application 3556 error-severity: error 3557 error-info: none 3558 Description: The request or response (that would be generated) is 3559 too large for the implementation to handle. 3561 error-tag: missing-attribute 3562 error-type: rpc, protocol, application 3563 error-severity: error 3564 error-info: : name of the missing attribute 3565 : name of the element that is supposed to 3566 contain the missing attribute 3567 Description: An expected attribute is missing. 3569 error-tag: bad-attribute 3570 error-type: rpc, protocol, application 3571 error-severity: error 3572 error-info: : name of the attribute w/ bad value 3573 : name of the element that contains 3574 the attribute with the bad value 3575 Description: An attribute value is not correct; e.g., wrong type, 3576 out of range, pattern mismatch. 3578 error-tag: unknown-attribute 3579 error-type: rpc, protocol, application 3580 error-severity: error 3581 error-info: : name of the unexpected attribute 3582 : name of the element that contains 3583 the unexpected attribute 3584 Description: An unexpected attribute is present. 3586 error-tag: missing-element 3587 error-type: protocol, application 3588 error-severity: error 3589 error-info: : name of the missing element 3590 Description: An expected element is missing. 3592 error-tag: bad-element 3593 error-type: protocol, application 3594 error-severity: error 3595 error-info: : name of the element w/ bad value 3596 Description: An element value is not correct; e.g., wrong type, 3597 out of range, pattern mismatch. 3599 error-tag: unknown-element 3600 error-type: protocol, application 3601 error-severity: error 3602 error-info: : name of the unexpected element 3603 Description: An unexpected element is present. 3605 error-tag: unknown-namespace 3606 error-type: protocol, application 3607 error-severity: error 3608 error-info: : name of the element that contains 3609 the unexpected namespace 3610 : name of the unexpected namespace 3611 Description: An unexpected namespace is present. 3613 error-tag: access-denied 3614 error-type: protocol, application 3615 error-severity: error 3616 error-info: none 3617 Description: Access to the requested protocol operation, or 3618 data model is denied because authorization failed. 3620 error-tag: lock-denied 3621 error-type: protocol 3622 error-severity: error 3623 error-info: : session ID of session holding the 3624 requested lock, or zero to indicate a non-NETCONF 3625 entity holds the lock 3626 Description: Access to the requested lock is denied because the 3627 lock is currently held by another entity. 3629 error-tag: resource-denied 3630 error-type: transport, rpc, protocol, application 3631 error-severity: error 3632 error-info: none 3633 Description: Request could not be completed because of 3634 insufficient resources. 3636 error-tag: rollback-failed 3637 error-type: protocol, application 3638 error-severity: error 3639 error-info: none 3640 Description: Request to rollback some configuration change (via 3641 rollback-on-error or discard-changes operations) was 3642 not completed for some reason. 3644 error-tag: data-exists 3645 error-type: application 3646 error-severity: error 3647 error-info: none 3648 Description: Request could not be completed because the relevant 3649 data model content already exists. For example, 3650 a "create" operation was attempted on data that 3651 already exists. 3653 error-tag: data-missing 3654 error-type: application 3655 error-severity: error 3656 error-info: none 3657 Description: Request could not be completed because the relevant 3658 data model content does not exist. For example, 3659 a "delete" operation was attempted on 3660 data that does not exist. 3662 error-tag: operation-not-supported 3663 error-type: protocol, application 3664 error-severity: error 3665 error-info: none 3666 Description: Request could not be completed because the requested 3667 operation is not supported by this implementation. 3669 error-tag: operation-failed 3670 error-type: rpc, protocol, application 3671 error-severity: error 3672 error-info: none 3673 Description: Request could not be completed because the requested 3674 operation failed for some reason not covered by 3675 any other error condition. 3677 error-tag: partial-operation 3678 error-type: application 3679 error-severity: error 3680 error-info: : identifies an element in the data 3681 model for which the requested operation has been 3682 completed for that node and all its child nodes. 3683 This element can appear zero or more times in the 3684 container. 3686 : identifies an element in the data 3687 model for which the requested operation has failed 3688 for that node and all its child nodes. 3689 This element can appear zero or more times in the 3690 container. 3692 : identifies an element in the data 3693 model for which the requested operation was not 3694 attempted for that node and all its child nodes. 3695 This element can appear zero or more times in the 3696 container. 3698 Description: This error-tag is obsolete, and SHOULD NOT be sent 3699 by servers conforming to this document. 3701 Some part of the requested operation failed or was 3702 not attempted for some reason. Full cleanup has 3703 not been performed (e.g., rollback not supported) 3704 by the server. The error-info container is used 3705 to identify which portions of the application 3706 data model content for which the requested operation 3707 has succeeded (), failed (), 3708 or not been attempted (). 3710 error-tag: malformed-message 3711 error-type: rpc 3712 error-severity: error 3713 error-info: none 3714 Description: A message could not be handled because it failed to 3715 be parsed correctly. For example, the message is not 3716 well-formed XML or it uses an invalid character set. 3718 This error-tag is new in :base:1.1 and MUST NOT be 3719 sent to old clients. 3721 Appendix B. XML Schema for NETCONF Messages Layer 3723 This section is normative. 3725 file "netconf.xsd" 3727 3728 3736 3737 3738 This schema defines the syntax for the NETCONF Messages layer 3739 messages 'hello', 'rpc', and 'rpc-reply'. 3740 3741 3743 3746 3748 3749 3750 This import accesses the xml: attribute groups for the 3751 xml:lang as declared on the error-message element. 3752 3753 3754 3755 3758 3759 3760 3761 3762 3763 3766 3767 3768 3770 3771 3772 3773 3774 3775 3778 3779 3780 3781 3782 3784 3787 3788 3789 3790 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3839 3841 3843 3845 3847 3849 3850 3851 3852 3854 3856 3857 3858 3859 3860 3861 3862 3863 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3877 3878 3879 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3895 3896 3897 3898 3899 3901 3903 3904 3905 3907 3911 3912 3913 3914 3917 3918 3922 3923 3925 3929 3930 3932 3935 3936 3937 3938 3939 3940 3941 3943 3944 3945 3946 3948 3949 3950 3951 3953 3955 Appendix C. YANG Module for NETCONF Protocol Operations 3957 This section is normative. 3959 The ietf-netconf YANG module imports typedefs from [RFC6021]. 3961 // RFC Ed.: please update the date to the date of publication 3962 file "ietf-netconf@2011-03-08.yang" 3964 module ietf-netconf { 3966 // the namespace for NETCONF XML definitions is unchanged 3967 // from RFC 4741 which this document replaces 3968 namespace "urn:ietf:params:xml:ns:netconf:base:1.0"; 3970 prefix nc; 3972 import ietf-inet-types { 3973 prefix inet; 3974 } 3976 organization 3977 "IETF NETCONF (Network Configuration) Working Group"; 3979 contact 3980 "WG Web: 3981 WG List: 3983 WG Chair: Bert Wijnen 3984 3986 WG Chair: Mehmet Ersue 3987 3989 Editor: Martin Bjorklund 3990 3992 Editor: Juergen Schoenwaelder 3993 3995 Editor: Andy Bierman 3996 "; 3998 description 3999 "NETCONF Protocol Data Types and Protocol Operations. 4001 Copyright (c) 2010 IETF Trust and the persons identified as 4002 the document authors. All rights reserved. 4004 Redistribution and use in source and binary forms, with or 4005 without modification, is permitted pursuant to, and subject 4006 to the license terms contained in, the Simplified BSD License 4007 set forth in Section 4.c of the IETF Trust's Legal Provisions 4008 Relating to IETF Documents 4009 (http://trustee.ietf.org/license-info). 4011 This version of this YANG module is part of RFC XXXX; see 4012 the RFC itself for full legal notices."; 4013 // RFC Ed.: replace XXXX with actual RFC number and remove this note 4015 // RFC Ed.: please update the date to the date of publication 4016 revision 2011-03-08 { 4017 description 4018 "Initial revision"; 4019 reference 4020 "RFC XXXX: Network Configuration Protocol"; 4021 } 4023 extension get-filter-element-attributes { 4024 description 4025 "If this extension is present within the 4026 an 'anyxml' statement named 'filter', which must be 4027 conceptually defined within the RPC input section 4028 for the 'get' and 'get-config' protocol operations, 4029 then the following unqualified XML attribute is 4030 supported within the 'filter' element, within 4031 a 'get' or 'get-config' protocol operation: 4033 type : optional attribute with allowed 4034 value strings 'subtree' and 'xpath'. 4035 If missing, the default value is 'subtree'. 4037 If the 'xpath' feature is supported, then the 4038 following unqualified XML attribute is 4039 also supported: 4041 select: optional attribute containing a 4042 string representing an XPath expression. 4043 The 'type' attribute must be equal to 'xpath' 4044 if this attribute is present."; 4045 } 4047 // NETCONF capabilities defined as features 4048 feature writable-running { 4049 description 4050 "NETCONF :writable-running capability; 4051 If the server advertises the :writable-running 4052 capability for a session, then this feature must 4053 also be enabled for that session. Otherwise, 4054 this feature must not be enabled."; 4055 reference "RFC XXXX, section 8.2."; 4056 } 4058 feature candidate { 4059 description 4060 "NETCONF :candidate capability; 4061 If the server advertises the :candidate 4062 capability for a session, then this feature must 4063 also be enabled for that session. Otherwise, 4064 this feature must not be enabled."; 4065 reference "RFC XXXX, section 8.3."; 4066 } 4068 feature confirmed-commit { 4069 if-feature candidate; 4070 description 4071 "NETCONF :confirmed-commit:1.1 capability; 4072 If the server advertises the :confirmed-commit:1.1 4073 capability for a session, then this feature must 4074 also be enabled for that session. Otherwise, 4075 this feature must not be enabled."; 4077 reference "RFC XXXX, section 8.4."; 4078 } 4080 feature rollback-on-error { 4081 description 4082 "NETCONF :rollback-on-error capability; 4083 If the server advertises the :rollback-on-error 4084 capability for a session, then this feature must 4085 also be enabled for that session. Otherwise, 4086 this feature must not be enabled."; 4087 reference "RFC XXXX, section 8.5."; 4088 } 4090 feature validate { 4091 description 4092 "NETCONF :validate:1.1 capability; 4093 If the server advertises the :validate:1.1 4094 capability for a session, then this feature must 4095 also be enabled for that session. Otherwise, 4096 this feature must not be enabled."; 4097 reference "RFC XXXX, section 8.6."; 4098 } 4099 feature startup { 4100 description 4101 "NETCONF :startup capability; 4102 If the server advertises the :startup 4103 capability for a session, then this feature must 4104 also be enabled for that session. Otherwise, 4105 this feature must not be enabled."; 4106 reference "RFC XXXX, section 8.7."; 4107 } 4109 feature url { 4110 description 4111 "NETCONF :url capability; 4112 If the server advertises the :url 4113 capability for a session, then this feature must 4114 also be enabled for that session. Otherwise, 4115 this feature must not be enabled."; 4116 reference "RFC XXXX, section 8.8."; 4117 } 4119 feature xpath { 4120 description 4121 "NETCONF :xpath capability; 4122 If the server advertises the :xpath 4123 capability for a session, then this feature must 4124 also be enabled for that session. Otherwise, 4125 this feature must not be enabled."; 4126 reference "RFC XXXX, section 8.9."; 4127 } 4129 // NETCONF Simple Types 4131 typedef session-id-type { 4132 type uint32 { 4133 range "1..max"; 4134 } 4135 description 4136 "NETCONF Session Id"; 4137 } 4139 typedef session-id-or-zero-type { 4140 type uint32; 4141 description 4142 "NETCONF Session Id or Zero to indicate none"; 4143 } 4145 typedef error-tag-type { 4146 type enumeration { 4147 enum in-use { 4148 description 4149 "The request requires a resource that 4150 already is in use."; 4151 } 4152 enum invalid-value { 4153 description 4154 "The request specifies an unacceptable value for one 4155 or more parameters."; 4156 } 4157 enum too-big { 4158 description 4159 "The request or response (that would be generated) is 4160 too large for the implementation to handle."; 4161 } 4162 enum missing-attribute { 4163 description 4164 "An expected attribute is missing."; 4165 } 4166 enum bad-attribute { 4167 description 4168 "An attribute value is not correct; e.g., wrong type, 4169 out of range, pattern mismatch."; 4170 } 4171 enum unknown-attribute { 4172 description 4173 "An unexpected attribute is present."; 4174 } 4175 enum missing-element { 4176 description 4177 "An expected element is missing."; 4178 } 4179 enum bad-element { 4180 description 4181 "An element value is not correct; e.g., wrong type, 4182 out of range, pattern mismatch."; 4183 } 4184 enum unknown-element { 4185 description 4186 "An unexpected element is present."; 4187 } 4188 enum unknown-namespace { 4189 description 4190 "An unexpected namespace is present."; 4191 } 4192 enum access-denied { 4193 description 4194 "Access to the requested protocol operation, or 4195 data model is denied because authorization failed."; 4196 } 4197 enum lock-denied { 4198 description 4199 "Access to the requested lock is denied because the 4200 lock is currently held by another entity."; 4201 } 4202 enum resource-denied { 4203 description 4204 "Request could not be completed because of 4205 insufficient resources."; 4206 } 4207 enum rollback-failed { 4208 description 4209 "Request to rollback some configuration change (via 4210 rollback-on-error or discard-changes operations) was 4211 not completed for some reason."; 4213 } 4214 enum data-exists { 4215 description 4216 "Request could not be completed because the relevant 4217 data model content already exists. For example, 4218 a 'create' operation was attempted on data that 4219 already exists."; 4220 } 4221 enum data-missing { 4222 description 4223 "Request could not be completed because the relevant 4224 data model content does not exist. For example, 4225 a 'delete' operation was attempted on 4226 data that does not exist."; 4227 } 4228 enum operation-not-supported { 4229 description 4230 "Request could not be completed because the requested 4231 operation is not supported by this implementation."; 4232 } 4233 enum operation-failed { 4234 description 4235 "Request could not be completed because the requested 4236 operation failed for some reason not covered by 4237 any other error condition."; 4238 } 4239 enum partial-operation { 4240 description 4241 "This error-tag is obsolete, and SHOULD NOT be sent 4242 by servers conforming to this document."; 4244 } 4245 enum malformed-message { 4246 description 4247 "A message could not be handled because it failed to 4248 be parsed correctly. For example, the message is not 4249 well-formed XML or it uses an invalid character set."; 4250 } 4251 } 4252 description "NETCONF Error Tag"; 4253 reference "RFC XXXX, Appendix A."; 4254 } 4256 typedef error-severity-type { 4257 type enumeration { 4258 enum error { 4259 description "Error severity"; 4260 } 4261 enum warning { 4262 description "Warning severity"; 4263 } 4264 } 4265 description "NETCONF Error Severity"; 4266 reference "RFC XXXX, section 4.3."; 4267 } 4269 typedef edit-operation-type { 4270 type enumeration { 4271 enum merge { 4272 description 4273 "The configuration data identified by the 4274 element containing this attribute is merged 4275 with the configuration at the corresponding 4276 level in the configuration datastore identified 4277 by the target parameter."; 4278 } 4279 enum replace { 4280 description 4281 "The configuration data identified by the element 4282 containing this attribute replaces any related 4283 configuration in the configuration datastore 4284 identified by the target parameter. If no such 4285 configuration data exists in the configuration 4286 datastore, it is created. Unlike a 4287 operation, which replaces the 4288 entire target configuration, only the configuration 4289 actually present in the config parameter is affected."; 4290 } 4291 enum create { 4292 description 4293 "The configuration data identified by the element 4294 containing this attribute is added to the 4295 configuration if and only if the configuration 4296 data does not already exist in the configuration 4297 datastore. If the configuration data exists, an 4298 element is returned with an 4299 value of 'data-exists'."; 4300 } 4301 enum delete { 4302 description 4303 "The configuration data identified by the element 4304 containing this attribute is deleted from the 4305 configuration if and only if the configuration 4306 data currently exists in the configuration 4307 datastore. If the configuration data does not 4308 exist, an element is returned with 4309 an value of 'data-missing'."; 4310 } 4311 enum remove { 4312 description 4313 "The configuration data identified by the element 4314 containing this attribute is deleted from the 4315 configuration if the configuration 4316 data currently exists in the configuration 4317 datastore. If the configuration data does not 4318 exist, the 'remove' operation is silently ignored 4319 by the server."; 4320 } 4321 } 4322 default "merge"; 4323 description "NETCONF 'operation' attribute values"; 4324 reference "RFC XXXX, section 7.2."; 4325 } 4327 // NETCONF Standard Protocol Operations 4329 rpc get-config { 4330 description 4331 "Retrieve all or part of a specified configuration."; 4333 reference "RFC XXXX, section 7.1."; 4335 input { 4336 container source { 4337 description 4338 "Particular configuration to retrieve."; 4340 choice config-source { 4341 mandatory true; 4342 description 4343 "The configuration to retrieve."; 4344 leaf candidate { 4345 if-feature candidate; 4346 type empty; 4347 description 4348 "The candidate configuration is the config source."; 4349 } 4350 leaf running { 4351 type empty; 4352 description 4353 "The running configuration is the config source."; 4354 } 4355 leaf startup { 4356 if-feature startup; 4357 type empty; 4358 description 4359 "The startup configuration is the config source. 4360 This is optional-to-implement on the server because 4361 not all servers will support filtering for this 4362 datastore."; 4363 } 4364 } 4365 } 4367 anyxml filter { 4368 description 4369 "Subtree or XPath filter to use."; 4370 nc:get-filter-element-attributes; 4371 } 4372 } 4374 output { 4375 anyxml data { 4376 description 4377 "Copy of the source datastore subset which matched 4378 the filter criteria (if any). An empty data container 4379 indicates that the request did not produce any results."; 4380 } 4381 } 4382 } 4384 rpc edit-config { 4385 description 4386 "The 'edit-config' operation loads all or part of a specified 4387 configuration to the specified target configuration."; 4389 reference "RFC XXXX, section 7.2."; 4391 input { 4392 container target { 4393 description 4394 "Particular configuration to edit."; 4396 choice config-target { 4397 mandatory true; 4398 description 4399 "The configuration target."; 4401 leaf candidate { 4402 if-feature candidate; 4403 type empty; 4404 description 4405 "The candidate configuration is the config target."; 4406 } 4407 leaf running { 4408 if-feature writable-running; 4409 type empty; 4410 description 4411 "The running configuration is the config source."; 4412 } 4413 } 4414 } 4416 leaf default-operation { 4417 type enumeration { 4418 enum merge { 4419 description 4420 "The default operation is merge."; 4421 } 4422 enum replace { 4423 description 4424 "The default operation is replace."; 4425 } 4426 enum none { 4427 description 4428 "There is no default operation."; 4429 } 4430 } 4431 default "merge"; 4432 description 4433 "The default operation to use."; 4434 } 4436 leaf test-option { 4437 if-feature validate; 4438 type enumeration { 4439 enum test-then-set { 4440 description 4441 "The server will test and then set if no errors."; 4442 } 4443 enum set { 4444 description 4445 "The server will set without a test first."; 4446 } 4448 enum test-only { 4449 description 4450 "The server will only test and not set, even 4451 if there are no errors."; 4452 } 4453 } 4454 default "test-then-set"; 4455 description 4456 "The test option to use."; 4457 } 4459 leaf error-option { 4460 type enumeration { 4461 enum stop-on-error { 4462 description 4463 "The server will stop on errors."; 4464 } 4465 enum continue-on-error { 4466 description 4467 "The server may continue on errors."; 4468 } 4469 enum rollback-on-error { 4470 description 4471 "The server will rollback on errors. 4472 This value can only be used if the 'rollback-on-error' 4473 feature is supported."; 4474 } 4475 } 4476 default "stop-on-error"; 4477 description 4478 "The error option to use."; 4479 } 4481 choice edit-content { 4482 mandatory true; 4483 description 4484 "The content for the edit operation"; 4486 anyxml config { 4487 description 4488 "Inline Config content."; 4489 } 4490 leaf url { 4491 if-feature url; 4492 type inet:uri; 4493 description 4494 "URL based config content."; 4495 } 4496 } 4497 } 4498 } 4500 rpc copy-config { 4501 description 4502 "Create or replace an entire configuration datastore with the 4503 contents of another complete configuration datastore."; 4505 reference "RFC XXXX, section 7.3."; 4507 input { 4508 container target { 4509 description 4510 "Particular configuration to copy to."; 4512 choice config-target { 4513 mandatory true; 4514 description 4515 "The configuration target of the copy operation."; 4517 leaf candidate { 4518 if-feature candidate; 4519 type empty; 4520 description 4521 "The candidate configuration is the config target."; 4522 } 4523 leaf running { 4524 if-feature writable-running; 4525 type empty; 4526 description 4527 "The running configuration is the config target. 4528 This is optional-to-implement on the server."; 4529 } 4530 leaf startup { 4531 if-feature startup; 4532 type empty; 4533 description 4534 "The startup configuration is the config target."; 4535 } 4536 leaf url { 4537 if-feature url; 4538 type inet:uri; 4539 description 4540 "The URL-based configuration is the config target."; 4541 } 4542 } 4543 } 4545 container source { 4546 description 4547 "Particular configuration to copy from."; 4549 choice config-source { 4550 mandatory true; 4551 description 4552 "The configuration source for the copy operation."; 4554 leaf candidate { 4555 if-feature candidate; 4556 type empty; 4557 description 4558 "The candidate configuration is the config source."; 4559 } 4560 leaf running { 4561 type empty; 4562 description 4563 "The running configuration is the config source."; 4564 } 4565 leaf startup { 4566 if-feature startup; 4567 type empty; 4568 description 4569 "The startup configuration is the config source."; 4570 } 4571 leaf url { 4572 if-feature url; 4573 type inet:uri; 4574 description 4575 "The URL-based configuration is the config source."; 4576 } 4577 anyxml config { 4578 description 4579 "Inline Config content: 'config' element. Represents 4580 an entire configuration datastore, not 4581 a subset of the running datastore."; 4583 } 4584 } 4585 } 4586 } 4587 } 4589 rpc delete-config { 4590 description 4591 "Delete a configuration datastore."; 4593 reference "RFC XXXX, section 7.4."; 4595 input { 4596 container target { 4597 description 4598 "Particular configuration to delete."; 4600 choice config-target { 4601 mandatory true; 4602 description 4603 "The configuration target to delete."; 4605 leaf startup { 4606 if-feature startup; 4607 type empty; 4608 description 4609 "The startup configuration is the config target."; 4610 } 4611 leaf url { 4612 if-feature url; 4613 type inet:uri; 4614 description 4615 "The URL-based configuration is the config target."; 4616 } 4617 } 4618 } 4619 } 4620 } 4622 rpc lock { 4623 description 4624 "The lock operation allows the client to lock the configuration 4625 system of a device."; 4627 reference "RFC XXXX, section 7.5."; 4629 input { 4630 container target { 4631 description 4632 "Particular configuration to lock"; 4634 choice config-target { 4635 mandatory true; 4636 description 4637 "The configuration target to lock."; 4639 leaf candidate { 4640 if-feature candidate; 4641 type empty; 4642 description 4643 "The candidate configuration is the config target."; 4644 } 4645 leaf running { 4646 type empty; 4647 description 4648 "The running configuration is the config target."; 4649 } 4650 leaf startup { 4651 if-feature startup; 4652 type empty; 4653 description 4654 "The startup configuration is the config target."; 4655 } 4656 } 4657 } 4658 } 4659 } 4661 rpc unlock { 4662 description 4663 "The unlock operation is used to release a configuration lock, 4664 previously obtained with the 'lock' operation."; 4666 reference "RFC XXXX, section 7.6."; 4668 input { 4669 container target { 4670 description 4671 "Particular configuration to unlock."; 4673 choice config-target { 4674 mandatory true; 4675 description 4676 "The configuration target to unlock."; 4678 leaf candidate { 4679 if-feature candidate; 4680 type empty; 4681 description 4682 "The candidate configuration is the config target."; 4683 } 4684 leaf running { 4685 type empty; 4686 description 4687 "The running configuration is the config target."; 4688 } 4689 leaf startup { 4690 if-feature startup; 4691 type empty; 4692 description 4693 "The startup configuration is the config target."; 4694 } 4695 } 4696 } 4697 } 4698 } 4700 rpc get { 4701 description 4702 "Retrieve running configuration and device state information."; 4704 reference "RFC XXXX, section 7.7."; 4706 input { 4707 anyxml filter { 4708 description 4709 "This parameter specifies the portion of the system 4710 configuration and state data to retrieve."; 4711 nc:get-filter-element-attributes; 4712 } 4713 } 4715 output { 4716 anyxml data { 4717 description 4718 "Copy of the running datastore subset and/or state 4719 data which matched the filter criteria (if any). 4720 An empty data container indicates that the request did not 4721 produce any results."; 4722 } 4723 } 4724 } 4726 rpc close-session { 4727 description 4728 "Request graceful termination of a NETCONF session."; 4730 reference "RFC XXXX, section 7.8."; 4731 } 4733 rpc kill-session { 4734 description 4735 "Force the termination of a NETCONF session."; 4737 reference "RFC XXXX, section 7.9."; 4739 input { 4740 leaf session-id { 4741 type session-id-type; 4742 mandatory true; 4743 description 4744 "Particular session to kill."; 4745 } 4746 } 4747 } 4749 rpc commit { 4750 if-feature candidate; 4752 description 4753 "Commit the candidate configuration as the device's new 4754 current configuration"; 4756 reference "RFC XXXX, section 8.3.4.1."; 4758 input { 4759 leaf confirmed { 4760 if-feature confirmed-commit; 4761 type empty; 4762 description 4763 "Requests a confirmed commit."; 4764 reference "RFC XXXX, section 8.3.4.1."; 4765 } 4767 leaf confirm-timeout { 4768 if-feature confirmed-commit; 4769 type uint32 { 4770 range "1..max"; 4771 } 4772 units "seconds"; 4773 default "600"; // 10 minutes 4774 description 4775 "The timeout interval for a confirmed commit."; 4776 reference "RFC XXXX, section 8.3.4.1."; 4777 } 4779 leaf persist { 4780 if-feature confirmed-commit; 4781 type string; 4782 description 4783 "This parameter is used to make a confirmed commit 4784 persistent. A persistent confirmed commit is not aborted 4785 if the NETCONF session terminates. The only way to abort a 4786 persistent confirmed commit it to let the timer expire, or 4787 to use the cancel-commit operation. 4789 The value of this parameter is a token that must be given 4790 in the 'persist-id' parameter of commit or cancel-commit in 4791 order to confirm or cancel the persistent confirmed commit. 4793 The token should be a random string."; 4794 reference "RFC XXXX, section 8.3.4.1."; 4795 } 4797 leaf persist-id { 4798 if-feature confirmed-commit; 4799 type string; 4800 description 4801 "This parameter is given in order to commit a persistent 4802 confirmed commit. The value must be equal to the value 4803 given in the 'persist' parameter to the commit operation. 4804 If it does not match, the operation fails with an 4805 'invalid-value' error."; 4806 reference "RFC XXXX, section 8.3.4.1."; 4807 } 4809 } 4810 } 4812 rpc discard-changes { 4813 if-feature candidate; 4815 description 4816 "Revert the candidate configuration to the current 4817 running configuration."; 4819 reference "RFC XXXX, section 8.3.4.2."; 4820 } 4822 rpc cancel-commit { 4823 if-feature confirmed-commit; 4824 description 4825 "This operation is used to cancel an ongoing confirmed commit. 4826 If the confirmed commit is persistent, the parameter 4827 'persist-id' must be given, and it must match the value of the 4828 'persist' parameter."; 4829 reference "RFC XXXX, section 8.4.4.1."; 4831 input { 4832 leaf persist-id { 4833 type string; 4834 description 4835 "This parameter is given in order to cancel a persistent 4836 confirmed commit. The value must be equal to the value 4837 given in the 'persist' parameter to the commit operation. 4838 If it does not match, the operation fails with an 4839 'invalid-value' error."; 4840 } 4841 } 4842 } 4844 rpc validate { 4845 if-feature validate; 4847 description 4848 "Validates the contents of the specified configuration."; 4850 reference "RFC XXXX, section 8.6.4.1."; 4852 input { 4853 container source { 4854 description 4855 "Particular configuration to validate."; 4857 choice config-source { 4858 mandatory true; 4859 description 4860 "The configuration source to validate."; 4862 leaf candidate { 4863 if-feature candidate; 4864 type empty; 4865 description 4866 "The candidate configuration is the config source."; 4867 } 4868 leaf running { 4869 type empty; 4870 description 4871 "The running configuration is the config source."; 4872 } 4873 leaf startup { 4874 if-feature startup; 4875 type empty; 4876 description 4877 "The startup configuration is the config source."; 4878 } 4879 leaf url { 4880 if-feature url; 4881 type inet:uri; 4882 description 4883 "The URL-based configuration is the config source."; 4884 } 4885 anyxml config { 4886 description 4887 "Inline Config content: 'config' element. Represents 4888 an entire configuration datastore, not 4889 a subset of the running datastore."; 4890 } 4891 } 4892 } 4893 } 4894 } 4896 } 4898 4900 Appendix D. Capability Template 4902 This non-normative section defines a template that can be used to 4903 define protocol capabilities. Data models written in YANG usually do 4904 not need to define protocol capabilities since the usage of YANG 4905 automatically leads to a capability announcing the data model and any 4906 optional portions of the data model, so called features in YANG 4907 terminology. The capabilities template is intended to be used in 4908 cases where the YANG mechanisms are not powerful enough (e.g., for 4909 handling parametrized features) or a different data modeling language 4910 is used. 4912 D.1. capability-name (template) 4914 D.1.1. Overview 4916 D.1.2. Dependencies 4918 D.1.3. Capability Identifier 4920 The {name} capability is identified by the following capability 4921 string: 4923 {capability uri} 4925 D.1.4. New Operations 4927 D.1.4.1. 4929 D.1.5. Modifications to Existing Operations 4931 D.1.5.1. 4933 If existing operations are not modified by this capability, this 4934 section may be omitted. 4936 D.1.6. Interactions with Other Capabilities 4938 If this capability does not interact with other capabilities, this 4939 section may be omitted. 4941 Appendix E. Configuring Multiple Devices with NETCONF 4943 This section is non-normative. 4945 E.1. Operations on Individual Devices 4947 Consider the work involved in performing a configuration update 4948 against a single individual device. In making a change to the 4949 configuration, the application needs to build trust that its change 4950 has been made correctly and that it has not impacted the operation of 4951 the device. The application (and the application user) should feel 4952 confident that their change has not damaged the network. 4954 Protecting each individual device consists of a number of steps: 4956 o Acquiring the configuration lock. 4958 o Checkpointing the running configuration. 4960 o Loading and validating the incoming configuration. 4962 o Changing the running configuration. 4964 o Testing the new configuration. 4966 o Making the change permanent (if desired). 4968 o Releasing the configuration lock. 4970 Let's look at the details of each step. 4972 E.1.1. Acquiring the Configuration Lock 4974 A lock should be acquired to prevent simultaneous updates from 4975 multiple sources. If multiple sources are affecting the device, the 4976 application is hampered in both testing of its change to the 4977 configuration and in recovery if the update fails. Acquiring a 4978 short-lived lock is a simple defense to prevent other parties from 4979 introducing unrelated changes. 4981 The lock can be acquired using the operation. 4983 4985 4986 4987 4988 4989 4990 4992 If the :candidate capability is supported, the candidate 4993 configuration should be locked. 4995 4997 4998 4999 5000 5001 5002 5004 E.1.2. Checkpointing the Running Configuration 5006 The running configuration can be saved into a local file as a 5007 checkpoint before loading the new configuration. If the update 5008 fails, the configuration can be restored by reloading the checkpoint 5009 file. 5011 The checkpoint file can be created using the operation. 5013 5015 5016 5017 file://checkpoint.conf 5018 5019 5020 5021 5022 5023 5025 To restore the checkpoint file, reverse the and 5026 parameters. 5028 E.1.3. Loading and Validating the Incoming Configuration. 5030 If the :candidate capability is supported, the configuration can be 5031 loaded onto the device without impacting the running system. 5033 5035 5036 5037 5038 5039 5040 5041 5042 5043 5045 If the device supports the :validate:1.1 capability, it will by 5046 default validate the incoming configuration when it is loaded into 5047 the candidate. To avoid this validation, pass the 5048 parameter with the value "set". Full validation can be requested 5049 with the operation. 5051 5053 5054 5055 5056 5057 5058 5060 E.1.4. Changing the Running Configuration 5062 When the incoming configuration has been safely loaded onto the 5063 device and validated, it is ready to impact the running system. 5065 If the device supports the :candidate capability, use the 5066 operation to set the running configuration to the candidate 5067 configuration. Use the parameter to allow automatic 5068 reversion to the original configuration if connectivity to the device 5069 fails. 5071 5073 5074 5075 120 5076 5077 5079 If the candidate is not supported by the device, the incoming 5080 configuration change is loaded directly into running. 5082 5084 5085 5086 5087 5088 5089 5090 5091 5092 5094 E.1.5. Testing the New Configuration 5096 Now that the incoming configuration has been integrated into the 5097 running configuration, the application needs to gain trust that the 5098 change has affected the device in the way intended without affecting 5099 it negatively. 5101 To gain this confidence, the application can run tests of the 5102 operational state of the device. The nature of the test is dependent 5103 on the nature of the change and is outside the scope of this 5104 document. Such tests may include reachability from the system 5105 running the application (using ping), changes in reachability to the 5106 rest of the network (by comparing the device's routing table), or 5107 inspection of the particular change (looking for operational evidence 5108 of the BGP peer that was just added). 5110 E.1.6. Making the Change Permanent 5112 When the configuration change is in place and the application has 5113 sufficient faith in the proper function of this change, the 5114 application is expected to make the change permanent. 5116 If the device supports the :startup capability, the current 5117 configuration can be saved to the startup configuration by using the 5118 startup configuration as the target of the operation. 5120 5122 5123 5124 5125 5126 5127 5128 5129 5130 5132 If the device supports the :candidate capability and a confirmed 5133 commit was requested, the confirming commit must be sent before the 5134 timeout expires. 5136 5138 5139 5141 E.1.7. Releasing the Configuration Lock 5143 When the configuration update is complete, the lock must be released, 5144 allowing other applications access to the configuration. 5146 Use the operation to release the configuration lock. 5148 5150 5151 5152 5153 5154 5155 5157 If the :candidate capability is supported, the candidate 5158 configuration should be unlocked. 5160 5162 5163 5164 5165 5166 5167 5169 E.2. Operations on Multiple Devices 5171 When a configuration change requires updates across a number of 5172 devices, care needs to be taken to provide the required transaction 5173 semantics. The NETCONF protocol contains sufficient primitives upon 5174 which transaction-oriented operations can be built. Providing 5175 complete transactional semantics across multiple devices is 5176 prohibitively expensive, but the size and number of windows for 5177 failure scenarios can be reduced. 5179 There are two classes of multi-device operations. The first class 5180 allows the operation to fail on individual devices without requiring 5181 all devices to revert to their original state. The operation can be 5182 retried at a later time, or its failure simply reported to the user. 5183 An example of this class might be adding an NTP server. For this 5184 class of operations, failure avoidance and recovery are focused on 5185 the individual device. This means recovery of the device, reporting 5186 the failure, and perhaps scheduling another attempt. 5188 The second class is more interesting, requiring that the operation 5189 should complete on all devices or be fully reversed. The network 5190 should either be transformed into a new state or be reset to its 5191 original state. For example, a change to a VPN may require updates 5192 to a number of devices. Another example of this might be adding a 5193 class-of-service definition. Leaving the network in a state where 5194 only a portion of the devices have been updated with the new 5195 definition will lead to future failures when the definition is 5196 referenced. 5198 To give transactional semantics, the same steps used in single device 5199 operations listed above are used, but are performed in parallel 5200 across all devices. Configuration locks should be acquired on all 5201 target devices and kept until all devices are updated and the changes 5202 made permanent. Configuration changes should be uploaded and 5203 validation performed across all devices. Checkpoints should be made 5204 on each device. Then the running configuration can be changed, 5205 tested, and made permanent. If any of these steps fail, the previous 5206 configurations can be restored on any devices upon which they were 5207 changed. After the changes have been completely implemented or 5208 completely discarded, the locks on each device can be released. 5210 Appendix F. Changes from RFC 4741 5212 This section lists major changes between this document and RFC 4741. 5214 o Added the "malformed-message" error-tag. 5216 o Added "remove" enumeration value to the "operation" attribute. 5218 o Obsoleted the "partial-operation" error-tag enumeration value. 5220 o Added and parameters to the 5221 operation. 5223 o Updated the base protocol URI and clarified the message 5224 exchange to select and identify the base protocol version in use 5225 for a particular session. 5227 o Added a YANG module to model the operations and removed the 5228 operation layer from the XSD. 5230 o Clarified lock behavior for the candidate datastore. 5232 o Clarified the error response server requirements for the "delete" 5233 enumeration value of the "operation" attribute. 5235 o Added a namespace wildcarding mechanism for subtree filtering. 5237 o Added a "test-only" value for the parameter to the 5238 operation. 5240 o Added a operation. 5242 o Introduced a NETCONF username and a requirement for transport 5243 protocols to explain how a username is derived. 5245 Authors' Addresses 5247 Rob Enns (editor) 5248 Juniper Networks 5250 Email: rob.enns@gmail.com 5252 Martin Bjorklund (editor) 5253 Tail-f Systems 5255 Email: mbj@tail-f.com 5257 Juergen Schoenwaelder (editor) 5258 Jacobs University 5260 Email: j.schoenwaelder@jacobs-university.de 5262 Andy Bierman (editor) 5263 Brocade 5265 Email: andy.bierman@brocade.com