| Internet-Draft | System Configuration Data Handling | October 2020 |
| Feng & Ma | Expires 23 April 2021 | [Page] |
The NETCONF protocol [RFC6241] defines ways to read configuration and state data from a NETCONF server. In some cases, a client-configured data item refers to a non-existent system generated data item (e.g.,the auto-create interfaces ("eth1") is not yet present). In many situations, the system configured data item doesn't need to be know to the client and client-configured data item will automatically be removed from the operational state datastore and thus only appear in the intended datastore if client-configured data item doesn't exist. In other situations system configured data item needs to be known and overriden by the client. Not all server implementations treat the system configuration data in the same way. This document defines a capability-based extension to the NETCONF protocol that allows the NETCONF client to identify how system configuration are processed by the server, and also defines a new mechanism for client control of server processing of system configuration data.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 23 April 2021.¶
Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
The NETCONF protocol [RFC6241] defines ways to read configuration and state data from a NETCONF server.¶
In some cases, a client-configured data item refers to a nonexistent system generated data item (e.g.,the auto-create interfaces ("eth1") is not yet present).¶
Not all server implementations treat the system configuration data in the same way.¶
This document defines a capablity-based extension to the NETCONF protocol that allows the NETCONF client to identify how system configuation are processed by the server, and also defines new mechanism for client control of server processing of system configuration data.¶
This document assumes that the reader is familiar with the contents of [RFC6241], [RFC7950], [RFC8342], [RFC8407], and [RFC8525] and uses terminologies from those documents.¶
The following terms are defined in this document as follows:¶
Configuration that is supplied by the device itself [RFC8342].¶
When the device is powered on, the pre-provisioned configuration will be activated and provided, irrespective of physical resource present or not, sometimes the pre-provisioned configuration will be provided unconditionally(e.g., loop back interface activation), sometimes not, e.g., only provided when a special functionality is enabled.¶
When the device is powered on and the physical resource is present(e.g., insert interface card), the system will automatically detect it and load pre-provisioned configuration; when the physical resource is not present( remove interface card), the system configuration will be automatically cleared.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
Following guidelines for defining Datastores in the appendix A of [RFC8342], this document introduces a new datastore resource named 'system' that represents the pre-provisioned configuration or physical resource dependent configuration.¶
The datastore content is usually defined by the device vendor. It is static at most of time and MAY change e.g., depending on external factors like HW available or during device upgrade. On devices that support non-volatile storage, the contents of <system> configuration datastore need to be persist across reboots.¶
When the device is powered on and the physical resource is inserted into the device, physical resource dependent system configuration will be automatically loaded into <system>;¶
When the physical resource is removed from the device, the physical resource dependent system configuration will be automatically removed from <system>;¶
When the Logical resource dependent system configuration is referenced by another configured data item, it will be automatically loaded into <system> if it doesn't exist in the <system>; The <system> will keep unchanged if the Logical resource dependent system configuration has already been existed in the <system>.¶
The system configuration data handling behavior used by a server will impact NETCONF protocol operations in two ways:¶
Not all server implementations treat system configuration data in the same way. Instead of forcing a single implementation strategy, this document allows a server to advertise a particular style of system configuration data handling, and the client can adjust accordingly.¶
NETCONF servers report system configuration data in different ways. This document specifies two standard defaults handling basic modes that a server implementor may choose from:¶
A server that uses the 'report-all' basic mode MUST automatically¶
A server that uses the 'explicit' basic mode¶
On devices that support non-volatile storage, the contents of <system> (e.g.,logical resource dependent system configuration (conditional or unconditional) and physical resource dependent system configuration) will typically persist across reboots via that storage. At boot time, the device loads the saved system configuration into <running> together with saved startup configuration via 'merge' protocol operation. To save a new system configuration, data is copied to <system> via either implicit or explicit protocol operations.¶
The server MUST consider every data node to exist, even those explicitly set by the server.¶
The server considers any data node that is explicitly set data to exist.¶
When data is retrieved from a server using the 'explicit' basic mode, and the <with-system> parameter is not present, data nodes MUST be reported if explicitly modified by the client.¶
If the 'explicit' basic mode is used by the server and the <with-system> parameter supported by the server is set to a value equal to 'explicit', data nodes MUST be reported if explicitly modified by the client.¶
When data is retrieved from a server using the 'report-all' basic mode, and the <with-system> parameter is not present, all data nodes MUST be reported without data nodes considered to be system configuration data by the server.¶
If the 'report-all' basic mode is used by the server and the <with-system> parameter supported by the server is set to a value equal to 'report-all', all data nodes MUST be reported, including any data nodes considered to be system configuration data by the server.¶
If the 'report-all' basic mode is used by the server and the <with-system> parameter supported by the server is set to a value equal to 'report-all-tagged', all data nodes MUST be reported, including any data nodes considered to be system configuration data by the server. Explicitly set data by the server will be tagged with <system> if the system configuration is applied.¶
When data is retrieved from a server using the <with-system> parameter with a value equal to 'trim' , data nodes MUST be reported if considered to be system configuration data by the server. Data node MUST NOT be reported if explicitly modified by the client.¶
The :with-system capability indicates which system-data-handling basic mode is supported by the server. These retrieval modes allow a NETCONF client to control whether system configuration data is returned by the server. Sending of system configuration data is controlled for each individual operation separately.¶
A NETCONF server implementing the :with-system capability:¶
urn:ietf:params:netconf:capability:with-system:1.0¶
The identifier MUST have a parameter: "basic-mode". This indicates how the server will treat system configuration data, as defined in Section 4. The allowed values of this parameter are 'report-all', and 'explicit', as defined in Section 4.¶
The identifier MAY have another parameter: "also-supported". This parameter indicates which additional enumeration values (besides the basic-mode enumeration), the server will accept for the <with-system> parameter in Section 4. The value of the parameter is a comma separated list of one or more modes that are supported beside the mode indicated in the 'basic-mode' parameter. Possible modes are 'report-all', 'report-all-tagged','trim' and 'explicit', as defined in Section 4.¶
urn:ietf:params:netconf:capability:with-system:1.0?basic-mode=explicit&also-supported=report-all,report-all-tagged¶
A new <with-system> XML element is added to the input for the <get>, <get-config> and <copy-config> operations. If the <with-system> element is present, it controls the reporting of system configuration data. The server MUST return system configuration data in the NETCONF <rpc-reply> messages according to the value of this element, if the server supports the specified retrieval mode.¶
This parameter only controls these specified retrieval operations, and does not impact any other operations or the non-volatile storage of configuration data.¶
The <with-system> element is defined in the XML namespace for the ietf-netconf-with-system.yang module in Section 7, not the XML namespace for the <get>, <get-config> and <copy-config> operations.¶
If the <with-system> element is not present, the server MUST follow its basic mode behavior as indicated by the :with-system capability identifier's 'basic-mode' parameter, defined in Section 6.2.¶
The <get> and <get-config> operations support a separate filtering mechanism, using the <filter> parameter. The system configuration data filtering is conceptually done before the <filter> parameter is processed. For example, if the <with-system> parameter is equal to 'report-all', then the <filter> parameter is conceptually applied to all data nodes and all system configuration data.¶
The <edit-config> operation has several editing modes. The 'create', and 'delete' editing operations are affected by the system configuration data handling basic mode. The other enumeration values for the NETCONF operation attribute are not affected.¶
If the operation attribute contains the value 'create', and the data node already exists in the target configuration datastore, then the server MUST return an <rpc-error> response with a 'invalid-value' error-tag.¶
If the client sets a data node that is explicitly set by the server, the server MUST accept the request if it is valid. The server MUST keep or discard the new value based on its system configuration data handling basic mode.¶
The following YANG module defines the addition of the with-system element to the <get>, <get-config>, and <copy-config> operations. The YANG language is defined in [RFC6020]. The above operations are defined in YANG in [RFC6241]. Every NETCONF server which supports the :with-system capability MUST implement this YANG module.¶
<CODE BEGINS> file="ietf-netconf-with-system@2019-12-31.yang"
module ietf-netconf-with-system {
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-system";
prefix ncws;
import ietf-netconf { prefix nc; }
organization
"IETF NETCONF (Network Configuration Protocol) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
WG Chair:
Editor:
";
description
"This module defines an extension to the NETCONF protocol
that allows the NETCONF client to control how system configuration
data are handled by the server in particular NETCONF operations.
Copyright (c) 2010 IETF Trust and the persons identified as
the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this note
revision 2019-12-31 {
description
"Initial version.";
reference
"RFC XXXX: With-system capability for NETCONF";
}
typedef with-system-mode {
description
"Possible modes to report system configuration data.";
reference
"RFC XXXX; section 3.";
// RFC Ed.: replace XXXX with actual
// RFC number and remove this note
type enumeration {
enum report-all {
description
"All system configuration data is reported.";
reference
"RFC XXXX; section 3.1";
// RFC Ed.: replace XXXX with actual
// RFC number and remove this note
}
enum report-all-tagged {
description
"All system configuration data is reported.
Any nodes considered to be system configuration
data will contain a 'origin' XML attribute,
set to 'system'.";
reference
"RFC XXXX; section 3.4";
// RFC Ed.: replace XXXX with actual
// RFC number and remove this note
}
enum trim {
description
"Values are not reported if they contain the system
configuration data.";
reference
"RFC XXXX; section 3.2";
// RFC Ed.: replace XXXX with actual
// RFC number and remove this note
}
enum explicit {
description
"Report values that contain the definition of
explicitly set data.";
reference
"RFC XXXX; section 3.3";
// RFC Ed.: replace XXXX with actual
// RFC number and remove this note
}
}
}
grouping with-system-parameters {
description
"Contains the <with-system> parameter for control
of system configuration data in NETCONF retrieval
operations.";
leaf with-system {
description
"The explicit system configuration data processing
mode requested.";
reference
"RFC XXXX; section 4.6.1";
// RFC Ed.: replace XXXX with actual
// RFC number and remove this note
type with-system-mode;
}
}
// extending the get-config operation
augment /nc:get-config/nc:input {
description
"Adds the <with-system> parameter to the
input of the NETCONF <get-config> operation.";
reference
"RFC XXXX; section 4.6.1";
// RFC Ed.: replace XXXX with actual
// RFC number and remove this note
uses with-system-parameters;
}
// extending the get operation
augment /nc:get/nc:input {
description
"Adds the <with-system> parameter to
the input of the NETCONF <get> operation.";
reference
"RFC XXXX; section 4.6.1";
// RFC Ed.: replace XXXX with actual
// RFC number and remove this note
uses with-system-parameters;
}
}
<CODE ENDS>¶
This document registers the following capability identifier URN in the 'Network Configuration Protocol Capability URNs registry':¶
urn:ietf:params:netconf:capability:with-system:1.0¶
This document registers two XML namespace URNs in the 'IETF XML registry', following the format defined in [RFC3688].¶
URI: urn:ietf:params:xml:ns:netconf:system:1.0
URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system
Registrant Contact: The NETCONF WG of the IETF.
XML: N/A, the requested URIs are XML namespaces.¶
This document registers one module name in the 'YANG Module Names' registry, defined in [RFC6020] .¶
name: ietf-netconf-with-system
prefix: ncws
namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system
RFC: XXXX // RFC Ed.: replace XXXX and remove this comment¶
The following YANG module defines an example interfaces table to demonstrate how the <with-system> parameter behaves for a specific data model.¶
container interfaces {
list interface {
key name;
leaf name {
type string;
}
leaf description {
type string;
}
leaf-list ip-address {
type inet:ip-address;
}
}
}¶
The following data element shows the conceptual contents of the example server for the protocol operation examples in the next section. This includes all the configuration data nodes and system configuration leafs.¶
<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<interfaces xmlns="http://example.com/ns/interfaces">
<interface>
<name>lo0</name>
<ip-address>127.0.0.1</ip-address>
<ip-address>::1</ip-address>
</interface>
<interface>
<name>lo1</name>
<description>loopback</description>
<ip-address>127.0.0.1</ip-address>
<ip-address>::2</ip-address>
</interface>
<interface>
<name>lo2</name>
<description>loopback</description>
<ip-address>127.0.0.1</ip-address>
<ip-address>::3</ip-address>
</interface>
<interface>
<name>lo3</name>
<ip-address>127.0.0.1</ip-address>
<ip-address>::1</ip-address>
</interface>
</interfaces>
</data>¶
In this example, the 'ip-address' field for each interface entry is set in the following manner:¶
+---------+----------+-------+ | name |ip-address| set by| +---------+----------+-------+ | lo0 |127.0.0.1 | server| | lo0 | ::1 | server| | lo1 |127.0.0.1 | server| | lo1 | ::2 | client| | lo2 |127.0.0.1 | server| | lo2 | ::3 | client| | lo3 |127.0.0.1 | server| | lo3 | ::1 | server| +---------+----------+-------+¶
The following examples show some <get> operations using the 'with- system' element. The data model used for these examples is defined in Appendix A.1.¶
The client is retrieving all the data nodes within the 'interfaces' object, filtered with the <with-system> parameter.¶
The behavior of the <with-system> parameter handling for the value 'report-all' is demonstrated in this example.¶
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<interfaces xmlns="http://example.com/ns/interfaces"/>
</filter>
<with-system
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-system">
report-all
</with-system>
</get>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<interfaces xmlns="http://example.com/ns/interfaces">
<interface>
<name>lo0</name>
<ip-address>127.0.0.1</ip-address>
<ip-address>::1</ip-address>
</interface>
<interface>
<name>lo1</name>
<description>loopback</description>
<ip-address>127.0.0.1</ip-address>
<ip-address>::2</ip-address>
</interface>
<interface>
<name>lo2</name>
<description>loopback</description>
<ip-address>127.0.0.1</ip-address>
<ip-address>::3</ip-address>
</interface>
<interface>
<name>lo3</name>
<ip-address>127.0.0.1</ip-address>
<ip-address>::1</ip-address>
</interface>
</interfaces>
</data>
</rpc-reply>¶
The behavior of the <with-system> parameter handling for the value 'report-all-tagged' is demonstrated in this example. A 'tagged' data node is an element that contains the 'origin' XML attribute, set to 'system'.¶
The actual data nodes tagged by the server depend on the system configuration data handling basic mode used by the server. Only the data nodes that are considered to be system configuration data will be tagged.¶
In this example, the server's basic mode is 'explicit', then only data nodes that are not explicitly set data are tagged. If the server's basic mode is 'report-all', then no data nodes are tagged.¶
<rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<interfaces xmlns="http://example.com/ns/interfaces"/>
</filter>
<with-system
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-system">
report-all-tagged
</with-system>
</get>
</rpc>¶
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin">
<data>
<interfaces xmlns="http://example.com/ns/interfaces">
<interface or:origin="or:system">
<name>lo0</name>
<ip-address>127.0.0.1</ip-address>
<ip-address>::1</ip-address>
</interface>
<interface>
<name>lo1</name>
<description>loopback</description>
<ip-address or:origin="or:system">127.0.0.1</ip-address>
<ip-address>::2</ip-address>
</interface>
<interface>
<name>lo2</name>
<description>loopback</description>
<ip-address or:origin="or:system">127.0.0.1</ip-address>
<ip-address>::3</ip-address>
</interface>
<interface or:origin="or:system">
<name>lo3</name>
<ip-address>127.0.0.1</ip-address>
<ip-address>::1</ip-address>
</interface>
</interfaces>
</data>
</rpc-reply>¶
The behavior of the <with-system> parameter handling for the value 'explicit' is demonstrated in this example.¶
<rpc message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<interfaces xmlns="http://example.com/ns/interfaces"/>
</filter>
<with-system
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-system">
explicit
</with-system>
</get>
</rpc>¶
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<interfaces xmlns="http://example.com/ns/interfaces">
<interface>
<name>lo0</name>
</interface>
<interface>
<name>lo1</name>
<description>loopback</description>
<ip-address>::2</ip-address>
</interface>
<interface>
<name>lo2</name>
<description>loopback</description>
<ip-address>::3</ip-address>
</interface>
<interface>
<name>lo3</name>
</interface>
</interfaces>
</data>
</rpc-reply>¶
The behavior of the <with-system> parameter handling for the value 'trim' is demonstrated in this example.¶
<rpc message-id="104"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<interfaces xmlns="http://example.com/ns/interfaces"/>
</filter>
<with-system
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-system">
trim
</with-system>
</get>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<interfaces xmlns="http://example.com/ns/interfaces">
<interface>
<name>lo0</name>
<ip-address>127.0.0.1</ip-address>
<ip-address>::1</ip-address>
</interface>
<interface>
<name>lo1</name>
<description>loopback</description>
<ip-address>127.0.0.1</ip-address>
</interface>
<interface>
<name>lo2</name>
<description>loopback</description>
<ip-address>127.0.0.1</ip-address>
</interface>
<interface>
<name>lo3</name>
<ip-address>127.0.0.1</ip-address>
<ip-address>::1</ip-address>
</interface>
</interfaces>
</data>
</rpc-reply>¶