Capabilities

Server capabilities are the primary mechanism to specify optional behavior in the NETCONF protocol. This section describes the capabilities that are supported by the netconfd-pro server.

:base:1.0

The :base:1.0 capability indicates that the RFC 4741 version of the NETCONF protocol is supported.

This capability can be controlled with the --protocols CLI parameter.

This capability is supported by default, but it will not be present if the --with-netconf parameter is set to 'false'.

:base:1.1

The :base:1.1 capability indicates that the RFC 6241 version of the NETCONF protocol is supported.

This capability can be controlled with the --protocols CLI parameter.

This capability is supported by default, but it will not be present if the --with-netconf parameter is set to 'false'.

:candidate

The :candidate capability indicates that database edits will be done to the <candidate> database, and saved with the <commit> operation.

The <candidate> configuration is a shared scratch-pad, so it should be used with the locking. Database edits are collected in the <candidate> and then applied, all or nothing, to the <running> database, with the <commit> operation.

This capability is supported by default. It is controlled by the --target configuration parameter (--target=candidate).

By default, only a superuser account can use the <delete-config> operation on the <candidate> configuration.

:config-id

The :config-id capability indicates the current configuration ID of the running datastore. It can be used by clients to cache the running configuration. The config-id attribute returned in the <rpc-reply> message for a <get-config> operation. If this value matches the value in a <hello> message, then the client knows the current configuration is the same as the cached value.

This capability can be enabled or disabled with the --with-config-id CLI parameter.

:confirmed-commit

The :confirmed-commit capability indicates that the server will support the <confirmed> and <confirm-timeout> parameters to the <commit> operation. If the 'base:1.1' protocol version is in use, then the <persist> and <persist-id> parameters are also supported.

The confirmed commit procedure requires that two <commit> operations be used to apply changes from the candidate configuration to the running configuration.

If the second <commit> operation is not received before the <confirm-timeout> value (default 10 minutes), then the running and candidate configurations will be reset to the contents of the running configuration, before the first <commit> operation.

If the session that started the confirmed-commit procedure is terminated for any reason before the second <commit> operation is completed, then the running configuration will be reset, as if the confirm-timeout interval had expired.

If the confirmed-commit procedure is used, and the :startup capability is also supported, then the contents of NV-storage (e.g., startup-cfg.xml) will not be updated or altered by this procedure. Only the running configuration will be affected by the rollback,

If the <confirmed> parameter is used again, in the second <commit> operation, then the timeout interval will be extended, and any changes made to the candidate configuration will be committed. If the running and candidate configurations are reverted, any intermediate edits made since the first <commit> operation will be lost.

This capability can be enabled or disabled with the --with-confirmed-commit CLI parameter.

:interleave

The :interleave capability indicates that the server will accept <rpc> requests other than <close-session> during notification delivery. It is supported at all times, and cannot be configured. This capability is disabled if the --with-notifications CLI parameter is ‘false’.

:netconf-monitoring

The :netconf-monitoring capability indicates that the ietf-netconf-monitoring.yang data sub-trees are supported.

The /netconf-state/capabilities subtree can be examined to discover the active set of NETCONF capabilities.
The /netconf-state/datastores subtree can be examined to discover the active database locks.
The /netconf-state/schemas subtree can be examined for all the YANG modules that are available for download with the <get-schema> operation.
The /netconf-state/sessions subtree can be examined for monitoring NETCONF session activity.
The /netconf-state/statistics subtree can be examined for monitoring global NETCONF counters.

:notification

The :notification capability indicates that the server will accept the <create-subscription> operation, and deliver notifications to the session, according to the subscription request.

All <create-subscription> options and features are supported.

A notification log is maintained on the server, which is restarted every time the server reboots.

This log can be accessed as a 'replay subscription'.

The <replayComplete> Event and <notificationComplete> Event types are not stored in the log.

This capability can be enabled and disabled with the --with-notifications CLI parameter.

:partial-lock

The :partial-lock capability indicates that RFC 5717 is implemented, and partial locking of the <running> database is supported with the <partial-lock> and <partial-unlock> operations.

The <copy-config> operation is not supported using the <running> database as a target, so partial locks do not affect that operation.

The <edit-config> operation on the <running> database is allowed if the --target parameter is set to 'running'.

The <commit> operation will fail if any portion of the altered configuration is locked by another session. Data in the <candidate> database which is identical to the corresponding data in the <running> configuration is not affected by a <partial-lock> operation.

The constant VAL_MAX_PLOCKS in ncx/val.h controls the maximum number of concurrent locks that a single session can own on a database node. The default value is 4.

There is no hard resource limit for:

the number of total partial-locks
the number of <select> parameters in the <partial-lock> request
the number of nodes that can be locked by a single partial-lock

When the maximum <lock-id> is reached (MAX_UINT), the server will not reset the <lock-id> to '1' unless there are no partial locks currently held on the <running> database. The <lock-id> '0' is not used.

:rollback-on-error

The :rollback-on-error capability indicates that the server supports 'all-or-nothing' editing for a single <edit-config> operation. This is a standard enumeration value for the <error-option> parameter.

The server will perform all PDU validation no matter what <error-option> is selected.
Execution phase will not occur if any errors at all are found in the validation phase.

During execution phase, this parameter will affect error processing. When set to 'rollback-on-error', if any part of the requested configuration change cannot be performed, the database will be restored to its previous state, and server instrumentation callbacks to 'undo' any changes made will be invoked.

This capability can be enabled or disabled with the --with-rollback-on-error CLI parameter.

:schema-retrieval

The :schema-retrieval capability indicates that the <get-schema> operation is supported.

The netconfd-pro server supports this operation for all YANG modules in use at the time.

The <identifier> parameter must be set to the name of the YANG module.

The <format> parameter must be set to 'YANG'.

The <version> parameter must be set to a revision date to retrieve a specific version of the module, or the empty string to retrieve whatever version the server is using.

:startup

The :startup capability indicates that the <startup> configuration is supported by the server.

This capability is controlled by the --with-startup configuration parameter. If this parameter is set to 'true', then the ':startup' capability will be supported.

If this capability is supported:

the server will allow the <startup> configuration to be the source of a <get-config>.
the server will allow the <startup> configuration to be the target of a <copy-config> operation, if the source is the <running> configuration.
If the :validate capability is enabled, then the server will allow the <startup> configuration to be the target of a <validate> operation.
If the user is a superuser account, or access is configured in NACM to allow it, then the server will allow the <startup> configuration to be the target of a <delete-config> operation.

No other operations on the <startup> database are supported. The <startup> database cannot be edited with <edit-config>, or over-written with <copy-config>.

:validate

The :validate capability indicates that the <validate> operation is accepted, and the <test-option> for the <edit-config> operation is also accepted, by the server.

Versions supported:

validate:1.0
validate:1.1

This capability is controlled by the --with-validate configuration parameter. If it is set to 'false' then this capability will not be available in netconfd-pro.

The <validate> operation can be invoked in several ways:

validate the <candidate> database if the :candidate capability is supported
validate the <running> database
validate the <startup> database if the :startup capability is supported
validate an in-line <config> element, which represents the entire contents of a database.

The <test-option> parameter for the <edit-config> operation can be used. This parameter has a significant impact on operations, and needs to be used carefully.

set: This option is not the default, but it is probably the desired behavior for the <candidate> database. In order to fully utilize the incremental editing capability of this database, the 'set' value should be used.

This will prevent any validation error messages unrelated to the current edit. The <validate> operation can be used before the <commit> is done, if desired. The same errors (if any) should be reported by <validate> or <commit>.
test-then-set: This option is the default, and will cause a resource intensive validation procedure to be invoked every time the <candidate> database is edited. (The validation procedure is always invoked on every edit to the <running> configuration).

If any database validation errors are found (in addition to the requested edit), then they will be reported. Use the <error-path> field to determine which type of error is being reported by the server.

Note

The NETCONF default test-then-set can be resource intensive and does not need to be used since any <commit> operation will also perform the validation tests.

:url

The :url capability indicates that the server accepts the <url> parameter in NETCONF operations that use this parameter. This capability can be disabled with the --with-url CLI configuration parameter.

The following operations are affected by the :url capability:

<edit-config>
- <url> accepted instead of <config> as a configuration data source
<copy-config>
- <url> accepted as a source parameter.
- <url> accepted as a target parameter.
- <url> to <url> copy not supported (optional to implement)
<delete-config>
- <url> accepted as source to delete
<validate>
- <url> accepted as a configuration source to validate.

Supported Schemes:

The 'file' scheme is supported and enabled if --with-url is set to ‘true’.
The ‘ftp’ scheme is available if the --with-url-ftp CLI parameter is set to ‘true’.
The ‘tftp’ scheme is available if the --with-url-tftp CLI parameter is set to ‘true’.

A URL file can be specified as a simple file within the root directory.

No whitespace or special characters are allowed in the file name.

The file extension '.xml' should be used. The server only generates and expects XML configuration files. The NETCONF 'config' element is used as the top-level element in all <url> files.

The $YUMAPRO_DATAPATH environment variable or the $$datapath system variable is used to find the file names specified in the <url> URI string.

Example:

<url>file:///my-backup.xml</url>

:with-defaults

The :with-defaults capability indicates that the server will accept the <with-defaults> parameter for the following operations:

There are 4 values defined for this parameter. The server supports all of them, no matter what mode is used for the default style.

report-all: all nodes are reported
report-all-tagged: all nodes are reported with an XML attribute indicating the nodes which are considered default nodes by the server.
trim: nodes set to their YANG default-stmt value by the server or the client are skipped
explicit: nodes set by the server are skipped. (Nodes set in the <startup> are considered to be set by the client, not the server.)

The --default-style configuration parameter is used to control the behavior the server will use for these operations when the <with-defaults> parameter is missing. The server will also use this default value when automatically saving the <running> configuration to non-volatile storage.

:writable-running

The :writable-running capability indicates that the server uses the <running> configuration as its edit target. In this case, the <target> parameter for the <edit-config> operation can only be set to <running>.

All edits are activated immediately, but only if the entire database is going to be valid after the edits. A non-destructive test is performed before activating the requested changes.

If this capability is advertised, then netconfd-pro will also advertise the :startup capability. They are always used together.

Edits to the <running> configuration take affect right away, but they are only saved to non-volatile storage automatically if the --with-startup configuration parameter is set to 'false'.

:xpath

The :xpath capability indicates that XPath filtering is supported for the <get>, <get-config>, and <get-data> operations. This is a built-in capability that cannot be disabled.

The netconfd-pro server implements all of XPath 1.0, plus the following additions:

the 'current' function from XPath 2.0 is supported
a missing XML namespace will match any YANG module namespace (XPath 2.0 behavior) instead of matching the NULL namespace (XPath 1.0 behavior)
the 'preceding' and 'following' axes should not be used. The database is dynamic and the relative document order is not stable. This is also a very resource intensive operation.
Refer to the XPath Usage <https://datatracker.ietf.org/doc/html/rfc8407#section-4.6> section of RFC 8407 for more details on XPath usage.

XPath filtering affects whether the server will return particular subtrees or not. It does not change the format of the <get> or <get-config> output. The result returned by the server will not be the raw XPath node-set from evaluating the specified 'select' expression against a database.

The server will normalize the XPath search results it returns:

There will be no duplicate nodes, even if there were duplicates in the XPath result node-set.
All result nodes with common ancestor nodes will be grouped together in the <rpc-reply>.
All list nodes will include child nodes for any missing key leafs, even if they were not requested in the 'select' expression.

:yang-library

The :yang-library capability indicates that the server supports YANG Library mechanism for announcing conformance information. This capability is coupled to the ietf-yang-library.yang module.

The server announces the modules it implements by implementing the YANG module ietf-yang-library.yang and listing all implemented modules for a client to retrieve.

There are 2 versions of this module in use:

:yang-library:1.0 defined in RFC 7950
- The YANG module in RFC 7985 is used
- The subtree /modules-state contains the library information
- Identified by revision date 2016-06-21
- The server will advertise the required capability in the <hello> message. It has the form:
```
urn:ietf:params:netconf:capability:yang-library:1.0?revision=<date>&module-set-id=<id>
```
  where <date> and <id> are replaced by the proper values.
:yang-library:1.1 defined in RFC 8526
- The YANG module in RFC 8525 is used
- The subtree /yang-library contains the library information
- Identified by revision date 2019-01-04
- This version is used if the --with-nmda=true setting is used
- The server will advertise the required capability in the <hello> message. It has the form:
```
urn:ietf:params:netconf:capability:yang-library:1.1?revision=<date>&content-id=<content-id-value>
```
  where <date> and <content-id-value> are replaced by the proper values.

Note

The 2 YANG Library revisions are very different in structure. Both variants are present in the server, if NMDA is used.

The parameter "revision" has the same value as the revision date of the ietf-yang-library.yang module implemented by the server.

The parameter "module-set-id" has the same value as the leaf /modules-state/module-set-id.

If the value of this leaf changes, the server also generates a <yang-library-change> Event notification, with the new value of "module-set-id".

With this mechanism, a client can cache the supported modules for a server and only update the cache if the "module-set-id" value in the <hello> message changes.