draft-ietf-netconf-4741bis-02.txt   draft-ietf-netconf-4741bis-03.txt 
Network Working Group R. Enns, Ed. Network Working Group R. Enns, Ed.
Internet-Draft Juniper Networks Internet-Draft Juniper Networks
Intended status: Standards Track M. Bjorklund, Ed. Intended status: Standards Track M. Bjorklund, Ed.
Expires: August 8, 2010 Tail-f Systems Expires: January 13, 2011 Tail-f Systems
J. Schoenwaelder, Ed. J. Schoenwaelder, Ed.
Jacobs University Jacobs University
A. Bierman, Ed. A. Bierman, Ed.
InterWorking Labs InterWorking Labs
February 4, 2010 July 12, 2010
Network Configuration Protocol (NETCONF) Network Configuration Protocol (NETCONF)
draft-ietf-netconf-4741bis-02 draft-ietf-netconf-4741bis-03
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). realized as Remote Procedure Calls (RPC).
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF). Note that other groups may also distribute
other groups may also distribute working documents as Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at This Internet-Draft will expire on January 13, 2011.
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 8, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
skipping to change at page 2, line 15 skipping to change at page 2, line 9
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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the BSD License. described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this 10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process. modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format not be created outside the IETF Standards Process, except to format
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. Protocol Overview . . . . . . . . . . . . . . . . . . . . 7 1.1. Protocol Overview . . . . . . . . . . . . . . . . . . . . 7
1.2. Capabilities . . . . . . . . . . . . . . . . . . . . . . 8 1.2. Capabilities . . . . . . . . . . . . . . . . . . . . . . 8
1.3. Separation of Configuration and State Data . . . . . . . 8 1.3. Separation of Configuration and State Data . . . . . . . 9
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 10 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 10
2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 10 2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 10
2.2. Authentication, Integrity, and Confidentiality . . . . . 10 2.2. Authentication, Integrity, and Confidentiality . . . . . 10
2.3. Authentication . . . . . . . . . . . . . . . . . . . . . 11 2.3. Authentication . . . . . . . . . . . . . . . . . . . . . 11
2.4. Mandatory Transport Protocol . . . . . . . . . . . . . . 11 2.4. Mandatory Transport Protocol . . . . . . . . . . . . . . 11
3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 12 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 12
3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 12 3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2. No Document Type Declarations . . . . . . . . . . . . . . 12 3.2. No Document Type Declarations . . . . . . . . . . . . . . 12
4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 13 4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 13
4.2. <rpc-reply> Element . . . . . . . . . . . . . . . . . . . 14 4.2. <rpc-reply> Element . . . . . . . . . . . . . . . . . . . 14
4.3. <rpc-error> Element . . . . . . . . . . . . . . . . . . . 15 4.3. <rpc-error> Element . . . . . . . . . . . . . . . . . . . 15
4.4. <ok> Element . . . . . . . . . . . . . . . . . . . . . . 18 4.4. <ok> Element . . . . . . . . . . . . . . . . . . . . . . 18
4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 18 4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 19
5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 19 5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 20
5.1. Configuration Datastores . . . . . . . . . . . . . . . . 19 5.1. Configuration Datastores . . . . . . . . . . . . . . . . 20
5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 19 5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 20
6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 20 6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 21
6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 20 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 21
6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 21 6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 22
6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 21 6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 22
6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 21 6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 22
6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 22 6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 23
6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 22 6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 23
6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 23 6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 24
6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 24 6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 26
6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 25 6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 26
6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 25 6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 26
6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 26 6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 27
6.4.3. Select the Entire <users> Subtree . . . . . . . . . . 26 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 . . . . . . . . . . . . . . . . . . . . . . . 28 Subtree . . . . . . . . . . . . . . . . . . . . . . . 29
6.4.5. One Specific <user> Entry . . . . . . . . . . . . . . 29 6.4.5. One Specific <user> Entry . . . . . . . . . . . . . . 30
6.4.6. Specific Elements from a Specific <user> Entry . . . 30 6.4.6. Specific Elements from a Specific <user> Entry . . . 31
6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 31 6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 32
6.4.8. Elements with Attribute Naming . . . . . . . . . . . 33 6.4.8. Elements with Attribute Naming . . . . . . . . . . . 34
7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 35 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 36
7.1. <get-config> . . . . . . . . . . . . . . . . . . . . . . 35 7.1. <get-config> . . . . . . . . . . . . . . . . . . . . . . 36
7.2. <edit-config> . . . . . . . . . . . . . . . . . . . . . . 38 7.2. <edit-config> . . . . . . . . . . . . . . . . . . . . . . 38
7.3. <copy-config> . . . . . . . . . . . . . . . . . . . . . . 45 7.3. <copy-config> . . . . . . . . . . . . . . . . . . . . . . 45
7.4. <delete-config> . . . . . . . . . . . . . . . . . . . . . 47 7.4. <delete-config> . . . . . . . . . . . . . . . . . . . . . 47
7.5. <lock> . . . . . . . . . . . . . . . . . . . . . . . . . 47 7.5. <lock> . . . . . . . . . . . . . . . . . . . . . . . . . 47
7.6. <unlock> . . . . . . . . . . . . . . . . . . . . . . . . 50 7.6. <unlock> . . . . . . . . . . . . . . . . . . . . . . . . 50
7.7. <get> . . . . . . . . . . . . . . . . . . . . . . . . . . 51 7.7. <get> . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.8. <close-session> . . . . . . . . . . . . . . . . . . . . . 53 7.8. <close-session> . . . . . . . . . . . . . . . . . . . . . 53
7.9. <kill-session> . . . . . . . . . . . . . . . . . . . . . 54 7.9. <kill-session> . . . . . . . . . . . . . . . . . . . . . 54
8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 56 8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 56
8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 56 8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 56
8.2. Writable-Running Capability . . . . . . . . . . . . . . . 57 8.2. Writable-Running Capability . . . . . . . . . . . . . . . 57
8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 57 8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 57
8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 57 8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 57
8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 57 8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 57
8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 57 8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 58
8.2.5. Modifications to Existing Operations . . . . . . . . 57 8.2.5. Modifications to Existing Operations . . . . . . . . 58
8.3. Candidate Configuration Capability . . . . . . . . . . . 58 8.3. Candidate Configuration Capability . . . . . . . . . . . 58
8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 58 8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 58
8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 59 8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 59
8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 59 8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 59
8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 59 8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 59
8.3.5. Modifications to Existing Operations . . . . . . . . 60 8.3.5. Modifications to Existing Operations . . . . . . . . 60
8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 61 8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 61
8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 61 8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 61
8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 62 8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 63
8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 62 8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 63
8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 62 8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 63
8.4.5. Modifications to Existing Operations . . . . . . . . 62 8.4.5. Modifications to Existing Operations . . . . . . . . 64
8.5. Rollback on Error Capability . . . . . . . . . . . . . . 63 8.5. Rollback on Error Capability . . . . . . . . . . . . . . 66
8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 63 8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 66
8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 63 8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 67
8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 64 8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 67
8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 64 8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 67
8.5.5. Modifications to Existing Operations . . . . . . . . 64 8.5.5. Modifications to Existing Operations . . . . . . . . 67
8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 64 8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 68
8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 64 8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 68
8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65 8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 68
8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 65 8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 68
8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 65 8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 68
8.6.5. Modifications to Existing Operations . . . . . . . . 66 8.6.5. Modifications to Existing Operations . . . . . . . . 69
8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 66 8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 69
8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 66 8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 69
8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 67 8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 70
8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 67 8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 70
8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 67 8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 70
8.7.5. Modifications to Existing Operations . . . . . . . . 67 8.7.5. Modifications to Existing Operations . . . . . . . . 70
8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 68 8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 71
8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 68 8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 71
8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 68 8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 71
8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 68 8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 71
8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 68 8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 71
8.8.5. Modifications to Existing Operations . . . . . . . . 68 8.8.5. Modifications to Existing Operations . . . . . . . . 71
8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 69 8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 72
8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 69 8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 72
8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 70 8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 73
8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 70 8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 73
8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 70 8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 73
8.9.5. Modifications to Existing Operations . . . . . . . . 70 8.9.5. Modifications to Existing Operations . . . . . . . . 73
9. Security Considerations . . . . . . . . . . . . . . . . . . . 72 9. Security Considerations . . . . . . . . . . . . . . . . . . . 75
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77
10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 74 10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 77
10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 74 10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 77
10.3. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 74 10.3. NETCONF YANG Module . . . . . . . . . . . . . . . . . . . 77
11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 76 10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 77
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 79
12.1. Normative References . . . . . . . . . . . . . . . . . . 77 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 80
12.2. Informative References . . . . . . . . . . . . . . . . . 77 12.1. Normative References . . . . . . . . . . . . . . . . . . 80
Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 79 12.2. Informative References . . . . . . . . . . . . . . . . . 80
Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 83 Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 82
Appendix C. YANG Module for NETCONF Protocol Operations . . . . 88 Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 86
Appendix D. Capability Template . . . . . . . . . . . . . . . . 102 Appendix C. YANG Module for NETCONF Protocol Operations . . . . 91
D.1. capability-name (template) . . . . . . . . . . . . . . . 102 Appendix D. Capability Template . . . . . . . . . . . . . . . . 111
D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 102 D.1. capability-name (template) . . . . . . . . . . . . . . . 111
D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 102 D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 111
D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 102 D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 111
D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 102 D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 111
D.1.5. Modifications to Existing Operations . . . . . . . . 102 D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 111
D.1.6. Interactions with Other Capabilities . . . . . . . . 102 D.1.5. Modifications to Existing Operations . . . . . . . . 111
Appendix E. Configuring Multiple Devices with NETCONF . . . . . 103 D.1.6. Interactions with Other Capabilities . . . . . . . . 111
E.1. Operations on Individual Devices . . . . . . . . . . . . 103 Appendix E. Configuring Multiple Devices with NETCONF . . . . . 112
E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 103 E.1. Operations on Individual Devices . . . . . . . . . . . . 112
E.1.2. Loading the Update . . . . . . . . . . . . . . . . . 104 E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 112
E.1.3. Validating the Incoming Configuration . . . . . . . . 105 E.1.2. Checkpointing the Running Configuration . . . . . . . 113
E.1.4. Checkpointing the Running Configuration . . . . . . . 105 E.1.3. Loading and Validating the Incoming Configuration. . 114
E.1.5. Changing the Running Configuration . . . . . . . . . 106 E.1.4. Changing the Running Configuration . . . . . . . . . 114
E.1.6. Testing the New Configuration . . . . . . . . . . . . 107 E.1.5. Testing the New Configuration . . . . . . . . . . . . 115
E.1.7. Making the Change Permanent . . . . . . . . . . . . . 107 E.1.6. Making the Change Permanent . . . . . . . . . . . . . 115
E.1.8. Releasing the Configuration Lock . . . . . . . . . . 108 E.1.7. Releasing the Configuration Lock . . . . . . . . . . 116
E.2. Operations on Multiple Devices . . . . . . . . . . . . . 108 E.2. Operations on Multiple Devices . . . . . . . . . . . . . 117
Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 110 Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 118
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 119
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 6, line 41 skipping to change at page 6, line 41
adjust its behavior to take advantage of the features exposed by the adjust its behavior to take advantage of the features exposed by the
device. The capability definitions can be easily extended in a device. The capability definitions can be easily extended in a
noncentralized manner. Standard and non-standard capabilities can be noncentralized manner. Standard and non-standard capabilities can be
defined with semantic and syntactic rigor. Capabilities are defined with semantic and syntactic rigor. Capabilities are
discussed in Section 8. discussed in Section 8.
The NETCONF protocol is a building block in a system of automated The NETCONF protocol is a building block in a system of automated
configuration. XML is the lingua franca of interchange, providing a configuration. XML is the lingua franca of interchange, providing a
flexible but fully specified encoding mechanism for hierarchical flexible but fully specified encoding mechanism for hierarchical
content. NETCONF can be used in concert with XML-based content. NETCONF can be used in concert with XML-based
transformation technologies, such as XSLT [10], to provide a system transformation technologies, such as XSLT [11], to provide a system
for automated generation of full and partial configurations. The for automated generation of full and partial configurations. The
system can query one or more databases for data about networking system can query one or more databases for data about networking
topologies, links, policies, customers, and services. This data can topologies, links, policies, customers, and services. This data can
be transformed using one or more XSLT scripts from a task-oriented, be transformed using one or more XSLT scripts from a task-oriented,
vendor-independent data schema into a form that is specific to the vendor-independent data schema into a form that is specific to the
vendor, product, operating system, and software release. The vendor, product, operating system, and software release. The
resulting data can be passed to the device using the NETCONF resulting data can be passed to the device using the NETCONF
protocol. protocol.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
skipping to change at page 7, line 23 skipping to change at page 7, line 23
and "application". and "application".
A NETCONF session is the logical connection between a network A NETCONF session is the logical connection between a network
administrator or network configuration application and a network administrator or network configuration application and a network
device. A device MUST support at least one NETCONF session and device. A device MUST support at least one NETCONF session and
SHOULD support multiple sessions. Global configuration attributes SHOULD support multiple sessions. Global configuration attributes
can be changed during any authorized session, and the effects are can be changed during any authorized session, and the effects are
visible in all sessions. Session-specific attributes affect only the visible in all sessions. Session-specific attributes affect only the
session in which they are changed. session in which they are changed.
NETCONF can be conceptually partitioned into four layers: NETCONF can be conceptually partitioned into four layers as shown in
Figure 1.
Layer Example Layer Example
+-------------+ +-----------------+ +----------------+ +-------------+ +-----------------+ +----------------+
(4) | Content | | Configuration | | Notification | (4) | Content | | Configuration | | Notification |
| | | data | | data | | | | data | | data |
+-------------+ +-----------------+ +----------------+ +-------------+ +-----------------+ +----------------+
| | | | | |
+-------------+ +-----------------+ | +-------------+ +-----------------+ |
(3) | Operations | | <edit-config> | | (3) | Operations | | <edit-config> | |
| | | | | | | | | |
skipping to change at page 7, line 46 skipping to change at page 7, line 47
+-------------+ +-----------------+ +----------------+ +-------------+ +-----------------+ +----------------+
(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 | | | | Transports | | |
+-------------+ +-----------------------------------------+ +-------------+ +-----------------------------------------+
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 transport
protocol that provides a set of basic requirements. Section 2 protocol that provides a set of basic requirements. Section 2
discusses these requirements. 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. Section 4 documents this framing mechanism for encoding RPCs and notifications. Section 4
protocol. documents the RPCs, and [8] documents notifications.
3. The Operations layer defines a set of base operations invoked as 3. The Operations layer defines a set of base operations invoked as
RPC methods with XML-encoded parameters. Section 7 details the RPC methods with XML-encoded parameters. Section 7 details the
list of base operations. list of base operations.
4. The Content layer is outside the scope of this document. Given 4. The Content layer is outside the scope of this document. It is
the current proprietary nature of the configuration data being expected that separate efforts to standardize NETCONF data models
manipulated, the specification of this content depends on the
NETCONF implementation. It is expected that a separate effort to
specify a standard data definition language and standard content
will be undertaken. will be undertaken.
The YANG data modeling language [9] has been developed for specifying
NETCONF data models and operations, covering the Operations and the
Content layers of Figure 1.
1.2. Capabilities 1.2. 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). These URIs should follow the uniform resource identifier (URI). These URIs should follow the
guidelines as described in Section 8. guidelines as described in Section 8.
Capabilities augment the base operations of the device, describing Capabilities augment the base operations of the device, describing
both additional operations and the content allowed inside operations. both additional operations and the content allowed inside operations.
The client can discover the server's capabilities and use any The client can discover the server's capabilities and use any
skipping to change at page 9, line 33 skipping to change at page 9, line 39
operations for each. The <get-config> operation retrieves operations for each. The <get-config> operation retrieves
configuration data only, while the <get> operation retrieves configuration data only, while the <get> operation retrieves
configuration and state data. configuration and state data.
Note that the NETCONF protocol is focused on the information required Note that the NETCONF protocol is focused on the information required
to get the device into its desired running state. The inclusion of to get the device into its desired running state. The inclusion of
other important, persistent data is implementation specific. For other important, persistent data is implementation specific. For
example, user files and databases are not treated as configuration example, user files and databases are not treated as configuration
data by the NETCONF protocol. data by the NETCONF protocol.
If a local database of user authentication data is stored on the For example, if a local database of user authentication data is
device, whether it is included in configuration data is an stored on the device, it is an implementation-dependent matter
implementation-dependent matter. whether it is included in configuration data.
2. Transport Protocol Requirements 2. Transport Protocol Requirements
NETCONF uses an RPC-based communication paradigm. A client sends a NETCONF uses an RPC-based communication paradigm. A client sends a
series of one or more RPC request operations, which cause the server series of one or more RPC request operations, which cause the server
to respond with a corresponding series of RPC replies. to respond with a corresponding series of RPC replies.
The NETCONF protocol can be layered on any transport protocol that The NETCONF protocol can be layered on any transport protocol that
provides the required set of functionality. It is not bound to any provides the required set of functionality. It is not bound to any
particular transport protocol, but allows a mapping to define how it particular transport protocol, but allows a mapping to define how it
skipping to change at page 10, line 45 skipping to change at page 10, line 45
connection MUST be automatically released when the connection closes, connection MUST be automatically released when the connection closes,
making failure recovery simpler and more robust. For example, when a making failure recovery simpler and more robust. For example, when a
lock is acquired by a client, the lock persists until either it is lock is acquired by a client, the lock persists until either it is
explicitly released or the server determines that the connection has explicitly released or the server determines that the connection has
been terminated. If a connection is terminated while the client been terminated. If a connection is terminated while the client
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, and NETCONF connections must provide authentication, data integrity,
confidentiality. NETCONF depends on the transport protocol for this confidentiality, and replay protection. NETCONF depends on the
capability. A NETCONF peer assumes that appropriate levels of transport protocol for this capability. A NETCONF peer assumes that
security and confidentiality are provided independently of this appropriate levels of security and confidentiality are provided
document. For example, connections may be encrypted in TLS [11] or independently of this document. For example, connections may be
SSH [12], depending on the underlying protocol. encrypted in TLS [15] or SSH [14], depending on the underlying
protocol.
2.3. Authentication 2.3. Authentication
NETCONF connections must be authenticated. The transport protocol is NETCONF connections must be authenticated. The transport protocol is
responsible for authentication. The peer assumes that the responsible for authentication of the server to the client and
connection's authentication information has been validated by the authentication of the client to the server. A NETCONF peer assumes
underlying protocol using sufficiently trustworthy mechanisms and that the connection's authentication information has been validated
that the peer's identity has been sufficiently proven. by the underlying transport protocol using sufficiently trustworthy
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 defined by the device. For uses existing authentication mechanisms available on the device. For
example, a device that supports RADIUS [13] should allow the use of example, a NETCONF server on a device that supports RADIUS [12]
RADIUS to authenticate NETCONF sessions. should allow the use of RADIUS to authenticate NETCONF sessions.
The authentication process should result in an identity whose The authentication process MUST result in an authenticated client
permissions are known to the device. These permissions MUST be identity whose permissions are known to the server. The
enforced during the remainder of the NETCONF session. authenticated identity of a client is commonly referred to as the
NETCONF username. The algorithm used to derive the username is
transport protocol specific and in addition specific to the
authentication mechanism used by the transport protocol. NETCONF
transport protocols therefore MUST explain how a NETCONF username is
derived from the authentication mechanisms supported by the transport
protocol.
The access permissions of a given client, identified by its NETCONF
username, are part of the configuration of the NETCONF server. These
permissions MUST be enforced during the remainder of the NETCONF
session. The details how access control is configured is outside the
scope of this document.
2.4. Mandatory Transport Protocol 2.4. Mandatory Transport Protocol
A NETCONF implementation MUST support the SSH transport protocol A NETCONF implementation MUST support the SSH transport protocol
mapping [4]. mapping [4].
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,
skipping to change at page 14, line 31 skipping to change at page 14, line 31
</rpc> </rpc>
4.2. <rpc-reply> Element 4.2. <rpc-reply> Element
The <rpc-reply> message is sent in response to an <rpc> operation. The <rpc-reply> message is sent in response to an <rpc> operation.
The <rpc-reply> element has a mandatory attribute "message-id", which The <rpc-reply> element has a mandatory attribute "message-id", which
is equal to the "message-id" attribute of the <rpc> for which this is is equal to the "message-id" attribute of the <rpc> for which this is
a response. a response.
A NETCONF peer MUST also return any additional attributes included in A NETCONF server MUST also return any additional attributes included
the <rpc> element unmodified in the <rpc-reply> element. in the <rpc> element unmodified in the <rpc-reply> element.
The response data is encoded as one or more child elements to the The response data is encoded as one or more child elements to the
<rpc-reply> element. <rpc-reply> element.
For example: For example:
The following <rpc> element invokes the NETCONF <get> method and The following <rpc> element invokes the NETCONF <get> method and
includes an additional attribute called "user-id". Note that the includes an additional attribute called "user-id". Note that the
"user-id" attribute is not in the NETCONF namespace. The returned "user-id" attribute is not in the NETCONF namespace. The returned
<rpc-reply> element returns the "user-id" attribute, as well as the <rpc-reply> element returns the "user-id" attribute, as well as the
skipping to change at page 16, line 16 skipping to change at page 16, line 16
error-tag: Contains a string identifying the error condition. See error-tag: Contains a string identifying the error condition. See
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
which utilize the "warning" enumeration. This is reserved for
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. tag can be associated with a particular error condition. If a
data-model specific and a implementation-specific error-app-tag
both exist, then the data-model specific value MUST be used by the
server.
error-path: Contains the absolute XPath [2] expression identifying error-path: Contains the absolute XPath [2] expression identifying
the element path to the node that is associated with the error the element path to the node that is associated with the error
being reported in a particular rpc-error element. This element being reported in a particular rpc-error element. This element
will not be present if no appropriate payload element or data will not be present if no appropriate payload element or data
store node can be associated with a particular error condition. store node can be associated with a particular error condition.
The XPath expression is interpreted in the following context: The XPath expression is interpreted in the following context:
* The set of namespace declarations are those in scope on the * The set of namespace declarations are those in scope on the
rpc-error element. rpc-error element.
* The set of variable bindings is empty. * The set of variable bindings is empty.
* 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 "rpc" context node is the rpc request's document node (i.e., the
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 which 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 [1] and discussed in [14]. defined in [1] and discussed in [13].
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.
skipping to change at page 20, line 26 skipping to change at page 21, line 26
centralized implementation strategies. centralized implementation strategies.
Conceptually, a subtree filter is comprised of zero or more element Conceptually, a subtree filter is comprised of zero or more element
subtrees, which represent the filter selection criteria. At each subtrees, which represent the filter selection criteria. At each
containment level within a subtree, the set of sibling nodes is containment level within a subtree, the set of sibling nodes is
logically processed by the server to determine if its subtree and logically processed by the server to determine if its subtree and
path of elements to the root are included in the filter output. path of elements to the root are included in the filter output.
All elements present in a particular subtree within a filter must All elements present in a particular subtree within a filter must
match associated nodes present in the server's conceptual data model. match associated nodes present in the server's conceptual data model.
XML namespaces may be specified (via 'xmlns' declarations) within the XML namespaces MAY be specified (via 'xmlns' attributes) within the
filter data model. If they are, the declared namespace must first NETCONF message. If they are specified, the declared namespace MUST
exactly match a namespace supported by the server. Note that prefix exactly match a namespace supported by the server, with one
values for qualified namespaces are not relevant when comparing exception. A namespace wildcard mechanism is defined in
filter elements to elements in the underlying data model. Only data Section 6.2.1.
associated with a specified namespace will be included in the filter
output. Note that prefix values for qualified namespaces are not relevant
when comparing filter elements to elements in the underlying data
model.
Each node specified in a subtree filter represents an inclusive Each node specified in a subtree filter represents an inclusive
filter. Only associated nodes in underlying data model(s) within the filter. Only associated nodes in underlying data model(s) within the
specified configuration datastore on the server are selected by the specified configuration datastore on the server are selected by the
filter. A node must exactly match the namespace and hierarchy of filter. A node must exactly match the namespace and hierarchy of
elements given in the filter data, except that the filter absolute elements given in the filter data, except that the filter absolute
path name is adjusted to start from the layer below <filter>. path name is adjusted to start from the layer below <filter>.
Response messages contain only the subtrees selected by the filter. Response messages contain only the subtrees selected by the filter.
Any selection criteria that were present in the request, within a Any selection criteria that were present in the request, within a
skipping to change at page 21, line 25 skipping to change at page 22, line 25
o Containment Nodes o Containment Nodes
o Selection Nodes o Selection Nodes
o Content Match Nodes o Content Match Nodes
6.2.1. Namespace Selection 6.2.1. Namespace Selection
If namespaces are used, then the filter output will only include If namespaces are used, then the filter output will only include
elements from the specified namespace. A namespace is considered to elements from the specified namespace. A namespace is considered to
match (for filter purposes) if the content of the 'xmlns' attributes match (for filter purposes) if the XML namespace associated with a
are the same in the filter and the underlying data model. Note that particular node within the <filter> element is the same as in the
namespace selection cannot be used by itself. At least one element underlying data model. Note that namespace selection cannot be used
must be specified in the filter any elements to be included in the by itself. At least one element must be specified in the filter any
filter output. elements to be included in the filter output.
An XML namespace wildcard mechanism is defined for subtree filtering.
If an element within the <filter> element is not qualified by a
namespace (e.g., xmlns=""), then the server MUST evaluate all the XML
namespaces it supports, when processing that subtree filter node.
This wildcard mechanism is not applicable to XML attributes.
Example: Example:
<filter type="subtree"> <filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config"/> <top xmlns="http://example.com/schema/1.2/config"/>
</filter> </filter>
In this example, the <top> element is a selection node, and only this In this example, the <top> element is a selection node, and only this
node and any child nodes (from the underlying data model) in the node in the 'http://example.com/schema/1.2/config' namespace and any
'http://example.com/schema/1.2/config' namespace will be included in child nodes (from the underlying data model) will be included in the
the filter output. filter output.
6.2.2. Attribute Match Expressions 6.2.2. Attribute Match Expressions
An attribute that appears in a subtree filter is part of an An attribute that appears in a subtree filter is part of an
"attribute match expression". Any number of (unqualified or "attribute match expression". Any number of (unqualified or
qualified) XML attributes may be present in any type of filter node. qualified) XML attributes may be present in any type of filter node.
In addition to the selection criteria normally applicable to that In addition to the selection criteria normally applicable to that
node, the selected data must have matching values for every attribute node, the selected data must have matching values for every attribute
specified in the node. If an element is not defined to include a specified in the node. If an element is not defined to include a
specified attribute, then it is not selected in the filter output. specified attribute, then it is not selected in the filter output.
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>
skipping to change at page 37, line 39 skipping to change at page 38, line 39
<dept>1</dept> <dept>1</dept>
<id>1</id> <id>1</id>
</company-info> </company-info>
</user> </user>
<!-- additional <user> elements appear here... --> <!-- additional <user> elements appear here... -->
</users> </users>
</top> </top>
</data> </data>
</rpc-reply> </rpc-reply>
If the configuration is available in multiple formats, such as XML
and text, an XML namespace can be used to specify which format is
desired. In the following example, the client uses a specific
element (<config-text>) in a specific namespace to indicate to the
server the desire to receive the configuration in an alternative
format. The server may support any number of distinct formats or
views into the configuration data, with the client using the
<filter> parameter to select between them.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<!-- request a text version of the configuration -->
<config-text xmlns="http://example.com/text/1.2/config"/>
</filter>
</get-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<config-text xmlns="http://example.com/text/1.2/config">
<!-- configuration text... -->
</config-text>
</data>
</rpc-reply>
Section 6 contains additional examples of subtree filtering. Section 6 contains additional examples of subtree filtering.
7.2. <edit-config> 7.2. <edit-config>
Description: Description:
The <edit-config> operation loads all or part of a specified The <edit-config> operation loads all or part of a specified
configuration to the specified target configuration. This configuration to the specified target configuration. This
operation allows the new configuration to be expressed in several operation allows the new configuration to be expressed in several
ways, such as using a local file, a remote file, or inline. If ways, such as using a local file, a remote file, or inline. If
skipping to change at page 39, line 39 skipping to change at page 39, line 50
configuration datastore, it is created. Unlike a configuration datastore, it is created. Unlike a
<copy-config> operation, which replaces the entire target <copy-config> operation, which replaces the entire target
configuration, only the configuration actually present in configuration, only the configuration actually present in
the config parameter is affected. the config parameter is affected.
create: The configuration data identified by the element create: The configuration data identified by the element
containing this attribute is added to the configuration if containing this attribute is added to the configuration if
and only if the configuration data does not already exist in and only if the configuration data does not already exist in
the configuration datastore. If the configuration data the configuration datastore. If the configuration data
exists, an <rpc-error> element is returned with an exists, an <rpc-error> element is returned with an
<error-tag> value of data-exists. <error-tag> value of "data-exists".
delete: The configuration data identified by the element delete: The configuration data identified by the element
containing this attribute is deleted in the configuration containing this attribute is deleted from the configuration
datastore identified by the target parameter. 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".
remove: 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.
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:
skipping to change at page 40, line 37 skipping to change at page 41, line 9
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 The test-option element may be specified only if the device
advertises the :validate capability (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
skipping to change at page 46, line 7 skipping to change at page 46, line 7
<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 Name of the configuration datastore to use as the destination
of the copy operation. of the copy operation.
source: source:
skipping to change at page 56, line 23 skipping to change at page 56, line 23
Additional capabilities can be defined using the template in Additional capabilities can be defined using the template in
Appendix D. Future capability definitions may be published as Appendix D. Future capability definitions may be published as
standards by standards bodies or published as proprietary extensions. standards by standards bodies or published as proprietary extensions.
A NETCONF capability is identified with a URI. The base capabilities A NETCONF capability is identified with a URI. The base capabilities
are defined using URNs following the method described in RFC 3553 are defined using URNs following the method described in RFC 3553
[6]. Capabilities defined in this document have the following [6]. Capabilities defined in this document have the following
format: format:
urn:ietf:params:netconf:capability:{name}:1.0 urn:ietf:params:netconf:capability:{name}:1.x
where {name} is the name of the capability. Capabilities are often where {name} is the name of the capability. Capabilities are often
referenced in discussions and email using the shorthand :{name}. For referenced in discussions and email using the shorthand :{name}, or
:{name}:{version} if the capability exists in multiple versions. For
example, the foo capability would have the formal name example, the foo capability would have the formal name
"urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo". "urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo".
The shorthand form MUST NOT be used inside the protocol. The shorthand form MUST NOT be used inside the protocol.
8.1. Capabilities Exchange 8.1. Capabilities Exchange
Capabilities are advertised in messages sent by each peer during Capabilities are advertised in messages sent by each peer during
session establishment. When the NETCONF session is opened, each peer session establishment. When the NETCONF session is opened, each peer
(both client and server) MUST send a <hello> element containing a (both client and server) MUST send a <hello> element containing a
list of that peer's capabilities. Each peer MUST send at least the list of that peer's capabilities. Each peer MUST send at least the
base NETCONF capability, "urn:ietf:params:netconf:base:1.0". base NETCONF capability, "urn:ietf:params:netconf:base:1.1". A peer
MAY include capabilities for previous NETCONF versions, to indicate
that it supports multiple protocol versions.
Both NETCONF peers MUST verify that the other peer has advertised a
common protocol version. When comparing protocol version capability
URIs, only the base part is used, in the event any parameters are
encoded at the end of the URI string. If no protocol version
capability in common is found, the NETCONF peer MUST NOT continue the
session. If more than one protocol version URI in common is present,
then the highest numbered (most recent) protocol version MUST be used
by both peers.
A server sending the <hello> element MUST include a <session-id> A server sending the <hello> element MUST include a <session-id>
element containing the session ID for this NETCONF session. A client element containing the session ID for this NETCONF session. A client
sending the <hello> element MUST NOT include a <session-id> element. sending the <hello> element MUST NOT include a <session-id> element.
A server receiving a <session-id> element MUST NOT continue the A server receiving a <session-id> element MUST NOT continue the
NETCONF session. Similarly, a client that does not receive a NETCONF session. Similarly, a client that does not receive a
<session-id> element in the server's <hello> message MUST NOT <session-id> element in the server's <hello> message MUST NOT
continue the NETCONF session. In both cases, the underlying continue the NETCONF session. In both cases, the underlying
transport should be closed. transport should be closed.
In the following example, a server advertises the base NETCONF In the following example, a server advertises the base NETCONF
capability, one NETCONF capability defined in the base NETCONF capability, one NETCONF capability defined in the base NETCONF
document, and one implementation-specific capability. document, and one implementation-specific capability.
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities> <capabilities>
<capability> <capability>
urn:ietf:params:netconf:base:1.0 urn:ietf:params:netconf:base:1.1
</capability> </capability>
<capability> <capability>
urn:ietf:params:netconf:capability:startup:1.0 urn:ietf:params:netconf:capability:startup:1.0
</capability> </capability>
<capability> <capability>
http://example.net/router/2.3/myfeature http://example.net/router/2.3/myfeature
</capability> </capability>
</capabilities> </capabilities>
<session-id>4</session-id> <session-id>4</session-id>
</hello> </hello>
skipping to change at page 58, line 37 skipping to change at page 58, line 46
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 capability (Section 8.4) would make no sense as the :confirmed-commit:1.1 capability (Section 8.4) would make no
a "copy confirmed" operation. sense as a "copy confirmed" operation.
The candidate configuration may be shared among multiple sessions. The candidate configuration may 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 may configuration is not shared, it must assume that other sessions may
be able to modify the candidate configuration at the same time. It be able to modify the candidate configuration at the same time. It
is therefore prudent for a client to lock the candidate configuration is therefore prudent for a client to lock the candidate configuration
before modifying it. before modifying it.
The client can discard any uncommitted changes to the candidate The client can discard any uncommitted changes to the candidate
configuration by executing the <discard-changes> operation. This configuration by executing the <discard-changes> operation. This
skipping to change at page 59, line 39 skipping to change at page 59, line 46
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
candidate configuration datastore, then the running candidate configuration datastore, then the running
configuration MUST remain unchanged. If the device does configuration MUST remain unchanged. If the device does
succeed in committing, the running configuration MUST be succeed in committing, the running configuration MUST be
updated with the contents of the candidate configuration. updated with the contents of the candidate configuration.
If the running or candidate configuration is currently locked If the running or candidate configuration is currently locked
by a different session, the <commit> operation, MUST fail with by a different session, the <commit> operation MUST fail with
an <error-tag> value of 'in-use'. an <error-tag> value of 'in-use'.
If the system does not have the :candidate capability, the If the system does not have the :candidate capability, the
<commit> operation is not available. <commit> operation is not available.
Positive Response: Positive Response:
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.
skipping to change at page 61, line 43 skipping to change at page 61, line 50
When a client fails with outstanding changes to the candidate When a client fails with outstanding changes to the candidate
configuration, recovery can be difficult. To facilitate easy configuration, recovery can be difficult. To facilitate easy
recovery, any outstanding changes are discarded when the lock is recovery, any outstanding changes are discarded when the lock is
released, whether explicitly with the <unlock> operation or released, whether explicitly with the <unlock> operation or
implicitly from session failure. implicitly from session failure.
8.4. Confirmed Commit Capability 8.4. Confirmed Commit Capability
8.4.1. Description 8.4.1. Description
The :confirmed-commit capability indicates that the server will The :confirmed-commit:1.1 capability indicates that the server will
support the <confirmed> and <confirm-timeout> parameters for the support the <cancel-commit> operation and the <confirmed>,
<commit> protocol operation. See Section 8.3 for further details on <confirm-timeout>, <persist>, and <persist-id> parameters for the
the <commit> operation. <commit> operation. See Section 8.3 for further details on the
<commit> operation.
A confirmed commit operation MUST be reverted if a follow-up commit A confirmed commit operation MUST be reverted if a confirming commit
(called the "confirming commit") is not issued within 600 seconds (10 is not issued within 600 seconds (10 minutes). The confirming commit
minutes). The timeout period can be adjusted with the is a commit operation without the <confirmed> parameter. The timeout
<confirm-timeout> element. The confirming commit can itself include period can be adjusted with the <confirm-timeout> parameter. If a
a <confirmed> parameter. follow-up confirmed commit operation is issued before the timer
expires, the timer is reset to the new value (600 seconds by
default). Both the confirming commit and a follow-up confirmed
commit operation MAY introduce additional changes to the
configuration,
If the <persist> element is not given in the confirmed commit
operation, any follow-up commit and the confirming commit MUST be
issued on the same session that issued the confirmed commit. If the
<persist> element is given in the confirmed commit operation, a
follow-up commit and the confirming commit can be given on any
session, and they MUST include a <persist-id> element with a value
equal to the given value of the <persist> element.
If the server also advertises the :startup capability, a
<copy-config> from running to startup is also necessary to save the
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
the configuration to its state before the confirmed commit was the configuration to its state before the confirmed commit was
issued. issued, unless the confirmed commit also included a <persist>
element.
If the device reboots for any reason before the confirm timeout If the device reboots for any reason before the confirm timeout
expires, the server MUST restore the configuration to its state expires, the server MUST restore the configuration to its state
before the confirmed commit was issued. before the confirmed commit was issued.
If a confirming commit is not issued, the device will revert its If a confirming commit is not issued, the device will revert its
configuration to the state prior to the issuance of the confirmed configuration to the state prior to the issuance of the confirmed
commit. Note that any commit operation, including a commit which commit. To cancel a confirmed commit and revert changes without
introduces additional changes to the configuration, will serve as a waiting for the confirm timeout to expire, the client can explicitly
confirming commit. Thus to cancel a confirmed commit and revert restore the configuration to its state before the confirmed commit
changes without waiting for the confirm timeout to expire, the client was issued, by using the <cancel-commit> operation.
can explicitly restore the configuration to its state before the
confirmed commit was issued.
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 databases, order to use this feature with shared configuration databases,
configuration locking should also be used. configuration locking should also be used.
Version 1.0 of this capability was defined in [16]. The current
version is 1.1, and is defined in this document. It extends version
1.0 by adding a new operation, <cancel-commit>, and two new optional
parameters, <persist> and <persist-id>. For backwards compatibility
with old clients, servers confirming to this specification MAY
advertise version 1.0 in addition to version 1.1.
8.4.2. Dependencies 8.4.2. Dependencies
The :confirmed-commit capability is only relevant if the :candidate The :confirmed-commit:1.1 capability is only relevant if the
capability is also supported. :candidate capability is also supported.
8.4.3. Capability Identifier 8.4.3. Capability Identifier
The :confirmed-commit capability is identified by the following The :confirmed-commit:1.1 capability is identified by the following
capability string: capability string:
urn:ietf:params:netconf:capability:confirmed-commit:1.0 urn:ietf:params:netconf:capability:confirmed-commit:1.1
8.4.4. New Operations 8.4.4. New Operations
None. 8.4.4.1. <cancel-commit>
Description:
Cancels an ongoing confirmed commit. If the <persist-id>
parameter is not given, the <cancel-commit> operation MUST be
issued on the same session that issued the confirmed commit.
Parameters:
persist-id:
Cancels a persistent confirmed commit. The value MUST be
equal to the value given in the <persist> parameter to the
commit operation. If the value does not match, the
operation fails with an "invalid-value" error.
Positive Response:
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
request cannot be completed for any reason.
Example:
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
</commit>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<cancel-commit/>
</rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
8.4.5. Modifications to Existing Operations 8.4.5. Modifications to Existing Operations
8.4.5.1. <commit> 8.4.5.1. <commit>
The :confirmed-commit capability allows 2 additional parameters to The :confirmed-commit:1.1 capability allows 4 additional parameters
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:
Make the confirmed commit survive a session termination, and
set a token on the ongoing confirmed commit.
persist-id:
Used to issue a follow-up confirmed commit or a confirming
commit from any session, with the token from the previous
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>
<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>
Example:
<!-- start a persistent confirmed-commit -->
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
<persist>IQ,d4668</persist>
</commit>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<!-- confirm the persistent confirmed-commit,
possibly from another session -->
<rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<persist-id>IQ,d4668</persist-id>
</commit>
</rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</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
skipping to change at page 65, line 12 skipping to change at page 68, line 19
Validation consists of checking a complete configuration for Validation consists of checking a complete configuration for
syntactical and semantic errors before applying the configuration to syntactical and semantic errors before applying the configuration to
the device. the device.
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.
This capability exists in two versions, 1.0 and 1.1. Version 1.1 Version 1.0 of this capability was defined in [16]. The current
contains all of version 1.0, and adds a new value, "test-only", to version is 1.1, and is defined in this document. It extends version
the test-option parameter. Servers SHOULD implement and advertise 1.0 by adding a new value, "test-only", to the test-option parameter
version 1.1, and MAY, for backwards compatibility, also advertise of the edit-config operation. For backwards compatibility with old
version 1.0. Note that both versions can be advertised at the same clients, servers confirming to this specification MAY advertise
time. 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
Version 1.0 of the :validate capability is identified by the The :validate:1.1 capability is identified by the following
following capability string: capability string:
urn:ietf:params:netconf:capability:validate:1.0
Version 1.1 of the :validate capability is identified by the
following capability string:
urn:ietf:params:netconf:capability:validate:1.1 urn:ietf:params:netconf:capability:validate:1.1
8.6.4. New Operations 8.6.4. New Operations
8.6.4.1. <validate> 8.6.4.1. <validate>
Description: Description:
This protocol operation validates the contents of the specified This protocol operation validates the contents of the specified
skipping to change at page 66, line 43 skipping to change at page 69, line 43
<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>
8.6.5. Modifications to Existing Operations 8.6.5. Modifications to Existing Operations
8.6.5.1. <edit-config> 8.6.5.1. <edit-config>
The :validate capability modifies the <edit-config> operation to The :validate:1.1 capability modifies the <edit-config> operation to
accept the <test-option> parameter. accept the <test-option> parameter.
8.7. Distinct Startup Capability 8.7. Distinct Startup Capability
8.7.1. Description 8.7.1. Description
The device supports separate running and startup configuration The device supports separate running and startup configuration
datastores. The startup configuration is loaded by the device when datastores. The startup configuration is loaded by the device when
it boots. Operations that affect the running configuration will not it boots. Operations that affect the running configuration will not
be automatically copied to the startup configuration. An explicit be automatically copied to the startup configuration. An explicit
skipping to change at page 67, line 44 skipping to change at page 70, line 44
| Operation | Parameters | Notes | | Operation | Parameters | Notes |
+--------------------+--------------------------+-------------------+ +--------------------+--------------------------+-------------------+
| <get-config> | <source> | | | <get-config> | <source> | |
| | | | | | | |
| <copy-config> | <source> <target> | | | <copy-config> | <source> <target> | |
| | | | | | | |
| <lock> | <target> | | | <lock> | <target> | |
| | | | | | | |
| <unlock> | <target> | | | <unlock> | <target> | |
| | | | | | | |
| <validate> | <source> | If :validate is | | <validate> | <source> | If :validate:1.1 |
| | | advertised | | | | is advertised |
| | | | | | | |
| <delete-config> | <target> | Resets the device | | <delete-config> | <target> | Resets the device |
| | | to its factory | | | | to its factory |
| | | defaults | | | | defaults |
+--------------------+--------------------------+-------------------+ +--------------------+--------------------------+-------------------+
To save the startup configuration, use the copy-config operation to To save the startup configuration, use the copy-config operation to
copy the <running> configuration datastore to the <startup> copy the <running> configuration datastore to the <startup>
configuration datastore. configuration datastore.
<rpc message-id="101" <rpc message-id="101"
skipping to change at page 69, line 15 skipping to change at page 72, line 15
The :url capability modifies the <edit-config> operation to accept The :url capability modifies the <edit-config> operation to accept
the <url> element as an alternative to the <config> parameter. the <url> element as an alternative to the <config> parameter.
8.8.5.2. <copy-config> 8.8.5.2. <copy-config>
The :url capability modifies the <copy-config> operation to accept The :url capability modifies the <copy-config> operation to accept
the <url> element as the value of the <source> and the <target> the <url> element as the value of the <source> and the <target>
parameters. parameters.
The file that the url refers to contains the complete datastore,
encoded in XML under the element 'config' in the
'urn:ietf:params:xml:ns:netconf:base:1.0' namespace.
8.8.5.3. <delete-config> 8.8.5.3. <delete-config>
The :url capability modifies the <delete-config> operation to accept The :url capability modifies the <delete-config> operation to accept
the <url> element as the value of the <target> parameters. the <url> element as the value of the <target> parameters.
8.8.5.4. <validate> 8.8.5.4. <validate>
The :url capability modifies the <validate> operation to accept the The :url capability modifies the <validate> operation to accept the
<url> element as the value of the <source> parameter. <url> element as the value of the <source> parameter.
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
[2]. [2].
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 [2], with the same extension for root node children as in XPath 1.0 [2], with the same extension for root node children as
used by XSLT 1.0 [10] (section 3.1). Specifically, it means that the used by XSLT 1.0 [11] (section 3.1). Specifically, it means that the
root node may have any number of element nodes as its children. root node may have any 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 filter o The set of namespace declarations are those in scope on the filter
element. 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.
skipping to change at page 74, line 12 skipping to change at page 77, line 12
server. However, such a solution is not useful in all deployment server. However, such a solution is not useful in all deployment
scenarios, such as those where SSH public/private key pairs are used. 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 [7]. IETF XML registry [7].
Following the format in RFC 3688, IANA has made the following IANA is requested to update the allocation of the following URI to
registration. 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 [7]. XML registry [7].
Following the format in RFC 3688, IANA has made the following IANA is requested to update the allocation of the following URI to
registration. 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 Capability URNs 10.3. NETCONF YANG Module
This document creates a registry that allocates NETCONF capability
identifiers. Additions to the registry require IETF Standards
Action.
The initial content of the registry contains the capability URNs This document registers a YANG module in the YANG Module Names
defined in Section 8. registry [9].
Following the guidelines in RFC 3553 [6], IANA assigned a NETCONF name: ietf-netconf
sub-namespace as follows: namespace: urn:ietf:params:xml:ns:netconf:base:1.0
prefix: nc
reference: RFCXXXX
Registry name: netconf 10.4. NETCONF Capability URNs
Specification: Section 8 of this document. IANA has created and will maintain a registry "Network Configuration
Protocol (NETCONF) Capability URNs" that allocates NETCONF capability
identifiers. Additions to the registry require IETF Standards
Action.
Repository: The following table. IANA is requested to update the allocations of the following
capabilities to reference this document when it is published as an
RFC.
+--------------------+----------------------------------------------+ +--------------------+----------------------------------------------+
| Index | Capability Identifier | | Index | Capability Identifier |
+--------------------+----------------------------------------------+ +--------------------+----------------------------------------------+
| :writable-running | urn:ietf:params:netconf:capability:writable- | | :writable-running | urn:ietf:params:netconf:capability:writable- |
| | running:1.0 | | | running:1.0 |
| | | | | |
| :candidate | urn:ietf:params:netconf:capability:candidate | | :candidate | urn:ietf:params:netconf:capability:candidate |
| | :1.0 | | | :1.0 |
| | | | | |
| :confirmed-commit | urn:ietf:params:netconf:capability:confirmed |
| | -commit:1.0 |
| | |
| :rollback-on-error | urn:ietf:params:netconf:capability:rollback- | | :rollback-on-error | urn:ietf:params:netconf:capability:rollback- |
| | on-error:1.0 | | | on-error:1.0 |
| | | | | |
| :validate | urn:ietf:params:netconf:capability:validate: |
| | 1.0 |
| | urn:ietf:params:netconf:capability:validate: |
| | 1.1 |
| | |
| :startup | urn:ietf:params:netconf:capability:startup:1 | | :startup | urn:ietf:params:netconf:capability:startup:1 |
| | .0 | | | .0 |
| | | | | |
| :url | urn:ietf:params:netconf:capability:url:1.0 | | :url | urn:ietf:params:netconf:capability:url:1.0 |
| | | | | |
| :xpath | urn:ietf:params:netconf:capability:xpath:1.0 | | :xpath | urn:ietf:params:netconf:capability:xpath:1.0 |
+--------------------+----------------------------------------------+ +--------------------+----------------------------------------------+
Index value: The capability name. IANA is requested to add the following capabilities to the registry:
+---------------------+---------------------------------------------+
| Index | Capability Identifier |
+---------------------+---------------------------------------------+
| :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 11. Authors and Acknowledgements
This document was written by: This document was written by:
Andy Bierman Andy Bierman
Ken Crozier, Cisco Systems Ken Crozier, Cisco Systems
Rob Enns, Juniper Networks Rob Enns, Juniper Networks
skipping to change at page 77, line 9 skipping to change at page 80, line 9
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, Juergen Schoenwalder, Glenn Waters, David Perkins, Weijing Chisholm, Juergen Schoenwalder, Glenn Waters, David Perkins, Weijing
Chen, Simon Leinen, Keith Allen, and Dave Harrington for all of their Chen, Simon Leinen, Keith Allen, and Dave Harrington for all of their
valuable advice. valuable advice.
12. References 12. References
12.1. Normative References 12.1. Normative References
[1] Bray, T., Sperberg-McQueen, C., Paoli, J., and E. Maler, [1] Sperberg-McQueen, C., Maler, E., Paoli, J., and T. Bray,
"Extensible Markup Language (XML) 1.0 (Second Edition)", World "Extensible Markup Language (XML) 1.0 (Second Edition)", World
Wide Web Consortium FirstEdition REC-xml-20001006, Wide Web Consortium FirstEdition REC-xml-20001006,
October 2000, <http://www.w3.org/TR/2000/REC-xml-20001006>. October 2000, <http://www.w3.org/TR/2000/REC-xml-20001006>.
[2] DeRose, S. and J. Clark, "XML Path Language (XPath) Version [2] DeRose, S. and J. Clark, "XML Path Language (XPath) Version
1.0", World Wide Web Consortium Recommendation REC-xpath- 1.0", World Wide Web Consortium Recommendation REC-xpath-
19991116, November 1999, 19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
[3] Bradner, S., "Key words for use in RFCs to Indicate Requirement [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement
skipping to change at page 77, line 36 skipping to change at page 80, line 36
Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986,
January 2005. January 2005.
[6] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF [6] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF
URN Sub-namespace for Registered Protocol Parameters", BCP 73, URN Sub-namespace for Registered Protocol Parameters", BCP 73,
RFC 3553, June 2003. RFC 3553, June 2003.
[7] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [7] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[8] Bjorklund, M., "YANG - A data modeling language for NETCONF", [8] Lengyel, B. and M. Bjorklund, "Partial Lock Remote Procedure
draft-ietf-netmod-yang-10 (work in progress), January 2010. Call (RPC) for NETCONF", RFC 5717, December 2009.
[9] Schoenwaelder, J., "Common YANG Data Types", [9] Bjorklund, M., "YANG - A data modeling language for the Network
draft-ietf-netmod-yang-types-06 (work in progress), Configuration Protocol (NETCONF)", draft-ietf-netmod-yang-13
February 2010. (work in progress), June 2010.
[10] Schoenwaelder, J., "Common YANG Data Types",
draft-ietf-netmod-yang-types-09 (work in progress), April 2010.
12.2. Informative References 12.2. Informative References
[10] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide [11] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide
Web Consortium Recommendation REC-xslt-19991116, November 1999, Web Consortium Recommendation REC-xslt-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xslt-19991116>. <http://www.w3.org/TR/1999/REC-xslt-19991116>.
[11] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) [12] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote
Protocol Version 1.1", RFC 4346, April 2006.
[12] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Protocol
Architecture", RFC 4251, January 2006.
[13] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote
Authentication Dial In User Service (RADIUS)", RFC 2865, Authentication Dial In User Service (RADIUS)", RFC 2865,
June 2000. June 2000.
[14] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the [13] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the
Use of Extensible Markup Language (XML) within IETF Protocols", Use of Extensible Markup Language (XML) within IETF Protocols",
BCP 70, RFC 3470, January 2003. BCP 70, RFC 3470, January 2003.
[14] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Protocol
Architecture", RFC 4251, January 2006.
[15] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS)
Protocol Version 1.1", RFC 4346, April 2006.
[16] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006.
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 in use. Description: The request requires a resource that already is in 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 should <bad-element> : name of the element that should
contain the missing attribute 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 rollback some configuration change (via
rollback-on-error or discard-changes operations) was rollback-on-error or discard-changes operations) was
not completed for some reason. 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: Some part of the requested operation failed or was Description: This error-tag is obsolete, and SHOULD NOT be sent
not attempted for some reason. Full cleanup has by servers conforming to this document.
not been performed (e.g., rollback not supported)
by the server. The error-info container is used Some part of the requested operation failed or was
to identify which portions of the application not attempted for some reason. Full cleanup has
data model content for which the requested operation not been performed (e.g., rollback not supported)
has succeeded (<ok-element>), failed (<bad-element>), by the server. The error-info container is used
or not been attempted (<noop-element>). to identify which portions of the application
data model content for which the requested operation
has succeeded (<ok-element>), failed (<bad-element>),
or not been attempted (<noop-element>).
Appendix B. XML Schema for NETCONF Messages Layer Appendix B. XML Schema for NETCONF Messages Layer
This section is normative. This section is normative.
BEGIN <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"
targetNamespace="urn:ietf:params:xml:ns:netconf:base:1.0" targetNamespace="urn:ietf:params:xml:ns:netconf:base:1.0"
elementFormDefault="qualified" elementFormDefault="qualified"
attributeFormDefault="unqualified" attributeFormDefault="unqualified"
xml:lang="en"> xml:lang="en"
version="1.1">
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
This schema defines the syntax for the NETCONF Message layer This schema defines the syntax for the NETCONF Message layer
messages 'hello', 'rpc', and 'rpc-reply'. messages 'hello', 'rpc', and 'rpc-reply'.
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
<!-- <!--
import standard XML definitions import standard XML definitions
skipping to change at page 83, line 52 skipping to change at page 87, line 4
<xs:restriction base="xs:string"> <xs:restriction base="xs:string">
<xs:maxLength value="4095"/> <xs:maxLength value="4095"/>
</xs:restriction> </xs:restriction>
</xs:simpleType> </xs:simpleType>
<!-- <!--
Types used for session-id Types used for session-id
--> -->
<xs:simpleType name="SessionId"> <xs:simpleType name="SessionId">
<xs:restriction base="xs:unsignedInt"> <xs:restriction base="xs:unsignedInt">
<xs:minInclusive value="1"/> <xs:minInclusive value="1"/>
</xs:restriction>
</xs:restriction>
</xs:simpleType> </xs:simpleType>
<xs:simpleType name="SessionIdOrZero"> <xs:simpleType name="SessionIdOrZero">
<xs:restriction base="xs:unsignedInt"/> <xs:restriction base="xs:unsignedInt"/>
</xs:simpleType> </xs:simpleType>
<!-- <!--
<rpc> element <rpc> element
--> -->
<xs:complexType name="rpcType"> <xs:complexType name="rpcType">
<xs:sequence> <xs:sequence>
<xs:element ref="rpcOperation"/> <xs:element ref="rpcOperation"/>
skipping to change at page 86, line 16 skipping to change at page 89, line 17
<xs:attribute ref="xml:lang" use="optional"/> <xs:attribute ref="xml:lang" use="optional"/>
</xs:extension> </xs:extension>
</xs:simpleContent> </xs:simpleContent>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:element name="error-info" type="errorInfoType" <xs:element name="error-info" type="errorInfoType"
minOccurs="0"/> minOccurs="0"/>
</xs:sequence> </xs:sequence>
</xs:complexType> </xs:complexType>
<!-- <!--
operation attribute used in <edit-config>
-->
<xs:simpleType name="editOperationType">
<xs:restriction base="xs:string">
<xs:enumeration value="merge"/>
<xs:enumeration value="replace"/>
<xs:enumeration value="create"/>
<xs:enumeration value="delete"/>
<xs:enumeration value="remove"/>
</xs:restriction>
</xs:simpleType>
<xs:attribute name="operation" type="editOperationType"/>
<!--
<rpc-reply> element <rpc-reply> element
--> -->
<xs:complexType name="rpcReplyType"> <xs:complexType name="rpcReplyType">
<xs:choice> <xs:choice>
<xs:element name="ok"/> <xs:element name="ok"/>
<xs:group ref="rpcResponse"/> <xs:group ref="rpcResponse"/>
</xs:choice> </xs:choice>
<xs:attribute name="message-id" type="messageIdType" <xs:attribute name="message-id" type="messageIdType"
use="optional"/> use="optional"/>
<!-- <!--
Any attributes supplied with <rpc> element must be returned Any attributes supplied with <rpc> element must be returned
on <rpc-reply>. on <rpc-reply>.
--> -->
<xs:anyAttribute processContents="lax"/> <xs:anyAttribute processContents="lax"/>
</xs:complexType> </xs:complexType>
<xs:group name="rpcResponse"> <xs:group name="rpcResponse">
<xs:sequence> <xs:sequence>
<xs:element ref="rpc-error" <xs:element ref="rpc-error"
minOccurs="0" maxOccurs="unbounded"/> minOccurs="0" maxOccurs="unbounded"/>
<xs:choice> <xs:any namespace="##any" processContents="lax"
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
minOccurs="0" maxOccurs="unbounded"/>
</xs:choice>
</xs:sequence> </xs:sequence>
</xs:group> </xs:group>
<xs:element name="rpc-reply" type="rpcReplyType"/> <xs:element name="rpc-reply" type="rpcReplyType"/>
<!-- <!--
<rpc-error> element <rpc-error> element
--> -->
<xs:element name="rpc-error" type="rpcErrorType"/> <xs:element name="rpc-error" type="rpcErrorType"/>
<!-- <!--
rpcOperationType: used as a base type for all rpcOperationType: used as a base type for all
NETCONF operations NETCONF operations
--> -->
skipping to change at page 87, line 26 skipping to change at page 90, line 39
</xs:sequence> </xs:sequence>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:element name="session-id" <xs:element name="session-id"
type="SessionId" minOccurs="0"/> type="SessionId" minOccurs="0"/>
</xs:sequence> </xs:sequence>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
</xs:schema> </xs:schema>
END <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.
BEGIN <CODE BEGINS> file "ietf-netconf@2010-06-04.yang"
module ietf-netconf { module ietf-netconf {
namespace "urn:ietf:params:xml:ns:netconf:base:1.0"; // the namespace for NETCONF XML definitions has not changed
prefix nc; // this value is pre-determined by RFC 4741
namespace "urn:ietf:params:xml:ns:netconf:base:1.0";
import ietf-inet-types { prefix nc;
prefix inet;
}
organization import ietf-inet-types {
"IETF NETCONF (Network Configuration) Working Group"; prefix inet;
}
contact organization
"Send comments to the NETCONF WG mailing list. "IETF NETCONF (Network Configuration) Working Group";
<netconf@ietf.org>";
description contact
"NETCONF Protocol Data Types and RPC methods. "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Copyright (c) 2010 IETF Trust and the persons identified as WG Chair: Bert Wijnen
the document authors. All rights reserved. <mailto:bertietf@bwijnen.net>
Redistribution and use in source and binary forms, with or WG Chair: Mehmet Ersue
without modification, are permitted provided that the <mailto:mehmet.ersue@nsn.com>
following conditions are met:
- Redistributions of source code must retain the above Editor: Martin Bjorklund
copyright notice, this list of conditions and the <mailto:mbj@tail-f.com>
following disclaimer.
- Redistributions in binary form must reproduce the above Editor: Juergen Schoenwaelder
copyright notice, this list of conditions and the <mailto:j.schoenwaelder@jacobs-university.de>
following disclaimer in the documentation and/or other
materials provided with the distribution.
- Neither the name of Internet Society, IETF or IETF Editor: Andy Bierman
Trust, nor the names of specific contributors, may be <mailto:andyb@iwl.com>";
used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND description
CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED "NETCONF Protocol Data Types and RPC methods.
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This version of this YANG module is part of RFC XXXX; see Copyright (c) 2010 IETF Trust and the persons identified as
the RFC itself for full legal notices."; the document authors. All rights reserved.
// RFC Ed.: replace XXXX with actual RFC number and Redistribution and use in source and binary forms, with or
// remove this note without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
reference "draft-ietf-netconf-rfc4741bis-01.txt"; This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this note
revision 2010-02-04 { revision 2010-06-04 {
description description
"Initial revision"; "Initial revision";
reference reference
"RFC XXXX: Network Configuration Protocol"; "RFC XXXX: Network Configuration Protocol";
// RFC Ed.: replace XXXX with actual RFC number and }
// remove this note
}
extension get-filter-element-attributes { extension get-filter-element-attributes {
description description
"If this extension is present within the "If this extension is present within the
an 'anyxml' statement named 'filter', which must be an 'anyxml' statement named 'filter', which must be
conceptually defined within the RPC input section conceptually defined within the RPC input section
for the 'get' and 'get-config' RPC operations, for the 'get' and 'get-config' RPC operations,
then the following unqualified XML attribute is then the following unqualified XML attribute is
supported within the 'filter' element, within supported within the 'filter' element, within
a 'get' or 'get-config' protocol operation: a 'get' or 'get-config' protocol operation:
type : optional attribute with allowed type : optional attribute with allowed
value strings 'subtree' and 'xpath'. value strings 'subtree' and 'xpath'.
If missing, the default value is 'subtree'. If missing, the default value is 'subtree'.
If the xpath feature is supported, then the If the 'xpath' feature is supported, then the
following unqualified XML attribute is following unqualified XML attribute is
also supported: also supported:
select: optional attribute containing a select: optional attribute containing a
string representing an XPath expression. string representing an XPath expression.
The 'type' attribute must be equal to 'xpath' The 'type' attribute must be equal to 'xpath'
if this attribute is present."; if this attribute is present.";
} }
// NETCONF capabilities defined as features // NETCONF capabilities defined as features
feature writable-running { feature writable-running {
description description
"NETCONF :writable-running capability; "NETCONF :writable-running capability;
If the server advertises the :writable-running 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.";
// RFC Ed.: replace XXXX with actual RFC number and
// remove this note
reference "RFC XXXX, section 8.2.";
}
feature candidate { reference "RFC XXXX, section 8.2.";
description }
"NETCONF :candidate capability;
If the server advertises the :candidate
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.3.";
}
feature confirmed-commit { feature candidate {
if-feature candidate; description
description "NETCONF :candidate capability;
"NETCONF :confirmed-commit capability; If the server advertises the :candidate
If the server advertises the :confirmed-commit 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.3.";
}
reference "RFC XXXX, section 8.4."; feature confirmed-commit {
} 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.";
feature rollback-on-error { reference "RFC XXXX, section 8.4.";
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 XXXX, section 8.5."; 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 XXXX, section 8.5.";
}
feature validate { feature validate {
status "deprecated"; description
description "NETCONF :validate:1.1 capability;
"NETCONF :validate:1.0 capability; If the server advertises the :validate:1.1
If the server advertises the :validate:1.0 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.6.";
reference "RFC XXXX, section 8.6."; }
}
feature validate-1.1 { feature startup {
description description
"NETCONF :validate:1.1 capability; "NETCONF :startup capability;
If the server advertises the :validate:1.1 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.6."; reference "RFC XXXX, section 8.7.";
} }
feature startup { feature url {
description description
"NETCONF :startup capability; "NETCONF :url capability;
If the server advertises the :startup 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.7."; reference "RFC XXXX, section 8.8.";
} }
feature url { feature xpath {
description description
"NETCONF :url capability; "NETCONF :xpath capability;
If the server advertises the :url If the server advertises the :xpath
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 XXXX, section 8.9.";
} }
feature xpath { // NETCONF Simple Types
description
"NETCONF :xpath capability; typedef session-id-type {
If the server advertises the :xpath type uint32 {
capability for a session, then this feature must range "1..max";
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.9.";
} }
description
"NETCONF Session Id";
}
// NETCONF Simple Types typedef session-id-or-zero-type {
type uint32;
description
"NETCONF Session Id or Zero to indicate none";
}
typedef session-id-type { typedef error-tag-type {
type uint32 { type enumeration {
range "1..max"; enum in-use {
description
"The request requires a resource that
already is in use.";
}
enum invalid-value {
description
"The request specifies an unacceptable value for one
or more parameters.";
}
enum too-big {
description
"The request or response (that would be generated) is
too large for the implementation to handle.";
}
enum missing-attribute {
description
"An expected attribute is missing.";
}
enum bad-attribute {
description
"An attribute value is not correct; e.g., wrong type,
out of range, pattern mismatch.";
}
enum unknown-attribute {
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 rollback 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.";
}
}
description "NETCONF Error Tag";
reference "RFC XXXX, section YYY";
}
typedef error-severity-type {
type enumeration {
enum error {
description "Error severity";
}
enum warning {
description "Warning severity";
} }
description
"NETCONF Session Id";
} }
description "NETCONF Error Severity";
reference "RFC XXXX, section YYY";
}
typedef session-id-or-zero-type { typedef edit-operation-type {
type uint32; type enumeration {
description enum merge {
"NETCONF Session Id or Zero to indicate none"; 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 RPC Methods // NETCONF Standard RPC Methods
rpc get-config { rpc get-config {
description description
"Retrieve all or part of a specified configuration."; "Retrieve all or part of a specified configuration.";
reference "RFC XXXX, section 7.1."; reference "RFC XXXX, section 7.1.";
input { input {
container source { container source {
description description
"Particular configuration to retrieve."; "Particular configuration to retrieve.";
choice config-source { choice config-source {
mandatory true; mandatory true;
description
"The configuration to retrieve.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config source.";
leaf candidate {
if-feature candidate;
type empty;
}
leaf running {
type empty;
}
leaf startup {
if-feature startup;
type empty;
description
"This is optional-to-implement on the server because
not all servers will support filtering for this
database.";
}
} }
} leaf running {
type empty;
anyxml filter { description
description "The running configuration is the config source.";
"Subtree or Xpath filter to use."; }
nc:get-filter-element-attributes; 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
database.";
}
} }
} }
output { anyxml filter {
container data { description
presence "Subtree or XPath filter to use.";
"An empty data container indicates that the nc:get-filter-element-attributes;
request did not produce any results."; }
description
"Copy of the source database subset which matched
the filter criteria (if any).";
}
}
} }
rpc edit-config { output {
description container data {
"The 'edit-config' operation loads all or part of a specified presence
configuration to the specified target configuration."; "An empty data container indicates that the
request did not produce any results.";
description
"Copy of the source database subset which matched
the filter criteria (if any).";
}
}
}
reference "RFC XXXX, section 7.2."; rpc edit-config {
description
"The 'edit-config' operation loads all or part of a specified
configuration to the specified target configuration.";
input { reference "RFC XXXX, section 7.2.";
container target {
description
"Particular configuration to edit.";
choice config-target { input {
mandatory true; container target {
description
"Particular configuration to edit.";
leaf candidate { choice config-target {
if-feature candidate; mandatory true;
type empty; description
} "The configuration target.";
leaf running {
if-feature writable-running; leaf candidate {
type empty; 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.";
} }
} }
}
leaf default-operation { leaf default-operation {
type enumeration { type enumeration {
enum merge; enum merge {
enum replace; description
enum none; "The default operation is merge.";
}
enum replace {
description
"The default operation is replace.";
}
enum none {
description
"There is no default operation.";
} }
default "merge";
} }
default "merge";
description
"The default operation to use.";
}
leaf test-option { leaf test-option {
if-feature validate; if-feature validate;
type enumeration { type enumeration {
enum test-then-set; enum test-then-set {
enum set; description
enum test-only { "The server will test and then set if no errors.";
description }
"This value can only be used if the 'validate-1.1' enum set {
feature is supported."; description
} "The server will set without a test first.";
} }
}
leaf error-option { enum test-only {
type enumeration { description
enum stop-on-error; "The server will only test and not set, even
enum continue-on-error; if there are no errors.";
enum rollback-on-error {
description
"This value can only be used if the 'rollback-on-error'
feature is supported.";
}
} }
default "stop-on-error";
} }
default "test-then-set";
description
"The test option to use.";
}
choice edit-content { leaf error-option {
mandatory true; type enumeration {
anyxml config { enum stop-on-error {
description description
"Inline Config content: 'config' element. "The server will stop on errors.";
This is not full 'anyxml' because the <config>
element cannot directly contain a text node.";
} }
leaf url { enum continue-on-error {
if-feature url; description
type inet:uri; "The server may continue on errors.";
} }
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 {
mandatory true;
description
"The content for the edit operation";
anyxml config {
description
"Inline Config content.";
}
leaf url {
if-feature url;
type inet:uri;
description
"URL based config content.";
} }
} }
} }
}
rpc copy-config { rpc copy-config {
description description
"Create or replace an entire configuration datastore with the "Create or replace an entire configuration datastore with the
contents of another complete configuration datastore."; contents of another complete configuration datastore.";
reference "RFC XXXX, section 7.3."; reference "RFC XXXX, section 7.3.";
input { input {
container target { container target {
description description
"Particular configuration to copy to."; "Particular configuration to copy to.";
choice config-target { choice config-target {
mandatory true; mandatory true;
description
"The configuration target of the copy operation.";
leaf candidate { leaf candidate {
if-feature candidate; if-feature candidate;
type empty; type empty;
} description
leaf running { "The candidate configuration is the config target.";
if-feature writable-running; }
type empty; leaf running {
description if-feature writable-running;
"This is optional-to-implement on the server."; type empty;
} description
leaf startup { "The running configuration is the config target.
if-feature startup; This is optional-to-implement on the server.";
type empty; }
} leaf startup {
leaf url { if-feature startup;
if-feature url; type empty;
type inet:uri; 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 { container source {
description description
"Particular configuration to copy from."; "Particular configuration to copy from.";
choice config-source { choice config-source {
mandatory true; mandatory true;
description
"The configuration source for the copy operation.";
leaf candidate { leaf candidate {
if-feature candidate; if-feature candidate;
type empty; type empty;
} description
leaf running { "The candidate configuration is the config source.";
type empty; }
} leaf running {
leaf startup { type empty;
if-feature startup; description
type empty; "The running configuration is the config source.";
} }
leaf url { leaf startup {
if-feature url; if-feature startup;
type inet:uri; type empty;
} description
anyxml config { "The startup configuration is the config source.";
description }
"Inline Config content: 'config' element. leaf url {
Represents an entire 'stand-alone' if-feature url;
configuration database, not a subset of type inet:uri;
the running database."; description
} "The URL-based configuration is the config source.";
}
anyxml config {
description
"Inline Config content: 'config' element.
Represents an entire 'stand-alone'
configuration database, not a subset of
the running database.";
} }
} }
} }
} }
}
rpc delete-config {
description
"Delete a configuration datastore.";
rpc delete-config { reference "RFC XXXX, section 7.4.";
description
"Delete a configuration datastore.";
reference "RFC XXXX, section 7.4."; input {
container target {
description
"Particular configuration to delete.";
input { choice config-target {
container target { mandatory true;
description description
"Particular configuration to delete."; "The configuration target to delete.";
choice config-target {
mandatory true;
leaf startup { leaf startup {
if-feature startup; if-feature startup;
type empty; type empty;
} description
leaf url { "The startup configuration is the config target.";
if-feature url; }
type inet:uri; leaf url {
} if-feature url;
type inet:uri;
description
"The URL-based configuration is the config target.";
} }
} }
} }
} }
}
rpc lock { rpc lock {
description description
"The lock operation allows the client to lock the configuration "The lock operation allows the client to lock the configuration
system of a device."; system of a device.";
reference "RFC XXXX, section 7.5."; reference "RFC XXXX, section 7.5.";
input { input {
container target { container target {
description description
"Particular configuration to lock"; "Particular configuration to lock";
choice config-target { choice config-target {
mandatory true; mandatory true;
description
"The configuration target to lock.";
leaf candidate { leaf candidate {
if-feature candidate; if-feature candidate;
type empty; type empty;
} description
leaf running { "The candidate configuration is the config target.";
type empty; }
} leaf running {
leaf startup { type empty;
if-feature startup; description
type empty; "The running configuration is the config target.";
} }
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
} }
} }
} }
} }
}
rpc unlock { rpc unlock {
description description
"The unlock operation is used to release a configuration lock, "The unlock operation is used to release a configuration lock,
previously obtained with the 'lock' operation."; previously obtained with the 'lock' operation.";
reference "RFC XXXX, section 7.6."; reference "RFC XXXX, section 7.6.";
input { input {
container target { container target {
description description
"Particular configuration to unlock."; "Particular configuration to unlock.";
choice config-target { choice config-target {
mandatory true; mandatory true;
description
"The configuration target to unlock.";
leaf candidate { leaf candidate {
if-feature candidate; if-feature candidate;
type empty; type empty;
} description
leaf running { "The candidate configuration is the config target.";
type empty; }
} leaf running {
leaf startup { type empty;
if-feature startup; description
type empty; "The running configuration is the config target.";
} }
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
} }
} }
} }
} }
}
rpc get { rpc get {
description description
"Retrieve running configuration and device state information."; "Retrieve running configuration and device state information.";
reference "RFC XXXX, section 7.7."; reference "RFC XXXX, section 7.7.";
input { input {
anyxml filter { anyxml filter {
description description
"This parameter specifies the portion of the system "This parameter specifies the portion of the system
configuration and state data to retrieve."; configuration and state data to retrieve.";
nc:get-filter-element-attributes; nc:get-filter-element-attributes;
}
} }
}
output { output {
container data { container data {
presence presence
"An empty data container indicates that the filter "An empty data container indicates that the filter
request did not match any results."; request did not match any results.";
description description
"Copy of the 'running' database subset and/or state "Copy of the 'running' database subset and/or state
data which matched the filter criteria (if any)."; data which matched the filter criteria (if any).";
}
} }
} }
}
rpc close-session { rpc close-session {
description description
"Request graceful termination of a NETCONF session."; "Request graceful termination of a NETCONF session.";
reference "RFC XXXX, section 7.8.";
}
rpc kill-session { reference "RFC XXXX, section 7.8.";
description }
"Force the termination of a NETCONF session."; rpc kill-session {
description
"Force the termination of a NETCONF session.";
reference "RFC XXXX, section 7.9."; reference "RFC XXXX, section 7.9.";
input { input {
leaf session-id { leaf session-id {
type session-id-type; type session-id-type;
mandatory true; mandatory true;
description description
"Particular session to kill."; "Particular session to kill.";
}
} }
} }
}
rpc commit { rpc commit {
if-feature candidate; if-feature candidate;
description description
"Commit the candidate configuration as the device's new "Commit the candidate configuration as the device's new
current configuration"; current configuration";
reference "RFC XXXX, section 8.3.4.1."; reference "RFC XXXX, section 8.3.4.1.";
input { input {
leaf confirmed { leaf confirmed {
if-feature confirmed-commit; if-feature confirmed-commit;
type empty; type empty;
reference "RFC XXXX, section 8.3.4.1."; description
} "Requests a confirmed commit.";
reference "RFC XXXX, section 8.3.4.1.";
}
leaf confirm-timeout { leaf confirm-timeout {
if-feature confirmed-commit; if-feature confirmed-commit;
type uint32 { type uint32 {
range "1..max"; range "1..max";
}
units "seconds";
default "600"; // 10 minutes
reference "RFC XXXX, section 8.3.4.1.";
} }
units "seconds";
default "600"; // 10 minutes
description
"The timeout interval for a confirmed commit.";
reference "RFC XXXX, section 8.3.4.1.";
}
leaf persist {
if-feature confirmed-commit;
type string;
description
"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
in the 'persist-id' parameter of commit or cancel-commit in
order to confirm or cancel the persistent confirmed commit.
The token should be a random string.";
reference "RFC XXXX, 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 { rpc discard-changes {
if-feature candidate; if-feature candidate;
description description
"Revert the candidate configuration to the current "Revert the candidate configuration to the current
running configuration."; running configuration.";
reference "RFC XXXX, section 8.3.4.2."; 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 XXXX, section 8.4.4.1.";
input {
leaf persist-id {
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 { rpc validate {
if-feature validate; if-feature validate;
description description
"Validates the contents of the specified configuration."; "Validates the contents of the specified configuration.";
reference "RFC XXXX, section 8.6.4.1."; reference "RFC XXXX, section 8.6.4.1.";
input { input {
container source { container source {
description description
"Particular configuration to validate."; "Particular configuration to validate.";
choice config-source { choice config-source {
mandatory true; mandatory true;
description
"The configuration source to validate.";
leaf candidate { leaf candidate {
if-feature candidate; if-feature candidate;
type empty; type empty;
} description
leaf running { "The candidate configuration is the config source.";
type empty; }
} leaf running {
leaf startup { type empty;
if-feature startup; description
type empty; "The running configuration is the config source.";
} }
leaf url { leaf startup {
if-feature url; if-feature startup;
type inet:uri; type empty;
} description
anyxml config { "The startup configuration is the config source.";
description }
"Inline Config content: 'config' element. leaf url {
Represents an entire 'stand-alone' if-feature url;
configuration database, not a subset of type inet:uri;
the running database."; description
} "The URL-based configuration is the config source.";
}
anyxml config {
description
"Inline Config content: 'config' element.
Represents an entire 'stand-alone'
configuration database, not a subset of
the running database.";
} }
} }
} }
} }
} }
END }
<CODE ENDS>
Appendix D. Capability Template Appendix D. Capability Template
This section is non-normative. This non-normative section defines a template that should be used to
define protocol capabilities. Data models written in YANG usually do
not need to define protocol capabilities since the usage of YANG
automatically leads to a capability announcing the data model and any
optional portions of the data model, so called features in YANG
terminology. The capabilities template should only be used in cases
where the YANG mechanisms are not powerful enough (e.g., for handling
parametrized features) or a different data modeling 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 103, line 22 skipping to change at page 112, line 22
against a single individual device. In making a change to the against a single individual device. In making a change to the
configuration, the application needs to build trust that its change configuration, the application needs to build trust that its change
has been made correctly and that it has not impacted the operation of has been made correctly and that it has not impacted the operation of
the device. The application (and the application user) should feel the device. The application (and the application user) should feel
confident that their change has not damaged the network. confident that their change has not damaged the network.
Protecting each individual device consists of a number of steps: Protecting each individual device consists of a number of steps:
o Acquiring the configuration lock. o Acquiring the configuration lock.
o Loading the update.
o Validating the incoming configuration.
o Checkpointing the running configuration. o Checkpointing the running configuration.
o Loading and validating the incoming configuration.
o Changing the running configuration. o Changing the running configuration.
o Testing the new configuration. o Testing the new configuration.
o Making the change permanent (if desired). o Making the change permanent (if desired).
o Releasing the configuration lock. o Releasing the configuration lock.
Let's look at the details of each step. Let's look at the details of each step.
skipping to change at page 104, line 14 skipping to change at page 113, line 14
<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>
E.1.2. Loading the Update
The configuration can be loaded onto the device without impacting the
running system. If the :url capability is supported and lists "file"
as a supported scheme, incoming changes can be placed in a local
file.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<url>file://incoming.conf</url>
</target>
<source>
<config>
<!-- place incoming configuration here -->
</config>
</source>
</copy-config>
</rpc>
If the :candidate capability is supported, the candidate If the :candidate capability is supported, the candidate
configuration can be used. configuration should be locked.
<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> <lock>
<target> <target>
<candidate/> <candidate/>
</target> </target>
<config> </lock>
<!-- place incoming configuration here -->
</config>
</edit-config>
</rpc>
If the update fails, the user file can be deleted using the
<delete-config> operation, or the candidate configuration can be
reverted using the <discard-changes> operation.
E.1.3. Validating the Incoming Configuration
Before the incoming configuration is applied, validating it is often
useful. Validation allows the application to gain confidence that
the change will succeed and simplifies recovery if it does not.
If the device supports the :url capability and lists "file" as a
supported scheme, use the <validate> operation with the <source>
parameter set to the proper user file:
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate>
<source>
<url>file://incoming.conf</url>
</source>
</validate>
</rpc>
If the device supports the :candidate capability, some validation
will be performed as part of loading the incoming configuration into
the candidate. For full validation, either pass the <validate>
parameter during the <edit-config> step given above, or use the
<validate> operation with the <source> parameter set to <candidate>.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate>
<source>
<candidate/>
</source>
</validate>
</rpc> </rpc>
E.1.4. Checkpointing the Running Configuration E.1.2. Checkpointing the Running Configuration
The running configuration can be saved into a local file as a The running configuration can be saved into a local file as a
checkpoint before loading the new configuration. If the update checkpoint before loading the new configuration. If the update
fails, the configuration can be restored by reloading the checkpoint fails, the configuration can be restored by reloading the checkpoint
file. file.
The checkpoint file can be created using the <copy-config> operation. The checkpoint file can be created using the <copy-config> operation.
<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">
skipping to change at page 106, line 20 skipping to change at page 114, 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.5. Changing the Running Configuration E.1.3. Loading and Validating the Incoming Configuration.
When the incoming configuration has been safely loaded onto the
device and validated, it is ready to impact the running system.
If the device supports the :url capability and lists "file" as a If the :candidate capability is supported, the configuration can be
supported scheme, use the <edit-config> operation to merge the loaded onto the device without impacting the running system.
incoming configuration into the 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/> <candidate/>
</target> </target>
<config> <config>
<url>file://incoming.conf</url> <!-- place incoming configuration changes here -->
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
If the device supports the :validate:1.1 capability, it will by
default validate the incoming configuration when it is loaded into
the candidate. To avoid this validation, pass the <test-option>
parameter with the value "set". Full validation can be requested
with the <validate> operation.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate>
<source>
<candidate/>
</source>
</validate>
</rpc>
E.1.4. Changing the Running Configuration
When the incoming configuration has been safely loaded onto the
device and validated, it is ready to impact the running system.
If the device supports the :candidate capability, use the <commit> If the device supports the :candidate capability, use the <commit>
operation to set the running configuration to the candidate operation to set the running configuration to the candidate
configuration. Use the <confirmed> parameter to allow automatic configuration. Use the <confirmed> parameter to allow automatic
reversion to the original configuration if connectivity to the device reversion to the original configuration if connectivity to the device
fails. fails.
<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>
If the candidate is not supported by the device, the incoming
configuration change is loaded directly into running.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<!-- place incoming configuration changes here -->
</config>
</edit-config>
</rpc> </rpc>
E.1.6. Testing the New Configuration E.1.5. Testing the New Configuration
Now that the incoming configuration has been integrated into the Now that the incoming configuration has been integrated into the
running configuration, the application needs to gain trust that the running configuration, the application needs to gain trust that the
change has affected the device in the way intended without affecting change has affected the device in the way intended without affecting
it negatively. it negatively.
To gain this confidence, the application can run tests of the To gain this confidence, the application can run tests of the
operational state of the device. The nature of the test is dependent operational state of the device. The nature of the test is dependent
on the nature of the change and is outside the scope of this on the nature of the change and is outside the scope of this
document. Such tests may include reachability from the system document. Such tests may include reachability from the system
running the application (using ping), changes in reachability to the running the application (using ping), changes in reachability to the
rest of the network (by comparing the device's routing table), or rest of the network (by comparing the device's routing table), or
inspection of the particular change (looking for operational evidence inspection of the particular change (looking for operational evidence
of the BGP peer that was just added). of the BGP peer that was just added).
E.1.7. Making the Change Permanent E.1.6. Making the Change Permanent
When the configuration change is in place and the application has When the configuration change is in place and the application has
sufficient faith in the proper function of this change, the sufficient faith in the proper function of this change, the
application should make the change permanent. application should make the change permanent.
If the device supports the :startup capability, the current If the device supports the :startup capability, the current
configuration can be saved to the startup configuration by using the configuration can be saved to the startup configuration by using the
startup configuration as the target of the <copy-config> operation. startup configuration as the target of the <copy-config> operation.
<rpc message-id="101" <rpc message-id="101"
skipping to change at page 108, line 5 skipping to change at page 116, line 26
If the device supports the :candidate capability and a confirmed If the device supports the :candidate capability and a confirmed
commit was requested, the confirming commit must be sent before the commit was requested, the confirming commit must be sent before the
timeout expires. timeout expires.
<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/>
</rpc> </rpc>
E.1.8. Releasing the Configuration Lock E.1.7. Releasing the Configuration Lock
When the configuration update is complete, the lock must be released, When the configuration update is complete, the lock must be released,
allowing other applications access to the configuration. allowing other applications access to the configuration.
Use the <unlock> operation to release the configuration lock. Use the <unlock> operation to release the configuration 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">
<unlock> <unlock>
<target> <target>
<running/> <running/>
</target> </target>
</unlock> </unlock>
</rpc> </rpc>
If the :candidate capability is supported, the candidate
configuration should be unlocked.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock>
<target>
<candidate/>
</target>
</unlock>
</rpc>
E.2. Operations on Multiple Devices E.2. Operations on Multiple Devices
When a configuration change requires updates across a number of When a configuration change requires updates across a number of
devices, care should be taken to provide the required transaction devices, care should be taken to provide the required transaction
semantics. The NETCONF protocol contains sufficient primitives upon semantics. The NETCONF protocol contains sufficient primitives upon
which transaction-oriented operations can be built. Providing which transaction-oriented operations can be built. Providing
complete transactional semantics across multiple devices is complete transactional semantics across multiple devices is
prohibitively expensive, but the size and number of windows for prohibitively expensive, but the size and number of windows for
failure scenarios can be reduced. failure scenarios can be reduced.
skipping to change at page 110, line 8 skipping to change at page 118, line 8
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.
Appendix F. Changes from RFC 4741 Appendix F. Changes from RFC 4741
This section lists major changes between this document and RFC 4741. This section lists major changes between this document and RFC 4741.
TBD.
o Added 'remove' enumeration value to the operation attribute.
o Obsoleted the 'partial-operation' error-tag enumeration value.
o Added <persist> and <persist-id> parameters to the <commit>
operation.
o Updated the base protocol URI and clarified the <hello> message
exchange to select and identify the base protocol version in use
for a particular session.
o Added a YANG module to model the operations and removed the
operation layer from the XSD.
o Clarified lock behavior for the candidate database.
o Clarified the error response server requirements for the 'delete'
operation attribute enumeration value.
o Added a namespace wildcarding mechanism for subtree filtering.
o Added a "test-only" value for the <test-option> parameter to the
<edit-config> operation.
o Added a <cancel-commit> operation.
o Introduced a NETCONF username and a requirement for transport
protocols to explain how a username is derived.
Authors' Addresses Authors' Addresses
Rob Enns (editor) Rob Enns (editor)
Juniper Networks Juniper Networks
1194 North Mathilda Ave 1194 North Mathilda Ave
Sunnyvale, CA 94089 Sunnyvale, CA 94089
US US
Email: rpe@juniper.net Email: rpe@juniper.net
 End of changes. 258 change blocks. 
1004 lines changed or deleted 1478 lines changed or added

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