NETCONF
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). NETCONF RPC request shows a NETCONF RPC request.
NETCONF can be conceptually partitioned into four layers as described in RFC 6241. NETCONF layers (RFC 6241) shows the NETCONF layers.
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 YANG-modeled operations)
The SR OS NETCONF server supports both the base:1.1 capability and the base:1.0 capability.
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 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. You must configure the access netconf statement in the local user record. Also, NETCONF runs over SSH, and SSH supports RADIUS/TACACS+ user authentication.
- RADIUS
Use the following command to enable access netconf in the user template:
- MD-CLI
configure system security aaa user-template user-template-name radius-default - classic
CLI
configure system security user-template radius_default
Use the following command to enable use-default-template:
- MD-CLI
configure system security aaa remote-servers radius use-default-template - classic
CLI
configure system security radius use-default-template
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".
- MD-CLI
- TACACS+
Use the following command to enable access tacplus in the user template:
- MD-CLI
configure system security aaa user-template user-template-name tacplus-default - classic
CLI
configure system security user-template tacplus_default
Use the following command to enable use-default-template:
- MD-CLI
configure system security aaa remote-servers tacplus use-default-template - classic
CLI
configure system security tacplus use-default-template
- 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.
Datastores and URLs
SR OS supports several datastores, including the following standard datastores:
-
<running>
-
<candidate>
-
<startup>
-
<intended>
-
<operational>
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.
- <intended>
- <operational>
The :candidate capability is advertised in the SR OS NETCONF server <hello> as:
<capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>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 representation of the configuration after configuration transformations (such as configuration group expansion) to the <running> datastore are performed.
The <operational> datastore is a read-only representation of the elements the SR OS is using. This includes all configuration (including configuration transformations) and all state information.
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:
<capability>urn:ietf:params:netconf:capability:startup:1.0</capability>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:
<capability>urn:ietf:params:netconf:capability:url:1.0?scheme=ftp,tftp,file</capability>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>
BOF (Boot Options File) is a separate configuration region, which can be configured over NETCONF 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, which can be configured over NETCONF using the Nokia SR OS YANG models (including configuring any LI log-ids needed to subscribe to and receive LI NETCONF notifications). The same user permissions apply using NETCONF as with MD-CLI (that is, only LI users can access LI data).
Operational datastore
The <operational> datastore is a read-only representation of the elements that the SR OS is using. This includes all configuration (including configuration transformations) and all state information.
The <operational> datastore is only accessible over NETCONF and requires that NMDA support is enabled. To obtain <operational> datastore information, use the <get-data> RPC.
Obtaining information from the <operational> datastore using the <get-data> RPC
<rpc message-id="example" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda" xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
<datastore>ds:operational</datastore>
</get-data>
</rpc>
The <get-data> RPC performed on the <operational> datastore can be extended with the with-origin option to detail the origin of each configuration node, excluding non-presence containers.
The following rules define the origin:
- YANG non-presence containers do not have an origin.
- The origin for system-provisioned YANG lists that were not explicitly configured and for YANG leafs in these lists is system.
- The origin for explicitly configured YANG containers, lists, and leafs (visible in MD-CLI using the info intended command) is intended.
- The origin for YANG containers, lists, and leafs that are not system-provisioned and not explicitly configured is default.
<get-data> RPC usage with the with-origin option
<rpc message-id="example" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda" xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
<datastore>ds:operational</datastore>
<with-origin/>
</get-data>
</rpc>
NETCONF operations and capabilities
Each RPC request can only contain one operation. The following table summarizes the protocol operations and capabilities supported on the 7450 ESS, 7750 SR, and 7950 XRS.
| Support | Capabilities | Operations |
|---|---|---|
|
Base Protocol Operations |
— |
|
|
RFC 62411 |
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 |
The following table lists the supported NETCONF operations and arguments.
| Operation | Arguments |
|---|---|
|
get-config |
source/[configuration-region] [filter] [format] |
|
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] [format] |
|
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] [format] [with-origin] |
|
action |
(2) |
The following table lists protocol operations and level of support in SR OS NETCONF servers, and limitations, if any, in the current implementation.
| Protocol operation | Example | Supported | Notes |
|---|---|---|---|
|
get-config |
|
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. |
|
No |
— |
|
|
Yes |
— |
|
|
No |
— |
|
|
No |
— |
|
|
Yes |
A <filter> is an optional argument. All subtree filters are supported in SR OS except for ‟attribute match expressions”. |
|
|
No |
— |
|
|
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 |
|
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. |
|
Yes |
A <filter> is an optional argument. Subtree filters are supported except for "attribute match expressions". |
|
|
No |
— |
|
|
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 |
|
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. |
|
No |
— |
|
|
No |
— |
|
|
Yes |
— |
|
|
Yes |
Default |
|
|
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”. |
|
|
Yes |
— |
|
|
Yes |
— |
|
|
Yes |
— |
|
|
Yes |
— |
|
|
No |
— |
|
|
Yes |
— |
|
|
Yes |
Default. This can be specified but, starting in Release 20.2.R1, behaves the same as a rollback-on-error. |
|
|
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 |
|
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 |
|
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 netconf auto-config-save is configured, in classic CLI in the configure system context and in MD-CLI in the system management-interface context. To use the commit operation, the user must belong to a NETCONF system security profile with commit enabled for the base-op-authorization. |
|
Yes |
Optional. Specifies a comment in the commit history. |
|
|
Yes |
Optional. Can only be used with non-li configurations. |
|
|
Yes |
Optional. Can only be used with non-li configurations. |
|
|
Yes |
Optional. Can only be used with non-li configurations. |
|
|
Yes |
Optional. Can only be used with non-li configurations. |
|
|
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 |
|
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. |
|
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 |
|
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. |
|
No |
The running datastore cannot be a <target> for a <copy-config>. |
|
|
No |
Use <discard-changes>. |
|
|
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. |
|
|
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. |
|
|
Yes |
— |
|
|
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. |
|
|
No |
— |
|
|
Yes |
— |
|
|
Yes |
— |
|
|
No |
Use <commit> instead. |
|
|
No |
— |
|
|
Yes |
Supported in model-driven configuration mode only. |
|
|
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. |
|
|
Yes |
Supported if both source and target are not remote URLs. |
|
|
No |
— |
|
|
Yes |
— |
|
|
Yes |
— |
|
|
Yes |
— |
|
|
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. |
|
|
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 |
|
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 |
|
Yes |
Only a NETCONF user that belongs to a profile with base-op-authorization/lock enabled, can lock a datastore. |
|
Yes |
Locking the <candidate> datastore implicitly locks both the <running> and <candidate> datastores. |
|
|
Yes |
Locking the <running> datastore locks both the <running> and <candidate> datastores. |
|
|
No |
— |
|
|
No |
— |
|
|
Yes |
Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. |
|
|
unlock |
|
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:
Upon unlocking/disconnecting a NETCONF session that had acquired a
datastore lock, SR OS:
|
|
Yes |
— |
|
|
Yes |
— |
|
|
No |
— |
|
|
No |
— |
|
|
Yes |
Optional. Specify "li", "bof" or "configure". Default, if not specified, is "configure". Can only be used with the Nokia SR OS modules. |
|
|
validate |
|
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. |
|
Yes |
— |
|
|
Yes |
— |
|
|
No |
— |
|
|
No |
— |
|
|
No |
— |
|
|
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 |
|
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. |
|
Yes |
— |
|
|
Yes |
— |
|
|
No |
— |
|
|
No |
— |
|
|
discard-changes |
|
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. |
|
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 |
|
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. |
|
Yes |
Optional |
|
|
Yes |
Optional |
|
|
Yes |
Optional |
|
|
No |
Optional |
|
|
get-schema |
|
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. |
|
Yes |
Mandatory |
|
|
Yes |
Optional |
|
|
Yes |
Optional |
|
|
get-data |
|
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. |
|
Yes |
Mandatory. The ‟startup” cannot be used. |
|
|
Yes |
Optional |
|
|
Yes |
Optional |
|
|
No |
Optional |
|
|
No |
Optional |
|
|
Yes |
Optional. To use this option the datastore must be "operational". |
|
|
Yes |
Optional |
|
|
No |
Optional |
|
|
Yes |
Optional. Default if not specified is "configure". Can be "li" or "configure". Can only be used with the Nokia SR OS modules. |
|
|
action |
(2) |
<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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<configuration-region>bof</configuration-region>
<filter>
<bof xmlns="urn:nokia.com:sros:ns:yang:sr:bof-conf">
</bof>
</filter>
</get>
</rpc>
]]>]]>
To retrieve LI configurations, the ‟li” <configuration-region> must be specified within the <get> RPC. For example:
<get>
<configuration-region>li</configuration-region>
<filter>
<li xmlns="urn:nokia.com:sros:ns:yang:sr:li-conf">
</li>
</filter>
</get>
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 Protocol operations and level of support in Nokia SR OS NETCONF servers 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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
<system>
<name nokia-attr:comment="This is a comment on the system name."> node2</name>
</system>
</configure>
</data>
</rpc-reply>
The optional proprietary <format> argument is supported. See Output format selection for more information.
See the following sections for examples of <get> request and response messages:
Namespace specified in <configure> tag
The following example shows a <configure> tag that contains a namespace.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
</configure>
</filter>
</get>
</rpc>
]]>]]>
The following example shows the reply, which returns no errors.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
</configure>
</data>
</rpc-reply>
]]>]]>
Namespace error in <configure> tag
The following example shows a <configure> tag that does not contain a namespace.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<configure>
<python xmlns="urn:nokia.com:sros:ns:yang:sr:conf-python">
</python>
</configure>
</filter>
</get>
</rpc>
]]>]]>
The following example shows the reply, which returns SR OS errors.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>protocol</error-type>
<error-tag>bad-element</error-tag>
<error-severity>error</error-severity>
<error-message>
Element is not valid in the specified context.
</error-message>
<error-info>
<bad-element>configure</bad-element>
</error-info>
</rpc-error>
</rpc-reply>
]]>]]>
Namespace specified in <state> tag
The following example shows a <state> tag that contains a namespace.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<state xmlns="urn:nokia.com:sros:ns:yang:sr:state">
</state>
</filter>
</get>
</rpc>
]]>]]>
The following example shows the reply, which returns no errors.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<state xmlns="urn:nokia.com:sros:ns:yang:sr:state">
...
...
</state>
</data>
</rpc-reply>
]]>]]>
Namespace error in <state> tag
The following example shows a <state> tag that does not contain a namespace.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<state>
</state>
</filter>
</get>
</rpc>
]]>]]>
The following example shows the reply, which returns errors.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>protocol</error-type>
<error-tag>bad-element</error-tag>
<error-severity>error</error-severity>
<error-message>
Element is not valid in the specified context.
</error-message>
<error-info>
<bad-element>state</bad-element>
</error-info>
</rpc-error>
</rpc-reply>
]]>]]>
Output format tag
The following example shows the <get> operation combined with a subtree filter and requests the output in the MD-CLI format.
MD-CLI format
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<get>
<format>md-cli</format>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<management-interface>
<netconf/>
</management-interface>
</system>
</configure>
</filter>
</get>
</rpc>
]]>]]>
The following example shows the reply.
MD-CLI format reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<data>
configure {
system {
management-interface {
netconf {
admin-state enable
auto-config-save true
capabilities {
candidate true
writable-running false
}
}
}
}
}
</data>
</rpc-reply>
]]>]]>
The following example shows the <get> operation combined with a subtree filter and requests the output in the JSON (IETF) format.
JSON (IETF) format
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<get>
<format>json</format>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<management-interface>
<netconf/>
</management-interface>
</system>
</configure>
</filter>
</get>
</rpc>
]]>]]>
The following example shows the reply.
JSON (IETF) format reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<data>
{
"nokia-conf:configure": {
"system": {
"management-interface": {
"netconf": {
"admin-state": "enable",
"auto-config-save": true,
"capabilities": {
"candidate": true,
"writable-running": false
}
}
}
}
}
}
</data>
</rpc-reply>
]]>]]>
<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 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 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 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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<configuration-region>bof</configuration-region>
<running/>
</source>
<filter>
<bof xmlns="urn:nokia.com:sros:ns:yang:sr:bof-conf">
</bof>
</filter>
</get-config>
</rpc>
]]>]]>
To retrieve LI configurations, the ‟li” <configuration-region> must be specified within the <get-config> <source>. For example:
<get-config>
<source>
<configuration-region>li</configuration-region>
<candidate/>
</source>
<filter>
…
</filter>
</get-config>
Alternatively, the <source> can be specified in the format of ‟configuration-region”-”datastore”. For example:
<get-config>
<source>
<li-candidate/>
</source>
<filter>
…
</filter>
</get-config>
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:
<get-config>
<source>
<configuration-region>configure</configuration-region>
<li-candidate/>
</source>
<filter>
…
</filter>
</get-config>
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 Protocol operations and level of support in Nokia SR OS NETCONF servers 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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
<system>
<name nokia-attr:comment="This is a comment on the system name."> node2</name>
</system>
</configure>
</data>
</rpc-reply>
The optional proprietary <format> argument is supported. See Output format selection for more information.
The following sections contain examples of <get-config> request and response messages.
Reply with defaults
The following example shows the use of <with-defaults> with a value of "report-all".
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<candidate/>
</source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<security>
<cpm-filter>
<ipv6-filter>
</ipv6-filter>
</cpm-filter>
</security>
</system>
</configure>
</filter>
<with-defaults xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults">
report-all
</with-defaults>
</get-config>
</rpc>
]]>]]>
The following example shows the reply, which returns all attributes, even those with default values.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
<system>
<security>
<cpm-filter>
<ipv6-filter>
<admin-state>disable</admin-state>
</ipv6-filter>
</cpm-filter>
</security>
</system>
</configure>
</data>
</rpc-reply>
]]>]]>
Reply without default values
The following example shows a <get-config> request using <with-defaults>.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<candidate/>
</source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<security>
<cpm-filter>
<ipv6-filter>
</ipv6-filter>
</cpm-filter>
</security>
</system>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
The following output shows the reply, which does not return attributes with default values.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<candidate/>
</source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<security>
<cpm-filter>
<ipv6-filter>
</ipv6-filter>
</cpm-filter>
</security>
</system>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
Containment node
The following example shows a containment node.
<?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>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router/>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
List without a key specified
The following example shows a selection node that is a list and does not have a key specified.
<?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>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<interface>
</interface>
</router>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
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.
<?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>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<interface>
<admin-state/>
</interface>
</router>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
Non-key leaf specified as a content match node
The following example shows a non-key leaf specified as a content match node.
<?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>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<interface>
<admin-state>disable</admin-state>
</interface>
</router>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
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.
<?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>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<interface>
<interface-name>Test</interface-name>
</interface>
</router>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
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.
<?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>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source><candidate/></source>
</get-config>
</rpc>
]]>]]>
The following example shows a content match node on a lead-list when only the <configure> tag is present inside the <filter> tag.
<?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>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf"/>
</filter>
</get-config>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source><candidate/></source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf"/>
</filter>
</get-config>
</rpc>
]]>]]>
Output format tag
The following example shows the <get-config> operation combined with a subtree filter and requests the output in the MD-CLI format.
MD-CLI format
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<get-config>
<format>md-cli</format>
<source><running/></source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<management-interface>
<netconf/>
</management-interface>
</system>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
The following example shows the reply.
MD-CLI format reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<data>
configure {
system {
management-interface {
netconf {
admin-state enable
auto-config-save true
capabilities {
candidate true
writable-running false
}
}
}
}
}
</data>
</rpc-reply>
]]>]]>
The following example shows the <get-config> operation combined with a subtree filter and requests the output in the JSON (IETF) format.
JSON (IETF) format
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<get-config>
<format>json</format>
<source><running/></source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<management-interface>
<netconf/>
</management-interface>
</system>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
The following example shows the reply.
JSON (IETF) format reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<data>
{
"nokia-conf:configure": {
"system": {
"management-interface": {
"netconf": {
"admin-state": "enable",
"auto-config-save": true,
"capabilities": {
"candidate": true,
"writable-running": false
}
}
}
}
}
}
</data>
</rpc-reply>
<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 <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 is linked 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. On 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 is linked 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. On 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, results 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 Application of default operation value for parent and child nodes and 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:
Create
Create/Merge: SR OS processes the request, which succeeds or fails based on the behavior of this operation.
Delete/Remove: SR OS returns an error.
Merge
Create/Merge/Delete/Remove: SR OS processes the request, which succeeds or fails based on the behavior of this operation.
Delete/Remove
Create/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.
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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<configuration-region>bof</configuration-region>
<candidate/>
</target>
<config>
<bof xmlns="urn:nokia.com:sros:ns:yang:sr:bof-conf">
<console>
<wait-time>5</wait-time>
</console>
</bof>
</config>
</edit-config>
</rpc>
]]>]]>
To edit LI configurations, the ‟li” <configuration-region> must be specified within the <edit-config> <target>. For example:
<edit-config>
<target>
<configuration-region>li</configuration-region>
<candidate/>
</target>
<config>
<!-- place LI configuration changes here -->
</config>
</edit-config>
Alternatively, the <target> can be specified in the format of ‟configuration-region”-”datastore”. For example:
<edit-config>
<target>
<li-candidate/>
</target>
<config>
<!-- place LI configuration changes here -->
</config>
</edit-config>
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:
<edit-config>
<target>
<configuration-region>configure</configuration-region>
<li-candidate/>
</target>
<config>
<!-- place LI configuration changes here -->
</config>
</edit-config>
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 Protocol operations and level of support in Nokia SR OS NETCONF servers 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:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/></target>
<config>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
<system>
<name nokia-attr:comment="This is a comment on the system name."> node2</name>
</system>
</configure>
</config>
</edit-config>
</rpc>
]]>]]>
See the following sections for examples of <edit-config> request and response messages:
<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.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><running/></target>
<config>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<python>
<python-script>
<script-name>testing</script-name>
</python-script>
</python>
</configure>
</config>
</edit-config>
</rpc>
]]>]]>
The following example shows the reply, which returns SR OS errors.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>protocol</error-type>
<error-tag>operation-not-supported</error-tag>
<error-severity>error</error-severity>
<error-message>
writable-running capability is not supported
</error-message>
<error-info>
<bad-element>running</bad-element>
</error-info>
</rpc-error>
</rpc-reply>
]]>]]>
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.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/></target>
<config>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<service>
<epipe>
<service-name>CustDoc</service-name>
<customer>1</customer>
<description>Local epipe</description>
</epipe>
</service>
</configure>
</config>
</edit-config>
</rpc>
]]>]]>
The following example shows the reply.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]>]]>
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”).
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/></target>
<config>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<service>
<epipe>
<service-name>CustDoc</service-name>
<customer>1</customer>
<description operation="remove">Local epipe</description>
</epipe>
</service>
</configure>
</config>
</edit-config>
</rpc>
]]>]]>
The following example shows the reply.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]>]]>
<copy-config>
To <copy-config> BOF configurations, the ‟bof” <configuration-region> must be specified within the <copy-config> RPC <source> and <target>. For example:
<?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>
<configuration-region>bof</configuration-region>
<startup/>
</target>
<source>
<configuration-region>bof</configuration-region>
<running/>
</source>
</copy-config>
</rpc>
]]>]]>
When <copy-config> RPC is used with the ‟bof” <configuration-region>, only the following combinations are supported:
<source>config</source> and <target>candidate</target>
-
<source>running</source> and <target>startup</target>
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:
<copy-config>
<target>
<configuration-region>li</configuration-region>
<startup/>
</target>
<source>
<configuration-region>li</configuration-region>
<running/>
</source>
</copy-config>
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:
<copy-config>
<target><li-startup/></target>
<source><li-running/></source>
</copy-config>
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:
<copy-config>
<target>
<configuration-region>configure</configuration-region>
<li-startup/>
</target>
<source>
<configuration-region>configure</configuration-region>
<li-running/>
</source>
</copy-config>
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 Protocol operations and level of support in Nokia SR OS NETCONF servers for more details.
<delete-config>
See Protocol operations and level of support in Nokia SR OS NETCONF servers for more details.
<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
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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<configuration-region>bof</configuration-region>
<candidate/>
</target>
</lock>
</rpc>
]]>]]>
To lock an LI datastore, the ‟li” <configuration-region> must be specified within the <lock> <target>. For example:
<lock>
<target>
<configuration-region>li</configuration-region>
<candidate/>
</target>
</lock>
Alternatively, the <target> can be specified in the format of ‟configuration-region”-”datastore”. For example:
<lock>
<target>
<li-candidate/>
</target>
</lock>
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:
<lock>
<target>
<configuration-region>configure</configuration-region>
<li-candidate/>
</target>
</lock>
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 Protocol operations and level of support in Nokia SR OS NETCONF servers for more details.
<unlock>
Because there is a single lock per datastore, regardless of the scope of that lock, the following restrictions 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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock>
<target>
<configuration-region>bof</configuration-region>
<candidate/>
</target>
</unlock>
</rpc>
]]>]]>
To unlock an LI datastore, the ‟li” <configuration-region> must be specified within the <unlock> <target>. For example:
<unlock>
<target>
<configuration-region>li</configuration-region>
<candidate/>
</target>
</unlock>
Alternatively, the <target> can be specified in the format of ‟configuration-region”-”datastore”. For example:
<unlock>
<target>
<li-candidate/>
</target>
</unlock>
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:
<unlock>
<target>
<configuration-region>configure</configuration-region>
<li-candidate/>
</target>
</unlock>
In the preceding example, the <unlock> is used to unlock the ‟li” <candidate> datastore.
See Protocol operations and level of support in Nokia SR OS NETCONF servers for more information.
<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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<configuration-region>bof</configuration-region>
</commit>
</rpc>
]]>]]>
To commit LI configurations, the ‟li” <configuration-region> must be specified within the <commit> RPC. For example:
<commit>
<configuration-region>li</configuration-region>
</commit>
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.
Parameters for a <commit> operation lists the supported parameters for a <commit> operation.
Table 5. 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 Protocol operations and level of support in Nokia SR OS NETCONF servers for more information.
<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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<discard-changes>
<configuration-region>bof</configuration-region>
</discard-changes>
</rpc>
]]>]]>
To discard LI configuration changes, the ‟li” <configuration-region> must be specified within the <discard-changes> RPC. For example:
<discard-changes>
<configuration-region>li</configuration-region>
</discard-changes>
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 Protocol operations and level of support in Nokia SR OS NETCONF servers for more information.
<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:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate>
<source>
<configuration-region>bof</configuration-region>
<candidate/>
</source>
</validate>
</rpc>
]]>]]>
To validate LI configurations, the ‟li” <configuration-region> must be specified within the <validate> <source>. For example:
<validate>
<source>
<configuration-region>li</configuration-region>
<candidate/>
</source>
</validate>
Alternatively, the <source> can be specified in the format of ‟configuration-region”-”datastore”. For example:
<validate>
<source>
<li-candidate/>
</source>
</validate>
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:
<validate>
<source>
<configuration-region>configure</configuration-region>
<li-candidate/>
</source>
</validate>
In the preceding example, the <validate> is used on the ‟li” <candidate> datastore.
See Protocol operations and level of support in Nokia SR OS NETCONF servers for more information.
<get-schema>
A <get-schema> operation is supported for explicit schema retrieval using NETCONF. See NETCONF monitoring for more information.
See Protocol operations and level of support in Nokia SR OS NETCONF servers for more details.
<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 Protocol operations and level of support in Nokia SR OS NETCONF servers for more details.
The optional proprietary <format> argument is supported. See Output format selection for more information.
See Output format tag for an example of <get-data> request and response messages.
Output format tag
The following example shows the <get-data> operation combined with a subtree filter and requests the output in the MD-CLI format.
MD-CLI format
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<get-data>
<format>md-cli</format>
<datastore>running</datastore>
<subtree-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda">
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<management-interface>
<netconf/>
</management-interface>
</system>
</configure>
</subtree-filter>
</get-data>
</rpc>
]]>]]>
The following example shows the reply.
MD-CLI format reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<data>
configure {
system {
management-interface {
netconf {
admin-state enable
auto-config-save true
capabilities {
candidate true
writable-running false
}
}
}
}
}
</data>
</rpc-reply>
]]>]]>
The following example shows the <get-data> operation combined with a subtree filter and requests the output in the JSON (IETF) format.
JSON (IETF) format
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<get-data>
<format>json</format>
<datastore>running</datastore>
<subtree-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda">
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<management-interface>
<netconf/>
</management-interface>
</system>
</configure>
</subtree-filter>
</get-data>
</rpc>
]]>]]>
The following example shows the reply.
JSON (IETF) format reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<data>
{
"nokia-conf:configure": {
"system": {
"management-interface": {
"netconf": {
"admin-state": "enable",
"auto-config-save": true,
"capabilities": {
"candidate": true,
"writable-running": false
}
}
}
}
}
}
</data>
</rpc-reply>
]]>]]>
Datastore and operation combinations
The following table lists the operations supported by the datastores.
| Operation | Datastore | |||
|---|---|---|---|---|
| <running> | <candidate> | <intended> | <operational> | |
|
<edit-config> |
✓ | |||
|
<get-config> |
✓ | ✓ | ||
|
<get-data>3 |
✓ | ✓ | ✓ | ✓ |
The <get> RPC returns data that has the config field set to false in the YANG model, and data from the <running> datastore that has the config field set to true in the YANG model.
Output format selection
The SR OS NETCONF implementation provides an optional proprietary <format> argument for the <get>, <get-config>, and <get-data> NETCONF operations and the <md-compare> YANG-modeled operation.
The <format> argument allows the operator to display the resultant data in either the XML (default), JSON IETF, or MD-CLI format.
The supported options for the <format> argument are as follows:
- xml
- json
- md-cli
The supported options for the <format> argument are as follows for the <md-compare> YANG-modeled operation:
- xml
- md-cli
Private candidates over NETCONF
The SR OS NETCONF implementation provides a proprietary function to operate a specific NETCONF session in private candidate mode. This provides the ability for NETCONF (and CLI) sessions to cohabit with minimal disruption to each other because the sessions often configure entirely separate sections of the overall device configuration.
Setting up, configuring, and discarding private candidates
Sending the urn:nokia.com:nc:pc client capability from the NETCONF
client to the NETCONF server in the <hello> message establishes the private
candidate mode. The private candidate mode applies for the duration of a specific
NETCONF session. The following example shows how to send the client capability.
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
<capability>urn:nokia.com:nc:pc</capability>
</capabilities>
</hello>
]]>]]>The server sends no specific response to the <hello> message. From this point on, the session is in private candidate mode.
Private candidate mode operates in the same way as the default global candidate mode in many respects. Most of the RPCs and NETCONF operations that can be used remain the same.
Whenever a NETCONF operation references the candidate configuration datastore, a private candidate configuration is used. The system creates a private candidate configuration as a copy of the running configuration when the first RPC that requires a candidate configuration is used. The system also creates a baseline candidate configuration at this point. The baseline candidate configuration acts as a reference for identifying changes that the NETCONF client has made in the private candidate.
The following RPCs do not require a candidate and therefore do not trigger the creation of a candidate:
- <get-schema>
- <validate> when used without specifying a source configuration datastore
- any <action> RPC that does not require a candidate configuration
Every NETCONF session running in private candidate mode has its own private candidate configuration. If multiple NETCONF clients are used to configure specific sections of the configuration, the private candidate mode provides improvements in performance and operation because of the ability to edit configuration changes without locking the candidate configuration datastore.
See "Candidate configuration modes" in the 7450 ESS, 7750 SR, 7950 XRS, and VSR MD-CLI User Guide for more information.
When a configuration is edited over NETCONF in the private candidate, MD-CLI users do not see these configuration changes in the global candidate configuration datastore as these changes are in the private candidate belonging to the specific NETCONF session.
When a NETCONF session running in private candidate mode sends a <commit> RPC, the SR OS node performs an update and subsequently a commit operation. See " Multiple simultaneous candidate configurations" in the 7450 ESS, 7750 SR, 7950 XRS, and VSR MD-CLI User Guide for more information.
In the unlikely event that a collision in the configuration occurs because other users configure the same area of the configuration at the same time, the update operation in this process fails and therefore the <commit> RPC also fails. This update failure ensures the following:
- The user is aware of the conflict.
- The integrity of the operational configuration on the node remains intact.
- No unintended configuration changes resulting from any other users' input are made.
If the <commit> RPC fails for the above reason, sending the <commit> again may resolve the issue. If the issue is not resolved, the session must be restarted.
The <commit> RPC over a NETCONF session running in private candidate mode does not accept the persist-id option.
Closing a private candidate NETCONF session, either through disconnection or the <close-session> operation, discards the private candidate and all uncommitted configuration changes.
Locking private candidates in NETCONF
When using the private candidate mode over NETCONF, it is less likely that the candidate configuration needs to be locked. There can still be specific operational situations where the operator wants to use the private candidate functionality and temporarily restrict all other users from changing the node’s running configuration.
In this case, the operator can use the <lock> RPC as they would in the usual operating mode for NETCONF.
If an operator issues the <lock> RPC, the following applies:
- The private candidate configuration is promoted to a private-exclusive candidate configuration within SR OS.
- Any configuration changes that exist in the operator’s private candidate are retained.
- No other users on the SR OS node can commit any configuration changes.
When the operator who issued the <lock> RPC wants to allow others users to commit configuration changes again, the operator issues the <unlock> RPC.
If the operator issues the <unlock> RPC, the following applies:
- The other users get the rights to commit configuration changes again.
- Any uncommitted configuration changes in the private-exclusive candidate configuration are retained.
- The operator's private-exclusive candidate configuration is demoted back to private candidate status.
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 correct 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 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.
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.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:alu="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source> <running/> </source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<router-name>Base</router-name>
<interface>
<interface-name>system</interface-name>
</interface>
</router>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
In the following reply, the namespace is accepted and no error message is returned.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:alu="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
<router>
<router-instance>Base</router-instance>
<interface>
<interface-name>system</interface-name>
<admin-state>disable</admin-state>
</interface>
</router>
</configure>
</data>
</rpc-reply>
]]>]]>
Non-default NETCONF base namespace
The following example shows an allowed non-default NETCONF base namespace used in the <rpc> element.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:alu="urn:nokia.com:sros:ns:yang:sr:conf">
<get-config>
<source> <running/> </source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<router-name>Base</router-name>
<interface>
<interface-name>system</interface-name>
</interface>
</router>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
In the following reply, a non-NETCONF base namespace is allowed and no error is returned.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:alu=="urn:nokia.com:sros:ns:yang:sr:conf">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
<router>
<router-name>Base</router-name>
<interface>
<interface-name>system</interface-name>
<admin-state>disable</admin-state>
</interface>
</router>
</configure>
</data>
</rpc-reply>
]]>]]>
Invalid NETCONF namespace declaration
The following example shows an invalid NETCONF namespace declared in the <rpc> element.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:alu="urn:alcatel-lucent.com:sros:ns:yang:sr:conf">
<get-config>
<source><running/></source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<router-name>Base</router-name>
<interface>
<interface-name>system</interface-name>
</interface>
</router>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
In the following reply, SR OS returns an error.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:alu="urn:alcatel-lucent.com:sros:ns:yang:sr:conf">
<rpc-error>
<error-type>protocol</error-type>
<error-tag>unknown-namespace</error-tag>
<error-severity>error</error-severity>
<error-message>
An unexpected namespace is present.
</error-message>
<error-info>
<bad-element>rpc</bad-element>
<bad-namespace>urn:alcatel-lucent.com:sros:ns:yang:sr:conf</bad-namespace>
</error-info>
</rpc-error>
</rpc-reply>
]]>]]>
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.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:alu="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source> <running/> </source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<router-name>Base</router-name>
<interface xmlns:alu="urn:nokia.com:sros:ns:yang:sr:conf">
<alu:interface-name>system</alu:interface-name>
</interface>
</router>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
In the following reply, the non-standard NETCONF namspace or prefix used in the tag is ignored.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:alu="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<router-name>Base</router-name>
<interface>
<interface-name>system</interface-name>
<admin-state>disable</admin-state>
</interface>
</router>
</configure>
</data>
</rpc-reply>
]]>]]>
Chunked frame mechanism
The following example shows a chunked message.
#359
<?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>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf"><router><router-name>Base</router-name>
<interface><interface-name>system</interface-name></interface></router></configure></filter></get-
config></rpc>
##
The following example shows the reply.
#38
<?xml version="1.0" encoding="UTF-8"?>
#1
#10
<rpc-reply
#17
message-id="101"
#48
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
#1
>
#1
#9
<data
#1
>
#1
#63
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
#21
<router>
#48
<router-name>Base</router-name>
#28
<interface>
#60
<interface-name>system</interface-name>
#55
<admin-state>disable</admin-state>
#29
</interface>
#22
</router>
#21
</configure>
#11
</data>
#1
#12
</rpc-reply>
##
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).
ssh user_name@netconf_server_ip -p port_number -s netconf
The following example shows an exchange of hello messages, which include advertisement of capabilities.
From the SR OS server:
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
<capability>urn:ietf:params:netconf:base:1.1</capability>
...
...
</capabilities>
<session-id>20</session-id>
</hello>
]]>]]>
A NETCONF client can reply with a hello message as shown in either of the following:
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
</capabilities>
</hello>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.1</capability>
</capabilities>
</hello>
]]>]]>
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.
<?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>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<management-interface>
<netconf/>
</management-interface>
</system>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
The following example shows the reply.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
<management-interface>
<netconf>
<admin-state>enable</admin-state>
<auto-config-save>true</auto-config-save>
</netconf>
<management-interface>
</system>
</configure>
</data>
</rpc-reply>
]]>]]>
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.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source><candidate/></source>
<filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<system>
</system>
</configure>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<log/>
</configure>
</filter>
</get-config>
</rpc>
]]>]]>
The following example shows the reply.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<log>
<filter>
<filter-id>1001</filter-id>
<entry>
<entry-id>10</entry-id>
<description>events of major severity or higher</description>
<action>forward</action>
<match>
<severity>
<gte>major</gte>
</severity>
</match>
</entry>
</filter>
...
...
<log-id>
<id>101</id>
<destination>
<netconf>
</netconf>
</destination>
</log-id>
</log>
<system>
<name>Test</name>
<dns>
<address-pref>ipv4-only</address-pref>
</dns>
...
...
</system>
</configure>
</data>
</rpc-reply>
]]>]]>
Creating an Epipe service
The following example shows an <edit-config> request on the <candidate> datastore to create a basic Epipe service.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/></target>
<config>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<service>
<epipe>
<service-name>CustDoc</service-name>
<customer>1</customer>
<service-mtu>1514</service-mtu>
</epipe>
</service>
</configure>
</config>
</edit-config>
</rpc>
]]>]]>
The following example shows the reply.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]>]]>
Returning multiple errors
The following example shows SR OS returning multiple errors with the <commit>.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/></target>
<config>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<router>
<router-name>Base</router-name>
<ldp>
<interface-parameters>
<interface>
<ip-int-name>xe-1/1/1</ip-int-name>
<ipv4>
</ipv4>
</interface>
<interface>
<ip-int-name>xe-1/2/1</ip-int-name>
<ipv4>
</ipv4>
</interface>
</interface-parameters>
<targeted-session>
<peer>
<ip-address>172.22.1.34</ip-address>
</peer>
</targeted-session>
<tcp-session-parameters>
<peer-transport>
<ip-address>172.22.1.34</ip-address>
<authentication-key>Ru4bf!n</authentication-key>
</peer-transport>
</tcp-session-parameters>
</ldp>
</router>
</configure>
</config>
</edit-config>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit/>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>operation-failed</error-tag>
<error-severity>error</error-severity>
<error-path xmlns:a="urn:nokia.com:sros:ns:yang:sr:conf">
/a:configure/a:router[a:router-name="Base"]/a:ldp/a:interface-parameters/a:interface[a:ip-int-name="xe-1/1/1"]
</error-path>
<error-message>
MINOR: MGMT_CORE #224: Entry does not exist - configure router router-name "Base" interface interface-name
"xe-1/1/1"
</error-message>
<error-info>
<err-element>interface</err-element>
</error-info>
</rpc-error>
<rpc-error>
<error-type>application</error-type>
<error-tag>operation-failed</error-tag>
<error-severity>error</error-severity>
<error-path xmlns:a="urn:nokia.com:sros:ns:yang:sr:conf">
/a:configure/a:router[a:router-name="Base"]/a:ldp/a:interface-parameters/a:interface[a:ip-int-name="xe-1/2/1"]
</error-path>
<error-message>
MINOR: MGMT_CORE #224: Entry does not exist - configure router router-name "Base" interface interface-name
"xe-1/2/1"
</error-message>
<error-info>
<err-element>interface</err-element>
</error-info>
</rpc-error>
</rpc-reply>
]]>]]>
NETCONF notifications
NETCONF notifications support is a standard IETF asynchronous notification delivery service for NETCONF that is specified in RFC 5277. SR OS allows log events to be output as NETCONF notifications. NETCONF is one of the output options for an event log (along with SNMP, syslog, and others).
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 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 maps log events to the following NETCONF notifications. See NETCONF notification examples for more information.
sros-config-change-event
This notification contains information about configuration changes in classic format. The tmnxConfigModify, tmnxConfigCreate, and tmnxConfigDelete log events from the SYSTEM and SECURITY applications are mapped to this notification. For model-driven information about configuration changes, Nokia recommends you use ON_CHANGE telemetry (for example, a subscription to the YANG /configure path) or the netconf-config-change notification that follows.
sros-state-change-event
This notification contains information about state changes in classic format. The tmnxStateChange log event from the SYSTEM and SECURITY applications are mapped to this notification. For model-driven information about state changes, Nokia recommends you use ON_CHANGE telemetry (for example, a subscription to various YANG state paths).
sros-command-accounting-event
This notification contains information about the commands and operations performed by users in classic CLI and MD-CLI. Log events mapped to this notification include the cli_*_io events from the USER application and the md_cli_io and md_cli_unauth_io events from the SECURITY application.
-
sros-log-generic-event
This notification contains information about non-LI SR OS log events in most protocols and feature areas. All log events that are not mapped to any other notifications in this list are mapped to the sros-log-generic-event.
netconf-config-change
This is a notification based on the model-driven configuration change log events ‟mdConfigChange”, ‟mdOcConfigChange”, ‟mdBofConfigChange”, and ‟mdDebugConfigChange” from the MGMT_CORE application. 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 does not occur.
sros-md-rpc-accounting-event
This is a notification based on the NETCONF/gRPC local command accounting log events (the netconf_auth, netconf_unauth, grpc_auth, and grpc_unauth log events from the SECURITY application). 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 Lawful Intercept (LI) NETCONF notifications.
sros-li-config-change-event
This notification contains information about LI configuration changes in classic format. The tmnxConfigModify, tmnxConfigCreate, and tmnxConfigDelete LI log events from the LI application are mapped to this notification. For model-driven information about LI configuration changes, Nokia recommends you use the netconf-li-config-change notification described in the following bullets.
sros-li-state-change-event
This notification contains information about LI state changes in classic format. The tmnxStateChange log event from the LI application is mapped to this notification.
sros-li-command-accounting-event
This notification contains information about which LI user performed which commands and operations in classic CLI and MD-CLI. LI log events mapped to this notification include the cli_*_io events from the LI application as well as the md_cli_io and md_cli_unauth_io events from the LI application.
sros-li-log-generic-event
This notification contains information about LI SR OS log events in most protocols and feature areas. All LI SR OS log events that are not mapped to any other notifications in this list are mapped to the sros-li-log-generic-event.
netconf-li-config-change
This is a notification based on the model-driven LI configuration change log event (the ‟mdLiConfigChange” log event from the LI application). It is sent upon any LI configuration change that occurs in the running datastore by 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
This is 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 from the LI application). 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 provide basic information about which RPC/operation was requested and the associated user. They do not show the details of every configuration element changed in a NETCONF request.
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:
If a <stopTime> is not specified, the session continues to send notifications as they arise in the system. The following is an example of a session without a <stopTime> specified:
If neither <startTime> and <stopTime> arguments are present, no replay is present and notifications continue to be sent until the subscription is terminated.
NETCONF notification examples
This section provides examples of NETCONF notifications.
Example of <create-subscription> operation
The following example shows a <create-subscription> operation.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<create-subscription>
</create-subscription>
</rpc>
]]>]]>
The following example shows the reply.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]>]]>
Example of sros-config-change-event notification
The following example shows an sros-config-change-event notification.
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2017-06-12T09:12:43.376Z</eventTime>
<sros-config-change-event xmlns="urn:nokia.com:sros:ns:yang:sr:notifications">
<sequence-number>8447</sequence-number>
<severity>warning</severity>
<application>system</application>
<event-id>2008</event-id>
<event-name>tmnxConfigDelete</event-name>
<router-name>Base</router-name>
<subject>LDP</subject>
<message>vRtrLdpNgSessionTable: Virtual Router 1, Peer 2.2.2.2:0. managed object deleted</message>
<event-params>
<tmnxNotifyRow>vRtrLdpNgSessState.1.1.6.2.2.2.2.0.0</tmnxNotifyRow>
<tmnxNotifyEntryOID>vRtrLdpNgSessionEntry</tmnxNotifyEntryOID>
<tmnxNotifyObjectName>vRtrLdpNgSessionTable: Virtual Router 1, Peer 2.2.2.2:0.</tmnxNotifyObjectName>
</event-params>
</sros-config-change-event>
</notification>
Example of sros-state-change-event notification
The following example shows an sros-state-change-event notification.
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2017-06-12T09:16:36.781Z</eventTime>
<sros-state-change-event xmlns="urn:nokia.com:sros:ns:yang:sr:notifications">
<sequence-number>8460</sequence-number>
<severity>warning</severity>
<application>system</application>
<event-id>2009</event-id>
<event-name>tmnxStateChange</event-name>
<router-name>Base</router-name>
<subject>LDP</subject>
<message>Status of vRtrLdpNgSessionTable: Virtual Router 1, Peer 2.2.2.2:0. changed administrative state: inService, operational state: inService</message>
<event-params>
<tmnxNotifyRow>vRtrLdpNgSessState.1.1.6.2.2.2.2.0.0</tmnxNotifyRow>
<tmnxNotifyRowAdminState>inService</tmnxNotifyRowAdminState>
<tmnxNotifyRowOperState>inService</tmnxNotifyRowOperState>
<tmnxNotifyEntryOID>vRtrLdpNgSessionEntry</tmnxNotifyEntryOID>
<tmnxNotifyObjectName>vRtrLdpNgSessionTable: Virtual Router 1, Peer 2.2.2.2:0.</tmnxNotifyObjectName>
</event-params>
</sros-state-change-event>
</notification>
Example of sros-cli-accounting-event notification
The following example shows an sros-cli-accounting-event notification.
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2017-06-12T09:11:45.476Z</eventTime>
<sros-command-accounting-event mlns="urn:nokia.com:sros:ns:yang:sr:notifications">
<sequence-number>8462</sequence-number>
<severity>minor</severity>
<application>user</application>
<event-id>2011</event-id>
<event-name>cli_config_io</event-name>
<router-name>Base</router-name>
<subject>admin</subject>
<message>User from CONSOLE: Dut-C>config>log>log-id# /configure router interface "toDutB_214" </message>
<event-params>
<srcAddr>CONSOLE</srcAddr>
<prompt>Dut-C>config>log>log-id# </prompt>
<message>/configure router interface "toDutB_214" </message>
</event-params>
</sros-command-accounting-event>
</notification>
Example of sros-log-generic-event notification
The following shows an sros-log-generic-event notification.
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2017-06-12T09:12:42.344Z</eventTime>
<sros-log-generic-event xmlns="urn:nokia.com:sros:ns:yang:sr:notifications">
<sequence-number>8443</sequence-number>
<severity>warning</severity>
<application>ospf</application>
<event-id>2047</event-id>
<event-name>tmnxOspfNgIfStateChange</event-name>
<router-name>Base</router-name>
<subject>VR: 1 OSPFv2 (0) </subject>
<message>LCL_RTR_ID 1.1.1.1: Interface toDutB_214 state changed to down (event IF_DOWN)</message>
<event-params>
<vRtrID>1</vRtrID>
<tmnxOspfVersion>version2</tmnxOspfVersion>
<tmnxOspfInstance>0</tmnxOspfInstance>
<tmnxOspfRouterId>16843009</tmnxOspfRouterId>
<tmnxOspfNgIfIndex>0x00000007</tmnxOspfNgIfIndex>
<tmnxOspfNgIfInstId>0</tmnxOspfNgIfInstId>
<tmnxOspfNgIfAreaId>0</tmnxOspfNgIfAreaId>
<tmnxOspfNgIfState>down</tmnxOspfNgIfState>
<tmnxOspfIfIpName>toDutB_214</tmnxOspfIfIpName>
<tmnxOspfIfEvent>IF_DOWN</tmnxOspfIfEvent>
<ospfRouterIdIpAddr>1.1.1.1</ospfRouterIdIpAddr>
</event-params>
</sros-log-generic-event>
</notification>
Example of netconf-config-change notification
The following example shows a netconf-config-change notification.
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2016-01-01T19:17:33Z</eventTime>
<netconf-config-change
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"
xmlns:notif="urn:nokia.com:sros:ns:yang:sr:notifications"
xmlns:sros="urn:nokia.com:sros:ns:yang:sr:conf">
<changed-by>
<username>user_name</username>
<session-id>8</session-id>
<source-host>138.192.72.45</remote-host>
</changed-by>
<datastore>running</datastore>
<edit>
<target>/config/service/epipe[serviceId=1]</target>
<operation>create</operation>
<notif:value>anyValue</notif:value>
</edit>
</netconf-config-change>
</notification>
Example of sros-md-rpc-accounting-event notification
The following example shows an sros-md-rpc-accounting-event notification.
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2019-10-08T21:01:50.165Z</eventTime>
<sros-md-rpc-accounting- event xmlns="urn:nokia.com:sros:ns:yang:sr:notifications">
<sequence-number>124</sequence-number>
<severity>minor</severity>
<application>security</application>
<event-id>2227</event-id>
<event-name>netconf_auth</event-name>
<router-name>management</router-name>
<subject>admin</subject>
<message>User admin from 192.168.7.229 port 44559 to port 830 session 7: edit-config RPC authorized</message>
<event-params>
<userName>admin</userName>
<srcAddr>192.168.7.229</srcAddr>
<srcPort>44559</srcPort>
<dstPort>830</dstPort>
<sessionId>7</sessionId>
<rpcName>edit-config</rpcName>
</event-params>
</sros-md-rpc-accounting-event>
</notification>
]]>]]>
NETCONF monitoring
The :ietf-netconf-monitoring capability is advertised in the SR OS NETCONF server <hello> using the following syntax.
<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 all subtrees from the YANG model that is used to monitor the NETCONF protocol as described in RFC 6022 (that is, “:ietf-netconf-monitoring” capability).
A <get-schema> operation is supported for explicit schema retrieval using NETCONF (YANG data model discovery and download as described in RFC 6022). The following parameters are supported:
-
identifier
This parameter is a mandatory string. It specifies an identifier for the schema list entry (YANG file). It can be the name of a module or a submodule.
-
version
This parameter is an optional string. It specifies a version of the schema requested (for example, YANG file). It represents the most recent YANG revision statement in a module or submodule. There is an empty string if no revision statement is present. Because multiple versions may be supported by the NETCONF server, each version must be reported individually in the schema list (it can have same identifier but different versions).
-
format
This parameter is an optional string. It specifies the data modeling language in which the schema is written. The default value is yang when not specified. If specified, yang is the only value supported.
Unless the user intentionally specifies a schema path destination 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 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 are installed and available to the <get-schema> NETCONF RPC. Nokia recommends 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.
Use the following command to configure the schema path:
configure system management-interface schema-pathSee the schema-path command description in the 7450 ESS, 7750 SR, 7950 XRS, and VSR Classic CLI Command Reference Guide for more information. If a schema-path command is configured, you must copy all the YANG schema files manually to the specified schema-path before 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 is 180 characters, however, Nokia recommends that a specified schema path be less than or equal to 135 characters, to guarantee that a <get-schema> works 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".
Output of a <get-schema> request output
<?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">
<identifier>nokia-conf</identifier>
</get-schema>
</rpc>
]]>]]>Output of a reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-
monitoring"><![CDATA[module nokia-conf {
yang-version "1.1";
namespace "urn:nokia.com:sros:ns:yang:sr:conf";
..
}
]]></data>
</rpc-reply>netconf-state schemas
The schemas subtree provides a list of the supported YANG schemas on the SR OS device.
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. Examples are available at the end of this section.
A /netconf-state/schemas path returns all supported YANG modules.
Output of a request and the received response
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<schemas/>
</netconf-state>
</filter>
</get>
</rpc>
]]>]]>
Output of the reply
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<schemas>
<schema>
<identifier>nokia-conf</identifier>
<version>2016-07-06</version>
<format>yang</format>
<namespace>urn:nokia.com:sros:ns:yang:sr:conf</namespace>
<location>NETCONF</location>
</schema>
<schema>
<identifier>nokia-conf-aa-group</identifier>
<version>2018-09-14</version>
<format>yang</format>
<namespace>urn:nokia.com:sros:ns:yang:sr:conf</namespace>
<location>NETCONF</location>
</schema>
<schema>
<identifier>nokia-conf-aaa</identifier>
<version>2018-08-27</version>
<format>yang</format>
<namespace>urn:nokia.com:sros:ns:yang:sr:conf</namespace>
<location>NETCONF</location>
</schema>
….
….
<schema>
<identifier>nokia-state</identifier>
<version>2016-07-06</version>
<format>yang</format>
<namespace>urn:nokia.com:sros:ns:yang:sr:state</namespace>
<location>NETCONF</location>
</schema>
<schema>
<identifier>nokia-state-aa-group</identifier>
<version>2018-09-14</version>
<format>yang</format>
<namespace>urn:nokia.com:sros:ns:yang:sr:state</namespace>
<location>NETCONF</location>
</schema>
<schema>
<identifier>nokia-state-aaa</identifier>
<version>2018-08-27</version>
<format>yang</format>
<namespace>urn:nokia.com:sros:ns:yang:sr:state</namespace>
<location>NETCONF</location>
</schema>
…
…
</schemas>
</state>
</data>
</rpc-reply>
netconf-state datastores
The datastores subtree provides a list of configuration datastores supported on the SR OS device.
The data returned for a query of the /netconf-state/datastores path depends on the settings of the yang-modules container and whether NMDA support is configured.
netconf-state datastores request and received response
<rpc message-id="50" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<datastores/>
</netconf-state>
</filter>
</get>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="50" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<datastores>
<datastore>
<name>running</name>
</datastore>
<datastore>
<name>candidate</name>
</datastore>
<datastore>
<name>startup</name>
</datastore>
[..SNIP..]
</datastore>
</datastores>
</netconf-state>
</data>
</rpc-reply>
]]>]]>
netconf-state sessions
The sessions subtree provides a list of all active NETCONF sessions.
netconf-state session request and received response
<rpc message-id="50" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<sessions/>
</netconf-state>
</filter>
</get>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="50" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<sessions>
<session>
<session-id>249</session-id>
<transport xmlns:ietf-netconf-monitoring="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">ietf-netconf-monitoring:netconf-ssh</transport>
<username>admin</username>
<source-host>192.168.168.2</source-host>
<login-time>2022-06-23T13:11:08.0Z</login-time>
<in-rpcs>1</in-rpcs>
<in-bad-rpcs>0</in-bad-rpcs>
<out-rpc-errors>0</out-rpc-errors>
<out-notifications>0</out-notifications>
</session>
</sessions>
</netconf-state>
</data>
</rpc-reply>
]]>]]>
netconf-state capabilities
The capabilities subtree provides a list of the capabilities of the current NETCONF session. The output is similar to the NETCONF hello message.
netconf-state statistics
The statistics subtree provides statistical data pertaining to the NETCONF service on the SR OS device.
netconf-state statistics request and received response
<rpc message-id="50" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<statistics/>
</netconf-state>
</filter>
</get>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="50" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<statistics>
<netconf-start-time>2022-06-22T20:22:21.0Z</netconf-start-time>
<in-sessions>2</in-sessions>
<in-rpcs>4</in-rpcs>
<in-bad-rpcs>1</in-bad-rpcs>
<out-rpc-errors>1</out-rpc-errors>
<out-notifications>0</out-notifications>
</statistics>
</netconf-state>
</data>
</rpc-reply>
]]>]]>
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):
<capability>urn:ietf:params:netconf:capability:yang-
library:1.1?revision=<date>&content-id=<content-id-value></capability>
The following is the YANG tree diagram for the ‟/yang-library” model:
module: ietf-yang-library
+--ro yang-library
+--ro module-set* [name]
| +--ro name string
| +--ro module* [name]
| | +--ro name yang:yang-identifier
| | +--ro revision? revision-identifier
| | +--ro namespace inet:uri
| | +--ro location* inet:uri
| | +--ro submodule* [name]
| | | +--ro name yang:yang-identifier
| | | +--ro revision? revision-identifier
| | | +--ro location* inet:uri
| | +--ro feature* yang:yang-identifier
| | +--ro deviation* -> ../../module/name
| +--ro import-only-module* [name revision]
| +--ro name yang:yang-identifier
| +--ro revision union
| +--ro namespace inet:uri
| +--ro location* inet:uri
| +--ro submodule* [name]
| +--ro name yang:yang-identifier
| +--ro revision? revision-identifier
| +--ro location* inet:uri
+--ro schema* [name]
| +--ro name string
| +--ro module-set* -> ../../module-set/name
+--ro datastore* [name]
| +--ro name ds:datastore-ref
| +--ro schema -> ../../schema/name
+--ro content-id string
The SR OS NETCONF server advertises the following capability in the <hello> message:
<capability>urn:ietf:params:netconf:capability:yang-
library:1.0?revision=<revision-date>&module-set-id=<string></capability>
The following is the YANG tree diagram for the modules-state model:
+--ro modules-state
+--ro module-set-id string
+--ro module* [name revision]
+--ro name yang:yang-identifier
+--ro revision union
+--ro schema? inet:uri
+--ro namespace inet:uri
+--ro feature* yang:yang-identifier
+--ro deviation* [name revision]
| +--ro name yang:yang-identifier
| +--ro revision union
+--ro conformance-type enumeration
+--ro submodule* [name revision]
+--ro name yang:yang-identifier
+--ro revision union
+--ro schema? inet:uri
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:
<capability>urn:ietf:params:netconf:capability:yang-library:1.0?revision=2018-
05-08&module-set-id=1234</capability>
The following example shows the NETCONF client using the advertised module-set-id to query the YANG library.
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
<get>
<filter type="subtree">
<modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<module-set-id>1234</module-set-id>
<module>
</module>
</modules-state>
</filter>
</get>
</rpc>
]]>]]>
The following example shows the reply.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<module-set-id>1234</module-set-id>
<module>
<name>iana-if-type</name>
<revision>2014-05-08</revision>
<namespace>urn:ietf:params:xml:ns:yang:iana-if-type</namespace>
<conformance-type>implement</conformance-type>
</module>
…
…
<module>
<name>nokia-conf</name>
<revision>2016-07-06</revision>
<namespace>urn:nokia.com:sros:ns:yang:sr:conf</namespace>
<conformance-type>implement</conformance-type>
<submodule>
<name>nokia-conf-aa-common</name>
<revision>2018-04-23</revision>
</submodule>
…
…
</module>
…
…
</modules-state>
</data>
</rpc-reply>
]]>]]>
Operational commands via NETCONF
Operational commands (for example, admin reboot, file remove) are supported via NETCONF using:
-
individually YANG-modeled 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 YANG-modeled 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.
Individually YANG-modeled 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-modeled operations.
Output of a request to create a new directory on CF1
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<action xmlns="urn:ietf:params:xml:ns:yang:1">
<file xmlns="urn:nokia.com:sros:ns:yang:sr:oper-file">
<make-directory>
<url>cf1:\\my-folder-abc</url>
</make-directory>
</file>
</action>
</rpc>
]]>]]>
Output of a reply for a successful directory creation operation
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nokiaoper="urn:nokia.com:sros:ns:yang:sr:oper-file">
<nokiaoper:operation-id>10</nokiaoper:operation-id>
<nokiaoper:start-time>2021-06-16T20:09:00.7Z</nokiaoper:start-time>
<nokiaoper:status>completed</nokiaoper:status>
<nokiaoper:end-time>2021-06-16T20:09:06.7Z</nokiaoper:end-time>
</rpc-reply>
]]>]]>
Output of a CPM synchronize operation request
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<action xmlns="urn:ietf:params:xml:ns:yang:1">
<admin xmlns="urn:nokia.com:sros:ns:yang:sr:oper-admin">
<redundancy>
<synchronize>
<configuration/>
</synchronize>
</redundancy>
</admin>
</action>
</rpc>
]]>]]>
Output of a reply when the CPM synchronize operation fails
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>operation-failed</error-tag>
<error-severity>error</error-severity>
<error-message>
MINOR: MGMT_AGENT #2007: Operation failed - secondary CPM offline
</error-message>
</rpc-error>
</rpc-reply>
]]>]]>
<md-compare> YANG-modeled operation
NETCONF can be used to obtain the differences between configurations. The <md-compare> operation is a synchronous YANG modelled operation. See Individually YANG-modeled operations for more information.
The YANG model with detailed input and output parameters for the <md-compare> operation is available in the YANG distribution for the specific software release.
The following table summarizes a selection of the available input parameters.
| Input parameter | Description |
|---|---|
| <path>/<subtree-path> |
The XML-formatted and correctly namespaced path to the tree location where the <md-compare> operation is executed. Omitting the <subtree-path> executes the <md-compare> operation from the root of the YANG tree. Optional. Default: root (/) |
| <configuration-region> |
The SR OS configuration region. See <get> for an example of the <configuration-region>. Optional. Default: configure |
| <format> |
The NETCONF output format. See Output format selection for more information. Optional. Default: xml |
| <source> |
The source configuration. See Source and destination locations for more information. Optional. Default: <candidate/> |
| <destination> |
The destination configuration. See Source and destination locations for more information. Optional. Default: <baseline/> |
The following table describes the source and destination locations available for use.
| Option | Description |
|---|---|
| <candidate/> | The candidate configuration. This is the default for the <source> input parameter. |
| <baseline/> | The baseline configuration. This is the default for the <destination> input parameter. |
| <url>URL</url> |
Uses the location specified in the URL. The following URL types are supported:
|
| <running/> | The running configuration |
| <startup/> | The startup configuration |
| <booted/> | The booted configuration. To use this option, the <configuration-region> must be set to "bof". |
| <rollback><checkpoint-id>NUMBER</checkpoint-id></rollback> | The configuration stored at the rollback checkpoint-id identified by NUMBER |
The results from the <md-compare> operation are displayed in the <results>/<md-compare-output> XML field.
The XML-formatted <md-compare> provides the correctly formatted and namespace-aware XML data that, if sent to the node, results in the target configuration. This option is similar to the use of compare summary netconf-rpc in the MD-CLI.
The MD-CLI-formatted <md-compare> provides the equivalent output as compare summary in the MD‑CLI.
The following output shows the example configuration used in the <md-compare> operation examples.
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<edit-config>
<target><candidate/></target>
<config>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<log>
<log-id>
<name>50</name>
<admin-state>enable</admin-state>
<description>Example</description>
<source>
<main>true</main>
<change>true</change>
</source>
<destination>
<cli>
</cli>
</destination>
</log-id>
</log>
</configure>
</config>
</edit-config>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<ok/>
</rpc-reply>
]]>]]>
See the following sections for examples of the <md-compare> operation:
<md-compare> using all default values
<rpc message-id="121" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<action xmlns="urn:ietf:params:xml:ns:yang:1">
<global-operations xmlns="urn:nokia.com:sros:ns:yang:sr:oper-global">
<md-compare/>
</global-operations>
</action>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="121" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1" xmlns:nokiaoper="urn:nokia.com:sros:ns:yang:sr:oper-global">
<nokiaoper:operation-id>11</nokiaoper:operation-id>
<nokiaoper:start-time>2022-06-20T22:03:09.9Z</nokiaoper:start-time>
<nokiaoper:results>
<nokiaoper:md-compare-output>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
<log>
<log-id>
<name>50</name>
<admin-state>enable</admin-state>
<description>Example</description>
<source>
<main>true</main>
<change>true</change>
</source>
<destination>
<cli>
</cli>
</destination>
</log-id>
</log>
</configure>
</nokiaoper:md-compare-output>
</nokiaoper:results>
<nokiaoper:status>completed</nokiaoper:status>
<nokiaoper:end-time>2022-06-20T22:03:10.0Z</nokiaoper:end-time>
</rpc-reply>
]]>]]>
<md-compare> using MD-CLI format
<rpc message-id="121" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<action xmlns="urn:ietf:params:xml:ns:yang:1">
<global-operations xmlns="urn:nokia.com:sros:ns:yang:sr:oper-global">
<md-compare>
<format>md-cli</format>
</md-compare>
</global-operations>
</action>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="121" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1" xmlns:nokiaoper="urn:nokia.com:sros:ns:yang:sr:oper-global">
<nokiaoper:operation-id>12</nokiaoper:operation-id>
<nokiaoper:start-time>2022-06-20T22:09:24.6Z</nokiaoper:start-time>
<nokiaoper:results>
<nokiaoper:md-compare-output>
configure {
log {
+ log-id "50" {
+ admin-state enable
+ description "Example"
+ source {
+ main true
+ change true
+ }
+ destination {
+ cli {
+ }
+ }
+ }
}
}
</nokiaoper:md-compare-output>
</nokiaoper:results>
<nokiaoper:status>completed</nokiaoper:status>
<nokiaoper:end-time>2022-06-20T22:09:24.6Z</nokiaoper:end-time>
</rpc-reply>
]]>]]>
<md-compare> using XML format and an explicit path
The following example shows the <md-compare> operation run from the configure log log-id 50 source path specifying explicitly the XML format.
<rpc message-id="121" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<action xmlns="urn:ietf:params:xml:ns:yang:1">
<global-operations xmlns="urn:nokia.com:sros:ns:yang:sr:oper-global">
<md-compare>
<format>xml</format>
<path>
<subtree-path>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<log>
<log-id>
<name>50</name>
<source/>
</log-id>
</log>
</configure>
</subtree-path>
</path>
</md-compare>
</global-operations>
</action>
</rpc>
]]>]]>
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="121" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:yang="urn:ietf:params:xml:ns:yang:1" xmlns:nokiaoper="urn:nokia.com:sros:ns:yang:sr:oper-global">
<nokiaoper:operation-id>14</nokiaoper:operation-id>
<nokiaoper:start-time>2022-06-20T22:12:18.6Z</nokiaoper:start-time>
<nokiaoper:results>
<nokiaoper:md-compare-output>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf" xmlns:nokia-attr="urn:nokia.com:sros:ns:yang:sr:attributes">
<log>
<log-id>
<name>50</name>
<source>
<main>true</main>
<change>true</change>
</source>
</log-id>
</log>
</configure>
</nokiaoper:md-compare-output>
</nokiaoper:results>
<nokiaoper:status>completed</nokiaoper:status>
<nokiaoper:end-time>2022-06-20T22:12:18.6Z</nokiaoper:end-time>
</rpc-reply>
]]>]]>
NETCONF operations using the md-cli-raw-command request
In addition to individually YANG-modelled operations described in Individually YANG-modeled operations, SR OS also supports a wide set of operations over NETCONF with the md-cli-raw-command request.
Nokia recommends using an individually modeled YANG operation if it is available for a specific operation, but for operations that are not individually YANG-modelled, the md-cli-raw-command can be used.
The command input string accepts a command in the exact format as it would be entered in the MD-CLI. For example:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<action xmlns="urn:ietf:params:xml:ns:yang:1">
<global-operations xmlns="urn:nokia.com:sros:ns:yang:sr:oper-global">
<md-cli-raw-command>
<md-cli-input-line>clear router Base interface system statistics</md-cli-input-line>
</md-cli-raw-command>
</global-operations>
</action>
</rpc>
Other examples of commands that can be used as input strings include:
-
file list cf1:
-
show system information
-
tools dump resource-usage
-
tools perform cflowd manual-export
-
//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. Because 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 is 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
-
file edit
-
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
-
//file vi
-
//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.