With-defaults Capability for NETCONF
Extracted elements (25)
Rather than forcing a single implementation strategy for default data handling, the document allows servers to advertise their particular style (report-all, trim, or explicit) so clients can adjust accordingly. This acknowledges that not all server implementations treat default data the same way.
The 'report-all-tagged' mode was added as a special variant (not a basic mode) to allow a client to distinguish default from non-default data within a single retrieval operation, without requiring the server to adopt it as its fundamental default-handling strategy.
In 'report-all' basic mode, if the 'default' attribute is present in any configuration data, the server MUST return an <rpc-error> with an 'unknown-attribute' error-tag, since this mode has no concept of a default node.
The <with-defaults> element XML namespace belongs to the ietf-netconf-with-defaults YANG module, not to the namespace of <get>, <get-config>, or <copy-config>. A server implementing the module MUST also advertise a YANG module capability URI per RFC 6020 rules.
A NETCONF server MUST select one of the three basic modes defined in Section 2 for handling default data: 'report-all', 'trim', or 'explicit'.
A new <with-defaults> XML element is added to the input for <get>, <get-config>, and <copy-config> operations. If an unsupported value is used, the server MUST return an <rpc-error> with an 'invalid-value' error-tag.
If the 'default' attribute is present in <edit-config>, the effective operation for the target data node MUST be 'create', 'merge', or 'replace'. Otherwise, the server MUST return an <rpc-error> with an 'invalid-value' error-tag.
If the <with-defaults> element is not present in a retrieval operation, the server MUST follow its basic mode behavior as indicated by the :with-defaults capability identifier's 'basic-mode' parameter.
In 'explicit' basic mode, a 'create' for a node set by the client to its schema default MUST fail with 'data-exists'; a 'create' for a server-set default MUST succeed. A 'delete' for a client-set default MUST succeed; a 'delete' for a server-set default MUST fail with 'data-missing'.
In 'report-all' basic mode, a valid 'create' operation attribute for a data node containing its schema default value MUST fail with a 'data-exists' error-tag, and a valid 'delete' MUST succeed (though the node is immediately replaced by the default value).
In 'trim' basic mode, a valid 'delete' operation for a missing data node that has a schema default value MUST fail with a 'data-missing' error-tag. Setting a node to its schema default value MUST succeed but the value MUST NOT be saved in the datastore.
Other NETCONF operations that return configuration data SHOULD also handle default data according to the rules in this document and explicitly state this in their documentation; if unspecified, the default-handling rules herein do not affect those operations.
The <copy-config> operation's <with-defaults> parameter only takes effect when the target is specified with the <url> parameter. If the target is a NETCONF configuration datastore, <with-defaults> has no effect and MUST be silently ignored.
The :with-defaults capability identifier MUST include the 'basic-mode' parameter indicating the server's default-handling mode. It MAY include an 'also-supported' parameter listing additional retrieval modes the server accepts.
When the 'default' attribute is present and set to 'true' or '1' in <edit-config> or <copy-config>, the server MUST treat it as a request to return the node to its default value. The node MUST contain a value equal to the schema default value; otherwise the server MUST return an 'invalid-value' error.
The capability identifier URI is 'urn:ietf:params:netconf:capability:with-defaults:1.0' with required parameter 'basic-mode' (values: 'report-all', 'trim', 'explicit') and optional 'also-supported' (comma-separated list of additionally supported modes).
The 'explicit' basic mode MUST consider any data node that is not explicitly set by a client to be default data. Explicitly-set nodes are reported even if they contain the schema default value; server-set default nodes are not reported.
The 'report-all' basic mode treats no data node as default data, even schema default data. All data nodes MUST be reported in basic mode retrieval when <with-defaults> is not present.
The 'report-all-tagged' retrieval mode returns all data nodes like 'report-all', but annotates nodes considered default by the server with a 'default' XML attribute set to 'true' or '1'. It is optional and indicated via the 'also-supported' capability parameter.
The 'trim' basic mode MUST consider any data node set to its schema default value to be default data. Such nodes MUST NOT be reported in basic mode retrieval and MUST NOT be saved in the NETCONF configuration datastore.
The :with-defaults capability allows a NETCONF client to identify how defaults are processed by the server and provides new mechanisms for client control of server processing of default data. It is advertised via a capability URI with required 'basic-mode' parameter.
The YANG module 'ietf-netconf-with-defaults' (namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults) defines the 'with-defaults-mode' typedef with enumerations 'report-all', 'report-all-tagged', 'trim', and 'explicit', and augments <get-config>, <get>, and <copy-config> input with the <with-defaults> leaf.
This document registers the capability identifier URN 'urn:ietf:params:netconf:capability:with-defaults:1.0' in the NETCONF Capability URNs registry, two XML namespace URNs in the IETF XML registry, and the module name 'ietf-netconf-with-defaults' in the YANG Module Names registry.
The with-defaults capability extension does not introduce any new or increased security risks into the management system. The security considerations of RFC 6241 (NETCONF) apply to this document as well.
The 'default' XML attribute (namespace: urn:ietf:params:xml:ns:netconf:default:1.0) is of XSD type xs:boolean. Allowable lexical representations are '0'/'false' for false and '1'/'true' for true; implementations MUST support both styles.