RFC 8527

RESTCONF Extensions to Support the Network Management Datastore Architecture

📅 published March 2019, from ietf

Abstract 🌸

Okay bestie, this RFC is RFC 8527, called RESTCONF Extensions to Support the Network Management Datastore Architecture 🦋. It's an IETF (Internet Engineering Task Force) Standards Track document, dated March 2019, with ISSN 2070-1721. The authors are M. Bjorklund (Tail-f Systems), J. Schoenwaelder (Jacobs University), P. Shafer (Juniper Networks), K. Watsen (Watsen Networks), and R. Wilton (Cisco Systems) 👑. It updates RFC 8040, and the header doesn't list anything it obsoletes 💅.

So the abstract basically says that this doc extends the RESTCONF protocol from RFC 8040 so it can support the Network Management Datastore Architecture (NMDA) from RFC 8342 ✨. It updates RFC 8040 by adding new datastore resources, adding a new query parameter, and requiring RESTCONF servers that implement the NMDA to use the YANG library from RFC 8525 🎀.

Status of This Memo 📜

This is an Internet Standards Track document 🔥.

It's a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, got public review, and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check Section 2 of RFC 7841 🧚.

For the current status of this document, any errata, and how to give feedback on it, go to https://www.rfc-editor.org/info/rfc8527 💜.

Copyright (c) 2019 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, because 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 they are provided without warranty as described in the Simplified BSD License 🫶.

Table of Contents 🗂️

1. Introduction ....................................................3
   1.1. Terminology ................................................3
2. Datastore and YANG Library Requirements .........................3
3. RESTCONF Extensions .............................................4
   3.1. New Datastore Resources ....................................4
   3.2. Protocol Operations ........................................5
        3.2.1. The "with-defaults" Query Parameter on the
               Operational State Datastore .........................5
        3.2.2. New "with-origin" Query Parameter ...................6
4. IANA Considerations .............................................7
5. Security Considerations .........................................7
6. Normative References ............................................7
Authors' Addresses .................................................9

1. Introduction 🌈

This doc extends the RESTCONF protocol defined in [RFC8040] so it can support the Network Management Datastore Architecture (NMDA) defined in [RFC8342] ✨.

It also updates [RFC8040] so RESTCONF clients can discover which datastores the RESTCONF server supports, figure out which modules are supported in each datastore, and interact with all the datastores the NMDA supports 🦋. Specifically, the update adds new datastore resources, adds a new query parameter, and requires RESTCONF servers that implement the NMDA to use the YANG library [RFC8525] 💅.

This solution is backwards compatible with [RFC8040], and that works because it only adds new resources and leaves the semantics of the existing resources unchanged 🎀.

1.1. Terminology

This document uses the terminology defined by the NMDA [RFC8342] 📖.

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 🔥.

2. Datastore and YANG Library Requirements 👑

An NMDA-compliant RESTCONF server MUST support the operational state datastore, and it MUST implement at least revision 2019-01-04 of the "ietf-yang-library" module defined in [RFC8525] 💖.

A server like that tells you it supports the NMDA in two ways: by implementing the {+restconf}/ds/ietf-datastores:operational resource, and by implementing at least revision 2019-01-04 of the "ietf-yang-library" module ✨.

A RESTCONF client can check whether a server supports the NMDA by using either the HEAD or GET methods on {+restconf}/ds/ietf-datastores:operational 🧚.

A RESTCONF client can also discover which datastores and YANG modules the server supports by reading the YANG library information from the operational state datastore 🌸.

3. RESTCONF Extensions 🎀

This section describes the RESTCONF extensions needed to support the NMDA 💅.

3.1. New Datastore Resources 🦋

This document defines a set of new resources that represent datastores as defined in [RFC8342]. You reach these resources using the following resource path template:

  {+restconf}/ds/<datastore>

The <datastore> path component is encoded as an "identityref" according to the JSON encoding rules for identities, defined in Section 6.8 of [RFC7951]. The namespace-qualified form MUST be used. Such an identity MUST be derived from the "datastore" identity defined in the "ietf-datastores" YANG module [RFC8342] 🔥.

Specifically:

  • The resource {+restconf}/ds/ietf-datastores:operational refers to the operational state datastore.
  • The resource {+restconf}/ds/ietf-datastores:running refers to the running configuration datastore.
  • The resource {+restconf}/ds/ietf-datastores:intended refers to the intended configuration datastore.

An NMDA-compliant server MUST implement {+restconf}/ds/ietf-datastores:operational. Other datastore resources MAY be implemented 💜.

YANG actions can only be invoked in {+restconf}/ds/ietf-datastores:operational 👑.

As an example, if a server implements a datastore called "ds-ephemeral", defined in a module called "example-ds-ephemeral", then the server would implement the resource {+restconf}/ds/example-ds-ephemeral:ds-ephemeral 🌈.

3.2. Protocol Operations ⭐

The protocol operations available for the new datastore resources (see Section 3.1) are the same as the protocol operations defined in [RFC8040] for the {+restconf}/data resource, with the following exceptions 💅:

  • Dynamic configuration datastores are excluded, because each dynamic configuration datastore definition needs to be reviewed for what protocol operations it supports 🙈.
  • Some datastores are read-only by nature (for example, <intended>), so any attempt to modify these datastores will fail. A server MUST return a response with a "405 Method Not Allowed" status-line and an error-tag value of "operation-not-supported" 😭.
  • The semantics of the "with-defaults" query parameter (Section 4.8.9 of [RFC8040]) are different when you interact with the operational state datastore. They're described in Section 3.2.1 🎀.
  • [RFC8040], Section 3.5.4, paragraph 3 does not apply when interacting with any resource under {+restconf}/ds 🫶.

3.2.1. The "with-defaults" Query Parameter on the Operational State Datastore 🍓

Support for the "with-defaults" query parameter (Section 4.8.9 of [RFC8040]) is OPTIONAL when interacting with {+restconf}/ds/ietf-datastores:operational. The capability that indicates a server's support is identified with this URI:

  urn:ietf:params:restconf:capability:with-operational-defaults:1.0

For servers that support it, the "with-defaults" query parameter works on the operational state datastore like this:

  • If no "with-defaults" query parameter is specified, or if it's set to "explicit", "report-all", or "report-all-tagged", then the "in use" values, as defined in Section 5.3 of [RFC8342], are returned from the operational state datastore. This happens even if a node has a default statement in the YANG module and the server is using that default value. If the "with-defaults" parameter is set to "report-all-tagged", any values that match the schema default get tagged with additional metadata, as described in Section 4.8.9 of [RFC8040] 🌸.
  • If the "with-defaults" query parameter is set to "trim", all "in use" values are returned, except the output is filtered to exclude any values that match the default defined in the YANG schema ✨.

Servers are not required to support all values in the "with-defaults" query parameter on the operational state datastore. If a request uses a value that isn't supported, the error handling behavior is as described in Section 4.8.9 of [RFC8040] 💀.

3.2.2. New "with-origin" Query Parameter 🦋

A new query parameter named "with-origin" is added to the GET operation. If it's present, it asks the server to include "origin" metadata annotations in its response, as detailed in the NMDA. This parameter is only valid when you query {+restconf}/ds/ietf-datastores:operational or any datastores with identities derived from the "operational" identity. If you specify an invalid datastore, the server MUST return a response with a "400 Bad Request" status-line, using an error-tag value of "invalid-value" 😤. "origin" metadata annotations are not included unless a client explicitly asks for them 💅.

Data in the operational state datastore can come from multiple sources. The server should return the "origin" metadata annotation value that most accurately indicates the source of the operational value, as specified in Section 5.3.4 of [RFC8342] 🧠.

When you encode the "origin" metadata annotation for a hierarchy of returned nodes, the annotation can be omitted for a child node when its value matches the value of the parent node, as described in the "ietf-origin" YANG module [RFC8342] 🌷.

Support for the "with-origin" query parameter is OPTIONAL. It is identified with this URI:

  urn:ietf:params:restconf:capability:with-origin:1.0

4. IANA Considerations 🌍

This document defines two capability identifier URNs in the "RESTCONF Capability URNs" registry defined in [RFC8040]:

  Index
  Capability Identifier
  ---------------------

  :with-origin
  urn:ietf:params:restconf:capability:with-origin:1.0

  :with-operational-defaults
  urn:ietf:params:restconf:capability:with-operational-defaults:1.0

Part 1 done, bestie! 🌈💖

5. Security Considerations 🔒

okay bestie, security is where we get serious 🫶. This document adds new datastore resources to RESTCONF, and RESTCONF sits on top of HTTPS. The lowest layer is HTTPS, and the secure transport it has to support is TLS [RFC8446] ✨. Gorgeous, right? 💖

RESTCONF also uses the network configuration access control model [RFC8341] 👑. That's the bit that lets you restrict particular RESTCONF users to a preconfigured subset of all the RESTCONF protocol operations and content. So you can literally decide who gets to touch what 💅.

The security constraints from the base RESTCONF protocol (see Section 12 of [RFC8040]) also apply to the new RESTCONF datastore resources defined in this document 🔥. No loopholes, no exceptions, periodt 🙈.

6. Normative References 📚

Authors' Addresses ✨

Martin Bjorklund
Tail-f Systems

Email: mbj@tail-f.com


Juergen Schoenwaelder
Jacobs University

Email: j.schoenwaelder@jacobs-university.de


Phil Shafer
Juniper Networks

Email: phil@juniper.net


Kent Watsen
Watsen Networks

Email: kent+ietf@watsen.net


Robert Wilton
Cisco Systems

Email: rwilton@cisco.com

That's the whole spec, bestie! 🌈💖 The five authors who wrote it are all listed above, and they're absolutely iconic 👑🫶.

📦 where this page comes from