[Search] [txt|html|xml|pdf|bibtex] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01                                                         
NETCONF                                                      J. Lindblad
Internet-Draft                                             Cisco Systems
Intended status: Standards Track                         22 October 2021
Expires: 25 April 2022


                  Transaction ID Mechanism for NETCONF
                draft-lindblad-netconf-transaction-id-01

Abstract

   NETCONF clients and servers often need to have a synchronized view of
   the server's configuration data stores.  The volume of configuration
   data in a server may be very large, while data store changes
   typically are small when observed at typical client resynchronization
   intervals.

   Rereading the entire data store and analyzing the response for
   changes is an inefficient mechanism for synchronization.  This
   document specifies an extension to NETCONF that allows clients and
   servers to keep synchronized with a much smaller data exchange and
   without any need for servers to store information about the clients.

Discussion Venues

   This note is to be removed before publishing as an RFC.

   Source for this draft and an issue tracker can be found at
   https://github.com/janlindblad/netconf-transaction-id.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 25 April 2022.





Lindblad                  Expires 25 April 2022                 [Page 1]


Internet-Draft                    NCTID                     October 2021


Copyright Notice

   Copyright (c) 2021 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Simplified BSD License text
   as described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Conventions and Definitions . . . . . . . . . . . . . . . . .   3
   3.  NETCONF Transaction id Extension  . . . . . . . . . . . . . .   3
     3.1.  General Principles  . . . . . . . . . . . . . . . . . . .   4
     3.2.  Conditional Transactions  . . . . . . . . . . . . . . . .   5
     3.3.  Other NETCONF Operations  . . . . . . . . . . . . . . . .   6
   4.  ETag Transaction id Mechanism . . . . . . . . . . . . . . . .   6
     4.1.  ETag attribute  . . . . . . . . . . . . . . . . . . . . .   6
     4.2.  Configuration Retreival . . . . . . . . . . . . . . . . .   7
       4.2.1.  Initial Configuration Response  . . . . . . . . . . .   7
       4.2.2.  Configuration Response Pruning  . . . . . . . . . . .   9
     4.3.  Configuration Update  . . . . . . . . . . . . . . . . . .  11
       4.3.1.  Conditional Configuration Update  . . . . . . . . . .  14
     4.4.  ETags with Other NETCONF Operations . . . . . . . . . . .  16
   5.  YANG Modules  . . . . . . . . . . . . . . . . . . . . . . . .  17
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  20
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  20
   8.  Changes . . . . . . . . . . . . . . . . . . . . . . . . . . .  21
     8.1.  Major changes in -01 since -00  . . . . . . . . . . . . .  21
   9.  Normative References  . . . . . . . . . . . . . . . . . . . .  22
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  22
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  22

1.  Introduction

   When a NETCONF client connects with a NETCONF server, a frequently
   occurring use case is for the client to find out if the configuration
   has changed since it was last connected.  Such changes could occur
   for example if another NETCONF client has made changes, or another
   system or operator made changes through other means than NETCONF.





Lindblad                  Expires 25 April 2022                 [Page 2]


Internet-Draft                    NCTID                     October 2021


   One way of detecting a change for a client would be to retrieve the
   entire configuration from the server, then compare the result with a
   previously stored copy at the client side.  This approach is not
   popular with most NETCONF users, however, since it would often be
   very expensive in terms of communications and computation cost.

   Furthermore, even if the configuration is reported to be unchanged,
   that will not guarantee that the configuration remains unchanged when
   a client sends a subsequent change request, a few moments later.

   Evidence of a transaction id feature being demanded by clients is
   that several server implementors have built proprietary and mutually
   incompatible mechanisms for obtaining a transaction id from a NETCONF
   server.

   RESTCONF, RFC 8040 (https://tools.ietf.org/html/rfc8040), defines a
   mechanism for detecting changes in configuration subtrees based on
   Entity-tags (ETags).  In conjunction with this, RESTCONF provides a
   way to make configuration changes conditional on the server
   confiuguration being untouched by others.  This mechanism leverages
   RFC 7232 (https://tools.ietf.org/html/rfc7232) "Hypertext Transfer
   Protocol (HTTP/1.1): Conditional Requests".

   This document defines similar functionality for NETCONF, RFC 6241
   (https://tools.ietf.org/html/rfc6241).

2.  Conventions and Definitions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  NETCONF Transaction id Extension

   This document describes a NETCONF extension which modifies the
   behavior of get-config, get-data, edit-config, edit-data, discard-
   changes, copy-config, delete-config and commit such that clients are
   able to conditionally retrieve and update the configuration in a
   NETCONF server.  NETCONF servers that support this extension MUST
   announce the capability
   "urn:ietf:params:netconf:capability:txid:1.0".








Lindblad                  Expires 25 April 2022                 [Page 3]


Internet-Draft                    NCTID                     October 2021


   Several low level mechanisms could be defined to fulfill the
   requirements for efficient client-server transaction id
   synchronization.  This document defines only one mechanism, but
   additional mechanisms could be added in future versions of this
   document, or in separate documents.

   The common use cases for such mecahnisms are briefly discussed here.

   Initial configuration retrieval  When the client initially connects
      to a server, it may be interested to acquire a current view of
      (parts of) the server's configuration.
      In order to be able to efficiently detect changes later, it may
      also be interested to store meta level transaction id information
      about subtrees of the configuration.

   Subsequent configuration retrieval  When a client needs to reread
      (parts of) the server's configuration, it may be interested to
      leverage the transaction id meta data it has stored by requesting
      the server to prune the response so that it does not repeat
      configuration data that the client is already aware of.

   Configuration update with transaction id return  When a client issues
      a transaction towards a server, it may be interested to also learn
      the new transaction id meta data the server has stored for the
      updated parts of the configuration.

   Configuration update with transaction id specification  When a client
      issues a transaction towards a server, it may be interested to
      also specify the new transaction id meta data that the server
      stores for the updated parts of the configuration.

   Conditional configuration update  When a client issues a transaction
      towards a server, it may specify transaction id data for the
      transaction in order to allow the server to verify that the client
      is up to date with any changes in the parts of the configuration
      that it is concerned with.  If the transaction id information in
      the server is different than the client expected, the server
      rejects the transaction with a specific error message.

3.1.  General Principles

   All transaction id mechanisms SHALL maintain a transaction id value
   for each configuration datastore supported by the server.  Some
   transaction id mechanisms will also maintain transaction id values
   for elements deeper in the YANG data tree.  The elements for which
   the server maintains transaction ids are collectively referred to as
   the "versioned elements".




Lindblad                  Expires 25 April 2022                 [Page 4]


Internet-Draft                    NCTID                     October 2021


   The server returning transaction id values for the versioned elements
   MUST ensure the transaction id values are changed every time there
   has been a configuration change at or below the element associated
   with the value.  This means any update of a config true element will
   result in a new transaction id value for all ancestor versioned
   elements, up to and including the datastore root itself.

   This also means a server MUST update the transaction id value for any
   elements that change as a result of a configuration change,
   regardless of source, even if the changed elements are not explicitly
   part of the change payload.  An example of this is dependent data
   under YANG RFC 7950 (https://tools.ietf.org/html/rfc7950) when- or
   choice-statements.

   The server MUST NOT change the transaction id value of a versioned
   element unless a child element of that element has been changed.  The
   server MUST NOT change any transaction id values due to changes in
   config false data.

3.2.  Conditional Transactions

   Conditional transactions are useful when a client is interested to
   make a configuration change, being sure that the server configuration
   has not changed since the client last inspected it.

   By supplying the latest transaction id values known to the client in
   its change requests (edit-config etc.), it can request the server to
   reject the transaction in case any relevant changes have occurred at
   the server that the client is not yet aware of.

   This allows a client to reliably compute and send confiuguration
   changes to a server without either acquiring a global datastore lock
   for a potentially extended period of time, or risk that a change from
   another client disrupts the intent in the time window between a read
   (get-config etc.) and write (edit-config etc.) operation.

   If the server rejects the transaction because the configuration
   transaction id value differs from the client's expectation, the
   server MUST return an rpc-error with the following values:

      error-tag:      operation-failed
      error-type:     protocol
      error-severity: error

   Additionally, the error-info tag SHOULD contain an sx:structure
   containing relevant details about the mismatching transaction ids.





Lindblad                  Expires 25 April 2022                 [Page 5]


Internet-Draft                    NCTID                     October 2021


3.3.  Other NETCONF Operations

   discard-changes  The discard-changes operation resets the candidate
      datastore to the contents of the running datastore.  The server
      MUST ensure the transaction id values in the candidate datastore
      get the same values as in the running datastore when this
      operation runs.

   copy-config  The copy-config operation can be used to copy contents
      between datastores.  The server MUST ensure the transaction id
      values retain the same values as in the soruce datastore.

      If copy-config is used to copy from a file, URL or other source
      that is not a datastore, the server MUST ensure the transaction id
      values are changed.

   delete-config  The server MUST ensure the datastore transaction id
      value is changed.

   commit  At commit, with regards to the transaction id values, the
      server MUST treat the contents of the candidate datastore as if
      any transaction id value provided by the client when updating the
      candidate was provided in a single edit-config towards the running
      datastore.  If the transaction is rejected due to transaction id
      value mismatch, an rpc-error as described in section Conditional
      Transactions (Section 3.2) MUST be sent.

4.  ETag Transaction id Mechanism

4.1.  ETag attribute

   Central to the ETag configuration retrieval and update mechanism
   described in the following sections is a meta data XML attribute
   called "etag".  The etag attribute is defined in the namespace
   "urn:ietf:params:xml:ns:netconf:txid:1.0".

   Servers MUST maintain a top-level etag value for each configuration
   datastore they implement.  Servers SHOULD maintain etag values for
   YANG containers that hold configuration for different subsystems.
   Servers MAY maintain etag values for any YANG container or list
   element they implement.










Lindblad                  Expires 25 April 2022                 [Page 6]


Internet-Draft                    NCTID                     October 2021


   The etag attribute values are opaque UTF-8 strings chosen freely,
   except that the etag string must not contain space, backslash or
   double quotes.  The point of this restriction is to make it easy to
   reuse implementations that adhere to section 2.3.1 in RFC 7232
   (https://tools.ietf.org/html/rfc7232).  The probability SHOULD be
   made very low that an etag value that has been used historically by a
   server is used again by that server.

   The detailed rules for when to update the etag value are described in
   section Configuration Update (Section 4.3).  These rules are chosen
   to be consistent with the ETag mechanism in RESTCONF, RFC 8040
   (https://tools.ietf.org/html/rfc8040), specifically sections 3.4.1.2,
   3.4.1.3 and 3.5.2.

4.2.  Configuration Retreival

   Clients MAY request the server to return etag attribute values in the
   response by adding one or more etag attributes in get-config or get-
   data requests.

   The etag attribute may be added directly on the get-config or get-
   data requests, in which case it pertains to the entire datastore.  A
   client MAY also add etag attributes to zero or more individual
   elements in the get-config or get-data filter, in which case it
   pertains to the subtree rooted at that element.

   For each element that the client requests etag attributes, the server
   MUST return etags for all versioned elements at or below that point
   that are part of the server's respone.  ETags are returned as
   attributes on the element they pertain to.  The datastore root etag
   value is returned on the top-level data tag in the response.

   If the client is requesting an etag value for an element that is not
   among the server's versioned elements, then the server MUST return
   the etag attribute on the closest ancestor that is a versioned
   element, and all children of that ancestor.  The datastore root is
   always a versioned element.

4.2.1.  Initial Configuration Response

   When the client adds etag attributes to a get-config or get-data
   request, it should specify the last known etag values it has seen for
   the elements it is asking about.  Initially, the client will not know
   any etag value and should use "?".

   To retrieve etag attributes across the entire NETCONF server
   configuration, a client might send:




Lindblad                  Expires 25 April 2022                 [Page 7]


Internet-Draft                    NCTID                     October 2021


   <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"
        xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <get-config txid:etag="?"/>
   </rpc>

   To retrieve etag attributes for a specific interface using an xpath
   filter, a client might send:

   <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"
        xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <get-config>
       <source>
         <running/>
       </source>
       <filter type="xpath"
         xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces"
         select=
           "/if:interfaces/if:interface[if:name='GigabitEthernet-0/0']"
         txid:etag="?"/>
     </get-config>
   </rpc>

   To retrieve etag attributes for "ietf-interfaces", but not for
   "nacm", a client might send:

   <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"
        xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <get-config>
       <source>
         <running/>
       </source>
       <filter>
         <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
           txid:etag="?"/>
         <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
       </filter>
     </get-config>
   </rpc>

   When a NETCONF server receives a get-config or get-data request
   containing txid:etag attributes with the value "?", it MUST return
   etag attributes for all versioned elements below this point included
   in the reply.

   If the server considers the container "interfaces" and the list
   "interface" elements to be versioned elements, the server's response
   to the request above might look like:




Lindblad                  Expires 25 April 2022                 [Page 8]


Internet-Draft                    NCTID                     October 2021


   <rpc-reply message-id="1"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
              xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <data txid:etag="def88884321">
       <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
                   txid:etag="def88884321">
         <interface txid:etag="def88884321">
           <name>GigabitEthernet-0/0</name>
           <description>Management Interface</description>
           <type>ianaift:ethernetCsmacd</type>
           <enabled>true</enabled>
         </interface>
         <interface txid:etag="abc12345678">
           <name>GigabitEthernet-0/1</name>
           <description>Upward Interface</description>
           <type>ianaift:ethernetCsmacd</type>
           <enabled>true</enabled>
         </interface>
       </interfaces>
       <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
         <groups>
           <group>
             <name>admin</name>
             <user-name>sakura</user-name>
             <user-name>joe</user-name>
           </group>
         </groups>
       </nacm>
     </data>
   </rpc>

4.2.2.  Configuration Response Pruning

   A NETCONF client that already knows some etag values MAY request that
   the configuration retrieval request is pruned with respect to the
   client's prior knowledge.

   To retrieve only changes for "ietf-interfaces" that do not have the
   last known etag value "abc12345678", but include the entire
   configuration for "nacm", regardless of etags, a client might send:











Lindblad                  Expires 25 April 2022                 [Page 9]


Internet-Draft                    NCTID                     October 2021


   <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"
        xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <get-config>
       <source>
         <running/>
       </source>
       <filter>
         <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
           txid:etag="abc12345678"/>
         <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
       </filter>
     </get-config>
   </rpc>

   When a NETCONF server receives a get-config or get-data request
   containing an element with a client specified etag attribute, there
   are several different cases:

   *  The element is not a versioned element, i.e. the server does not
      maintain an etag value for this element.  In this case, the server
      MUST look up the closest ancestor that is a versioned element, and
      proceed as if the client had specified the etag value for that
      element.

   *  The element is a versioned element, and the client specified etag
      attribute value is different than the server's etag value for this
      element.  In this case the server MUST return the contents as it
      would otherwise have done, adding the etag attributes of all child
      versioned elements to the response.  In case the client has
      specified etag attributes for some child elements, then these
      cases MUST be re-evaluated for those elements.

   *  The element is a versioned element, and the client specified etag
      attribute value matches the server's etag value.  In this case the
      server MUST return the element decorated with an etag attribute
      with the value "=", and child elements pruned.

   For list elements, pruning child elements means that key elements
   MUST be included in the response, and other child elements MUST NOT
   be included.  For containers, child elements MUST NOT be included.

   For example, assuming the NETCONF server configuration is the same as
   in the previous rpc-reply example, the server's response to request
   above might look like:







Lindblad                  Expires 25 April 2022                [Page 10]


Internet-Draft                    NCTID                     October 2021


   <rpc-reply message-id="1"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
              xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <data txid:etag="def88884321">
       <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
                   txid:etag="def88884321">
         <interface txid:etag="def88884321">
           <name>GigabitEthernet-0/0</name>
           <description>Management Interface</description>
           <type>ianaift:ethernetCsmacd</type>
           <enabled>true</enabled>
         </interface>
         <interface txid:etag="=">
           <name>GigabitEthernet-0/1</name>
         </interface>
       </interfaces>
       <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
         <groups>
           <group>
             <name>admin</name>
             <user-name>sakura</user-name>
             <user-name>joe</user-name>
           </group>
         </groups>
       </nacm>
     </data>
   </rpc>

4.3.  Configuration Update

   Whenever the configuration on a server changes for any reason, the
   server MUST update the etag value for all versioned elements that
   have children that changed.

   If the change is due to a NETCONF client edit-config or edit-data
   request that includes the ietf-netconf-txid:with-etag presence
   container, the server MUST return the etag value of the targeted
   datastore as an attribute on the XML ok tag in the rpc-reply.

   The server MUST NOT change the etag value of a versioned element
   unless a child element of that element has been changed.  The server
   MUST NOT change any etag values due to changes in config false data.

   How the server selects a new etag value to use for the changed
   elements is described in section ETag attribute (Section 4.1).






Lindblad                  Expires 25 April 2022                [Page 11]


Internet-Draft                    NCTID                     October 2021


   For example, if a client wishes to update the interface description
   for interface "GigabitEthernet-0/1" to "Downward Interface", it might
   send:

   <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
     <edit-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
                  xmlns:ietf-netconf-txid=
                   "urn:ietf:params:xml:ns:yang:ietf-netconf-txid">
       <target>
         <candidate/>
       </target>
       <test-option>test-then-set</test-option>
       <ietf-netconf-txid:with-etag/>
       <config>
         <interfaces
           xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
           <interface>
             <name>GigabitEthernet-0/1</name>
             <description>Downward Interface</description>
           </interface>
         </interfaces>
       </config>
     </edit-config>
   </rpc>

   The server would update the description leaf in the candidate
   datastore, and return an rpc-reply as follows:

   <rpc-reply message-id="1"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
              xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <ok txid:etag="ghi55550101"/>
   </rpc-reply>

   A subsequent get-config request for "ietf-interfaces", with
   txid:etag="?" might then return:















Lindblad                  Expires 25 April 2022                [Page 12]


Internet-Draft                    NCTID                     October 2021


   <rpc-reply message-id="1"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
              xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <data txid:etag="ghi55550101">
       <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
                   txid:etag="ghi55550101">
         <interface txid:etag="def88884321">
           <name>GigabitEthernet-0/0</name>
           <description>Management Interface</description>
           <type>ianaift:ethernetCsmacd</type>
           <enabled>true</enabled>
         </interface>
         <interface txid:etag="ghi55550101">
           <name>GigabitEthernet-0/1</name>
           <description>Downward Interface</description>
           <type>ianaift:ethernetCsmacd</type>
           <enabled>true</enabled>
         </interface>
       </interfaces>
     </data>
   </rpc>

   In case the server at this point received a configuration change from
   another source, such as a CLI operator, adding an MTU value for the
   interface "GigabitEthernet-0/0", a subsequent get-config request for
   "ietf-interfaces", with txid:etag="?" might then return:

























Lindblad                  Expires 25 April 2022                [Page 13]


Internet-Draft                    NCTID                     October 2021


   <rpc-reply message-id="1"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
              xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <data txid:etag="cli22223333">
       <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
                   txid:etag="cli22223333">
         <interface txid:etag="cli22223333">
           <name>GigabitEthernet-0/0</name>
           <description>Management Interface</description>
           <type>ianaift:ethernetCsmacd</type>
           <enabled>true</enabled>
           <mtu>768</mtu>
         </interface>
         <interface txid:etag="ghi55550101">
           <name>GigabitEthernet-0/1</name>
           <description>Downward Interface</description>
           <type>ianaift:ethernetCsmacd</type>
           <enabled>true</enabled>
         </interface>
       </interfaces>
     </data>
   </rpc>

4.3.1.  Conditional Configuration Update

   When a NETCONF client sends an edit-config or edit-data request to a
   NETCONF server that implements this specification, the client MAY
   specify expected etag values on the versioned elements touched by the
   transaction.

   If such an etag value differs from the etag value stored on the
   server, the server MUST reject the transaction and return an rpc-
   error as specified in section Conditional Transactions (Section 3.2).

   Additionally, the error-info tag MUST contain an sx:structure etag-
   value-mismatch-error-info as defined in the module ietf-netconf-txid,
   with mismatch-path set to the instance identifier value identifying
   one of the versioned elements that had an etag value mismatch, and
   mismatch-etag-value set to the server's current value of the etag
   attribute for that versioned element.

   For example, if a client wishes to delete the interface
   "GigabitEthernet-0/1" if and only if its configuration has not been
   altered since this client last synchronized its configuration with
   the server (at which point it received the etag "ghi55550101"),
   regardless of any possible changes to other interfaces, it might
   send:




Lindblad                  Expires 25 April 2022                [Page 14]


Internet-Draft                    NCTID                     October 2021


   <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"
        xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
        xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0"
        xmlns:ietf-netconf-txid=
          "urn:ietf:params:xml:ns:yang:ietf-netconf-txid">
     <edit-config>
       <target>
         <candidate/>
       </target>
       <test-option>test-then-set</test-option>
       <ietf-netconf-txid:with-etag/>
       <config>
         <interfaces
           xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
           <interface nc:operation="delete"
                      txid:etag="ghi55550101">
             <name>GigabitEthernet-0/1</name>
           </interface>
         </interfaces>
       </config>
     </edit-config>
   </rpc>

   If interface "GigabitEthernet-0/1" has the etag value "ghi55550101",
   as expected by the client, the transaction goes through, and the
   server responds something like:

   <rpc-reply message-id="1"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
              xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <ok txid:etag="xyz77775511"/>
   </rpc-reply>

   A subsequent get-config request for "ietf-interfaces", with
   txid:etag="?" might then return:
















Lindblad                  Expires 25 April 2022                [Page 15]


Internet-Draft                    NCTID                     October 2021


   <rpc-reply message-id="1"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
              xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <data txid:etag="xyz77775511">
       <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces"
                   txid:etag="xyz77775511">
         <interface txid:etag="def88884321">
           <name>GigabitEthernet-0/0</name>
           <description>Management Interface</description>
           <type>ianaift:ethernetCsmacd</type>
           <enabled>true</enabled>
         </interface>
       </interfaces>
     </data>
   </rpc-reply>

   In case interface "GigabitEthernet-0/1" did not have the expected
   etag value "ghi55550101", the server rejects the transaction, and
   might send:

   <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
              xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces"
              xmlns:ietf-netconf-txid=
                "urn:ietf:params:xml:ns:yang:ietf-netconf-txid">
              message-id="1">
     <rpc-error>
       <error-type>protocol</error-type>
       <error-tag>operation-failed</error-tag>
       <error-severity>error</error-severity>
       <error-info>
         <ietf-netconf-txid:etag-value-mismatch-error-info>
           <ietf-netconf-txid:mismatch-path>
             /if:interfaces/if:interface[if:name="GigabitEthernet-0/0"]
           </ietf-netconf-txid:mismatch-path>
           <ietf-netconf-txid:mismatch-etag-value>
             cli22223333
           </ietf-netconf-txid:mismatch-etag-value>
         </ietf-netconf-txid:etag-value-mismatch-error-info>
       </error-info>
     </rpc-error>
   </rpc-reply>

4.4.  ETags with Other NETCONF Operations

   The following NETCONF Operations also need some special
   considerations.

   discard-changes  The server MUST ensure the etag attributes in the



Lindblad                  Expires 25 April 2022                [Page 16]


Internet-Draft                    NCTID                     October 2021


      candidate datastore get the same values as in the running
      datastore when this operation runs.

   copy-config  The server MUST ensure the etag attributes retain the
      same values as in the soruce datastore.

      If copy-config is used to copy from a source that is not a
      datastore, the server MUST ensure etags are given new values.

   delete-config  The server MUST ensure the datastore etag is given a
      new value.

   commit  At commit, with regards to the etag values, the server MUST
      treat the contents of the candidate datastore as if any etag
      attributes provided by the client were provided in a single edit-
      config towards the running datastore.  If the commit is rejected
      due to etag mismatch, the rpc-error message specified in section
      Conditional Configuration Update (Section 4.3.1) MUST be sent.

   The client MAY request that the new etag value is returned as an
   attribute on the ok response for a successful commit.  The client
   requests this by adding with-etag to the commit operation.

   For example, a client might send:

   <rpc message-id="1"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       xmlns:ietf-netconf-txid=
         "urn:ietf:params:xml:ns:yang:ietf-netconf-txid"
     <commit>
       <ietf-netconf-txid:with-etag/>
     </commit>
   </rpc>

   Assuming the server accepted the transaction, it might respond:

   <rpc-reply message-id="1"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns:txid="urn:ietf:params:xml:ns:netconf:txid:1.0">
     <ok txid:etag="ghi55550101"/>
   </rpc-reply>

5.  YANG Modules








Lindblad                  Expires 25 April 2022                [Page 17]


Internet-Draft                    NCTID                     October 2021


   module ietf-netconf-txid {
     yang-version 1.1;
     namespace
       'urn:ietf:params:xml:ns:yang:ietf-netconf-txid';
     prefix ietf-netconf-txid;

     import ietf-netconf {
       prefix nc;
     }

     import ietf-netconf-nmda {
       prefix ncds;
     }

     import ietf-yang-structure-ext {
       prefix sx;
     }

     organization
       "IETF NETCONF (Network Configuration) Working Group";

     contact
       "WG Web:   <http://tools.ietf.org/wg/netconf/>
        WG List:  <netconf@ietf.org>

        Author:   Jan Lindblad
                  <mailto:jlindbla@cisco.com>";

     description
       "NETCONF Transaction ID aware operations for NMDA.

        Copyright (c) 2021 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, is permitted pursuant to, and subject
        to the license terms contained in, the Simplified BSD License
        set forth in Section 4.c of the IETF Trust's Legal Provisions
        Relating to IETF Documents
        (http://trustee.ietf.org/license-info).

        This version of this YANG module is part of RFC XXXX; see
        the RFC itself for full legal notices.";

     revision 2021-11-01 {
       description
         "Initial revision";
       reference



Lindblad                  Expires 25 April 2022                [Page 18]


Internet-Draft                    NCTID                     October 2021


         "RFC XXXX: Xxxxxxxxx";
     }

     typedef etag-t {
       type string {
         pattern ".* .*" {
           modifier invert-match;
         }
         pattern ".*\".*" {
           modifier invert-match;
         }
         pattern ".*\\.*" {
           modifier invert-match;
         }
       }
       description
         "Unique Entity-tag value representing a specific transaction.
          Could be any string that does not contain spaces, double
          quotes or backslash.  The values '?' and '=' have special
          meaning.";
     }

     grouping transaction-id-grouping {
       container with-etag {
         presence
           "Indicates that the client requests the server to include a
            txid:etag transaction id in the rpc-reply";
       }
       description
         "Grouping for transaction id mechanisms, to be augmented into
          rpcs that modify configuration data stores.";
     }

     augment /nc:edit-config/nc:input {
       uses transaction-id-grouping;
       description
         "Injects the transaction id mechanisms into the
         edit-config operation";
     }

     augment /nc:commit/nc:input {
       uses transaction-id-grouping;
       description
         "Injects the transaction id mechanisms into the
         commit operation";
     }

     augment /ncds:edit-data/ncds:input {



Lindblad                  Expires 25 April 2022                [Page 19]


Internet-Draft                    NCTID                     October 2021


       uses transaction-id-grouping;
       description
         "Injects the transaction id mechanisms into the
         edit-data operation";

     sx:structure etag-value-mismatch-error-info {
       container etag-value-mismatch-error-info {
         description
            "This error is returned by a NETCONF server when a client
             sends a configuration change request, with the additonal
             condition that the server aborts the transaction if the
             server's configuration has changed from what the client
             expects, and the configuration is found not to actually
             not match the client's expectation.";
         leaf mismatch-path {
           type instance-identifier;
           description
             "Indicates the YANG path to the element with a mismatching
              etag value.";
         }
         leaf mismatch-etag-value {
           type etag-t;
           description
             "Indicates server's value of the etag attribute for one
              mismatching element.";
         }
       }
     }
   }

6.  Security Considerations

   TODO Security

7.  IANA Considerations

   This document registers the following capability identifier URN in
   the 'Network Configuration Protocol (NETCONF) Capability URNs'
   registry:

     urn:ietf:params:netconf:capability:txid:1.0

   This document registers two XML namespace URNs in the 'IETF XML
   registry', following the format defined in RFC 3688
   (https://tools.ietf.org/html/rfc3688).






Lindblad                  Expires 25 April 2022                [Page 20]


Internet-Draft                    NCTID                     October 2021


     URI: urn:ietf:params:xml:ns:netconf:txid:1.0

     URI: urn:ietf:params:xml:ns:yang:ietf-netconf-txid

     Registrant Contact: The NETCONF WG of the IETF.

     XML: N/A, the requested URIs are XML namespaces.

   This document registers one module name in the 'YANG Module Names'
   registry, defined in RFC 6020 (https://tools.ietf.org/html/rfc6020).

     name: ietf-netconf-txid

     prefix: ietf-netconf-txid

     namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-txid

     RFC: XXXX

8.  Changes

8.1.  Major changes in -01 since -00

   *  Updated the text on numerous points in order to answer questions
      that appeared on the mailing list.

   *  Changed the document structure into a general transaction id part
      and one etag specific part.

   *  Renamed entag attribute to etag, prefix to txid, namespace to
      urn:ietf:params:xml:ns:yang:ietf-netconf-txid.

   *  Set capability string to
      urn:ietf:params:netconf:capability:txid:1.0

   *  Changed YANG module name, namespace and prefix to match names
      above.

   *  Harmonized/slightly adjusted etag value space with RFC 7232 and
      RFC 8040.

   *  Removed all text discussing etag values provided by the client
      (although this is still an interesting idea, if you ask the
      author)







Lindblad                  Expires 25 April 2022                [Page 21]


Internet-Draft                    NCTID                     October 2021


   *  Clarified the etag attribute mechanism, especially when it comes
      to matching against non-versioned elements, its cascading upwards
      in the tree and secondary effects from when- and choice-
      statements.

   *  Added a mechanism for returning the server assigned etag value in
      get-config and get-data.

   *  Added section describing how the NETCONF discard-changes, copy-
      config, delete-config and commit operations work with respect to
      etags.

   *  Added IANA Considerations section.

   *  Removed all comments about open questions.

9.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

Acknowledgments

   The author wishes to thank Benoit Claise for making this work happen,
   and the following individuals, who all provided helpful comments: Per
   Andersson, Kent Watsen, Andy Bierman, Robert Wilton, Qiufang Ma.

Author's Address

   Jan Lindblad
   Cisco Systems

   Email: jlindbla@cisco.com












Lindblad                  Expires 25 April 2022                [Page 22]