5. NETCONF
5.1. NETCONF Overview
NETCONF is a standardized IETF configuration management protocol specified in RFC 6241, Network Configuration Protocol (NETCONF). It is secure, connection-oriented, and runs on top of the SSHv2 transport protocol as specified in RFC 6242, Using the NETCONF Configuration Protocol over Secure Shell (SSH). NETCONF is an XML-based protocol that can be used as an alternative to CLI or SNMP for managing an SR OS router.
NETCONF uses RPC messaging for communication between a NETCONF client and the NETCONF server running on SR OS. An RPC message and configuration or state data is encapsulated within an XML document. These XML documents are exchanged between a NETCONF client and a NETCONF server in a request/response type of interaction. The SR OS NETCONF interface supports configuration, state and various router operations (for example, reboot). Figure 14 shows a NETCONF RPC request.
Figure 14: NETCONF RPC Request
NETCONF can be conceptually partitioned into four layers as described in RFC 6241. Figure 15 shows the NETCONF layers.
Figure 15: NETCONF Layers (RFC 6241)
5.2. NETCONF in SR OS
NETCONF can be used on an SR OS router to perform router management operations including:
- changing the configuration of the router (using the <edit-config> operation)
- reading the configuration of the router (using the <get-config> operation, equivalent to the info command while in the configure branch of the SR OS CLI)
- reading operational status and data using the <get> operation (equivalent to the show commands in the SR OS CLI, or executing the info command while in the state branch of MD-CLI)
- notifications on an SR OS router (equivalent to the SR OS log events)
- operations equivalent to MD-CLI commands, such as admin, file, clear, oam, and ping, using md-cli-raw-command (See NETCONF Operations Using the md-cli-raw-command Request.)
- some operations (for example, admin reboot, ping) are individually modeled as YANG actions and can be called from NETCONF (see Individually Modeled YANG-based Operations).
The SR OS NETCONF server supports both the base:1.1 capability and the base:1.0 capability.
5.2.1. Transport and Sessions
SSH transport for NETCONF is supported on TCP port 830 (default) or port 22 with IPv4 or IPv6 in-band in the “Base” routing instance or in a VPRN, or out-of-band in the “Management” routing instance on the CPM Ethernet ports.
NETCONF SSH sessions (the same as CLI, SCP, and sFTP sessions) are subject to any configurable and non-configurable session limits; for example, inbound-max-sessions.
Both the SSH server and NETCONF protocol must be enabled in the router configuration in order to use NETCONF.
NETCONF sessions do not time out automatically and are not subject to the CLI session timeout. Operators can disconnect sessions manually using the admin disconnect command.
A client establishing a NETCONF session must log in to the router so user accounts must exist for NETCONF on SR OS. An access type netconf is provided. For access to the Nokia SR OS YANG data models, only netconf access is necessary.
Authentication using the local user database is supported for NETCONF users. The access netconf statement must be configured in the local user record. Also, NETCONF runs over SSH, and SSH supports RADIUS/TACACS+ user authentication.
For RADIUS, access netconf must be enabled in the user template (configure system security user-template radius_default in the classic CLI, or configure system security aaa user-template radius-default in the MD-CLI), and use-default-template must be enabled (configure system security radius use-default-template in the classic CLI, or configure system security aaa remote-servers radius use-default-template in the MD-CLI). The RADIUS server must also send the Timetra-Access VSA with a value that includes "netconf" access, for example, "Timetra-Access = netconf" or "Timetra-Access = 15".
For TACACS+, access tacplus must be enabled in the user template (configure system security user-template tacplus_default in the classic CLI, or configure system security aaa user-template tacplus-default in the MD-CLI), and use-default-template must be enabled (configure system security tacplus use-default-template in the classic CLI, or configure system security aaa remote-servers tacplus use-default-template in the MD-CLI).
Authorization is supported for configuration and state elements in NETCONF. The local, RADIUS, or TACACS+ authorization CLI rules are translated and applied to NETCONF requests to modify or display configuration or state data.
5.2.2. Datastores and URLs
SR OS supports several datastores including the following standard datastores:
- <running>
- <candidate>
- <startup>
- <intended>
Some NETCONF functions use data from <url> locations.
For additional details about datastores, see Datastores and Regions.
The supported datastores can be obtained through the “/yang-library” state data model that contains a list of supported datastores, as defined in RFC 8525.
The :candidate capability is advertised in the SR OS NETCONF server <hello> as:
Configuration changes (using the Nokia SR OS YANG data models) made to the <candidate> datastore take effect after a successful <commit> operation.
The <intended> datastore is a read-only datastore that represents the configuration after configuration transformations (such as configuration group expansion) to <running> are performed.
The <startup> datastore and <url> can only be used with <copy-config> and <delete-config> and are not supported with any other operations (including <edit-config>, <get-config>, <get>, <validate>, and so on).
The :startup capability is advertised in the SR OS NETCONF server <hello> as:
The <url> supports the same options as CLI <file-url>: local urls (CF) and remote urls (ftp and tftp).
The :url capability is advertised in the SR OS NETCONF server <hello> as:
The following examples show the format of each URL scheme:
- <url>ftp://name:passwd@IP_ADDRESS/myfiles/myfile.cfg</url>
- <url>tftp://name:passwd@IP_ADDRESS/myfiles/myfile.cfg</url>
- <url>file:///cf3:/myfiles/myfile.cfg</url>
- <url>cf3:/myfiles/myfile.cfg</url>
 | Note: The examples use “///” for the file URL. Also, the file://localhost/... format is not supported. |
BOF (Boot Options File) is a separate configuration region, and configuration over NETCONF can be performed using the Nokia SR OS YANG models.
Debug configuration (such as debug mirrors, or any debug configuration saved with admin save debug) is not available as a configuration region.
Lawful Intercept (LI) is a separate configuration region, and configuration over NETCONF can be performed using the Nokia SR OS YANG models (including configuring any LI log-ids needed to subscribe/receive LI NETCONF notifications). The same user permissions apply using NETCONF as with MD-CLI (in other words, only LI users can access LI data).
The <candidate> datastore supports the XML content layer only.
5.2.3. NETCONF Operations and Capabilities
Each RPC request can only contain one operation. Table 24 summarizes the protocol operations and capabilities supported on the 7450 ESS, 7750 SR, and 7950 XRS.
Table 24: Summary of Operations and Capabilities
Support | Capabilities | Operations |
Base Protocol Operations | — |
|
RFC 6241 1 | writable-running capability | — |
candidate configuration capability | ||
confirmed commit | <cancel-commit> | |
validate | ||
startup | — | |
URL | — | |
rollback-on-error | — | |
RFC 6243 | with-defaults | — |
RFC 5277 | notification | <create-subscription> |
interleave | — | |
RFC 6022 | ietf-network-monitoring | |
RFC 8525 | ietf-yang-library | — |
RFC 8526 | — | <get data> |
RFC 7950 | — | <action> 2 |
- Optional capabilities defined in RFC 6241 are supported
- YANG 1.1 defines an <action> element. See section Individually Modeled YANG-based Operations for details of SR OS support of actions.
Notes:
Table 25 shows supported NETCONF operations.
Table 25: Supported Standard NETCONF Operations and Arguments
Operation | Arguments |
get-config | source/[configuration-region] [filter] |
edit-config | target/[configuration-region] [default-operation] [test-option] [error-option] config |
copy-config | target/[configuration-region] source/[configuration-region] |
delete-config | target |
lock | target/[configuration-region] |
unlock | target/[configuration-region] |
get | [filter] [configuration-region] |
close-session | — |
kill-session | session-id |
discard-changes | [configuration-region] |
validate | source/[configuration-region] |
commit | [confirmed] [confirm-timeout] [persist] [persist-id] [configuration-region] |
cancel-commit | [persist-id] |
create-subscription | [stream] [startTime] [stopTime] |
get-schema | identifier [version] [format] |
get-data | datastore [subtree-filter] [max-depth] [with-defaults] [configuration-region] |
action | ( 1) |
- YANG 1.1 defines an <action> element. See section Individually Modeled YANG-based Operations for details of SR OS support for actions.
Note:
| Note: Bracketed arguments are optional. X/[configuration-group] means that the [configuration-group] can only be used as a child of X. |
Table 26 lists protocol operations and level of support in SR OS NETCONF servers, and limitations, if any, in the current implementation.
Table 26: Protocol Operations and Level of Support in Nokia SR OS NETCONF Servers
Protocol Operation | Example | Supported | Notes |
get-config | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get-config> <source> <running/> </source> </get-config> </rpc> ]]>]]> | Yes | To use the get-config operation, the user must belong to a NETCONF system security profile with get-config enabled for the base-op-authorization. If present, configuration annotations are encoded with the nokia-attr:comment attribute. |
<source> <startup/> </source> | No | — | |
<source> <candidate/> </source> | Yes | — | |
<source> <config/> </source> | No | — | |
<source> <url/> </source> | No | — | |
<?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101"xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get-config> <source><running/></source> <filter type="subtree"> </filter> </get-config> </rpc> ]]>]]> | Yes | A <filter> is an optional argument. All subtree filters are supported in SR OS except for “attribute match expressions”. | |
<filter type="xpath"> </filter> | No | — | |
<source> <configuration-region>...</configuration-region </source> | Yes | Optional. Specify "li", "bof" or "configure". The default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. A datastore must be specified inside the <source> if the <configuration-region> is used. | |
get | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get/> </rpc> ]]>]]> | Yes | Retrieves both configuration and state data if in XML content layer. To use the get operation, the user must belong to a NETCONF system security profile with get enabled for the base-op-authorization. If present, configuration annotations are encoded with the nokia-attr:comment attribute. |
<?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get> <filter type="subtree"> </filter> </get> </rpc> ]]>]]> | Yes | A <filter> is an optional argument. Subtree filters are supported except for "attribute match expressions". | |
<filter type="xpath"> </filter> | No | — | |
<configuration-region>...</configuration-region> | Yes | Optional. Specify "li", "bof" or "configure". The default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. | |
edit-config | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <edit-config> <target/> <default-operation/> <test-option/> <error-option/> <config/> </edit-config> </rpc> ]]>]]> | Yes | <default-operation>, <test-option>, and <error-option> are optional arguments. To use the edit-config operation, the user must belong to a NETCONF system security profile with edit-config enabled for the base-op-authorization. Configuration annotations may be encoded with the nokia-attr:comment attribute to add, change, or delete the annotations. |
<target> <url/> </target> | No | — | |
<target> <startup/> </target> | No | — | |
<target> <candidate/> </target> | Yes | — | |
<default-operation>merge</default-operation> | Yes | Default | |
<default-operation>none</default-operation> | Yes | With the Nokia SR OS YANG modules, an operation of "none" (inherited or direct) on a leaf node that does not exist in the data model causes SR OS to return an error with an <error-tag> value of “data-missing”. | |
<default-operation>replace</default-operation> | Yes | — | |
<test-option>test-then-set</test-option> | Yes | — | |
<test-option>set</test-option> | Yes | — | |
<test-option>test-only</test-option> | Yes | — | |
<error-option>continue-on-error</error-option> | No | — | |
<error-option>rollback-on-error</error-option> | Yes | — | |
<error-option>stop-on-error</error-option> | Yes | Default. This can be specified but, starting in Release 20.2.R1, behaves the same as a rollback-on-error. | |
<target> <configuration-region>...</configuration-region> </target> | Yes | Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. | |
close-session | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <close-session/> </rpc> ]]>]]> | Yes | When a session is closed, any locks held are released and the session is terminated. Any pending RPC requests are discarded. To use the close-session operation, the user must belong to a NETCONF system security profile with close-session enabled for the base-op-authorization. |
commit | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <commit/> </rpc> ]]>]]> | Yes | When commit is issued, any configuration stored in the <candidate> datastore is written to the running configuration unless the device is locked by a NETCONF client or <running> datastore is locked by any other NETCONF session. The startup configuration is also written if system management-interface netconf auto-config-save is configured. To use the commit operation, the user must belong to a NETCONF system security profile with commit enabled for the base-op-authorization. |
<commit><comment>Comment entered over NETCONF.</comment></commit> | Yes | Optional. Specifies a comment in the commit history. | |
<commit><confirmed/></commit> | Yes | Optional. Can only be used with non-li configurations. | |
<commit> <confirmed/> <confirm-timeout/> </commit> | Yes | Optional. Can only be used with non-li configurations. | |
<commit> <confirmed/> <confirm-timeout/> <persist/> </commit> | Yes | Optional. Can only be used with non-li configurations. | |
<commit> <confirmed/> <confirm-timeout/> <persist/> <persist-id/> </commit> | Yes | Optional. Can only be used with non-li configurations. | |
<commit> <configuration-region>...</configuration-region> </commit> | Yes | Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. | |
cancel-commit | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <cancel-commit/> </rpc> | Yes | Can only be used with non-li configurations. To use the cancel commit operation, the user must belong to a NETCONF system security profile with cancel-commit enabled for the base-op-authorization. |
<cancel-commit> <persist-id/></cancel-commit> | Yes | Optional. When a <commit> <persist> is used, the value of a <cancel-commit> <persist-id> must be equal to the value used in the <commit> <persist>. | |
copy-config | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <copy-config> <target/> <source/> </copy-config> </rpc> ]]>]]> | Yes | The <copy-config> operation is supported for specific combinations of source and target datastores. To use the copy-config operation, the user must belong to a NETCONF system security profile with copy-config enabled for the base-op-authorization. When the specified <configuration-region> is "li", the <source><running/> to <target><startup/> becomes the only valid <copy-config> combination. |
<target><running/></target> | No | The running datastore cannot be a <target> for a <copy-config>. | |
<target><candidate/></target> <source><running/></source> | No | Use <discard-changes>. | |
<target><startup/></target> <source><running/></source> | Yes | Equivalent to admin save. An index file is also saved in classic management-interface configuration-mode if persist on is configured in the BOF. | |
<target><url/></target> <source><running/></source> | Yes | Equivalent to admin save file-url. An index file is also saved in classic management-interface configuration-mode if persist on is configured in the BOF. | |
<target><candidate/></target> <source><startup/></source> | Yes | — | |
<target><url/></target> <source><startup/></source> | Yes | Supported if both source and target are not remote URLs. Only configuration changes are saved; for example, an index file is not saved in classic management-interface configuration-mode even if persist on is configured in the BOF. | |
<target><running/></target> <source><startup/></source> | No | — | |
<target><startup/></target> <source><candidate/></source> | Yes | — | |
<target><url/></target> <source><candidate/></source> | Yes | — | |
<target><running/></target> <source><candidate/></source | No | Use <commit> instead. | |
<target><running/></target> <source><url/></source> | No | — | |
<target><candidate/></target> <source><url/></source> | Yes | Supported in model-driven configuration mode only. | |
<target><startup/></target> <source><url/></source> | Yes | Supported if both source and target are not remote URLs. Only configuration changes are saved; for example, an index file is not saved in classic management-interface configuration-mode even if persist on is configured in the BOF. | |
<target><url/></target> <source><url/></source> | Yes | Supported if both source and target are not remote URLs. | |
<target><config/></target> | No | — | |
<target><candidate/></target> <source><config/></source> | Yes | — | |
<target><startup/></target> <source><config/></source> | Yes | — | |
<target><url/></target> <source><config/></source> | Yes | — | |
<target> <configuration-region>...</configuration-region> </target> | Yes | Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure”. Can only be used with the Nokia SR OS modules. Not supported in mixed mode. | |
<source> <configuration-region>...</configuration-region> </source> | Yes | Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. Not supported in mixed mode. | |
kill-session | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <kill-session> <session-id/> </kill-session> </rpc> ]]>]]> | Yes | A NETCONF session cannot kill itself. A NETCONF session cannot kill a non-NETCONF session. When a session is killed, any operations pending in that session are discarded. Any locks held by that session are released. Only a NETCONF user that belongs to a profile with base-op-authorization/kill-session enabled, can kill a NETCONF session. |
lock | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <lock> <target/> </lock> </rpc> ]]>]]> | Yes | Only a NETCONF user that belongs to a profile with base-op-authorization/lock enabled, can lock a datastore. |
<target><candidate/></target> | Yes | Locking the <candidate> datastore implicitly locks both the <running> and <candidate> datastores. | |
<target><running/></target> | Yes | Locking the <running> datastore locks both the <running> and <candidate> datastores. | |
<target><startup/></target> | No | — | |
<target><url/></target> | No | — | |
<target> <configuration-region>...</configuration-region> </target> | Yes | Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. | |
unlock | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <unlock> <target/> </unlock> </rpc> ]]>]]> | Yes | Only a NETCONF user that belongs to a profile with base-op-authorization/lock enabled, can unlock a datastore. A datastore lock is unlocked when: - using <unlock> - disconnecting a NETCONF session (from CLI using the admin disconnect command, by using Ctrl-c, by performing <kill-session>, or by performing <close-session>) Upon unlocking/disconnecting a NETCONF session that had acquired a datastore lock, SR OS: - releases the lock - discards any “uncommitted” changes |
<target><candidate/></target> | Yes | — | |
<target><running/></target> | Yes | — | |
<target><startup/></target> | No | — | |
<target><url/></target> | No | — | |
<target> <configuration-region>...</configuration-region> </target> | Yes | Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. | |
validate | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <validate> <source/> </validate> </rpc> ]]>]]> | Yes | XML content layer only. Only syntax validation is performed. If more than one error exists, SR OS returns multiple errors. No semantic validation is performed. To use the validate operation, the user must belong to a NETCONF system security profile with validate enabled for the base-op-authorization. |
<source><candidate/></source> | Yes | — | |
<source><running/></source> | Yes | — | |
<source><startup/></source> | No | — | |
<source><url/></source> | No | — | |
<source><config/></source> | No | — | |
<source> <configuration-region>...</configuration-region> </source> | Yes | Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. | |
delete-config | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <delete-config> <target/> </delete-config> </rpc> ]]>]]> | Yes | To use the delete-config operation, the user must belong to a NETCONF system security profile with delete-config enabled for the base-op-authorization. |
<target><startup/></target> | Yes | — | |
<target><url/></target> | Yes | — | |
<target><running/></target> | No | — | |
<target><candidate/></target> | No | — | |
discard-changes | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <discard-changes/> </rpc> ]]>]]> | Yes | To use the discard-changes operation, the user must belong to a NETCONF system security profile with discard-changes enabled for the base-op-authorization. |
<discard-changes> <configuration-region>...</configuration-region> </discard-changes> | Yes | Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. | |
create-subscription | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> <create-subscription/> </rpc> ]]>]]> | Yes | To use the create-subscription operation, the user must belong to a NETCONF system security profile with create-subscription enabled for the base-op-authorization. The configuration of base-op-authorization create-subscription is not pre-emptive, which means it is checked only at the time of the initial subscription. Configuration changes to the base-op-authorization do not cancel any in-progress subscriptions and operators who successfully subscribed continue to receive messages. |
<create-subscription><stream/></create-subscription> | Yes | Optional | |
<create-subscription><startTime/></create-subscription> | Yes | Optional | |
<create-subscription><stopTime/></create-subscription> | Yes | Optional | |
<create-subscription><filter/></create-subscription> | No | Optional | |
get-schema | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get-schema xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"> </get-schema> </rpc> ]]>]]> | Yes | To use the get-schema operation, the user must belong to a NETCONF system security profile with get-schema enabled for the base-op-authorization. |
<get-schema><identifier/></get-schema> | Yes | Mandatory | |
<get-schema><version/></get-schema> | Yes | Optional | |
<get-schema><format/></get-schema> | Yes | Optional | |
get-data | <?xml version="1.0" encoding="UTF-8"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get-data> </get-data> </rpc> ]]>]]> | Yes | To use the get-data operation, the user must belong to a NETCONF system security profile with get-data enabled for the base-op-authorization. |
<get-data><datastore/></get-data> | Yes | Mandatory. The “startup” cannot be used. | |
<get-data><subtree-filter/></get-data> | Yes | Optional | |
<get-data><max-depth/></get-data> | Yes | Optional | |
<get-data><config-filter/></get-data> | No | Optional | |
<get-data><origin-filters/></get-data> | No | Optional | |
<get-data><with-origin/></get-data> | No | Optional | |
<get-data><with-defaults/></get-data> | Yes | Optional | |
<get-data><xpath-filter/></get-data> | No | Optional | |
<get-data> <configuration-region> </configuration-region> </get-data> | Yes | Optional. Default if not specified is "configure". Can be "li" or "configure". Can only be used with the Nokia SR OS modules. | |
action | ( 1) |
- YANG 1.1 defines an <action> element. See section Individually Modeled YANG-based Operations for details of SR OS support for actions.
Note:
5.2.3.1. <get>
A <get> request can retrieve both the configuration and state data from the "urn:nokia.com:sros:ns:yang:sr:conf" namespace and state data from the "urn:nokia.com:sros:ns:yang:sr:state" namespace.
If any nodes from the configure tree are included in a <get> request filter then, at minimum, the <configure> tag must contain a namespace. If the namespace is not specified, SR OS returns an error.
A <get> request is first analyzed for syntax errors before any execution starts. If a syntax error is found, a single global <rpc-error> for the entire request is sent in the reply.
Responses are provided for each item in the request until the first item with an error is found. The item with an error has a <response> tag containing some error information, followed by an <rpc-error> tag (and sub-tags). The reply is then returned, and subsequent items are not executed.
The <rpc-error> for an individual item (that is, for a non-syntax error) is after the </response> information and not inside the <response>.
See the <get-config> section for details about subtree filtering support.
To retrieve BOF configurations, the “bof” <configuration-region> must be specified within the <get> RPC. For example:
To retrieve LI configurations, the “li” <configuration-region> must be specified within the <get> RPC. For example:
When a <configuration-region> is not specified, the <configuration-region> (that is, the main non-LI configuration region) is considered to be “configure” by default.
When a mismatched namespace or <configuration-region> combination is specified, SR OS returns an empty <data>.
See Table 26 for more details.
If present, configuration annotations are encoded with the nokia-attr:comment attribute. In the following example, configure system name is annotated with the comment "This is a comment on the system name." in the RPC reply:
See the following sections for examples of <get> request and response messages:
5.2.3.1.1. Example: Namespace Specified in <configure> Tag
The following shows a <configure> tag that contains a namespace.
The following example shows the reply, which returns no errors.
5.2.3.1.2. Example: Namespace Error in <configure> Tag
The following example shows a <configure> tag that does not contain a namespace.
The following example shows the reply, which returns SR OS errors.
5.2.3.1.3. Example: Namespace Specified in <state> Tag
The following example shows a <state> tag that contains a namespace.
The following example shows the reply, which returns no errors.
5.2.3.1.4. Example: Namespace Error in <state> Tag
The following example shows a <state> tag that does not contain a namespace.
The following example shows the reply, which returns errors.
5.2.3.2. <get-config>
A <get-config> operation is supported on the <candidate> datastore.
The <get-config> requests on the <candidate> datastore return only XML-formatted content. If no filter is specified for the <candidate> datastore, SR OS returns only the Nokia SR OS configurations.
For the Nokia SR OS YANG modules, <get-config> requests that specify a nonexistent list node or presence container result in an <rpc-error> response.
For the “report-all” value with the <with-defaults> tag (RFC 6243) in an XML- content layer, <get-config> returns the equivalent of the CLI command info detail (the returned data includes attributes that are set to their default values).
Subtree filtering is supported for <get-config> (and <get> requests). The following is the subtree filtering behavior.
- Containment nodes are supported (section 6.2.3 of RFC 6241). Nodes that contain children nodes (containers) can be used for subtree filtering. See Example: Containment Node for more information.
- Attribute match expressions (section 6.2.2 of RFC 6241) are not supported.
- Selection nodes are supported (section 6.2.4 of RFC 6241). Empty leaf nodes and list name nodes can be used as selection nodes. A selection node that is a list and does not have a key specified is supported. See Example: List with Non-key Leaf Specified as Selection Node for more information.
- Content match nodes are supported (section 6.2.5 of RFC 6241). Content match nodes that are leafs but not keys are also supported. See Example: Non-key Leaf Specified as a Content Match Node for more information.
The <get-config> operation returns data nodes set by a client to their default Nokia SR OS model values (the “explicit” mode as described in RFC 6243).
To retrieve BOF configurations, the “bof” <configuration-region> must be specified within the <get-config> <source>. For example:
To retrieve LI configurations, the “li” <configuration-region> must be specified within the <get-config> <source>. For example:
Alternatively, the <source> can be specified in the format of “configuration-region”-”datastore”. For example:
When both the <configuration-region> and the “configuration-region”-“datastore” format are used, SR OS applies the last tag used in the XML request. For example:
In the preceding example, the <get-config> is used to retrieve the “li” configuration data from the “li” candidate datastore.
When a mismatched namespace or <configuration-region> combination is specified, SR OS returns an empty <data>.
See Table 26 for more details.
If present, configuration annotations are encoded with the nokia-attr:comment attribute. In the following example, configure system name is annotated with the comment "This is a comment on the system name." in the RPC reply:
The following sections contain examples of <get-config> request and response messages.
5.2.3.2.1. Example: Reply with Defaults
The following example shows the use of <with-defaults> with a value of "report-all".
The following example shows the reply, which returns all attributes, even those with with default values.
5.2.3.2.2. Example: Reply Without Default Values
The following example shows a <get-config> request using <with-defaults>.
The following output shows the reply, which does not return attributes with default values.
5.2.3.2.3. Example: Containment Node
The following example shows a containment node.
5.2.3.2.4. Example: List Without a Key Specified
The following example shows a selection node that is a list and does not have a key specified.
5.2.3.2.5. Example: List with Non-key Leaf Specified as Selection Node
The following example shows a list with a non-key leaf specified as a selection node. Keys are returned as well.
5.2.3.2.6. Example: Non-key Leaf Specified as a Content Match Node
The following example shows a non-key leaf specified as a content match node.
5.2.3.2.7. Example: Content Match Node on a List Key
Multiple key leafs for the same key cannot be requested inside the same instance of the list name node. Instead, each key value must be inside its own instance of the list name node; for example, <interface><interface-name>abc</interface-name></interface><interface> <interface-name>def</interface-name></interface>.
The following example shows a content match node on a list key.
5.2.3.2.8. Example: Content Match Node on a Leaf-list
A content match node can be performed on a leaf-list but SR OS requires that all of the leaf-list elements and nodes must be specified. The full configuration (equivalent to the classic CLI command admin display-config or the MD-CLI command admin show configuration) can be obtained using a <get-config> request both when a <filter> tag is not present and when the <configure> tag is present inside a <filter> tag.
The following example shows a content match node on a lead-list when the <filter> tag is not present.
The following example shows a content match node on a lead-list when only the <configure> tag is present inside the <filter> tag.
5.2.3.3. <edit-config>
An <edit-config> operation is supported on the <candidate> datastore. The <edit-config> requests that specify the <running> datastore as a target when using the "urn:nokia.com:sros:ns:yang:sr:conf" namespace (the Nokia SR OS YANG modules) result in an error response.
The <edit-config> requests to the <candidate> datastore only result in XML- formatted content.
An internal "implicit" lock is in place on the <running> datastore; the datastore has a scope of all configuration commands in SR OS (not just the "urn:nokia.com:sros:ns:yang:sr:conf" namespace). The following actions affect the "implicit" lock.
- The first NETCONF <edit-config> on a global <candidate> datastore triggers the "implicit" lock.
- The completion of a NETCONF <commit> releases the "implicit" lock.
- The NETCONF <discard-changes> operation releases the "implicit" lock.
The following scenarios are impacted when the "implicit" lock is in place.
- All classic CLI commands are blocked while in model-driven configuration mode, and SR OS returns an error.
- An SNMP set request is blocked while in model-driven configuration mode, and SR OS returns an error.
One or more <edit-config> requests can be performed on the <candidate> datastore before the changes are committed or discarded.
The supported <edit-config> operation attribute values are listed in Table 27.
Table 27: <edit-config> Operation Attribute Values
Command | Notes |
urn:nokia.com:sros:ns:yang:sr:conf namespace Nokia SR OS YANG modules | |
merge (Nokia SR OS modules) | Supported |
remove (Nokia SR OS modules) | A <remove> operation removes the deleted configuration and returns it to the default value. A <remove> operation automatically removes all child objects of a deleted object (leaves, lists, containers, and so on). Explicit shutdown of the object being removed (or any child) is not required and results in an error if a merge operation is specified on a tag that inherits a <remove> operation. A <remove> operation is allowed on non-presence containers. The non-presence container and all of its children are removed (for example, a non-presence container with no child nodes is not displayed in a <get> or <get-config> reply). A <remove> operation is allowed on an object where all child branches and dependencies are automatically removed (but the <remove> operation fails if any outside objects refer to the object being removed). A <remove> operation is allowed on a <shutdown/> leaf (which returns it to its default value). A <remove> operation is allowed on a non-Boolean leaf. Upon specifying a <remove> operation on a node where none of its children belong to the urn:nokia.com:sros:ns:yang:sr:conf namespace (the Nokia SR OS YANG modules), SR OS does not return an error and completes the node removal. A <remove> operation for a leaf, where the request also specifies a value for the leaf, results in an error. |
delete (Nokia SR OS modules) | SR OS returns an error if a <delete> operation is performed on a list that does not specify a key (that is, an attempt to delete all members of a list). SR OS returns an error if a <delete> operation is performed on a leaf or presence container that is already deleted (or has the default value and the default-handling is trim). SR OS may return an error and may not complete the deletion operation when a <delete> operation is performed on a node where any of its children do not belong to the urn:nokia.com:sros:ns:yang:sr:conf namespace (the Nokia SR OS YANG modules). A <delete> operation removes the deleted configuration and returns it to the default value. A <delete> operation automatically deletes all child objects of a deleted object (leaves, lists, containers, and so on). Explicit shutdown of the object being deleted (or any of its children) is not required and results in an error if a merge operation is specified on a tag that inherits a <delete> operation. A <delete> operation is allowed on non-presence containers. The non-presence container and all of its children are deleted (for example, a non-presence container with no child nodes is not displayed in a <get> or <get-config> reply). A <delete> operation is allowed on an object where all child branches and dependencies are automatically deleted (but the <delete> operation fails if any outside objects refer to the object being deleted). A <delete> operation is allowed on a <shutdown/> leaf (which returns it to its default value). A <delete> operation is allowed on a non-boolean leaf. Upon specifying a <delete> operation on a node where none of its children belong to the urn:nokia.com:sros:ns:yang:sr:conf namespace (the Nokia SR OS YANG modules), SR OS does not return an error and completes the node deletion. A <delete> operation for a leaf, where the request also specifies a value for the leaf, will result in an error. |
create (Nokia SR OS modules) | When a <create> operation for a leaf or presence container is performed, SR OS returns an error if the leaf or presence container is being set to the same value (unless the default-handling is trim and the value being set is the default value). |
replace (Nokia SR OS modules) | Supported |
The <edit-config> operation <default-operation> parameter is supported with the following values:
- replace
- merge
- none
- In the urn:nokia.com:sros:ns:yang:sr:conf namespace (the Nokia SR OS YANG modules), an operation of "none" (inherited or direct) on a leaf node that does not exist in the data model causes SR OS to return an error with an <error-tag> value of data-missing.
For <delete> and <remove> operations in the Nokia SR OS namespace, the SR OS NETCONF server will recursively unwind any children of the node being deleted or removed first before removing the node. The deepest child branch of the request is examined first, and any leaves are processed, after which the server works backwards out of the deepest branches back up to the object where the delete operation was specified.
The following applies to the urn:nokia.com:sros:ns:yang:sr:conf namespace (the Nokia SR OS YANG modules):
- SR OS returns an error if an explicitly defined <edit-config> operation (such as "delete") is specified on a "key" leaf.
- The "operation" attribute is inherited from the parent node if not explicitly specified (similar to namespaces). If no parent node is available, the "default-operation" value is used. This means that the "operation" attribute has a "scope" that it applies to the nested nodes until it is redefined.
See Example: Application of Default Operation Value for Parent and Child Nodes and Example: Exceptions to the Default Operation Handling for more information.
The following scenarios simplify “operation" inheritance, where the first line in each scenario represents the operation value of the parent node and the following lines represent the possible operation values for the child nodes and the SR OS behavior in each case:
- CreateCreate/Merge: SR OS processes the request, which succeeds or fails based on the behavior of this operation.Delete/Remove: SR OS returns an error.
- MergeCreate/Merge/Delete/Remove: SR OS processes the request, which succeeds or fails based on the behavior of this operation.
- Delete/RemoveCreate/Merge: SR OS returns an error.Delete/Remove: SR OS processes the request, which succeeds or fails based on the behavior of this operation.
The <error-option> is supported. SR OS implements the rollback-on-error behavior at all times, when:
- the error-option is not specified
- the error-option is specified and set to either stop-on-error or rollback-on-error
As per RFC 6020, YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF), the “insert” and “value” attributes are supported with user-ordered leaf-lists to insert or move a user-ordered leaf-list entry in the candidate datastore.
As per RFC 6020, the “insert” and “key” attributes are supported with user-ordered lists to insert or move a user-ordered list entry in the candidate datastore.
With a NETCONF <edit-config> RPC, SR OS authorizes all configuration changes in the <candidate> datastore; that is, it checks the YANG tree and authorizes every changed managed object (MO).
The deletion of a container results in the deletion of any children containers that are authorized for deletion, as well as their contents. Children containers that are not authorized for deletion, as well as their contents, are retained. For example, upon deletion of configure system, configure system security is not deleted because the deletion of that child container is not authorized.
| Note: A “no change” for a value does not require authorization. Therefore, it is possible to execute a non-authorized command if there is no change in value. For example, when a user is not authorized to change access li, but attempts to change it for another a user who already has access li, SR OS allows that action because there is no change in value. |
To edit BOF configurations, the “bof” <configuration-region> must be specified within the <edit-config> <target>. For example:
To edit LI configurations, the “li” <configuration-region> must be specified within the <edit-config> <target>. For example:
Alternatively, the <target> can be specified in the format of “configuration-region”-”datastore”. For example:
When both the <configuration-region> and the “configuration-region”-”datastore” format are used, SR OS applies the last tag used in the XML request. For example:
When a mismatched namespace or <configuration-region> combination is specified, SR OS returns an error.
The <edit-config> RPC can only be used to push LI configuration changes if all of the following conditions are true.
- The NETCONF user is an LI user.
- The NETCONF session has an exclusive lock on the LI configuration region and <candidate> datastore.
- The specified <configuration-region> is “li”.
- The YANG modules that are used are the Nokia SR OS YANG modules.
If any of the preceding conditions is false, SR OS returns an error.
See Table 26 for more details.
Configuration annotations may be encoded with the nokia-attr:comment attribute to add, change, or delete the annotations. In the following example, configure system name is annotated with the comment “This is a comment on the system name.” in the <edit-config> RPC:
See the following sections for examples of <edit-config> request and response messages:
5.2.3.3.1. Example: <running> Datastore with the “urn:nokia.com:sros:ns:yang:sr:conf” Namespace
The following example shows the use of the <running> datastore with the “urn:nokia.com/sros:ns:yang:sr:conf” namespace.
The following example shows the reply, which returns SR OS errors.
5.2.3.3.2. Example: Application of Default Operation Value for Parent and Child Nodes
The following example shows that the default (operation=”merge”) applies to all parent and child nodes.
The following example shows the reply.
5.2.3.3.3. Example: Exceptions to the Default Operation Handling
The following example shows that the default (operation=”merge”) applies to all parent and child nodes except for <description>, which has a (operation=”delete”).
The following example shows the reply.
5.2.3.4. <copy-config>
To <copy-config> BOF configurations, the “bof” <configuration-region> must be specified within the <copy-config> RPC <source> and <target>. For example:
| Note: When <copy-config> RPC is used with the “bof” <configuration-region>, only the following combinations are supported:
|
To <copy-config> LI configurations, the “li” <configuration-region> must be specified within the <copy-config> RPC <source> and <target>. When the <configuration-region> is “li” or “bof”, SR OS can only <copy-config> from the <running> datastore to the <startup> datastore. For example:
Performing a <copy-config> between datastores from different <configuration-region> is not allowed. Mismatching the source or target <configuration-region> causes SR OS to return an error.
Alternatively, the <target>/<source> can be specified in the format of “configuration-region”-“datastore”. For example:
When both the <configuration-region> and the “configuration-region”-“datastore” format are used, SR OS applies the last tag used in the XML request. For example:
In the preceding example, the <copy-config> is used to copy the configuration data from the “li” <running> datastore to the “li” <startup> datastore.
See Table 26 for more details.
5.2.3.5. <delete-config>
See Table 26 for more details.
5.2.3.6. <lock>
Taking the <candidate> datastore lock is equivalent to starting a CLI exclusive session. A NETCONF session cannot take the <candidate> datastore lock if there are uncommitted configuration changes in the <candidate> datastore.
It is recommended that a NETCONF session should always take the <candidate> datastore lock before reading or writing configurations to ensure the <candidate> datastore is not changed by other model-driven sessions. Release the <candidate> datastore lock after all configurations are successfully read or committed.
When either the <running> datastore lock or the <candidate> datastore lock is taken by a NETCONF session:
- no NETCONF session can take the <running> datastore lock
- no NETCONF session can take the <candidate> datastore lock
- no other NETCONF session can do an <edit-config> on the <running> datastore
- no other NETCONF session can do an <edit-config> on the <candidate> datastore
- no other NETCONF session can do a <commit> on the <candidate> datastore
- no other NETCONF session can do a <discard-changes> on the <candidate> datastore
- CLI becomes read-only
- classic CLI rollback revert is blocked
A datastore lock is unlocked when disconnecting a NETCONF session (either from the CLI using the admin disconnect command, using Ctrl-c, or by performing a <kill-session> / <close-session> operation). Upon disconnecting a NETCONF session that had acquired a datastore lock, SR OS:
- releases the lock
- discards any “uncommitted” changes
| Note: The behavior is different if the disconnected NETCONF session was using the global <candidate> datastore and had uncommitted configuration changes. In that case, SR OS keeps the “uncommitted” changes in the global <candidate> datastore. |
Timeouts for locks are not supported. No specific admin or tools commands are provided to release the lock without disconnecting the session that holds it, but the session that holds the lock can be administratively disconnected through a CLI command to release the lock.
Using a CLI show command, the operator can determine whether the <running> datastore is locked, the <candidate> datastore is locked, or both are locked, and the session ID of the session that holds the lock.
From CLI, the operator can configure whether users that belong to a specific profile have permission to lock NETCONF sessions.
An active NETCONF session can be disconnected from the CLI using the session ID. The user can use the show command to find the NETCONF session ID, then use this session ID in the admin command to disconnect the NETCONF session.
To lock a BOF datastore, the “bof” <configuration-region> must be specified within the <lock> <target>. For example:
To lock an LI datastore, the “li” <configuration-region> must be specified within the <lock> <target>. For example:
Alternatively, the <target> can be specified in the format of “configuration-region”-”datastore”. For example:
When both the <configuration-region> and the “configuration-region”-“datastore” format are used, SR OS applies the last tag used in the XML request. For example:
In the preceding example, the <lock> is used to lock the “li” <candidate> datastore.
The LI datastores have independent locks from the main configuration datastores.
See Table 26 for more details.
5.2.3.7. <unlock>
Because there is a single lock per datastore, regardless of the scope of that lock, the following caveats apply to the <unlock> operation.
- The <running> datastore lock is unlocked by using the <unlock> command only on the <running> datastore. An error results and the lock stays if a different datastore is specified with the <unlock> operation.
- The <candidate> datastore lock is unlocked by using the <unlock> command only on the <candidate> datastore. An error results and the lock stays if a different datastore is specified with the <unlock> operation.
Performing an <unlock> operation on the <candidate> datastore discards all pending (not committed) <candidate> datastore changes.
To unlock a BOF datastore, the “bof” <configuration-region> must be specified within the <unlock> <target>. For example:
To unlock an LI datastore, the “li” <configuration-region> must be specified within the <unlock> <target>. For example:
Alternatively, the <target> can be specified in the format of “configuration-region”-”datastore”. For example:
When both the <configuration-region> and the “configuration-region”-”datastore” format are used, SR OS applies the last tag used in the XML request. For example:
In the preceding example, the <unlock> is used to unlock the “li” <candidate> datastore.
See Table 26 for more information.
5.2.3.8. <commit>
The following are the characteristics of the <commit> command.
- It represents the equivalent of the CLI command commit.
- When a <commit> operation fails and more than one error exists, SR OS returns multiple errors.
- When SR OS is not able to commit all the changes in the <candidate> datastore, SR OS keeps the <running> datastore unchanged.
- When a NETCONF session is disconnected (using the CLI command, Ctrl-c, or <kill-session>) in the middle of a <commit> operation, SR OS keeps the <running> datastore unchanged.
- The persistency of changes made using a <commit> operation is operator-controlled. A copy of the <running> datastore to the <startup> datastore can be automatically performed after each successful <commit> operation. This behavior can be enabled or disabled through a CLI command.
- If changes exist in the <candidate> datastore (before they are committed to the <running> datastore), this impacts:
- a CLI user trying to make immediate changes, because SR OS may block some CLI immediate configurations
- an SNMP set request, because SR OS may block the request and return an error
To commit BOF configurations, the “bof” <configuration-region> must be specified within the <commit> RPC. For example:
To commit LI configurations, the “li” <configuration-region> must be specified within the <commit> RPC. For example:
The <commit> RPC can only be used with LI configuration changes if all of the following conditions are true.
- The NETCONF user is a LI user.
- The NETCONF session has an exclusive lock on the LI configuration region and <candidate> datastore.
- The specified <configuration-region> is “li”.
- The YANG modules used are the Nokia SR OS YANG modules.
If any of the preceding conditions are false, SR OS returns an error.
The :confirmed-commit capability cannot be used with LI configuration changes.
The :confirmed-commit capability is advertised in the SR OS NETCONF server <hello> as:
<capability>urn:ietf:params:netconf:capability:confirmed-commit:1.1</capability>
The :confirmed-commit capability includes the following characteristics.
- The capability is not advertised if the operator disables the <candidate> datastore capability using the available SR OS CLI command.
- Table 28 lists the supported parameters for a <commit> operation.
Table 28: Parameters for a <commit> Operation
Parameter
Description
<comment>
Optional.
Specifies a comment in the commit history.
<confirmed>
Indicates a confirmed <commit> operation.
<confirm-timeout>
Specifies the timeout period for confirmed commit (in seconds). If unspecified, the confirmed commit timeout defaults to 600 seconds (10 minutes).
<persist>
Configures the confirmed commit changes to survive a session termination. It sets a token on the ongoing confirmed commit. If <persist> is not in the confirmed commit operation, any follow-up commit and the confirming commit must be issued on the same session that issued the confirmed commit. If <persist> is in the confirmed commit operation, a follow-up commit and the confirming commit can be on any session. However, they must include a <persist-id> element with a value equal to the value of the <persist> element in the confirmed commit. The <persist> element cannot be changed through a follow-up confirmed commit.
<persist-id>
Issues a follow-up confirmed commit or the confirming commit from any session, using the same token from the <persist> element of the confirmed commit. The <persist-id> element cannot be changed through a follow-up confirmed commit.
- If <persist> is specified in the confirmed commit, the configuration changes are rolled back only if the timeout expires before a confirming commit is received. The confirming commit must include a <persist-id> tag with a value equal to the value of the <persist> tag contained in the confirmed commit.
- If the NETCONF session that initiated the confirmed commit is closed while waiting for the confirming commit (for example, disconnected), SR OS restores the configuration to its state before the confirmed commit was issued. This is valid only if <persist> was not defined in the confirmed commit.If a follow-up confirmed commit is issued before the timer expires, the timer is reset to the new value.
- The confirming commit and the follow-up confirmed commit cannot introduce additional changes to the configuration.The <cancel-commit> operation is supported. It can cancel an ongoing confirmed commit (that is, cancel the timer and rollback the changes introduced with the confirmed commit).
- Without the <persist> parameter, the <cancel-commit> operation must be issued in the same session that issued the confirmed commit.
- If the configuration changes involve changing the configuration-mode to classic, a confirmed commit should not be used to commit those configuration changes, as SR OS would switch to classic mode before sending the second commit.
See Table 26 for more information.
5.2.3.9. <discard-changes>
The <discard-changes> operation causes the <candidate> datastore to revert to match the <running> datastore and discard any uncommitted configuration changes.
To discard BOF configuration changes, the “bof” <configuration-region> must be specified within the <discard-changes> RPC. For example:
To discard LI configuration changes, the “li” <configuration-region> must be specified within the <discard-changes> RPC. For example:
The <discard-changes> RPC can only be used with LI configuration changes if all of the following conditions are true.
- The NETCONF user is a LI user.
- The NETCONF session has an exclusive lock on the LI configuration region and <candidate> datastore.
- The specified <configuration-region> is “li”.
- The YANG modules used are the Nokia SR OS YANG modules.
If any of the preceding conditions are false, SR OS returns an error.
See Table 26 for more information.
5.2.3.10. <validate>
The following is the list of supported :validate operations.
- The validate:1.1 and :validate:1.0 capabilities are advertised in the NETCONF server <hello> as the following:<capability>urn:ietf:params:netconf:capability:validate:1.0</capability><capability>urn:ietf:params:netconf:capability:validate:1.1</capability>
To validate BOF configurations, the “bof” <configuration-region> must be specified within the <validate> <source>. For example:
To validate LI configurations, the “li” <configuration-region> must be specified within the <validate> <source>. For example:
Alternatively, the <source> can be specified in the format of “configuration-region”-”datastore”. For example:
When both the <configuration-region> and the “configuration-region”-“datastore” format are used, SR OS applies the last tag used in the XML request. For example:
In the preceding example, the <validate> is used on the “li” <candidate> datastore.
See Table 26 for more information.
5.2.3.11. <get-schema>
A <get-schema> operation is supported for explicit schema retrieval using NETCONF. See NETCONF Monitoring for more information.
See Table 26 for more details.
5.2.3.12. <get-data>
A <get-data> operation is similar to the <get-config> operation. When applied to the <running/> or <candidate/> datastores, it returns the same data as the <get-config> operation. A <get-data> operation can be applied to the <intended/> datastore, whereas a <get-config> operation cannot be used on the <intended/> datastore.
See Table 26 for more details.
5.2.4. Datastore and Operation Combinations
Table 29 lists the operations supported by the Nokia modules and datastore combinations.
Table 29: Datastore and Nokia Modules Combinations
Operation | Nokia Modules | ||
<running> | <candidate> | <intended> | |
<edit-config> | ✓ | ||
<get-config> | ✓ | ✓ | |
<get-data> 1 | ✓ | ✓ | ✓ |
<get> 2 | ✓ 3 | ||
- The use of <get-data> and the intended datastore require nmda-support to be enabled.
- The <running> or <candidate> datastores are not applicable for a <get> operation.
- Retrieves both configuration and state data (XML format only).
Notes:
5.2.5. General NETCONF Behavior
Using Ctrl-c in a NETCONF session will immediately terminate the session.
The SR OS NETCONF implementation supports XML namespaces (xmlns).
If an invalid namespace is specified within the client hello message, no error will be returned because the NETCONF server is still waiting for the client to send a valid <hello/>. For further NETCONF requests (without sending a proper hello message), even though correct, SR OS returns an error indicating that “Common base capability not found.”
In the <rpc> element, the allowed XML namespaces are:
- standard NETCONF “urn:ietf:params:xml:ns:netconf:base:1.0” namespace
- Nokia SR OS namespaces; for example, “urn:nokia.com:sros:ns:yang:sr:conf” namespace or “urn:nokia.com:sros:ns:yang:sr:state” namespace
In the <rpc> element, prefixes are accepted and have to be specified with a valid URI. If an incorrect URI is declared with a prefix, SR OS detects the invalid URI and sends an <rpc-error> response.
If any other XML namespace is declared (or assigned to a prefix) in the <rpc> element, SR OS returns an error.
Any prefix declarations in the rest of the request are ignored and unused. The SR OS NETCONF server puts the correct NETCONF namespace declaration (“urn:ietf:params:xml:ns:netconf:base:1.0”) in all replies.
An <edit-config> request must specify which data model (for example, Nokia SR OS YANG modules) is being used in the top-level <configure> element.
- SR OS accepts a single namespace at the top-level <configure> element. For example:<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf"><system>....
- The NETCONF client can declare the namespaces with prefixes at the <rpc> element and use the corresponding prefixes later in the request message <configure/> block.
- SR OS returns an error if the request contains one or more incorrect namespaces.
The chunked framing mechanism is supported in addition to the EOM mechanism. As per RFC 6242, Section 4.1 - Framing Protocol, “[...] If the :base:1.1 capability is advertised by both peers, the chunked framing mechanism (see Section 4.2) is used for the remainder of the NETCONF session. Otherwise, the end-of-message-based mechanism is used.” See Example: Chunked Frame Mechanism for more information.
Handling of default data (for example, info vs info detail) uses the mechanisms described in RFC 6243. The SR OS NETCONF server supports the “explicit” method as the default for the Nokia SR OS YANG modules. It also supports the “report-all” method.
The advertised capability changes depending on which YANG modules are enabled or disabled in SR OS. For example, when Nokia modules are enabled and all other modules are disabled, the following capability is advertised:
<capability>urn:ietf:params:netconf:capability:with-defaults:1.0?basic-mode=explicit&also-supported=report-all</capability>
A debug system netconf info command can be used to dump NETCONF debug message streams. Note that in case of failure, the current logging levels do not mark the messages as errors or warnings.
5.2.5.1. Example: Multiple Use of Standard NETCONF Namespace
The following example shows the standard NETCONF namespace “urn:ietf:params:xml:ns:netconf:base:1.0” is used more than once in the <rpc> element:
In the following reply, the namespace is accepted and no error message is returned.
5.2.5.2. Example: Non-default NETCONF Base Namespace
The following example shows an allowed non-default NETCONF base namespace used in the <rpc> element.
In the following reply, a non-NETCONF base namespace is allowed and no error is returned.
5.2.5.3. Example: Invalid NETCONF Namespace Declaration
The following example shows an invalid NETCONF namespace declared in the <rpc> element.
In the following reply, SR OS returns an error.
5.2.5.4. Example: Non-default NETCONF Namespace or Prefix Declaration in a Child Tag
The following example shows a non-default NETCONF namespace or prefix declared in any child tag overriding the one declared under the <rpc> tag.
In the following reply, the non-standard NETCONF namspace or prefix used in the tag is ignored.
5.2.5.5. Example: Chunked Frame Mechanism
The following example shows a chunked message.
The following example shows the reply.
5.2.6. Establishing a NETCONF Session
The following example shows a client on a Linux PC initiating a connection to an SR OS NETCONF server. The SSH session must be invoked using an SSH subsystem (as recommended in RFC 6242).
The following example shows an exchange of hello messages, which include advertisement of capabilities.
From the SR OS server:
A NETCONF client can reply with a hello message as shown in either of the following:
5.2.6.1. Example: Checking NETCONF Status
The following example shows a <get-config> request on the <running> datastore that checks on whether NETCONF is shut down or not on the router.
The following example shows the reply.
5.2.6.2. Example: Retrieving System Configurations, QoS, and Log Branches
The following example shows a <get-config> request on the <candidate> datastore to get the full configurations of the system, QoS, and log branches.
The following example shows the reply.
5.2.6.3. Example: Creating an Epipe Service
The following example shows an <edit-config> request on the <candidate> datastore to create a basic Epipe service.
The following example shows the reply.
5.2.6.4. Example: Returning Multiple Errors
The following example shows SR OS returning multiple errors with the <commit>.
5.3. NETCONF Notifications
NETCONF notifications support is a standard IETF asynchronous notification delivery service for the NETCONF that is specified in RFC 5277.
The :notification capability and the :interleave capability are advertised in the SR OS NETCONF server <hello> as:
<capability>urn:ietf:params:netconf:capability:notification:1.0</capability> <capability>urn:ietf:params:netconf:capability:interleave:1.0</capability>
The following are characteristics of the NETCONF notifications capabilities supported in SR OS:
- The :notification capability allows the SR OS NETCONF server can process a subscription and send event notifications to the NETCONF client.
- The :interleave capability allows the SR OS NETCONF server supports receiving, processing, and responding to NETCONF requests on the same NETCONF session that has an active notification subscription.
- A NETCONF client needs to maintain an open NETCONF session with the NETCONF server in order to receive NETCONF notifications.
- A NETCONF client can send a <create-subscription> RPC to the SR OS NETCONF server to start receiving notification messages.
- If the SR OS NETCONF server can satisfy the request, SR OS sends an <OK> element within the <rpc-reply>.
- If the SR OS NETCONF server cannot satisfy the request, SR OS sends an <rpc-error> element within the <rpc-reply>.
- Subscriptions are nonpersistent and their lifetime is defined by their NETCONF session (not maintained with a router reboot).
- An optional parameter that can be defined for a <create-subscription> RPC is [stream]. The following are characteristics of the [stream] parameter:
- An event stream is a set of event notifications matching a specified forwarding criteria and available to the NETCONF clients for subscription.
- A NETCONF session can subscribe to only one stream at a time.
- One stream can be subscribed-to by many NETCONF sessions.
- The SR OS NETCONF server maintains one or more event streams.
- SR OS uses the SR OS event reporting framework for NETCONF notifications.
- A log-id can be configured to be a NETCONF stream. A “netconf-stream” exists for each log-id to assign a NETCONF "stream" name to the log-id. A netconf-stream is unique per SR OS device. The netconf-stream must be configured with “to netconf” for subscriptions to be accepted. If a netconf-stream is changed, active subscriptions to the changed NETCONF stream name are terminated by SR OS.
- There is one preconfigured stream with the netconf-stream set to “to netconf”, that is, log-id 101. It is used by default if the [stream] parameter is not specified. The preconfigured stream is modifiable but not deletable.
- Other streams can be configured using NETCONF or CLI. These streams are user-configured, which means that they are modifiable and can be deleted. A user-configured stream netconf-stream cannot be set to “to netconf” because “to netconf” is reserved for the preconfigured stream (that is, log-id 101).
- When a NETCONF client tries to subscribe to the SNMP log-id or a non-configured log-id, SR OS returns an error.
- SR OS supports a maximum number of 64 concurrent subscriptions to all streams.
- Notifications can be filtered out using a log-id “filter” or using base-op for create-subscriptions RPC.
- After the NETCONF server receives an SR OS event through a stream, a <notification> element is ready to be sent to all NETCONF sessions subscribed to that stream as per their filters.
- SR OS supports the following NETCONF notifications (see NETCONF Notification Examples for more information):
- sros-config-change-event: sent with every configuration change; that is, any new, deleted, or modified configuration
- sros-state-change-event: sent with every state change
- sros-command-accounting-event: sent to keep track of which user did what activity on the SR OS device
- sros-log-generic-event: contains the rest of the SR OS log events (except for the LI ones)
- netconf-config-change: A notification based on the model-driven configuration change log events, “mdConfigChange”, “mdOcConfigChange”, “mdBofConfigChange”, and “mdDebugConfigChange”. The notification is sent upon any configuration change that occurs in the running datastore by a model-driven management interface, using either the Nokia SR OS or OpenConfig data models, and in any configuration region except li (such as configure, bof, and debug). By default, the notification is disabled because all corresponding log events are also disabled by default. The notification uses the standard notification: netconf-config-change (as per RFC 6470) augmented with a value leaf.A single configuration change may involve editing more than one object (target). Each log event contains only a single object edit. As a result, only one object (target) edit can exist per netconf-config-change notification. Bundling of edits in a single netconf-config-change notification is not allowed.
- sros-md-rpc-accounting-event: A notification based on the NETCONF/gRPC local command accounting log events (the netconf_auth, netconf_unauth, grpc_auth, and grpc_unauth log events). This notification is sent upon receiving any RPC from a NETCONF/gRPC client. The NETCONF/gRPC local command accounting log events and NETCONF notification do not show the details of the configuration changes sent using the NETCONF/gRPC RPCs.
- SR OS supports the following LI NETCONF notifications:
- sros-li-config-change-event: Sent with every LI configuration change; that is, any new, deleted, or modified configuration
- sros-li-state-change-event: Sent with every LI state change
- sros-li-command-accounting-event: Sent to keep track of each LI user’s activities on the SR OS device
- sros-li-log-generic-event: Contains the remaining SR OS LI log events
- netconf-li-config-change: A notification based on the model-driven configuration change log event (the “mdLiConfigChange” log event). It is sent to the running datastore in the system for all configuration changes to a model-driven management interface. By default, this notification is enabled, because the log event is also enabled by default.
- sros-md-li-rpc-accounting-event: A notification based on the NETCONF/gRPC local command accounting LI log events (the netconf_auth, netconf_unauth, grpc_auth, and grpc_unauth log events). This notification is sent upon receiving any RPC from a NETCONF/gRPC client. The NETCONF/gRPC local command accounting LI log events and LI NETCONF notification do not show the details of the LI configuration changes sent using the RPCs.
In a <create-subscription>, a <filter> is an optional argument that is not supported by SR OS.
In a <create-subscription>, a <startTime> is an optional argument. This argument triggers the starting time of a replay. If it is not present, the subscription cannot be used to replay. A <startTime> cannot specify a time that is later than the current time (that is, in the future). SR OS supports timezones.
In a <create-subscription>, a <stopTime> is another optional argument. If this argument is not present, notifications continue to be sent until the subscription is terminated. A <stopTime> can specify a time that is later than the current time (that is, in the future). SR OS supports timezones.
A replay buffer is maintained by the SR OS server (per stream) and sorted by the order they were initially sent out (that is, by sequence-id, and not by timestamps).
- A replay request from the client causes stored events to be sent to the client for the specified time interval.
- A stream that supports replay is not expected to have an unlimited supply of saved notifications available to accommodate any replay request.
- The <startTime> and <stopTime> arguments specify when collections begin and end, respectively.
- A <replayComplete> notification is sent to indicate that all the replay notifications have been sent.
- If a <stopTime> was specified, the session then becomes a normal NETCONF session, and the NETCONF server accepts <rpc> operations. A <notificationComplete> notification is expected after the <replayComplete> if a <stopTime> was specified. The following is an example of a session with a <stopTime> specified:C S| || capability exchange ||-------------------------->||<------------------------->|| || <create-subscription> | (startTime,|-------------------------->| stopTime)|<--------------------------|| <rpc-reply> || || <notification> ||<--------------------------|| || <notification> ||<--------------------------|| <notification> | (replayComplete)|<--------------------------|| <notification> |(notificationComplete)|<--------------------------|| || || || <rpc> ||-------------------------->||<--------------------------|| <rpc-reply> || |
- If a <stopTime> was not specified, the session will continue to send notifications as they arise in the system. The following is an example of a session without a <stopTime> specified:C S| || capability exchange ||-------------------------->||<------------------------->|| || <create-subscription> | (startTime)|-------------------------->||<--------------------------|| <rpc-reply> || || <notification> ||<--------------------------|| || <notification> ||<--------------------------|| <notification> | (replayComplete)|<--------------------------|| || || || <notification> ||<--------------------------|| || || <notification> ||<--------------------------|| || |
- If neither <startTime> and <stopTime> arguments are present, no replay is present and notifications continue to be sent until the subscription is terminated.
5.3.1. NETCONF Notification Examples�
This section provides examples of NETCONF notifications.
5.3.1.1. Example: <create-subscription> Operation
The following example shows a create-subscription> operation.
The following examples show the reply.
5.3.1.2. Example: sros-config-change-event Notification
The following example shows an sros-config-change-event notification.
5.3.1.3. Example: sros-state-change-event Notification
The following example shows an sros-state-change-event notification.
5.3.1.4. Example: sros-cli-accounting-event Notification
The following example shows an sros-cli-accounting-event notification.
5.3.1.5. Example: sros-log-generic-event Notification
The following shows an sros-log-generic-event notification.
5.3.1.6. Example: netconf-config-change Notification
The following example shows a netconf-config-change notification.
5.3.1.7. Example: sros-md-rpc-accounting-event Notification�
The following example shows an sros-md-rpc-accounting-event notification.
5.4. NETCONF Monitoring
The :ietf-netconf-monitoring capability is advertised in the SR OS NETCONF server <hello> as:
<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring</capability>
The advertised capability provides information about the schemas supported by SR OS, which allows a NETCONF client to query and retrieve schema information from the SR OS NETCONF server.
SR OS supports the "/netconf-state/schemas" subtree only from the YANG model that is used to monitor the NETCONF protocol as per RFC 6022 (that is, ":ietf-netconf-monitoring" capability).
The data returned for a query of the /netconf-state/schemas path depends on the settings of the various commands in the yang-modules container.The following are examples.
- A "/netconf-state/schemas" path returns all supported Nokia models (modules and sub-modules) when the nokia-submodules parameter is set to true (or enabled).
- A "/netconf-state/schemas" path returns the supported combined Nokia (flat) models when the nokia-combined-modules parameter is set to true (or enabled).
- A "/netconf-state/schemas" path returns the ietf modules (for example, ietf-inet-types or ietf-yang-types) and the Nokia types in the returned list of schemas when either the nokia-submodules or nokia-combined-modules is set to true (or enabled).
The following example shows a request and the received response.
The following example shows the reply.
A <get-schema> operation is supported for explicit schema retrieval using NETCONF (YANG data models' discovery and download as per RFC 6022). The following parameters are supported:
- identifier: A mandatory string. Specifies an identifier for the schema list entry (YANG file). It can be the name of a module or a submodule.
- version: An optional string. Specifies a version of the schema requested (for example, YANG file). It represents the most recent YANG revision statement in a module or submodule. Empty string if no revision statement is present. As multiple versions may be supported by the NETCONF server, each version must be reported individually in the schema list (it can have the same identifier but different versions).
- format: An optional string. Specifies the data modeling language that the schema is written in. Default value is “yang” when not specified; “yang” shall be the only value supported if specified.
Unless the user intentionally specifies a schema path destination from which to acquire the YANG schema files, the software upgrade process manages the YANG schema files to ensure the schema files are synchronized with the software image on both the primary and standby CPM.
When an SR OS image boots (from bof primary-image), the associated YANG files shall match the image. If the primary SR OS image fails to boot and the secondary (or tertiary) SR OS image (from bof secondary-image or bof tertiary-image) loads, the YANG schema files associated with the loaded image shall be installed and available to the <get-schema> NETCONF RPC. It is recommended that each of the primary-image, secondary-image, and tertiary-image strings do not exceed 120 characters for the <get-schema> request to work properly with all schema files.
The configure system management-interface schema-path CLI command can be used to configure the schema path. See the schema-path command description in 7450 ESS, 7750 SR, 7950 XRS, and VSR Classic CLI Command Reference Guide for more information. If schema-path is configured, all the YANG files must be manually copied to the specified schema-path URL prior to using the <get-schema> RPC successfully.
When the requested schema does not exist, the <error-tag> returned is "invalid-value". The maximum length of a schema path URL is 180 characters, however, Nokia recommends that a URL string be less than or equal to 135 characters, to guarantee that a <get-schema> will work properly with the longest YANG module name in SR OS.
When more than one schema matches the requested parameters, the <error-tag> returned is "operation-failed".
The following example shows a <get-schema> request.
The following example shows the reply.
5.5. YANG Library
SR OS supports a mechanism, a YANG library, to identify the YANG modules and submodules that are implemented by the NETCONF server. NETCONF clients should be able to query or cache the YANG library contents and identify whether their cache is out-of-date.
The SR OS NETCONF server supports the “/yang-library” state model and advertises the following capability in the <hello> message (in accordance with RFC 8525):
The following is the YANG tree diagram for the “/yang-library”model:
The SR OS NETCONF server advertises the following capability in the <hello> message:
The following is the YANG tree diagram for the modules-state model:
The module-set-id is a mandatory leaf that identifies a set of YANG modules that the SR OS NETCONF server supports. The value of this leaf changes whenever there is a change in the set of modules or submodules in the YANG library. When this change occurs, SR OS changes the module-set-id value advertised in the NETCONF server <hello> message.
The modules-state can be used by the NETCONF client to fetch the YANG library, cache it, and re-fetch it only if the value of the module-set-id changes again. The YANG library is returned in the module list.
Example
If the SR OS NETCONF server advertises the following capability, the NETCONF client can use the advertised module-set-id to query the YANG library:
The following example shows the NETCONF client using the advertised module-set-id to query the YANG library.
The following example shows the reply.
5.6. Operational Commands via NETCONF
Operational commands (for example, admin reboot, file remove) are supported via NETCONF using:
- individually modeled YANG-based operations
- md-cli-raw-command
Nokia recommends using an individually modeled YANG operation, if it is available for a specific operation, instead of the md-cli-raw-command. The individually modeled YANG-based operations are useful for operations that have specific results data in the output (providing fully modeled and structured output). The md-cli-raw-command is available for all SR OS operations but requires string parsing of the output for commands with results data.
Individually modeled operations that are supported over NETCONF can be viewed in the nokia-oper-*.yang files in the YANG distribution of a specific software release.
5.6.1. Individually Modeled YANG-based Operations
Some operations are modeled using a YANG “action” statement per operation. These can be viewed in the nokia-oper-*.yang files.
The commands in the YANG operations models are invoked via NETCONF using the "action" RPC, as described in section 7.15 of RFC 7950.
For more information, see YANG-based Operations.
The following is an example that shows a request to create a new directory on CF1:
The following is an example output that shows the reply for a successful directory creation operation.
The following is an example that shows a CPM synchronize operation request.
The following is an example that shows the reply when the CPM synchronize operation fails.
5.6.2. NETCONF Operations Using the md-cli-raw-command Request
The md-cli-raw-command request allows a NETCONF client to execute a wide set of operations on the SR OS router.
The command input string accepts a command in the exact format as it would be entered in the MD-CLI. For example:
Other examples of commands that can be used as input strings include:
- admin reboot now
- clear router Base interface system statistics
- file list cf1:
- oam eth-cfm loopback 28 md-admin-name "14" ma-admin-name "200" mep-id 32 send-count 5 interval 10
- ping 10.10.10.2
- show system information
- tools dump resource-usage
- tools perform cflowd manual-export
- traceroute 192.168.10.1
- //debug router ldp interface foo
The SR OS NETCONF server workflow to process the md-cli-raw-command request is the following.
- Open a new temporary MD-CLI session (with the same username as the NETCONF session).
- Pass the input command to the MD-CLI engine.
- Return the MD-CLI output to the NETCONF client as an unstructured block of text in the <rpc-reply> message.
The MD-CLI context for the operation is the root and the MD-CLI executes the command in operational mode, which is similar to a user newly logged into an MD-CLI session.
Interactive commands, or commands that prompt for input, are not supported and result in an error. For example, using “admin reboot” as an input string fails. Using “admin reboot now” is accepted. Other examples of interactive commands that are not supported include:
- enable
- password
- ssh
- telnet
The cli-engine command controls the engines allowed to process the input. Since the starting context for any md-cli-raw-command is the root of the MD-CLI engine, any configuration value that does not allow md-cli access causes md-cli-raw-command requests to fail. Access to classic CLI commands through the md-cli-raw-command (for example, commands starting with “//”) requires access to both md-cli and classic-cli. Changes to the cli-engine configuration only take effect on raw-md-cli-command in NETCONF sessions that are started after the cli-engine configuration was changed.
Only a single operation is supported as the input to the md-cli-raw-command request. Multiple operations require multiple NETCONF RPCs.
The md-cli-raw-command request is not intended as a mechanism to read structured state data or to manage basic configuration. The YANG-modeled configuration and state data are managed and accessed using standard NETCONF operations, such as <edit-config>, <get-config>, and <get>.
The following MD-CLI commands and similar commands are not supported as input strings for md-cli-raw-command:
- admin show configuration
- bof
- configure
- debug
- edit-config
- environment
- exec
- history
- info
- li
- logout
- pyexec (when invoked from the pySROS Python 3 libraries)
- //admin display-config
- //admin compare
- //admin rollback
- //admin view
- //bof
- //candidate
- //configure
- //environment
- //exec
- //history
- //logout
Unstructured state information can be retrieved using md-cli-raw-command, for example, with show or tools dump commands as the input string. The output returned, however, is an unstructured block of text. Structured state information can be retrieved using the standard NETCONF <get> operation.