Information About the NETCONF Protocol
Introduction to Data Models - Programmatic and Standards-Based Configuration
The traditional way of managing network devices is by using Command Line Interfaces (CLIs) for configurational (configuration commands) and operational data (show commands). For network management, Simple Network Management Protocol (SNMP) is widely used, especially for exchanging management information between various network devices. Although CLIs and SNMP are heavily used, they have several restrictions. CLIs are highly proprietary, and human intervention is required to understand and interpret their text-based specification. SNMP does not distinguish between configurational and operational data.
The solution lies in adopting a programmatic and standards-based way of writing configurations to any network device, replacing the process of manual configuration. Network devices running on Cisco IOS XE support the automation of configuration for multiple devices across the network using data models. Data models are developed in a standard, industry-defined language, that can define configuration and state information of a network.
Cisco IOS XE supports the Yet Another Next Generation (YANG) data modeling language. YANG can be used with the Network Configuration Protocol (NETCONF) to provide the desired solution of automated and programmable network operations. NETCONF (RFC 6241) is an XML-based protocol that client applications use to request information from and make configuration changes to the device. YANG is primarily used to model the configuration and state data used by NETCONF operations.
In Cisco IOS XE, model-based interfaces interoperate with existing device CLI, Syslog, and SNMP interfaces. These interfaces are optionally exposed northbound from network devices. YANG is used to model each protocol based on RFC 6020.
Note |
To access Cisco YANG models in a developer-friendly way, clone the GitHub repository, and navigate to the vendor/cisco subdirectory. Models for various releases of IOS-XE, IOS-XR, and NX-OS platforms are available here. |
NETCONF
NETCONF provides a mechanism to install, manipulate, and delete the configuration of network devices.
It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages.
NETCONF uses a simple Remote Procedure Call (RPC) based mechanism to facilitate communication between a client and a server. The client can be a script or application running as part of a network manager. The server is typically a network device (switch or router). It uses Secure Shell (SSH) as the transport layer across network devices. It uses SSH port number 830 as the default port. The port number is a configurable option.
NETCONF also supports capability discovery and model downloads. Supported models are discovered using the ietf-netconf-monitoring model. Revision dates for each model are shown in the capabilities response. Data models are available for optional download from a device using the get-schema RPC. You can use these YANG models to understand or export the data model. For more details on NETCONF, see RFC 6241.
In releases prior to Cisco IOS XE Fuji 16.8.1, an operational data manager (based on polling) was enabled separately. In Cisco IOS XE Fuji 16.8.1 and later releases, operational data works on platforms running NETCONF (similar to how configuration data works), and is enabled by default. For more information on the components that are enabled for operational data queries or streaming, see the GitHub respository, to view *-oper in the naming convention.
NETCONF RESTCONF IPv6 Support
Data model interfaces (DMIs) support the use of IPv6 protocol. DMI IPv6 support helps client applications to communicate with services that use IPv6 addresses. External facing interfaces will provide dual-stack support; both IPv4 and IPv6.
DMIs are a set of services that facilitate the management of network elements. Application layer protocols such as, NETCONF and RESTCONF access these DMIs over a network.
If IPv6 addresses are not configured, external-facing applications will continue to listen on IPv6 sockets; but these sockets will be unreachable.
NETCONF Global Session Lock
The NETCONF protocol provides a set of operations to manage device configurations and retrieve device state information. NETCONF supports a global lock, and the ability to kill non-responsive sessions are introduced in NETCONF.
To ensure consistency and prevent conflicting configurations through multiple simultaneous sessions, the owner of the session can lock the NETCONF session. The NETCONF lock RPC locks the configuration parser and the running configuration database. All other NETCONF sessions (that do not own the lock) cannot perform edit operations; but can perform read operations. These locks are intended to be short-lived and allow the owner to make changes without interaction with other NETCONF clients, non-NETCONF clients (such as, SNMP and CLI scripts), and human users.
A global lock held by an active session is revoked when the associated session is killed. The lock gives the session holding the lock exclusive write access to the configuration. When a configuration change is denied due to a global lock, the error message will specify that a NETCONF global lock is the reason the configuration change has been denied.
The <lock> operation takes a mandatory parameter, <target> that is the name of the configuration datastore that is to be locked. When a lock is active, the <edit-config> and <copy-config> operations are not allowed.
If the clear configuration lock command is specified while a NETCONF global lock is being held, a full synchronization of the configuration is scheduled and a warning syslog message is produced. This command clears only the parser configuration lock.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<running/>
</target>
</lock>
</rpc>
NETCONF Kill Session
During a session conflict or client misuse of the global lock, NETCONF sessions can be monitored via the show netconf-yang sessions command, and non-responsive sessions can be cleared using the clear netconf-yang session command. The clear netconf-yang session command clears both the NETCONF lock and the configuration lock.
A <kill-session> request will force a NETCONF session to terminate. When a NETCONF entity receives a <kill-session> request for an open session, it stops all operations in process, releases all locks and resources associated with the session, and closes any associated connections.
A <kill-session> request requires the session-ID of the NETCONF session that is to be terminated. If the value of the session-ID is equal to the current session ID, an invalid-value error is returned. If a NETCONF session is terminated while its transaction is still in progress, the data model infrastructure will request a rollback, apply it to the network element, and trigger a synchronization of all YANG models.
If a session kill fails, and a global lock is held, enter the clear configuration lock command via the console or vty. At this point, the data models can be stopped and restarted.
Candidate Config Support
The Candidate Config Support feature enables support for candidate capability by implementing RFC 6241 with a simple commit option.
Candidate datastore provides a temporary work space in which a copy of the device's running configuration is stored. You can create and modify the running configuration before committing the running configuration to the device. Candidate capability is indicated by the following NETCONF capability: urn:ietf:params:netconf:capability:candidate:1.0. This NETCONF capability indicates that the device supports Candidate Datastore. This is a shared data store which enables the user to create, add, delete and make changes to the device configuration without effecting the running configuration on the device. A commit operation pushes the configuration from “candidate” to the “running” configuration on the device. When “candidate” data store is enabled, the Running data store is NOT writable through NETCONF sessions, all configurations get committed ONLY through Candidate. In other words, the writable-running NETCONF capability is not enabled with Candidate.
Note |
It must be kept in mind that candidate datastore is a shared data store. Multiple NETCONF sessions can modify it contents simultaneously. Therefore, it is important to lock the datastore before modifying its contents, to prevent conflicting commits which can eventually lead to losing any configuration changes. |
NETCONF Operations on Candidate
The following operations can be performed on Candidate data store.
Note |
The information in this section has been referenced from section 8.3.4 of RFC6241. Please refer to the RFC for for more details and the exact RPCs. |
Lock
A <lock> RPC is used to “Lock” the target data store. This prevents others users from modifying the configuration in the “locked” data store. We can lock both candidate and running data through the lock operation.
Note |
“Locking” candidate datastore does not affect Cisco IOS config lock or running config lock and vice versa. |
Commit
A <commit> RPC, copies the candidate configuration to the device’s running configuration. A commit operation must be performed after you have updated the candidate configuration to push the configuration to the device.
If either “Running” or “Candidate” datastore is locked by another NETCONF session, the commit RPC will fail with an RPC Error Reply. The <error-tag> should be <in-use> and <error-info> should have the “session-id” of the NETCONF session holding the lock. You can also lock the “running” config by using the “Global” lock by entering the “conf t lock” mode, but, the commit operation will fail with an RPC Error Reply, with error-tag value <in-use> and the session-id will be “0”.
Edit-config
Candidate configuration can be used as a target for “edit-config” operation to modify a configuration. This provides you the the ability to stage configuration changes in candidate without affecting the running configuration on the device.
Discard
To remove the changes made to candidate configuration, perform a discard operation to revert the candidate configuration to running configuration.
If the contents of candidate datastore have already been modified by NETCONF session A, and session B tries to lock the Candidate, the lock will fail. NETCONF session B must perform a <discard> operation to remove any outstanding configurations on candidate from other NETCONF sessions before locking a candidate.
Unlock
After working on candidate configuration, such as, lock, edit-config, or commit operations, you can “unlock” the data store, by specifying “candidate” as target in the Unlock RPC. Candidate is now available for all operations in other sessions.
If failure occurs with outstanding changes to candidate datastore, it can be challenging to recover the configuration and creates problems for other sessions. To avoid any issues, outstanding changes are discarded in candidate when the lock is released—either implicitly on “NETCONF session failure” or explicitly on “Unlock” operation.
Get-config, Copy-config, Validate
Candidate can be used as a source or target for any of the get-config, copy-config or validate config operations. If you do not want to commit changes in candidate to the device but only to validate the configuration, you can do so by <validate> RPC followed by a “discard”.
How to use Candidate?
The following diagram explains the recommended best practice when modifying the device configuration through candidate datastore:
-
Lock running datastore.
-
Lock randidate datastore.
-
Make modifications to candidate configuration through edit-config RPCs with target candidate.
-
Commit candidate configuration to running.
-
Unlock candidate and running.
Candidate Support Configuration
The candidate datastore functionality can be enabled by using the netconf-yang feature candidate-datastore command. When the datastore state changes from “running” to “candidate” or back, a warning message will be displayed notifying the user that a restart of netconf-yang or restconf will occur in order for the change to take effect. When candidate is enabled, The running data store is not writable through Netconf sessions, all configurations get committed only through candidate. In other words, the writable-running Netconf capability is not enabled with candidate.
If the selection of candidate or running datastore, is specified in the configuration when a netconf-yang or restconf confd process starts, a warning appears as shown below.
Device(config)# netconf-yang feature candidate-datastore
netconf-yang initialization in progress - datastore transition not allowed, please try again after 30 seconds
If the selection of candidate or running is made after netconf-yang or restconf confd process starts, the following apply:
-
If the netconf-yang feature candidate-datastore command is configured, the command enables the “candidate” datastore and prints the following warning:
“netconf-yang and/or restconf is transitioning from running to candidate netconf-yang and/or restconf will now be restarted, and any sessions in progress will be terminated”.
-
If the netconf-yang feature candidate-datastore command is removed, the command disables the “candidate” datastore, enables the “running” datastore and prints the following warning:
netconf-yang and/or restconf is transitioning from candidate to running netconf-yang and/or restconf will now be restarted, and any sessions in progress will be terminated”.
-
When netconf-yang or restconf are restarted, sessions in progress will be lost.
Note |
Candidate data store is a shared data store, that is, multiple Netconf sessions can modify the contents simultaneously. Therefore, it is important for a user to lock the data store before modifying its contents, to prevent conflicting commits which can eventually lead to losing any configuration changes; wherein another user overwrites the configuration by modifying the configuration and issuing a commit. |