| 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
This document extends the RESTCONF protocols with transaction capabilities that allow for safe concurrent access of multiple clients.
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 (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.
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:
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].
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].
The following terms are defined in [RFC7950]:
The following terms are defined in [RFC7231]:
The following terms are defined in [RFC7232]:
The following terms are defined in [RFC8040]:
The following terms are defined in [RFC8342]:
The following new term is used in this document:
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.
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 impact operational state of the device until they are merged into <intended> via the "commit" operation (Section 4.1).
In order to support transactions in RESTCONF, the YANG module "ietf-restconf-transactions" defines two RPC operations described below.
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:
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.
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:
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 or similar tools.
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>";
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.";
}
}
<CODE ENDS>
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
TBD