| < draft-ma-netmod-with-system-02.txt | draft-ma-netmod-with-system-03.txt > | |||
|---|---|---|---|---|
| NETMOD Q. Ma, Ed. | NETMOD Q. Ma, Ed. | |||
| Internet-Draft Huawei | Internet-Draft Huawei | |||
| Updates: RFC8342, RFC6241, RFC8526, RFC8040 (if K. Watsen | Updates: RFC8342, RFC6241, RFC8526, RFC8040 (if K. Watsen | |||
| approved) Watsen Networks | approved) Watsen Networks | |||
| Intended status: Standards Track Q. Wu | Intended status: Standards Track Q. Wu | |||
| Expires: 18 August 2022 C. Feng | Expires: 12 October 2022 C. Feng | |||
| Huawei | Huawei | |||
| J. Lindblad | J. Lindblad | |||
| Cisco Systems | Cisco Systems | |||
| 14 February 2022 | 10 April 2022 | |||
| System-defined Configuration | System-defined Configuration | |||
| draft-ma-netmod-with-system-02 | draft-ma-netmod-with-system-03 | |||
| Abstract | Abstract | |||
| This document updates NMDA [RFC8342] to define a read-only | This document updates NMDA [RFC8342] to define a read-only | |||
| conventional configuration datastore called "system" to hold system- | conventional configuration datastore called "system" to hold system- | |||
| defined configurations. To avoid clients' explicit copy/paste of | defined configurations. To avoid clients' explicit copy/paste of | |||
| referenced system-defined configuration, a "resolve-system" parameter | referenced system-defined configuration into the target configuration | |||
| has been defined to allow the server acting as a "system client" to | datastore (e.g., <running>), a "resolve-system" parameter has been | |||
| populate referenced system-defined nodes automatically. The solution | defined to allow the server acting as a "system client" to copy | |||
| enables clients to reference nodes defined in <system>, overwrite | referenced system-defined nodes automatically. The solution enables | |||
| values of configurations defined in <system>, and configure | clients manipulating the target configuration datastore (e.g., | |||
| <running>) to overlay and reference nodes defined in <system>, | ||||
| override values of configurations defined in <system>, and configure | ||||
| descendant nodes of system-defined nodes. | descendant nodes of system-defined nodes. | |||
| 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 18 August 2022. | This Internet-Draft will expire on 12 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
| 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 | 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 4 | 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 5 | |||
| 1.3. Updates to RFC 8342 . . . . . . . . . . . . . . . . . . . 5 | 1.3. Updates to RFC 8342 . . . . . . . . . . . . . . . . . . . 5 | |||
| 1.4. Updates to RFC 6241, RFC 8526 . . . . . . . . . . . . . . 5 | 1.4. Updates to RFC 6241, RFC 8526 . . . . . . . . . . . . . . 5 | |||
| 1.5. Updates to RFC 8040 . . . . . . . . . . . . . . . . . . . 5 | 1.5. Updates to RFC 8040 . . . . . . . . . . . . . . . . . . . 6 | |||
| 2. Kinds of System Configuration . . . . . . . . . . . . . . . . 6 | 1.5.1. Query Parameter . . . . . . . . . . . . . . . . . . . 6 | |||
| 2.1. Immediately-Active . . . . . . . . . . . . . . . . . . . 6 | 1.5.2. Query Parameter URI . . . . . . . . . . . . . . . . . 6 | |||
| 2.2. Conditionally-Active . . . . . . . . . . . . . . . . . . 6 | 2. Kinds of System Configuration . . . . . . . . . . . . . . . . 7 | |||
| 2.3. Inactive-Until-Referenced . . . . . . . . . . . . . . . . 6 | 2.1. Immediately-Active . . . . . . . . . . . . . . . . . . . 7 | |||
| 2.2. Conditionally-Active . . . . . . . . . . . . . . . . . . 7 | ||||
| 2.3. Inactive-Until-Referenced . . . . . . . . . . . . . . . . 7 | ||||
| 3. Static Characteristics . . . . . . . . . . . . . . . . . . . 7 | 3. Static Characteristics . . . . . . . . . . . . . . . . . . . 7 | |||
| 3.1. Read-only to Clients . . . . . . . . . . . . . . . . . . 7 | 3.1. Read-only to Clients . . . . . . . . . . . . . . . . . . 7 | |||
| 3.2. May Change via Software Upgrades . . . . . . . . . . . . 7 | 3.2. May Change via Software Upgrades . . . . . . . . . . . . 8 | |||
| 3.3. No Impact to <operational> . . . . . . . . . . . . . . . 7 | 3.3. No Impact to <operational> . . . . . . . . . . . . . . . 8 | |||
| 4. Dynamic Behavior . . . . . . . . . . . . . . . . . . . . . . 7 | 4. Dynamic Behavior . . . . . . . . . . . . . . . . . . . . . . 8 | |||
| 4.1. Conceptual Model . . . . . . . . . . . . . . . . . . . . 7 | 4.1. Conceptual Model . . . . . . . . . . . . . . . . . . . . 8 | |||
| 4.2. Servers Auto-populating Referenced System | 4.2. Explicit Declaration of System Configuration . . . . . . 9 | |||
| Configuration . . . . . . . . . . . . . . . . . . . . . . 8 | 4.3. Servers Auto-configuring Referenced System | |||
| 4.3. Explicit Declaration of System Configuration . . . . . . 9 | Configuration . . . . . . . . . . . . . . . . . . . . . . 10 | |||
| 4.4. Modifying (overriding) System Configuration . . . . . . . 9 | 4.4. Modifying (overriding) System Configuration . . . . . . . 10 | |||
| 4.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 10 | 4.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 4.5.1. Server Populating of <running> Automatically . . . . 10 | 4.5.1. Server Configuring of <running> Automatically . . . . 11 | |||
| 4.5.2. Declaring a System-defined Node in <running> | 4.5.2. Declaring a System-defined Node in <running> | |||
| Explicitly . . . . . . . . . . . . . . . . . . . . . 16 | Explicitly . . . . . . . . . . . . . . . . . . . . . 17 | |||
| 4.5.3. Modifying a System-instantiated Leaf's Value . . . . 19 | 4.5.3. Modifying a System-instantiated Leaf's Value . . . . 20 | |||
| 4.5.4. Configuring Descendant Nodes of a System-defined | 4.5.4. Configuring Descendant Nodes of a System-defined | |||
| Node . . . . . . . . . . . . . . . . . . . . . . . . 21 | Node . . . . . . . . . . . . . . . . . . . . . . . . 22 | |||
| 5. The <system> Configuration Datastore . . . . . . . . . . . . 22 | 5. The <system> Configuration Datastore . . . . . . . . . . . . 23 | |||
| 6. The "ietf-system-datastore" Module . . . . . . . . . . . . . 23 | 6. The "ietf-system-datastore" Module . . . . . . . . . . . . . 25 | |||
| 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 24 | 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 25 | |||
| 6.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 24 | 6.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 25 | |||
| 6.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 25 | 6.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 26 | |||
| 7. The "ietf-netconf-resolve-system" Module . . . . . . . . . . 27 | 7. The "ietf-netconf-resolve-system" Module . . . . . . . . . . 28 | |||
| 7.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 27 | 7.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 28 | |||
| 7.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 28 | 7.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 29 | |||
| 7.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 31 | 7.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 32 | |||
| 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 | 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 | |||
| 8.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 33 | 8.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 35 | |||
| 8.2. The "YANG Module Names" Registry . . . . . . . . . . . . 33 | 8.2. The "YANG Module Names" Registry . . . . . . . . . . . . 35 | |||
| 9. Security Considerations . . . . . . . . . . . . . . . . . . . 34 | 8.3. RESTCONF Capability URN Registry . . . . . . . . . . . . 35 | |||
| 9.1. Regarding the "ietf-system-datastore" YANG Module . . . . 34 | 9. Security Considerations . . . . . . . . . . . . . . . . . . . 35 | |||
| 9.1. Regarding the "ietf-system-datastore" YANG Module . . . . 35 | ||||
| 9.2. Regarding the "ietf-netconf-resolve-system" YANG | 9.2. Regarding the "ietf-netconf-resolve-system" YANG | |||
| Module . . . . . . . . . . . . . . . . . . . . . . . . . 34 | Module . . . . . . . . . . . . . . . . . . . . . . . . . 36 | |||
| 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 34 | 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 36 | |||
| Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 35 | Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 36 | |||
| References . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 | References . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 | |||
| Normative References . . . . . . . . . . . . . . . . . . . . . 35 | Normative References . . . . . . . . . . . . . . . . . . . . . 36 | |||
| Informative References . . . . . . . . . . . . . . . . . . . . 35 | Informative References . . . . . . . . . . . . . . . . . . . . 37 | |||
| Appendix A. Key Use Cases . . . . . . . . . . . . . . . . . . . 36 | Appendix A. Key Use Cases . . . . . . . . . . . . . . . . . . . 38 | |||
| A.1. Device Powers On . . . . . . . . . . . . . . . . . . . . 36 | A.1. Device Powers On . . . . . . . . . . . . . . . . . . . . 38 | |||
| A.2. Client Commits Configuration . . . . . . . . . . . . . . 37 | A.2. Client Commits Configuration . . . . . . . . . . . . . . 39 | |||
| A.3. Operator Installs Card into a Chassis . . . . . . . . . . 38 | A.3. Operator Installs Card into a Chassis . . . . . . . . . . 40 | |||
| Appendix B. Changes between Revisions . . . . . . . . . . . . . 39 | Appendix B. Changes between Revisions . . . . . . . . . . . . . 41 | |||
| Appendix C. Open Issues tracking . . . . . . . . . . . . . . . . 40 | Appendix C. Open Issues tracking . . . . . . . . . . . . . . . . 42 | |||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 | |||
| 1. Introduction | 1. Introduction | |||
| NMDA [RFC8342] defines system configuration as the configuration that | NMDA [RFC8342] defines system configuration as the configuration that | |||
| is supplied by the device itself and should be present in | is supplied by the device itself and should be present in | |||
| <operational> when it is in use. | <operational> when it is in use. | |||
| However, there is a desire to enable a server to better document the | However, there is a desire to enable a server to better document the | |||
| system configuration. Clients can benefit from a standard mechanism | system configuration. Clients can benefit from a standard mechanism | |||
| to see what system configuration is available in a server. | to see what system configuration is available in a server. | |||
| In some cases, the client references a system configuration which | In some cases, the client references a system configuration which | |||
| isn't returned when the datastore is read. Having to copy the entire | isn't present in the target datastore (e.g., <running>). Having to | |||
| contents of the system configuration into <running> should be avoided | copy the entire contents of the system configuration into the target | |||
| or reduced when possible while ensuring that all referential | datastore should be avoided or reduced when possible while ensuring | |||
| integrity constraints are satisfied. | that all referential integrity constraints are satisfied. | |||
| In some other cases, configuration of descendant nodes of system | In some other cases, configuration of descendant nodes of system- | |||
| defined configuration needs to be supported. For example, the system | defined configuration needs to be supported. For example, the system | |||
| configuration may contain an almost empty physical interface, while | configuration may contain an almost empty physical interface, while | |||
| the client needs to be able to add, modify, remove a number of | the client needs to be able to add, modify, remove a number of | |||
| descendant nodes. Some descendant nodes may not be modifiable (e.g., | descendant nodes. Some descendant nodes may not be modifiable (e.g., | |||
| "name" and "type" set by the system). | "name" and "type" set by the system). | |||
| This document updates NMDA [RFC8342] to define a read-only | This document updates NMDA [RFC8342] to define a read-only | |||
| conventional configuration datastore called "system" to hold system- | conventional configuration datastore called "system" to hold system- | |||
| defined configurations. To avoid clients' explicit copy/paste of | defined configurations. To avoid clients' explicit copy/paste of | |||
| referenced system-defined configuration, a "resolve-system" parameter | referenced system-defined configuration into the target configuration | |||
| has been defined to allow the server acting as a "system client" to | datastore (e.g., <running>), a "resolve-system" parameter has been | |||
| populate referenced system-defined nodes automatically. The solution | defined to allow the server acting as a "system client" to copy | |||
| enables clients to reference nodes defined in <system>, overwrite | referenced system-defined nodes automatically. The solution enables | |||
| values of configurations defined in <system>, and configure | clients manipulating the target configuration datastore (e.g., | |||
| <running>) to overlay and reference nodes defined in <system>, | ||||
| override values of configurations defined in <system>, and configure | ||||
| descendant nodes of system-defined nodes. | descendant nodes of system-defined nodes. | |||
| Conformance to this document requires servers to implement the "ietf- | Conformance to this document requires servers to implement the "ietf- | |||
| system-datastore" YANG Module. | system-datastore" YANG Module. | |||
| 1.1. Terminology | 1.1. Terminology | |||
| This document assumes that the reader is familiar with the contents | This document assumes that the reader is familiar with the contents | |||
| of [RFC6241], [RFC7950], [RFC8342], [RFC8407], and [RFC8525] and uses | of [RFC6241], [RFC7950], [RFC8342], [RFC8407], and [RFC8525] and uses | |||
| terminologies from those documents. | terminologies from those documents. | |||
| The following terms are defined in this document as follows: | The following terms are defined in this document as follows: | |||
| System configuration: Configuration that is provided by the system | System configuration: Configuration that is provided by the system | |||
| itself [RFC8342]. | itself. System configuration is present in <system> once it's | |||
| created (regardless of being applied by the device), and appears | ||||
| in <intended> which is subject to validation. Applied system | ||||
| configuration also appears in <operational> with origin="system". | ||||
| System configuration datastore: A configuration datastore holding | System configuration datastore: A configuration datastore holding | |||
| the complete configuration provided by the system itself. This | the complete configuration provided by the system itself. This | |||
| datastore is referred to as "<system>". | datastore is referred to as "<system>". | |||
| This document redefines the term "conventional configuration | This document redefines the term "conventional configuration | |||
| datastore" from RFC 8342 to add "system" to the list conventional | datastore" from RFC 8342 to add "system" to the list of conventional | |||
| configuration datastores: | configuration datastores: | |||
| Conventional configuration datastore: One of the following set of | Conventional configuration datastore: One of the following set of | |||
| configuration datastores: <running>, <startup>, <candidate>, | configuration datastores: <running>, <startup>, <candidate>, | |||
| <system>, and <intended>. These datastores share a common | <system>, and <intended>. These datastores share a common | |||
| datastore schema, and protocol operations allow copying data | datastore schema, and protocol operations allow copying data | |||
| between these datastores. The term "conventional" is chosen as a | between these datastores. The term "conventional" is chosen as a | |||
| generic umbrella term for these datastores. | generic umbrella term for these datastores. | |||
| 1.2. Requirements Language | 1.2. Requirements Language | |||
| skipping to change at page 5, line 10 ¶ | skipping to change at page 5, line 23 ¶ | |||
| "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. | |||
| 1.3. Updates to RFC 8342 | 1.3. Updates to RFC 8342 | |||
| This document updates RFC 8342 to define a configuration datastore | This document updates RFC 8342 to define a configuration datastore | |||
| called "system" to hold system configuration, it also redefines the | called "system" to hold system configuration, it also redefines the | |||
| term "conventional configuration datastore" from RFC 8342 to add | term "conventional configuration datastore" from RFC 8342 to add | |||
| "system" to the list conventional configuration datastores. The | "system" to the list of conventional configuration datastores. The | |||
| contents of <system> datastore are read-only to clients but may | contents of <system> datastore are read-only to clients but may | |||
| change dynamically. The <system> aware client may retrieve all three | change dynamically. The <system> aware client may retrieve all three | |||
| types of system configuration defined in Section 2, reference nodes | types of system configuration defined in Section 2, reference nodes | |||
| defined in <system>, overwrite values of configurations defined in | defined in <system>, override values of configurations defined in | |||
| <system>, and configure descendant nodes of system-defined nodes. | <system>, and configure descendant nodes of system-defined nodes. | |||
| The server will merge <running> and <system> to create <intended>. | The server will merge <running> and <system> to create <intended>. | |||
| As always, system configuration will appear in <operational> with | As always, system configuration will appear in <operational> with | |||
| origin="system". | origin="system" when it is in use. | |||
| The <system> datastore makes system configuration visible to clients | The <system> datastore makes system configuration visible to clients | |||
| in order for being referenced or configurable prior to present in | in order for being referenced or configurable prior to present in | |||
| <operational>. | <operational>. | |||
| 1.4. Updates to RFC 6241, RFC 8526 | 1.4. Updates to RFC 6241, RFC 8526 | |||
| This document augments <edit-config> and <edit-data> RPC operations | This document augments <edit-config> and <edit-data> RPC operations | |||
| defined in [RFC6241] and [RFC8526] respectively, with a new | defined in [RFC6241] and [RFC8526] respectively, with a new | |||
| additional input parameter "resolve-system". | additional input parameter "resolve-system". The <copy-config> RPC | |||
| operation defined in [RFC6241] is also augmented to support "resolve- | ||||
| system" parameter. | ||||
| The "resolve-system" parameter is optional and has no value. When it | The "resolve-system" parameter is optional and has no value. When it | |||
| is provided and the server detects that there is a reference to a | is provided and the server detects that there is a reference to a | |||
| system-defined node during the validation, the server will | system-defined node during the validation, the server will | |||
| automatically populate the referenced system configuration into the | automatically copy the referenced system configuration into the | |||
| validated datastore to make the configuration valid without the | validated datastore to make the configuration valid without the | |||
| client doing so explicitly. Legacy Clients interacting with servers | client doing so explicitly. Legacy Clients interacting with servers | |||
| that support this parameter don't see any changes in <edit-config> | that support this parameter don't see any changes in <edit- | |||
| and <edit-data> behaviors. | config>/<edit-data> and <copy-config> behaviors. | |||
| According to the NETCONF constraint enforcement model defined in the | According to the NETCONF constraint enforcement model defined in the | |||
| section 8.3 of [RFC7950], if the target datastore of the <edit- | section 8.3 of [RFC7950], if the target datastore of the <edit- | |||
| config> or <edit-data> is "running" or "startup", the server- | config>/<edit-data> or <copy-config> is "running" or "startup", the | |||
| populating of the target datastore MUST be enforced at the end of the | server's copy referenced nodes from <system> to the target datastore | |||
| <edit-config> or <edit-data> operations during the validation. If | MUST be enforced at the end of the <edit-config>/<edit-data> or | |||
| the target datastore of the <edit-config> or <edit-data> is | <copy-config> operations during the validation. If the target | |||
| "candidate", the server-populating of the target datastore is delayed | datastore of the <edit-config>/<edit-data> or <copy-config> is | |||
| until a <commit> or <validate> operation takes place. | "candidate", the server's copy referenced nodes from <system> to the | |||
| target datastore is delayed until a <commit> or <validate> operation | ||||
| takes place. | ||||
| 1.5. Updates to RFC 8040 | 1.5. Updates to RFC 8040 | |||
| This document extends Section 4.8 of [RFC8040] to add a new query | This document extends Section 4.8 and Section 9.1.1 of [RFC8040] to | |||
| parameter "resolve-system". | add a new query parameter "resolve-system" and corresponding query | |||
| parameter capability URI. | ||||
| 1.5.1. Query Parameter | ||||
| The "resolve-system" parameter controls whether to allow a server | The "resolve-system" parameter controls whether to allow a server | |||
| populate any referenced system-defined configuration automatically | copy any referenced system-defined configuration automatically | |||
| without the client doing so explicitly. This parameter is only | without the client doing so explicitly. This parameter is only | |||
| allowed with no values carried. If this parameter has any unexpected | allowed with no values carried. If this parameter has any unexpected | |||
| value, then a "400 Bad Request" status-line is returned. | value, then a "400 Bad Request" status-line is returned. | |||
| +----------------+---------+-----------------------------------------+ | +----------------+---------+-----------------------------------------+ | |||
| | Name | Methods | Description | | | Name | Methods | Description | | |||
| +----------------+---------+-----------------------------------------+ | +----------------+---------+-----------------------------------------+ | |||
| |resolve-system | POST, | resolve any references not resolved by | | |resolve-system | POST, | resolve any references not resolved by | | |||
| | | PUT | the client and populate referenced | | | | PUT | the client and copy referenced | | |||
| | | | system configuration into <running> | | | | | system configuration into <running> | | |||
| | | | automatically. This parameter can be | | | | | automatically. This parameter can be | | |||
| | | | given in any order. | | | | | given in any order. | | |||
| +----------------+---------+-----------------------------------------+ | +----------------+---------+-----------------------------------------+ | |||
| 1.5.2. Query Parameter URI | ||||
| To enable the RESTCONF client to discover if the "resolve-system" | ||||
| query parameter is supported by the server, the following capability | ||||
| URI is defined, which is advertised by the server if supported, using | ||||
| the "ietf-restconf-monitoring" module defined in RFC 8040: | ||||
| urn:ietf:params:restconf:capability:resolve-system:1.0 | ||||
| 2. Kinds of System Configuration | 2. Kinds of System Configuration | |||
| There are three types of system configurations: immediately-active | There are three types of system configurations: immediately-active | |||
| system configuration, conditionally-active system configuration and | system configuration, conditionally-active system configuration and | |||
| inactive-until-referenced system configuration. | inactive-until-referenced system configuration. | |||
| 2.1. Immediately-Active | 2.1. Immediately-Active | |||
| Immediately-active system configurations are those applied and active | Immediately-active system configurations are those generated in | |||
| immediately (e.g., a loop-back interface) , irrespective of physical | <system> and applied immediately when the device is powered on (e.g., | |||
| resource present or not, a special functionality enabled or not. | a loop-back interface) , irrespective of physical resource present or | |||
| not, a special functionality enabled or not. | ||||
| 2.2. Conditionally-Active | 2.2. Conditionally-Active | |||
| System configurations which are provided and activated based on | System configurations which are generated in <system> and applied | |||
| specific conditions being met in a system, e.g., if a physical | based on specific conditions being met in a system, e.g., if a | |||
| resource is present (e.g., insert interface card), the system will | physical resource is present (e.g., insert interface card), the | |||
| automatically detect it and load pre-provisioned configuration; when | system will automatically detect it and load pre-provisioned | |||
| the physical resource is not present( remove interface card), the | configuration; when the physical resource is not present( remove | |||
| system configuration will be automatically cleared. Another example | interface card), the system configuration will be automatically | |||
| is when a special functionality is enabled, e.g., when QoS function | cleared. Another example is when a special functionality is enabled, | |||
| is enabled, QoS policies are automatically created by the system. | e.g., when QoS function is enabled, QoS policies are automatically | |||
| created by the system. | ||||
| 2.3. Inactive-Until-Referenced | 2.3. Inactive-Until-Referenced | |||
| There are some predefined objects(e.g., application ids, anti-x | There are some predefined objects(e.g., application ids, anti-x | |||
| signatures, trust anchor certs, etc.) as a convenience for the | signatures, trust anchor certs, etc.) as a convenience for the | |||
| clients. The clients can also define their own data objects for | clients. The clients can also define their own data objects for | |||
| their unique requirements. Inactive-until-referenced system | their unique requirements. Inactive-until-referenced system | |||
| configurations are not applied and active immediately but only after | configurations are generated in <system> immediately when it is | |||
| they are referenced by client-defined configuration. | powered on, but they are not applied and active until being | |||
| referenced. | ||||
| 3. Static Characteristics | 3. Static Characteristics | |||
| 3.1. Read-only to Clients | 3.1. Read-only to Clients | |||
| From the client's perspective, the contents of the <system> datastore | The <system> configuration datastore is a read-only configuration | |||
| are read-only. There is no way to delete system configuration from a | datastore (i.e., edits towards <system> directly MUST be denied), | |||
| server. Any deletable system-provided configuration must be defined | though the client may be allowed to override the value of a system- | |||
| in <factory-default> [RFC8808], which is used to initialize <running> | initialized data node (see Section 4.4). Configuration defined in | |||
| when the device is first-time powered on or reset to its factory | <system> is merged into <intended>, and present in <operational> if | |||
| default condition. | it is actively in use by the device. Thus unless the resource is no | |||
| longer available (e.g., the interface removed physically), there is | ||||
| no way to actually delete system configuration from a server, even if | ||||
| a client may be allowed to delete the configuration copied from | ||||
| <system> into <running>. Any deletable system-provided configuration | ||||
| must be defined in <factory-default> [RFC8808], which is used to | ||||
| initialize <running> when the device is first-time powered on or | ||||
| reset to its factory default condition. | ||||
| 3.2. May Change via Software Upgrades | 3.2. May Change via Software Upgrades | |||
| System configuration MAY change dynamically, e.g., depending on | System configuration MAY change dynamically, e.g., depending on | |||
| factors like device upgrade or if system-controlled resources(e.g., | factors like device upgrade or if system-controlled resources(e.g., | |||
| HW available) change. In some implementations, when QoS function is | HW available) change. In some implementations, when QoS function is | |||
| enabled, QoS-related predefined policies are created by system. If | enabled, QoS-related policies are created by system. If the system | |||
| the system configuration gets changed, YANG notification (e.g., | configuration gets changed, YANG notification (e.g., "push-change- | |||
| "push-change-update" notification) [RFC8641][RFC8639][RFC6470] can be | update" notification) [RFC8641][RFC8639][RFC6470] can be used to | |||
| used to notify the client. | notify the client. Any update of the contents in <system> will not | |||
| cause the automatic update of <running>, even if some of the system | ||||
| configuration has already been copied into <running> explicitly or | ||||
| automatically before the update. | ||||
| 3.3. No Impact to <operational> | 3.3. No Impact to <operational> | |||
| This work intends to have no impact to <operational>. As always, | This work intends to have no impact to <operational>. As always, | |||
| system configuration will appear in <operational> with | system configuration will appear in <operational> with | |||
| "origin=system". This work enables a subset of those system | "origin=system". This work enables a subset of those system | |||
| generated nodes to be defined like configuration, i.e., made visible | generated nodes to be defined like configuration, i.e., made visible | |||
| to clients in order for being referenced or configurable prior to | to clients in order for being referenced or configurable prior to | |||
| present in <operational>. The referenced system configuration in | present in <operational>. "Config false" nodes are out of scope, | |||
| <running> automatically copied from <system> by the server MUST have | hence existing "config false" nodes are not impacted by this work. | |||
| its origin set to "system" when present in <operational>. "Config | ||||
| false" nodes are completely out of scope, hence existing "config | ||||
| false" nodes are not impacted by this work. | ||||
| 4. Dynamic Behavior | 4. Dynamic Behavior | |||
| 4.1. Conceptual Model | 4.1. Conceptual Model | |||
| This document introduces a mandatory datastore named "system" which | This document introduces a mandatory datastore named "system" which | |||
| is used to hold all three types of system configurations defined in | is used to hold all three types of system configurations defined in | |||
| Section 2. | Section 2. | |||
| When the device is powered on, immediately-active system | When the device is powered on, immediately-active system | |||
| configuration will be provided and activated immediately but | configuration will be generated in <system> and applied immediately | |||
| inactive-until-referenced system configuration only becomes active if | but inactive-until-referenced system configuration only becomes | |||
| it is referenced by client-defined configuration. While | active if it is referenced by client-defined configuration. While | |||
| conditionally-active system configuration will be created and | conditionally-active system configuration will be created and | |||
| immediately activated if the condition on system resources is met | immediately applied if the condition on system resources is met when | |||
| when the device is powered on or running. | the device is powered on or running. | |||
| All above three types of system configurations will go into <system>. | All above three types of system configurations will appear in | |||
| The client may reference nodes defined in <system>, overwrite values | <system>. Clients MAY reference nodes defined in <system>, override | |||
| of configurations defined in <system>, and configure descendant nodes | values of configurations defined in <system>, and configure | |||
| of system-defined nodes in <running>. Then the server will merge | descendant nodes of system-defined nodes, by copying or writing | |||
| <running> and <system> to create <intended>, in which process, | intended configurations into the target configuration datastore | |||
| <running> MAY overwrite and/or extend <system>. If a server | (e.g., <running>). | |||
| implements <intended>, <system> MUST be merged into <intended>. | ||||
| The server will merge <running> and <system> to create <intended>, in | ||||
| which process, the data node appears in <running> takes precedence | ||||
| over the same node in <system> if the server allows the node to be | ||||
| modifiable; additional nodes to a list entry or new list/leaf-list | ||||
| entries appear in <running> extends the list entry or the whole list/ | ||||
| leaf-list defined in <system> if the server allows the list/leaf-list | ||||
| to be updated. In addition, the <intended> configuration datastore | ||||
| represents the configuration after all configuration transformation | ||||
| to <system> are performed (e.g., system-defined template expansion, | ||||
| removal of inactive system configuration). If a server implements | ||||
| <intended>, <system> MUST be merged into <intended>. | ||||
| Servers MUST enforce that configuration references in <running> are | Servers MUST enforce that configuration references in <running> are | |||
| resolved within the <running> datastore and ensure that <running> | resolved within the <running> datastore and ensure that <running> | |||
| contains any referenced system objects. Clients MUST either | contains any referenced system objects. Clients MUST either | |||
| explicitly configure system-defined nodes in <running> or use the | explicitly copy system-defined nodes into <running> or use the | |||
| "resolve-system" parameter. The server MUST enforce that the | "resolve-system" parameter. The server MUST enforce that the | |||
| referenced system nodes injected into <running> by the client is | referenced system nodes configured into <running> by the client is | |||
| consistent with <system>. Note that only <system> aware clients copy | consistent with <system>. Note that <system> aware clients know how | |||
| referenced system nodes from <system>. How clients unaware of the | to discover what nodes exist in <system>. How clients unaware of the | |||
| <system> datastore can find appropriate configurations are beyond the | <system> datastore can find appropriate configurations is beyond the | |||
| scope of this document. | scope of this document. | |||
| No matter how the referenced system objects are populated, the nodes | No matter how the referenced system objects are copied into | |||
| copied into <running> would always be returned in a read of | <running>, the nodes copied into <running> would always be returned | |||
| <running>, regardless if the client is <system> aware. | after a read of <running>, regardless if the client is <system> | |||
| aware. | ||||
| 4.2. Servers Auto-populating Referenced System Configuration | ||||
| This document defines a new parameter "resolve-system" to the input | ||||
| for the <edit-config> and <edit-data> operations. Clients that are | ||||
| aware of the "resolve-system" parameter MAY use this parameter to | ||||
| avoid the requirement to provide a referentially complete | ||||
| configuration in <running>. | ||||
| If the "resolve-system" is present, the server MUST populate relevant | ||||
| referenced system-defined nodes into the target datastore without the | ||||
| client doing the copy/paste explicitly, to resolve any references not | ||||
| resolved by the client. The server acting as a "system client" like | ||||
| any other remote clients populates the referenced system-defined | ||||
| nodes when triggered by the "resolve-system" parameter. If the | ||||
| "resolve-system" parameter is not given by the client, the server | ||||
| MUST NOT modify <running> in any way not specified by the client. | ||||
| The server may automatically configure the list entries (with at | ||||
| least the keys) in the target datastore (e.g., <running>) for any | ||||
| system configuration list entries that are referenced elsewhere by | ||||
| the clients. Not all the contents of the list entry (i.e., the | ||||
| descendant nodes) are necessarily populated by the sever - only the | ||||
| parts that are required to make the <running> valid. A read back of | ||||
| <running> (i.e., <get>, <get-config> or <get-data> operation) returns | ||||
| those automatically populated nodes. | ||||
| 4.3. Explicit Declaration of System Configuration | 4.2. Explicit Declaration of System Configuration | |||
| It is also possible for a client to explicitly declare system | It is possible for a client to explicitly declare system | |||
| configuration nodes in the target datastore (e.g., <running>) with | configuration nodes in the target datastore (e.g., <running>) with | |||
| the same values as in <system>. When a client configures a node | the same values as in <system>, by configuring a node (list/leaf-list | |||
| (list entry, leaf, etc) in <running> that matches the same node and | entry, leaf, etc) in the target datastore (e.g., <running>) that | |||
| value in <system>, then that node becomes part of <running>. A read | matches the same node and value in <system>. | |||
| back of <running> returns those explicitly configured nodes. | ||||
| This explicit configuration of system configuration in <running> can | This explicit configuration of system-defined nodes in <running> can | |||
| be useful, for example, when the client doesn't want a "system | be useful, for example, when the client doesn't want a "system | |||
| client" to have a role or hasn't implemented the "resolve-system" | client" to have a role or hasn't implemented the "resolve-system" | |||
| parameter. The client can explicitly declare (i.e. configure in | parameter. The client can explicitly declare (i.e. configure in | |||
| <running>) the list entries (with at least the keys) for any system | <running>) the list entries (with at least the keys) for any system | |||
| configuration list entries that are referenced elsewhere in | configuration list entries that are referenced elsewhere in | |||
| <running>. Similarly, The client does not necessarily need to | <running>. The client does not necessarily need to declare all the | |||
| declare all the contents of the list entry (i.e. the descendant | contents of the list entry (i.e. the descendant nodes) - only the | |||
| nodes) - only the parts that are required to make the <running> | parts that are required to make the <running> appear valid. | |||
| appear valid. | ||||
| 4.3. Servers Auto-configuring Referenced System Configuration | ||||
| This document defines a new parameter "resolve-system" to the input | ||||
| for the <edit-config>, <edit-data> and <copy-config> operations. | ||||
| Clients that are aware of the "resolve-system" parameter MAY use this | ||||
| parameter to avoid the requirement to provide a referentially | ||||
| complete configuration in <running>. | ||||
| If the "resolve-system" is present, the server MUST copy relevant | ||||
| referenced system-defined nodes into the target datastore (e.g., | ||||
| <running>) without the client doing the copy/paste explicitly, to | ||||
| resolve any references not resolved by the client. The server acting | ||||
| as a "system client" like any other remote clients copies the | ||||
| referenced system-defined nodes when triggered by the "resolve- | ||||
| system" parameter. If the "resolve-system" parameter is not given by | ||||
| the client, the server SHOULD NOT modify <running> in any way | ||||
| otherwise not specified by the client. | ||||
| The server may automatically configure the list entries (with at | ||||
| least the keys) in the target datastore (e.g., <running>) for any | ||||
| system configuration list entries that are referenced elsewhere by | ||||
| the clients. Similarly, not all the contents of the list entry | ||||
| (i.e., the descendant nodes) are necessarily copied by the server - | ||||
| only the parts that are required to make the <running> valid. A read | ||||
| back of <running> (i.e., <get>, <get-config> or <get-data> operation) | ||||
| returns those automatically copied nodes. | ||||
| 4.4. Modifying (overriding) System Configuration | 4.4. Modifying (overriding) System Configuration | |||
| In some cases, a server may allow some parts of system configuration | In some cases, a server may allow some parts of system configuration | |||
| to be modified. List keys in system configuration can't be changed | to be modified. List keys in system configuration can't be changed | |||
| by a client, but other descendant nodes in a list entry may be | by a client, but other descendant nodes in a list entry may be | |||
| modifiable or non-modifiable. Leafs and leaf-lists outside of lists | modifiable or non-modifiable. Leafs and leaf-lists outside of lists | |||
| may also be modifiable or non-modifiable. Modification of system | may also be modifiable or non-modifiable. Even if some system | |||
| configuration is achieved by the client writing configuration to | configuration has been copied into <running> earlier, whether it is | |||
| <running> that overrides the system configuration. Client | modifiable or not in <running> follows general YANG and NACM rules, | |||
| configuration statements in <running> take precedence over system | and other server-internal restrictions. If a system configuration | |||
| configuration nodes in <system> if the server allows the nodes to be | node is non-modifiable, then writing a different value for that node | |||
| modified. If a system configuration node is non-modifiable, then | in <running> MUST return an error. The immutability of system | |||
| writing a different value for that node in <running> MUST return an | configuration is further defined in [I-D.ma-netmod-immutable-flag]. | |||
| error. | ||||
| Modification of system configuration is achieved by the client | ||||
| writing configuration to <running> that overrides the system | ||||
| configuration. Configurations defined in <running> take precedence | ||||
| over system configuration nodes in <system> if the server allows the | ||||
| nodes to be modified. | ||||
| A server may also allow a client to add data nodes to a list entry in | A server may also allow a client to add data nodes to a list entry in | |||
| <system> by writing those additional nodes in <running>. Those | <system> by writing those additional nodes in <running>. Those | |||
| additional data nodes may not exist in <system> (i.e. an *addition* | additional data nodes may not exist in <system> (i.e. an *addition* | |||
| rather than an override). | rather than an override). | |||
| While modifying (overriding) system configuration nodes may be | While modifying (overriding) system configuration nodes may be | |||
| supported by a server, there is no mechanism for deleting a system | supported by a server, there is no mechanism for deleting a system | |||
| configuration node. A "mandatory true" leaf, for example, may have a | configuration node unless the resource is no longer available. For | |||
| value in <system> which can be modified (overridden) by a client | example, a "mandatory true" leaf may have a value in <system> which | |||
| setting that leaf to a value in <running>. But the leaf could not be | can be modified (overridden) by a client setting that leaf to a value | |||
| deleted. | in <running>. But the leaf could not be deleted. Another example of | |||
| this might be that system initializes a value for a particular leaf | ||||
| which is overridden by the client with intended value in <running>. | ||||
| The client may delete the leaf in <running>, but system-initialized | ||||
| value defined in <system> will be in use and appear in <operational>. | ||||
| Comment 1: What if <system> contains a set of values for a leaf-list, | Comment 1: What if <system> contains a set of values for a leaf-list, | |||
| and a client configures another set of values for that leaf-list in | and a client configures another set of values for that leaf-list in | |||
| <running>, will the set of values in <running> completely replace the | <running>, will the set of values in <running> completely replace the | |||
| set of values in <system>? Or the two sets of values are merged | set of values in <system>? Or the two sets of values are merged | |||
| together? | together? | |||
| Comment 2: how "ordered-by user" lists and leaf-lists are merged? Do | Comment 2: how "ordered-by user" lists and leaf-lists are merged? Do | |||
| the <running> values go before or after, or is this a case where a | the <running> values go before or after, or is this a case where a | |||
| full-replace is needed. | full-replace is needed. | |||
| 4.5. Examples | 4.5. Examples | |||
| This section shows the examples of server-populating of <running> | This section shows the examples of server-configuring of <running> | |||
| automatically, declaring a system-defined node in <running> | automatically, declaring a system-defined node in <running> | |||
| explicitly, modifying a system-instantiated leaf's value and | explicitly, modifying a system-instantiated leaf's value and | |||
| configuring descendant nodes of a system-defined node. For each | configuring descendant nodes of a system-defined node. For each | |||
| example, the corresponding XML snippets are provided. | example, the corresponding XML snippets are provided. | |||
| 4.5.1. Server Populating of <running> Automatically | 4.5.1. Server Configuring of <running> Automatically | |||
| In this subsection, the following fictional module is used: | In this subsection, the following fictional module is used: | |||
| module example-application { | module example-application { | |||
| yang-version 1.1; | yang-version 1.1; | |||
| namespace "urn:example:application"; | namespace "urn:example:application"; | |||
| prefix "app"; | prefix "app"; | |||
| import ietf-inet-types { | import ietf-inet-types { | |||
| prefix "inet"; | prefix "inet"; | |||
| skipping to change at page 23, line 27 ¶ | skipping to change at page 24, line 27 ¶ | |||
| tree, generated by the system | tree, generated by the system | |||
| * Management operations: The content of the datastore is set by the | * Management operations: The content of the datastore is set by the | |||
| server in an implementation dependent manner. The content can not | server in an implementation dependent manner. The content can not | |||
| be changed by management operations via NETCONF, RESTCONF, the | be changed by management operations via NETCONF, RESTCONF, the | |||
| CLI, etc, but may change itself by upgrades and/or when resource- | CLI, etc, but may change itself by upgrades and/or when resource- | |||
| conditions are met. The datastore can be read using the standard | conditions are met. The datastore can be read using the standard | |||
| NETCONF/RESTCONF protocol operations. | NETCONF/RESTCONF protocol operations. | |||
| * Origin: This document does not define any new origin identity when | * Origin: This document does not define any new origin identity when | |||
| it interacts with <intended> datastore and finally flows into | it interacts with <intended> datastore and flows into | |||
| <operational>. The "system" origin Metadata Annotation [RFC7952] | <operational>. The "system" origin Metadata Annotation [RFC7952] | |||
| is used to indicate the origin of a data item is system. | is used to indicate the origin of a data item is system. | |||
| * Protocols: YANG-driven management protocols, such as NETCONF and | * Protocols: YANG-driven management protocols, such as NETCONF and | |||
| RESTCONF. | RESTCONF. | |||
| * Defining YANG module: "ietf-system-datastore". | * Defining YANG module: "ietf-system-datastore". | |||
| The datastore's content is populated by the server and read-only to | The datastore's content is defined by the server and read-only to | |||
| clients. Upon the content is created or changed, it will be merged | clients. Upon the content is created or changed, it will be merged | |||
| into <intended> datastore. Unlike <factory-default>[RFC8808], it MAY | into <intended> datastore. Unlike <factory-default>[RFC8808], it MAY | |||
| change dynamically, e.g., depending on factors like during device | change dynamically, e.g., depending on factors like device upgrade or | |||
| upgrade or system-controlled resources(e.g., HW available) and the | system-controlled resources change (e.g., HW available). The | |||
| <system> datastore does not have to persist across reboots. <factory- | <system> datastore doesn't persist across reboots; the contents of | |||
| reset> RPC operation defined in [RFC8808] can reset it to its factory | <system> will be lost upon reboot and recreated by the system with | |||
| default configuration without including configuration generated due | the same or changed contents. <factory-reset> RPC operation defined | |||
| to the system update or client-enabled functionality. | in [RFC8808] can reset it to its factory default configuration | |||
| without including configuration generated due to the system update or | ||||
| client-enabled functionality. | ||||
| The <system> datastore is defined as a conventional configuration | ||||
| datastore and shares a common datastore schema with other | ||||
| conventional datastores. The <system> configuration datastore must | ||||
| always be valid, as defined in Section 8.1 of [RFC7950]. | ||||
| 6. The "ietf-system-datastore" Module | 6. The "ietf-system-datastore" Module | |||
| 6.1. Data Model Overview | 6.1. Data Model Overview | |||
| This YANG module defines a new YANG identity named "system" that uses | This YANG module defines a new YANG identity named "system" that uses | |||
| the "ds:datastore" identity defined in [RFC8342]. A client can | the "ds:datastore" identity defined in [RFC8342]. A client can | |||
| discover the <system> datastore support on the server by reading the | discover the <system> datastore support on the server by reading the | |||
| YANG library information from the operational state datastore. Note | YANG library information from the operational state datastore. Note | |||
| that no new origin identity is defined in this document, the | that no new origin identity is defined in this document, the | |||
| "or:system" origin Metadata Annotation [RFC7952] is used to indicate | "or:system" origin Metadata Annotation [RFC7952] is used to indicate | |||
| the origin of a data item is system. Support for the "origin" | the origin of a data item is system. Support for the "origin" | |||
| annotation is identified with the feature "origin" defined in | annotation is identified with the feature "origin" defined in | |||
| skipping to change at page 27, line 11 ¶ | skipping to change at page 28, line 11 ¶ | |||
| } | } | |||
| } | } | |||
| <CODE ENDS> | <CODE ENDS> | |||
| 7. The "ietf-netconf-resolve-system" Module | 7. The "ietf-netconf-resolve-system" Module | |||
| This YANG module is optional to implement. | This YANG module is optional to implement. | |||
| 7.1. Data Model Overview | 7.1. Data Model Overview | |||
| This YANG module augments NETCONF <edit-config> and <edit-data> | This YANG module augments NETCONF <edit-config>, <edit-data> and | |||
| operations with a new parameter "resolve-system" in the input | <copy-config> operations with a new parameter "resolve-system" in the | |||
| parameters. If the "resolve-system" parameter is present, the server | input parameters. If the "resolve-system" parameter is present, the | |||
| will populate the referenced system configuration into target | server will copy the referenced system configuration into target | |||
| datastore automatically. A NETCONF client can discover the "resolve- | datastore automatically. A NETCONF client can discover the "resolve- | |||
| system" parameter support on the server by checking the YANG library | system" parameter support on the server by checking the YANG library | |||
| information with "ietf-netconf-resolve-system" included from the | information with "ietf-netconf-resolve-system" included from the | |||
| operational state datastore. | operational state datastore. | |||
| Comment: How does a RESTCONF client know if the RESTCONF server | ||||
| implements the "resolve-system" parameter? | ||||
| The following tree diagram [RFC8340] illustrates the "ietf-netconf- | The following tree diagram [RFC8340] illustrates the "ietf-netconf- | |||
| resolve-system" module: | resolve-system" module: | |||
| module: ietf-netconf-resolve-system | module: ietf-netconf-resolve-system | |||
| augment /nc:edit-config/nc:input: | augment /nc:edit-config/nc:input: | |||
| +---w resolve-system? empty | +---w resolve-system? empty | |||
| augment /nc:copy-config/nc:input: | ||||
| +---w resolve-system? empty | ||||
| augment /ncds:edit-data/ncds:input: | augment /ncds:edit-data/ncds:input: | |||
| +---w resolve-system? empty | +---w resolve-system? empty | |||
| The following tree diagram [RFC8340] illustrates "edit-config" and | The following tree diagram [RFC8340] illustrates "edit-config", | |||
| "edit-data" rpcs defined in "ietf-netconf" and "ietf-netconf-nmda" | "copy-config" and "edit-data" rpcs defined in "ietf-netconf" and | |||
| respectively, augmented by "ietf-netconf-resolve-system" YANG module | "ietf-netconf-nmda" respectively, augmented by "ietf-netconf-resolve- | |||
| : | system" YANG module : | |||
| rpcs: | rpcs: | |||
| +---x edit-config | +---x edit-config | |||
| | +---w input | | +---w input | |||
| | +---w target | | +---w target | |||
| | | +---w (config-target) | | | +---w (config-target) | |||
| | | +--:(candidate) | | | +--:(candidate) | |||
| | | | +---w candidate? empty {candidate}? | | | | +---w candidate? empty {candidate}? | |||
| | | +--:(running) | | | +--:(running) | |||
| | | +---w running? empty {writable-running}? | | | +---w running? empty {writable-running}? | |||
| | +---w default-operation? enumeration | | +---w default-operation? enumeration | |||
| | +---w test-option? enumeration {validate}? | | +---w test-option? enumeration {validate}? | |||
| | +---w error-option? enumeration | | +---w error-option? enumeration | |||
| | +---w (edit-content) | | +---w (edit-content) | |||
| | | +--:(config) | | | +--:(config) | |||
| | | | +---w config? <anyxml> | | | | +---w config? <anyxml> | |||
| | | +--:(url) | | | +--:(url) | |||
| | | +---w url? inet:uri {url}? | | | +---w url? inet:uri {url}? | |||
| | +---w resolve-system? empty | | +---w resolve-system? empty | |||
| +---x copy-config | ||||
| | +---w input | ||||
| | +---w target | ||||
| | | +---w (config-target) | ||||
| | | +--:(candidate) | ||||
| | | | +---w candidate? empty {candidate}? | ||||
| | | +--:(running) | ||||
| | | | +---w running? empty {writable-running}? | ||||
| | | +--:(startup) | ||||
| | | | +---w startup? empty {startup}? | ||||
| | | +--:(url) | ||||
| | | +---w url? inet:uri {url}? | ||||
| | +---w source | ||||
| | | +---w (config-source) | ||||
| | | +--:(candidate) | ||||
| | | | +---w candidate? empty {candidate}? | ||||
| | | +--:(running) | ||||
| | | | +---w running? empty | ||||
| | | +--:(startup) | ||||
| | | | +---w startup? empty {startup}? | ||||
| | | +--:(url) | ||||
| | | | +---w url? inet:uri {url}? | ||||
| | | +--:(config) | ||||
| | | +---w config? <anyxml> | ||||
| | +---w resolve-system? empty | ||||
| +---x edit-data | +---x edit-data | |||
| +---w input | +---w input | |||
| +---w datastore ds:datastore-ref | +---w datastore ds:datastore-ref | |||
| +---w default-operation? enumeration | +---w default-operation? enumeration | |||
| +---w (edit-content) | +---w (edit-content) | |||
| | +--:(config) | | +--:(config) | |||
| | | +---w config? <anydata> | | | +---w config? <anydata> | |||
| | +--:(url) | | +--:(url) | |||
| | +---w url? inet:uri {nc:url}? | | +---w url? inet:uri {nc:url}? | |||
| +---w resolve-system? empty | +---w resolve-system? empty | |||
| 7.2. Example Usage | 7.2. Example Usage | |||
| This section gives an example of an <edit-config> request to | This section gives an example of an <edit-config> request to | |||
| reference system-defined data nodes which are not present in | reference system-defined data nodes which are not present in | |||
| <running> with a "resolve-system" parameter. A retrieval of | <running> with a "resolve-system" parameter. A retrieval of | |||
| <running> to show the auto-populated referenced system objects after | <running> to show the auto-copied referenced system objects after the | |||
| the <edit-config> request is also given. The YANG module used is | <edit-config> request is also given. The YANG module used is shown | |||
| shown as follows, leafrefs refer to an existing name and address of | as follows, leafrefs refer to an existing name and address of an | |||
| an interface: | interface: | |||
| module example-interface-management { | module example-interface-management { | |||
| yang-version 1.1; | yang-version 1.1; | |||
| namespace "urn:example:interfacemgmt"; | namespace "urn:example:interfacemgmt"; | |||
| prefix "inm"; | prefix "inm"; | |||
| container interfaces { | container interfaces { | |||
| list interface { | list interface { | |||
| key name; | key name; | |||
| leaf name { | leaf name { | |||
| skipping to change at page 30, line 27 ¶ | skipping to change at page 31, line 27 ¶ | |||
| <edit-config> | <edit-config> | |||
| <target> | <target> | |||
| <running/> | <running/> | |||
| </target> | </target> | |||
| <config> | <config> | |||
| <default-address xmlns="urn:example:interfacemgmt"> | <default-address xmlns="urn:example:interfacemgmt"> | |||
| <if-name>lo0</if-name> | <if-name>lo0</if-name> | |||
| <address>127.0.0.1</address> | <address>127.0.0.1</address> | |||
| </default-address> | </default-address> | |||
| </config> | </config> | |||
| <resolve-system/> | ||||
| </edit-config> | </edit-config> | |||
| <resolve-system/> | ||||
| </rpc> | </rpc> | |||
| Since the "resolve-system" parameter is provided, the server will | Since the "resolve-system" parameter is provided, the server will | |||
| resolve any leafrefs to system configurations and copy the referenced | resolve any leafrefs to system configurations and copy the referenced | |||
| system-defined nodes into <running> automatically with the same value | system-defined nodes into <running> automatically with the same value | |||
| (i.e., the name and ip-address data nodes of lo0 interface) in | (i.e., the name and ip-address data nodes of lo0 interface) in | |||
| <system> at the end of <edit-config> operation constraint | <system> at the end of <edit-config> operation constraint | |||
| enforcement. After the processing, a positive resonse is returned: | enforcement. After the processing, a positive resonse is returned: | |||
| <rpc-reply message-id="101" | <rpc-reply message-id="101" | |||
| skipping to change at page 31, line 18 ¶ | skipping to change at page 32, line 18 ¶ | |||
| <source> | <source> | |||
| <running/> | <running/> | |||
| </source> | </source> | |||
| <filter type="subtree"> | <filter type="subtree"> | |||
| <interfaces xmlns="urn:example:interfacemgmt"/> | <interfaces xmlns="urn:example:interfacemgmt"/> | |||
| </filter> | </filter> | |||
| </get-config> | </get-config> | |||
| </rpc> | </rpc> | |||
| Given that the referenced interface "name" and "ip-address" of lo0 | Given that the referenced interface "name" and "ip-address" of lo0 | |||
| are populated by the server, the following response is returned: | are configured by the server, the following response is returned: | |||
| <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"> | |||
| <data> | <data> | |||
| <interfaces xmlns="urn:example:interfacemgmt"> | <interfaces xmlns="urn:example:interfacemgmt"> | |||
| <interface> | <interface> | |||
| <name>lo0</name> | <name>lo0</name> | |||
| <ip-address>127.0.0.1</ip-address> | <ip-address>127.0.0.1</ip-address> | |||
| </interface> | </interface> | |||
| </interfaces> | </interfaces> | |||
| skipping to change at page 32, line 20 ¶ | skipping to change at page 33, line 20 ¶ | |||
| Author: Qiufang Ma | Author: Qiufang Ma | |||
| <mailto:maqiufang1@huawei.com> | <mailto:maqiufang1@huawei.com> | |||
| Author: Chong Feng | Author: Chong Feng | |||
| <mailto:frank.fengchong@huawei.com> | <mailto:frank.fengchong@huawei.com> | |||
| Author: Qin Wu | Author: Qin Wu | |||
| <mailto:bill.wu@huawei.com>"; | <mailto:bill.wu@huawei.com>"; | |||
| description | description | |||
| "This module defines an extension to the NETCONF protocol | "This module defines an extension to the NETCONF protocol | |||
| that allows the NETCONF client to control whether the server | that allows the NETCONF client to control whether the server | |||
| is allowed to populate referenced system configuration | is allowed to copy referenced system configuration | |||
| automatically without the client doing so explicitly. | automatically without the client doing so explicitly. | |||
| Copyright (c) 2021 IETF Trust and the persons identified | Copyright (c) 2021 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 | |||
| skipping to change at page 33, line 5 ¶ | skipping to change at page 34, line 5 ¶ | |||
| revision 2021-05-14 { | revision 2021-05-14 { | |||
| description | description | |||
| "Initial version."; | "Initial version."; | |||
| reference | reference | |||
| "RFC XXXX: System-defined Configuration"; | "RFC XXXX: System-defined Configuration"; | |||
| } | } | |||
| augment /nc:edit-config/nc:input { | augment /nc:edit-config/nc:input { | |||
| description | description | |||
| "Allows the server to automatically populate | "Allows the server to automatically configure | |||
| referenced system configuration to make configuration | referenced system configuration to make configuration | |||
| valid."; | valid."; | |||
| leaf resolve-system { | leaf resolve-system { | |||
| type empty ; | type empty ; | |||
| description | description | |||
| "When present, the server is allowed to automatically | "When present, the server is allowed to automatically | |||
| populate referenced system configuration into <running>."; | configure referenced system configuration into the | |||
| } | target configuration datastore."; | |||
| } | ||||
| } | ||||
| augment /nc:copy-config/nc:input { | ||||
| description | ||||
| "Allows the server to automatically configure | ||||
| referenced system configuration to make configuration | ||||
| valid."; | ||||
| leaf resolve-system { | ||||
| type empty ; | ||||
| description | ||||
| "When present, the server is allowed to automatically | ||||
| configure referenced system configuration into the | ||||
| target configuration datastore."; | ||||
| } | ||||
| } | } | |||
| augment /ncds:edit-data/ncds:input { | augment /ncds:edit-data/ncds:input { | |||
| description | description | |||
| "Allows the server to automatically populate | "Allows the server to automatically configure | |||
| referenced system configuration to make configuration | referenced system configuration to make configuration | |||
| valid."; | valid."; | |||
| leaf resolve-system { | leaf resolve-system { | |||
| type empty ; | type empty ; | |||
| description | description | |||
| "When present, the server is allowed to automatically | "When present, the server is allowed to automatically | |||
| populate referenced system configuration into <running>."; | configure referenced system configuration into the | |||
| } | target configuration datastore."; | |||
| } | ||||
| } | } | |||
| } | } | |||
| <CODE ENDS> | <CODE ENDS> | |||
| 8. IANA Considerations | 8. IANA Considerations | |||
| 8.1. The "IETF XML" Registry | 8.1. The "IETF XML" Registry | |||
| This document registers two XML namespace URNs in the 'IETF XML | This document registers two XML namespace URNs 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-system-datastore | URI: urn:ietf:params:xml:ns:yang:ietf-system-datastore | |||
| 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. | |||
| URI: urn:ietf:params:xml:ns:yang:ietf-netconf-resolve-system | URI: urn:ietf:params:xml:ns:yang:ietf-netconf-resolve-system | |||
| skipping to change at page 34, line 15 ¶ | skipping to change at page 35, line 32 ¶ | |||
| name: ietf-system-datastore | name: ietf-system-datastore | |||
| prefix: sys | prefix: sys | |||
| namespace: urn:ietf:params:xml:ns:yang:ietf-system-datatstore | namespace: urn:ietf:params:xml:ns:yang:ietf-system-datatstore | |||
| RFC: XXXX // RFC Ed.: replace XXXX and remove this comment | RFC: XXXX // RFC Ed.: replace XXXX and remove this comment | |||
| name: ietf-netconf-resolve-system | name: ietf-netconf-resolve-system | |||
| prefix: ncrs | prefix: ncrs | |||
| namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-resolve-system | namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-resolve-system | |||
| RFC: XXXX // RFC Ed.: replace XXXX and remove this comment | RFC: XXXX // RFC Ed.: replace XXXX and remove this comment | |||
| 8.3. RESTCONF Capability URN Registry | ||||
| This document registers a capability in the "RESTCONF Capability | ||||
| URNs" registry [RFC8040]: | ||||
| Index Capability Identifier | ||||
| ------------------------------------------------------------------------------- | ||||
| :resolve-system urn:ietf:params:restconf:capability:resolve-system:1.0 | ||||
| 9. Security Considerations | 9. Security Considerations | |||
| 9.1. Regarding the "ietf-system-datastore" YANG Module | 9.1. Regarding the "ietf-system-datastore" YANG Module | |||
| The YANG module defined in this document extends the base operations | The YANG module defined in this document extends the base operations | |||
| for NETCONF [RFC6241] and RESTCONF [RFC8040]. The lowest NETCONF | for NETCONF [RFC6241] and RESTCONF [RFC8040]. The lowest NETCONF | |||
| layer is the secure transport layer, and the mandatory-to-implement | layer is the secure transport layer, and the mandatory-to-implement | |||
| secure transport is Secure Shell (SSH) [RFC6242]. The lowest | secure transport is Secure Shell (SSH) [RFC6242]. The lowest | |||
| RESTCONF layer is HTTPS, and the mandatory-to-implement secure | RESTCONF layer is HTTPS, and the mandatory-to-implement secure | |||
| transport is TLS [RFC8446]. | transport is TLS [RFC8446]. | |||
| skipping to change at page 35, line 33 ¶ | skipping to change at page 37, line 12 ¶ | |||
| Normative References | 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>. | |||
| Informative References | Informative References | |||
| [I-D.ma-netmod-immutable-flag] | ||||
| Ma, Q., Wu, Q., and H. Li, "Immutable Metadata | ||||
| Annotation", Work in Progress, Internet-Draft, draft-ma- | ||||
| netmod-immutable-flag-00, 10 February 2022, | ||||
| <https://www.ietf.org/archive/id/draft-ma-netmod- | ||||
| immutable-flag-00.txt>. | ||||
| [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., | [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., | |||
| and A. Bierman, Ed., "Network Configuration Protocol | and A. Bierman, Ed., "Network Configuration Protocol | |||
| (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, | (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, | |||
| <https://www.rfc-editor.org/info/rfc6241>. | <https://www.rfc-editor.org/info/rfc6241>. | |||
| [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", | [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", | |||
| RFC 7950, DOI 10.17487/RFC7950, August 2016, | RFC 7950, DOI 10.17487/RFC7950, August 2016, | |||
| <https://www.rfc-editor.org/info/rfc7950>. | <https://www.rfc-editor.org/info/rfc7950>. | |||
| [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | |||
| skipping to change at page 39, line 37 ¶ | skipping to change at page 41, line 22 ¶ | |||
| <interface> | <interface> | |||
| <name>et-0/0/0</name> | <name>et-0/0/0</name> | |||
| <description>Test interface</description> | <description>Test interface</description> | |||
| <mtu or:origin="or:system">1500</mtu> | <mtu or:origin="or:system">1500</mtu> | |||
| </interface> | </interface> | |||
| <interface> | <interface> | |||
| </interfaces> | </interfaces> | |||
| Appendix B. Changes between Revisions | Appendix B. Changes between Revisions | |||
| v00 - v01 | v02 - v03 | |||
| * Define a RESTCONF capability URI for "resolve-system" RESTCONF | ||||
| query parameter; | ||||
| * Augment <copy-config> RPC operation to support "resolve-system" | ||||
| for input parameter; | ||||
| * Editorial changes for clarification and explanation. E.g., | ||||
| definition of system configuration, is <system> always valid? | ||||
| Will the update of <system> be reflected into <running>? Clarify | ||||
| "read-only to clients" and "modifying system configuration", non- | ||||
| deletable system configuration, etc | ||||
| v00 - v02 | ||||
| * Remove the "with-system" parameter to retrieve <running> with | * Remove the "with-system" parameter to retrieve <running> with | |||
| system configuration merged in. | system configuration merged in. | |||
| * Add a new parameter named "resolve-system" to allow the server to | * Add a new parameter named "resolve-system" to allow the server to | |||
| populate referenced system configuration into <running> | populate referenced system configuration into <running> | |||
| automatically in order to make <running> valid. | automatically in order to make <running> valid. | |||
| * Usage examples refinement. | * Usage examples refinement. | |||
| End of changes. 70 change blocks. | ||||
| 217 lines changed or deleted | 350 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/ | ||||