< draft-ma-netmod-immutable-flag-00.txt   draft-ma-netmod-immutable-flag-01.txt >
NETMOD Q. Ma, Ed. NETMOD Q. Ma
Internet-Draft Q. Wu Internet-Draft Q. Wu
Intended status: Standards Track Huawei Intended status: Standards Track Huawei
Expires: 14 August 2022 H. Li Expires: 16 October 2022 B. Lengyel
Ericsson
H. Li
HPE HPE
10 February 2022 14 April 2022
Immutable Metadata Annotation YANG Extension and Metadata Annotation for Immutable Flag
draft-ma-netmod-immutable-flag-00 draft-ma-netmod-immutable-flag-01
Abstract Abstract
This document defines a metadata annotation [RFC7952] named This document defines a YANG extension named "immutable" to indicate
"immutable" to indicate the immutability of a particular instantiated that specific data nodes are not allowed to be created/deleted/
data node. Any instantiated data node annotated with updated. To indicate that specific instances of a list/leaf-list
immutable="true" by the server is read-only to the clients of YANG- node cannot be changed after initialization, a metadata annotation
driven management protocols, such as NETCONF, RESTCONF and other with the same name is also defined. Any data node or instance marked
management operations (e.g., SNMP and CLI requests). as immutable is read-only to the clients of YANG-driven management
protocols, such as NETCONF, RESTCONF and other management operations
(e.g., SNMP and CLI requests).
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 14 August 2022. This Internet-Draft will expire on 16 October 2022.
Copyright Notice Copyright Notice
Copyright (c) 2022 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License. provided without warranty as described in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. "Immutable" Metadata Annotation Definition . . . . . . . . . 3 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. "Immutable" YANG Extension . . . . . . . . . . . . . . . . . 5
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 4. "Immutable" Metadata Annotation . . . . . . . . . . . . . . . 5
4.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 6 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.2. The "YANG Module Names" Registry . . . . . . . . . . . . 6 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 9
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 9
6.1. Normative References . . . . . . . . . . . . . . . . . . 7 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9
6.2. Informative References . . . . . . . . . . . . . . . . . 8 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 8 8.1. Normative References . . . . . . . . . . . . . . . . . . 10
A.1. Interface Example . . . . . . . . . . . . . . . . . . . . 8 8.2. Informative References . . . . . . . . . . . . . . . . . 11
A.1.1. Creating an "immutable" Interface Type . . . . . . . 10 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 11
A.1.2. Changing an "immutable" Interface Type . . . . . . . 10 A.1. Interface Example . . . . . . . . . . . . . . . . . . . . 11
A.1.3. Deleting an "immutable" Interface Type . . . . . . . 11 A.1.1. Creating an Interface with a "type" Value . . . . . . 12
A.2. Built-in Access Control Example . . . . . . . . . . . . . 12 A.1.2. Updating the Value of an Interface Type . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 A.2. Immutable System Capabilities Modelled as "config
true" . . . . . . . . . . . . . . . . . . . . . . . . . . 14
A.3. Immutable System-defined List Entries . . . . . . . . . . 15
Appendix B. Changes between revisions . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
YANG [RFC7950] is a data modeling language used to model both state YANG [RFC7950] is a data modeling language used to model both state
and configuration data, based on the "config" statement. However, and configuration data, based on the "config" statement. However
there are some configuration data which may not be writable to there exists data that should not be modifiable by the client, but
clients, e.g., the interface name and type values created by the still needs to be declared as "config true" to:
system due to the hardware currently present in the device cannot be
modified by clients, while configurations such as MTU created by the
system are free to be modified by the client.
Allowing some configuration modifiable while others not is * allow configuration of data nodes under immutable lists or
inconsistent and introduces ambiguity to clients. containers;
To address this issue, this document defines a metadata annotation * ensure the existence of specific list entries that are provided
[RFC7952] named "immutable" to indicate the immutability and needed by the system, while additional list entries can be
characteristic of a particular instantiated data node. Any created, modified or deleted;
instantiated data node marked with immutable="true" by the server is
read-only to the clients of YANG-driven management protocols, such as * place "when", "must" and "leafref" constraints between
NETCONF, RESTCONF and other management operations (e.g., SNMP and CLI configuration and immutable schema nodes.
requests).
E.g., the interface name and type values created by the system due to
the hardware currently present in the device cannot be modified by
clients, while configurations such as MTU created by the system are
free to be modified by the client. Further examples and use-cases
are described in Appendix A.
Allowing some configuration to be modifiable while other parts are
not is inconsistent and introduces ambiguity to clients.
To address this issue, this document defines a YANG extension and a
metadata annotation [RFC7952] named "immutable" to indicate the
immutability characteristic of a particular schema node or
instantiated data node. If a schema node is marked as immutable,
data nodes based on the schema MUST NOT be added, removed or updated
by management protocols, such as NETCONF, RESTCONF or other
management operations (e.g., SNMP and CLI requests). If an
instantiated data node is marked as immutable the server MUST reject
changes to it by YANG-driven management protocols, such as NETCONF,
RESTCONF and other management operations (e.g., SNMP and CLI
requests). Marking instance data nodes as immutable (as opposed to
marking schema-nodes) is important when only some instances of a list
or leaf-list shall be marked as read-only.
Theoretically, any "config true" data node is allowed to be created,
updated and deleted. This work makes write access restrictions other
than general YANG and NACM rules visible, which doesn't mean
attaching such restrictions is encouraged.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The following terms are defined in [RFC6241] and [RFC8341] and are The following terms are defined in [RFC6241] and [RFC8341] and are
not redefined here: not redefined here:
* configuration data * configuration data
* access operation * access operation
* write access
The following terms are defined in this document: The following terms are defined in this document:
immutable: A metadata annotation indicating the immutability of a immutable: A property indicating that a schema node is not allowed
data node. An immutable data node is read-only to clients. Note to be created/deleted/updated. When annotating an instance of a
that "immutable" is used to annotate instances of YANG data nodes list/leaf-list, it indicates that the instance cannot be updated
rather than schema nodes. For instance, a "list" data node may once it's created. The immutability of a specific data node or
exist in multiple instances in the data tree, "immutable" can instance is datastore-independent, protocol-independent and user-
annotate some of the instances as read-only, while others are not. independent.
2. "Immutable" Metadata Annotation Definition 2. Overview
The "immutable" flag is used to indicate the immutability of a The "immutable" concept only puts write access restrictions to read-
particular instantiated data node. It applies to the container, write datastores. When a specific data node or instance is marked as
anydata, anyxml, leaf, list and leaf-list entries. The values are "immutable", NACM cannot override this to allow create/delete/update
boolean types indicating whether the data node instance is immutable access.
or not.
When the client retrieves a particular datastore, immutable data node Immutability is a property of the object itself. A particular data
instances MUST be annotated with immutable="true" by the server. If node or instance MUST have the same immutability in all read-write
the "immutable" metadata annotation is not specified, the default is datastores. The immutable property should be visible even in read-
the same as the "immutable" value of the parent node. The default only datastores (e.g., <system>, <intended>, <operational>), however
"immutable" value for a top level data node is false. this only serves as information about the data node itself, but has
no effect on the handling of the read-only datastore. In addition,
the immutability property of a particular data node or instance MUST
NOT change due to different network management protocols and users.
Any data node instance annotated with "immutable=true" is read-only If a particular list/leaf-list node is marked as "immutable" without
to clients, which means that the following access operations for a exceptions for "update" in the schema (e.g., a list data node is
particular instance are not allowed: always immutable and an update is not allowed), the server SHOULD NOT
annotate its instances duplicately.
* Create: add descendant node instances for a container instance Servers MUST reject any attempt to the "create", "delete" and
annotated with "immutable"; "update" access operations on an immutable data node or instance;
marked by YANG extension (except according to the exceptions
argument) or metadata annotation. The error reporting is performed
at various different time according to the selected read-write target
datastore. If the target datastore is "running", the server should
reply with an "invalid-value" at a <edit-config> operation time. If
the target datastore is "candidate", the "invalid-value" error
response to update an immutable data node is delayed until a <commit>
or <validate> operation takes place. For an example of an "invalid-
value" error response, see Appendix A.1.2.
* Delete: delete a data node instance annotated with "immutable" or However the following operations SHOULD be allowed:
its child node instances from a datastore, e.g., delete an
immutable list or leaf-list entry;
* Update: update an existing data node instance annotated with * Use a create, update, delete/remove operation on an immutable
"immutable" or its child node instances in a datastore, e.g., node/instance if the effective change is null. E.g. If a leaf
modify the value of an immutable leaf data node; has a current value of "5" it should be allowed to replace it with
a value of "5".
However the following operations SHOULD be allowed: * Create an immutable data node/instance with a same value initially
set by the system if it doesn't exist in the datastore, e.g.,
explicitly configure a system generated interface name and type in
<running>;
* Create an immutable data node with a same value initially set by 3. "Immutable" YANG Extension
the system if it doesn't exist in the datastore, e.g., explicitly
configure a system generated interface name in <running>;
* Delete the parent node of an immutable data node unless the parent The "immutable" YANG extension can be a substatement to a leaf, leaf-
node is also annotated with "immutable=true", e.g., list, container, list, anydata or anyxml statement. It indicates
/interfaces/interface/type leaf instance is immutable, but the that data nodes based on the parent statement MUST NOT be added,
deletion to the /interfaces/interface list entry is allowed; removed or updated except according to the exceptions argument. The
server MUST reject any such write attempt.
Comment: Should we allow the client delete an "immutable" system The "immutable" YANG extension defines an argument statement named
instantiated node in <running> (see Appendix A.1.3)? "exceptions" which gives a list of operations that users are
permitted to invoke for the specified node.
Comment: Annotations can only be attached to individual list/leaf- The following values are supported for the "exceptions" argument:
list entry, how would the client know if it's to apply to the whole
list/leaf-list, the list/leaf-list entries, or both?
Servers MUST reject any attempt to the "create", "delete" and * Create: allow users to create instances of the data node;
"update" access operations on an immutable data node. The error
reporting is performed at various different time according to the * Update: allow users to modify instances of the data node;
selected target datastore. If the target datastore is "running" or
"startup", the server should reply with an "invalid-value" at a * Delete: allow users to delete instances of the data node.
<edit-config> operation time. If the target datastore is
"candidate", the "invalid-value" error response to update an 4. "Immutable" Metadata Annotation
immutable data node is delayed until a <commit> or <validate>
operation takes place. For an example of an "invalid-value" error The "immutable" flag is used to indicate the immutability of a
response, see Appendix A.1.2. particular instantiated data node. It only applies to the list/leaf-
list entries. The values are boolean types indicating whether the
data node instance is immutable or not.
Any list/leaf-list instance annotated with immutable="true" is read-
only to clients, which means that once an instance is created, the
client cannot change it. If a list entry is annotated with
immutable="true", any contained descendant instances of any type
(including leafs, lists, containers, etc.) inside the specific
instance is not allowed to be created, updated and deleted without
the need to annotate descendant nodes instances explicitly.
Note that "immutable" metadata annotation is used to annotate
instances of a list/leaf-list rather than schema nodes. For
instance, a list node may exist in multiple instances in the data
tree, "immutable" can annotate some of the instances as read-only,
while others are not.
When the client retrieves a particular datastore, immutable data node
instances MUST be annotated with immutable="true" by the server. If
the "immutable" metadata annotation inside a list entry is not
specified, the default "immutable" value for a list/leaf-list entry
is false.
Different from the "immutable" YANG extension, deletion to an
instance marked with immutable="true" metadata annotation SHOULD
always be allowed unless the list/leaf-list data node in the schema
has an im:immutable extension as substatement without a "delete"
exception.
5. YANG Module
3. YANG Module
<CODE BEGINS> <CODE BEGINS>
file="ietf-immutable@2022-01-05.yang" file="ietf-immutable@2022-03-28.yang"
module ietf-immutable { module ietf-immutable {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-immutable"; namespace "urn:ietf:params:xml:ns:yang:ietf-immutable";
prefix im; prefix im;
import ietf-yang-metadata { import ietf-yang-metadata {
prefix md; prefix md;
} }
organization organization
skipping to change at page 5, line 29 skipping to change at page 6, line 50
"WG Web: <https://datatracker.ietf.org/wg/netmod/> "WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org> WG List: <mailto:netmod@ietf.org>
Author: Qiufang Ma Author: Qiufang Ma
<mailto:maqiufang1@huawei.com> <mailto:maqiufang1@huawei.com>
Author: Qin Wu Author: Qin Wu
<mailto:bill.wu@huawei.com> <mailto:bill.wu@huawei.com>
Author: Balazs Lengyel
<mailto:balazs.lengyel@ericsson.com>
Author: Hongwei Li Author: Hongwei Li
<mailto:flycoolman@gmail.com>"; <mailto:flycoolman@gmail.com>";
description description
"This module defines a metadata annotation named 'immutable' "This module defines a metadata annotation named 'immutable'
to indicate the immutability of a particular instantiated to indicate the immutability of a particular instantiated
data node. Any instantiated data node marked with data node. Any instantiated data node marked with
immutable='true' by the server is read-only to the clients immutable='true' by the server is read-only to the clients
of YANG-driven management protocols, such as NETCONF, of YANG-driven management protocols, such as NETCONF,
RESTCONF as well as SNMP and CLI requests. RESTCONF as well as SNMP and CLI requests.
Copyright (c) 2021 IETF Trust and the persons identified The module defines the immutable extension that indicates
that data nodes based ona data-dafinition statement cannot
be added removed or updated except according to the
exceptions argument.
Copyright (c) 2022 IETF Trust and the persons identified
as authors of the code. All rights reserved. as authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with Redistribution and use in source and binary forms, with
or without modification, is permitted pursuant to, and or without modification, is permitted pursuant to, and
subject to the license terms contained in, the Simplified subject to the license terms contained in, the Simplified
BSD License set forth in Section 4.c of the IETF Trust's BSD License set forth in Section 4.c of the IETF Trust's
Legal Provisions Relating to IETF Documents Legal Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info). (https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC HHHH This version of this YANG module is part of RFC HHHH
(https://www.rfc-editor.org/info/rfcHHHH); see the RFC (https://www.rfc-editor.org/info/rfcHHHH); see the RFC
itself for full legal notices. itself for full legal notices.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
are to be interpreted as described in BCP 14 (RFC 2119) are to be interpreted as described in BCP 14 (RFC 2119)
(RFC 8174) when, and only when, they appear in all (RFC 8174) when, and only when, they appear in all
capitals, as shown here."; capitals, as shown here.";
revision 2022-01-05 { revision 2022-03-28 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXX: Immutable Metadata Annotation"; "RFC XXX: Immutable Metadata Annotation";
} }
extension immutable {
argument exceptions;
description
"The 'immutable' extension as a substatement to a data
definition statement indicates that data nodes based on
the parent statement MUST NOT be added, removed or
updated by management protocols, such as NETCONF,
RESTCONF or other management operations (e.g., SNMP
and CLI requests) except when indicated by the
exceptions argument.
Immutable data MAY be marked as config true to allow
'leafref', 'when' or 'must' constraints to be based
on it.
The statement MUST only be a substatement of the leaf,
leaf-list, container, list, anydata, anyxml statements.
Zero or one immutable statement per parent statement
is allowed.
NO substatements are allowed.
The argument is a list of operations that users are
permitted to be used for the specified node, while
other operations are forbidden by the immutable extension.
- create: allows users to create instances of the object
- update : allows users to modify instances of the object
- delete : allows users to delete instances of the object
To dis-allow all user write access, omit the argument;
To allow only create and delete user access, provide
the string 'create delete' for the 'exceptions' parameter.
Providing all 3 parameters has the same affect as not
using this extension at all, but can be used anyway.
Equivalent YANG definition for this extension:
leaf immutable {
type bits {
bit create;
bit update;
bit delete;
}
default '';
}
Adding immutable or removing values from the
exceptions argument of an existing immutable statement
are non-backwards compatible changes.
Other changes to immutable are backwards compatible.";
}
md:annotation immutable { md:annotation immutable {
type boolean; type boolean;
description description
"The 'immutable' annotation indicates the immutability of an "The 'immutable' annotation indicates the immutability of an
instantiated data node. Any data node instance marked as instantiated data node. Any data node instance marked as
'immutable=true' is read-only to clients and cannot be 'immutable=true' is read-only to clients and cannot be
created/deleted/changed through NETCONF, RESTCONF or CLI. updated through NETCONF, RESTCONF or CLI. It applies to the
It applies to the container, anydata, anyxml and leaf list and leaf-list entries. The default is 'immutable=false'
instances, list and leaf-list entries. if not specified for an instance.";
If not specified for a given configuration data node
instance, then the immutability is the same as its parent
node instance in the data tree. The default for any top-level
configuration data node instance is false if not specified.";
} }
} }
<CODE ENDS> <CODE ENDS>
4. IANA Considerations 6. IANA Considerations
4.1. The "IETF XML" Registry 6.1. The "IETF XML" Registry
This document registers one XML namespace URN in the 'IETF XML This document registers one XML namespace URN in the 'IETF XML
registry', following the format defined in [RFC3688]. registry', following the format defined in [RFC3688].
URI: urn:ietf:params:xml:ns:yang:ietf-immutable URI: urn:ietf:params:xml:ns:yang:ietf-immutable
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URIs are XML namespaces. XML: N/A, the requested URIs are XML namespaces.
4.2. The "YANG Module Names" Registry 6.2. The "YANG Module Names" Registry
This document registers one module name in the 'YANG Module Names' This document registers one module name in the 'YANG Module Names'
registry, defined in [RFC6020]. registry, defined in [RFC6020].
name: ietf-immutable name: ietf-immutable
prefix: im prefix: im
namespace: urn:ietf:params:xml:ns:yang:ietf-immutable namespace: urn:ietf:params:xml:ns:yang:ietf-immutable
RFC: XXXX // RFC Ed.: replace XXXX and remove this comment RFC: XXXX // RFC Ed.: replace XXXX and remove this comment
5. Security Considerations 7. Security Considerations
The YANG module specified in this document defines a metadata The YANG module specified in this document defines a metadata
annotation for data nodes that is designed to be accessed network annotation for data nodes that is designed to be accessed network
management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040].
The lowest NETCONF layer is the secure transport layer, and the The lowest NETCONF layer is the secure transport layer, and the
mandatory-to-implement secure transport is Secure Shell (SSH) mandatory-to-implement secure transport is Secure Shell (SSH)
[RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to- [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-
implement secure transport is TLS [RFC8446]. implement secure transport is TLS [RFC8446].
Since immutable information is tied to applied configuration values, Since immutable information is tied to applied configuration values,
it is only accessible to clients that have the permissions to read it is only accessible to clients that have the permissions to read
the applied configuration values. the applied configuration values.
The security considerations for the Defining and Using Metadata with The security considerations for the Defining and Using Metadata with
YANG (see Section 9 of [RFC7952]) apply to the metadata annotation YANG (see Section 9 of [RFC7952]) apply to the metadata annotation
defined in this document. defined in this document.
6. References 8. References
6.1. Normative References 8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004, DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>. <https://www.rfc-editor.org/info/rfc3688>.
skipping to change at page 8, line 30 skipping to change at page 11, line 9
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Model", STD 91, RFC 8341, Access Control Model", STD 91, RFC 8341,
DOI 10.17487/RFC8341, March 2018, DOI 10.17487/RFC8341, March 2018,
<https://www.rfc-editor.org/info/rfc8341>. <https://www.rfc-editor.org/info/rfc8341>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
6.2. Informative References 8.2. Informative References
[I-D.ma-netmod-with-system]
Ma, Q., Watsen, K., Wu, Q., Chong, F., and J. Lindblad,
"System-defined Configuration", Work in Progress,
Internet-Draft, draft-ma-netmod-with-system-03, 10 April
2022, <https://www.ietf.org/archive/id/draft-ma-netmod-
with-system-03.txt>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
Appendix A. Usage Examples Appendix A. Usage Examples
A.1. Interface Example A.1. Interface Example
In this section, the following fragment of a fictional interface This section shows how to use im:immutable YANG extension to mark
module is used: some data node as immutable.
When an interface is physically present, the system will create an
interface entry automatically with valid name and type values in
<system> (see [I-D.ma-netmod-with-system]). The system-generated
data is dependent on and must represent the HW present, and as a
consequence must not be changed by the client. The data is modelled
as "config true" and should be marked as immuable.
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.
The immutability of the data is the same for all interface instances,
thus following fragment of a fictional interface module including an
"immutable" YANG extension can be used:
container interfaces { container interfaces {
list interface { list interface {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf type { leaf type {
im:immutable "create";
type identityref { type identityref {
base ianaift:iana-interface-type; base ianaift:iana-interface-type;
} }
mandatory true;
} }
leaf mtu { leaf mtu {
type uint16; type uint16;
} }
leaf-list ip-address { leaf-list ip-address {
type inet:ip-address; type inet:ip-address;
} }
} }
} }
In this example model, when an interface is physically present, the Note that the "name" leaf is defined as a list key which can never
system will create an interface entry automatically with valid name been modified for a particular list entry, there is no need to mark
and type values. Let's say that there is a system-defined interface "name" as immutable.
"eth0" in <operational>:
<interfaces xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type"
xmlns:im="urn:ietf:params:xml:ns:yang:ietf-immutable"
or:origin="or:system">
<interface>
<name>eth0</name>
<type im:immutable="true">ianaift:ethernetCsmacd</type>
<mtu>1500</mtu>
</interface>
</interfaces>
The "type" leaf instance is annotated with immutable="true" in the
RPC response, which means that it is not allowed to be modified by
client configuration operations. Note that although the "name"
defined as a list key leaf isn't annotated with immutable="true",
modification of the key value for a particular list entry is never
allowed. Deletion to the whole list entry of interface "eth0" should
be allowed in this case, since there is no annotation for the "type"
leaf instance's parent node.
A.1.1. Creating an "immutable" Interface Type A.1.1. Creating an Interface with a "type" Value
The server should accept the configuration to set the leaf "type" to As defined in the YANG model, there is an exception for "create"
the value same as in <operational>: operation. Assume the interface hardware is not present physically
at this point, the client is allowed to create an interface named
"eth0" with a type value in <running>:
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="101"> message-id="101">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
</target> </target>
<config> <config>
<interface xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0" <interface xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type" xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type"
skipping to change at page 10, line 32 skipping to change at page 13, line 27
</interface> </interface>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
A.1.2. Changing an "immutable" Interface Type The interface data does not appear in <operational> since the
physical interface doesn't exist. When the interface is inserted,
the system will detect it and create the associated configuration in
<system>. The system tries to merge the interface configuration in
the <running> datastore with the same name as the inserted interface
configuration in <system>. If no such interface configuration named
"eth0" is found in <system> or the type set by the client doesn't
match the real interface type generated by the system, only the
system-defined interface configuration is applied and present in
<operational>.
If a client tries to change the type of an interface to a value that A.1.2. Updating the Value of an Interface Type
doesn't match the real type of the interface used by the system, the
server must reject the request: Assume the system applied the interface configuration named "eth0"
successfully. If a client tries to change the type of an interface
to a value that doesn't match the real type of the interface used by
the system, the server must reject the request:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
</target> </target>
<config> <config>
<interface xc:operation="merge" <interface xc:operation="merge"
skipping to change at page 11, line 38 skipping to change at page 14, line 38
<error-severity>error</error-severity> <error-severity>error</error-severity>
<error-path xmlns:t="http://example.com/schema/1.2/config"> <error-path xmlns:t="http://example.com/schema/1.2/config">
/interfaces/interface[name="eth0"]/type /interfaces/interface[name="eth0"]/type
</error-path> </error-path>
<error-message xml:lang="en"> <error-message xml:lang="en">
Invalid type for interface eth0 Invalid type for interface eth0
</error-message> </error-message>
</rpc-error> </rpc-error>
</rpc-reply> </rpc-reply>
A.1.3. Deleting an "immutable" Interface Type A.2. Immutable System Capabilities Modelled as "config true"
Should the server accept the configuration of deleting the type of System capabilities might be represented as system-set data nodes in
interface named "eth0" from the running configuration? the model. Configurable data nodes might need constraints specified
<rpc message-id="102" as "when", "must" or "path" statements to ensure that configuration
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" is set according to the system's capabilities. E.g.,
xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<interface>
<name>eth0</name>
<type xc:operation="delete">ianaift:ethernetCsmacd</type>
</interface>
</config>
</edit-config>
</rpc>
Even the type of interface named "eth0" is deleted from the running * A timer can support the values 1,5,8 seconds. This is defined in
configuration, the client which performs a <get-data> towards the leaf-list 'supported-timer-values'.
<operational> will still get:
<interfaces xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin" * When the configurable 'interface-timer' leaf is set, it should be
xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type" ensured that one of the supported values is used. The natural
xmlns:im="urn:ietf:params:xml:ns:yang:ietf-immutable" solution would be to make the 'interface-timer' a leaf-ref
or:origin="or:intended"> pointing at the 'supported-timer-values'.
<interface>
<name>eth0</name>
<type im:immutable="true" or:origin="or:intended">
ianaift:ethernetCsmacd
</type>
<mtu>1500</mtu>
</interface>
</interfaces>
A.2. Built-in Access Control Example However, this is not possible as 'supported-timer-values' must be
readOnly 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 schema nodes.
In this example, the "ietf-netconf-acm" YANG module defined in The solution is that the supported-timer-values data node in the YANG
[RFC8341] is used. Suppose when the device is powered on, the system Model shall be defined as "config true" and shall also be marked with
may provide some built-in access control groups, for each access the "immutable" extension. After this the 'interface-timer' shall be
control group there exists at least one built-in user, which might be defined as a leaf-ref pointing at the 'supported-timer-values'.
read-only and cannot be modified by the client. In addition, the
system also can predefine some access control rules for a specific
group. Some rules can be modified, while others are not (e.g.,
access control rule for a root account should be immutable). In
addition, clients can also define their own groups and access control
rules freely.
The built-in access control groups and rules are provided by the A.3. Immutable System-defined List Entries
system, they are present in <operational>. The example below
illustrates what the built-in groups and rules might look like for a
server after it boots:
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" There are some system-defined entries for a "config true" list which
xmlns:im="urn:ietf:params:xml:ns:yang:ietf-immutable"> are present in <system> (see [I-D.ma-netmod-with-system]) and cannot
<groups> be updated by the client, such system-defined instances should be
<group> defined immutable. The client is free to define, update and delete
<name>admin</name> their own list entries in <running>. Thus the list data node in the
<user-name im:immutable="true">admin</user-name> YANG model cannot be marked as "immutable" extension as a whole. But
</group> some of the system-defined list entries need to be protected if they
<group> are copied from the <system> datastore to <running>.
<name>monitor</name>
<user-name im:immutable="true">user</user-name>
</group>
<group>
<name>visit</name>
<user-name im:immutable="true">guest</user-name>
</group>
</groups>
<rule-list im:immutable="true">
<name>admin-acl</name>
<group>admin</group>
<rule>
<name>permit-all</name>
<module-name>*</module-name>
<access-operations>*</access-operations>
<action>permit</action>
</rule>
</rule-list>
<rule-list>
<name>monitor-acl</name>
<group>visit</group>
<rule>
<name>permit-monitor</name>
<module-name>ietf-netconf-monitoring</module-name>
<access-operations>read</access-operations>
<action>permit</action>
</rule>
</rule-list>
<rule-list>
<name>visit-acl</name>
<group>visit</group>
<rule>
<name>deny-ncm</name>
<module-name>ietf-netconf-monitoring</module-name>
<access-operations>*</access-operations>
<action>deny</action>
</rule>
</rule-list>
</nacm>
As indicated in the above XML snippet, the system predefines three An immutable metadata annotation can be useful in this case. When
access control groups and for each group there is one built-in the client retrieves those system-defined entries towards <system>
immutable user, which means that the client can define new users for (or <running> if they are copied into <running>), an immutable="true"
a particular access control group, but deletion of a built-in user- annotation is returned; so that the client can understand that the
name is not allowed. The system also provides three access control predefined list entries shall not be updated but they can configure
list entries, one for each predefined group. Only the access control their list entries without any restriction.
rule for the "admin" group is read-only to clients.
Appendix B. Changes between revisions
Note to RFC Editor (To be removed by RFC Editor)
v00 - v01
* Added immutable extension
* Added new use-cases for immutable extension and annotation
* Added requirement that an update that means no effective change
should always be allowed
* Added clarification that immutable is only applied to read-write
datastore
* Narrowed the applied scope of metadata annotation to list/leaf-
list instances
Authors' Addresses Authors' Addresses
Qiufang Ma (editor) Qiufang Ma
Huawei Huawei
101 Software Avenue, Yuhua District 101 Software Avenue, Yuhua District
Nanjing Nanjing
Jiangsu, 210012 Jiangsu, 210012
China China
Email: maqiufang1@huawei.com Email: maqiufang1@huawei.com
Qin Wu Qin Wu
Huawei Huawei
101 Software Avenue, Yuhua District 101 Software Avenue, Yuhua District
Nanjing Nanjing
Jiangsu, 210012 Jiangsu, 210012
China China
Email: bill.wu@huawei.com Email: bill.wu@huawei.com
Balazs Lengyel
Ericsson
Email: balazs.lengyel@ericsson.com
Hongwei Li Hongwei Li
HPE HPE
Email: flycoolman@gmail.com Email: flycoolman@gmail.com
 End of changes. 61 change blocks. 
251 lines changed or deleted 359 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/