< draft-bierman-netconf-efficiency-extensions-01.txt   draft-bierman-netconf-efficiency-extensions-02.txt >
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks, Inc. Internet-Draft YumaWorks, Inc.
Intended status: Standards Track April 21, 2014 Intended status: Standards Track October 21, 2014
Expires: October 23, 2014 Expires: April 24, 2015
NETCONF Efficiency Extensions NETCONF Efficiency Extensions
draft-bierman-netconf-efficiency-extensions-01 draft-bierman-netconf-efficiency-extensions-02
Abstract Abstract
This document describes protocol extensions to improve the efficiency This document describes protocol extensions to improve the efficiency
of the Network Configuration Protocol (NETCONF). Protocol of the Network Configuration Protocol (NETCONF). Protocol
capabilities and operations are defined to reduce network usage and capabilities and operations are defined to reduce network usage and
transaction complexity. transaction complexity.
Status of this Memo Status of this Memo
skipping to change at page 1, line 33 skipping to change at page 1, line 33
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 23, 2014. This Internet-Draft will expire on April 24, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 17 skipping to change at page 2, line 17
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.3. RESTCONF . . . . . . . . . . . . . . . . . . . . . . . 5 1.1.3. RESTCONF . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.4. YANG Patch . . . . . . . . . . . . . . . . . . . . . . 5 1.1.4. YANG Patch . . . . . . . . . . . . . . . . . . . . . . 5
1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 5 1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 5
1.2. Problem Statement . . . . . . . . . . . . . . . . . . . . 6 1.2. Problem Statement . . . . . . . . . . . . . . . . . . . . 6
1.2.1. Initial Configuration Retrieval . . . . . . . . . . . 6 1.2.1. Initial Configuration Retrieval . . . . . . . . . . . 6
1.2.2. Message Encoding . . . . . . . . . . . . . . . . . . . 6 1.2.2. Datastore Editing . . . . . . . . . . . . . . . . . . 6
1.2.3. Datastore Editing . . . . . . . . . . . . . . . . . . 7 1.2.3. Data Retrieval . . . . . . . . . . . . . . . . . . . . 8
1.2.4. Data Retrieval . . . . . . . . . . . . . . . . . . . . 8 1.3. Solution . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3. Solution . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.1. Configuration ID Advertisement . . . . . . . . . . . . 10 1.3.1. Configuration ID Advertisement . . . . . . . . . . . . 10
1.3.2. Message Encoding Negotiation . . . . . . . . . . . . . 10 1.3.2. <edit2> Operation . . . . . . . . . . . . . . . . . . 10
1.3.3. <edit2> Operation . . . . . . . . . . . . . . . . . . 11 1.3.3. <get2> Operation . . . . . . . . . . . . . . . . . . . 10
1.3.4. <get2> Operation . . . . . . . . . . . . . . . . . . . 11 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 11
2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.1. "config-id" Capability . . . . . . . . . . . . . . . . . . 11
2.1. "config-id" Capability . . . . . . . . . . . . . . . . . . 12 2.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 11
2.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 12 2.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . . 12
2.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . . 13 2.1.3. Capability Identifier . . . . . . . . . . . . . . . . 12
2.1.3. Capability Identifier . . . . . . . . . . . . . . . . 13 2.1.4. New Operations . . . . . . . . . . . . . . . . . . . . 12
2.1.4. New Operations . . . . . . . . . . . . . . . . . . . . 14 2.1.5. Modifications to Existing Operations . . . . . . . . . 13
2.1.5. Modifications to Existing Operations . . . . . . . . . 14 2.1.6. Interactions with Other Capabilities . . . . . . . . . 13
2.1.6. Interactions with Other Capabilities . . . . . . . . . 14 2.2. <edit2> Protocol Operation . . . . . . . . . . . . . . . . 13
2.2. "encoding" Capability . . . . . . . . . . . . . . . . . . 14 2.2.1. <edit2> Input . . . . . . . . . . . . . . . . . . . . 13
2.2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.2. <edit2> Output . . . . . . . . . . . . . . . . . . . . 14
2.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . 16 2.2.3. <edit2> YANG Tree Diagram . . . . . . . . . . . . . . 14
2.2.3. Capability Identifier . . . . . . . . . . . . . . . . 16 2.2.4. <edit2> Example . . . . . . . . . . . . . . . . . . . 16
2.2.4. New Operations . . . . . . . . . . . . . . . . . . . . 17 2.3. <complete-commit> Operation . . . . . . . . . . . . . . . 18
2.2.5. Modifications to Existing Operations . . . . . . . . . 17 2.3.1. <complete-commit> Input . . . . . . . . . . . . . . . 18
2.2.6. Interactions with Other Capabilities . . . . . . . . . 17 2.3.2. <complete-commit> Output . . . . . . . . . . . . . . . 18
2.3. <edit2> Protocol Operation . . . . . . . . . . . . . . . . 17 2.3.3. <complete-commit> YANG Tree Diagram . . . . . . . . . 19
2.3.1. <edit2> Input . . . . . . . . . . . . . . . . . . . . 17 2.3.4. <complete-commit> Example . . . . . . . . . . . . . . 19
2.3.2. <edit2> Output . . . . . . . . . . . . . . . . . . . . 18 2.4. <revert-commit> Operation . . . . . . . . . . . . . . . . 19
2.3.3. <edit2> YANG Tree Diagram . . . . . . . . . . . . . . 19 2.4.1. <revert-commit> Input . . . . . . . . . . . . . . . . 19
2.3.4. <edit2> Example . . . . . . . . . . . . . . . . . . . 20 2.4.2. <revert-commit> Output . . . . . . . . . . . . . . . . 19
2.4. <complete-commit> Operation . . . . . . . . . . . . . . . 22 2.4.3. <revert-commit> YANG Tree Diagram . . . . . . . . . . 20
2.4.1. <complete-commit> Input . . . . . . . . . . . . . . . 22 2.4.4. <revert-commit> Example . . . . . . . . . . . . . . . 20
2.4.2. <complete-commit> Output . . . . . . . . . . . . . . . 22 2.5. <get2> Protocol Operation . . . . . . . . . . . . . . . . 20
2.4.3. <complete-commit> YANG Tree Diagram . . . . . . . . . 23 2.5.1. Depth Filters . . . . . . . . . . . . . . . . . . . . 20
2.4.4. <complete-commit> Example . . . . . . . . . . . . . . 23 2.5.2. Time Filters . . . . . . . . . . . . . . . . . . . . . 21
2.5. <revert-commit> Operation . . . . . . . . . . . . . . . . 23 2.5.3. <get2> Input . . . . . . . . . . . . . . . . . . . . . 21
2.5.1. <revert-commit> Input . . . . . . . . . . . . . . . . 23 2.5.4. <get2> Output . . . . . . . . . . . . . . . . . . . . 22
2.5.2. <revert-commit> Output . . . . . . . . . . . . . . . . 23 2.5.5. <get2> YANG Tree Diagram . . . . . . . . . . . . . . . 23
2.5.3. <revert-commit> YANG Tree Diagram . . . . . . . . . . 24 2.5.6. <get2> Example . . . . . . . . . . . . . . . . . . . . 23
2.5.4. <revert-commit> Example . . . . . . . . . . . . . . . 24
2.6. <get2> Protocol Operation . . . . . . . . . . . . . . . . 24 2.6. NETCONF-EX YANG Module . . . . . . . . . . . . . . . . . . 24
2.6.1. Depth Filters . . . . . . . . . . . . . . . . . . . . 24 2.7. XSD for NETCONF-EX Metadata . . . . . . . . . . . . . . . 40
2.6.2. Time Filters . . . . . . . . . . . . . . . . . . . . . 25 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43
2.6.3. <get2> Input . . . . . . . . . . . . . . . . . . . . . 25 3.1. NETCONF-EX XML Namespace . . . . . . . . . . . . . . . . . 43
2.6.4. <get2> Output . . . . . . . . . . . . . . . . . . . . 26 3.2. NETCONF-EX XML Schema . . . . . . . . . . . . . . . . . . 43
2.6.5. <get2> YANG Tree Diagram . . . . . . . . . . . . . . . 27 3.3. NETCONF-EX YANG Module . . . . . . . . . . . . . . . . . . 43
2.6.6. <get2> Example . . . . . . . . . . . . . . . . . . . . 27 4. Security Considerations . . . . . . . . . . . . . . . . . . . 44
2.7. NETCONF-EX YANG Module . . . . . . . . . . . . . . . . . . 28 5. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.8. XSD for NETCONF-EX Metadata . . . . . . . . . . . . . . . 44 5.1. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 45
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 5.1.1. Removed :encoding Capability . . . . . . . . . . . . . 45
3.1. NETCONF-EX XML Namespace . . . . . . . . . . . . . . . . . 47 5.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.2. NETCONF-EX XML Schema . . . . . . . . . . . . . . . . . . 47 5.2.1. Removed :capability-id Capability . . . . . . . . . . 45
3.3. NETCONF-EX YANG Module . . . . . . . . . . . . . . . . . . 47 5.2.2. RESTCONF Alignment . . . . . . . . . . . . . . . . . . 46
4. Security Considerations . . . . . . . . . . . . . . . . . . . 48 6. Normative References . . . . . . . . . . . . . . . . . . . . . 47
5. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . . 48
5.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 49 A.1. resource-identifier-type . . . . . . . . . . . . . . . . . 48
5.1.1. Removed :capability-id Capability . . . . . . . . . . 49 A.2. no YANG for top-level message nodes . . . . . . . . . . . 48
5.1.2. RESTCONF Alignment . . . . . . . . . . . . . . . . . . 49 A.3. config-id attribute . . . . . . . . . . . . . . . . . . . 48
6. Normative References . . . . . . . . . . . . . . . . . . . . . 50 A.4. <get2> nodeset retrieval . . . . . . . . . . . . . . . . . 48
Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . . 52 Appendix B. Additional Examples . . . . . . . . . . . . . . . . . 49
A.1. resource-identifier-type . . . . . . . . . . . . . . . . . 52 B.1. YANG Module Used in Examples . . . . . . . . . . . . . . . 49
A.2. no YANG for top-level message nodes . . . . . . . . . . . 52 B.2. YANG Data Used in Examples . . . . . . . . . . . . . . . . 50
A.3. config-id attribute . . . . . . . . . . . . . . . . . . . 52 B.3. <edit2> Examples . . . . . . . . . . . . . . . . . . . . . 51
A.4. <get2> nodeset retrieval . . . . . . . . . . . . . . . . . 52 B.3.1. Confirmed Commit on the "running" Datastore . . . . . 51
Appendix B. Additional Examples . . . . . . . . . . . . . . . . . 53 B.3.2. Conditional Editing with "if-match" Parameter . . . . 52
B.1. YANG Module Used in Examples . . . . . . . . . . . . . . . 53 B.3.3. Bulk Editing with "target-resource" Parameter . . . . 55
B.2. YANG Data Used in Examples . . . . . . . . . . . . . . . . 54 B.3.4. Edit Validation with "test-only" Parameter . . . . . . 57
B.3. <edit2> Examples . . . . . . . . . . . . . . . . . . . . . 55 B.4. <get2> Examples . . . . . . . . . . . . . . . . . . . . . 58
B.3.1. Confirmed Commit on the "running" Datastore . . . . . 55 B.4.1. If-Modified-Since Non-Empty Filter Retrieval . . . . . 58
B.3.2. Conditional Editing with "if-match" Parameter . . . . 56 B.4.2. If-Modified-Since Empty Filter Retrieval . . . . . . . 60
B.3.3. Bulk Editing with "target-resource" Parameter . . . . 59 B.4.3. Keys Only Filter Retrieval . . . . . . . . . . . . . . 60
B.3.4. Edit Validation with "test-only" Parameter . . . . . . 61 B.4.4. Test for Node Existence with Depth=1 . . . . . . . . . 62
B.4. <get2> Examples . . . . . . . . . . . . . . . . . . . . . 62 B.4.5. Retrieve Only Non-Configuration Data Nodes . . . . . . 63
B.4.1. If-Modified-Since Non-Empty Filter Retrieval . . . . . 62 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 65
B.4.2. If-Modified-Since Empty Filter Retrieval . . . . . . . 64
B.4.3. Keys Only Filter Retrieval . . . . . . . . . . . . . . 64
B.4.4. Test for Node Existence with Depth=1 . . . . . . . . . 66
B.4.5. Retrieve Only Non-Configuration Data Nodes . . . . . . 67
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 69
1. Introduction 1. Introduction
There is a need for standard mechanisms to allow NETCONF [RFC6241] There is a need for standard mechanisms to allow NETCONF [RFC6241]
application designers to manage NETCONF servers more efficiently when application designers to manage NETCONF servers more efficiently when
used in network environments with poor connectivity, low bandwidth, used in network environments with poor connectivity, low bandwidth,
and/or high latency. In such conditions, it is desirable to minimize and/or high latency. In such conditions, it is desirable to minimize
network usage wrt/ the size of protocol messages and the number of network usage wrt/ the size of protocol messages and the number of
protocol operations required to perform a network management protocol operations required to perform a network management
function. function.
skipping to change at page 6, line 40 skipping to change at page 6, line 40
the quantity of large <rpc-reply> messages from every server could the quantity of large <rpc-reply> messages from every server could
severely impact network performance. severely impact network performance.
It would be useful if the <hello> message exchange could be enhanced It would be useful if the <hello> message exchange could be enhanced
so an entity-tag value for the current running datastore so an entity-tag value for the current running datastore
configuration is included in the server <hello> message. A client configuration is included in the server <hello> message. A client
can cache the server configuration identifier and omit an initial can cache the server configuration identifier and omit an initial
<get-config> operation if the value from the server <hello> message <get-config> operation if the value from the server <hello> message
matches the cached value. matches the cached value.
1.2.2. Message Encoding 1.2.2. Datastore Editing
NETCONF uses a hard-wired message encoding format, namely XML.
However, XML tends to be verbose, especially for YANG data models
that have long data node identifiers.
There is no reason for the NETCONF message encoding to be hardwired,
except for the <hello> message. It would be useful if the NETCONF
protocol could support other message encoding formats, such as JSON
[JSON]. The <hello> message exchange could be enhanced so the client
and server negotiated the message encoding to use for all other
messages via an capability exchange included in both <hello>
messages.
1.2.3. Datastore Editing
There are several deficiencies with the NETCONF editing procedures There are several deficiencies with the NETCONF editing procedures
that could be improved. that could be improved.
Multi-operation functions can be required. A single edit can take up Multi-operation functions can be required. A single edit can take up
to 9 operations. Several operations are required to complete a set to 9 operations. Several operations are required to complete a set
of 1 or more edits on a NETCONF server. Each operation uses 1 of 1 or more edits on a NETCONF server. Each operation uses 1
request and 1 response message. If the candidate datastore is used, request and 1 response message. If the candidate datastore is used,
then 1 extra operation is required (for the <commit> operation) to then 1 extra operation is required (for the <commit> operation) to
activate the edit(s). If the startup datastore is used then 1 extra activate the edit(s). If the startup datastore is used then 1 extra
skipping to change at page 8, line 39 skipping to change at page 8, line 20
way to apply a set of edits to multiple target nodes at once. way to apply a set of edits to multiple target nodes at once.
There is no confirmed commit support for the running datastore. The There is no confirmed commit support for the running datastore. The
ability to backup the running datastore, change it, and revert it ability to backup the running datastore, change it, and revert it
unless the client confirms the changes has nothing to do with the unless the client confirms the changes has nothing to do with the
candidate datastore. A NETCONF server with limited memory is not candidate datastore. A NETCONF server with limited memory is not
likely to support the candidate datastore. This feature is useful likely to support the candidate datastore. This feature is useful
for any type of network-wide configuration change, regardless of for any type of network-wide configuration change, regardless of
device size. device size.
1.2.4. Data Retrieval 1.2.3. Data Retrieval
NETCONF data retrieval via the <get> and <get-config> operations can NETCONF data retrieval via the <get> and <get-config> operations can
be very inefficient. Some vendors do not even support <get> because be very inefficient. Some vendors do not even support <get> because
it can be such a resource-intensive operation and return an enormous it can be such a resource-intensive operation and return an enormous
amount of data, especially if all server data is requested at once. amount of data, especially if all server data is requested at once.
A client cannot retrieve just the non-configuration data. The A client cannot retrieve just the non-configuration data. The
NETCONF <get> operation allows a client to retrieve data from the NETCONF <get> operation allows a client to retrieve data from the
server but it returns all data, including configuration datastore server but it returns all data, including configuration datastore
nodes. The <get-config> operation already returns all configuration nodes. The <get-config> operation already returns all configuration
skipping to change at page 10, line 39 skipping to change at page 10, line 20
string. A client can cache this value for each server that supports string. A client can cache this value for each server that supports
this capability, along with a copy of its running configuration. this capability, along with a copy of its running configuration.
When a new session is started, the client can examine the "config-id" When a new session is started, the client can examine the "config-id"
<capability> URI sent by the server. If it is the same as the cached <capability> URI sent by the server. If it is the same as the cached
value then the client can use the cached running datastore copy value then the client can use the cached running datastore copy
instead of sending an initial <get-config> operation to the server. instead of sending an initial <get-config> operation to the server.
The :config-id capability is ignored in the calculation of the The :config-id capability is ignored in the calculation of the
:capability-id capability. Refer to Section 2.1 for details on :capability-id capability. Refer to Section 2.1 for details on
configuration ID advertisement. configuration ID advertisement.
1.3.2. Message Encoding Negotiation 1.3.2. <edit2> Operation
A new capability called "encoding" is defined to allow a client to
request that an alternate message encoding be used for the NETCONF
session. The capability is encoded as a comma-separated list of
media types. This list is ordered by the client in the order of
highest preference first. The server list is unordered. The first
match (done in client priority) is the message encoding used for the
rest of session. Refer to Section 2.2 for details on message
encoding negotiation.
1.3.3. <edit2> Operation
A new NETCONF protocol operation called <edit2> is defined to address A new NETCONF protocol operation called <edit2> is defined to address
the deficiencies described in Section 1.2.3. This operation allows the deficiencies described in Section 1.2.2. This operation allows
the entire NETCONF edit procedure to be accomplished with 1 request the entire NETCONF edit procedure to be accomplished with 1 request
message. The editing procedures are aligned with the resource model message. The editing procedures are aligned with the resource model
defined in [RESTCONF]. Refer to Section 2.3 for details on <edit2> defined in [RESTCONF]. Refer to Section 2.2 for details on <edit2>
operation. operation.
The "confirmed-commit" procedure has been integrated into the <edit2> The "confirmed-commit" procedure has been integrated into the <edit2>
operation, and can be supported by any server without requiring operation, and can be supported by any server without requiring
support for the candidate datastore. It is optional to implement, support for the candidate datastore. It is optional to implement,
based on the "confirmed-edit" capability defined in Section 2.7. based on the "confirmed-edit" capability defined in Section 2.6.
Refer to Section 2.4 for details on the <complete-commit> operation Refer to Section 2.3 for details on the <complete-commit> operation
and Section 2.5 for details on the <revert-commit> operation. and Section 2.4 for details on the <revert-commit> operation.
1.3.4. <get2> Operation 1.3.3. <get2> Operation
A new NETCONF protocol operation called <get2> is defined to address A new NETCONF protocol operation called <get2> is defined to address
the deficiencies described in Section 1.2.4. This operation allows the deficiencies described in Section 1.2.3. This operation allows
several filter types to be combined to control the data that is several filter types to be combined to control the data that is
returned in the <rpc-reply> message, and an extensible framework for returned in the <rpc-reply> message, and an extensible framework for
retrieving metadata associated with datastore or data resources. retrieving metadata associated with datastore or data resources.
Refer to Section 2.6 for details on <get2> operation. Refer to Section 2.5 for details on <get2> operation.
2. Definitions 2. Definitions
This section defines the NETCONF efficiency extensions: This section defines the NETCONF efficiency extensions:
- :config-id Capability - :config-id Capability
- :encoding Capability
- <edit2> Operation - <edit2> Operation
- <complete-commit> Operation - <complete-commit> Operation
- <revert-commit> Operation - <revert-commit> Operation
- <get2> Operation - <get2> Operation
2.1. "config-id" Capability 2.1. "config-id" Capability
2.1.1. Overview 2.1.1. Overview
The :config-id capability indicates that the server maintains a The :config-id capability indicates that the server maintains a
skipping to change at page 13, line 44 skipping to change at page 12, line 39
The :config-id capability URI MUST contain an "id" argument assigned The :config-id capability URI MUST contain an "id" argument assigned
an opaque string value indicating the current config ID value for the an opaque string value indicating the current config ID value for the
running datastore. For example: running datastore. For example:
urn:ietf:params:netconf:capability:config-id:1.0?id=6882391 urn:ietf:params:netconf:capability:config-id:1.0?id=6882391
The current config ID value MUST be updated any time a The current config ID value MUST be updated any time a
"netconf-config-change" event would be generated by the server. "netconf-config-change" event would be generated by the server.
If [RFC6470] is supported, then the "config-id" leaf defined in If [RFC6470] is supported, then the "config-id" leaf defined in
Section 2.7 MUST be included in <netconf-config-change> event Section 2.6 MUST be included in <netconf-config-change> event
notifications. notifications.
If the "with-metadata" parameter in the <get2> operation specifies If the "with-metadata" parameter in the <get2> operation specifies
the "config-id" identity, then the server MUST return the current the "config-id" identity, then the server MUST return the current
config ID for the running datastore, if the "source" parameter config ID for the running datastore, if the "source" parameter
identifies the running datastore. The server MAY maintain config IDs identifies the running datastore. The server MAY maintain config IDs
for other datastores as well. for other datastores as well.
2.1.4. New Operations 2.1.4. New Operations
skipping to change at page 14, line 20 skipping to change at page 13, line 15
2.1.5. Modifications to Existing Operations 2.1.5. Modifications to Existing Operations
The :config-id capability does not modify any existing protocol The :config-id capability does not modify any existing protocol
operations. operations.
2.1.6. Interactions with Other Capabilities 2.1.6. Interactions with Other Capabilities
The :config-id capability does not interact with any other The :config-id capability does not interact with any other
capabilities. capabilities.
2.2. "encoding" Capability 2.2. <edit2> Protocol Operation
2.2.1. Overview
The :encoding capability is used by the client to request an
alternate message encoding be used instead of XML. The client and
server both send a list of media types for the message encodings they
support, encoded as a comma-separated list (with no whitespace). The
client list is an ordered by preference. The server list is
unordered.
+-----------+ +-----------+ +--------------+
| | Client and | | | |
| <hello> | server select | <rpc> | | <rpc-reply> |
| | protocol base | | | |
+-----------+ and encoding +-----------+ +--------------+
Always encoded --- > Start encoding all messages
in XML w/base:1.0 in the selected encoding
message framing and message framing
Both the client and server will examine the others <hello> message
for the "encoding" <capability> URI. If not present, then the
default encoding is used, which is XML.
The client list is compared against the server list, checked in the
client specified order. If the same media type appears in the server
list, then that is the encoding that will be active for the remainder
of the session (i.e., starting with the first <rpc> request). All
<rpc>, <rpc-reply>, and <notification> messages MUST be encoded in
the negotiated encoding.
Both the client and server MUST support the "application/xml" media
type to be backward-compatible with [RFC6241].
If "application/json" encoding is used, then the encoding defined in
[I-D.lhotka-netmod-json] MUST be used so namespaces will be properly
identified. Any metadata that needs to encoded MUST be encoded
according to the procedure defined in [RESTCONF], section 4.4.
The message framing used for the session is unaffected by this
capability. The "base1.0" vs. "base1.1" negotiation defined in
[RFC6241] determines the message framing that is used for the entire
session.
2.2.1.1. :encoding Capability Example
In this example, the client supports the following message encodings,
shown in the preferred order.
- Efficient XML Interchange (EXI)
- JSON
- XML
Some extra whitespace has been added for display purposes only.
# Client requests a new session with alternate encoding
# also requesting an abbreviated hello
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
<capability>urn:ietf:params:netconf:base:1.1</capability>
<capability>
urn:ietf:params:netconf:capability:encoding:1.0?
types=application/exi,application/json,application/xml
</capability>
</hello>
The server supports the following encodings:
- XML
- JSON
Since the most preferred media type in common is "application/json",
the JSON encoding used for the remainder of the session.
In this example, the server sends an full <hello> message to the
client, truncated for brevity. Extra whitespace has been added for
display purposes only.
# Server starts session 4 with JSON encoding
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
<capability>urn:ietf:params:netconf:base:1.1</capability>
<capability>
urn:ietf:params:netconf:capability:encoding:1.0?
types=application/xml,application/json
</capability>
<capability>
urn:ietf:params:netconf:capability:config-id?id=2130
</capability>
<!-- rest of URIs ... -->
<capabilities>
<session-id>4</session-id>
</hello>
At this point, both the client and server switch to JSON encoding:
# client send a <kill-session> request
{ "ietf-netconf:rpc" : {
"@@message-id" : "201",
"kill-session" : {
"session-id" : 42
}
}
}
# server sends an <ok/> reply
{ "ietf-netconf:rpc-reply" : {
"@@message-id" : "201",
"ok" : [null]
}
}
2.2.2. Dependencies
The :encoding capability is not dependent on any other capabilities.
2.2.3. Capability Identifier
The :encoding capability is identified by the following capability
string:
urn:ietf:params:netconf:capability:encoding:1.0
This capability MUST be advertised in every server <hello> message.
The "encoding" capability URI MUST contain a "types" argument
containing a comma-separated list of media types that represent the
message encoding formats supported by the server.
If the client supports the :encoding capability, it SHOULD include an
"encoding" <capability> URI in its <hello> message. The client MAY
omit this capability if XML encoding is desired.
For example (line wrapped for display purposes only)
urn:ietf:params:netconf:capability:encoding:1.0?
types=application/json,application/xml
2.2.4. New Operations
The :encoding capability does not introduce any new protocol
operations.
2.2.5. Modifications to Existing Operations
The :encoding capability does not modify any existing protocol
operations.
2.2.6. Interactions with Other Capabilities
The :encoding capability does not interact with any other
capabilities.
2.3. <edit2> Protocol Operation
The <edit2> operation is specified with a YANG "rpc" statement, The <edit2> operation is specified with a YANG "rpc" statement,
defined in Section 2.7. This operation allows the entire NETCONF defined in Section 2.6. This operation allows the entire NETCONF
transaction procedure to be performed in a single operation or transaction procedure to be performed in a single operation or
multiple operations, depending on the input parameters used. multiple operations, depending on the input parameters used.
There are no XML attributes used (e.g., "operation" from RFC 6241, There are no XML attributes used (e.g., "operation" from RFC 6241,
"insert", "value" from RFC 6020). Instead, configuration edits are "insert", "value" from RFC 6020). Instead, configuration edits are
specified with an edit list, using the YANG Patch mechanism defined specified with an edit list, using the YANG Patch mechanism defined
in [RESTCONF]. This is used instead of a complete XML instance in [RESTCONF]. This is used instead of a complete XML instance
document, e.g. <config> element, to represent an unordered patch list document, e.g. <config> element, to represent an unordered patch list
inferred from the diffs. (Although YANG Patch can be used in this inferred from the diffs. (Although YANG Patch can be used in this
mode if client wants to merge or replace the entire configuration mode if client wants to merge or replace the entire configuration
datastore). datastore).
2.3.1. <edit2> Input 2.2.1. <edit2> Input
o target: name of the configuration datastore being edited o target: name of the configuration datastore being edited
o target-resource: XPath node-set expression representing 1 or more o target-resource: XPath node-set expression representing 1 or more
target resources within the datastore to edit. target resources within the datastore to edit.
o yang-patch: container of ordered edits to apply to the target o yang-patch: container of ordered edits to apply to the target
resource(s). resource(s).
o test-only: flag to request that the edit request be validated but o test-only: flag to request that the edit request be validated but
no edits should actually be applied no edits should actually be applied
o if-match: if the entity tag for the target resource(s) does not o if-match: if the entity tag for the target resource(s) does not
skipping to change at page 18, line 46 skipping to change at page 14, line 30
<edit2> request that extends, a <complete-commit> request to <edit2> request that extends, a <complete-commit> request to
finish, or a <revert-commit> request to cancel a confirmed commit finish, or a <revert-commit> request to cancel a confirmed commit
procedure in progress. procedure in progress.
o persist: identifier string to use in the "persist-id" parameter to o persist: identifier string to use in the "persist-id" parameter to
extend, complete, or cancel a confirmed commit procedure. extend, complete, or cancel a confirmed commit procedure.
o persist-id: identifier string to extend a confirmed commit o persist-id: identifier string to extend a confirmed commit
procedure in progress. procedure in progress.
2.3.2. <edit2> Output 2.2.2. <edit2> Output
Positive Response: Positive Response:
This operation returns data containing a "yang-patch-status" report This operation returns data containing a "yang-patch-status" report
(defined in [RESTCONF]) instead of an "ok" element. This report (defined in [RESTCONF]) instead of an "ok" element. This report
contains an "ok" element that is present if the entire operation contains an "ok" element that is present if the entire operation
succeeded. succeeded.
Error Response: Error Response:
The <rpc-error> element can be returned, e.g., if the message The <rpc-error> element can be returned, e.g., if the message
contains invalid parameter syntax. The server MUST report editing contains invalid parameter syntax. The server MUST report editing
errors in the "edit" list within the "yang-patch-status" container. errors in the "edit" list within the "yang-patch-status" container.
2.3.3. <edit2> YANG Tree Diagram 2.2.3. <edit2> YANG Tree Diagram
Key: DRI = data-resource-identifier Key: DRI = data-resource-identifier
+---x edit2 +---x edit2
+--ro input +--ro input
| +--ro target | +--ro target
| | +--ro (datastore-target) | | +--ro (datastore-target)
| | +--:(candidate) | | +--:(candidate)
| | | +--ro candidate? empty | | | +--ro candidate? empty
| | +--:(running) | | +--:(running)
skipping to change at page 20, line 31 skipping to change at page 16, line 14
+--:(errors) +--:(errors)
+--ro errors +--ro errors
+--ro error +--ro error
+--ro error-type enumeration +--ro error-type enumeration
+--ro error-tag string +--ro error-tag string
+--ro error-app-tag? string +--ro error-app-tag? string
+--ro error-path? DRI +--ro error-path? DRI
+--ro error-message? string +--ro error-message? string
+--ro error-info +--ro error-info
2.3.4. <edit2> Example 2.2.4. <edit2> Example
In this example, an "all-in-one" YANG Patch edit is shown. the In this example, an "all-in-one" YANG Patch edit is shown. the
following conditions apply: following conditions apply:
- The server supports the :candidate and :startup capabilities - The server supports the :candidate and :startup capabilities
- The "example-ex" YANG module is supported by the server - The "example-ex" YANG module is supported by the server
The starting state of the "/forests" data structure is described in The starting state of the "/forests" data structure is described in
Appendix B.2. The client is adding an "oak" tree and changing the Appendix B.2. The client is adding an "oak" tree and changing the
location of the "birch" tree in the "north" forest. location of the "birch" tree in the "north" forest.
skipping to change at page 22, line 28 skipping to change at page 18, line 28
<edit-id>birch</edit-id> <edit-id>birch</edit-id>
<ok/> <ok/>
</edit> </edit>
</edit-status> </edit-status>
</yang-patch-status> </yang-patch-status>
</rpc-reply> </rpc-reply>
Refer to Appendix B.3 for additional <edit2> protocol operation Refer to Appendix B.3 for additional <edit2> protocol operation
examples. examples.
2.4. <complete-commit> Operation 2.3. <complete-commit> Operation
A new NETCONF protocol operation called <complete-commit> is defined A new NETCONF protocol operation called <complete-commit> is defined
to complete a confirmed commit procedure. to complete a confirmed commit procedure.
2.4.1. <complete-commit> Input 2.3.1. <complete-commit> Input
There is one optional parameter for this protocol operation: There is one optional parameter for this protocol operation:
o persist-id: an identifier string that MUST match the "persist" o persist-id: an identifier string that MUST match the "persist"
value, if it was used in the confirmed-commit procedure. value, if it was used in the confirmed-commit procedure.
2.4.2. <complete-commit> Output 2.3.2. <complete-commit> Output
Positive Response: Positive Response:
The there is a confirmed-commit procedure in progress and it is The there is a confirmed-commit procedure in progress and it is
successfully completed, then an <ok/> element is returned. successfully completed, then an <ok/> element is returned.
Negative Response: An <rpc-error> response is sent if the request Negative Response: An <rpc-error> response is sent if the request
cannot be completed for any reason. cannot be completed for any reason.
2.4.3. <complete-commit> YANG Tree Diagram 2.3.3. <complete-commit> YANG Tree Diagram
+---x complete-commit +---x complete-commit
+--ro input +--ro input
+--ro persist-id? string +--ro persist-id? string
2.4.4. <complete-commit> Example 2.3.4. <complete-commit> Example
In this example, the client has previously started a confirmed commit In this example, the client has previously started a confirmed commit
procedure using the "persist" parameter set to the value "abcdef". procedure using the "persist" parameter set to the value "abcdef".
<rpc message-id="102" <rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<complete-commit <complete-commit
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-ex"> xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-ex">
<persist-id>abcdef</persist-id> <persist-id>abcdef</persist-id>
</complete-commit> </complete-commit>
</rpc> </rpc>
<rpc-reply message-id="102" <rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
2.5. <revert-commit> Operation 2.4. <revert-commit> Operation
A new NETCONF protocol operation called <revert-commit> is defined to A new NETCONF protocol operation called <revert-commit> is defined to
cancel a confirmed commit procedure and revert the running datastore. cancel a confirmed commit procedure and revert the running datastore.
The <cancel-commit> operation in [RFC6241] cannot be used because it The <cancel-commit> operation in [RFC6241] cannot be used because it
requires the implementation of the candidate capability. requires the implementation of the candidate capability.
2.5.1. <revert-commit> Input 2.4.1. <revert-commit> Input
There is one optional parameter for this protocol operation: There is one optional parameter for this protocol operation:
o persist-id: an identifier string that MUST match the "persist" o persist-id: an identifier string that MUST match the "persist"
value, if it was used in the confirmed-commit procedure. value, if it was used in the confirmed-commit procedure.
2.5.2. <revert-commit> Output 2.4.2. <revert-commit> Output
Positive Response: Positive Response:
If there is a confirmed-commit procedure in progress and it is If there is a confirmed-commit procedure in progress and it is
successfully cancelled, and the running datastore successfully successfully cancelled, and the running datastore successfully
reverted, then an <ok/> element is returned. reverted, then an <ok/> element is returned.
Negative Response: An <rpc-error> response is sent if the request Negative Response: An <rpc-error> response is sent if the request
cannot be completed for any reason. cannot be completed for any reason.
2.5.3. <revert-commit> YANG Tree Diagram 2.4.3. <revert-commit> YANG Tree Diagram
+---x revert-commit +---x revert-commit
+--ro input +--ro input
+--ro persist-id? string +--ro persist-id? string
2.5.4. <revert-commit> Example 2.4.4. <revert-commit> Example
In this example, the client has previously started a confirmed commit In this example, the client has previously started a confirmed commit
procedure using the "persist" parameter set to the value "abcdef". procedure using the "persist" parameter set to the value "abcdef".
<rpc message-id="103" <rpc message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<revert-commit <revert-commit
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-ex"> xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-ex">
<persist-id>abcdef</persist-id> <persist-id>abcdef</persist-id>
</revert-commit> </revert-commit>
</rpc> </rpc>
<rpc-reply message-id="103" <rpc-reply message-id="103"
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>
2.6. <get2> Protocol Operation 2.5. <get2> Protocol Operation
The <get2> operation is specified with a YANG "rpc" statement, The <get2> operation is specified with a YANG "rpc" statement,
defined in Section 2.7. A specific datastore is selected for the defined in Section 2.6. A specific datastore is selected for the
source of the retrieval operation. Several different types of source of the retrieval operation. Several different types of
filters are provided. Filters are combined in a conceptual filters are provided. Filters are combined in a conceptual
"logical-AND" operation, and are optional to use by the client. Not "logical-AND" operation, and are optional to use by the client. Not
all filtering mechanisms are mandatory-to-implement for the server. all filtering mechanisms are mandatory-to-implement for the server.
2.6.1. Depth Filters 2.5.1. Depth Filters
A depth filter indicates how many subtree levels should be returned A depth filter indicates how many subtree levels should be returned
in the <rpc-reply>. This filter is specified with the "depth" input in the <rpc-reply>. This filter is specified with the "depth" input
parameter for the <get2> protocol operation. The default "0" parameter for the <get2> protocol operation. The default "0"
indicates that all levels from the requested subtrees should be indicates that all levels from the requested subtrees should be
returned. returned.
A new level is started for each YANG data node within the requested A new level is started for each YANG data node within the requested
subtree. All top level data nodes are considered to be child nodes subtree. All top level data nodes are considered to be child nodes
(level 1) of a conceptual <config> root. (level 1) of a conceptual <config> root.
skipping to change at page 25, line 20 skipping to change at page 21, line 20
If the depth requested is equal to "1", then only the requested data If the depth requested is equal to "1", then only the requested data
nodes (or top-level data nodes) will be returned. This mechanism can nodes (or top-level data nodes) will be returned. This mechanism can
be used to detect the existence of containers and list entries within be used to detect the existence of containers and list entries within
a particular subtree, without returning any of the descendant nodes. a particular subtree, without returning any of the descendant nodes.
Higher depth values indicates the number of descendant nodes to Higher depth values indicates the number of descendant nodes to
include in the response. For example, if the depth requested is include in the response. For example, if the depth requested is
equal to "2", then only the requested data nodes (or top-level data equal to "2", then only the requested data nodes (or top-level data
nodes) and their immediate child data nodes will be returned. nodes) and their immediate child data nodes will be returned.
2.6.2. Time Filters 2.5.2. Time Filters
A time filter specifies that data should only be returned if the A time filter specifies that data should only be returned if the
last-modified timestamp for the target datastore is more recent than last-modified timestamp for the target datastore is more recent than
the timestamp specified in the "if-modified-since" parameter. the timestamp specified in the "if-modified-since" parameter.
If this feature is supported, then the server will maintain a If this feature is supported, then the server will maintain a
"last-modified" timestamp for the running datastore. The server MAY "last-modified" timestamp for the running datastore. The server MAY
support additional nested timestamps for data nodes within the support additional nested timestamps for data nodes within the
datastore. The server MAY support timestamps for other datastores. datastore. The server MAY support timestamps for other datastores.
skipping to change at page 25, line 47 skipping to change at page 21, line 47
returned in the <rpc-reply>. returned in the <rpc-reply>.
If the "full-delta" parameter is present, and the server maintains If the "full-delta" parameter is present, and the server maintains
"last-modified" timestamps for any data nodes within the source "last-modified" timestamps for any data nodes within the source
datastore, then the same type of comparison will be done for the data datastore, then the same type of comparison will be done for the data
node to determine if it should be included in the response. If no node to determine if it should be included in the response. If no
"last-modified" timestamp is maintained for a data node, then the "last-modified" timestamp is maintained for a data node, then the
server will use the "last-modified" timestamp for its nearest server will use the "last-modified" timestamp for its nearest
ancestor, or for the datastore itself if there are none. ancestor, or for the datastore itself if there are none.
2.6.3. <get2> Input 2.5.3. <get2> Input
o source: A container indicating the conceptual datastore for the o source: A container indicating the conceptual datastore for the
retrieval request. retrieval request.
o filter-spec: A choice indicating the content filter specification o filter-spec: A choice indicating the content filter specification
for the retrieval request. for the retrieval request.
o keys-only: A leaf indicating that only the key leafs, combined o keys-only: A leaf indicating that only the key leafs, combined
with other filtering criteria, should be returned. with other filtering criteria, should be returned.
o if-modified-since: A leaf indicating the time filter specification o if-modified-since: A leaf indicating the time filter specification
for the retrieval request, according to the procedures in for the retrieval request, according to the procedures in
Section 2.6.2. Section 2.5.2.
o full-delta: If present and the "if-modified-since" parameter is o full-delta: If present and the "if-modified-since" parameter is
also present, then the entire datastore will be filtered by last also present, then the entire datastore will be filtered by last
modification time, not just the entire datastore. modification time, not just the entire datastore.
o depth: A leaf indicating the subtree depth level for the retrieval o depth: A leaf indicating the subtree depth level for the retrieval
request, according to the procedures in Section 2.6.1. request, according to the procedures in Section 2.5.1.
o with-defaults: A leaf indicating the type of defaults handling o with-defaults: A leaf indicating the type of defaults handling
requested, according to procedures in [RFC6243]. requested, according to procedures in [RFC6243].
o with-metadata: A leaf-list indicating the specific metadata that o with-metadata: A leaf-list indicating the specific metadata that
the server should add to the response, such as "last-modified" or the server should add to the response, such as "last-modified" or
"etag", encoded in XML according to the schema in Section 2.8. "etag", encoded in XML according to the schema in Section 2.7.
o with-locking: if present then the server will provide exclusive o with-locking: if present then the server will provide exclusive
write access to this <get2> operation so the target datastore is write access to this <get2> operation so the target datastore is
not modified during the entire retrieval operation. not modified during the entire retrieval operation.
o max-lock-wait: amount of time the client is willing to wait for o max-lock-wait: amount of time the client is willing to wait for
locks to clear, if "with-locking" parameter is present. locks to clear, if "with-locking" parameter is present.
2.6.4. <get2> Output 2.5.4. <get2> Output
Positive Response: A <data> element is returned which contains the Positive Response: A <data> element is returned which contains the
data corresponding to the input parameters specified in the request. data corresponding to the input parameters specified in the request.
The child nodes of the <data> container correspond to top-level YANG The child nodes of the <data> container correspond to top-level YANG
data nodes. data nodes.
If the server supports the "timestamps" YANG feature, and the target If the server supports the "timestamps" YANG feature, and the target
is the running datastore, then a "last-modified" attribute SHOULD be is the running datastore, then a "last-modified" attribute SHOULD be
included in the <rpc-reply> element. included in the <rpc-reply> element.
Negative Response: An <rpc-error> response is sent if the request Negative Response: An <rpc-error> response is sent if the request
cannot be completed for any reason. cannot be completed for any reason.
2.6.5. <get2> YANG Tree Diagram 2.5.5. <get2> YANG Tree Diagram
+---x get2 +---x get2
+--ro input +--ro input
| +--ro source | +--ro source
| | +--ro (datastore-source)? | | +--ro (datastore-source)?
| | +--:(candidate) | | +--:(candidate)
| | | +--ro candidate? empty | | | +--ro candidate? empty
| | +--:(running) | | +--:(running)
| | | +--ro running? empty | | | +--ro running? empty
| | +--:(startup) | | +--:(startup)
skipping to change at page 27, line 37 skipping to change at page 23, line 37
| +--ro if-modified-since? yang:date-and-time | +--ro if-modified-since? yang:date-and-time
| +--ro full-delta? empty | +--ro full-delta? empty
| +--ro depth? uint32 | +--ro depth? uint32
| +--ro with-defaults? with-defaults-mode | +--ro with-defaults? with-defaults-mode
| +--ro with-metadata* identityref | +--ro with-metadata* identityref
| +--ro with-locking? empty | +--ro with-locking? empty
| +--ro max-lock-wait? uint32 | +--ro max-lock-wait? uint32
+--ro output +--ro output
+--ro data +--ro data
2.6.6. <get2> Example 2.5.6. <get2> Example
In this example, the retrieval the "forests" resource is shown. the In this example, the retrieval the "forests" resource is shown. the
following conditions apply: following conditions apply:
- The server supports the :candidate and :startup capabilities - The server supports the :candidate and :startup capabilities
- The "example-ex" YANG module is supported by the server - The "example-ex" YANG module is supported by the server
The starting state of the "/forests" data structure is described in The starting state of the "/forests" data structure is described in
Appendix B.2. The client is retrieving just the "forests" node, Appendix B.2. The client is retrieving just the "forests" node,
along with the "last-modified" and "etag" metadata for that node. along with the "last-modified" and "etag" metadata for that node.
skipping to change at page 28, line 24 skipping to change at page 24, line 24
<with-metadata>ncex:etags</with-metadata> <with-metadata>ncex:etags</with-metadata>
<with-metadata>ncex:config-id</with-metadata> <with-metadata>ncex:config-id</with-metadata>
<with-locking /> <with-locking />
<max-lock-wait>5</max-lock-wait> <max-lock-wait>5</max-lock-wait>
</get2> </get2>
</rpc> </rpc>
The server has a "forests" node so this node is returned along with The server has a "forests" node so this node is returned along with
the requested metadata for the node. Note that the XML namespace for the requested metadata for the node. Note that the XML namespace for
the "ncex" metadata is the XSD target namespace defined in the "ncex" metadata is the XSD target namespace defined in
Section 2.8, not the YANG namespace URI defined in Section 2.7. Section 2.7, not the YANG namespace URI defined in Section 2.6.
<rpc-reply message-id="104" <rpc-reply message-id="104"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-ex" <data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-ex"
xmlns:m="urn:ietf:params:xml:ns:netconf:netconf-ex:1.0" xmlns:m="urn:ietf:params:xml:ns:netconf:netconf-ex:1.0"
m:last-modified="2012-09-09T02:00:00Z" m:last-modified="2012-09-09T02:00:00Z"
m:config-id="3aee5601"> m:config-id="3aee5601">
<forests xmlns="http://example.com/ns/example-ex" <forests xmlns="http://example.com/ns/example-ex"
m:last-modified="2012-09-09T02:00:00Z" m:last-modified="2012-09-09T02:00:00Z"
m:etag="3aee5601" /> m:etag="3aee5601" />
</data> </data>
</rpc-reply> </rpc-reply>
Refer to Appendix B.4 for additional <get2> protocol operation Refer to Appendix B.4 for additional <get2> protocol operation
examples. examples.
2.7. NETCONF-EX YANG Module 2.6. NETCONF-EX YANG Module
This module imports the "with-defaults-parameters" grouping from This module imports the "with-defaults-parameters" grouping from
[RFC6243]. [RFC6243].
Several YANG features are imported from [RFC6241]. These correspond Several YANG features are imported from [RFC6241]. These correspond
to the NETCONF capabilities (e.g., candidate, url, startup, xpath) to the NETCONF capabilities (e.g., candidate, url, startup, xpath)
but defined as YANG features instead of URIs. but defined as YANG features instead of URIs.
Some data types are imported from [RFC6991]: Some data types are imported from [RFC6991]:
skipping to change at page 29, line 21 skipping to change at page 25, line 21
- yang-patch - yang-patch
- yang-patch-status - yang-patch-status
One notification is augmented from [RFC6470]. One notification is augmented from [RFC6470].
- netconf-configuration-change - netconf-configuration-change
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-netconf-ex@2014-04-21.yang" <CODE BEGINS> file "ietf-netconf-ex@2014-10-21.yang"
module ietf-netconf-ex { module ietf-netconf-ex {
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-ex"; namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-ex";
prefix ncex; prefix ncex;
import ietf-inet-types { import ietf-inet-types {
prefix inet; prefix inet;
} }
skipping to change at page 30, line 42 skipping to change at page 26, line 42
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from // Note: extracted from
// draft-bierman-netconf-efficiency-extensions-01.txt // draft-bierman-netconf-efficiency-extensions-02.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision "2014-04-21" { revision "2014-10-21" {
description description
"Initial revision. <get2> operation originally published "Initial revision. <get2> operation originally published
in draft-bierman-netconf-get2-03.txt"; in draft-bierman-netconf-get2-03.txt";
reference reference
"RFC XXXX: NETCONF Efficiency Extensions"; "RFC XXXX: NETCONF Efficiency Extensions";
} }
/* Features */ /* Features */
skipping to change at page 44, line 35 skipping to change at page 40, line 35
"Contains the new configuration ID for the "Contains the new configuration ID for the
running datastore on the server, representing running datastore on the server, representing
the datastore after the configuration changes."; the datastore after the configuration changes.";
} }
} }
} }
<CODE ENDS> <CODE ENDS>
2.8. XSD for NETCONF-EX Metadata 2.7. XSD for NETCONF-EX Metadata
The following XML Schema document [XSD] defines the "last-modified" The following XML Schema document [XSD] defines the "last-modified"
and "etag" attributes, described within this document. The and "etag" attributes, described within this document. The
"last-modified" attribute is only relevant if the server supports the "last-modified" attribute is only relevant if the server supports the
"timestamps" YANG feature within the "ietf-netconf-ex" YANG module. "timestamps" YANG feature within the "ietf-netconf-ex" YANG module.
The "last-modified" attribute uses the XSD data type "dateTime", in The "last-modified" attribute uses the XSD data type "dateTime", in
accordance with Section 3.2.7.1 of XML Schema Part 2: Datatypes. accordance with Section 3.2.7.1 of XML Schema Part 2: Datatypes.
This is equivalent to the YANG data type "date-and-time". This is equivalent to the YANG data type "date-and-time".
The "etag" attribute uses the XSD data type "string", in accordance The "etag" attribute uses the XSD data type "string", in accordance
with the "yang-entity-tag" YANG typedef defined in Section 2.7. with the "yang-entity-tag" YANG typedef defined in Section 2.6.
The "config-id" attribute uses the XSD data type "string". The "config-id" attribute uses the XSD data type "string".
<CODE BEGINS> file "netconf-ex.xsd" <CODE BEGINS> file "netconf-ex.xsd"
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:netconf:netconf-ex:1.0" xmlns="urn:ietf:params:xml:ns:netconf:netconf-ex:1.0"
targetNamespace="urn:ietf:params:xml:ns:netconf:netconf-ex:1.0" targetNamespace="urn:ietf:params:xml:ns:netconf:netconf-ex:1.0"
elementFormDefault="qualified" elementFormDefault="qualified"
skipping to change at page 49, line 9 skipping to change at page 45, line 9
4. Security Considerations 4. Security Considerations
This document does not introduce any new security concerns in This document does not introduce any new security concerns in
addition to those specified in [RFC6241], section 9. addition to those specified in [RFC6241], section 9.
5. Change Log 5. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
5.1. 00 to 01 5.1. 01 to 02
5.1.1. Removed :capability-id Capability 5.1.1. Removed :encoding Capability
The :encoding URI exchange was removed because the developers who
want to use JSON are using RESTCONF instead of NETCONF. The NETCONF
protocol should support a binary format that can be streamed by
servers. This should be done as a separate standards effort.
5.2. 00 to 01
5.2.1. Removed :capability-id Capability
The :capability-id URI exchange was removed because the NETCONF The :capability-id URI exchange was removed because the NETCONF
protocol does not allow the server to delay its <hello> message so protocol does not allow the server to delay its <hello> message so
the client cannot choose the full or abbreviated <hello>. the client cannot choose the full or abbreviated <hello>.
This makes the :capability-id URI exchange unworkable for several This makes the :capability-id URI exchange unworkable for several
reasons: reasons:
o Since the client cannot select the server hello format based on o Since the client cannot select the server hello format based on
its own notion of the cached capability set, the server must be its own notion of the cached capability set, the server must be
skipping to change at page 49, line 43 skipping to change at page 46, line 5
to-use by the client. to-use by the client.
o Forcing the client to perform a <get> request and wait for an o Forcing the client to perform a <get> request and wait for an
<rpc-reply> before using the NETCONF session introduces 1 round- <rpc-reply> before using the NETCONF session introduces 1 round-
trip of extra latency into the protocol. trip of extra latency into the protocol.
o Forcing the client to perform a <get> request and wait for an o Forcing the client to perform a <get> request and wait for an
<rpc-reply> before using the NETCONF session introduces extra <rpc-reply> before using the NETCONF session introduces extra
complexity into the protocol. complexity into the protocol.
5.1.2. RESTCONF Alignment 5.2.2. RESTCONF Alignment
The YANG module was updated to align with new RESTCONF and YANG Patch The YANG module was updated to align with new RESTCONF and YANG Patch
drafts. The "location" leaf has been removed from the drafts. The "location" leaf has been removed from the
"yang-patch-status" grouping. "yang-patch-status" grouping.
6. Normative References 6. Normative References
[I-D.lhotka-netmod-json]
Lhotka, L., "Modeling JSON Text with YANG",
draft-lhotka-netmod-yang-json-02 (work in progress),
September 2013.
[JSON] Bray, T., Ed., "The JSON Data Interchange Format",
draft-ietf-json-rfc4627bis-03 (work in progress),
September 2013.
[RESTCONF] [RESTCONF]
Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando, Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
"RESTCONF Protocol", draft-ietf-netconf-restconf-00 (work Protocol", draft-ietf-netconf-restconf-02 (work in
in progress), March 2014. progress), October 2014.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020, Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010. October 2010.
skipping to change at page 51, line 7 skipping to change at page 47, line 47
Recommendation REC-xpath-19991116, November 1999, Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
[XSD] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes [XSD] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium Second Edition", World Wide Web Consortium
Recommendation REC-xmlschema-2-20041028, October 2004, Recommendation REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[YANG-Patch] [YANG-Patch]
Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando, Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando,
"YANG Patch Media Type", draft-ietf-netconf-yang-patch-00 "YANG Patch Media Type", draft-ietf-netconf-yang-patch-01
(work in progress), March 2014. (work in progress), July 2014.
Appendix A. Open Issues Appendix A. Open Issues
A.1. resource-identifier-type A.1. resource-identifier-type
The resource-identifier-type typedef from yang-patch is a RESTCONF The resource-identifier-type typedef from yang-patch is a RESTCONF
path expression, not an XPath path expression. The error-path path expression, not an XPath path expression. The error-path
parameter also uses RESTCONF path strings. Should either or both of parameter also uses RESTCONF path strings. Should either or both of
these be XPath instead? these be XPath instead?
 End of changes. 58 change blocks. 
324 lines changed or deleted 138 lines changed or added

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