draft-ietf-netconf-4741bis-10.txt   rfc6241.txt 
Network Working Group R. Enns, Ed. Internet Engineering Task Force (IETF) R. Enns, Ed.
Internet-Draft Juniper Networks Request for Comments: 6241 Juniper Networks
Obsoletes: 4741 (if approved) M. Bjorklund, Ed. Obsoletes: 4741 M. Bjorklund, Ed.
Intended status: Standards Track Tail-f Systems Category: Standards Track Tail-f Systems
Expires: September 15, 2011 J. Schoenwaelder, Ed. ISSN: 2070-1721 J. Schoenwaelder, Ed.
Jacobs University Jacobs University
A. Bierman, Ed. A. Bierman, Ed.
Brocade Brocade
March 14, 2011 June 2011
Network Configuration Protocol (NETCONF) Network Configuration Protocol (NETCONF)
draft-ietf-netconf-4741bis-10
Abstract Abstract
The Network Configuration Protocol (NETCONF) defined in this document The Network Configuration Protocol (NETCONF) defined in this document
provides mechanisms to install, manipulate, and delete the provides mechanisms to install, manipulate, and delete the
configuration of network devices. It uses an Extensible Markup configuration of network devices. It uses an Extensible Markup
Language (XML)-based data encoding for the configuration data as well Language (XML)-based data encoding for the configuration data as well
as the protocol messages. The NETCONF protocol operations are as the protocol messages. The NETCONF protocol operations are
realized as Remote Procedure Calls (RPC). This document obsoletes realized as remote procedure calls (RPCs). This document obsoletes
RFC 4741. RFC 4741.
Status of this Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering This is an Internet Standards Track document.
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
This Internet-Draft will expire on September 15, 2011. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6241.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 12 skipping to change at page 3, line 12
it for publication as an RFC or to translate it into languages other it for publication as an RFC or to translate it into languages other
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7
1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8
1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . 10 1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . 10
1.4. Separation of Configuration and State Data . . . . . . . 10 1.4. Separation of Configuration and State Data . . . . . . . 10
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 12 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 11
2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 12 2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 11
2.2. Authentication, Integrity, and Confidentiality . . . . . 12 2.2. Authentication, Integrity, and Confidentiality . . . . . 12
2.3. Mandatory Transport Protocol . . . . . . . . . . . . . . 13 2.3. Mandatory Transport Protocol . . . . . . . . . . . . . . 12
3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 14 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 13
3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 14 3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2. Document Type Declarations . . . . . . . . . . . . . . . 14 3.2. Document Type Declarations . . . . . . . . . . . . . . . 13
4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 15 4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 13
4.2. <rpc-reply> Element . . . . . . . . . . . . . . . . . . . 16 4.2. <rpc-reply> Element . . . . . . . . . . . . . . . . . . . 15
4.3. <rpc-error> Element . . . . . . . . . . . . . . . . . . . 17 4.3. <rpc-error> Element . . . . . . . . . . . . . . . . . . . 16
4.4. <ok> Element . . . . . . . . . . . . . . . . . . . . . . 20 4.4. <ok> Element . . . . . . . . . . . . . . . . . . . . . . 19
4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 21 4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 19
5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 22 5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 19
5.1. Configuration Datastores . . . . . . . . . . . . . . . . 22 5.1. Configuration Datastores . . . . . . . . . . . . . . . . 19
5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 22 5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 20
6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 23 6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 20
6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 23 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 20
6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 23 6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 21
6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 24 6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 21
6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 24 6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 22
6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 25 6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 23
6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 25 6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 23
6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 26 6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 24
6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 27 6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 25
6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 28 6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 26
6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 28 6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 26
6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 28 6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 26
6.4.3. Select the Entire <users> Subtree . . . . . . . . . . 29 6.4.3. Select the Entire <users> Subtree . . . . . . . . . . 27
6.4.4. Select All <name> Elements within the <users> 6.4.4. Select All <name> Elements within the <users>
Subtree . . . . . . . . . . . . . . . . . . . . . . . 31 Subtree . . . . . . . . . . . . . . . . . . . . . . . 29
6.4.5. One Specific <user> Entry . . . . . . . . . . . . . . 32 6.4.5. One Specific <user> Entry . . . . . . . . . . . . . . 30
6.4.6. Specific Elements from a Specific <user> Entry . . . 33 6.4.6. Specific Elements from a Specific <user> Entry . . . 31
6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 34 6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 32
6.4.8. Elements with Attribute Naming . . . . . . . . . . . 36 6.4.8. Elements with Attribute Naming . . . . . . . . . . . 33
7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 38 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 35
7.1. <get-config> . . . . . . . . . . . . . . . . . . . . . . 38 7.1. <get-config> . . . . . . . . . . . . . . . . . . . . . . 35
7.2. <edit-config> . . . . . . . . . . . . . . . . . . . . . . 40 7.2. <edit-config> . . . . . . . . . . . . . . . . . . . . . . 37
7.3. <copy-config> . . . . . . . . . . . . . . . . . . . . . . 47 7.3. <copy-config> . . . . . . . . . . . . . . . . . . . . . . 43
7.4. <delete-config> . . . . . . . . . . . . . . . . . . . . . 49 7.4. <delete-config> . . . . . . . . . . . . . . . . . . . . . 44
7.5. <lock> . . . . . . . . . . . . . . . . . . . . . . . . . 49 7.5. <lock> . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.6. <unlock> . . . . . . . . . . . . . . . . . . . . . . . . 52 7.6. <unlock> . . . . . . . . . . . . . . . . . . . . . . . . 47
7.7. <get> . . . . . . . . . . . . . . . . . . . . . . . . . . 53 7.7. <get> . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.8. <close-session> . . . . . . . . . . . . . . . . . . . . . 55 7.8. <close-session> . . . . . . . . . . . . . . . . . . . . . 49
7.9. <kill-session> . . . . . . . . . . . . . . . . . . . . . 56 7.9. <kill-session> . . . . . . . . . . . . . . . . . . . . . 50
8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 58 8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 51
8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 58 8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 51
8.2. Writable-Running Capability . . . . . . . . . . . . . . . 59 8.2. Writable-Running Capability . . . . . . . . . . . . . . . 53
8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 59 8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 53
8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 59 8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 53
8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 59 8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 53
8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 60 8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 53
8.2.5. Modifications to Existing Operations . . . . . . . . 60 8.2.5. Modifications to Existing Operations . . . . . . . . 53
8.3. Candidate Configuration Capability . . . . . . . . . . . 60 8.3. Candidate Configuration Capability . . . . . . . . . . . 53
8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 60 8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 53
8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 61 8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 54
8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 61 8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 54
8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 61 8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 54
8.3.5. Modifications to Existing Operations . . . . . . . . 62 8.3.5. Modifications to Existing Operations . . . . . . . . 56
8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 63 8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 57
8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 63 8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 57
8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65 8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 58
8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 65 8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 58
8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 65 8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 59
8.4.5. Modifications to Existing Operations . . . . . . . . 66 8.4.5. Modifications to Existing Operations . . . . . . . . 60
8.5. Rollback on Error Capability . . . . . . . . . . . . . . 68 8.5. Rollback-on-Error Capability . . . . . . . . . . . . . . 61
8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 68 8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 61
8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 69 8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 62
8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 69 8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 62
8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 69 8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 62
8.5.5. Modifications to Existing Operations . . . . . . . . 69 8.5.5. Modifications to Existing Operations . . . . . . . . 62
8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 70 8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 63
8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 70 8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 63
8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 70 8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 63
8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 70 8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 63
8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 70 8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 63
8.6.5. Modifications to Existing Operations . . . . . . . . 71 8.6.5. Modifications to Existing Operations . . . . . . . . 64
8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 71 8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 64
8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 71 8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 64
8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 72 8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65
8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 72 8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 65
8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 72 8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 65
8.7.5. Modifications to Existing Operations . . . . . . . . 72 8.7.5. Modifications to Existing Operations . . . . . . . . 65
8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 73 8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 66
8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 73 8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 66
8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 73 8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 66
8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 73 8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 66
8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 73 8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 66
8.8.5. Modifications to Existing Operations . . . . . . . . 73 8.8.5. Modifications to Existing Operations . . . . . . . . 66
8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 74 8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 67
8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 74 8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 67
8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 75 8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 68
8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 75 8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 68
8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 75 8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 68
8.9.5. Modifications to Existing Operations . . . . . . . . 75 8.9.5. Modifications to Existing Operations . . . . . . . . 68
9. Security Considerations . . . . . . . . . . . . . . . . . . . 77 9. Security Considerations . . . . . . . . . . . . . . . . . . . 69
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 71
10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 79 10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 71
10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 79 10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 71
10.3. NETCONF YANG Module . . . . . . . . . . . . . . . . . . . 79 10.3. NETCONF YANG Module . . . . . . . . . . . . . . . . . . . 72
10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 79 10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 72
11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 81 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 73
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 73
12.1. Normative References . . . . . . . . . . . . . . . . . . 82 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 74
12.2. Informative References . . . . . . . . . . . . . . . . . 83 13.1. Normative References . . . . . . . . . . . . . . . . . . 74
Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 84 13.2. Informative References . . . . . . . . . . . . . . . . . 75
Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 88 Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 76
Appendix C. YANG Module for NETCONF Protocol Operations . . . . 93 Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 80
Appendix D. Capability Template . . . . . . . . . . . . . . . . 113 Appendix C. YANG Module for NETCONF Protocol Operations . . . . 85
D.1. capability-name (template) . . . . . . . . . . . . . . . 113 Appendix D. Capability Template . . . . . . . . . . . . . . . . 105
D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 113 D.1. capability-name (template) . . . . . . . . . . . . . . . 105
D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 113 D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 105
D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 113 D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 105
D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 113 D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 105
D.1.5. Modifications to Existing Operations . . . . . . . . 113 D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 105
D.1.6. Interactions with Other Capabilities . . . . . . . . 113 D.1.5. Modifications to Existing Operations . . . . . . . . 105
Appendix E. Configuring Multiple Devices with NETCONF . . . . . 114 D.1.6. Interactions with Other Capabilities . . . . . . . . 105
E.1. Operations on Individual Devices . . . . . . . . . . . . 114 Appendix E. Configuring Multiple Devices with NETCONF . . . . . 106
E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 114 E.1. Operations on Individual Devices . . . . . . . . . . . . 106
E.1.2. Checkpointing the Running Configuration . . . . . . . 115 E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 106
E.1.3. Loading and Validating the Incoming Configuration. . 116 E.1.2. Checkpointing the Running Configuration . . . . . . . 107
E.1.4. Changing the Running Configuration . . . . . . . . . 116 E.1.3. Loading and Validating the Incoming Configuration . . 108
E.1.5. Testing the New Configuration . . . . . . . . . . . . 117 E.1.4. Changing the Running Configuration . . . . . . . . . 108
E.1.6. Making the Change Permanent . . . . . . . . . . . . . 117 E.1.5. Testing the New Configuration . . . . . . . . . . . . 109
E.1.7. Releasing the Configuration Lock . . . . . . . . . . 118 E.1.6. Making the Change Permanent . . . . . . . . . . . . . 109
E.2. Operations on Multiple Devices . . . . . . . . . . . . . 119 E.1.7. Releasing the Configuration Lock . . . . . . . . . . 110
Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 120 E.2. Operations on Multiple Devices . . . . . . . . . . . . . 111
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 121 Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 112
1. Introduction 1. Introduction
The NETCONF protocol defines a simple mechanism through which a The NETCONF protocol defines a simple mechanism through which a
network device can be managed, configuration data information can be network device can be managed, configuration data information can be
retrieved, and new configuration data can be uploaded and retrieved, and new configuration data can be uploaded and
manipulated. The protocol allows the device to expose a full, formal manipulated. The protocol allows the device to expose a full, formal
application programming interface (API). Applications can use this application programming interface (API). Applications can use this
straightforward API to send and receive full and partial straightforward API to send and receive full and partial
configuration data sets. configuration data sets.
skipping to change at page 7, line 17 skipping to change at page 7, line 20
o candidate configuration datastore: A configuration datastore that o candidate configuration datastore: A configuration datastore that
can be manipulated without impacting the device's current can be manipulated without impacting the device's current
configuration and that can be committed to the running configuration and that can be committed to the running
configuration datastore. Not all devices support a candidate configuration datastore. Not all devices support a candidate
configuration datastore. configuration datastore.
o capability: A functionality that supplements the base NETCONF o capability: A functionality that supplements the base NETCONF
specification. specification.
o client: A client invokes protocol operations on a server. In o client: Invokes protocol operations on a server. In addition, a
addition, a client can subscribe to receive notifications from a client can subscribe to receive notifications from a server.
server.
o configuration data: Configuration data is the set of writable data o configuration data: The set of writable data that is required to
that is required to transform a system from its initial default transform a system from its initial default state into its current
state into its current state. state.
o datastore: A conceptual place to store and access information. A o datastore: A conceptual place to store and access information. A
datastore might be implemented, for example, using files, a datastore might be implemented, for example, using files, a
database, flash memory locations or combinations thereof. database, flash memory locations, or combinations thereof.
o configuration datastore: A configuration datastore is defined as o configuration datastore: The datastore holding the complete set of
the datastore holding the complete set of configuration data that configuration data that is required to get a device from its
is required to get a device from its initial default state into a initial default state into a desired operational state.
desired operational state.
o message: A protocol element sent over a session. Messages are o message: A protocol element sent over a session. Messages are
well-formed XML documents. well-formed XML documents.
o notification: A server initiated message indicating that a certain o notification: A server-initiated message indicating that a certain
event has been recognized by the server. event has been recognized by the server.
o protocol operation: A specific remote procedure call, as used o protocol operation: A specific remote procedure call, as used
within the NETCONF protocol. within the NETCONF protocol.
o remote procedure call: A remote procedure call (RPC), realized by o remote procedure call (RPC): Realized by exchanging <rpc> and
exchanging <rpc> and <rpc-reply> messages. <rpc-reply> messages.
o running configuration datastore: A configuration datastore holding o running configuration datastore: A configuration datastore holding
the complete configuration currently active on the device. The the complete configuration currently active on the device. The
running configuration datastore always exists. running configuration datastore always exists.
o server: A server executes protocol operations invoked by a client. o server: Executes protocol operations invoked by a client. In
In addition, a server can send notifications to a client. addition, a server can send notifications to a client.
o session: Client and server exchange messages using a secure, o session: Client and server exchange messages using a secure,
connection-oriented session. connection-oriented session.
o startup configuration datastore: The configuration datastore o startup configuration datastore: The configuration datastore
holding the configuration loaded by the device when it boots. holding the configuration loaded by the device when it boots.
Only present on devices that separate the startup configuration Only present on devices that separate the startup configuration
datastore from the running configuration datastore. datastore from the running configuration datastore.
o state data: State data is the additional data on a system that is o state data: The additional data on a system that is not
not configuration data such as read-only status information and configuration data such as read-only status information and
collected statistics. collected statistics.
o user: The authenticated identity of the client. The authenticated o user: The authenticated identity of the client. The authenticated
identity of a client is commonly referred to as the NETCONF identity of a client is commonly referred to as the NETCONF
username. username.
1.2. Protocol Overview 1.2. Protocol Overview
NETCONF uses a simple RPC-based mechanism to facilitate communication NETCONF uses a simple RPC-based mechanism to facilitate communication
between a client and a server. The client can be a script or between a client and a server. The client can be a script or
skipping to change at page 9, line 23 skipping to change at page 9, line 23
| | | | | | | | | |
+-------------+ +-----------------+ | +-------------+ +-----------------+ |
| | | | | |
+-------------+ +-----------------+ +----------------+ +-------------+ +-----------------+ +----------------+
(2) | Messages | | <rpc>, | | <notification> | (2) | Messages | | <rpc>, | | <notification> |
| | | <rpc-reply> | | | | | | <rpc-reply> | | |
+-------------+ +-----------------+ +----------------+ +-------------+ +-----------------+ +----------------+
| | | | | |
+-------------+ +-----------------------------------------+ +-------------+ +-----------------------------------------+
(1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... | (1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... |
| Transports | | | | Transport | | |
+-------------+ +-----------------------------------------+ +-------------+ +-----------------------------------------+
Figure 1: NETCONF Protocol Layers Figure 1: NETCONF Protocol Layers
1. The Secure Transport layer provides a communication path between (1) The Secure Transport layer provides a communication path between
the client and server. NETCONF can be layered over any transport the client and server. NETCONF can be layered over any
protocol that provides a set of basic requirements. Section 2 transport protocol that provides a set of basic requirements.
discusses these requirements. Section 2 discusses these requirements.
2. The Messages layer provides a simple, transport-independent (2) The Messages layer provides a simple, transport-independent
framing mechanism for encoding RPCs and notifications. Section 4 framing mechanism for encoding RPCs and notifications.
documents the RPC messages, and [RFC5717] documents Section 4 documents the RPC messages, and [RFC5717] documents
notifications. notifications.
3. The Operations layer defines a set of base protocol operations (3) The Operations layer defines a set of base protocol operations
invoked as RPC methods with XML-encoded parameters. Section 7 invoked as RPC methods with XML-encoded parameters. Section 7
details the list of base protocol operations. details the list of base protocol operations.
4. The Content layer is outside the scope of this document. It is (4) The Content layer is outside the scope of this document. It is
expected that separate efforts to standardize NETCONF data models expected that separate efforts to standardize NETCONF data
will be undertaken. models will be undertaken.
The YANG data modeling language [RFC6020] has been developed for The YANG data modeling language [RFC6020] has been developed for
specifying NETCONF data models and protocol operations, covering the specifying NETCONF data models and protocol operations, covering the
Operations and the Content layers of Figure 1. Operations and the Content layers of Figure 1.
1.3. Capabilities 1.3. Capabilities
A NETCONF capability is a set of functionality that supplements the A NETCONF capability is a set of functionality that supplements the
base NETCONF specification. The capability is identified by a base NETCONF specification. The capability is identified by a
uniform resource identifier (URI) [RFC3986]. uniform resource identifier (URI) [RFC3986].
skipping to change at page 12, line 45 skipping to change at page 12, line 12
holds a lock, the server can perform any appropriate recovery. The holds a lock, the server can perform any appropriate recovery. The
<lock> operation is further discussed in Section 7.5. <lock> operation is further discussed in Section 7.5.
2.2. Authentication, Integrity, and Confidentiality 2.2. Authentication, Integrity, and Confidentiality
NETCONF connections MUST provide authentication, data integrity, NETCONF connections MUST provide authentication, data integrity,
confidentiality, and replay protection. NETCONF depends on the confidentiality, and replay protection. NETCONF depends on the
transport protocol for this capability. A NETCONF peer assumes that transport protocol for this capability. A NETCONF peer assumes that
appropriate levels of security and confidentiality are provided appropriate levels of security and confidentiality are provided
independently of this document. For example, connections could be independently of this document. For example, connections could be
encrypted using TLS [RFC5246] or SSH [RFC4251], depending on the encrypted using Transport Layer Security (TLS) [RFC5246] or Secure
underlying protocol. Shell (SSH) [RFC4251], depending on the underlying protocol.
NETCONF connections MUST be authenticated. The transport protocol is NETCONF connections MUST be authenticated. The transport protocol is
responsible for authentication of the server to the client and responsible for authentication of the server to the client and
authentication of the client to the server. A NETCONF peer assumes authentication of the client to the server. A NETCONF peer assumes
that the connection's authentication information has been validated that the connection's authentication information has been validated
by the underlying transport protocol using sufficiently trustworthy by the underlying transport protocol using sufficiently trustworthy
mechanisms and that the peer's identity has been sufficiently proven. mechanisms and that the peer's identity has been sufficiently proven.
One goal of NETCONF is to provide a programmatic interface to the One goal of NETCONF is to provide a programmatic interface to the
device that closely follows the functionality of the device's native device that closely follows the functionality of the device's native
interface. Therefore, it is expected that the underlying protocol interface. Therefore, it is expected that the underlying protocol
uses existing authentication mechanisms available on the device. For uses existing authentication mechanisms available on the device. For
example, a NETCONF server on a device that supports RADIUS [RFC2865] example, a NETCONF server on a device that supports RADIUS [RFC2865]
might allow the use of RADIUS to authenticate NETCONF sessions. might allow the use of RADIUS to authenticate NETCONF sessions.
The authentication process MUST result in an authenticated client The authentication process MUST result in an authenticated client
identity whose permissions are known to the server. The identity whose permissions are known to the server. The
authenticated identity of a client is commonly referred to as the authenticated identity of a client is commonly referred to as the
NETCONF username. The username is a string of characters that match NETCONF username. The username is a string of characters that match
the "Char" production from section 2.2 of [W3C.REC-xml-20001006] . the "Char" production from Section 2.2 of [W3C.REC-xml-20001006].
The algorithm used to derive the username is transport protocol The algorithm used to derive the username is transport protocol
specific and in addition specific to the authentication mechanism specific and in addition specific to the authentication mechanism
used by the transport protocol. The transport protocol MUST provide used by the transport protocol. The transport protocol MUST provide
a username to be used by the other NETCONF layers. a username to be used by the other NETCONF layers.
The access permissions of a given client, identified by its NETCONF The access permissions of a given client, identified by its NETCONF
username, are part of the configuration of the NETCONF server. These username, are part of the configuration of the NETCONF server. These
permissions MUST be enforced during the remainder of the NETCONF permissions MUST be enforced during the remainder of the NETCONF
session. The details how access control is configured is outside the session. The details of how access control is configured is outside
scope of this document. the scope of this document.
2.3. Mandatory Transport Protocol 2.3. Mandatory Transport Protocol
A NETCONF implementation MUST support the SSH transport protocol A NETCONF implementation MUST support the SSH transport protocol
mapping [I-D.ietf-netconf-rfc4742bis]. mapping [RFC6242].
3. XML Considerations 3. XML Considerations
XML serves as the encoding format for NETCONF, allowing complex XML serves as the encoding format for NETCONF, allowing complex
hierarchical data to be expressed in a text format that can be read, hierarchical data to be expressed in a text format that can be read,
saved, and manipulated with both traditional text tools and tools saved, and manipulated with both traditional text tools and tools
specific to XML. specific to XML.
All NETCONF messages MUST be well-formed XML, encoded in UTF-8 All NETCONF messages MUST be well-formed XML, encoded in UTF-8
[RFC3629]. If a peer receives an <rpc> message that is not well- [RFC3629]. If a peer receives an <rpc> message that is not well-
formed XML or not encoded in UTF-8, it SHOULD reply with a formed XML or not encoded in UTF-8, it SHOULD reply with a
"malformed-message" error. If a reply cannot be sent for any reason, "malformed-message" error. If a reply cannot be sent for any reason,
the server MUST terminate the session. the server MUST terminate the session.
A NETCONF message MAY begin with an XML declaration (see section 2.8 A NETCONF message MAY begin with an XML declaration (see Section 2.8
of [W3C.REC-xml-20001006]). of [W3C.REC-xml-20001006]).
This section discusses a small number of XML-related considerations This section discusses a small number of XML-related considerations
pertaining to NETCONF. pertaining to NETCONF.
3.1. Namespace 3.1. Namespace
All NETCONF protocol elements are defined in the following namespace: All NETCONF protocol elements are defined in the following namespace:
urn:ietf:params:xml:ns:netconf:base:1.0 urn:ietf:params:xml:ns:netconf:base:1.0
NETCONF capability names MUST be URIs [RFC3986]. NETCONF NETCONF capability names MUST be URIs [RFC3986]. NETCONF
capabilities are discussed in Section 8. capabilities are discussed in Section 8.
3.2. Document Type Declarations 3.2. Document Type Declarations
Document type declarations (see section 2.8 of Document type declarations (see Section 2.8 of
[W3C.REC-xml-20001006]) MUST NOT appear in NETCONF content. [W3C.REC-xml-20001006]) MUST NOT appear in NETCONF content.
4. RPC Model 4. RPC Model
The NETCONF protocol uses an RPC-based communication model. NETCONF The NETCONF protocol uses an RPC-based communication model. NETCONF
peers use <rpc> and <rpc-reply> elements to provide transport peers use <rpc> and <rpc-reply> elements to provide transport-
protocol-independent framing of NETCONF requests and responses. protocol-independent framing of NETCONF requests and responses.
The syntax and XML encoding of the Messages layer RPCs are formally The syntax and XML encoding of the Messages-layer RPCs are formally
defined in the XML schema in Appendix B. defined in the XML schema in Appendix B.
4.1. <rpc> Element 4.1. <rpc> Element
The <rpc> element is used to enclose a NETCONF request sent from the The <rpc> element is used to enclose a NETCONF request sent from the
client to the server. client to the server.
The <rpc> element has a mandatory attribute "message-id", which is a The <rpc> element has a mandatory attribute "message-id", which is a
string chosen by the sender of the RPC that will commonly encode a string chosen by the sender of the RPC that will commonly encode a
monotonically increasing integer. The receiver of the RPC does not monotonically increasing integer. The receiver of the RPC does not
skipping to change at page 18, line 16 skipping to change at page 16, line 46
Appendix A for allowed values. Appendix A for allowed values.
error-severity: Contains a string identifying the error severity, as error-severity: Contains a string identifying the error severity, as
determined by the device. One of: determined by the device. One of:
* error * error
* warning * warning
Note that there are no <error-tag> values defined in this document Note that there are no <error-tag> values defined in this document
which utilize the "warning" enumeration. This is reserved for that utilize the "warning" enumeration. This is reserved for
future use. future use.
error-app-tag: Contains a string identifying the data-model-specific error-app-tag: Contains a string identifying the data-model-specific
or implementation-specific error condition, if one exists. This or implementation-specific error condition, if one exists. This
element will not be present if no appropriate application error element will not be present if no appropriate application error-
tag can be associated with a particular error condition. If a tag can be associated with a particular error condition. If a
data-model specific and a implementation-specific error-app-tag data-model-specific and an implementation-specific error-app-tag
both exist, then the data-model specific value MUST be used by the both exist, then the data-model-specific value MUST be used by the
server. server.
error-path: Contains the absolute XPath [W3C.REC-xpath-19991116] error-path: Contains the absolute XPath [W3C.REC-xpath-19991116]
expression identifying the element path to the node that is expression identifying the element path to the node that is
associated with the error being reported in a particular associated with the error being reported in a particular
<rpc-error> element. This element will not be present if no <rpc-error> element. This element will not be present if no
appropriate payload element or datastore node can be associated appropriate payload element or datastore node can be associated
with a particular error condition. with a particular error condition.
The XPath expression is interpreted in the following context: The XPath expression is interpreted in the following context:
skipping to change at page 18, line 51 skipping to change at page 17, line 32
* The function library is the core function library. * The function library is the core function library.
The context node depends on the node associated with the error The context node depends on the node associated with the error
being reported: being reported:
* If a payload element can be associated with the error, the * If a payload element can be associated with the error, the
context node is the rpc request's document node (i.e., the context node is the rpc request's document node (i.e., the
<rpc> element). <rpc> element).
* Otherwise, the context node is the root of all data models, * Otherwise, the context node is the root of all data models,
i.e., the node which has the top-level nodes from all data i.e., the node that has the top-level nodes from all data
models as children. models as children.
error-message: Contains a string suitable for human display that error-message: Contains a string suitable for human display that
describes the error condition. This element will not be present describes the error condition. This element will not be present
if no appropriate message is provided for a particular error if no appropriate message is provided for a particular error
condition. This element SHOULD include an "xml:lang" attribute as condition. This element SHOULD include an "xml:lang" attribute as
defined in [W3C.REC-xml-20001006] and discussed in [RFC3470]. defined in [W3C.REC-xml-20001006] and discussed in [RFC3470].
error-info: Contains protocol- or data-model-specific error content. error-info: Contains protocol- or data-model-specific error content.
This element will not be present if no such error content is This element will not be present if no such error content is
provided for a particular error condition. The list in Appendix A provided for a particular error condition. The list in Appendix A
defines any mandatory error-info content for each error. After defines any mandatory error-info content for each error. After
any protocol-mandated content, a data model definition MAY mandate any protocol-mandated content, a data model definition MAY mandate
that certain application-layer error information be included in that certain application-layer error information be included in
the error-info container. An implementation MAY include the error-info container. An implementation MAY include
additional elements to provide extended and/or implementation- additional elements to provide extended and/or implementation-
specific debugging information. specific debugging information.
Appendix A enumerates the standard NETCONF errors. Appendix A enumerates the standard NETCONF errors.
Example: Example: An error is returned if an <rpc> element is received
without a "message-id" attribute. Note that only in this case is
An error is returned if an <rpc> element is received without a it acceptable for the NETCONF peer to omit the "message-id"
"message-id" attribute. Note that only in this case is it attribute in the <rpc-reply> element.
acceptable for the NETCONF peer to omit the "message-id" attribute
in the <rpc-reply> element.
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config> <get-config>
<source> <source>
<running/> <running/>
</source> </source>
</get-config> </get-config>
</rpc> </rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
skipping to change at page 22, line 45 skipping to change at page 20, line 29
5.2. Data Modeling 5.2. Data Modeling
Data modeling and content issues are outside the scope of the NETCONF Data modeling and content issues are outside the scope of the NETCONF
protocol. An assumption is made that the device's data model is protocol. An assumption is made that the device's data model is
well-known to the application and that both parties are aware of well-known to the application and that both parties are aware of
issues such as the layout, containment, keying, lookup, replacement, issues such as the layout, containment, keying, lookup, replacement,
and management of the data, as well as any other constraints imposed and management of the data, as well as any other constraints imposed
by the data model. by the data model.
NETCONF carries configuration data inside the <config> element that NETCONF carries configuration data inside the <config> element that
is specific to device's data model. The protocol treats the contents is specific to the device's data model. The protocol treats the
of that element as opaque data. The device uses capabilities to contents of that element as opaque data. The device uses
announce the set of data models that the device implements. The capabilities to announce the set of data models that the device
capability definition details the operation and constraints imposed implements. The capability definition details the operation and
by data model. constraints imposed by data model.
Devices and managers can support multiple data models, including both Devices and managers can support multiple data models, including both
standard and proprietary data models. standard and proprietary data models.
6. Subtree Filtering 6. Subtree Filtering
6.1. Overview 6.1. Overview
XML subtree filtering is a mechanism that allows an application to XML subtree filtering is a mechanism that allows an application to
select particular XML subtrees to include in the <rpc-reply> for a select particular XML subtrees to include in the <rpc-reply> for a
skipping to change at page 25, line 13 skipping to change at page 22, line 46
Example: Example:
<filter type="subtree"> <filter type="subtree">
<t:top xmlns:t="http://example.com/schema/1.2/config"> <t:top xmlns:t="http://example.com/schema/1.2/config">
<t:interfaces> <t:interfaces>
<t:interface t:ifName="eth0"/> <t:interface t:ifName="eth0"/>
</t:interfaces> </t:interfaces>
</t:top> </t:top>
</filter> </filter>
In this example, the <top>, and <interfaces> elements are containment In this example, the <top> and <interfaces> elements are containment
nodes, the <interface> element is a selection node, and "ifName" is nodes, the <interface> element is a selection node, and "ifName" is
an attribute match expression. Only "interface" nodes in the an attribute match expression. Only "interface" nodes in the
"http://example.com/schema/1.2/config" namespace that have an "http://example.com/schema/1.2/config" namespace that have an
"ifName" attribute with the value "eth0" and occur within "ifName" attribute with the value "eth0" and occur within
"interfaces" nodes within "top" nodes will be included in the filter "interfaces" nodes within "top" nodes will be included in the filter
output. output.
6.2.3. Containment Nodes 6.2.3. Containment Nodes
Nodes that contain child elements within a subtree filter are called Nodes that contain child elements within a subtree filter are called
skipping to change at page 29, line 23 skipping to change at page 27, line 14
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data> <data>
</data> </data>
</rpc-reply> </rpc-reply>
6.4.3. Select the Entire <users> Subtree 6.4.3. Select the Entire <users> Subtree
The filter in this example contains one selection node (<users>), so The filter in this example contains one selection node (<users>), so
just that subtree is selected by the filter. This example represents just that subtree is selected by the filter. This example represents
the fully-populated <users> data model in most of the filter examples the fully populated <users> data model in most of the filter examples
that follow. In a real data model, the <company-info> would not that follow. In a real data model, the <company-info> would not
likely be returned with the list of users for a particular host or likely be returned with the list of users for a particular host or
network. network.
NOTE: The filtering and configuration examples used in this document NOTE: The filtering and configuration examples used in this document
appear in the namespace "http://example.com/schema/1.2/config". The appear in the namespace "http://example.com/schema/1.2/config". The
root element of this namespace is <top>. The <top> element and its root element of this namespace is <top>. The <top> element and its
descendents represent an example configuration data model only. descendents represent an example configuration data model only.
<rpc message-id="101" <rpc message-id="101"
skipping to change at page 34, line 46 skipping to change at page 32, line 11
</top> </top>
</data> </data>
</rpc-reply> </rpc-reply>
6.4.7. Multiple Subtrees 6.4.7. Multiple Subtrees
This filter contains three subtrees (name=root, fred, barney). This filter contains three subtrees (name=root, fred, barney).
The "root" subtree filter contains two containment nodes (<users>, The "root" subtree filter contains two containment nodes (<users>,
<user>), one content match node (<name>), and one selection node <user>), one content match node (<name>), and one selection node
(<company-info>). The subtree selection criteria is met, and just (<company-info>). The subtree selection criteria are met, and just
the company-info subtree for "root" is selected in the filter output. the company-info subtree for "root" is selected in the filter output.
The "fred" subtree filter contains three containment nodes (<users>, The "fred" subtree filter contains three containment nodes (<users>,
<user>, <company-info>), one content match node (<name>), and one <user>, <company-info>), one content match node (<name>), and one
selection node (<id>). The subtree selection criteria is met, and selection node (<id>). The subtree selection criteria are met, and
just the <id> element within the company-info subtree for "fred" is just the <id> element within the company-info subtree for "fred" is
selected in the filter output. selected in the filter output.
The "barney" subtree filter contains three containment nodes The "barney" subtree filter contains three containment nodes
(<users>, <user>, <company-info>), two content match nodes (<name>, (<users>, <user>, <company-info>), two content match nodes (<name>,
<type>), and one selection node (<dept>). The subtree selection <type>), and one selection node (<dept>). The subtree selection
criteria is not met because user "barney" is not a "superuser", and criteria are not met because user "barney" is not a "superuser", and
the entire subtree for "barney" (including its parent <user> entry) the entire subtree for "barney" (including its parent <user> entry)
is excluded from the filter output. is excluded from the filter output.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config> <get-config>
<source> <source>
<running/> <running/>
</source> </source>
<filter type="subtree"> <filter type="subtree">
skipping to change at page 38, line 44 skipping to change at page 35, line 44
"operation not supported". An initiator SHOULD NOT assume that any "operation not supported". An initiator SHOULD NOT assume that any
operation will always succeed. The return values in any RPC reply operation will always succeed. The return values in any RPC reply
SHOULD be checked for error responses. SHOULD be checked for error responses.
The syntax and XML encoding of the protocol operations are formally The syntax and XML encoding of the protocol operations are formally
defined in the YANG module in Appendix C. The following sections defined in the YANG module in Appendix C. The following sections
describe the semantics of each protocol operation. describe the semantics of each protocol operation.
7.1. <get-config> 7.1. <get-config>
Description: Description: Retrieve all or part of a specified configuration
datastore.
Retrieve all or part of a specified configuration datastore.
Parameters: Parameters:
source: source: Name of the configuration datastore being queried, such
as <running/>.
Name of the configuration datastore being queried, such as
<running/>.
filter:
This parameter identifies the portions of the device filter: This parameter identifies the portions of the device
configuration datastore to retrieve. If this parameter is not configuration datastore to retrieve. If this parameter is not
present, the entire configuration is returned. present, the entire configuration is returned.
The <filter> element MAY optionally contain a "type" attribute. The <filter> element MAY optionally contain a "type" attribute.
This attribute indicates the type of filtering syntax used This attribute indicates the type of filtering syntax used
within the <filter> element. The default filtering mechanism within the <filter> element. The default filtering mechanism
in NETCONF is referred to as subtree filtering and is described in NETCONF is referred to as subtree filtering and is described
in Section 6. The value "subtree" explicitly identifies this in Section 6. The value "subtree" explicitly identifies this
type of filtering. type of filtering.
If the NETCONF peer supports the :xpath capability If the NETCONF peer supports the :xpath capability
(Section 8.9), the value "xpath" MAY be used to indicate that (Section 8.9), the value "xpath" MAY be used to indicate that
the "select" attribute on the <filter> element contains an the "select" attribute on the <filter> element contains an
XPath expression. XPath expression.
Positive Response: Positive Response: If the device can satisfy the request, the server
sends an <rpc-reply> element containing a <data> element with the
If the device can satisfy the request, the server sends an results of the query.
<rpc-reply> element containing a <data> element with the results
of the query.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the Negative Response: An <rpc-error> element is included in the
request cannot be completed for any reason. <rpc-reply> if the request cannot be completed for any reason.
Example: To retrieve the entire <users> subtree: Example: To retrieve the entire <users> subtree:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config> <get-config>
<source> <source>
<running/> <running/>
</source> </source>
<filter type="subtree"> <filter type="subtree">
skipping to change at page 41, line 13 skipping to change at page 37, line 38
If a NETCONF peer supports the :url capability (Section 8.8), the If a NETCONF peer supports the :url capability (Section 8.8), the
<url> element can appear instead of the <config> parameter. <url> element can appear instead of the <config> parameter.
The device analyzes the source and target configurations and The device analyzes the source and target configurations and
performs the requested changes. The target configuration is not performs the requested changes. The target configuration is not
necessarily replaced, as with the <copy-config> message. Instead, necessarily replaced, as with the <copy-config> message. Instead,
the target configuration is changed in accordance with the the target configuration is changed in accordance with the
source's data and requested operations. source's data and requested operations.
If the <edit-config> operation contains multiple sub-operations If the <edit-config> operation contains multiple sub-operations
which apply to the same conceptual node in the underlying data that apply to the same conceptual node in the underlying data
model, then the result of the operation is undefined (i.e., model, then the result of the operation is undefined (i.e.,
outside the scope of the NETCONF protocol). outside the scope of the NETCONF protocol).
Attributes: Attributes:
operation: operation: Elements in the <config> subtree MAY contain an
"operation" attribute, which belongs to the NETCONF namespace
Elements in the <config> subtree MAY contain an "operation" defined in Section 3.1. The attribute identifies the point in
attribute. The attribute identifies the point in the the configuration to perform the operation and MAY appear on
configuration to perform the operation and MAY appear on
multiple elements throughout the <config> subtree. multiple elements throughout the <config> subtree.
If the "operation" attribute is not specified, the If the "operation" attribute is not specified, the
configuration is merged into the configuration datastore. configuration is merged into the configuration datastore.
The "operation" attribute has one of the following values: The "operation" attribute has one of the following values:
merge: The configuration data identified by the element merge: The configuration data identified by the element
containing this attribute is merged with the configuration containing this attribute is merged with the configuration
at the corresponding level in the configuration datastore at the corresponding level in the configuration datastore
skipping to change at page 42, line 21 skipping to change at page 38, line 45
remove: The configuration data identified by the element remove: The configuration data identified by the element
containing this attribute is deleted from the configuration containing this attribute is deleted from the configuration
if the configuration data currently exists in the if the configuration data currently exists in the
configuration datastore. If the configuration data does not configuration datastore. If the configuration data does not
exist, the "remove" operation is silently ignored by the exist, the "remove" operation is silently ignored by the
server. server.
Parameters: Parameters:
target: target: Name of the configuration datastore being edited, such as
Name of the configuration datastore being edited, such as
<running/> or <candidate/>. <running/> or <candidate/>.
default-operation: default-operation: Selects the default operation (as described in
the "operation" attribute) for this <edit-config> request. The
Selects the default operation (as described in the "operation" default value for the <default-operation> parameter is "merge".
attribute) for this <edit-config> request. The default value
for the <default-operation> parameter is "merge".
The <default-operation> parameter is optional, but if provided, The <default-operation> parameter is optional, but if provided,
it has one of the following values: it has one of the following values:
merge: The configuration data in the <config> parameter is merge: The configuration data in the <config> parameter is
merged with the configuration at the corresponding level in merged with the configuration at the corresponding level in
the target datastore. This is the default behavior. the target datastore. This is the default behavior.
replace: The configuration data in the <config> parameter replace: The configuration data in the <config> parameter
completely replaces the configuration in the target completely replaces the configuration in the target
skipping to change at page 43, line 6 skipping to change at page 39, line 28
in the <config> parameter, unless and until the incoming in the <config> parameter, unless and until the incoming
configuration data uses the "operation" attribute to request configuration data uses the "operation" attribute to request
a different operation. If the configuration in the <config> a different operation. If the configuration in the <config>
parameter contains data for which there is not a parameter contains data for which there is not a
corresponding level in the target datastore, an <rpc-error> corresponding level in the target datastore, an <rpc-error>
is returned with an <error-tag> value of data-missing. is returned with an <error-tag> value of data-missing.
Using "none" allows operations like "delete" to avoid Using "none" allows operations like "delete" to avoid
unintentionally creating the parent hierarchy of the element unintentionally creating the parent hierarchy of the element
to be deleted. to be deleted.
test-option: test-option: The <test-option> element MAY be specified only if
the device advertises the :validate:1.1 capability
The <test-option> element MAY be specified only if the device (Section 8.6).
advertises the :validate:1.1 capability (Section 8.6).
The <test-option> element has one of the following values: The <test-option> element has one of the following values:
test-then-set: Perform a validation test before attempting to test-then-set: Perform a validation test before attempting to
set. If validation errors occur, do not perform the set. If validation errors occur, do not perform the
<edit-config> operation. This is the default test-option. <edit-config> operation. This is the default test-option.
set: Perform a set without a validation test first. set: Perform a set without a validation test first.
test-only: Perform only the validation test, without test-only: Perform only the validation test, without
attempting to set. attempting to set.
error-option: error-option: The <error-option> element has one of the following
values:
The <error-option> element has one of the following values:
stop-on-error: Abort the edit-config operation on first error. stop-on-error: Abort the <edit-config> operation on first
This is the default error-option. error. This is the default error-option.
continue-on-error: Continue to process configuration data on continue-on-error: Continue to process configuration data on
error; error is recorded, and negative response is generated error; error is recorded, and negative response is generated
if any errors occur. if any errors occur.
rollback-on-error: If an error condition occurs such that an rollback-on-error: If an error condition occurs such that an
error severity <rpc-error> element is generated, the server error severity <rpc-error> element is generated, the server
will stop processing the edit-config operation and restore will stop processing the <edit-config> operation and restore
the specified configuration to its complete state at the the specified configuration to its complete state at the
start of this edit-config operation. This option requires start of this <edit-config> operation. This option requires
the server to support the :rollback-on-error capability the server to support the :rollback-on-error capability
described in Section 8.5. described in Section 8.5.
config: config: A hierarchy of configuration data as defined by one of
the device's data models. The contents MUST be placed in an
A hierarchy of configuration data as defined by one of the
device's data models. The contents MUST be placed in an
appropriate namespace, to allow the device to detect the appropriate namespace, to allow the device to detect the
appropriate data model, and the contents MUST follow the appropriate data model, and the contents MUST follow the
constraints of that data model, as defined by its capability constraints of that data model, as defined by its capability
definition. Capabilities are discussed in Section 8. definition. Capabilities are discussed in Section 8.
Positive Response: Positive Response: If the device was able to satisfy the request, an
<rpc-reply> is sent containing an <ok> element.
If the device was able to satisfy the request, an <rpc-reply> is
sent containing an <ok> element.
Negative Response:
An <rpc-error> response is sent if the request cannot be completed
for any reason.
Example: Negative Response: An <rpc-error> response is sent if the request
cannot be completed for any reason.
The <edit-config> examples in this section utilize a simple data Example: The <edit-config> examples in this section utilize a simple
model, in which multiple instances of the <interface> element can data model, in which multiple instances of the <interface> element
be present, and an instance is distinguished by the <name> element can be present, and an instance is distinguished by the <name>
within each <interface> element. element within each <interface> element.
Set the MTU to 1500 on an interface named "Ethernet0/0" in the Set the MTU to 1500 on an interface named "Ethernet0/0" in the
running configuration: running configuration:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
</target> </target>
skipping to change at page 47, line 38 skipping to change at page 43, line 7
</edit-config> </edit-config>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
7.3. <copy-config> 7.3. <copy-config>
Description: Description: Create or replace an entire configuration datastore
with the contents of another complete configuration datastore. If
Create or replace an entire configuration datastore with the the target datastore exists, it is overwritten. Otherwise, a new
contents of another complete configuration datastore. If the one is created, if allowed.
target datastore exists, it is overwritten. Otherwise, a new one
is created, if allowed.
If a NETCONF peer supports the :url capability (Section 8.8), the If a NETCONF peer supports the :url capability (Section 8.8), the
<url> element can appear as the <source> or <target> parameter. <url> element can appear as the <source> or <target> parameter.
Even if it advertises the :writable-running capability, a device Even if it advertises the :writable-running capability, a device
MAY choose not to support the <running/> configuration datastore MAY choose not to support the <running/> configuration datastore
as the <target> parameter of a <copy-config> operation. A device as the <target> parameter of a <copy-config> operation. A device
MAY choose not to support remote-to-remote copy operations, where MAY choose not to support remote-to-remote copy operations, where
both the <source> and <target> parameters use the <url> element. both the <source> and <target> parameters use the <url> element.
If the <source> and <target> parameters identify the same URL or If the <source> and <target> parameters identify the same URL or
configuration datastore, an error MUST be returned with an error- configuration datastore, an error MUST be returned with an error-
tag containing "invalid-value". tag containing "invalid-value".
Parameters: Parameters:
target: target: Name of the configuration datastore to use as the
destination of the <copy-config> operation.
Name of the configuration datastore to use as the destination
of the <copy-config> operation.
source:
Name of the configuration datastore to use as the source of the
<copy-config> operation, or the <config> element containing the
complete configuration to copy.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply> is source: Name of the configuration datastore to use as the source
sent that includes an <ok> element. of the <copy-config> operation, or the <config> element
containing the complete configuration to copy.
Negative Response: Positive Response: If the device was able to satisfy the request, an
<rpc-reply> is sent that includes an <ok> element.
An <rpc-error> element is included within the <rpc-reply> if the Negative Response: An <rpc-error> element is included within the
request cannot be completed for any reason. <rpc-reply> if the request cannot be completed for any reason.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config> <copy-config>
<target> <target>
<running/> <running/>
</target> </target>
<source> <source>
skipping to change at page 48, line 45 skipping to change at page 44, line 4
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config> <copy-config>
<target> <target>
<running/> <running/>
</target> </target>
<source> <source>
<url>https://user:password@example.com/cfg/new.txt</url> <url>https://user:password@example.com/cfg/new.txt</url>
</source> </source>
</copy-config> </copy-config>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
7.4. <delete-config> 7.4. <delete-config>
Description: Description: Delete a configuration datastore. The <running>
configuration datastore cannot be deleted.
Delete a configuration datastore. The <running> configuration
datastore cannot be deleted.
If a NETCONF peer supports the :url capability (Section 8.8), the If a NETCONF peer supports the :url capability (Section 8.8), the
<url> element can appear as the <target> parameter. <url> element can appear as the <target> parameter.
Parameters: Parameters:
target: target: Name of the configuration datastore to delete.
Name of the configuration datastore to delete.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply> is
sent that includes an <ok> element.
Negative Response: Positive Response: If the device was able to satisfy the request, an
<rpc-reply> is sent that includes an <ok> element.
An <rpc-error> element is included within the <rpc-reply> if the Negative Response: An <rpc-error> element is included within the
request cannot be completed for any reason. <rpc-reply> if the request cannot be completed for any reason.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<delete-config> <delete-config>
<target> <target>
<startup/> <startup/>
</target> </target>
</delete-config> </delete-config>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
7.5. <lock> 7.5. <lock>
Description:
The <lock> operation allows the client to lock the entire Description: The <lock> operation allows the client to lock the
configuration datastore system of a device. Such locks are entire configuration datastore system of a device. Such locks are
intended to be short-lived and allow a client to make a change intended to be short-lived and allow a client to make a change
without fear of interaction with other NETCONF clients, non- without fear of interaction with other NETCONF clients, non-
NETCONF clients (e.g., SNMP and command line interface (CLI) NETCONF clients (e.g., SNMP and command line interface (CLI)
scripts), and human users. scripts), and human users.
An attempt to lock the configuration datastore MUST fail if an An attempt to lock the configuration datastore MUST fail if an
existing session or other entity holds a lock on any portion of existing session or other entity holds a lock on any portion of
the lock target. the lock target.
When the lock is acquired, the server MUST prevent any changes to When the lock is acquired, the server MUST prevent any changes to
the locked resource other than those requested by this session. the locked resource other than those requested by this session.
SNMP and CLI requests to modify the resource MUST fail with an SNMP and CLI requests to modify the resource MUST fail with an
appropriate error. appropriate error.
The duration of the lock is defined as beginning when the lock is The duration of the lock is defined as beginning when the lock is
acquired and lasting until either the lock is released or the acquired and lasting until either the lock is released or the
NETCONF session closes. The session closure can be explicitly NETCONF session closes. The session closure can be explicitly
performed by the client, or implicitly performed by the server performed by the client, or implicitly performed by the server
based on criteria such as failure of the underlying transport, based on criteria such as failure of the underlying transport,
simple inactivity timeout, or detection of abusive behavior on the simple inactivity timeout, or detection of abusive behavior on the
part of the client . This criteria is dependent on the part of the client. These criteria are dependent on the
implementation and the underlying transport. implementation and the underlying transport.
The <lock> operation takes a mandatory parameter, <target>. The The <lock> operation takes a mandatory parameter, <target>. The
<target> parameter names the configuration datastore that will be <target> parameter names the configuration datastore that will be
locked. When a lock is active, using the <edit-config> operation locked. When a lock is active, using the <edit-config> operation
on the locked configuration datastore and using the locked on the locked configuration datastore and using the locked
configuration as a target of the <copy-config> operation will be configuration as a target of the <copy-config> operation will be
disallowed by any other NETCONF session. Additionally, the system disallowed by any other NETCONF session. Additionally, the system
will ensure that these locked configuration resources will not be will ensure that these locked configuration resources will not be
modified by other non-NETCONF management operations such as SNMP modified by other non-NETCONF management operations such as SNMP
and CLI. The <kill-session> operation can be used to force the and CLI. The <kill-session> operation can be used to force the
release of a lock owned by another NETCONF session. It is beyond release of a lock owned by another NETCONF session. It is beyond
the scope of this document to define how to break locks held by the scope of this document to define how to break locks held by
other entities. other entities.
A lock MUST NOT be granted if either of the following conditions A lock MUST NOT be granted if any of the following conditions is
is true: true:
* A lock is already held by any NETCONF session or another * A lock is already held by any NETCONF session or another
entity. entity.
* The target configuration is <candidate>, it has already been * The target configuration is <candidate>, it has already been
modified, and these changes have not been committed or rolled modified, and these changes have not been committed or rolled
back. back.
* The target configuration is <running>, and another NETCONF
session has an ongoing confirmed commit (Section 8.4).
The server MUST respond with either an <ok> element or an The server MUST respond with either an <ok> element or an
<rpc-error>. <rpc-error>.
A lock will be released by the system if the session holding the A lock will be released by the system if the session holding the
lock is terminated for any reason. lock is terminated for any reason.
Parameters: Parameters:
target: target: Name of the configuration datastore to lock.
Name of the configuration datastore to lock.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply> is
sent that contains an <ok> element.
Negative Response: Positive Response: If the device was able to satisfy the request, an
<rpc-reply> is sent that contains an <ok> element.
An <rpc-error> element is included in the <rpc-reply> if the Negative Response: An <rpc-error> element is included in the
request cannot be completed for any reason. <rpc-reply> if the request cannot be completed for any reason.
If the lock is already held, the <error-tag> element will be If the lock is already held, the <error-tag> element will be
"lock-denied" and the <error-info> element will include the "lock-denied" and the <error-info> element will include the
<session-id> of the lock owner. If the lock is held by a non- <session-id> of the lock owner. If the lock is held by a non-
NETCONF entity, a <session-id> of 0 (zero) is included. Note that NETCONF entity, a <session-id> of 0 (zero) is included. Note that
any other entity performing a lock on even a partial piece of a any other entity performing a lock on even a partial piece of a
target will prevent a NETCONF lock (which is global) from being target will prevent a NETCONF lock (which is global) from being
obtained on that target. obtained on that target.
Example: Example: The following example shows a successful acquisition of a
lock.
The following example shows a successful acquisition of a lock.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock> <lock>
<target> <target>
<running/> <running/>
</target> </target>
</lock> </lock>
</rpc> </rpc>
skipping to change at page 52, line 4 skipping to change at page 46, line 41
<lock> <lock>
<target> <target>
<running/> <running/>
</target> </target>
</lock> </lock>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <!-- lock succeeded --> <ok/> <!-- lock succeeded -->
</rpc-reply> </rpc-reply>
Example: Example: The following example shows a failed attempt to acquire a
lock when the lock is already in use.
The following example shows a failed attempt to acquire a lock
when the lock is already in use.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock> <lock>
<target> <target>
<running/> <running/>
</target> </target>
</lock> </lock>
</rpc> </rpc>
skipping to change at page 52, line 39 skipping to change at page 47, line 32
</error-message> </error-message>
<error-info> <error-info>
<session-id>454</session-id> <session-id>454</session-id>
<!-- lock is held by NETCONF session 454 --> <!-- lock is held by NETCONF session 454 -->
</error-info> </error-info>
</rpc-error> </rpc-error>
</rpc-reply> </rpc-reply>
7.6. <unlock> 7.6. <unlock>
Description: Description: The <unlock> operation is used to release a
configuration lock, previously obtained with the <lock> operation.
The <unlock> operation is used to release a configuration lock,
previously obtained with the <lock> operation.
An <unlock> operation will not succeed if any of the following An <unlock> operation will not succeed if either of the following
conditions are true: conditions is true:
* the specified lock is not currently active * The specified lock is not currently active.
* the session issuing the <unlock> operation is not the same * The session issuing the <unlock> operation is not the same
session that obtained the lock session that obtained the lock.
The server MUST respond with either an <ok> element or an The server MUST respond with either an <ok> element or an
<rpc-error>. <rpc-error>.
Parameters: Parameters:
target: target: Name of the configuration datastore to unlock.
Name of the configuration datastore to unlock.
A NETCONF client is not permitted to unlock a configuration A NETCONF client is not permitted to unlock a configuration
datastore that it did not lock. datastore that it did not lock.
Positive Response: Positive Response: If the device was able to satisfy the request, an
<rpc-reply> is sent that contains an <ok> element.
If the device was able to satisfy the request, an <rpc-reply> is
sent that contains an <ok> element.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the Negative Response: An <rpc-error> element is included in the
request cannot be completed for any reason. <rpc-reply> if the request cannot be completed for any reason.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock> <unlock>
<target> <target>
<running/> <running/>
</target> </target>
</unlock> </unlock>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
7.7. <get> 7.7. <get>
Description: Description: Retrieve running configuration and device state
information.
Retrieve running configuration and device state information.
Parameters: Parameters:
filter: filter: This parameter specifies the portion of the system
This parameter specifies the portion of the system
configuration and state data to retrieve. If this parameter is configuration and state data to retrieve. If this parameter is
not present, all the device configuration and state information not present, all the device configuration and state information
is returned. is returned.
The <filter> element MAY optionally contain a "type" attribute. The <filter> element MAY optionally contain a "type" attribute.
This attribute indicates the type of filtering syntax used This attribute indicates the type of filtering syntax used
within the <filter> element. The default filtering mechanism within the <filter> element. The default filtering mechanism
in NETCONF is referred to as subtree filtering and is described in NETCONF is referred to as subtree filtering and is described
in Section 6. The value "subtree" explicitly identifies this in Section 6. The value "subtree" explicitly identifies this
type of filtering. type of filtering.
If the NETCONF peer supports the :xpath capability If the NETCONF peer supports the :xpath capability
(Section 8.9), the value "xpath" MAY be used to indicate that (Section 8.9), the value "xpath" MAY be used to indicate that
the "select" attribute of the <filter> element contains an the "select" attribute of the <filter> element contains an
XPath expression. XPath expression.
Positive Response: Positive Response: If the device was able to satisfy the request, an
<rpc-reply> is sent. The <data> section contains the appropriate
If the device was able to satisfy the request, an <rpc-reply> is subset.
sent. The <data> section contains the appropriate subset.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the Negative Response: An <rpc-error> element is included in the
request cannot be completed for any reason. <rpc-reply> if the request cannot be completed for any reason.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get> <get>
<filter type="subtree"> <filter type="subtree">
<top xmlns="http://example.com/schema/1.2/stats"> <top xmlns="http://example.com/schema/1.2/stats">
<interfaces> <interfaces>
<interface> <interface>
skipping to change at page 55, line 37 skipping to change at page 49, line 46
<ifInOctets>45621</ifInOctets> <ifInOctets>45621</ifInOctets>
<ifOutOctets>774344</ifOutOctets> <ifOutOctets>774344</ifOutOctets>
</interface> </interface>
</interfaces> </interfaces>
</top> </top>
</data> </data>
</rpc-reply> </rpc-reply>
7.8. <close-session> 7.8. <close-session>
Description: Description: Request graceful termination of a NETCONF session.
Request graceful termination of a NETCONF session.
When a NETCONF server receives a <close-session> request, it will When a NETCONF server receives a <close-session> request, it will
gracefully close the session. The server will release any locks gracefully close the session. The server will release any locks
and resources associated with the session and gracefully close any and resources associated with the session and gracefully close any
associated connections. Any NETCONF requests received after a associated connections. Any NETCONF requests received after a
<close-session> request will be ignored. <close-session> request will be ignored.
Positive Response: Positive Response: If the device was able to satisfy the request, an
<rpc-reply> is sent that includes an <ok> element.
If the device was able to satisfy the request, an <rpc-reply> is
sent that includes an <ok> element.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the Negative Response: An <rpc-error> element is included in the
request cannot be completed for any reason. <rpc-reply> if the request cannot be completed for any reason.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<close-session/> <close-session/>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
7.9. <kill-session> 7.9. <kill-session>
Description: Description: Force the termination of a NETCONF session.
Force the termination of a NETCONF session.
When a NETCONF entity receives a <kill-session> request for an When a NETCONF entity receives a <kill-session> request for an
open session, it will abort any operations currently in process, open session, it will abort any operations currently in process,
release any locks and resources associated with the session, and release any locks and resources associated with the session, and
close any associated connections. close any associated connections.
If a NETCONF server receives a <kill-session> request while If a NETCONF server receives a <kill-session> request while
processing a confirmed commit (Section 8.4), it MUST restore the processing a confirmed commit (Section 8.4), it MUST restore the
configuration to its state before the confirmed commit was issued. configuration to its state before the confirmed commit was issued.
Otherwise, the <kill-session> operation does not roll back Otherwise, the <kill-session> operation does not roll back
configuration or other device state modifications made by the configuration or other device state modifications made by the
entity holding the lock. entity holding the lock.
Parameters: Parameters:
session-id: session-id: Session identifier of the NETCONF session to be
terminated. If this value is equal to the current session ID,
Session identifier of the NETCONF session to be terminated. If an "invalid-value" error is returned.
this value is equal to the current session ID, an
"invalid-value" error is returned.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply> is
sent that includes an <ok> element.
Negative Response: Positive Response: If the device was able to satisfy the request, an
<rpc-reply> is sent that includes an <ok> element.
An <rpc-error> element is included in the <rpc-reply> if the Negative Response: An <rpc-error> element is included in the
request cannot be completed for any reason. <rpc-reply> if the request cannot be completed for any reason.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<kill-session> <kill-session>
<session-id>4</session-id> <session-id>4</session-id>
</kill-session> </kill-session>
</rpc> </rpc>
skipping to change at page 60, line 41 skipping to change at page 54, line 11
configuration is a full configuration data set that serves as a work configuration is a full configuration data set that serves as a work
place for creating and manipulating configuration data. Additions, place for creating and manipulating configuration data. Additions,
deletions, and changes can be made to this data to construct the deletions, and changes can be made to this data to construct the
desired configuration data. A <commit> operation MAY be performed at desired configuration data. A <commit> operation MAY be performed at
any time that causes the device's running configuration to be set to any time that causes the device's running configuration to be set to
the value of the candidate configuration. the value of the candidate configuration.
The <commit> operation effectively sets the running configuration to The <commit> operation effectively sets the running configuration to
the current contents of the candidate configuration. While it could the current contents of the candidate configuration. While it could
be modeled as a simple copy, it is done as a distinct operation for a be modeled as a simple copy, it is done as a distinct operation for a
number of reasons. In keeping high-level concepts as first class number of reasons. In keeping high-level concepts as first-class
operations, we allow developers to see more clearly both what the operations, we allow developers to see more clearly both what the
client is requesting and what the server must perform. This keeps client is requesting and what the server must perform. This keeps
the intentions more obvious, the special cases less complex, and the the intentions more obvious, the special cases less complex, and the
interactions between operations more straightforward. For example, interactions between operations more straightforward. For example,
the :confirmed-commit:1.1 capability (Section 8.4) would make no the :confirmed-commit:1.1 capability (Section 8.4) would make no
sense as a "copy confirmed" operation. sense as a "copy confirmed" operation.
The candidate configuration can be shared among multiple sessions. The candidate configuration can be shared among multiple sessions.
Unless a client has specific information that the candidate Unless a client has specific information that the candidate
configuration is not shared, it MUST assume that other sessions are configuration is not shared, it MUST assume that other sessions are
skipping to change at page 61, line 29 skipping to change at page 54, line 48
string: string:
urn:ietf:params:netconf:capability:candidate:1.0 urn:ietf:params:netconf:capability:candidate:1.0
8.3.4. New Operations 8.3.4. New Operations
8.3.4.1. <commit> 8.3.4.1. <commit>
Description: Description:
When a candidate configuration's content is complete, the When the candidate configuration's content is complete, the
configuration data can be committed, publishing the data set to configuration data can be committed, publishing the data set to
the rest of the device and requesting the device to conform to the rest of the device and requesting the device to conform to
the behavior described in the new configuration. the behavior described in the new configuration.
To commit the candidate configuration as the device's new To commit the candidate configuration as the device's new
current configuration, use the <commit> operation. current configuration, use the <commit> operation.
The <commit> operation instructs the device to implement the The <commit> operation instructs the device to implement the
configuration data contained in the candidate configuration. configuration data contained in the candidate configuration.
If the device is unable to commit all of the changes in the If the device is unable to commit all of the changes in the
skipping to change at page 64, line 7 skipping to change at page 57, line 30
8.4. Confirmed Commit Capability 8.4. Confirmed Commit Capability
8.4.1. Description 8.4.1. Description
The :confirmed-commit:1.1 capability indicates that the server will The :confirmed-commit:1.1 capability indicates that the server will
support the <cancel-commit> operation and the <confirmed>, support the <cancel-commit> operation and the <confirmed>,
<confirm-timeout>, <persist>, and <persist-id> parameters for the <confirm-timeout>, <persist>, and <persist-id> parameters for the
<commit> operation. See Section 8.3 for further details on the <commit> operation. See Section 8.3 for further details on the
<commit> operation. <commit> operation.
A confirmed commit operation MUST be reverted if a confirming commit A confirmed <commit> operation MUST be reverted if a confirming
is not issued within the timeout period (by default 600 seconds = 10 commit is not issued within the timeout period (by default 600
minutes). The confirming commit is a <commit> operation without the seconds = 10 minutes). The confirming commit is a <commit> operation
<confirmed> parameter. The timeout period can be adjusted with the without the <confirmed> parameter. The timeout period can be
<confirm-timeout> parameter. If a follow-up confirmed commit adjusted with the <confirm-timeout> parameter. If a follow-up
operation is issued before the timer expires, the timer is reset to confirmed <commit> operation is issued before the timer expires, the
the new value (600 seconds by default). Both the confirming commit timer is reset to the new value (600 seconds by default). Both the
and a follow-up confirmed commit operation MAY introduce additional confirming commit and a follow-up confirmed <commit> operation MAY
changes to the configuration. introduce additional changes to the configuration.
If the <persist> element is not given in the confirmed commit If the <persist> element is not given in the confirmed commit
operation, any follow-up commit and the confirming commit MUST be operation, any follow-up commit and the confirming commit MUST be
issued on the same session that issued the confirmed commit. If the issued on the same session that issued the confirmed commit. If the
<persist> element is given in the confirmed commit operation, a <persist> element is given in the confirmed <commit> operation, a
follow-up commit and the confirming commit can be given on any follow-up commit and the confirming commit can be given on any
session, and they MUST include a <persist-id> element with a value session, and they MUST include a <persist-id> element with a value
equal to the given value of the <persist> element. equal to the given value of the <persist> element.
If the server also advertises the :startup capability, a If the server also advertises the :startup capability, a
<copy-config> from running to startup is also necessary to save the <copy-config> from running to startup is also necessary to save the
changes to startup. changes to startup.
If the session issuing the confirmed commit is terminated for any If the session issuing the confirmed commit is terminated for any
reason before the confirm timeout expires, the server MUST restore reason before the confirm timeout expires, the server MUST restore
skipping to change at page 65, line 10 skipping to change at page 58, line 34
altered or removed, unless the configuration locking feature is used altered or removed, unless the configuration locking feature is used
(in other words, the lock is obtained before the <edit-config> (in other words, the lock is obtained before the <edit-config>
operation is started). Therefore, it is strongly suggested that in operation is started). Therefore, it is strongly suggested that in
order to use this feature with shared configuration datastores, order to use this feature with shared configuration datastores,
configuration locking SHOULD also be used. configuration locking SHOULD also be used.
Version 1.0 of this capability was defined in [RFC4741]. Version 1.1 Version 1.0 of this capability was defined in [RFC4741]. Version 1.1
is defined in this document, and extends version 1.0 by adding a new is defined in this document, and extends version 1.0 by adding a new
operation, <cancel-commit>, and two new optional parameters, operation, <cancel-commit>, and two new optional parameters,
<persist> and <persist-id>. For backwards compatibility with old <persist> and <persist-id>. For backwards compatibility with old
clients, servers confirming to this specification MAY advertise clients, servers conforming to this specification MAY advertise
version 1.0 in addition to version 1.1. version 1.0 in addition to version 1.1.
8.4.2. Dependencies 8.4.2. Dependencies
The :confirmed-commit:1.1 capability is only relevant if the The :confirmed-commit:1.1 capability is only relevant if the
:candidate capability is also supported. :candidate capability is also supported.
8.4.3. Capability Identifier 8.4.3. Capability Identifier
The :confirmed-commit:1.1 capability is identified by the following The :confirmed-commit:1.1 capability is identified by the following
skipping to change at page 66, line 45 skipping to change at page 60, line 20
8.4.5.1. <commit> 8.4.5.1. <commit>
The :confirmed-commit:1.1 capability allows 4 additional parameters The :confirmed-commit:1.1 capability allows 4 additional parameters
to the <commit> operation. to the <commit> operation.
Parameters: Parameters:
confirmed: confirmed:
Perform a confirmed commit operation. Perform a confirmed <commit> operation.
confirm-timeout: confirm-timeout:
Timeout period for confirmed commit, in seconds. If Timeout period for confirmed commit, in seconds. If
unspecified, the confirm timeout defaults to 600 seconds. unspecified, the confirm timeout defaults to 600 seconds.
persist: persist:
Make the confirmed commit survive a session termination, and Make the confirmed commit survive a session termination, and
set a token on the ongoing confirmed commit. set a token on the ongoing confirmed commit.
persist-id: persist-id:
Used to issue a follow-up confirmed commit or a confirming Used to issue a follow-up confirmed commit or a confirming
commit from any session, with the token from the previous commit from any session, with the token from the previous
commit operation. <commit> operation.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit> <commit>
<confirmed/> <confirmed/>
<confirm-timeout>120</confirm-timeout> <confirm-timeout>120</confirm-timeout>
</commit> </commit>
</rpc> </rpc>
skipping to change at page 68, line 33 skipping to change at page 61, line 35
<commit> <commit>
<persist-id>IQ,d4668</persist-id> <persist-id>IQ,d4668</persist-id>
</commit> </commit>
</rpc> </rpc>
<rpc-reply message-id="102" <rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
8.5. Rollback on Error Capability 8.5. Rollback-on-Error Capability
8.5.1. Description 8.5.1. Description
This capability indicates that the server will support the This capability indicates that the server will support the
"rollback-on-error" value in the <error-option> parameter to the "rollback-on-error" value in the <error-option> parameter to the
<edit-config> operation. <edit-config> operation.
For shared configurations, this feature can cause other configuration For shared configurations, this feature can cause other configuration
changes (for example, via other NETCONF sessions) to be inadvertently changes (for example, via other NETCONF sessions) to be inadvertently
altered or removed, unless the configuration locking feature is used altered or removed, unless the configuration locking feature is used
(in other words, the lock is obtained before the <edit-config> (in other words, the lock is obtained before the <edit-config>
operation is started). Therefore, it is strongly suggested that in operation is started). Therefore, it is strongly suggested that in
order to use this feature with shared configuration datastores, order to use this feature with shared configuration datastores,
configuration locking also be used. configuration locking also be used.
8.5.2. Dependencies 8.5.2. Dependencies
None None.
8.5.3. Capability Identifier 8.5.3. Capability Identifier
The :rollback-on-error capability is identified by the following The :rollback-on-error capability is identified by the following
capability string: capability string:
urn:ietf:params:netconf:capability:rollback-on-error:1.0 urn:ietf:params:netconf:capability:rollback-on-error:1.0
8.5.4. New Operations 8.5.4. New Operations
skipping to change at page 70, line 23 skipping to change at page 63, line 23
If this capability is advertised, the device supports the <validate> If this capability is advertised, the device supports the <validate>
protocol operation and checks at least for syntax errors. In protocol operation and checks at least for syntax errors. In
addition, this capability supports the <test-option> parameter to the addition, this capability supports the <test-option> parameter to the
<edit-config> operation and, when it is provided, checks at least for <edit-config> operation and, when it is provided, checks at least for
syntax errors. syntax errors.
Version 1.0 of this capability was defined in [RFC4741]. Version 1.1 Version 1.0 of this capability was defined in [RFC4741]. Version 1.1
is defined in this document, and extends version 1.0 by adding a new is defined in this document, and extends version 1.0 by adding a new
value, "test-only", to the <test-option> parameter of the value, "test-only", to the <test-option> parameter of the
<edit-config> operation. For backwards compatibility with old <edit-config> operation. For backwards compatibility with old
clients, servers confirming to this specification MAY advertise clients, servers conforming to this specification MAY advertise
version 1.0 in addition to version 1.1. version 1.0 in addition to version 1.1.
8.6.2. Dependencies 8.6.2. Dependencies
None. None.
8.6.3. Capability Identifier 8.6.3. Capability Identifier
The :validate:1.1 capability is identified by the following The :validate:1.1 capability is identified by the following
capability string: capability string:
skipping to change at page 71, line 17 skipping to change at page 64, line 17
If the device was able to satisfy the request, an <rpc-reply> If the device was able to satisfy the request, an <rpc-reply>
is sent that contains an <ok> element. is sent that contains an <ok> element.
Negative Response: Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason. request cannot be completed for any reason.
A <validate> operation can fail for a number of reasons, such A <validate> operation can fail for a number of reasons, such
as syntax errors, missing parameters, references to undefined as syntax errors, missing parameters, references to undefined
configuration data or any other violations of rules established configuration data, or any other violations of rules
by the underlying data model. established by the underlying data model.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate> <validate>
<source> <source>
<candidate/> <candidate/>
</source> </source>
</validate> </validate>
skipping to change at page 73, line 33 skipping to change at page 66, line 33
identified by URL arguments indicating the URL schemes supported. identified by URL arguments indicating the URL schemes supported.
8.8.2. Dependencies 8.8.2. Dependencies
None. None.
8.8.3. Capability Identifier 8.8.3. Capability Identifier
The :url capability is identified by the following capability string: The :url capability is identified by the following capability string:
urn:ietf:params:netconf:capability:url:1.0?scheme={name,...} urn:ietf:params:netconf:capability:url:1.0?scheme={name,...}
The :url capability URI MUST contain a "scheme" argument assigned a The :url capability URI MUST contain a "scheme" argument assigned a
comma-separated list of scheme names indicating which schemes the comma-separated list of scheme names indicating which schemes the
NETCONF peer supports. For example: NETCONF peer supports. For example:
urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file
8.8.4. New Operations 8.8.4. New Operations
None. None.
skipping to change at page 74, line 37 skipping to change at page 67, line 39
8.9. XPath Capability 8.9. XPath Capability
8.9.1. Description 8.9.1. Description
The XPath capability indicates that the NETCONF peer supports the use The XPath capability indicates that the NETCONF peer supports the use
of XPath expressions in the <filter> element. XPath is described in of XPath expressions in the <filter> element. XPath is described in
[W3C.REC-xpath-19991116]. [W3C.REC-xpath-19991116].
The data model used in the XPath expression is the same as that used The data model used in the XPath expression is the same as that used
in XPath 1.0 [W3C.REC-xpath-19991116], with the same extension for in XPath 1.0 [W3C.REC-xpath-19991116], with the same extension for
root node children as used by XSLT 1.0 [W3C.REC-xslt-19991116] root node children as used by XSLT 1.0 ([W3C.REC-xslt-19991116],
(section 3.1). Specifically, it means that the root node MAY have Section 3.1). Specifically, it means that the root node MAY have any
any number of element nodes as its children. number of element nodes as its children.
The XPath expression is evaluated in the following context: The XPath expression is evaluated in the following context:
o The set of namespace declarations are those in scope on the o The set of namespace declarations are those in scope on the
<filter> element. <filter> element.
o The set of variable bindings is defined by the data model. If no o The set of variable bindings is defined by the data model. If no
such variable bindings are defined, the set is empty. such variable bindings are defined, the set is empty.
o The function library is the core function library, plus any o The function library is the core function library, plus any
skipping to change at page 75, line 15 skipping to change at page 68, line 15
o The context node is the root node. o The context node is the root node.
The XPath expression MUST return a node set. If it does not return a The XPath expression MUST return a node set. If it does not return a
node set, the operation fails with an "invalid-value" error. node set, the operation fails with an "invalid-value" error.
The response message contains the subtrees selected by the filter The response message contains the subtrees selected by the filter
expression. For each such subtree, the path from the data model root expression. For each such subtree, the path from the data model root
node down to the subtree, including any elements or attributes node down to the subtree, including any elements or attributes
necessary to uniquely identify the subtree, are included in the necessary to uniquely identify the subtree, are included in the
response message. Specific data instances are not duplicated in the response message. Specific data instances are not duplicated in the
respone. response.
8.9.2. Dependencies 8.9.2. Dependencies
None. None.
8.9.3. Capability Identifier 8.9.3. Capability Identifier
The :xpath capability is identified by the following capability The :xpath capability is identified by the following capability
string: string:
skipping to change at page 75, line 45 skipping to change at page 68, line 45
The :xpath capability modifies the <get> and <get-config> operations The :xpath capability modifies the <get> and <get-config> operations
to accept the value "xpath" in the "type" attribute of the <filter> to accept the value "xpath" in the "type" attribute of the <filter>
element. When the "type" attribute is set to "xpath", a "select" element. When the "type" attribute is set to "xpath", a "select"
attribute MUST be present on the <filter> element. The "select" attribute MUST be present on the <filter> element. The "select"
attribute will be treated as an XPath expression and used to filter attribute will be treated as an XPath expression and used to filter
the returned data. The <filter> element itself MUST be empty in this the returned data. The <filter> element itself MUST be empty in this
case. case.
The XPath result for the select expression MUST be a node-set. Each The XPath result for the select expression MUST be a node-set. Each
node in the node-set MUST correspond to a node in underlying data node in the node-set MUST correspond to a node in the underlying data
model. In order to properly identify each node, the following model. In order to properly identify each node, the following
encoding rules are defined: encoding rules are defined:
o All ancestor nodes of the result node MUST be encoded first, so o All ancestor nodes of the result node MUST be encoded first, so
the <data> element returned in the reply contains only fully- the <data> element returned in the reply contains only fully
specified sub-trees, according to the underlying data model. specified subtrees, according to the underlying data model.
o If any sibling or ancestor nodes of the result node are needed to o If any sibling or ancestor nodes of the result node are needed to
identify a particular instance within a conceptual data structure, identify a particular instance within a conceptual data structure,
then these nodes MUST also be encoded in the response. then these nodes MUST also be encoded in the response.
For example: For example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config> <get-config>
skipping to change at page 77, line 10 skipping to change at page 69, line 45
</users> </users>
</top> </top>
</data> </data>
</rpc-reply> </rpc-reply>
9. Security Considerations 9. Security Considerations
This section provides security considerations for the base NETCONF This section provides security considerations for the base NETCONF
message layer and the base operations of the NETCONF protocol. message layer and the base operations of the NETCONF protocol.
Security considerations for the NETCONF transports are provided in Security considerations for the NETCONF transports are provided in
the transport documents and security considerations for the content the transport documents, and security considerations for the content
manipulated by NETCONF can be found in the documents defining data manipulated by NETCONF can be found in the documents defining data
models. models.
This document does not specify an authorization scheme, as such a This document does not specify an authorization scheme, as such a
scheme will likely be tied to a meta-data model or a data model. scheme will likely be tied to a meta-data model or a data model.
Implementors SHOULD provide a comprehensive authorization scheme with Implementors SHOULD provide a comprehensive authorization scheme with
NETCONF. NETCONF.
Authorization of individual users via the NETCONF server may or may Authorization of individual users via the NETCONF server may or may
not map 1:1 to other interfaces. First, the data models might be not map 1:1 to other interfaces. First, the data models might be
incompatible. Second, it could be desirable to authorize based on incompatible. Second, it could be desirable to authorize based on
mechanisms available in the secure transport layer (SSH, BEEP, etc). mechanisms available in the Secure Transport layer (e.g., SSH, Blocks
Extensible Exchange Protocol (BEEP), etc.).
In addition, operations on configurations could have unintended In addition, operations on configurations could have unintended
consequences if those operations are also not guarded by the global consequences if those operations are also not guarded by the global
lock on the files or objects being operated upon. For instance, a lock on the files or objects being operated upon. For instance, if
partially complete access list could be committed from a candidate the running configuration is not locked, a partially complete access
configuration unbeknownst to the owner of the lock of the candidate list could be committed from the candidate configuration unbeknownst
configuration, leading to either an insecure or inaccessible device to the owner of the lock of the candidate configuration, leading to
if the lock on the candidate configuration does not also apply to the either an insecure or inaccessible device.
<copy-config> operation when applied to it.
Configuration information is by its very nature sensitive. Its Configuration information is by its very nature sensitive. Its
transmission in the clear and without integrity checking leaves transmission in the clear and without integrity checking leaves
devices open to classic eavesdropping and false data injection devices open to classic eavesdropping and false data injection
attacks. Configuration information often contains passwords, user attacks. Configuration information often contains passwords, user
names, service descriptions, and topological information, all of names, service descriptions, and topological information, all of
which are sensitive. Because of this, this protocol SHOULD be which are sensitive. Because of this, this protocol SHOULD be
implemented carefully with adequate attention to all manner of attack implemented carefully with adequate attention to all manner of attack
one might expect to experience with other management interfaces. one might expect to experience with other management interfaces.
The protocol, therefore, MUST minimally support options for both The protocol, therefore, MUST minimally support options for both
confidentiality and authentication. It is anticipated that the confidentiality and authentication. It is anticipated that the
underlying protocol (SSH, BEEP, etc) will provide for both underlying protocol (SSH, BEEP, etc.) will provide for both
confidentiality and authentication, as is required. It is further confidentiality and authentication, as is required. It is further
expected that the identity of each end of a NETCONF session will be expected that the identity of each end of a NETCONF session will be
available to the other in order to determine authorization for any available to the other in order to determine authorization for any
given request. One could also easily envision additional given request. One could also easily envision additional
information, such as transport and encryption methods, being made information, such as transport and encryption methods, being made
available for purposes of authorization. NETCONF itself provide no available for purposes of authorization. NETCONF itself provides no
means to re-authenticate, much less authenticate. All such actions means to re-authenticate, much less authenticate. All such actions
occur at lower layers. occur at lower layers.
Different environments may well allow different rights prior to and Different environments may well allow different rights prior to and
then after authentication. Thus, an authorization model is not then after authentication. Thus, an authorization model is not
specified in this document. When an operation is not properly specified in this document. When an operation is not properly
authorized, a simple "access denied" is sufficient. Note that authorized, a simple "access denied" is sufficient. Note that
authorization information can be exchanged in the form of authorization information can be exchanged in the form of
configuration information, which is all the more reason to ensure the configuration information, which is all the more reason to ensure the
security of the connection. security of the connection.
That having been said, it is important to recognize that some That having been said, it is important to recognize that some
operations are clearly more sensitive by nature than others. For operations are clearly more sensitive by nature than others. For
instance, <copy-config> to the startup or running configurations is instance, <copy-config> to the startup or running configurations is
clearly not a normal provisioning operation, whereas <edit-config> clearly not a normal provisioning operation, whereas <edit-config>
is. Such global operations MUST disallow the changing of information is. Such global operations MUST disallow the changing of information
that an individual does not have authorization to perform. For that an individual does not have authorization to perform. For
example, if a user A is not allowed to configure an IP address on an example, if user A is not allowed to configure an IP address on an
interface but user B has configured an IP address on an interface in interface but user B has configured an IP address on an interface in
the <candidate> configuration, user A MUST NOT be allowed to commit the <candidate> configuration, user A MUST NOT be allowed to commit
the <candidate> configuration. the <candidate> configuration.
Similarly, just because someone says "go write a configuration Similarly, just because someone says "go write a configuration
through the URL capability at a particular place", this does not mean through the URL capability at a particular place", this does not mean
that an element will do it without proper authorization. that an element will do it without proper authorization.
The <lock> operation will demonstrate that NETCONF is intended for The <lock> operation will demonstrate that NETCONF is intended for
use by systems that have at least some trust of the administrator. use by systems that have at least some trust of the administrator.
As specified in this document, it is possible to lock portions of a As specified in this document, it is possible to lock portions of a
configuration that a principal might not otherwise have access to. configuration that a principal might not otherwise have access to.
After all, the entire configuration is locked. To mitigate this After all, the entire configuration is locked. To mitigate this
problem, there are two approaches. It is possible to kill another problem, there are two approaches. It is possible to kill another
NETCONF session programmatically from within NETCONF if one knows the NETCONF session programmatically from within NETCONF if one knows the
session identifier of the offending session. The other possible way session identifier of the offending session. The other possible way
to break a lock is to provide an function within the device's native to break a lock is to provide a function within the device's native
user interface. These two mechanisms suffer from a race condition user interface. These two mechanisms suffer from a race condition
that could be ameliorated by removing the offending user from an AAA that could be ameliorated by removing the offending user from an
server. However, such a solution is not useful in all deployment Authentication, Authorization, and Accounting (AAA) server. However,
scenarios, such as those where SSH public/private key pairs are used. such a solution is not useful in all deployment scenarios, such as
those where SSH public/private key pairs are used.
10. IANA Considerations 10. IANA Considerations
10.1. NETCONF XML Namespace 10.1. NETCONF XML Namespace
This document registers a URI for the NETCONF XML namespace in the This document registers a URI for the NETCONF XML namespace in the
IETF XML registry [RFC3688]. IETF XML registry [RFC3688].
IANA is requested to update the allocation of the following URI to IANA has updated the following URI to reference this document.
reference this document when it is published as an RFC.
URI: urn:ietf:params:xml:ns:netconf:base:1.0 URI: urn:ietf:params:xml:ns:netconf:base:1.0
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
10.2. NETCONF XML Schema 10.2. NETCONF XML Schema
This document registers a URI for the NETCONF XML schema in the IETF This document registers a URI for the NETCONF XML schema in the IETF
XML registry [RFC3688]. XML registry [RFC3688].
IANA is requested to update the allocation of the following URI to IANA has updated the following URI to reference this document.
reference this document when it is published as an RFC.
URI: urn:ietf:params:xml:schema:netconf URI: urn:ietf:params:xml:schema:netconf
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: Appendix B of this document. XML: Appendix B of this document.
10.3. NETCONF YANG Module 10.3. NETCONF YANG Module
This document registers a YANG module in the YANG Module Names This document registers a YANG module in the YANG Module Names
registry [RFC6020]. registry [RFC6020].
name: ietf-netconf name: ietf-netconf
skipping to change at page 79, line 43 skipping to change at page 72, line 16
XML: Appendix B of this document. XML: Appendix B of this document.
10.3. NETCONF YANG Module 10.3. NETCONF YANG Module
This document registers a YANG module in the YANG Module Names This document registers a YANG module in the YANG Module Names
registry [RFC6020]. registry [RFC6020].
name: ietf-netconf name: ietf-netconf
namespace: urn:ietf:params:xml:ns:netconf:base:1.0 namespace: urn:ietf:params:xml:ns:netconf:base:1.0
prefix: nc prefix: nc
reference: RFCXXXX reference: RFC 6241
10.4. NETCONF Capability URNs 10.4. NETCONF Capability URNs
IANA has created and will maintain a registry "Network Configuration IANA has created and now maintains a registry "Network Configuration
Protocol (NETCONF) Capability URNs" that allocates NETCONF capability Protocol (NETCONF) Capability URNs" that allocates NETCONF capability
identifiers. Additions to the registry require IETF Standards identifiers. Additions to the registry require IETF Standards
Action. Action.
IANA is requested to update the allocations of the following IANA has updated the allocations of the following capabilities to
capabilities to reference this document when it is published as an reference this document.
RFC.
+--------------------+----------------------------------------------+ Index
| Index | Capability Identifier | Capability Identifier
+--------------------+----------------------------------------------+ ------------------------
| :writable-running | urn:ietf:params:netconf:capability:writable- |
| | running:1.0 |
| | |
| :candidate | urn:ietf:params:netconf:capability:candidate |
| | :1.0 |
| | |
| :rollback-on-error | urn:ietf:params:netconf:capability:rollback- |
| | on-error:1.0 |
| | |
| :startup | urn:ietf:params:netconf:capability:startup:1 |
| | .0 |
| | |
| :url | urn:ietf:params:netconf:capability:url:1.0 |
| | |
| :xpath | urn:ietf:params:netconf:capability:xpath:1.0 |
+--------------------+----------------------------------------------+
IANA is requested to add the following capabilities to the registry: :writable-running
urn:ietf:params:netconf:capability:writable-running:1.0
+---------------------+---------------------------------------------+ :candidate
| Index | Capability Identifier | urn:ietf:params:netconf:capability:candidate:1.0
+---------------------+---------------------------------------------+
| :base:1.1 | urn:ietf:params:netconf:base:1.1 |
| | |
| :confirmed-commit:1 | urn:ietf:params:netconf:capability:confirme |
| .1 | d-commit:1.1 |
| | |
| :validate:1.1 | urn:ietf:params:netconf:capability:validate |
| | :1.1 |
+---------------------+---------------------------------------------+
11. Authors and Acknowledgements :rollback-on-error
urn:ietf:params:netconf:capability:rollback-on-error:1.0
This document was written by: :startup
urn:ietf:params:netconf:capability:startup:1.0
Andy Bierman :url
urn:ietf:params:netconf:capability:url:1.0
Ken Crozier, Cisco Systems :xpath
urn:ietf:params:netconf:capability:xpath:1.0
Rob Enns, Juniper Networks IANA has added the following capabilities to the registry:
Index
Capability Identifier
------------------------
:base:1.1
urn:ietf:params:netconf:base:1.1
:confirmed-commit:1.1
urn:ietf:params:netconf:capability:confirmed-commit:1.1
:validate:1.1
urn:ietf:params:netconf:capability:validate:1.1
11. Contributors
In addition to the editors, this document was written by:
Ken Crozier, Cisco Systems
Ted Goddard, IceSoft Ted Goddard, IceSoft
Eliot Lear, Cisco Systems Eliot Lear, Cisco Systems
Phil Shafer, Juniper Networks Phil Shafer, Juniper Networks
Steve Waldbusser Steve Waldbusser
Margaret Wasserman, ThingMagic Margaret Wasserman, Painless Security, LLC
12. Acknowledgements
The authors would like to acknowledge the members of the NETCONF The authors would like to acknowledge the members of the NETCONF
working group. In particular, we would like to thank Wes Hardaker working group. In particular, we would like to thank Wes Hardaker
for his persistence and patience in assisting us with security for his persistence and patience in assisting us with security
considerations. We would also like to thank Randy Presuhn, Sharon considerations. We would also like to thank Randy Presuhn, Sharon
Chisholm, Glenn Waters, David Perkins, Weijing Chen, Simon Leinen, Chisholm, Glenn Waters, David Perkins, Weijing Chen, Simon Leinen,
Keith Allen, Dave Harrington, Ladislav Lhotka, Tom Petch, and Kent Keith Allen, Dave Harrington, Ladislav Lhotka, Tom Petch, and Kent
Watsen for all of their valuable advice. Watsen for all of their valuable advice.
12. References 13. References
12.1. Normative References
[W3C.REC-xml-20001006]
Bray, T., Sperberg-McQueen, C., Paoli, J., and E. Maler,
"Extensible Markup Language (XML) 1.0 (Second Edition)",
World Wide Web Consortium FirstEdition REC-xml-20001006,
October 2000,
<http://www.w3.org/TR/2000/REC-xml-20001006>.
[W3C.REC-xpath-19991116] 13.1. Normative References
DeRose, S. and J. Clark, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[I-D.ietf-netconf-rfc4742bis]
Wasserman, M. and T. Goddard, "Using the NETCONF
Configuration Protocol over Secure Shell (SSH)",
draft-ietf-netconf-rfc4742bis-07 (work in progress),
February 2011.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
IETF URN Sub-namespace for Registered Protocol IETF URN Sub-namespace for Registered Protocol
Parameters", BCP 73, RFC 3553, June 2003. Parameters", BCP 73, RFC 3553, June 2003.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC5717] Lengyel, B. and M. Bjorklund, "Partial Lock Remote [RFC5717] Lengyel, B. and M. Bjorklund, "Partial Lock Remote
Procedure Call (RPC) for NETCONF", RFC 5717, Procedure Call (RPC) for NETCONF", RFC 5717,
December 2009. December 2009.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020, Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010. October 2010.
[RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021,
October 2010. October 2010.
12.2. Informative References [RFC6242] Wasserman, M., "Using the NETCONF Configuration Protocol
over Secure Shell (SSH)", RFC 6242, June 2011.
[W3C.REC-xslt-19991116] [W3C.REC-xml-20001006]
Clark, J., "XSL Transformations (XSLT) Version 1.0", World Sperberg-McQueen, C., Bray, T., Paoli, J., and E. Maler,
Wide Web Consortium Recommendation REC-xslt-19991116, "Extensible Markup Language (XML) 1.0 (Second Edition)",
November 1999, World Wide Web Consortium REC-xml-20001006, October 2000,
<http://www.w3.org/TR/1999/REC-xslt-19991116>. <http://www.w3.org/TR/2000/REC-xml-20001006>.
[W3C.REC-xpath-19991116]
DeRose, S. and J. Clark, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>.
13.2. Informative References
[RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson,
"Remote Authentication Dial In User Service (RADIUS)", "Remote Authentication Dial In User Service (RADIUS)",
RFC 2865, June 2000. RFC 2865, June 2000.
[RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for
the Use of Extensible Markup Language (XML) the Use of Extensible Markup Language (XML)
within IETF Protocols", BCP 70, RFC 3470, January 2003. within IETF Protocols", BCP 70, RFC 3470, January 2003.
[RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
Protocol Architecture", RFC 4251, January 2006. Protocol Architecture", RFC 4251, January 2006.
[RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006. December 2006.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[W3C.REC-xslt-19991116]
Clark, J., "XSL Transformations (XSLT) Version 1.0", World
Wide Web Consortium Recommendation REC-xslt-19991116,
November 1999,
<http://www.w3.org/TR/1999/REC-xslt-19991116>.
Appendix A. NETCONF Error List Appendix A. NETCONF Error List
This section is normative. This section is normative.
For each error-tag, the valid error-type and error-severity values For each error-tag, the valid error-type and error-severity values
are listed, together with any mandatory error-info, if any. are listed, together with any mandatory error-info, if any.
error-tag: in-use error-tag: in-use
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: none error-info: none
Description: The request requires a resource that already is in Description: The request requires a resource that already is in
use. use.
error-tag: invalid-value error-tag: invalid-value
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: none error-info: none
Description: The request specifies an unacceptable value for one Description: The request specifies an unacceptable value for one
or more parameters. or more parameters.
error-tag: too-big error-tag: too-big
error-type: transport, rpc, protocol, application error-type: transport, rpc, protocol, application
error-severity: error error-severity: error
error-info: none error-info: none
Description: The request or response (that would be generated) is Description: The request or response (that would be generated) is
too large for the implementation to handle. too large for the implementation to handle.
error-tag: missing-attribute error-tag: missing-attribute
error-type: rpc, protocol, application error-type: rpc, protocol, application
error-severity: error error-severity: error
error-info: <bad-attribute> : name of the missing attribute error-info: <bad-attribute> : name of the missing attribute
<bad-element> : name of the element that is supposed to <bad-element> : name of the element that is supposed
contain the missing attribute to contain the missing attribute
Description: An expected attribute is missing. Description: An expected attribute is missing.
error-tag: bad-attribute error-tag: bad-attribute
error-type: rpc, protocol, application error-type: rpc, protocol, application
error-severity: error error-severity: error
error-info: <bad-attribute> : name of the attribute w/ bad value error-info: <bad-attribute> : name of the attribute w/ bad value
<bad-element> : name of the element that contains <bad-element> : name of the element that contains
the attribute with the bad value the attribute with the bad value
Description: An attribute value is not correct; e.g., wrong type, Description: An attribute value is not correct; e.g., wrong type,
out of range, pattern mismatch. out of range, pattern mismatch.
error-tag: unknown-attribute error-tag: unknown-attribute
error-type: rpc, protocol, application error-type: rpc, protocol, application
error-severity: error error-severity: error
error-info: <bad-attribute> : name of the unexpected attribute error-info: <bad-attribute> : name of the unexpected attribute
<bad-element> : name of the element that contains <bad-element> : name of the element that contains
the unexpected attribute the unexpected attribute
Description: An unexpected attribute is present. Description: An unexpected attribute is present.
error-tag: missing-element error-tag: missing-element
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: <bad-element> : name of the missing element error-info: <bad-element> : name of the missing element
Description: An expected element is missing. Description: An expected element is missing.
error-tag: bad-element error-tag: bad-element
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: <bad-element> : name of the element w/ bad value error-info: <bad-element> : name of the element w/ bad value
Description: An element value is not correct; e.g., wrong type, Description: An element value is not correct; e.g., wrong type,
out of range, pattern mismatch. out of range, pattern mismatch.
error-tag: unknown-element error-tag: unknown-element
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: <bad-element> : name of the unexpected element error-info: <bad-element> : name of the unexpected element
Description: An unexpected element is present. Description: An unexpected element is present.
error-tag: unknown-namespace error-tag: unknown-namespace
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: <bad-element> : name of the element that contains error-info: <bad-element> : name of the element that contains
the unexpected namespace the unexpected namespace
<bad-namespace> : name of the unexpected namespace <bad-namespace> : name of the unexpected namespace
Description: An unexpected namespace is present. Description: An unexpected namespace is present.
error-tag: access-denied error-tag: access-denied
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: none error-info: none
Description: Access to the requested protocol operation, or Description: Access to the requested protocol operation or
data model is denied because authorization failed. data model is denied because authorization failed.
error-tag: lock-denied error-tag: lock-denied
error-type: protocol error-type: protocol
error-severity: error error-severity: error
error-info: <session-id> : session ID of session holding the error-info: <session-id> : session ID of session holding the
requested lock, or zero to indicate a non-NETCONF requested lock, or zero to indicate a non-NETCONF
entity holds the lock entity holds the lock
Description: Access to the requested lock is denied because the Description: Access to the requested lock is denied because the
lock is currently held by another entity. lock is currently held by another entity.
error-tag: resource-denied error-tag: resource-denied
error-type: transport, rpc, protocol, application error-type: transport, rpc, protocol, application
error-severity: error error-severity: error
error-info: none error-info: none
Description: Request could not be completed because of Description: Request could not be completed because of
insufficient resources. insufficient resources.
error-tag: rollback-failed error-tag: rollback-failed
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: none error-info: none
Description: Request to rollback some configuration change (via Description: Request to roll back some configuration change (via
rollback-on-error or discard-changes operations) was rollback-on-error or <discard-changes> operations)
not completed for some reason. was not completed for some reason.
error-tag: data-exists error-tag: data-exists
error-type: application error-type: application
error-severity: error error-severity: error
error-info: none error-info: none
Description: Request could not be completed because the relevant Description: Request could not be completed because the relevant
data model content already exists. For example, data model content already exists. For example,
a "create" operation was attempted on data that a "create" operation was attempted on data that
already exists. already exists.
error-tag: data-missing error-tag: data-missing
error-type: application error-type: application
error-severity: error error-severity: error
error-info: none error-info: none
Description: Request could not be completed because the relevant Description: Request could not be completed because the relevant
data model content does not exist. For example, data model content does not exist. For example,
a "delete" operation was attempted on a "delete" operation was attempted on
data that does not exist. data that does not exist.
error-tag: operation-not-supported error-tag: operation-not-supported
error-type: protocol, application error-type: protocol, application
error-severity: error error-severity: error
error-info: none error-info: none
Description: Request could not be completed because the requested Description: Request could not be completed because the requested
operation is not supported by this implementation. operation is not supported by this implementation.
error-tag: operation-failed error-tag: operation-failed
error-type: rpc, protocol, application error-type: rpc, protocol, application
error-severity: error error-severity: error
error-info: none error-info: none
Description: Request could not be completed because the requested Description: Request could not be completed because the requested
operation failed for some reason not covered by operation failed for some reason not covered by
any other error condition. any other error condition.
error-tag: partial-operation error-tag: partial-operation
error-type: application error-type: application
error-severity: error error-severity: error
error-info: <ok-element> : identifies an element in the data error-info: <ok-element> : identifies an element in the data
model for which the requested operation has been model for which the requested operation has been
completed for that node and all its child nodes. completed for that node and all its child nodes.
This element can appear zero or more times in the This element can appear zero or more times in the
<error-info> container. <error-info> container.
<err-element> : identifies an element in the data <err-element> : identifies an element in the data
model for which the requested operation has failed model for which the requested operation has failed
for that node and all its child nodes. for that node and all its child nodes.
This element can appear zero or more times in the This element can appear zero or more times in the
<error-info> container. <error-info> container.
<noop-element> : identifies an element in the data <noop-element> : identifies an element in the data
model for which the requested operation was not model for which the requested operation was not
attempted for that node and all its child nodes. attempted for that node and all its child nodes.
This element can appear zero or more times in the This element can appear zero or more times in the
<error-info> container. <error-info> container.
Description: This error-tag is obsolete, and SHOULD NOT be sent Description: This error-tag is obsolete, and SHOULD NOT be sent
by servers conforming to this document. by servers conforming to this document.
Some part of the requested operation failed or was Some part of the requested operation failed or was
not attempted for some reason. Full cleanup has not attempted for some reason. Full cleanup has
not been performed (e.g., rollback not supported) not been performed (e.g., rollback not supported)
by the server. The error-info container is used by the server. The error-info container is used
to identify which portions of the application to identify which portions of the application
data model content for which the requested operation data model content for which the requested operation
has succeeded (<ok-element>), failed (<bad-element>), has succeeded (<ok-element>), failed (<bad-element>),
or not been attempted (<noop-element>). or not been attempted (<noop-element>).
error-tag: malformed-message error-tag: malformed-message
error-type: rpc error-type: rpc
error-severity: error error-severity: error
error-info: none error-info: none
Description: A message could not be handled because it failed to Description: A message could not be handled because it failed to
be parsed correctly. For example, the message is not be parsed correctly. For example, the message is not
well-formed XML or it uses an invalid character set. well-formed XML or it uses an invalid character set.
This error-tag is new in :base:1.1 and MUST NOT be This error-tag is new in :base:1.1 and MUST NOT be
sent to old clients. sent to old clients.
Appendix B. XML Schema for NETCONF Messages Layer Appendix B. XML Schema for NETCONF Messages Layer
This section is normative. This section is normative.
<CODE BEGINS> file "netconf.xsd" <CODE BEGINS> file "netconf.xsd"
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
skipping to change at page 93, line 11 skipping to change at page 85, line 18
</xs:schema> </xs:schema>
<CODE ENDS> <CODE ENDS>
Appendix C. YANG Module for NETCONF Protocol Operations Appendix C. YANG Module for NETCONF Protocol Operations
This section is normative. This section is normative.
The ietf-netconf YANG module imports typedefs from [RFC6021]. The ietf-netconf YANG module imports typedefs from [RFC6021].
// RFC Ed.: please update the date to the date of publication <CODE BEGINS> file "ietf-netconf@2011-06-01.yang"
<CODE BEGINS> file "ietf-netconf@2011-03-08.yang"
module ietf-netconf { module ietf-netconf {
// the namespace for NETCONF XML definitions is unchanged // the namespace for NETCONF XML definitions is unchanged
// from RFC 4741 which this document replaces // from RFC 4741, which this document replaces
namespace "urn:ietf:params:xml:ns:netconf:base:1.0"; namespace "urn:ietf:params:xml:ns:netconf:base:1.0";
prefix nc; prefix nc;
import ietf-inet-types { import ietf-inet-types {
prefix inet; prefix inet;
} }
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netconf/> "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org> WG List: <netconf@ietf.org>
WG Chair: Bert Wijnen WG Chair: Bert Wijnen
<mailto:bertietf@bwijnen.net> <bertietf@bwijnen.net>
WG Chair: Mehmet Ersue WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com> <mehmet.ersue@nsn.com>
Editor: Martin Bjorklund Editor: Martin Bjorklund
<mailto:mbj@tail-f.com> <mbj@tail-f.com>
Editor: Juergen Schoenwaelder Editor: Juergen Schoenwaelder
<mailto:j.schoenwaelder@jacobs-university.de> <j.schoenwaelder@jacobs-university.de>
Editor: Andy Bierman Editor: Andy Bierman
<mailto:andy.bierman@brocade.com>"; <andy.bierman@brocade.com>";
description description
"NETCONF Protocol Data Types and Protocol Operations. "NETCONF Protocol Data Types and Protocol Operations.
Copyright (c) 2010 IETF Trust and the persons identified as Copyright (c) 2011 IETF Trust and the persons identified as
the document authors. All rights reserved. the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC 6241; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this note revision 2011-06-01 {
description
"Initial revision";
reference
"RFC 6241: Network Configuration Protocol";
}
// RFC Ed.: please update the date to the date of publication extension get-filter-element-attributes {
revision 2011-03-08 { description
description "If this extension is present within an 'anyxml'
"Initial revision"; statement named 'filter', which must be conceptually
reference defined within the RPC input section for the <get>
"RFC XXXX: Network Configuration Protocol"; and <get-config> protocol operations, then the
} following unqualified XML attribute is supported
within the <filter> element, within a <get> or
<get-config> protocol operation:
extension get-filter-element-attributes { type : optional attribute with allowed
description value strings 'subtree' and 'xpath'.
"If this extension is present within the If missing, the default value is 'subtree'.
an 'anyxml' statement named 'filter', which must be
conceptually defined within the RPC input section
for the 'get' and 'get-config' protocol operations,
then the following unqualified XML attribute is
supported within the 'filter' element, within
a 'get' or 'get-config' protocol operation:
type : optional attribute with allowed If the 'xpath' feature is supported, then the
value strings 'subtree' and 'xpath'. following unqualified XML attribute is
If missing, the default value is 'subtree'. also supported:
If the 'xpath' feature is supported, then the select: optional attribute containing a
following unqualified XML attribute is string representing an XPath expression.
also supported: The 'type' attribute must be equal to 'xpath'
if this attribute is present.";
}
select: optional attribute containing a // NETCONF capabilities defined as features
string representing an XPath expression. feature writable-running {
The 'type' attribute must be equal to 'xpath' description
if this attribute is present."; "NETCONF :writable-running capability;
} If the server advertises the :writable-running
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC 6241, Section 8.2";
}
// NETCONF capabilities defined as features feature candidate {
feature writable-running { description
description "NETCONF :candidate capability;
"NETCONF :writable-running capability; If the server advertises the :candidate
If the server advertises the :writable-running capability for a session, then this feature must
capability for a session, then this feature must also be enabled for that session. Otherwise,
also be enabled for that session. Otherwise, this feature must not be enabled.";
this feature must not be enabled."; reference "RFC 6241, Section 8.3";
reference "RFC XXXX, section 8.2."; }
}
feature candidate { feature confirmed-commit {
description if-feature candidate;
"NETCONF :candidate capability; description
If the server advertises the :candidate "NETCONF :confirmed-commit:1.1 capability;
capability for a session, then this feature must If the server advertises the :confirmed-commit:1.1
also be enabled for that session. Otherwise, capability for a session, then this feature must
this feature must not be enabled."; also be enabled for that session. Otherwise,
reference "RFC XXXX, section 8.3."; this feature must not be enabled.";
}
feature confirmed-commit { reference "RFC 6241, Section 8.4";
if-feature candidate; }
description
"NETCONF :confirmed-commit:1.1 capability;
If the server advertises the :confirmed-commit:1.1
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.4."; feature rollback-on-error {
} description
"NETCONF :rollback-on-error capability;
If the server advertises the :rollback-on-error
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC 6241, Section 8.5";
}
feature rollback-on-error { feature validate {
description description
"NETCONF :rollback-on-error capability; "NETCONF :validate:1.1 capability;
If the server advertises the :rollback-on-error If the server advertises the :validate:1.1
capability for a session, then this feature must capability for a session, then this feature must
also be enabled for that session. Otherwise, also be enabled for that session. Otherwise,
this feature must not be enabled."; this feature must not be enabled.";
reference "RFC XXXX, section 8.5.";
}
feature validate { reference "RFC 6241, Section 8.6";
description }
"NETCONF :validate:1.1 capability;
If the server advertises the :validate:1.1
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.6.";
}
feature startup {
description
"NETCONF :startup capability;
If the server advertises the :startup
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.7.";
}
feature url { feature startup {
description description
"NETCONF :url capability; "NETCONF :startup capability;
If the server advertises the :url If the server advertises the :startup
capability for a session, then this feature must capability for a session, then this feature must
also be enabled for that session. Otherwise, also be enabled for that session. Otherwise,
this feature must not be enabled."; this feature must not be enabled.";
reference "RFC XXXX, section 8.8."; reference "RFC 6241, Section 8.7";
} }
feature xpath { feature url {
description description
"NETCONF :xpath capability; "NETCONF :url capability;
If the server advertises the :xpath If the server advertises the :url
capability for a session, then this feature must capability for a session, then this feature must
also be enabled for that session. Otherwise, also be enabled for that session. Otherwise,
this feature must not be enabled."; this feature must not be enabled.";
reference "RFC XXXX, section 8.9."; reference "RFC 6241, Section 8.8";
} }
// NETCONF Simple Types feature xpath {
description
"NETCONF :xpath capability;
If the server advertises the :xpath
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC 6241, Section 8.9";
}
typedef session-id-type { // NETCONF Simple Types
type uint32 {
range "1..max";
}
description
"NETCONF Session Id";
}
typedef session-id-or-zero-type { typedef session-id-type {
type uint32; type uint32 {
description range "1..max";
"NETCONF Session Id or Zero to indicate none"; }
} description
"NETCONF Session Id";
}
typedef error-tag-type { typedef session-id-or-zero-type {
type enumeration { type uint32;
enum in-use { description
description "NETCONF Session Id or Zero to indicate none";
"The request requires a resource that }
already is in use."; typedef error-tag-type {
} type enumeration {
enum invalid-value { enum in-use {
description description
"The request specifies an unacceptable value for one "The request requires a resource that
or more parameters."; already is in use.";
} }
enum too-big { enum invalid-value {
description description
"The request or response (that would be generated) is "The request specifies an unacceptable value for one
too large for the implementation to handle."; or more parameters.";
} }
enum missing-attribute { enum too-big {
description description
"An expected attribute is missing."; "The request or response (that would be generated) is
} too large for the implementation to handle.";
enum bad-attribute { }
description enum missing-attribute {
"An attribute value is not correct; e.g., wrong type, description
out of range, pattern mismatch."; "An expected attribute is missing.";
} }
enum unknown-attribute { enum bad-attribute {
description description
"An unexpected attribute is present."; "An attribute value is not correct; e.g., wrong type,
} out of range, pattern mismatch.";
enum missing-element { }
description enum unknown-attribute {
"An expected element is missing."; description
"An unexpected attribute is present.";
}
enum missing-element {
description
"An expected element is missing.";
}
enum bad-element {
description
"An element value is not correct; e.g., wrong type,
out of range, pattern mismatch.";
}
enum unknown-element {
description
"An unexpected element is present.";
}
enum unknown-namespace {
description
"An unexpected namespace is present.";
}
enum access-denied {
description
"Access to the requested protocol operation or
data model is denied because authorization failed.";
}
enum lock-denied {
description
"Access to the requested lock is denied because the
lock is currently held by another entity.";
}
enum resource-denied {
description
"Request could not be completed because of
insufficient resources.";
}
enum rollback-failed {
description
"Request to roll back some configuration change (via
rollback-on-error or <discard-changes> operations)
was not completed for some reason.";
}
enum data-exists {
description
"Request could not be completed because the relevant
data model content already exists. For example,
a 'create' operation was attempted on data that
already exists.";
}
enum data-missing {
description
"Request could not be completed because the relevant
data model content does not exist. For example,
a 'delete' operation was attempted on
data that does not exist.";
}
enum operation-not-supported {
description
"Request could not be completed because the requested
operation is not supported by this implementation.";
}
enum operation-failed {
description
"Request could not be completed because the requested
operation failed for some reason not covered by
any other error condition.";
}
enum partial-operation {
description
"This error-tag is obsolete, and SHOULD NOT be sent
by servers conforming to this document.";
}
enum malformed-message {
description
"A message could not be handled because it failed to
be parsed correctly. For example, the message is not
well-formed XML or it uses an invalid character set.";
}
}
description "NETCONF Error Tag";
reference "RFC 6241, Appendix A";
}
typedef error-severity-type {
type enumeration {
enum error {
description "Error severity";
} }
enum bad-element { enum warning {
description description "Warning severity";
"An element value is not correct; e.g., wrong type,
out of range, pattern mismatch.";
} }
enum unknown-element { }
description "NETCONF Error Severity";
reference "RFC 6241, Section 4.3";
}
typedef edit-operation-type {
type enumeration {
enum merge {
description description
"An unexpected element is present."; "The configuration data identified by the
element containing this attribute is merged
with the configuration at the corresponding
level in the configuration datastore identified
by the target parameter.";
} }
enum unknown-namespace { enum replace {
description description
"An unexpected namespace is present."; "The configuration data identified by the element
containing this attribute replaces any related
configuration in the configuration datastore
identified by the target parameter. If no such
configuration data exists in the configuration
datastore, it is created. Unlike a
<copy-config> operation, which replaces the
entire target configuration, only the configuration
actually present in the config parameter is affected.";
} }
enum access-denied { enum create {
description description
"Access to the requested protocol operation, or "The configuration data identified by the element
data model is denied because authorization failed."; containing this attribute is added to the
configuration if and only if the configuration
data does not already exist in the configuration
datastore. If the configuration data exists, an
<rpc-error> element is returned with an
<error-tag> value of 'data-exists'.";
} }
enum lock-denied { enum delete {
description description
"Access to the requested lock is denied because the "The configuration data identified by the element
lock is currently held by another entity."; containing this attribute is deleted from the
configuration if and only if the configuration
data currently exists in the configuration
datastore. If the configuration data does not
exist, an <rpc-error> element is returned with
an <error-tag> value of 'data-missing'.";
} }
enum resource-denied { enum remove {
description description
"Request could not be completed because of "The configuration data identified by the element
insufficient resources."; containing this attribute is deleted from the
configuration if the configuration
data currently exists in the configuration
datastore. If the configuration data does not
exist, the 'remove' operation is silently ignored
by the server.";
} }
enum rollback-failed { }
description default "merge";
"Request to rollback some configuration change (via description "NETCONF 'operation' attribute values";
rollback-on-error or discard-changes operations) was reference "RFC 6241, Section 7.2";
not completed for some reason."; }
} // NETCONF Standard Protocol Operations
enum data-exists {
description rpc get-config {
"Request could not be completed because the relevant description
data model content already exists. For example, "Retrieve all or part of a specified configuration.";
a 'create' operation was attempted on data that
already exists."; reference "RFC 6241, Section 7.1";
}
enum data-missing { input {
description container source {
"Request could not be completed because the relevant
data model content does not exist. For example,
a 'delete' operation was attempted on
data that does not exist.";
}
enum operation-not-supported {
description description
"Request could not be completed because the requested "Particular configuration to retrieve.";
operation is not supported by this implementation.";
choice config-source {
mandatory true;
description
"The configuration to retrieve.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config source.";
}
leaf running {
type empty;
description
"The running configuration is the config source.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config source.
This is optional-to-implement on the server because
not all servers will support filtering for this
datastore.";
}
}
} }
enum operation-failed {
anyxml filter {
description description
"Request could not be completed because the requested "Subtree or XPath filter to use.";
operation failed for some reason not covered by nc:get-filter-element-attributes;
any other error condition.";
} }
enum partial-operation { }
description
"This error-tag is obsolete, and SHOULD NOT be sent
by servers conforming to this document.";
} output {
enum malformed-message { anyxml data {
description description
"A message could not be handled because it failed to "Copy of the source datastore subset that matched
be parsed correctly. For example, the message is not the filter criteria (if any). An empty data container
well-formed XML or it uses an invalid character set."; indicates that the request did not produce any results.";
} }
} }
description "NETCONF Error Tag"; }
reference "RFC XXXX, Appendix A.";
}
typedef error-severity-type {
type enumeration {
enum error {
description "Error severity";
}
enum warning {
description "Warning severity";
}
}
description "NETCONF Error Severity";
reference "RFC XXXX, section 4.3.";
}
typedef edit-operation-type {
type enumeration {
enum merge {
description
"The configuration data identified by the
element containing this attribute is merged
with the configuration at the corresponding
level in the configuration datastore identified
by the target parameter.";
}
enum replace {
description
"The configuration data identified by the element
containing this attribute replaces any related
configuration in the configuration datastore
identified by the target parameter. If no such
configuration data exists in the configuration
datastore, it is created. Unlike a
<copy-config> operation, which replaces the
entire target configuration, only the configuration
actually present in the config parameter is affected.";
}
enum create {
description
"The configuration data identified by the element
containing this attribute is added to the
configuration if and only if the configuration
data does not already exist in the configuration
datastore. If the configuration data exists, an
<rpc-error> element is returned with an
<error-tag> value of 'data-exists'.";
}
enum delete {
description
"The configuration data identified by the element
containing this attribute is deleted from the
configuration if and only if the configuration
data currently exists in the configuration
datastore. If the configuration data does not
exist, an <rpc-error> element is returned with
an <error-tag> value of 'data-missing'.";
}
enum remove {
description
"The configuration data identified by the element
containing this attribute is deleted from the
configuration if the configuration
data currently exists in the configuration
datastore. If the configuration data does not
exist, the 'remove' operation is silently ignored
by the server.";
}
}
default "merge";
description "NETCONF 'operation' attribute values";
reference "RFC XXXX, section 7.2.";
}
// NETCONF Standard Protocol Operations
rpc get-config {
description
"Retrieve all or part of a specified configuration.";
reference "RFC XXXX, section 7.1.";
input {
container source {
description
"Particular configuration to retrieve.";
choice config-source { rpc edit-config {
mandatory true; description
description "The <edit-config> operation loads all or part of a specified
"The configuration to retrieve."; configuration to the specified target configuration.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config source.";
}
leaf running {
type empty;
description
"The running configuration is the config source.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config source.
This is optional-to-implement on the server because
not all servers will support filtering for this
datastore.";
}
}
}
anyxml filter { reference "RFC 6241, Section 7.2";
description
"Subtree or XPath filter to use.";
nc:get-filter-element-attributes;
}
}
output { input {
anyxml data { container target {
description description
"Copy of the source datastore subset which matched "Particular configuration to edit.";
the filter criteria (if any). An empty data container
indicates that the request did not produce any results.";
}
}
}
rpc edit-config { choice config-target {
description mandatory true;
"The 'edit-config' operation loads all or part of a specified description
configuration to the specified target configuration."; "The configuration target.";
reference "RFC XXXX, section 7.2."; leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config target.";
}
leaf running {
if-feature writable-running;
type empty;
description
"The running configuration is the config source.";
}
}
}
input { leaf default-operation {
container target { type enumeration {
description enum merge {
"Particular configuration to edit."; description
"The default operation is merge.";
}
enum replace {
description
"The default operation is replace.";
}
enum none {
description
"There is no default operation.";
}
}
default "merge";
description
"The default operation to use.";
choice config-target { }
mandatory true;
description
"The configuration target.";
leaf candidate { leaf test-option {
if-feature candidate; if-feature validate;
type empty; type enumeration {
description enum test-then-set {
"The candidate configuration is the config target."; description
} "The server will test and then set if no errors.";
leaf running { }
if-feature writable-running; enum set {
type empty; description
description "The server will set without a test first.";
"The running configuration is the config source."; }
}
}
}
leaf default-operation { enum test-only {
type enumeration { description
enum merge { "The server will only test and not set, even
description if there are no errors.";
"The default operation is merge."; }
} }
enum replace { default "test-then-set";
description description
"The default operation is replace."; "The test option to use.";
} }
enum none {
description
"There is no default operation.";
}
}
default "merge";
description
"The default operation to use.";
}
leaf test-option { leaf error-option {
if-feature validate; type enumeration {
type enumeration { enum stop-on-error {
enum test-then-set { description
description "The server will stop on errors.";
"The server will test and then set if no errors."; }
} enum continue-on-error {
enum set { description
description "The server may continue on errors.";
"The server will set without a test first."; }
} enum rollback-on-error {
description
"The server will roll back on errors.
This value can only be used if the 'rollback-on-error'
feature is supported.";
}
}
default "stop-on-error";
description
"The error option to use.";
}
enum test-only { choice edit-content {
description mandatory true;
"The server will only test and not set, even description
if there are no errors."; "The content for the edit operation.";
}
}
default "test-then-set";
description
"The test option to use.";
}
leaf error-option { anyxml config {
type enumeration { description
enum stop-on-error { "Inline Config content.";
description }
"The server will stop on errors."; leaf url {
} if-feature url;
enum continue-on-error { type inet:uri;
description description
"The server may continue on errors."; "URL-based config content.";
} }
enum rollback-on-error { }
description }
"The server will rollback on errors. }
This value can only be used if the 'rollback-on-error'
feature is supported.";
}
}
default "stop-on-error";
description
"The error option to use.";
}
choice edit-content { rpc copy-config {
mandatory true; description
description "Create or replace an entire configuration datastore with the
"The content for the edit operation"; contents of another complete configuration datastore.";
anyxml config { reference "RFC 6241, Section 7.3";
description
"Inline Config content.";
}
leaf url {
if-feature url;
type inet:uri;
description
"URL based config content.";
}
}
}
}
rpc copy-config { input {
description container target {
"Create or replace an entire configuration datastore with the description
contents of another complete configuration datastore."; "Particular configuration to copy to.";
reference "RFC XXXX, section 7.3."; choice config-target {
mandatory true;
description
"The configuration target of the copy operation.";
input { leaf candidate {
container target { if-feature candidate;
description type empty;
"Particular configuration to copy to."; description
"The candidate configuration is the config target.";
}
leaf running {
if-feature writable-running;
type empty;
description
"The running configuration is the config target.
This is optional-to-implement on the server.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config target.";
}
}
}
choice config-target { container source {
mandatory true; description
description "Particular configuration to copy from.";
"The configuration target of the copy operation.";
leaf candidate { choice config-source {
if-feature candidate; mandatory true;
type empty; description
description "The configuration source for the copy operation.";
"The candidate configuration is the config target.";
}
leaf running {
if-feature writable-running;
type empty;
description
"The running configuration is the config target.
This is optional-to-implement on the server.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config target.";
}
}
}
container source { leaf candidate {
description if-feature candidate;
"Particular configuration to copy from."; type empty;
description
"The candidate configuration is the config source.";
}
leaf running {
type empty;
description
"The running configuration is the config source.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config source.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config source.";
}
anyxml config {
description
"Inline Config content: <config> element. Represents
an entire configuration datastore, not
a subset of the running datastore.";
}
}
}
}
}
choice config-source { rpc delete-config {
mandatory true; description
description "Delete a configuration datastore.";
"The configuration source for the copy operation.";
leaf candidate { reference "RFC 6241, Section 7.4";
if-feature candidate;
type empty;
description
"The candidate configuration is the config source.";
}
leaf running {
type empty;
description
"The running configuration is the config source.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config source.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config source.";
}
anyxml config {
description
"Inline Config content: 'config' element. Represents
an entire configuration datastore, not
a subset of the running datastore.";
} input {
} container target {
} description
} "Particular configuration to delete.";
}
rpc delete-config { choice config-target {
description mandatory true;
"Delete a configuration datastore."; description
"The configuration target to delete.";
reference "RFC XXXX, section 7.4."; leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config target.";
}
}
}
}
}
input { rpc lock {
container target { description
description "The lock operation allows the client to lock the configuration
"Particular configuration to delete."; system of a device.";
choice config-target { reference "RFC 6241, Section 7.5";
mandatory true;
description
"The configuration target to delete.";
leaf startup { input {
if-feature startup; container target {
type empty; description
description "Particular configuration to lock.";
"The startup configuration is the config target.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config target.";
}
}
}
}
}
rpc lock { choice config-target {
description mandatory true;
"The lock operation allows the client to lock the configuration description
system of a device."; "The configuration target to lock.";
reference "RFC XXXX, section 7.5."; leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config target.";
}
leaf running {
type empty;
description
"The running configuration is the config target.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
}
}
}
}
input { rpc unlock {
container target { description
description "The unlock operation is used to release a configuration lock,
"Particular configuration to lock"; previously obtained with the 'lock' operation.";
choice config-target { reference "RFC 6241, Section 7.6";
mandatory true;
description
"The configuration target to lock.";
leaf candidate { input {
if-feature candidate; container target {
type empty; description
description "Particular configuration to unlock.";
"The candidate configuration is the config target.";
}
leaf running {
type empty;
description
"The running configuration is the config target.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
}
}
}
}
rpc unlock { choice config-target {
description mandatory true;
"The unlock operation is used to release a configuration lock, description
previously obtained with the 'lock' operation."; "The configuration target to unlock.";
reference "RFC XXXX, section 7.6."; leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config target.";
}
leaf running {
type empty;
description
"The running configuration is the config target.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
}
}
}
}
input { rpc get {
container target { description
description "Retrieve running configuration and device state information.";
"Particular configuration to unlock.";
choice config-target { reference "RFC 6241, Section 7.7";
mandatory true;
description
"The configuration target to unlock.";
leaf candidate { input {
if-feature candidate; anyxml filter {
type empty; description
description "This parameter specifies the portion of the system
"The candidate configuration is the config target."; configuration and state data to retrieve.";
} nc:get-filter-element-attributes;
leaf running { }
type empty; }
description
"The running configuration is the config target.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
}
}
}
}
rpc get { output {
description anyxml data {
"Retrieve running configuration and device state information."; description
"Copy of the running datastore subset and/or state
data that matched the filter criteria (if any).
An empty data container indicates that the request did not
produce any results.";
}
reference "RFC XXXX, section 7.7."; }
}
input { rpc close-session {
anyxml filter { description
description "Request graceful termination of a NETCONF session.";
"This parameter specifies the portion of the system
configuration and state data to retrieve.";
nc:get-filter-element-attributes;
}
}
output { reference "RFC 6241, Section 7.8";
anyxml data { }
description
"Copy of the running datastore subset and/or state
data which matched the filter criteria (if any).
An empty data container indicates that the request did not
produce any results.";
}
}
}
rpc close-session { rpc kill-session {
description description
"Request graceful termination of a NETCONF session."; "Force the termination of a NETCONF session.";
reference "RFC XXXX, section 7.8."; reference "RFC 6241, Section 7.9";
}
rpc kill-session { input {
description leaf session-id {
"Force the termination of a NETCONF session."; type session-id-type;
mandatory true;
description
"Particular session to kill.";
}
}
}
reference "RFC XXXX, section 7.9."; rpc commit {
if-feature candidate;
input { description
leaf session-id { "Commit the candidate configuration as the device's new
type session-id-type; current configuration.";
mandatory true;
description
"Particular session to kill.";
}
}
}
rpc commit { reference "RFC 6241, Section 8.3.4.1";
if-feature candidate;
description input {
"Commit the candidate configuration as the device's new leaf confirmed {
current configuration"; if-feature confirmed-commit;
type empty;
description
"Requests a confirmed commit.";
reference "RFC 6241, Section 8.3.4.1";
}
reference "RFC XXXX, section 8.3.4.1."; leaf confirm-timeout {
if-feature confirmed-commit;
type uint32 {
range "1..max";
input { }
leaf confirmed { units "seconds";
if-feature confirmed-commit; default "600"; // 10 minutes
type empty; description
description "The timeout interval for a confirmed commit.";
"Requests a confirmed commit."; reference "RFC 6241, Section 8.3.4.1";
reference "RFC XXXX, section 8.3.4.1."; }
}
leaf confirm-timeout { leaf persist {
if-feature confirmed-commit; if-feature confirmed-commit;
type uint32 { type string;
range "1..max"; description
} "This parameter is used to make a confirmed commit
units "seconds"; persistent. A persistent confirmed commit is not aborted
default "600"; // 10 minutes if the NETCONF session terminates. The only way to abort
description a persistent confirmed commit is to let the timer expire,
"The timeout interval for a confirmed commit."; or to use the <cancel-commit> operation.
reference "RFC XXXX, section 8.3.4.1.";
}
leaf persist { The value of this parameter is a token that must be given
if-feature confirmed-commit; in the 'persist-id' parameter of <commit> or
type string; <cancel-commit> operations in order to confirm or cancel
description the persistent confirmed commit.
"This parameter is used to make a confirmed commit
persistent. A persistent confirmed commit is not aborted
if the NETCONF session terminates. The only way to abort a
persistent confirmed commit it to let the timer expire, or
to use the cancel-commit operation.
The value of this parameter is a token that must be given The token should be a random string.";
in the 'persist-id' parameter of commit or cancel-commit in reference "RFC 6241, Section 8.3.4.1";
order to confirm or cancel the persistent confirmed commit. }
The token should be a random string."; leaf persist-id {
reference "RFC XXXX, section 8.3.4.1."; if-feature confirmed-commit;
} type string;
description
"This parameter is given in order to commit a persistent
confirmed commit. The value must be equal to the value
given in the 'persist' parameter to the <commit> operation.
If it does not match, the operation fails with an
'invalid-value' error.";
reference "RFC 6241, Section 8.3.4.1";
}
leaf persist-id { }
if-feature confirmed-commit; }
type string;
description
"This parameter is given in order to commit a persistent
confirmed commit. The value must be equal to the value
given in the 'persist' parameter to the commit operation.
If it does not match, the operation fails with an
'invalid-value' error.";
reference "RFC XXXX, section 8.3.4.1.";
}
} rpc discard-changes {
} if-feature candidate;
rpc discard-changes { description
if-feature candidate; "Revert the candidate configuration to the current
running configuration.";
description reference "RFC 6241, Section 8.3.4.2";
"Revert the candidate configuration to the current }
running configuration.";
reference "RFC XXXX, section 8.3.4.2."; rpc cancel-commit {
} if-feature confirmed-commit;
description
"This operation is used to cancel an ongoing confirmed commit.
If the confirmed commit is persistent, the parameter
'persist-id' must be given, and it must match the value of the
'persist' parameter.";
reference "RFC 6241, Section 8.4.4.1";
rpc cancel-commit { input {
if-feature confirmed-commit; leaf persist-id {
description type string;
"This operation is used to cancel an ongoing confirmed commit. description
If the confirmed commit is persistent, the parameter "This parameter is given in order to cancel a persistent
'persist-id' must be given, and it must match the value of the confirmed commit. The value must be equal to the value
'persist' parameter."; given in the 'persist' parameter to the <commit> operation.
reference "RFC XXXX, section 8.4.4.1."; If it does not match, the operation fails with an
'invalid-value' error.";
}
}
}
input { rpc validate {
leaf persist-id { if-feature validate;
type string;
description
"This parameter is given in order to cancel a persistent
confirmed commit. The value must be equal to the value
given in the 'persist' parameter to the commit operation.
If it does not match, the operation fails with an
'invalid-value' error.";
}
}
}
rpc validate { description
if-feature validate; "Validates the contents of the specified configuration.";
description reference "RFC 6241, Section 8.6.4.1";
"Validates the contents of the specified configuration.";
reference "RFC XXXX, section 8.6.4.1."; input {
container source {
description
"Particular configuration to validate.";
input { choice config-source {
container source { mandatory true;
description description
"Particular configuration to validate."; "The configuration source to validate.";
choice config-source { leaf candidate {
mandatory true; if-feature candidate;
description type empty;
"The configuration source to validate."; description
"The candidate configuration is the config source.";
leaf candidate { }
if-feature candidate; leaf running {
type empty; type empty;
description description
"The candidate configuration is the config source."; "The running configuration is the config source.";
} }
leaf running { leaf startup {
type empty; if-feature startup;
description type empty;
"The running configuration is the config source."; description
} "The startup configuration is the config source.";
leaf startup { }
if-feature startup; leaf url {
type empty; if-feature url;
description type inet:uri;
"The startup configuration is the config source."; description
} "The URL-based configuration is the config source.";
leaf url { }
if-feature url; anyxml config {
type inet:uri; description
description "Inline Config content: <config> element. Represents
"The URL-based configuration is the config source."; an entire configuration datastore, not
} a subset of the running datastore.";
anyxml config { }
description }
"Inline Config content: 'config' element. Represents }
an entire configuration datastore, not }
a subset of the running datastore."; }
}
}
}
}
}
} }
<CODE ENDS> <CODE ENDS>
Appendix D. Capability Template Appendix D. Capability Template
This non-normative section defines a template that can be used to This non-normative section defines a template that can be used to
define protocol capabilities. Data models written in YANG usually do define protocol capabilities. Data models written in YANG usually do
not need to define protocol capabilities since the usage of YANG not need to define protocol capabilities since the usage of YANG
automatically leads to a capability announcing the data model and any automatically leads to a capability announcing the data model and any
optional portions of the data model, so called features in YANG optional portions of the data model, so called features in YANG
terminology. The capabilities template is intended to be used in terminology. The capabilities template is intended to be used in
cases where the YANG mechanisms are not powerful enough (e.g., for cases where the YANG mechanisms are not powerful enough (e.g., for
handling parametrized features) or a different data modeling language handling parameterized features) or a different data modeling
is used. language is used.
D.1. capability-name (template) D.1. capability-name (template)
D.1.1. Overview D.1.1. Overview
D.1.2. Dependencies D.1.2. Dependencies
D.1.3. Capability Identifier D.1.3. Capability Identifier
The {name} capability is identified by the following capability The {name} capability is identified by the following capability
skipping to change at page 116, line 5 skipping to change at page 108, line 5
</target> </target>
<source> <source>
<running/> <running/>
</source> </source>
</copy-config> </copy-config>
</rpc> </rpc>
To restore the checkpoint file, reverse the <source> and <target> To restore the checkpoint file, reverse the <source> and <target>
parameters. parameters.
E.1.3. Loading and Validating the Incoming Configuration. E.1.3. Loading and Validating the Incoming Configuration
If the :candidate capability is supported, the configuration can be If the :candidate capability is supported, the configuration can be
loaded onto the device without impacting the running system. loaded onto the device without impacting the running system.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config> <edit-config>
<target> <target>
<candidate/> <candidate/>
</target> </target>
skipping to change at page 119, line 34 skipping to change at page 111, line 34
The second class is more interesting, requiring that the operation The second class is more interesting, requiring that the operation
should complete on all devices or be fully reversed. The network should complete on all devices or be fully reversed. The network
should either be transformed into a new state or be reset to its should either be transformed into a new state or be reset to its
original state. For example, a change to a VPN may require updates original state. For example, a change to a VPN may require updates
to a number of devices. Another example of this might be adding a to a number of devices. Another example of this might be adding a
class-of-service definition. Leaving the network in a state where class-of-service definition. Leaving the network in a state where
only a portion of the devices have been updated with the new only a portion of the devices have been updated with the new
definition will lead to future failures when the definition is definition will lead to future failures when the definition is
referenced. referenced.
To give transactional semantics, the same steps used in single device To give transactional semantics, the same steps used in single-device
operations listed above are used, but are performed in parallel operations listed above are used, but are performed in parallel
across all devices. Configuration locks should be acquired on all across all devices. Configuration locks should be acquired on all
target devices and kept until all devices are updated and the changes target devices and kept until all devices are updated and the changes
made permanent. Configuration changes should be uploaded and made permanent. Configuration changes should be uploaded and
validation performed across all devices. Checkpoints should be made validation performed across all devices. Checkpoints should be made
on each device. Then the running configuration can be changed, on each device. Then the running configuration can be changed,
tested, and made permanent. If any of these steps fail, the previous tested, and made permanent. If any of these steps fail, the previous
configurations can be restored on any devices upon which they were configurations can be restored on any devices upon which they were
changed. After the changes have been completely implemented or changed. After the changes have been completely implemented or
completely discarded, the locks on each device can be released. completely discarded, the locks on each device can be released.
skipping to change at page 121, line 10 skipping to change at page 113, line 10
o Added a <cancel-commit> operation. o Added a <cancel-commit> operation.
o Introduced a NETCONF username and a requirement for transport o Introduced a NETCONF username and a requirement for transport
protocols to explain how a username is derived. protocols to explain how a username is derived.
Authors' Addresses Authors' Addresses
Rob Enns (editor) Rob Enns (editor)
Juniper Networks Juniper Networks
Email: rob.enns@gmail.com EMail: rob.enns@gmail.com
Martin Bjorklund (editor) Martin Bjorklund (editor)
Tail-f Systems Tail-f Systems
Email: mbj@tail-f.com EMail: mbj@tail-f.com
Juergen Schoenwaelder (editor) Juergen Schoenwaelder (editor)
Jacobs University Jacobs University
Email: j.schoenwaelder@jacobs-university.de EMail: j.schoenwaelder@jacobs-university.de
Andy Bierman (editor) Andy Bierman (editor)
Brocade Brocade
Email: andy.bierman@brocade.com EMail: andy.bierman@brocade.com
 End of changes. 303 change blocks. 
1498 lines changed or deleted 1405 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/