YANG Metadata Annotation for Immutable Flag

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 31 December 2024.¶

Copyright Notice

Copyright (c) 2024 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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

This document defines a way to formally document as a YANG metadata annotation an existing model handling behavior that has been used by multiple standard organizations and vendors. It is the aim to create one single standard solution for documenting non-modifiable system data declared as configuration, instead of the multiple existing vendor and organization specific solutions. See Appendix B for existing implementations.¶

YANG [RFC7950] is a data modeling language used to model both state and configuration data, based on the "config" statement. However, there exists some system configuration data that cannot be modified by the client (it is immutable), but still needs to be declared as "config true" to:¶

• allow configuration of data nodes under immutable lists or containers;¶

• place "when", "must" and "leafref" constraints between configuration and immutable data nodes;¶

• ensure the existence of specific list entries that are provided and needed by the system, while additional list entries can be created, modified or deleted.¶

If the server always rejects the client attempts to override some system-provided data because it internally thinks immutable, it should document it towards the clients in a machine-readable way rather than writing as plain text in the "description" statement.¶

This document defines a way to formally document existing behavior, implemented by servers in production, on the immutability of some system-provided nodes, using a YANG metadata annotation [RFC7952] called "immutable" to flag which nodes are immutable.¶

This document does not apply to the server not having any immutable system configuration. While in some cases immutability may be needed, it also has disadvantages, therefore it SHOULD be avoided wherever possible.¶

The following is a list of already implemented and potential use cases:¶

• UC1 Modeling of server capabilities¶

• UC2 HW based auto-configuration¶

• UC3 Predefined administrator roles¶

• UC4 Declaring immutable system configuration from an LNE's perspective¶

Appendix A describes the use cases in detail.¶

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

The document uses the following definition in [RFC6241]:¶

• configuration data¶

The document uses the following definition in [RFC7950]:¶

• data node¶

• leaf¶

• leaf-list¶

• container¶

• list¶

• anydata¶

• anyxml¶

• interior node¶

• data tree¶

The document uses the following definition in [RFC8341]:¶

• access operation¶

This document defines the following term:¶

immutable flag:

A read-only state value the server provides to describe immutability of the data, which is conveyed via a YANG metadata annotation called "immutable" with a boolean value.¶

3. Applicability

While immutable flag applies to all configuration nodes, its value "true" can only be used for system configuration.¶

The immutable flag is also visible in read-only datastores like <system> (if implemented, see [I-D.ietf-netmod-system-config]), <intended> and <operational> when a "with-immutable" parameter is carried (Section 4.2), however this only serves as descriptive information about the instance node itself, but has no effect on the handling of the read-only datastore.¶

Configuration data must have the same immutability in different writable datastores. The immutability of data nodes is protocol and user independent. The immutability and configured value of an existing node MUST only change via software upgrade, hardware resources change, or license change.¶

4. "Immutable" Metadata Annotation

module: ietf-immutable
  augment /ncds:get-data/ncds:input:
    +---w with-immutable?   empty {immutable}?
  augment /nc:get-config/nc:input:
    +---w with-immutable?   empty {immutable}?
  augment /nc:get/nc:input:
    +---w with-immutable?   empty {immutable}?

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

5. Use of Immutable Flag for Different Statements

This section defines what the immutable flag means to the client for each instance of YANG data node statement.¶

Throughout this section, the word "change" refers to create, update, and delete.¶

6. Immutability of Interior Nodes

Immutability is a conceptual operational state value that is recursively applied to descendants, which may reset the immutability state as needed, thereby affecting their descendants. There is no limit to the number of times the immutability state may change in a data tree.¶

If the "immutable" metadata annotation for returned child node is omitted, it has the same immutability as its parent node. The immutability of top hierarchy of returned nodes is false by default. Servers may suppress the annotation if it is inherited from its parent node or uses the default value as the top-level node, but are not precluded from returning the annotation on every single element.¶

For example, the following XML snippets shows applications configuration a server might return:¶

<applications im:immutable="false">
<application im:immutable="true">
  <name>ssh</name>
  <protocol>tcp</protocol>
  <port-number im:immutable="false">22</port-number>
</application>
<application im:immutable="false">
  <name>my-ssh</name>
  <protocol>tcp</protocol>
  <port-number>10022</port-number>
</application>
</applications>

In the example, there are two "application" list entries inside "applications" container node. The "immutable" metadata attribute for applications container instance is "false", which is also its default value as the top-level element, and thus can be omitted. The "application" list entry named "ssh" is immutable with the immutability of its child node "port-number" being explicitly toggled. The other child nodes inside "ssh" application instance inherit immutability from their parent node thus are also immutable. The "immutable" metadata attribute for application list entry named "my-ssh" is "false", which is also the same value as its parent node, and thus can be omitted.¶

7. System Configuration Datastore Interactions

Immutable configuration can only be created, updated and deleted by the server, and it is present in <system>, if implemented. That said, the existence of immutable configuration is independent of whether <system> is implemented or not. Not all system configuration data is immutable. Immutable configuration does not appear in <running> unless it is explicitly provided by the client or copied by the server via "resolve-system" parameter defined in [I-D.ietf-netmod-system-config].¶

A client may create/delete immutable nodes with same values as found in <system> (if implemented) in read-write configuration datastore (e.g., <candidate>, <running>), which merely mean making immutable nodes visible/invisible in the datastore.¶

8. NACM Interactions

The server rejects an operation request due to immutability when it tries to perform the operation on the request data. It happens after any access control processing, if the Network Configuration Access Control Model (NACM) [RFC8341] is implemented on a server. For example, if an operation requests to override an immutable configuration data, but the server checks the user is not authorized to perform the requested access operation on the request data, the request is rejected with an "access-denied" error.¶

9. YANG Module

This module imports definitions from [RFC6241] and [RFC8526].¶

<CODE BEGINS> file "ietf-immutable@2024-06-04.yang"

module ietf-immutable {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-immutable";
  prefix im;

  import ietf-yang-metadata {
    prefix md;
  }
  import ietf-netconf {
    prefix nc;
    reference
      "RFC 6241: Network Configuration Protocol (NETCONF)";
  }
  import ietf-netconf-nmda {
    prefix ncds;
    reference
      "RFC 8526: NETCONF Extensions to Support the Network
       Management Datastore Architecture";
  }
  organization
    "IETF Network Modeling (NETMOD) Working Group";

  contact
    "WG Web: <https://datatracker.ietf.org/wg/netmod/>
     WG List: <mailto:netmod@ietf.org>
     Author: Qiufang Ma
             <mailto:maqiufang1@huawei.com>
     Author: Qin Wu
             <mailto:bill.wu@huawei.com>
     Author: Balazs Lengyel
             <mailto:balazs.lengyel@ericsson.com>
     Author: Hongwei Li
             <mailto:flycoolman@gmail.com>";

  description
    "This module defines a metadata annotation called 'immutable'
     to allow the server to formally document existing behavior on
     the mutability of some system configuration. Clients may use
     'immutable' metadata annotation provided by the server to know
     beforehand why certain otherwise valid configuration requests
     will cause the server to return an error.

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

     This version of this YANG module is part of RFC HHHH
     (https://www.rfc-editor.org/info/rfcHHHH); see the RFC
     itself for full legal notices.

     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 (RFC 2119)
     (RFC 8174) when, and only when, they appear in all
     capitals, as shown here.";

  revision 2024-06-04 {
    description
      "Initial revision.";
    // RFC Ed.: replace XXXX and remove this comment
    reference
      "RFC XXXX: YANG Metadata Annotation for Immutable Flag";
  }

  md:annotation immutable {
    type boolean;
    description
      "The 'immutable' metadata annotation indicates the
       immutability of an instantiated data node. It takes as a
       value 'true' or 'false'. If the 'immutable' metadata
       annotation is not specified, the default value is the
       same as the value of its parent node in the data tree. The
       default value for a top-level instance node is false if not
       specified.";
  }

  feature immutable {
    description
      "Indicates that the server supports the 'immutable' metadata
       annotation.";
  }

  grouping with-immutable-grouping {
    description
      "Grouping for the with-immutable parameter that augments the
       RPC operations.";
    leaf with-immutable {
      type empty;
      description
        "If this parameter is present, the server returns the
         'immutable' annotation for configuration that it
         internally thinks immutable.";
    }
  }
  augment "/ncds:get-data/ncds:input" {
    if-feature "immutable";
    description
      "Allows the server to include 'immutable' metadata
       annotations in its response to get-data operation.";
    uses with-immutable-grouping;
  }
  augment "/nc:get-config/nc:input" {
    if-feature "immutable";
    description
      "Allows the server to include 'immutable' metadata
       annotations in its response to get-config operation.";
    uses with-immutable-grouping;
  }
  augment "/nc:get/nc:input" {
    if-feature "immutable";
    description
      "Allows the server to include 'immutable' metadata
       annotations in its response to get operation.";
    uses with-immutable-grouping;
  }
}

<CODE ENDS>

10. Security Considerations

This section uses the template described in Section 3.7 of [I-D.ietf-netmod-rfc8407bis].¶

The "ietf-immutable" YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446].¶

The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content.¶

The YANG module specified in this document defines a metadata annotation, it also extends the RPC operations of the NETCONF protocol in [RFC6241] and [RFC8526].¶

The security considerations for the Defining and Using Metadata with YANG (see Section 9 of [RFC7952]) apply to the metadata annotation defined in this document.¶

The security considerations for the NETCONF protocol operations (see Section 9 of [RFC6241] and Section 6 of [RFC8526]) still apply to the operations extended in this document.¶

11. IANA Considerations

        URI: urn:ietf:params:xml:ns:yang:ietf-immutable
        Registrant Contact: The IESG.
        XML: N/A, the requested URIs are XML namespaces.

        name: ietf-immutable
        prefix: im
        namespace: urn:ietf:params:xml:ns:yang:ietf-immutable
        RFC: XXXX

Index           Capability Identifier
----------------------------------------------------------------------
:with-immutable urn:ietf:params:restconf:capability:with-immutable:1.0

Appendix A. Detailed Use Cases

Appendix B. Existing Implementations

There are already a number of full or partial implementations of immutability:¶

• 3GPP TS 32.156 [TS32.156] and 28.623 [TS28.623]: Requirements and a partial solution¶

• ITU-T using ONF TR-531 [TR-531] concept on information model level but no YANG representation.¶

• Ericsson: requirements and solution¶

• YumaPro: requirements and solution¶

• Nokia: partial requirements and solution¶

• Huawei: partial requirements and solution¶

• Cisco using the concept at least in some YANG modules¶

• Junos OS provides a hidden and immutable configuration group called junos-defaults¶

Acknowledgments

Thanks to Kent Watsen, Jan Lindblad, Jason Sterne, Robert Wilton, Andy Bierman, Juergen Schoenwaelder, Reshad Rahman, Anthony Somerset, Lou Berger, Joe Clarke, and Scott Mansfield for reviewing, and providing important inputs to this document.¶

Authors' Addresses