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