diff --git a/draft-ietf-netmod-immutable-flag-01/draft-ietf-netmod-immutable-flag.html b/draft-ietf-netmod-immutable-flag-01/draft-ietf-netmod-immutable-flag.html new file mode 100644 index 0000000..1e78b74 --- /dev/null +++ b/draft-ietf-netmod-immutable-flag-01/draft-ietf-netmod-immutable-flag.html @@ -0,0 +1,2254 @@ + + + + + + +YANG Metadata Annotation for Immutable Flag + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Internet-Draftimmutable flagJune 2024
Ma, et al.Expires 31 December 2024[Page]
+
+
+
+
Workgroup:
+
netmod
+
Internet-Draft:
+
draft-ietf-netmod-immutable-flag-latest
+
Updates:
+
+6241, 8040, 8526 (if approved)
+
Published:
+
+ +
+
Intended Status:
+
Standards Track
+
Expires:
+
+
Authors:
+
+
+
Q. Ma, Ed. +
+
Huawei
+
+
+
Q. Wu
+
Huawei
+
+
+
B. Lengyel, Ed. +
+
Ericsson
+
+
+
H. Li
+
HPE
+
+
+
+
+

YANG Metadata Annotation for Immutable Flag

+
+

Abstract

+

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 called + "immutable" to flag which nodes are immutable.

+

Clients may use "immutable" annotations provided by the server, to + know beforehand why certain otherwise valid configuration requests + will cause the server to return an error.

+

The immutable flag is descriptive, documenting existing behavior, not + proscriptive, dictating server behavior.

+
+
+

+Discussion Venues +

+

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

+

Discussion of this document takes place on the + Network Modeling Working Group mailing list (netmod@ietf.org), + which is archived at https://mailarchive.ietf.org/arch/browse/netmod/.

+

Source for this draft and an issue tracker can be found at + https://github.com/netmod-wg/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.

+
+
+ +
+
+ ▲

+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:

+ +

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:

+ +

Appendix A describes the use cases in detail.

+
+
+

+1.1. Updates to RFC 6241 and RFC 8526 +

+

This document updates [RFC6241] and [RFC8526]. The NETCONF <get> and + <get-config> operations defined in [RFC6241], and <get-data> operation + defined in [RFC8526] are augmented with an additional input parameter + named "with-immutable", as specified in Section 4.2.1.

+
+
+
+
+

+1.2. Updates to RFC 8040 +

+

This document updates Sections 4.8 and 9.1.1 of [RFC8040] to add an + additional input parameter named "with-immutable", as specified in Section 4.2.2.

+
+
+
+
+

+1.3. Editorial Note (To be removed by RFC Editor) +

+

Note to the RFC Editor: This section is to be removed prior to publication.

+

This document contains placeholder values that need to be replaced with finalized + values at the time of publication. This note summarizes all of the + substitutions that are needed. No other RFC Editor instructions are specified + elsewhere in this document.

+

Please apply the following replacements:

+
    +
  • +

    XXXX --> the assigned RFC number for this draft

    +
    • +
  • +

    2024-06-04 --> the actual date of the publication of this document

    +
    • +
+
+
+
+
+
+
+

+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]:

+ +

The document uses the following definition in [RFC7950]:

+ +

The document uses the following definition in [RFC8341]:

+ +

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 +

+
+
+

+4.1. Definition +

+

The immutable flag which is defined as the metadata annotation takes a boolean + value, and it is returned as requested by the client using a "with-immutable" + parameter (Section 4.2). If the "immutable" metadata annotation for + configuration is not specified, the default "immutable" value is the + same as the immutability of its parent node in the data tree (Section 6). + The immutable metadata annotation value for a top-level instance + node is "false" if not specified.

+

Note that "immutable" metadata annotations are used to annotate data node + instances. A list may have multiple instances in the data tree, + servers may annotate some of the instances as immutable, while others as + mutable.

+

Servers MUST ignore any immutable annotations sent from the client.

+
+
+
+
+

+4.2. "with-immutable" Parameter +

+

This section specifies the NETCONF and RESTCONF protocol extensions to support + "with-immutable" parameter. The "immutable" metadata annotations are not returned + in a response unless explicitly requested by the client using this parameter.

+
+
+

+4.2.1. NETCONF Extensions to Support "with-immutable" +

+

This doument updates [RFC6241] to augment the <get-config> and <get> + operations with an additional parameter named "with-immutable". The + <get-data> operation defined in [RFC8526] is also updated to support + this parameter. If present, this parameter requests that the server includes + the "immutable" metadata annotations in its response.

+

Figure 1 provides the tree structure [RFC8340] of augmentations to NETCONF + operations, as defined in the "ietf-immutable" module (Section 9).

+
+
+
+
+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}?
+
+
+
Figure 1: +Augmentations to NETCONF Operations +
+
+

Servers' support for accepting "with-immutable" parameter and returning "immutable" + annotations is identified with the feature "immutable".

+
+
+
+
+

+4.2.2. RESTCONF Extensions to Support "with-immutable" +

+

This document extends Sections 4.8 and 9.1.1 of [RFC8040] to add a query + parameter named "with-immutable" to the GET operation. If present, this parameter + requests that the server includes the "immutable" metadata annotations in its + response. This parameter is only allowed with no values carried. If it has + any unexpected value, then a "404 Bad Request" status-line is returned.

+

To enable a RESTCONF client to discover if the "with-immutable" query parameter + is supported by the server, the following capability URI is defined:

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

+
+
+

+5.1. The "leaf" Statement +

+

When a leaf node instance is immutable, its value cannot change.

+
+
+
+
+

+5.2. The "leaf-list" Statement +

+

When a leaf-list node instance is immutable, its value cannot change.

+

The immutable annotation attached to the individual leaf-list instance + provides immutability with respect to the instance itself. If leaf-list + inherits immutability from an ancestor (e.g., container), it is identical + to each individual leaf-list entry being annotated without any bearing on the + entry ordering and addition of new entries.

+
+
+
+
+

+5.3. The "container" Statement +

+

When a container node instance is immutable, it cannot change, unless + the immutability of its descendant node is toggled.

+

By default, as with all interior nodes, immutability is recursively + applied to descendants (Section 6).

+
+
+
+
+

+5.4. The "list" Statement +

+

When a list node instance is immutable, it cannot change, unless the + immutability of its descendant node is toggled.

+

By default, as with all interior nodes, immutability is recursively + applied to descendants (Section 6).

+

The immutable annotation attached to the individual list instance provides + immutability with respect to the instance itself. If list inherits immutability + from an ancestor (e.g., container), it is identical to each individual list + entry being annotated without any bearing on the entry ordering and addition + of new entries.

+
+
+
+
+

+5.5. The "anydata" Statement +

+

When an anydata node instance is immutable, it cannot change. Additionally, + as with all interior nodes, immutability is recursively applied to + descendants (Section 6).

+
+
+
+
+

+5.6. The "anyxml" Statement +

+

When an "anyxml" node instance is immutable, it cannot change. Additionally, + as with all interior nodes, immutability is recursively applied to + descendants (Section 6).

+
+
+
+
+
+
+

+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 +

+
+
+

+11.1. The "IETF XML" Registry +

+

This document registers one XML namespace URN in the 'IETF XML registry', + following the format defined in [RFC3688].

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

+11.2. The "YANG Module Names" Registry +

+

This document registers one module name in the 'YANG Module Names' +registry, defined in [RFC6020].

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

+11.3. RESTCONF Capability URN Registry +

+

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

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

+12. References +

+
+
+

+12.1. Normative References +

+
+
[RFC2119]
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
+
+
[RFC3688]
+
+Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, , <https://www.rfc-editor.org/rfc/rfc3688>.
+
+
[RFC6020]
+
+Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, , <https://www.rfc-editor.org/rfc/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, , <https://www.rfc-editor.org/rfc/rfc6241>.
+
+
[RFC6242]
+
+Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, , <https://www.rfc-editor.org/rfc/rfc6242>.
+
+
[RFC7950]
+
+Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, , <https://www.rfc-editor.org/rfc/rfc7950>.
+
+
[RFC7952]
+
+Lhotka, L., "Defining and Using Metadata with YANG", RFC 7952, DOI 10.17487/RFC7952, , <https://www.rfc-editor.org/rfc/rfc7952>.
+
+
[RFC8040]
+
+Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, , <https://www.rfc-editor.org/rfc/rfc8040>.
+
+
[RFC8174]
+
+Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
+
+
[RFC8341]
+
+Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, , <https://www.rfc-editor.org/rfc/rfc8341>.
+
+
[RFC8446]
+
+Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, , <https://www.rfc-editor.org/rfc/rfc8446>.
+
+
[RFC8526]
+
+Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "NETCONF Extensions to Support the Network Management Datastore Architecture", RFC 8526, DOI 10.17487/RFC8526, , <https://www.rfc-editor.org/rfc/rfc8526>.
+
+
+
+
+
+
+

+12.2. Informative References +

+
+
[I-D.ietf-netmod-rfc8407bis]
+
+Bierman, A., Boucadair, M., and Q. Wu, "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", Work in Progress, Internet-Draft, draft-ietf-netmod-rfc8407bis-12, , <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-rfc8407bis-12>.
+
+
[I-D.ietf-netmod-system-config]
+
+Ma, Q., Wu, Q., and C. Feng, "System-defined Configuration", Work in Progress, Internet-Draft, draft-ietf-netmod-system-config-08, , <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-system-config-08>.
+
+
[RFC8340]
+
+Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, , <https://www.rfc-editor.org/rfc/rfc8340>.
+
+
[RFC8343]
+
+Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, DOI 10.17487/RFC8343, , <https://www.rfc-editor.org/rfc/rfc8343>.
+
+
[RFC8530]
+
+Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. Liu, "YANG Model for Logical Network Elements", RFC 8530, DOI 10.17487/RFC8530, , <https://www.rfc-editor.org/rfc/rfc8530>.
+
+
[TR-531]
+
+ONF, "UML to YANG Mapping Guidelines", , <https://wiki.opennetworking.org/download/attachments/376340494/Draft_TR-531_UML-YANG_Mapping_Gdls_v1.1.03.docx?version=5&modificationDate=1675432243513&api=v2>.
+
+
[TS28.623]
+
+3GPP, "Telecommunication management; Generic Network Resource Model (NRM) Integration Reference Point (IRP); Solution Set (SS) definitions", <https://www.3gpp.org/ftp/Specs/archive/28_series/28.623/28623-i02.zip>.
+
+
[TS32.156]
+
+3GPP, "Telecommunication management; Fixed Mobile Convergence (FMC) Model repertoire", <https://www.3gpp.org/ftp/Specs/archive/32_series/32.156/32156-h10.zip>.
+
+
+
+
+
+
+
+

+Appendix A. Detailed Use Cases +

+
+
+

+A.1. UC1 - Modeling of server capabilities +

+

System capabilities might be represented as system-defined data nodes in + the model. Configurable data nodes might need constraints specified as + "when", "must" or "path" statements to ensure that configuration is set + according to the system's capabilities. For example,

+
    +
  • +

    A timer can support the values 1,5,8 seconds. This is defined in the + leaf-list 'supported-timer-values'.

    +
    • +
  • +

    When the configurable 'interface-timer' leaf is set, it should be ensured + that one of the supported values is used. The natural solution would be to + make the 'interface-timer' a leaf-ref pointing at the 'supported-timer-values'.

    +
    • +
+

However, this is not possible as 'supported-timer-values' must be + read-only thus config=false while 'interface-timer' must be writable + thus config=true. According to the rules of YANG it is not allowed + to put a constraint between config true and false data nodes.

+

The solution is that the supported-timer-values data node in the YANG + Model shall be defined as "config true" and shall also be marked with + the "immutable" annotation making it unchangeable. After this the + 'interface-timer' shall be defined as a leaf-ref pointing at the + 'supported-timer-values'.

+
+
+
+
+

+A.2. UC2 - HW based auto-configuration - Interface Example +

+

[RFC8343] defines a YANG data model for the management of network + interfaces. When a system-controlled interface is physically present, + the system creates an interface entry with valid name and type + values in <system> (if exists, see [I-D.ietf-netmod-system-config]).

+

The system-generated type value is dependent on and represents the HW + present, and as a consequence cannot be changed by the client. If a + client tries to set the type of an interface to a value that can + never be used by the system, the request will be rejected by the + server. The data is modelled as "config true" and should be annotated + as immutable.

+

Seemingly an alternative would be to model the list and these leaves + as "config false", but that does not work because:

+
    +
  • +

    The list cannot be marked as "config false", because it needs to contain + configurable child nodes, e.g., ip-address or enabled;

    +
    • +
  • +

    The key leaf (name) cannot be marked as "config false" as the list + itself is config true;

    +
    • +
  • +

    The type cannot be marked "config false", because we MAY need to + reference the type to make different configuration nodes + conditionally available.

    +
    • +
+
+
+
+
+

+A.3. UC3 - Predefined Administrator Roles +

+

User and group management is fundamental for setting up access + control rules (see Section 2.5 of [RFC8341]).

+

A device may provide a predefined user account (e.g., a system + administrator that is always available and has full privileges) for + initial system set up and management of other users/groups. It is + possible that clients can define a new user/group and grant it + particular privileges, but the predefined administrator account and + its granted access cannot be modified.

+
+
+
+
+

+A.4. UC4 - Declaring immutable system configuration from an LNE's perspective +

+

An LNE (logical network element) is an independently managed virtual + network device made up of resources allocated to it from its host or + parent network device [RFC8530]. The host device may allocate some + resources to an LNE, which from an LNE's perspective is provided by + the system and may not be modifiable.

+

For example, a host may allocate an interface to an LNE with a valid + MTU value as its management interface, so that the allocated + interface should then be accessible as the LNE-specific instance of + the interface model. The assigned MTU value is system-created and + immutable from the context of the LNE.

+
+
+
+
+
+
+

+Appendix B. Existing Implementations +

+

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

+ +
+
+
+
+

+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 +

+
+
Qiufang Ma (editor)
+
Huawei
+
101 Software Avenue, Yuhua District
+
Nanjing, Jiangsu
+
210012
+
China
+ +
+
+
Qin Wu
+
Huawei
+
101 Software Avenue, Yuhua District
+
Nanjing, Jiangsu
+
210012
+
China
+ +
+
+
Balazs Lengyel (editor)
+
Ericsson
+ +
+
+
Hongwei Li
+
HPE
+ +
+
+
+ + + diff --git a/draft-ietf-netmod-immutable-flag-01/draft-ietf-netmod-immutable-flag.txt b/draft-ietf-netmod-immutable-flag-01/draft-ietf-netmod-immutable-flag.txt new file mode 100644 index 0000000..13549c3 --- /dev/null +++ b/draft-ietf-netmod-immutable-flag-01/draft-ietf-netmod-immutable-flag.txt @@ -0,0 +1,891 @@ + + + + +netmod Q. Ma, Ed. +Internet-Draft Q. Wu +Updates: 6241, 8040, 8526 (if approved) Huawei +Intended status: Standards Track B. Lengyel, Ed. +Expires: 31 December 2024 Ericsson + H. Li + HPE + 29 June 2024 + + + YANG Metadata Annotation for Immutable Flag + draft-ietf-netmod-immutable-flag-latest + +Abstract + + 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 called + "immutable" to flag which nodes are immutable. + + Clients may use "immutable" annotations provided by the server, to + know beforehand why certain otherwise valid configuration requests + will cause the server to return an error. + + The immutable flag is descriptive, documenting existing behavior, not + proscriptive, dictating server behavior. + +Discussion Venues + + This note is to be removed before publishing as an RFC. + + Discussion of this document takes place on the Network Modeling + Working Group mailing list (netmod@ietf.org), which is archived at + https://mailarchive.ietf.org/arch/browse/netmod/. + + Source for this draft and an issue tracker can be found at + https://github.com/netmod-wg/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 + 1.1. Updates to RFC 6241 and RFC 8526 + 1.2. Updates to RFC 8040 + 1.3. Editorial Note (To be removed by RFC Editor) + 2. Conventions and Definitions + 3. Applicability + 4. "Immutable" Metadata Annotation + 4.1. Definition + 4.2. "with-immutable" Parameter + 4.2.1. NETCONF Extensions to Support "with-immutable" + 4.2.2. RESTCONF Extensions to Support "with-immutable" + 5. Use of Immutable Flag for Different Statements + 5.1. The "leaf" Statement + 5.2. The "leaf-list" Statement + 5.3. The "container" Statement + 5.4. The "list" Statement + 5.5. The "anydata" Statement + 5.6. The "anyxml" Statement + 6. Immutability of Interior Nodes + 7. System Configuration Datastore Interactions + 8. NACM Interactions + 9. YANG Module + 10. Security Considerations + 11. IANA Considerations + 11.1. The "IETF XML" Registry + 11.2. The "YANG Module Names" Registry + 11.3. RESTCONF Capability URN Registry + 12. References + 12.1. Normative References + 12.2. Informative References + Appendix A. Detailed Use Cases + A.1. UC1 - Modeling of server capabilities + A.2. UC2 - HW based auto-configuration - Interface Example + A.3. UC3 - Predefined Administrator Roles + A.4. UC4 - Declaring immutable system configuration from an + LNE's perspective + Appendix B. Existing Implementations + Acknowledgments + Authors' Addresses + +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. + +1.1. Updates to RFC 6241 and RFC 8526 + + This document updates [RFC6241] and [RFC8526]. The NETCONF and + operations defined in [RFC6241], and + operation defined in [RFC8526] are augmented with an additional input + parameter named "with-immutable", as specified in Section 4.2.1. + +1.2. Updates to RFC 8040 + + This document updates Sections 4.8 and 9.1.1 of [RFC8040] to add an + additional input parameter named "with-immutable", as specified in + Section 4.2.2. + +1.3. Editorial Note (To be removed by RFC Editor) + + Note to the RFC Editor: This section is to be removed prior to + publication. + + This document contains placeholder values that need to be replaced + with finalized values at the time of publication. This note + summarizes all of the substitutions that are needed. No other RFC + Editor instructions are specified elsewhere in this document. + + Please apply the following replacements: + + * XXXX --> the assigned RFC number for this draft + + * 2024-06-04 --> the actual date of the publication of this document + +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 + (if implemented, see [I-D.ietf-netmod-system-config]), + and 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 + +4.1. Definition + + The immutable flag which is defined as the metadata annotation takes + a boolean value, and it is returned as requested by the client using + a "with-immutable" parameter (Section 4.2). If the "immutable" + metadata annotation for configuration is not specified, the default + "immutable" value is the same as the immutability of its parent node + in the data tree (Section 6). The immutable metadata annotation + value for a top-level instance node is "false" if not specified. + + Note that "immutable" metadata annotations are used to annotate data + node instances. A list may have multiple instances in the data tree, + servers may annotate some of the instances as immutable, while others + as mutable. + + Servers MUST ignore any immutable annotations sent from the client. + +4.2. "with-immutable" Parameter + + This section specifies the NETCONF and RESTCONF protocol extensions + to support "with-immutable" parameter. The "immutable" metadata + annotations are not returned in a response unless explicitly + requested by the client using this parameter. + +4.2.1. NETCONF Extensions to Support "with-immutable" + + This doument updates [RFC6241] to augment the and + operations with an additional parameter named "with-immutable". The + operation defined in [RFC8526] is also updated to support + this parameter. If present, this parameter requests that the server + includes the "immutable" metadata annotations in its response. + + Figure 1 provides the tree structure [RFC8340] of augmentations to + NETCONF operations, as defined in the "ietf-immutable" module + (Section 9). + + 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}? + + Figure 1: Augmentations to NETCONF Operations + + Servers' support for accepting "with-immutable" parameter and + returning "immutable" annotations is identified with the feature + "immutable". + +4.2.2. RESTCONF Extensions to Support "with-immutable" + + This document extends Sections 4.8 and 9.1.1 of [RFC8040] to add a + query parameter named "with-immutable" to the GET operation. If + present, this parameter requests that the server includes the + "immutable" metadata annotations in its response. This parameter is + only allowed with no values carried. If it has any unexpected value, + then a "404 Bad Request" status-line is returned. + + To enable a RESTCONF client to discover if the "with-immutable" query + parameter is supported by the server, the following capability URI is + defined: + + 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. + +5.1. The "leaf" Statement + + When a leaf node instance is immutable, its value cannot change. + +5.2. The "leaf-list" Statement + + When a leaf-list node instance is immutable, its value cannot change. + + The immutable annotation attached to the individual leaf-list + instance provides immutability with respect to the instance itself. + If leaf-list inherits immutability from an ancestor (e.g., + container), it is identical to each individual leaf-list entry being + annotated without any bearing on the entry ordering and addition of + new entries. + +5.3. The "container" Statement + + When a container node instance is immutable, it cannot change, unless + the immutability of its descendant node is toggled. + + By default, as with all interior nodes, immutability is recursively + applied to descendants (Section 6). + +5.4. The "list" Statement + + When a list node instance is immutable, it cannot change, unless the + immutability of its descendant node is toggled. + + By default, as with all interior nodes, immutability is recursively + applied to descendants (Section 6). + + The immutable annotation attached to the individual list instance + provides immutability with respect to the instance itself. If list + inherits immutability from an ancestor (e.g., container), it is + identical to each individual list entry being annotated without any + bearing on the entry ordering and addition of new entries. + +5.5. The "anydata" Statement + + When an anydata node instance is immutable, it cannot change. + Additionally, as with all interior nodes, immutability is recursively + applied to descendants (Section 6). + +5.6. The "anyxml" Statement + + When an "anyxml" node instance is immutable, it cannot change. + Additionally, as with all interior nodes, immutability is recursively + applied to descendants (Section 6). + +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: + + + + ssh + tcp + 22 + + + my-ssh + tcp + 10022 + + + + 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 , if implemented. That + said, the existence of immutable configuration is independent of + whether is implemented or not. Not all system configuration + data is immutable. Immutable configuration does not appear in + 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 (if implemented) in read-write configuration datastore + (e.g., , ), 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]. + + 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: + WG List: + Author: Qiufang Ma + + Author: Qin Wu + + Author: Balazs Lengyel + + Author: Hongwei Li + "; + + 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; + } + } + + +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 + +11.1. The "IETF XML" Registry + + This document registers one XML namespace URN in the 'IETF XML + registry', following the format defined in [RFC3688]. + + URI: urn:ietf:params:xml:ns:yang:ietf-immutable + Registrant Contact: The IESG. + XML: N/A, the requested URIs are XML namespaces. + +11.2. The "YANG Module Names" Registry + + This document registers one module name in the 'YANG Module Names' + registry, defined in [RFC6020]. + + name: ietf-immutable + prefix: im + namespace: urn:ietf:params:xml:ns:yang:ietf-immutable + RFC: XXXX + +11.3. RESTCONF Capability URN Registry + + This document defines the following capability identifier URNs in the + "RESTCONF Capability URNs" registry defined in [RFC8040]: + + Index Capability Identifier + ---------------------------------------------------------------------- + :with-immutable urn:ietf:params:restconf:capability:with-immutable:1.0 + +12. References + +12.1. 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, + . + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + DOI 10.17487/RFC3688, January 2004, + . + + [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for + the Network Configuration Protocol (NETCONF)", RFC 6020, + DOI 10.17487/RFC6020, October 2010, + . + + [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, + . + + [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure + Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, + . + + [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", + RFC 7950, DOI 10.17487/RFC7950, August 2016, + . + + [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", + RFC 7952, DOI 10.17487/RFC7952, August 2016, + . + + [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF + Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration + Access Control Model", STD 91, RFC 8341, + DOI 10.17487/RFC8341, March 2018, + . + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + . + + [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., + and R. Wilton, "NETCONF Extensions to Support the Network + Management Datastore Architecture", RFC 8526, + DOI 10.17487/RFC8526, March 2019, + . + +12.2. Informative References + + [I-D.ietf-netmod-rfc8407bis] + Bierman, A., Boucadair, M., and Q. Wu, "Guidelines for + Authors and Reviewers of Documents Containing YANG Data + Models", Work in Progress, Internet-Draft, draft-ietf- + netmod-rfc8407bis-12, 21 June 2024, + . + + [I-D.ietf-netmod-system-config] + Ma, Q., Wu, Q., and C. Feng, "System-defined + Configuration", Work in Progress, Internet-Draft, draft- + ietf-netmod-system-config-08, 18 June 2024, + . + + [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", + BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, + . + + [RFC8343] Bjorklund, M., "A YANG Data Model for Interface + Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, + . + + [RFC8530] Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. + Liu, "YANG Model for Logical Network Elements", RFC 8530, + DOI 10.17487/RFC8530, March 2019, + . + + [TR-531] ONF, "UML to YANG Mapping Guidelines", February 2023, + . + + [TS28.623] 3GPP, "Telecommunication management; Generic Network + Resource Model (NRM) Integration Reference Point (IRP); + Solution Set (SS) definitions", + . + + [TS32.156] 3GPP, "Telecommunication management; Fixed Mobile + Convergence (FMC) Model repertoire", + . + +Appendix A. Detailed Use Cases + +A.1. UC1 - Modeling of server capabilities + + System capabilities might be represented as system-defined data nodes + in the model. Configurable data nodes might need constraints + specified as "when", "must" or "path" statements to ensure that + configuration is set according to the system's capabilities. For + example, + + * A timer can support the values 1,5,8 seconds. This is defined in + the leaf-list 'supported-timer-values'. + + * When the configurable 'interface-timer' leaf is set, it should be + ensured that one of the supported values is used. The natural + solution would be to make the 'interface-timer' a leaf-ref + pointing at the 'supported-timer-values'. + + However, this is not possible as 'supported-timer-values' must be + read-only thus config=false while 'interface-timer' must be writable + thus config=true. According to the rules of YANG it is not allowed + to put a constraint between config true and false data nodes. + + The solution is that the supported-timer-values data node in the YANG + Model shall be defined as "config true" and shall also be marked with + the "immutable" annotation making it unchangeable. After this the + 'interface-timer' shall be defined as a leaf-ref pointing at the + 'supported-timer-values'. + +A.2. UC2 - HW based auto-configuration - Interface Example + + [RFC8343] defines a YANG data model for the management of network + interfaces. When a system-controlled interface is physically + present, the system creates an interface entry with valid name and + type values in (if exists, see + [I-D.ietf-netmod-system-config]). + + The system-generated type value is dependent on and represents the HW + present, and as a consequence cannot be changed by the client. If a + client tries to set the type of an interface to a value that can + never be used by the system, the request will be rejected by the + server. The data is modelled as "config true" and should be + annotated as immutable. + + Seemingly an alternative would be to model the list and these leaves + as "config false", but that does not work because: + + * The list cannot be marked as "config false", because it needs to + contain configurable child nodes, e.g., ip-address or enabled; + + * The key leaf (name) cannot be marked as "config false" as the list + itself is config true; + + * The type cannot be marked "config false", because we MAY need to + reference the type to make different configuration nodes + conditionally available. + +A.3. UC3 - Predefined Administrator Roles + + User and group management is fundamental for setting up access + control rules (see Section 2.5 of [RFC8341]). + + A device may provide a predefined user account (e.g., a system + administrator that is always available and has full privileges) for + initial system set up and management of other users/groups. It is + possible that clients can define a new user/group and grant it + particular privileges, but the predefined administrator account and + its granted access cannot be modified. + +A.4. UC4 - Declaring immutable system configuration from an LNE's + perspective + + An LNE (logical network element) is an independently managed virtual + network device made up of resources allocated to it from its host or + parent network device [RFC8530]. The host device may allocate some + resources to an LNE, which from an LNE's perspective is provided by + the system and may not be modifiable. + + For example, a host may allocate an interface to an LNE with a valid + MTU value as its management interface, so that the allocated + interface should then be accessible as the LNE-specific instance of + the interface model. The assigned MTU value is system-created and + immutable from the context of the LNE. + +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 + + Qiufang Ma (editor) + Huawei + 101 Software Avenue, Yuhua District + Nanjing, Jiangsu + 210012 + China + Email: maqiufang1@huawei.com + + + Qin Wu + Huawei + 101 Software Avenue, Yuhua District + Nanjing, Jiangsu + 210012 + China + Email: bill.wu@huawei.com + + + Balazs Lengyel (editor) + Ericsson + Email: balazs.lengyel@ericsson.com + + + Hongwei Li + HPE + Email: flycoolman@gmail.com diff --git a/draft-ietf-netmod-immutable-flag-01/index.html b/draft-ietf-netmod-immutable-flag-01/index.html new file mode 100644 index 0000000..9f73a98 --- /dev/null +++ b/draft-ietf-netmod-immutable-flag-01/index.html @@ -0,0 +1,45 @@ + + + + netmod-wg/immutable-flag draft-ietf-netmod-immutable-flag-01 preview + + + + +

Editor's drafts for draft-ietf-netmod-immutable-flag-01 branch of netmod-wg/immutable-flag

+ + + + + + +
immutable flagplain textsame as main
+ + + diff --git a/index.html b/index.html index e38dfb6..5c1f7c1 100644 --- a/index.html +++ b/index.html @@ -24,6 +24,14 @@

Editor's drafts for main branch of draft-ietf-netmod-immutable-flag-01

+ + + + + + +
immutable flagplain textsame as main