[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]



NETMOD Working Group                                           L. Lhotka
Internet-Draft                                                    CZ.NIC
Intended status: Standards Track                           June 13, 2018
Expires: December 15, 2018


                       RESTCONF with Transactions
             draft-lhotka-netconf-restconf-transactions-00

Abstract

   This document extends the RESTCONF protocols with transaction
   capabilities that allow for safe concurrent access of multiple
   clients.

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 December 15, 2018.

Copyright Notice

   Copyright (c) 2018 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.





Lhotka                  Expires December 15, 2018               [Page 1]


Internet-Draft         RESTCONF with Transactions              June 2018


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  YANG  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.2.  HTTP  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.3.  RESTCONF  . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.4.  NMDA  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.5.  New Terms . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  Datastores  . . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.1.  The Staging Configuration Datastore . . . . . . . . . . .   4
   4.  New Operations  . . . . . . . . . . . . . . . . . . . . . . .   5
     4.1.  Commit  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     4.2.  Reset . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   5.  Access Control  . . . . . . . . . . . . . . . . . . . . . . .   5
   6.  Compatibility . . . . . . . . . . . . . . . . . . . . . . . .   6
   7.  YANG Module . . . . . . . . . . . . . . . . . . . . . . . . .   6
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     10.1.  Normative References . . . . . . . . . . . . . . . . . .   8
     10.2.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  10
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  10

1.  Introduction

   The RESTCONF protocol [RFC8040] was introduced as a simpler
   alternative to the original NETCONF protocol [RFC6241].  Due to the
   simplicity requirement, some more complex features and functions of
   NETCONF, such as locks, subtree filtering or candidate configuration
   datastore, are not available in RESTCONF.

   On the other hand, RESTCONF offers several advantages over NETCONF,
   including:

   o  the use of HTTP methods and well-known Representational State
      Transfer (REST) approaches make it more accessible to developers
      and increases the choice of software libraries and tools

   o  cleaner semantics of edit operations,

   o  alternative encodings in which resources can be represented,
      currently JSON and XML; NETCONF supports only XML

   o  certain HTTP mechanisms, such as "Last-Modified" and "ETag"
      headers.





Lhotka                  Expires December 15, 2018               [Page 2]


Internet-Draft         RESTCONF with Transactions              June 2018


   This document extends the RESTCONF protocol with transaction
   capabilities, at the cost of adding two RPC operations and some
   complexity in the server implementation.  This makes RESTCONF
   suitable for network management environments where concurrent access
   of multiple client is needed.

   A RESTCONF server indicates support for transactions as defined in
   this document by including the YANG module "ietf-restconf-
   transactions" (Section 7) among implemented modules in its YANG
   library data [I-D.ietf-netconf-rfc7895bis].

2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

2.1.  YANG

   The following terms are defined in [RFC7950]:

   o  RPC operation

2.2.  HTTP

   The following terms are defined in [RFC7231]:

   o  resource

   The following terms are defined in [RFC7232]:

   o  entity-tag

2.3.  RESTCONF

   The following terms are defined in [RFC8040]:

   o  client

   o  RESTCONF root resource, {+restconf}

2.4.  NMDA

   The following terms are defined in [RFC8342]:

   o  candidate configuration datastore, <candidate>

   o  intended configuration datastore, <intended>



Lhotka                  Expires December 15, 2018               [Page 3]


Internet-Draft         RESTCONF with Transactions              June 2018


   o  operational state datastore, <operational>

   o  running configuration datastore, <running>

2.5.  New Terms

   The following new term is used in this document:

   o  staging configuration datastore: a configuration datastore that
      represents a staging area private to each RESTCONF user, and that
      is eventually commited into <intended>.

3.  Datastores

   A RESTCONF server implementing this document MUST be NMDA-compliant
   [I-D.ietf-netconf-nmda-restconf].  Apart from the operational state
   datastore, it MUST also support the intended configuration datastore.

   The intended configuration datastore SHOULD persist across server
   reboots.  In terms of the NMDA architecture [RFC8342], <intended> can
   be considered identical to <running>, although this document does not
   explicitly use the latter datastore.

3.1.  The Staging Configuration Datastore

   This document introduces a new configuration datastore named
   'staging' that represents a staging area private to each user (as
   identified by RESTCONF username, see [RFC8040] Section 2.5).

   In NETCONF terms ([RFC8040] Section 8.3), the staging datastore is
   essentially a non-shared candidate configuration datastore.  The new
   name is used in order to emphasize the narrower semantics: the
   staging datastore MUST be private to each user.

   Note that the above requirement does not necessarily mean that each
   user is provided with a separate copy of configuration data.  For
   instance, several efficient methods utilizing persistent data
   structures and copy-on-write are available.  However, the particular
   implementation approach is outside the scope of this document.

   The staging datastore assumes the place of the datastore resource as
   defined in [RFC8040] Section 3.4.  This means that all resources
   inside the "{+restconf}/data" subtree correspond to data instances in
   the staging datastore.  Therefore, the contents of the staging
   datastore can be retrieved by means of the GET method and modified by
   means of PUT, POST and PATCH methods exactly as specified in
   [RFC8040].  However, the changes to the staging datastore MUST NOT




Lhotka                  Expires December 15, 2018               [Page 4]


Internet-Draft         RESTCONF with Transactions              June 2018


   impact operational state of the device until they are merged into
   <intended> via the "commit" operation (Section 4.1).

4.  New Operations

   In order to support transactions in RESTCONF, the YANG module "ietf-
   restconf-transactions" defines two RPC operations described below.

4.1.  Commit

   The "commit" operation atomically merges the contents of the client's
   staging datastore into <intended>.

   The concrete strategy and implementation of the merge procedure is
   outside the scope of this document.  The resolution of merge
   conflicts can be fully automatic, which is preferable, or may require
   client's intervention.  In the latter case, the server SHALL send an
   error response with the following properties:

   o  HTTP status code 412

   o  error-tag of "operation-failed"

   o  error-app-tag of "merge-conflict"

   o  error-info containing additional information to aid the user in
      resolving the conflict.

4.2.  Reset

   The "reset" operation resets the user's staging datastore to the
   current contents of <intended>.

   If the server supports entity-tags (see [RFC8040] Section 3.5.2),
   then after completing the "reset" operation the entity-tags for the
   staging and intended datastore resources MUST be identical.

5.  Access Control

   A server that implements this document along with NETCONF Access
   Control Model [RFC8341] MUST guarantee that all NACM rules are
   observed.  This means in particular:

   o  Configuration data that is not readable for a given user MUST NOT
      be exposed in the user's staging datastore.






Lhotka                  Expires December 15, 2018               [Page 5]


Internet-Draft         RESTCONF with Transactions              June 2018


   o  A commit operation executed by a given user MUST NOT modify
      configuration data in <intended> in a way that is not compliant
      with NACM rules that are in effect for that user.

6.  Compatibility

   RESTCONF with transactions, as defined in this document, is
   compatible with the original RESTCONF specification [RFC8040] and
   RESTCONF NMDA extensions [I-D.ietf-netconf-nmda-restconf].

   In practical terms, standard RESTCONF clients are able to retrieve
   and edit data in the staging configuration datastore.  If they
   support NMDA, they can also retrieve data from <intended> and
   <operational>.  In order to make them useful for network management,
   it is only necessary to allow for executing the "commit" and "reset"
   operations.  This can be accomplished through simple scripts
   utilizing curl [1] or similar tools.

7.  YANG Module

   RFC Editor: In this section, replace all occurrences of 'XXXX' with
   the actual RFC number and all occurrences of the revision date below
   with the date of RFC publication (and remove this note).

   <CODE BEGINS> file "ietf-restconf-transactions@2018-06-11.yang"

   module ietf-restconf-transactions {

     namespace
       "urn:ietf:params:xml:ns:yang:ietf-restconf-transactions";

     prefix rct;

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

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

        WG Chair: Kent Watsen
                  <mailto:kwatsen@juniper.net>

        WG Chair: Mahesh Jethanandani
                  <mailto:mjethanandani@gmail.com>

        Editor:   Ladislav Lhotka
                  <mailto:lhotka@nic.cz>";



Lhotka                  Expires December 15, 2018               [Page 6]


Internet-Draft         RESTCONF with Transactions              June 2018


     description
       "This module defines operations that implement transactions in
        the RESTCONF protocol.

        Copyright (c) 2018 IETF Trust and the persons identified as
        authors of the code. 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
        (https://trustee.ietf.org/license-info).

        The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
        NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and
        'OPTIONAL' in the module text are to be interpreted as described
        in RFC 2119 (https://tools.ietf.org/html/rfc2119).

        This version of this YANG module is part of RFC XXXX
        (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for
        full legal notices.";

     revision 2018-06-11 {
       description
         "Initial revision.";
       reference
         "RFC XXXX: RESTCONF with Transactions";
     }

     /* Operations */

     rpc commit {
       description
         "Atomically merge the contents of client's staging datastore
          into the intended datastore.

          If a merge conflict occurs that cannot be automatically
          resolved, the server SHALL send an error report with
          error-app-tag set to 'merge-conflict' and error-info
          indicating the reason for the conflict.";
     }

     rpc reset {
       description
         "Reset the client's staging datastore so that its contents is
          identical to the contents of the intended repository.";
     }



Lhotka                  Expires December 15, 2018               [Page 7]


Internet-Draft         RESTCONF with Transactions              June 2018


   }

   <CODE ENDS>

8.  IANA Considerations

   RFC Editor: In this section, replace all occurrences of 'XXXX' with
   the actual RFC number and all occurrences of the revision date below
   with the date of RFC publication (and remove this note).

   This document registers one URI in the IETF XML Registry [RFC3688].
   The following registration has been made:

     URI: urn:ietf:params:xml:ns:yang:ietf-restconf-transactions

     Registrant Contact: The IESG.

     XML: N/A, the requested URI is an XML namespace.

   This document registers one YANG module in the YANG Module Names
   Registry [RFC6020].  The following registration has been made:

     name:       ietf-restconf-transactions
     namespace:  urn:ietf:params:xml:ns:yang:ietf-restconf-transactions
     prefix:     rct
     reference:  RFC XXXX

9.  Security Considerations

   TBD

10.  References

10.1.  Normative References

   [I-D.ietf-netconf-nmda-restconf]
              Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "RESTCONF Extensions to Support the Network
              Management Datastore Architecture", draft-ietf-netconf-
              nmda-restconf-04 (work in progress), April 2018.

   [I-D.ietf-netconf-rfc7895bis]
              Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
              and R. Wilton, "YANG Library", draft-ietf-netconf-
              rfc7895bis-06 (work in progress), April 2018.






Lhotka                  Expires December 15, 2018               [Page 8]


Internet-Draft         RESTCONF with Transactions              June 2018


   [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/info/rfc2119>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <https://www.rfc-editor.org/info/rfc6020>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/info/rfc6241>.

   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
              DOI 10.17487/RFC7231, June 2014,
              <https://www.rfc-editor.org/info/rfc7231>.

   [RFC7232]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
              DOI 10.17487/RFC7232, June 2014,
              <https://www.rfc-editor.org/info/rfc7232>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <https://www.rfc-editor.org/info/rfc8040>.

   [RFC8341]  Bierman, A. and M. Bjorklund, "Network Configuration
              Access Control Model", STD 91, RFC 8341,
              DOI 10.17487/RFC8341, March 2018,
              <https://www.rfc-editor.org/info/rfc8341>.

   [RFC8342]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "Network Management Datastore Architecture
              (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
              <https://www.rfc-editor.org/info/rfc8342>.





Lhotka                  Expires December 15, 2018               [Page 9]


Internet-Draft         RESTCONF with Transactions              June 2018


10.2.  URIs

   [1] https://curl.haxx.se

Author's Address

   Ladislav Lhotka
   CZ.NIC

   Email: lhotka@nic.cz









































Lhotka                  Expires December 15, 2018              [Page 10]


Html markup produced by rfcmarkup 1.127, available from https://tools.ietf.org/tools/rfcmarkup/