]> Huawei

101 Software Avenue, Yuhua District Nanjing, Jiangsu 210012 China maqiufang1@huawei.com

Huawei

101 Software Avenue, Yuhua District Nanjing, Jiangsu 210012 China bill.wu@huawei.com

Ericsson

balazs.lengyel@ericsson.com

HPE

flycoolman@gmail.com

Operations and Management netmod immutable flag system configuration This document defines a mechanism to formally document an 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 an existing behavior, not proscriptive, dictating server behaviors. This document updates RFC 8040 and RFC 8526. Discussion Venues Discussion of this document takes place on the Network Modeling Working Group mailing list (netmod@ietf.org), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction This document defines a YANG metadata annotation to formally document an existing model handling behavior that has been used by multiple standard organizations (e.g., 3GPP TS 32.156 , 28.623 , and ONF TR-531 ) and vendors. YANG 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 clients (that is, 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 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 a server always rejects a client's attempt to override some system-provided data because it internally thinks the data is 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 an approach to formally document an existing behavior, implemented by servers in production, on the immutability of some system-provided data, using a YANG metadata annotation called "immutable" to flag which nodes are immutable. This document does not regulate server behaviors. That said, it is expected that a server will return an error with an error-tag containing "invalid-value" if a client attempts to modify an immutable node. A non-exhaustive list of already implemented and potential use cases is provided below:

• UC1: Modeling of server capabilities ()
• UC2: Hardware based auto-configuration ()
• UC3: Predefined administrator roles ()
• UC4: Declaring immutable system configuration from the perspective of a Logical Network Element (LNE) ()

Updates to RFC 8040 This document updates Sections and of to add an additional query parameter named "with-immutability", as specified in .

Updates to RFC 8526 This document updates to add an additional input parameter named "with-immutability" for the <get-data> operation, as specified in .

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
• YYYY --> RFC number assigned to
• 2026-05-26 --> the actual date of the publication of this document

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 when, and only when, they appear in all capitals, as shown here. The document uses the following term defined in :

• configuration data

The document uses the following terms defined in :

• data node
• leaf
• leaf-list
• container
• list
• anydata
• anyxml
• interior node
• data tree

The document uses the following term defined in :

• access operation

The document uses the following term defined in :

• system configuration

This document defines the following term:

immutable flag:

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

Applicability While the immutable flag applies to all configuration nodes, its value MUST NOT be set to true for configuration data that is not system configuration. The immutable flag is only visible in read-only datastores (i.e., <system> , <intended>, and <operational>) when a "with-immutability" parameter is carried (). However, this only serves as descriptive information about the instance node itself, but has no effect on the handling of the read-only datastore. If the immutable flag is requested to be returned for an invalid datastore (i.e., any datastore other than <system>, <intended>, or <operational>), then the server MUST return an error response with the error-tag value "unknown-element". Configuration data has the same immutability if it appears in different datastores. The immutability of configuration data is protocol and user independent.

"Immutable" Metadata Annotation

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-immutability" parameter (). If the "immutable" metadata annotation for a configuration node is not specified, the default "immutable" value is the same as the value of its parent node in the data tree (). The "immutable" metadata annotation value for a top-level instance node is "false" if not specified. A node that is annotated as immutable cannot be changed via configuring a different value in read-write configuration datastores (e.g., <running>), nor is there any way to delete the node from the intended datastore, which is the merged result of <running> and <system> as defined in . The node MAY be explicitly configured by a client in <running> with the same value and that configuration in <running> may subsequently be removed, but neither of these edits will change the configuration in <intended> (if implemented) on the device. 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.

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

NETCONF Extensions to Support "with-immutability" This document updates to augment the <get-data> operation with an additional parameter named "with-immutability" when interacting with read-only datastores. If present, this parameter requests that the server includes the "immutable" metadata annotations in its response. provides the tree structure of augmentations to NETCONF operations, as defined in the "ietf-immutable-annotation" module ().

Augmentations to NETCONF Operations

To discover if the "with-immutability" parameter is supported by a server, a NETCONF client can query if the server implements "ietf-immutable-annotation" module by reading the YANG library information from the operational state datastore, as per . Refer to for an example of a NETCONF operation with "with-immutability" input parameter.

RESTCONF Extensions to Support "with-immutability" This document extends Sections and of to add a query parameter named "with-immutability" 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 when interacting with read-only datastores. If it has any unexpected value, then a "400 Bad Request" status-line is returned. RESTCONF protocol operations for the datastore resources are defined in . To enable a RESTCONF client to discover if the "with-immutability" query parameter is supported by a server, the following capability URI is defined: Refer to for an example of a RESTCONF operation with "with-immutability" query parameter.

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

The "leaf" Statement When a leaf node instance is immutable, it cannot be configured with a different value in read-write configuration datastores (e.g., <running>) or removed from <intended> (if implemented). Though it can be created/deleted in read-write configuration datastores (see Sections and ).

The "leaf-list" Statement When a leaf-list entry is immutable, it cannot be configured with a different value in read-write configuration datastore (e.g., <running>) or removed from <intended> (if implemented). Though it can be created/deleted in read-write configuration datastores (see Sections and ). The immutable annotation attached to an individual leaf-list entry provides immutability with respect to the entry itself. As per the restrictions in , annotations cannot be attached to an entire leaf-list instance and only to individual leaf-list entries, which implies a leaf-list as a whole can only inherit immutability from a parent node (e.g., container). If a leaf-list as a whole is immutable via inheritance from a parent node, any leaf-list entries cannot be added, modified, or reordered (if it is ordered-by user). Refer to for an example of immutability of leaf-lists.

The "container" Statement When a container node instance is immutable, it cannot be removed from <intended> (if implemented). Though it can be created/deleted in read-write configuration datastores (see Sections and ). Descendant nodes of a container recursively inherit the immutability of the container, unless the immutability is overridden by an "immutable" annotation on a descendant node ().

The "list" Statement When a list entry is immutable, it cannot be removed from <intended> (if implemented). Though it can be created/deleted in read-write configuration datastores (see Sections and ). Descendant nodes of a list entry recursively inherit the immutability of the list entry, unless the immutability is overridden by an "immutable" annotation on a descendant node (). The immutable annotation attached to an individual list entry provides immutability with respect to the entry itself. As per the restrictions in , annotations cannot be attached to an entire list instance and only to individual list entries, which implies a list as a whole can only inherit immutability from a parent node (e.g., container). If a list as a whole is immutable via inheritance from a parent node, any list entries cannot be added, removed, or reordered (if it is ordered-by user). Each list entry inherits the immutability of the list by default, unless the immutability is overridden by an "immutable" annotation on a list entry. Refer to for an example of immutability of lists.

The "anydata" Statement When an "anydata" node instance is immutable, it cannot be removed from <intended> (if implemented). Though it can be created/deleted in read-write configuration datastores (see Sections and ). Additionally, as with all interior nodes, immutability is recursively applied to descendants ().

The "anyxml" Statement When an "anyxml" node instance is immutable, it cannot be removed from <intended> (if implemented). Though it can be created/deleted in read-write configuration datastores (see Sections and ). Additionally, as with all interior nodes, immutability is recursively applied to descendants ().

Immutability of Interior Nodes Immutability is a property of a configuration data node instance, conveyed as metadata . It 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 a 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. Refer to for an example of how immutability is recursively inherited or explicitly reset by descendants.

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 configured. As specified in , a client MAY create/delete immutable nodes with same values as defined by server in read-write configuration datastore (e.g., <candidate>, <running>), which merely makes immutable nodes visible/invisible in the datastore.

NACM Interactions The server rejects an operation request due to immutability when it tries to perform the operation on the request data. Any immutability checking MUST be performed after access control decisions, if the Network Configuration Access Control Model (NACM) is implemented on a server. For example, if an operation requests to override an immutable configuration node, 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.

YANG Module This module imports definitions from , , , and . Editor: Qiufang Ma Editor: Qin Wu Editor: Balazs Lengyel Editor: 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) 2026 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). All revisions of IETF and IANA published modules can be found at the YANG Parameters registry group (https://www.iana.org/assignments/yang-parameters). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; revision 2026-05-26 { description "Initial revision."; 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'. An immutable node cannot be changed via configuring a different value in read-write configuration datastores (e.g., ), though it can be created/deleted in read-write configuration datastores. If not specified for a given configuration data node, the immutability is the same as the value of its parent node in the data tree. The default value of 'immutable' annotation for a top-level instance node is false if not specified."; } augment "/ncds:get-data/ncds:input" { description "Allows the server to include 'immutable' metadata annotations in its response to get-data operation."; leaf with-immutability { when "derived-from-or-self(../ncds:datastore,'sysds:system') " + "or derived-from-or-self(../ncds:datastore,'ds:intended') " + "or derived-from-or-self(../ncds:datastore,'ds:operational')"; type empty; description "If this parameter is present, the server returns the 'immutable' annotation for configuration that it considers immutable."; } } } ]]>

IANA Considerations

The "IETF XML" Registry IANA is requested to register the following URI in the "ns" registry within the "IETF XML Registry" group :

The "YANG Module Names" Registry IANA is requested to register the following YANG module in the "YANG Module Names" registry within the "YANG Parameters" registry group.

RESTCONF Capability URN Registry IANA is requested to register the following capability identifier URNs in the "RESTCONF Capability URNs" registry defined in :

Index:

:with-immutability

Capability Identifier:

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

Operational Considerations This document specifies a mechanism for clients to discover immutable system configuration before attempting modifications. Clients can leverage this information to avoid sending edit requests that would otherwise fail due to immutable nodes. The mechanism defined in this document is backward compatible with existing implementations. A legacy client unware of this mechanism will not include the "with-immutability" query parameter in its retrieval requests. Consequently, servers will process the request normally without returning any "immutable" metadata annotations. Conversely, a client explicitly requesting the immutable flag from a legacy server may either receive an error response for unsupported query parameter or have the parameter ignored, depending on the server's implementation.

Security Considerations This section is modeled after the template described in . The "ietf-immutable-annotation" YANG module defines a data model that is designed to be accessed via YANG-based management protocols, such as the Network Configuration Protocol (NETCONF) and RESTCONF . These YANG-based management protocols (1) have to use a secure transport layer (e.g., Secure Shell (SSH) , TLS , and QUIC ) and (2) have to use mutual authentication. The Network Configuration Access Control Model (NACM) 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 and . The "immutable" metadata annotation exposes the immutability of configuration data, which may provide hints for attackers to find vulnerabilities in the network, e.g., to leverage the immutability of some configuration to better craft an attack. Since immutable annotations are attached to the instances of configuration data nodes, it is only accessible to clients that have the permissions to read the annotated configuration nodes. The security considerations for the NETCONF protocol operations (see and ) also apply to the operations extended in this document.

References Normative References This document defines a YANG extension that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes. YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF). This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). This document extends the Network Configuration Protocol (NETCONF) defined in RFC 6241 in order to support the Network Management Datastore Architecture (NMDA) defined in RFC 8342. This document updates RFCs 6241 and 7950. The update to RFC 6241 adds new and operations and augments existing,, and operations. The update to RFC 7950 requires the usage of the YANG library (described in RFC 8525) by NETCONF servers implementing the NMDA. Huawei Huawei The Network Management Datastore Architecture (NMDA) in RFC 8342 defines several configuration datastores holding configuration. The contents of these configuration datastores are controlled by clients. This document introduces the concept of system configuration datastore holding configuration controlled by the system on which a server is running. The system configuration can be referenced (e.g., leafref) by configuration explicitly created by clients. This document updates RFC 8342. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK] The standardization of network configuration interfaces for use with the Network Configuration Protocol (NETCONF) or the RESTCONF protocol requires a structured and secure operating environment that promotes human usability and multi-vendor interoperability. There is a need for standard mechanisms to restrict NETCONF or RESTCONF protocol access for particular users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. This document defines such an access control model. This document obsoletes RFC 6536. This document extends the RESTCONF protocol defined in RFC 8040 in order to support the Network Management Datastore Architecture (NMDA) defined in RFC 8342. This document updates RFC 8040 by introducing new datastore resources, adding a new query parameter, and requiring the usage of the YANG library (described in RFC 8525) by RESTCONF servers implementing the NMDA. Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950. This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas. YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK] Informative References ONF 3GPP 3GPP This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. This document captures the current syntax used in YANG module tree diagrams. The purpose of this document is to provide a single location for this definition. This syntax may be updated from time to time based on the evolution of the YANG language. This document provides guidelines for authors and reviewers of specifications containing YANG data models, including IANA-maintained YANG modules. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) and RESTCONF protocol implementations that utilize YANG modules. This document obsoletes RFC 8407; it also updates RFC 8126 by providing additional guidelines for writing the IANA considerations for RFCs that specify IANA-maintained YANG modules. The Secure Shell Protocol (SSH) is a protocol for secure remote login and other secure network services over an insecure network. This document describes the SSH authentication protocol framework and public key, password, and host-based client authentication methods. Additional authentication methods are described in separate documents. The SSH authentication protocol runs on top of the SSH transport layer protocol and provides a single authenticated tunnel for the SSH connection protocol. [STANDARDS-TRACK] Independent This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705, 6066, 7627, and 8422 and obsoletes RFCs 5077, 5246, 6961, 8422, and 8446. This document also specifies new requirements for TLS 1.2 implementations. This document defines the core of the QUIC transport protocol. QUIC provides applications with flow-controlled streams for structured communication, low-latency connection establishment, and network path migration. QUIC includes security measures that ensure confidentiality, integrity, and availability in a range of deployment circumstances. Accompanying documents describe the integration of TLS for key negotiation, loss detection, and an exemplary congestion control algorithm. This document defines a YANG data model for the management of network interfaces. It is expected that interface-type-specific data models augment the generic interfaces data model defined in this document. The data model includes definitions for configuration and system state (status information and counters for the collection of statistics). The YANG data model in this document conforms to the Network Management Datastore Architecture (NMDA) defined in RFC 8342. This document obsoletes RFC 7223. This document defines a logical network element (LNE) YANG module that is compliant with the Network Management Datastore Architecture (NMDA). This module can be used to manage the logical resource partitioning that may be present on a network device. Examples of common industry terms for logical resource partitioning are logical systems or logical routers. The YANG model in this document conforms with NMDA as defined in RFC 8342.

Sample Use Cases

UC1: Modeling of Server Capabilities System capabilities might be represented as immutable configuration. Configurable data nodes might need constraints specified using "when", "must", or "path" statements to ensure that configuration is set according to the system's capabilities. For example, configurable timer (e.g., for an "interface-timer" or a "bfd-interval-timer") values are dependent on the underlying system timer resource limits.

• A timer might only support the values 1, 5, and 8 seconds, determined by the system capabilities. This is defined in the leaf-list 'supported-timer'.
• When the configurable 'interface-timer' leaf is set by a client, it should be ensured that one of the supported values is used. The natural solution would be to make the "interface-timer" a leafref pointing at the "supported-timer".

However, this is not possible as "supported-timer" 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 "config false" data nodes (). A solution is that the 'supported-timer' 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 leafref pointing at the 'supported-timer-values'.

UC2: Hardware-based Auto-configuration - Interface Example 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 ). The system-generated type value is dependent on and represents the hardware present, and as a consequence cannot be changed by clients. 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 modeled as "config true" and thus should be annotated as immutable. An alternative would be to model the list and these leafs 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.

UC3: Predefined Administrator Roles User and group management is fundamental for setting up access control rules (see ). 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 a new user/group can be defined granted particular privileges, but the predefined administrator account and its granted access are immutable.

UC4: Declaring Immutable System Configuration from the Perspective of a Logical Network Element (LNE) An LNE, as described in , is an independently managed virtual network device made up of resources allocated to it from its host or parent network device. 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.

Examples of Server's Immutable Behavior This section provides some examples to illustrate the server's behavior with immutable flag. These examples are not intended as recommendations for real-world deployments. The following fictional module is used throughout this section:

NETCONF Example to Retrieve Immutable Configuration illustrates a NETCONF request example to retrieve "user-groups" configuration in <system> with "with-immutability" parameter and the response that a server might return if it supports this query parameter. For illustrative clarity, some annotations that could otherwise be omitted are shown explicitly in the response.

A NETCONF Example to Retrieve Immutable Configuration sysds:system administrator administrator group admin ex-username-1 $5$rounds=10000$mysalt123456789$l4BjA1p/8q.qCYJ.\ 2pLqjR5mCJf2bP7cLpYWmnC7Hq8 ex-username-2 $1$/h1234q$abcdef1234567890abcdef system non-editable power-users Power user group power ex-username-3 $1$/h4567q$abcdef2345678901abcdef system editable ]]>

RESTCONF Example to Retrieve Immutable Configuration illustrates a RESTCONF request example to retrieve "user-groups" configuration in <system> with "with-immutability" query parameter and the response a server might return if it supports this query parameter. The JSON representation of the metadata annotations in the response follows the encoding specified in . For illustrative clarity, some annotations that could otherwise be omitted are shown explicitly in the response.

A RESTCONF Example to Retrieve Immutable Configuration

The Inheritance of Immutability In the example in and , there are two "group" list entries inside "user-groups" container node. The "immutable" metadata attribute for "user-groups" container instance is "false", which is also its default value as the top-level element, and thus can be omitted. The "administrator" list entry is immutable with the immutability of its descendant nodes "description" and "user" list entry of "ex-username-2" being explicitly toggled. Other descendant nodes (e.g., "access-level", "ex-username-1" user list entry, and "tag" leaf-list) inside "administrator" list entry inherit the immutability of the list entry, thus are also immutable. The "immutable" metadata attribute for "power-users" list entry is "false", which is also the same value as its parent node (i.e., the "user-groups" container), and thus can be omitted. Descendant nodes (e.g., "description", "access-level", "user" list, and "tag" leaf-list) inside "power-users" group inherit the immutability of the list entry, thus are also mutable.

Immutability of the list In the example in and , the "group" list as a whole inherits immutability from the container "user-groups", which is mutable. One of the list entry named "administrator" is immutable, and the other entry named "power-user" is mutable. The client is able to copy the entire "user-groups" container in <running>, add new "group" entries, modify the values of descendant nodes of "power-users" list entry, but the values of descendant nodes of "administrator" list entry cannot be overridden with different values except for the "description" and "ex-username-2" user list entry nodes, which is explicitly reset to be mutable. The client may also subsequently delete any copied "group" entries or the entire "user-groups" container, which will not prevent the deleted data being present in <intended> (if implemented) assuming it is still contained in <system>. The "user" list inside the "administrator" group list entry as a whole inherits immutability from the list entry, which is immutable. Thus the client cannot add new user entries inside "administrator" group. As one of the user entry named "ex-username-1" is immutable through inheritance, and the other "ex-username-2" user entry is explicitly set to be mutable. The client cannot modify the "password" parameter, or add a "full-name" value for user "ex-username-1". but is allowed to update (e.g., modify the "password" value, or add a "full-name" value) the list entry for user "ex-username-2". The client may copy or subsequently delete any of the two list entries in <running>, but there is no way to delete the nodes from <intended> (if implemented).

Immutability of the leaf-list In the example in and , the user-ordered "tag" leaf-list node inside the "administrator" group entry as a whole inherits immutability from the list entry, which is immutable. Thus the client cannot add, modify, or reorder entries, the client may copy or subsequently delete any of the two leaf-list entries in <running>, but there is no way to delete the nodes from <intended> if those entries appear in <system>. The leaf-list node instance inside the "power-users" group entry as a whole inherits immutability from the list entry, which is mutable. Thus the client can add or reorder entries, the client may copy or subsequently delete any of the two leaf-list entries in <running>, but there is no way to delete the nodes from <intended> if those entries appear in <system>.

Error Responses to Clients Overriding Immutable Configuration This section provides examples of a client's attempts to override immutable configuration and error responses that the server might return. Separate examples are provided for NETCONF and RESTCONF protocols, in and respectively.

A NETCONF Example to Override Immutable Configuration with Error Response administrator guest application invalid-value error /user-groups/group[name="administrator"]/access-level Invalid access-level value because the target node is marked \ as immutable ]]>

A RESTCONF Example to Override Immutable Configuration with Error Response

Existing Implementations Note to the RFC Editor: Please remove this section prior to publication. There are already a number of full or partial implementations of immutability:

• 3GPP TS 32.156 and 28.623 : Requirements and a partial solution
• ITU-T using ONF 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. Thanks to Per Andersson for the YANGDOCTORS review. Thanks to Mahesh Jethanandani for the AD review.