draft-ietf-netconf-4741bis-00.txt   draft-ietf-netconf-4741bis-01.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: September 5, 2009 Tail-f Systems Expires: January 14, 2010 Tail-f Systems
J. Schoenwaelder, Ed. J. Schoenwaelder, Ed.
Jacobs University Jacobs University
March 4, 2009 A. Bierman, Ed.
Netconf Central
July 13, 2009
NETCONF Configuration Protocol NETCONF Configuration Protocol
draft-ietf-netconf-4741bis-00 draft-ietf-netconf-4741bis-01
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 to IETF in full conformance with the
provisions of BCP 78 and BCP 79. This document may contain material provisions of BCP 78 and BCP 79. This document may contain material
from IETF Documents or IETF Contributions published or made publicly from IETF Documents or IETF Contributions published or made publicly
available before November 10, 2008. The person(s) controlling the available before November 10, 2008. The person(s) controlling the
copyright in some of this material may not have granted the IETF copyright in some of this material may not have granted the IETF
Trust the right to allow modifications of such material outside the Trust the right to allow modifications of such material outside the
IETF Standards Process. Without obtaining an adequate license from IETF Standards Process. Without obtaining an adequate license from
skipping to change at page 1, line 45 skipping to change at page 1, line 47
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 The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 5, 2009. This Internet-Draft will expire on January 14, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the Copyright (c) 2009 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 in effect on the date of Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info). publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. and restrictions with respect to this document.
Abstract Abstract
skipping to change at page 3, line 16 skipping to change at page 3, line 16
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 on top of a simple Remote Procedure Call (RPC) layer. realized on top of a simple Remote Procedure Call (RPC) layer.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1. Protocol Overview . . . . . . . . . . . . . . . . . . . . 7 1.1. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8
1.2. Capabilities . . . . . . . . . . . . . . . . . . . . . . 8 1.2. Capabilities . . . . . . . . . . . . . . . . . . . . . . 9
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 . . . . . . . . . . . . . . . 11
2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 10 2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 11
2.2. Authentication, Integrity, and Confidentiality . . . . . 10 2.2. Authentication, Integrity, and Confidentiality . . . . . 11
2.3. Authentication . . . . . . . . . . . . . . . . . . . . . 11 2.3. Authentication . . . . . . . . . . . . . . . . . . . . . 12
2.4. Mandatory Transport Protocol . . . . . . . . . . . . . . 11 2.4. Mandatory Transport Protocol . . . . . . . . . . . . . . 12
3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 12 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 13
3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 12 3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2. No Document Type Declarations . . . . . . . . . . . . . . 12 3.2. No Document Type Declarations . . . . . . . . . . . . . . 13
4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 13 4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 14
4.2. <rpc-reply> Element . . . . . . . . . . . . . . . . . . . 14 4.2. <rpc-reply> Element . . . . . . . . . . . . . . . . . . . 15
4.3. <rpc-error> Element . . . . . . . . . . . . . . . . . . . 15 4.3. <rpc-error> Element . . . . . . . . . . . . . . . . . . . 16
4.4. <ok> Element . . . . . . . . . . . . . . . . . . . . . . 18 4.4. <ok> Element . . . . . . . . . . . . . . . . . . . . . . 19
4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 19 4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 20
5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 20 5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 21
5.1. Configuration Datastores . . . . . . . . . . . . . . . . 20 5.1. Configuration Datastores . . . . . . . . . . . . . . . . 21
5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 20 5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 21
6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 21 6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 22
6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 21 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 22
6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 22 6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 23
6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 22 6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 23
6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 22 6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 23
6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 23 6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 24
6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 23 6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 24
6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 24 6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 25
6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 25 6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 26
6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 26 6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 27
6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 26 6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 27
6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 26 6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 27
6.4.3. Select the Entire <users> Subtree . . . . . . . . . . 27 6.4.3. Select the Entire <users> Subtree . . . . . . . . . . 28
6.4.4. Select All <name> Elements within the <users> 6.4.4. Select All <name> Elements within the <users>
Subtree . . . . . . . . . . . . . . . . . . . . . . . 29 Subtree . . . . . . . . . . . . . . . . . . . . . . . 30
6.4.5. One Specific <user> Entry . . . . . . . . . . . . . . 30 6.4.5. One Specific <user> Entry . . . . . . . . . . . . . . 31
6.4.6. Specific Elements from a Specific <user> Entry . . . 31 6.4.6. Specific Elements from a Specific <user> Entry . . . 32
6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 32 6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 33
6.4.8. Elements with Attribute Naming . . . . . . . . . . . 34 6.4.8. Elements with Attribute Naming . . . . . . . . . . . 35
7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 36 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 37
7.1. <get-config> . . . . . . . . . . . . . . . . . . . . . . 36 7.1. <get-config> . . . . . . . . . . . . . . . . . . . . . . 37
7.2. <edit-config> . . . . . . . . . . . . . . . . . . . . . . 39 7.2. <edit-config> . . . . . . . . . . . . . . . . . . . . . . 40
7.3. <copy-config> . . . . . . . . . . . . . . . . . . . . . . 46 7.3. <copy-config> . . . . . . . . . . . . . . . . . . . . . . 47
7.4. <delete-config> . . . . . . . . . . . . . . . . . . . . . 48 7.4. <delete-config> . . . . . . . . . . . . . . . . . . . . . 49
7.5. <lock> . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.5. <lock> . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.6. <unlock> . . . . . . . . . . . . . . . . . . . . . . . . 51 7.6. <unlock> . . . . . . . . . . . . . . . . . . . . . . . . 52
7.7. <get> . . . . . . . . . . . . . . . . . . . . . . . . . . 52 7.7. <get> . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.8. <close-session> . . . . . . . . . . . . . . . . . . . . . 54 7.8. <close-session> . . . . . . . . . . . . . . . . . . . . . 55
7.9. <kill-session> . . . . . . . . . . . . . . . . . . . . . 55 7.9. <kill-session> . . . . . . . . . . . . . . . . . . . . . 56
8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 57 8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 58
8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 57 8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 58
8.2. Writable-Running Capability . . . . . . . . . . . . . . . 58 8.2. Writable-Running Capability . . . . . . . . . . . . . . . 59
8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 58 8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 59
8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 58 8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 59
8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 58 8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 59
8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 58 8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 59
8.2.5. Modifications to Existing Operations . . . . . . . . 58 8.2.5. Modifications to Existing Operations . . . . . . . . 59
8.3. Candidate Configuration Capability . . . . . . . . . . . 59 8.3. Candidate Configuration Capability . . . . . . . . . . . 60
8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 59 8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 60
8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 60 8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 61
8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 60 8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 61
8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 60 8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 61
8.3.5. Modifications to Existing Operations . . . . . . . . 61 8.3.5. Modifications to Existing Operations . . . . . . . . 62
8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 62 8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 63
8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 62 8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 63
8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 63 8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 64
8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 63 8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 64
8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 63 8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 64
8.4.5. Modifications to Existing Operations . . . . . . . . 63 8.4.5. Modifications to Existing Operations . . . . . . . . 64
8.5. Rollback on Error Capability . . . . . . . . . . . . . . 64 8.5. Rollback on Error Capability . . . . . . . . . . . . . . 65
8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 64 8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 65
8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 64 8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65
8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 65 8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 66
8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 65 8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 66
8.5.5. Modifications to Existing Operations . . . . . . . . 65 8.5.5. Modifications to Existing Operations . . . . . . . . 66
8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 65 8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 66
8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 65 8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 66
8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 66 8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 67
8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 66 8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 67
8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 66 8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 67
8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 67 8.6.5. Modifications to Existing Operations . . . . . . . . 68
8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 67 8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 68
8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 67 8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 68
8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 67 8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 69
8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 68 8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 69
8.7.5. Modifications to Existing Operations . . . . . . . . 68 8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 69
8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 69 8.7.5. Modifications to Existing Operations . . . . . . . . 69
8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 69 8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 70
8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 69 8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 70
8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 69 8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 70
8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 69 8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 70
8.8.5. Modifications to Existing Operations . . . . . . . . 69 8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 70
8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 70 8.8.5. Modifications to Existing Operations . . . . . . . . 70
8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 70 8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 71
8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 70 8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 71
8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 70 8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 72
8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 70 8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 72
8.9.5. Modifications to Existing Operations . . . . . . . . 70 8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 72
9. Security Considerations . . . . . . . . . . . . . . . . . . . 72 8.9.5. Modifications to Existing Operations . . . . . . . . 72
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 9. Security Considerations . . . . . . . . . . . . . . . . . . . 74
10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 74 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 76
10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 74 10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 76
10.3. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 74 10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 76
11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 76 10.3. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 76
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 78
12.1. Normative References . . . . . . . . . . . . . . . . . . 77 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 79
12.2. Informative References . . . . . . . . . . . . . . . . . 77 12.1. Normative References . . . . . . . . . . . . . . . . . . 79
Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 79 12.2. Informative References . . . . . . . . . . . . . . . . . 79
Appendix B. XML Schema for NETCONF RPC and Protocol Operations . 83 Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 81
Appendix C. Capability Template . . . . . . . . . . . . . . . . 95 Appendix B. XML Schema for NETCONF RPC Layer . . . . . . . . . . 85
C.1. capability-name (template) . . . . . . . . . . . . . . . 95 Appendix C. YANG Module for NETCONF Protocol Operations . . . . 90
C.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 95 Appendix D. Capability Template . . . . . . . . . . . . . . . . 104
C.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 95 D.1. capability-name (template) . . . . . . . . . . . . . . . 104
C.1.3. Capability Identifier . . . . . . . . . . . . . . . . 95 D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 104
C.1.4. New Operations . . . . . . . . . . . . . . . . . . . 95 D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 104
C.1.5. Modifications to Existing Operations . . . . . . . . 95 D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 104
C.1.6. Interactions with Other Capabilities . . . . . . . . 95 D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 104
Appendix D. Configuring Multiple Devices with NETCONF . . . . . 96 D.1.5. Modifications to Existing Operations . . . . . . . . 104
D.1. Operations on Individual Devices . . . . . . . . . . . . 96 D.1.6. Interactions with Other Capabilities . . . . . . . . 104
D.1.1. Acquiring the Configuration Lock . . . . . . . . . . 96 Appendix E. Configuring Multiple Devices with NETCONF . . . . . 105
D.1.2. Loading the Update . . . . . . . . . . . . . . . . . 97 E.1. Operations on Individual Devices . . . . . . . . . . . . 105
D.1.3. Validating the Incoming Configuration . . . . . . . . 98 E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 105
D.1.4. Checkpointing the Running Configuration . . . . . . . 98 E.1.2. Loading the Update . . . . . . . . . . . . . . . . . 106
D.1.5. Changing the Running Configuration . . . . . . . . . 99 E.1.3. Validating the Incoming Configuration . . . . . . . . 107
D.1.6. Testing the New Configuration . . . . . . . . . . . . 100 E.1.4. Checkpointing the Running Configuration . . . . . . . 107
D.1.7. Making the Change Permanent . . . . . . . . . . . . . 100 E.1.5. Changing the Running Configuration . . . . . . . . . 108
D.1.8. Releasing the Configuration Lock . . . . . . . . . . 101 E.1.6. Testing the New Configuration . . . . . . . . . . . . 109
D.2. Operations on Multiple Devices . . . . . . . . . . . . . 101 E.1.7. Making the Change Permanent . . . . . . . . . . . . . 109
Appendix E. Deferred Features . . . . . . . . . . . . . . . . . 103 E.1.8. Releasing the Configuration Lock . . . . . . . . . . 110
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 104 E.2. Operations on Multiple Devices . . . . . . . . . . . . . 110
Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 112
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 113
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 12, line 12 skipping to change at page 13, line 12
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,
saved, and manipulated with both traditional text tools and tools saved, and manipulated with both traditional text tools and tools
specific to XML. specific to XML.
All NETCONF messages MUST be well-formed XML, encoded in UTF-8.
A NETCONF message MAY begin with an XML declaration (see section 2.8
of [1]).
This section discusses a small number of XML-related considerations This section discusses a small number of XML-related considerations
pertaining to NETCONF. pertaining to NETCONF.
3.1. Namespace 3.1. Namespace
All NETCONF protocol elements are defined in the following namespace: All NETCONF protocol elements are defined in the following namespace:
urn:ietf:params:xml:ns:netconf:base:1.0 urn:ietf:params:xml:ns:netconf:base:1.0
NETCONF capability names MUST be URIs [5]. NETCONF capabilities are NETCONF capability names MUST be URIs [5]. NETCONF capabilities are
skipping to change at page 13, line 11 skipping to change at page 14, line 11
3.2. No Document Type Declarations 3.2. No Document Type Declarations
Document type declarations MUST NOT appear in NETCONF content. Document type declarations MUST NOT appear in NETCONF content.
4. RPC Model 4. RPC Model
The NETCONF protocol uses an RPC-based communication model. NETCONF The NETCONF protocol uses an RPC-based communication model. NETCONF
peers use <rpc> and <rpc-reply> elements to provide transport peers use <rpc> and <rpc-reply> elements to provide transport
protocol-independent framing of NETCONF requests and responses. protocol-independent framing of NETCONF requests and responses.
The syntax and XML encoding of the RPC layer messages are formally
defined in the XML schema in Appendix B.
4.1. <rpc> Element 4.1. <rpc> Element
The <rpc> element is used to enclose a NETCONF request sent from the The <rpc> element is used to enclose a NETCONF request sent from the
client to the server. client to the server.
The <rpc> element has a mandatory attribute "message-id", which is an The <rpc> element has a mandatory attribute "message-id", which is an
arbitrary string chosen by the sender of the RPC that will commonly arbitrary string chosen by the sender of the RPC that will commonly
encode a monotonically increasing integer. The receiver of the RPC encode a monotonically increasing integer. The receiver of the RPC
does not decode or interpret this string but simply saves it to be does not decode or interpret this string but simply saves it to be
used as a "message-id" attribute in any resulting <rpc-reply> used as a "message-id" attribute in any resulting <rpc-reply>
skipping to change at page 14, line 31 skipping to change at page 15, line 32
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 peer MUST also return any additional attributes included in
the <rpc> element unmodified in the <rpc-reply> element. the <rpc> element unmodified in the <rpc-reply> element.
The response name and response data are encoded as the contents of The response data is encoded as one or more child elements to the
the <rpc-reply> element. The name of the reply is an element <rpc-reply> element.
directly inside the <rpc-reply> element, and any data is encoded
inside this 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
requested content. requested content.
<rpc message-id="101" <rpc message-id="101"
skipping to change at page 15, line 45 skipping to change at page 16, line 45
A server MUST NOT return application-level- or data-model-specific A server MUST NOT return application-level- or data-model-specific
error information in an <rpc-error> element for which the client does error information in an <rpc-error> element for which the client does
not have sufficient access rights. not have sufficient access rights.
The <rpc-error> element includes the following information: The <rpc-error> element includes the following information:
error-type: Defines the conceptual layer that the error occurred. error-type: Defines the conceptual layer that the error occurred.
Enumeration. One of: Enumeration. One of:
* transport * transport (layer: transport protocol)
* rpc * rpc (layer: rpc)
* protocol * protocol (layer: operations)
* application * application (layer: content)
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
skipping to change at page 16, line 26 skipping to change at page 17, line 26
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.
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 can be will not be present if no appropriate payload element can be
associated with a particular error condition, or if the associated with a particular error condition, or if the
'bad-element' QString returned in the 'error-info' container is 'bad-element' QName returned in the 'error-info' container is
sufficient to identify the node associated with the error. When sufficient to identify the node associated with the error.
the XPath expression is interpreted, the set of namespace
declarations are those in scope on the rpc-error element, The XPath expression is interpreted in the following context:
including the default namespace.
* The set of namespace declarations are those in scope on the
rpc-error element.
* The set of variable bindings is empty.
* The function library is the core function library.
* The context node is the document root node in the rpc request.
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 [12]. defined in [1] and discussed in [12].
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
skipping to change at page 18, line 48 skipping to change at page 19, line 48
</address> </address>
</interface> </interface>
</top> </top>
</error-info> </error-info>
</rpc-error> </rpc-error>
</rpc-reply> </rpc-reply>
4.4. <ok> Element 4.4. <ok> Element
The <ok> element is sent in <rpc-reply> messages if no errors or The <ok> element is sent in <rpc-reply> messages if no errors or
warnings occurred during the processing of an <rpc> request. For warnings occurred during the processing of an <rpc> request, and no
example: data was returned from the operation. For example:
<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>
4.5. Pipelining 4.5. Pipelining
NETCONF <rpc> requests MUST be processed serially by the managed NETCONF <rpc> requests MUST be processed serially by the managed
device. Additional <rpc> requests MAY be sent before previous ones device. Additional <rpc> requests MAY be sent before previous ones
skipping to change at page 29, line 25 skipping to change at page 30, line 25
</users> </users>
</top> </top>
</filter> </filter>
</get-config> </get-config>
</rpc> </rpc>
6.4.4. Select All <name> Elements within the <users> Subtree 6.4.4. Select All <name> Elements within the <users> Subtree
This filter contains two containment nodes (<users>, <user>) and one This filter contains two containment nodes (<users>, <user>) and one
selection node (<name>). All instances of the <name> element in the selection node (<name>). All instances of the <name> element in the
same sibling set are selected in the filter output. The manager may same sibling set are selected in the filter output. The client may
need to know that <name> is used as an instance identifier in this need to know that <name> is used as an instance identifier in this
particular data structure, but the server does not need to know that particular data structure, but the server does not need to know that
meta-data in order to process the request. meta-data in order to process the request.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config> <get-config>
<source> <source>
<running/> <running/>
</source> </source>
skipping to change at page 36, line 39 skipping to change at page 37, line 39
o close-session o close-session
o kill-session o kill-session
A protocol operation may fail for various reasons, including A protocol operation may fail for various reasons, including
"operation not supported". An initiator should not assume that any "operation not supported". An initiator should not assume that any
operation will always succeed. The return values in any RPC reply operation will always succeed. The return values in any RPC reply
should be checked for error responses. should be checked for error responses.
The syntax and XML encoding of the protocol operations are formally The syntax and XML encoding of the protocol operations are formally
defined in the XML schema in Appendix B. The following sections defined in the YANG module in Appendix C. The following sections
describe the semantics of each protocol operation. describe the semantics of each protocol operation.
7.1. <get-config> 7.1. <get-config>
Description: Description:
Retrieve all or part of a specified configuration. Retrieve all or part of a specified configuration.
Parameters: Parameters:
source: source:
Name of the configuration datastore being queried, such as Name of the configuration datastore being queried, such as
<running/>. <running/>.
filter: filter:
The filter element identifies the portions of the device This parameter identifies the portions of the device
configuration to retrieve. If this element is unspecified, the configuration to retrieve. If this parameter is not present,
entire configuration is returned. the entire configuration is returned.
The filter element may optionally contain a "type" attribute. The filter element may optionally contain a "type" attribute.
This attribute indicates the type of filtering syntax used This attribute indicates the type of filtering syntax used
within the filter element. The default filtering mechanism in within the filter element. The default filtering mechanism in
NETCONF is referred to as subtree filtering and is described in NETCONF is referred to as subtree filtering and is described in
Section 6. The value "subtree" explicitly identifies this type Section 6. The value "subtree" explicitly identifies this type
of filtering. of filtering.
If the NETCONF peer supports the :xpath capability If the NETCONF peer supports the :xpath capability
(Section 8.9), the value "xpath" may be used to indicate that (Section 8.9), the value "xpath" may be used to indicate that
skipping to change at page 41, line 41 skipping to change at page 42, line 41
advertises the :validate capability (Section 8.6). advertises the :validate 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
attempting to set.
error-option: error-option:
The error-option element has one of the following values: The error-option element has one of the following values:
stop-on-error: Abort the edit-config operation on first error. stop-on-error: Abort the edit-config operation on first error.
This is the default error-option. This is the default error-option.
continue-on-error: Continue to process configuration data on continue-on-error: Continue to process configuration data on
error; error is recorded, and negative response is generated error; error is recorded, and negative response is generated
if any errors occur. if any errors occur.
skipping to change at page 47, line 19 skipping to change at page 48, line 19
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:
Name of the configuration datastore to use as the source of the Name of the configuration datastore to use as the source of the
copy operation or the <config> element containing the copy operation, or the <config> element containing the complete
configuration subtree to copy. configuration to copy.
Positive Response: Positive Response:
If the device was able to satisfy the request, an <rpc-reply> is If the device was able to satisfy the request, an <rpc-reply> is
sent that includes an <ok> element. sent that includes an <ok> element.
Negative Response: Negative Response:
An <rpc-error> element is included within the <rpc-reply> if the An <rpc-error> element is included within the <rpc-reply> if the
request cannot be completed for any reason. request cannot be completed for any reason.
skipping to change at page 53, line 9 skipping to change at page 54, line 9
Description: Description:
Retrieve running configuration and device state information. Retrieve running configuration and device state information.
Parameters: Parameters:
filter: filter:
This parameter specifies the portion of the system This parameter specifies the portion of the system
configuration and state data to retrieve. If this parameter is configuration and state data to retrieve. If this parameter is
empty, all the device configuration and state information is not present, all the device configuration and state information
returned. is returned.
The filter element may optionally contain a 'type' attribute. The filter element may optionally contain a 'type' attribute.
This attribute indicates the type of filtering syntax used This attribute indicates the type of filtering syntax used
within the filter element. The default filtering mechanism in within the filter element. The default filtering mechanism in
NETCONF is referred to as subtree filtering and is described in NETCONF is referred to as subtree filtering and is described in
Section 6. The value 'subtree' explicitly identifies this type Section 6. The value 'subtree' explicitly identifies this type
of filtering. of filtering.
If the NETCONF peer supports the :xpath capability If the NETCONF peer supports the :xpath capability
(Section 8.9), the value "xpath" may be used to indicate that (Section 8.9), the value "xpath" may be used to indicate that
skipping to change at page 57, line 15 skipping to change at page 58, line 15
8. Capabilities 8. Capabilities
This section defines a set of capabilities that a client or a server This section defines a set of capabilities that a client or a server
MAY implement. Each peer advertises its capabilities by sending them MAY implement. Each peer advertises its capabilities by sending them
during an initial capabilities exchange. Each peer needs to during an initial capabilities exchange. Each peer needs to
understand only those capabilities that it might use and MUST ignore understand only those capabilities that it might use and MUST ignore
any capability received from the other peer that it does not require any capability received from the other peer that it does not require
or does not understand. or does not understand.
Additional capabilities can be defined using the template in Additional capabilities can be defined using the template in
Appendix C. 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.0
where {name} is the name of the capability. Capabilities are often where {name} is the name of the capability. Capabilities are often
skipping to change at page 63, line 17 skipping to change at page 64, line 17
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. Note that any commit operation, including a commit which
introduces additional changes to the configuration, will serve as a introduces additional changes to the configuration, will serve as a
confirming commit. Thus to cancel a confirmed commit and revert confirming commit. Thus to cancel a confirmed commit and revert
changes without waiting for the confirm timeout to expire, the changes without waiting for the confirm timeout to expire, the client
manager can explicitly restore the configuration to its state before can explicitly restore the configuration to its state before the
the confirmed commit was issued. 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.
8.4.2. Dependencies 8.4.2. Dependencies
skipping to change at page 65, line 50 skipping to change at page 66, line 50
<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. Validate Capability 8.6. Validate Capability
8.6.1. Description 8.6.1. Description
Validation consists of checking a candidate 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
contains all of version 1.0, and adds a new value, "test-only", to
the test-option parameter. Servers SHOULD implement and advertise
version 1.1, and MAY, for backwards compatibility, also advertise
version 1.0. Note that both versions can be advertised at the same
time.
8.6.2. Dependencies 8.6.2. Dependencies
None. None.
8.6.3. Capability Identifier 8.6.3. Capability Identifier
The :validate capability is identified by the following capability Version 1.0 of the :validate capability is identified by the
string: following capability string:
urn:ietf:params:netconf:capability:validate:1.0 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
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
configuration. configuration.
Parameters: Parameters:
source: source:
Name of the configuration datastore being validated, such as Name of the configuration datastore to validate, such as
<candidate> or the <config> element containing the <candidate>, or the <config> element containing the complete
configuration subtree to validate. configuration to validate.
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.
Negative Response: Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason. request cannot be completed for any reason.
skipping to change at page 67, line 27 skipping to change at page 68, line 39
<candidate/> <candidate/>
</source> </source>
</validate> </validate>
</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>
8.6.5. Modifications to Existing Operations
8.6.5.1. <edit-config>
The :validate capability modifies the <edit-config> operation to
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 reboots. Operations that affect the running configuration will it boots. Operations that affect the running configuration will not
not be automatically copied to the startup configuration. An be automatically copied to the startup configuration. An explicit
explicit <copy-config> operation from the <running> to the <startup> <copy-config> operation from the <running> to the <startup> must be
must be invoked to update the startup configuration to the current invoked to update the startup configuration to the current contents
contents of the running configuration. NETCONF protocol operations of the running configuration. NETCONF protocol operations refer to
refer to the startup datastore using the <startup> element. the startup datastore using the <startup> element.
8.7.2. Dependencies 8.7.2. Dependencies
None. None.
8.7.3. Capability Identifier 8.7.3. Capability Identifier
The :startup capability is identified by the following capability The :startup capability is identified by the following capability
string: string:
skipping to change at page 68, line 31 skipping to change at page 69, line 47
| | | | | | | |
| <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 is |
| | | advertised | | | | advertised |
| | | | | | | |
| | <delete-config> | <target> | | <delete-config> | <target> | Resets the device |
| | | | | | | to its factory |
| Resets the device | | | | | | defaults |
| to its factory | | |
| 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"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config> <copy-config>
<target> <target>
<startup/> <startup/>
</target> </target>
skipping to change at page 70, line 19 skipping to change at page 71, line 38
<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 XPath expression must return a node-set. 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
used by XSLT 1.0 [8] (section 3.1). Specifically, it means that the
root node may have any number of element nodes as its children.
The XPath expression is evaluated in a context where the context node The XPath expression is evaluated in the following context:
is the root node, and the set of namespace declarations are those in
scope on the filter element, including the default namespace. o The set of namespace declarations are those in scope on the filter
element.
o The set of variable bindings is defined by the data model. If no
such variable bindings are defined, the set is empty.
o The function library is the core function library, plus any
functions defined by the data model.
o The context node is the root node.
The XPath expression MUST return a node set. If it does not return a
node set, the operation fails with an "invalid-value" error.
8.9.2. Dependencies 8.9.2. Dependencies
None. None.
8.9.3. Capability Identifier 8.9.3. Capability Identifier
The :xpath capability is identified by the following capability The :xpath capability is identified by the following capability
string: string:
skipping to change at page 75, line 22 skipping to change at page 77, line 22
| | :1.0 | | | :1.0 |
| | | | | |
| :confirmed-commit | urn:ietf:params:netconf:capability:confirmed | | :confirmed-commit | urn:ietf:params:netconf:capability:confirmed |
| | -commit:1.0 | | | -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: | | :validate | urn:ietf:params:netconf:capability:validate: |
| | 1.0 | | | 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. Index value: The capability name.
skipping to change at page 77, line 9 skipping to change at page 79, line 9
for his persistance and patience in assisting us with security for his persistance 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] Paoli, J., Sperberg-McQueen, C., Maler, E., and T. Bray, [1] Bray, T., Sperberg-McQueen, C., Paoli, J., and E. Maler,
"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] Clark, J. and S. DeRose, "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
Levels", BCP 14, RFC 2119, March 1997. Levels", BCP 14, RFC 2119, March 1997.
[4] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration [4] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration
Protocol over Secure SHell (SSH)", RFC 4742, December 2006. Protocol over Secure SHell (SSH)", RFC 4742, December 2006.
skipping to change at page 80, line 6 skipping to change at page 82, line 6
Tag: unknown-attribute Tag: unknown-attribute
Error-type: rpc, protocol, application Error-type: rpc, protocol, application
Severity: 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.
Tag: missing-element Tag: missing-element
Error-type: rpc, protocol, application Error-type: protocol, application
Severity: 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.
Tag: bad-element Tag: bad-element
Error-type: rpc, protocol, application Error-type: protocol, application
Severity: 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.
Tag: unknown-element Tag: unknown-element
Error-type: rpc, protocol, application Error-type: protocol, application
Severity: 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.
Tag: unknown-namespace Tag: unknown-namespace
Error-type: rpc, protocol, application Error-type: protocol, application
Severity: 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.
Tag: access-denied Tag: access-denied
Error-type: rpc, protocol, application Error-type: protocol, application
Severity: error Severity: error
Error-info: none Error-info: none
Description: Access to the requested RPC, protocol operation, Description: Access to the requested protocol operation,
or data model is denied because authorization failed. or data model is denied because authorization failed.
Tag: lock-denied Tag: lock-denied
Error-type: protocol Error-type: protocol
Severity: 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.
skipping to change at page 81, line 33 skipping to change at page 83, line 33
Tag: data-missing Tag: data-missing
Error-type: application Error-type: application
Severity: 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 'replace' or 'delete' operation was attempted on a 'replace' or 'delete' operation was attempted on
data that does not exist. data that does not exist.
Tag: operation-not-supported Tag: operation-not-supported
Error-type: rpc, protocol, application Error-type: protocol, application
Severity: 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.
Tag: operation-failed Tag: operation-failed
Error-type: rpc, protocol, application Error-type: rpc, protocol, application
Severity: 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
skipping to change at page 83, line 5 skipping to change at page 85, line 5
Description: Some part of the requested operation failed or was Description: Some part of the requested operation failed or was
not attempted for some reason. Full cleanup has not attempted for some reason. Full cleanup has
not been performed (e.g., rollback not supported) not been performed (e.g., rollback not supported)
by the server. The error-info container is used by the server. The error-info container is used
to identify which portions of the application to identify which portions of the application
data model content for which the requested operation data model content for which the requested operation
has succeeded (<ok-element>), failed (<bad-element>), has succeeded (<ok-element>), failed (<bad-element>),
or not been attempted (<noop-element>). or not been attempted (<noop-element>).
Appendix B. XML Schema for NETCONF RPC and Protocol Operations Appendix B. XML Schema for NETCONF RPC Layer
This section is normative. This section is normative.
BEGIN BEGIN
<?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">
<xs:annotation>
<xs:documentation>
This schema defines the syntax for the NETCONF RPC layer
messages.
</xs:documentation>
</xs:annotation>
<!-- <!--
import standard XML definitions import standard XML definitions
--> -->
<xs:import namespace="http://www.w3.org/XML/1998/namespace" <xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"> schemaLocation="http://www.w3.org/2001/xml.xsd">
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
This import accesses the xml: attribute groups for the This import accesses the xml: attribute groups for the
xml:lang as declared on the error-message element. xml:lang as declared on the error-message element.
</xs:documentation> </xs:documentation>
skipping to change at page 86, line 27 skipping to change at page 88, line 35
<!-- <!--
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:element name="data" type="dataInlineType" minOccurs="0"/> <xs:choice>
<xs:any namespace="##any" processContents="lax"
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"/>
<!-- <!--
Type for <test-option> parameter to <edit-config>
-->
<xs:simpleType name="testOptionType">
<xs:restriction base="xs:string">
<xs:enumeration value="test-then-set"/>
<xs:enumeration value="set"/>
</xs:restriction>
</xs:simpleType>
<!--
Type for <error-option> parameter to <edit-config>
-->
<xs:simpleType name="errorOptionType">
<xs:restriction base="xs:string">
<xs:annotation>
<xs:documentation>
Use of the rollback-on-error value requires
the :rollback-on-error capability.
</xs:documentation>
</xs:annotation>
<xs:enumeration value="stop-on-error"/>
<xs:enumeration value="continue-on-error"/>
<xs:enumeration value="rollback-on-error"/>
</xs:restriction>
</xs:simpleType>
<!--
rpcOperationType: used as a base type for all rpcOperationType: used as a base type for all
NETCONF operations NETCONF operations
--> -->
<xs:complexType name="rpcOperationType"/> <xs:complexType name="rpcOperationType"/>
<xs:element name="rpcOperation" <xs:element name="rpcOperation"
type="rpcOperationType" abstract="true"/> type="rpcOperationType" abstract="true"/>
<!-- <!--
Type for <config> element
-->
<xs:complexType name="configInlineType">
<xs:complexContent>
<xs:extension base="xs:anyType"/>
</xs:complexContent>
</xs:complexType>
<!--
Type for <data> element
-->
<xs:complexType name="dataInlineType">
<xs:complexContent>
<xs:extension base="xs:anyType"/>
</xs:complexContent>
</xs:complexType>
<!--
Type for <filter> element
-->
<xs:simpleType name="FilterType">
<xs:restriction base="xs:string">
<xs:annotation>
<xs:documentation>
Use of the xpath value requires the :xpath capability.
</xs:documentation>
</xs:annotation>
<xs:enumeration value="subtree"/>
<xs:enumeration value="xpath"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="filterInlineType">
<xs:complexContent>
<xs:extension base="xs:anyType">
<xs:attribute name="type"
type="FilterType" default="subtree"/>
<!-- if type="xpath", the xpath expression
appears in the select element -->
<xs:attribute name="select"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<!--
configuration datastore names
-->
<xs:annotation>
<xs:documentation>
The startup datastore can be used only if the :startup
capability is advertised. The candidate datastore can
be used only if the :candidate datastore is advertised.
</xs:documentation>
</xs:annotation>
<xs:complexType name="configNameType"/>
<xs:element name="config-name"
type="configNameType" abstract="true"/>
<xs:element name="startup" type="configNameType"
substitutionGroup="config-name"/>
<xs:element name="candidate" type="configNameType"
substitutionGroup="config-name"/>
<xs:element name="running" type="configNameType"
substitutionGroup="config-name"/>
<!--
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:restriction>
</xs:simpleType>
<xs:attribute name="operation"
type="editOperationType" default="merge"/>
<!--
<default-operation> element
-->
<xs:simpleType name="defaultOperationType">
<xs:restriction base="xs:string">
<xs:enumeration value="merge"/>
<xs:enumeration value="replace"/>
<xs:enumeration value="none"/>
</xs:restriction>
</xs:simpleType>
<!--
<url> element
-->
<xs:complexType name="configURIType">
<xs:annotation>
<xs:documentation>
Use of the url element requires the :url capability.
</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:anyURI"/>
</xs:simpleContent>
</xs:complexType>
<!--
Type for <source> element (except <get-config>)
-->
<xs:complexType name="rpcOperationSourceType">
<xs:choice>
<xs:element name="config" type="configInlineType"/>
<xs:element ref="config-name"/>
<xs:element name="url" type="configURIType"/>
</xs:choice>
</xs:complexType>
<!--
Type for <source> element in <get-config>
-->
<xs:complexType name="getConfigSourceType">
<xs:choice>
<xs:element ref="config-name"/>
<xs:element name="url" type="configURIType"/>
</xs:choice>
</xs:complexType>
<!--
Type for <target> element
-->
<xs:complexType name="rpcOperationTargetType">
<xs:choice>
<xs:element ref="config-name"/>
<xs:element name="url" type="configURIType"/>
</xs:choice>
</xs:complexType>
<!--
<get-config> operation
-->
<xs:complexType name="getConfigType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="source"
type="getConfigSourceType"/>
<xs:element name="filter"
type="filterInlineType" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="get-config" type="getConfigType"
substitutionGroup="rpcOperation"/>
<!--
<edit-config> operation
-->
<xs:complexType name="editConfigType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:annotation>
<xs:documentation>
Use of the test-option element requires the
:validate capability. Use of the url element
requires the :url capability.
</xs:documentation>
</xs:annotation>
<xs:element name="target"
type="rpcOperationTargetType"/>
<xs:element name="default-operation"
type="defaultOperationType"
minOccurs="0"/>
<xs:element name="test-option"
type="testOptionType"
minOccurs="0"/>
<xs:element name="error-option"
type="errorOptionType"
minOccurs="0"/>
<xs:choice>
<xs:element name="config"
type="configInlineType"/>
<xs:element name="url"
type="configURIType"/>
</xs:choice>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="edit-config" type="editConfigType"
substitutionGroup="rpcOperation"/>
<!--
<copy-config> operation
-->
<xs:complexType name="copyConfigType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="target" type="rpcOperationTargetType"/>
<xs:element name="source" type="rpcOperationSourceType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="copy-config" type="copyConfigType"
substitutionGroup="rpcOperation"/>
<!--
<delete-config> operation
-->
<xs:complexType name="deleteConfigType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="target" type="rpcOperationTargetType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="delete-config" type="deleteConfigType"
substitutionGroup="rpcOperation"/>
<!--
<get> operation
-->
<xs:complexType name="getType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="filter"
type="filterInlineType" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="get" type="getType"
substitutionGroup="rpcOperation"/>
<!--
<lock> operation
-->
<xs:complexType name="lockType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="target"
type="rpcOperationTargetType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="lock" type="lockType"
substitutionGroup="rpcOperation"/>
<!--
<unlock> operation
-->
<xs:complexType name="unlockType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="target" type="rpcOperationTargetType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="unlock" type="unlockType"
substitutionGroup="rpcOperation"/>
<!--
<validate> operation
-->
<xs:complexType name="validateType">
<xs:annotation>
<xs:documentation>
The validate operation requires the :validate capability.
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="source" type="rpcOperationSourceType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="validate" type="validateType"
substitutionGroup="rpcOperation"/>
<!--
<commit> operation
-->
<xs:simpleType name="confirmTimeoutType">
<xs:restriction base="xs:unsignedInt">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="commitType">
<xs:annotation>
<xs:documentation>
The commit operation requires the :candidate capability.
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:annotation>
<xs:documentation>
Use of the confirmed and confirm-timeout elements
requires the :confirmed-commit capability.
</xs:documentation>
</xs:annotation>
<xs:element name="confirmed" minOccurs="0"/>
<xs:element name="confirm-timeout"
type="confirmTimeoutType"
minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="commit" type="commitType"
substitutionGroup="rpcOperation"/>
<!--
<discard-changes> operation
-->
<xs:complexType name="discardChangesType">
<xs:annotation>
<xs:documentation>
The discard-changes operation requires the
:candidate capability.
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="rpcOperationType"/>
</xs:complexContent>
</xs:complexType>
<xs:element name="discard-changes"
type="discardChangesType"
substitutionGroup="rpcOperation"/>
<!--
<close-session> operation
-->
<xs:complexType name="closeSessionType">
<xs:complexContent>
<xs:extension base="rpcOperationType"/>
</xs:complexContent>
</xs:complexType>
<xs:element name="close-session" type="closeSessionType"
substitutionGroup="rpcOperation"/>
<!--
<kill-session> operation
-->
<xs:complexType name="killSessionType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="session-id"
type="SessionId" minOccurs="1"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="kill-session" type="killSessionType"
substitutionGroup="rpcOperation"/>
<!--
<hello> element <hello> element
--> -->
<xs:element name="hello"> <xs:element name="hello">
<xs:complexType> <xs:complexType>
<xs:sequence> <xs:sequence>
<xs:element name="capabilities"> <xs:element name="capabilities">
<xs:complexType> <xs:complexType>
<xs:sequence> <xs:sequence>
<xs:element name="capability" type="xs:anyURI" <xs:element name="capability" type="xs:anyURI"
maxOccurs="unbounded"/> maxOccurs="unbounded"/>
skipping to change at page 95, line 5 skipping to change at page 90, line 5
</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 END
Appendix C. Capability Template Appendix C. YANG Module for NETCONF Protocol Operations
This section is normative.
BEGIN
module ietf-netconf {
namespace "urn:ietf:params:xml:ns:netconf:base:1.0";
prefix nc;
// for the uri data type
import ietf-inet-types { prefix inet; }
description
"NETCONF Protocol Data Types and RPC methods.
Copyright (c) 2009 IETF Trust and the persons identified as
the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:
- Redistributions of source code must retain the above
copyright notice, this list of conditions and the
following disclaimer.
- Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other
materials provided with the distribution.
- Neither the name of Internet Society, IETF or IETF
Trust, nor the names of specific contributors, may be
used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED
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
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this note
reference "draft-ietf-netconf-rfc4741bis-01.txt";
contact
"Send comments to the NETCONF WG mailing list.
<netconf@ietf.org>";
revision 2009-06-27 {
description
"Initial version";
}
extension get-filter-element-attributes {
description
"If this extension is present within the
an 'anyxml' statement named 'filter', which must be
conceptually defined within the RPC input section
for the 'get' and 'get-config' RPC operations,
then the following unqualified XML attribute is
supported within the 'filter' element, within
a 'get' or 'get-config' protocol operation:
type : optional attribute with allowed
value strings 'subtree' and 'xpath'.
If missing, the default value is 'subtree'.
If the xpath feature is supported, then the
following unqualified XML attribute is
also supported:
select: optional attribute containing a
string representing an XPath expression.
The 'type' attribute must be equal to 'xpath'
if this attribute is present.";
}
// NETCONF capabilities defined as features
feature writable-running {
description
"NETCONF :writable-running capability;
If the agent advertises the :writable-running
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
// RFC Ed.: replace XXXX with actual RFC number and
// remove this note
reference "RFC XXXX, section 8.2.";
}
feature candidate {
description
"NETCONF :candidate capability;
If the agent 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 {
description
"NETCONF :confirmed-commit capability;
If the agent advertises the :cornfirmed-commit
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.4.";
if-feature candidate;
}
feature rollback-on-error {
description
"NETCONF :rollback-on-error capability;
If the agent 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 {
status "deprecated";
description
"NETCONF :validate:1.0 capability;
If the agent advertises the :validate:1.0
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.6.";
}
feature validate-1.1 {
description
"NETCONF :validate:1.1 capability;
If the agent advertises the :validate:1.1
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.6.";
}
feature startup {
description
"NETCONF :startup capability;
If the agent advertises the :startup
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.7.";
}
feature url {
description
"NETCONF :url capability;
If the agent advertises the :url
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.8.";
}
feature xpath {
description
"NETCONF :xpath capability;
If the agent advertises the :xpath
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, section 8.9.";
}
// NETCONF Simple Types
typedef session-id-type {
description "NETCONF Session Id";
type uint32 {
range "1..max";
}
}
typedef session-id-or-zero-type {
description
"NETCONF Session Id or Zero to indicate none";
type uint32;
}
// NETCONF Standard RPC Methods
rpc get-config {
description
"Retrieve all or part of a specified configuration.";
reference "RFC XXXX, section 7.1.";
input {
container source {
description "Particular configuration to retrieve.";
choice config-source {
mandatory true;
leaf candidate {
if-feature candidate;
type empty;
}
leaf running {
type empty;
}
leaf startup {
if-feature startup;
description
"This is optional-to-implement on the agent because
not all agents will support filtering for this
database.";
type empty;
}
leaf url {
if-feature url;
type inet:uri;
}
}
}
anyxml filter {
description "Subtree or Xpath filter to use.";
nc:get-filter-element-attributes;
}
}
output {
container data {
description
"Copy of the source database subset which matched
the filter criteria (if any).";
presence
"An empty data container indicates that the
request did not produce any results.";
}
}
}
rpc edit-config {
description
"The 'edit-config' operation loads all or part of a specified
configuration to the specified target configuration.";
reference "RFC XXXX, section 8.8.5.1.";
input {
container target {
description "Particular configuration to edit.";
choice config-target {
mandatory true;
leaf candidate {
if-feature candidate;
type empty;
}
leaf running {
if-feature writable-running;
type empty;
}
}
}
leaf default-operation {
type enumeration {
enum merge;
enum replace;
enum none;
}
default "merge";
}
leaf test-option {
if-feature validate;
type enumeration {
enum test-then-set;
enum set;
enum test-only {
description
"This value can only be used if the 'validate-1.1'
feature is supported.";
}
}
}
leaf error-option {
type enumeration {
enum stop-on-error;
enum continue-on-error;
enum rollback-on-error {
description
"This value can only be used if the 'rollback-on-error'
feature is supported.";
}
}
default "stop-on-error";
}
choice edit-content {
mandatory true;
anyxml config {
description
"Inline Config content: 'config' element.
This is not full 'anyxml' because the <config>
element cannot directly contain a text node.";
}
leaf url {
if-feature url;
description
"Pointer to Config content: 'url' element.";
type inet:uri;
}
}
}
}
rpc copy-config {
description
"Create or replace an entire configuration datastore with the
contents of another complete configuration datastore.";
reference "RFC XXXX, section 8.8.5.2.";
input {
container target {
description "Particular configuration to copy to.";
choice config-target {
mandatory true;
leaf candidate {
if-feature candidate;
type empty;
}
leaf running {
if-feature writable-running;
description
"This is optional-to-implement on the agent.";
type empty;
}
leaf startup {
if-feature startup;
type empty;
}
leaf url {
if-feature url;
type inet:uri;
}
}
}
container source {
description "Particular configuration to copy from.";
choice config-source {
mandatory true;
leaf candidate {
if-feature candidate;
type empty;
}
leaf running {
type empty;
}
leaf startup {
if-feature startup;
type empty;
}
leaf url {
if-feature url;
type inet:uri;
}
}
}
}
}
rpc delete-config {
description
"Delete a configuration datastore.";
reference "RFC XXXX, section 8.8.5.3.";
input {
container target {
description "Particular configuration to delete.";
choice config-target {
mandatory true;
leaf startup {
if-feature startup;
type empty;
}
leaf url {
if-feature url;
type inet:uri;
}
}
}
}
}
rpc lock {
description
"The lock operation allows the client to lock the configuration
system of a device.";
reference "RFC XXXX, section 7.5.";
input {
container target {
description "Particular configuration to lock";
choice config-target {
mandatory true;
leaf candidate {
if-feature candidate;
type empty;
}
leaf running {
type empty;
}
leaf startup {
if-feature startup;
type empty;
}
leaf url {
if-feature url;
type inet:uri;
}
}
}
}
}
rpc unlock {
description
"The unlock operation is used to release a configuration lock,
previously obtained with the 'lock' operation.";
reference "RFC XXXX, section 7.6.";
input {
container target {
description "Particular configuration to unlock.";
choice config-target {
mandatory true;
leaf candidate {
if-feature candidate;
type empty;
}
leaf running {
type empty;
}
leaf startup {
if-feature startup;
type empty;
}
leaf url {
if-feature url;
type inet:uri;
}
}
}
}
}
rpc get {
description
"Retrieve running configuration and device state information.";
reference "RFC XXXX, section 7.7.";
input {
anyxml filter {
description
"This parameter specifies the portion of the system
configuration and state data to retrieve.";
nc:get-filter-element-attributes;
}
}
output {
container data {
description
"Copy of the 'running' database subset and/or state
data which matched the filter criteria (if any).";
presence
"An empty data container indicates that the filter
request did not match any results.";
}
}
}
rpc close-session {
description
"Request graceful termination of a NETCONF session.";
reference "RFC XXXX, section 7.8.";
}
rpc kill-session {
description
"Force the termination of a NETCONF session.";
reference "RFC XXXX, section 7.9.";
input {
leaf session-id {
description "Particular session to kill.";
type session-id-type;
mandatory true;
}
}
}
rpc commit {
if-feature candidate;
description
"Commit the candidate configuration as the device's new
current configuration";
reference "RFC XXXX, section 8.4.5.1.";
input {
leaf confirmed {
if-feature confirmed-commit;
reference "RFC XXXX, section 8.4.5.1.";
type empty;
}
leaf confirm-timeout {
if-feature confirmed-commit;
reference "RFC XXXX, section 8.4.5.1.";
type uint32 {
range "1..max";
}
units "seconds";
default "600"; // 10 minutes
}
}
}
rpc discard-changes {
if-feature candidate;
description
"Revert the candidate configuration to the current
running configuration.";
reference "RFC XXXX, section 8.3.4.2.";
}
rpc validate {
if-feature validate;
description
"Validates the contents of the specified configuration.";
reference "RFC XXXX, section 8.8.5.4.";
input {
container source {
description "Particular configuration to validate.";
choice config-source {
mandatory true;
leaf candidate {
if-feature candidate;
type empty;
}
leaf running {
// ed: not sure why this is here, since the
// running config should be valid all the time
type empty;
}
leaf startup {
if-feature startup;
type empty;
}
leaf url {
if-feature url;
type inet:uri;
}
anyxml config {
description
"Inline Config content: 'config' element.
Represents an entire 'stand-alone'
configuration database, not a subset of
the running database.";
}
}
}
}
}
}
END
Appendix D. Capability Template
This section is non-normative. This section is non-normative.
C.1. capability-name (template) D.1. capability-name (template)
C.1.1. Overview D.1.1. Overview
C.1.2. Dependencies D.1.2. Dependencies
C.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
string: string:
{capability uri} {capability uri}
C.1.4. New Operations D.1.4. New Operations
C.1.4.1. <op-name> D.1.4.1. <op-name>
C.1.5. Modifications to Existing Operations D.1.5. Modifications to Existing Operations
C.1.5.1. <op-name> D.1.5.1. <op-name>
If existing operations are not modified by this capability, this If existing operations are not modified by this capability, this
section may be omitted. section may be omitted.
C.1.6. Interactions with Other Capabilities D.1.6. Interactions with Other Capabilities
If this capability does not interact with other capabilities, this If this capability does not interact with other capabilities, this
section may be omitted. section may be omitted.
Appendix D. Configuring Multiple Devices with NETCONF Appendix E. Configuring Multiple Devices with NETCONF
This section is non-normative. This section is non-normative.
D.1. Operations on Individual Devices E.1. Operations on Individual Devices
Consider the work involved in performing a configuration update Consider the work involved in performing a configuration update
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:
skipping to change at page 96, line 38 skipping to change at page 105, line 38
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.
D.1.1. Acquiring the Configuration Lock E.1.1. Acquiring the Configuration Lock
A lock should be acquired to prevent simultaneous updates from A lock should be acquired to prevent simultaneous updates from
multiple sources. If multiple sources are affecting the device, the multiple sources. If multiple sources are affecting the device, the
application is hampered in both testing of its change to the application is hampered in both testing of its change to the
configuration and in recovery should the update fail. Acquiring a configuration and in recovery should the update fail. Acquiring a
short-lived lock is a simple defense to prevent other parties from short-lived lock is a simple defense to prevent other parties from
introducing unrelated changes. introducing unrelated changes.
The lock can be acquired using the <lock> operation. The lock can be acquired using the <lock> 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">
<lock> <lock>
<target> <target>
<running/> <running/>
</target> </target>
</lock> </lock>
</rpc> </rpc>
D.1.2. Loading the Update E.1.2. Loading the Update
The configuration can be loaded onto the device without impacting the The configuration can be loaded onto the device without impacting the
running system. If the :url capability is supported and lists "file" running system. If the :url capability is supported and lists "file"
as a supported scheme, incoming changes can be placed in a local as a supported scheme, incoming changes can be placed in a local
file. file.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config> <copy-config>
<target> <target>
skipping to change at page 98, line 5 skipping to change at page 107, line 5
<config> <config>
<!-- place incoming configuration here --> <!-- place incoming configuration here -->
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
If the update fails, the user file can be deleted using the If the update fails, the user file can be deleted using the
<delete-config> operation, or the candidate configuration can be <delete-config> operation, or the candidate configuration can be
reverted using the <discard-changes> operation. reverted using the <discard-changes> operation.
D.1.3. Validating the Incoming Configuration E.1.3. Validating the Incoming Configuration
Before the incoming configuration is applied, validating it is often Before the incoming configuration is applied, validating it is often
useful. Validation allows the application to gain confidence that useful. Validation allows the application to gain confidence that
the change will succeed and simplifies recovery if it does not. the change will succeed and simplifies recovery if it does not.
If the device supports the :url capability and lists "file" as a If the device supports the :url capability and lists "file" as a
supported scheme, use the <validate> operation with the <source> supported scheme, use the <validate> operation with the <source>
parameter set to the proper user file: parameter set to the proper user file:
<rpc message-id="101" <rpc message-id="101"
skipping to change at page 98, line 39 skipping to change at page 107, line 39
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate> <validate>
<source> <source>
<candidate/> <candidate/>
</source> </source>
</validate> </validate>
</rpc> </rpc>
D.1.4. Checkpointing the Running Configuration E.1.4. 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 99, line 20 skipping to change at page 108, line 20
</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.
D.1.5. Changing the Running Configuration E.1.5. Changing the Running Configuration
When the incoming configuration has been safely loaded onto the When the incoming configuration has been safely loaded onto the
device and validated, it is ready to impact the running system. 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 device supports the :url capability and lists "file" as a
supported scheme, use the <edit-config> operation to merge the supported scheme, use the <edit-config> operation to merge the
incoming configuration into the running configuration. 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">
skipping to change at page 100, line 6 skipping to change at page 109, line 6
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> </rpc>
D.1.6. Testing the New Configuration E.1.6. 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).
D.1.7. Making the Change Permanent E.1.7. 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 101, line 5 skipping to change at page 110, line 5
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>
D.1.8. Releasing the Configuration Lock E.1.8. 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>
D.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.
There are two classes of multi-device operations. The first class There are two classes of multi-device operations. The first class
skipping to change at page 103, line 5 skipping to change at page 112, line 5
across all devices. Configuration locks should be acquired on all across all devices. Configuration locks should be acquired on all
target devices and kept until all devices are updated and the changes target devices and kept until all devices are updated and the changes
made permanent. Configuration changes should be uploaded and made permanent. Configuration changes should be uploaded and
validation performed across all devices. Checkpoints should be made validation performed across all devices. Checkpoints should be made
on each device. Then the running configuration can be changed, on each device. Then the running configuration can be changed,
tested, and made permanent. If any of these steps fail, the previous tested, and made permanent. If any of these steps fail, the previous
configurations can be restored on any devices upon which they were configurations can be restored on any devices upon which they were
changed. After the changes have been completely implemented or changed. After the changes have been completely implemented or
completely discarded, the locks on each device can be released. completely discarded, the locks on each device can be released.
Appendix E. Deferred Features Appendix F. Changes from RFC 4741
The following features have been deferred until a future revision of
this document.
o Granular locking of configuration objects.
o Named configuration files/datastores.
o Support for multiple NETCONF channels.
o Asynchronous notifications.
o Explicit protocol support for rollback of configuration changes to This section lists major changes between this document and RFC 4741.
prior versions. TBD.
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
Martin Bjorklund (editor) Martin Bjorklund (editor)
Tail-f Systems Tail-f Systems
Email: mbj@tail-f.com Email: mbj@tail-f.com
Juergen Schoenwaelder (editor) Juergen Schoenwaelder (editor)
Jacobs University Jacobs University
Email: j.schoenwaelder@jacobs-university.de Email: j.schoenwaelder@jacobs-university.de
Andy Bierman (editor)
Netconf Central
Email: andy@netconfcentral.com
 End of changes. 73 change blocks. 
601 lines changed or deleted 909 lines changed or added

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