What is NETCONF ?
NETCONF Clients, Servers and YANG modules
NETCONF Sessions
Configuration Datastores
Configuration Data, State Data
Protocol Operations, NETCONF RPCs
Protocol Capabilities
NETCONF Notifications

What is NETCONF ?

The IETF Network Configuration Protocol, NETCONF (RFC6241), is the new IETF network management protocols that provide numerous advantages over the traditional Simple Network Management Protocol (SNMP). It uses XML based data encoding to configure and manage network devices through a set of standard Remote Procedure Call (RPC) methods.

YANG (RFC 6020) is a data modeling language used to model configuration and state data manipulated by NETCONF.

NETCONF Clients, Servers and YANG modules

The NETCONF architecture consists of three major components: servers, managers (clients) and YANG Data Modules, as shown in the figure below:

NETCONF Managers: A NETCONF manager is a software application (in client role) that configures, manages and/or monitors the NETCONF Servers in the managed network devices. A NETCONF manager sometimes is also called a Network Management System (NMS).

NETCONF Servers: A NETCONF Server is a software application (in server role) that runs in network devices such as switches, routers and printers, etc., talking to both the device and NETCONF Managers and acts as an “agent”. A Server configures the device to certain states upon receiving requests from Managers, and collects state information about the device and pass them to Managers. In other words a server executes protocol operations invoked by a client. In addition, a server can send notifications to clients.

YANG Modules: NETCONF Data models defines the configuration data and management information that is passed between a Server and a Manager.

NETCONF Sessions

The NETCONF server communicates with NETCONF managers through secure, connection-oriented sessions. A server and a manager explicitly establish a session to exchange data, and close the session when they are finished.

NETCONF servers must support NETCONF over SSH (RFC 6242). NETCONF can also be transported over TLS, SOAP and BEEP.

Configuration Datastores

The NETCONF PRC operations operate on configuration datastores. Datastore is a conceptual place to store and access information. A datastore might be implemented, for example, using files, a database, flash memory locations, or combinations thereof.

There are three standard configuration datastores:

<running> datastore: A configuration datastore holding the complete configuration currently active on the device. The running configuration datastore always exists.

<candidate> datastore: A configuration datastore that can be manipulated without impacting the device's current configuration and that can be committed to the running configuration datastore. Not all devices support a candidate configuration datastore.

<startup> datastore: startup configuration datastore: The configuration datastore holding the configuration loaded by the device when it boots. Only present on devices that separate the startup configuration datastore from the running configuration datastore

Configuration Data, State Data

The information that can be retrieved from a running system is separated into two classes, configuration data and state data. Configuration data is the set of writable data that is required to transform a system from its initial default state into its current state. State data is the additional data on a system that is not configuration data such as read-only status information and collected statistics.

The <get-config> operation retrieves configuration data only, while the <get> operation retrieves configuration and state data.

Protocol Operations, NETCONF RPCs

The NETCONF protocol uses an RPC-based communication model. NETCONF peers use <rpc> and <rpc-reply> elements to provide transport-protocol-independent framing of NETCONF requests and responses.


There are four types of message framing elements:

<rpc> Element
<rpc-reply> Element
<rpc-error> Element
<ok> Element

NETCONF carries retrieved data inside the <data> element.

 <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ex="http://example.net/content/1.0"
ex:user-id="fred">
<get/>
</rpc>

<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ex="http://example.net/content/1.0"
ex:user-id="fred">
<data>
<!-- contents here... -->
</data>
</rpc-reply>

NETCONF carries configuration data inside the <config> element.


Example: The <edit-config> examples in this section utilize a simple
data model, in which multiple instances of the <interface> element
can be present, and an instance is distinguished by the <name>
element within each <interface> element.

Set the MTU to 1500 on an interface named "Ethernet0/0" in the
running configuration:


<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<top xmlns="http://example.com/schema/1.2/config">
<interface>
<name>Ethernet0/0</name>
<mtu>1500</mtu>
</interface>
</top>
</config>
</edit-config>
</rpc>

<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>

NETCONF <rpc> requests MUST be processed serially by the managed device. The managed device MUST send responses only in the order the requests were received.

The NETCONF protocol provides a small set of low-level operations to manage device configurations and retrieve device state information. The base protocol provides operations to retrieve, configure, copy, and delete configuration datastores. Additional operations are provided, based on the capabilities advertised by the device.

The base protocol includes the following protocol operations:

Operation

Description

1 close-session
Request graceful termination of a NETCONF session.
<rpc message-id="101"xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<close-session/>
</rpc>
2 copy-config
Create or replace an entire configuration datastore with the contents of another complete configuration datastore. 
If the target datastore exists, it is overwritten. Otherwise, a new one is created, if allowed.
Example:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<running/>
</target>
<source>
<url>https://user:xxxxxxxxx/cfg/new.txt</url>
</source>
</rpc>

<rpc-reply message-id="101"  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
3 delete-config
Delete a configuration datastore. The <running> configuration datastore cannot be deleted.
Example:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<delete-config>
<target>
<startup/>
</target>
</delete-config>
</rpc>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
4 edit-config
Modify a configuration datastore by loading all or part of a specified configuration to the specified target 
configuration datastore.This operation allows the new configuration to be expressed inseveral ways,
such as using a local file, a remote file, orinline.
Example: The <edit-config> examples in this section utilize a simple data model, in which
by the <name> element within each <interface> element.
Set the MTU to 1500 on an interface named "Ethernet0/0" in the running configuration:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<top xmlns="http://example.com/schema/1.2/config">
<interface>
<name>Ethernet0/0</name>
<mtu>1500</mtu>
</interface>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
 get
Retrieve running configuration and device state information. 
Example:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/stats">
<interfaces>
<interface>
<ifName>eth0</ifName>
</interface>
</interfaces>
</top>
</filter>
</rpc>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/stats">
<interfaces>
<interface>
<ifName>eth0</ifName>
<ifInOctets>45621</ifInOctets>
<ifOutOctets>774344</ifOutOctets>
</interface>
</interfaces>
</top>
</data>
</rpc-reply>
6 get-config
Retrieve all or part of a specified configuration datastore
Example: To retrieve the entire <users> subtree:

<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users/>
</top>
</filter>
</get-config>
</rpc>

<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>root</name>
<type>superuser</type>
<full-name>Charlie Root</full-name>

<company-info>
<dept>1</dept>
<id>1</id>
</company-info>
</user>
<!-- additional <user> elements appear here... -->
</users>
</top>
</data>
</rpc-reply>
7 kill-session
Force the termination of a NETCONF session
<rpc message-id="101"xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<kill-session>
<session-id>4</session-id>
</kill-session>
</rpc>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
8 lock
The <lock> operation allows the client to lock the entire configuration datastore system of a device. 
Such locks are intended to be short-lived and allow a client to make a change without fear of
interaction with other NETCONF clients, non-NETCONF clients (e.g., SNMP and command line
interface (CLI) scripts), and human users.

Example: The following example shows a successful acquisition of a lock.

<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<running/>
</target>
</lock>
</rpc>

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <!-- lock succeeded -->
</rpc-reply>
9 unlock
The <unlock> operation is used to release a configuration lock, previously obtained with
the <lock> operation.
Example:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock>
<target>
<running/>
</target>
</unlock>
</rpc>
<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>

Protocol Capabilities

Capabilities are advertised in messages sent by each peer during session establishment. When the NETCONF session is opened, each peer (both client and server) MUST send a <hello> element containing a list of that peer's capabilities. Each peer MUST send at least the base NETCONF capability, "urn:ietf:params:netconf:base:1.1".

Each capability is also given a human-readable name, which is used throughout the documentation, instead of the URI representation. By convention, a colon character is pre-pended to the name to indicate it is a capability identifier.

:writable-running
:base

The following table summarizes the standard capabilities which a server may choose to support.

* :candidate:
urn:ietf:params:netconf:capability:candidate:1.0

The candidate configuration capability, :candidate, indicates that the device supports a candidate configuration datastore, which is used to hold configuration data that can be manipulated without impacting the device's current configuration. The candidate configuration is a full configuration data set that serves as a work place for creating and manipulating configuration data. Additions, deletions, and changes can be made to this data to construct the desired configuration data.

The server will support the <discard-changes> and basic <commit> operations. A <commit> operation MAY be performed at any time that causes the device's running configuration to be set to the value of the candidate configuration


*:confirmed-commit:
urn:ietf:params:netconf:capability:confirmed-commit:1.0
urn:ietf:params:netconf:capability:confirmed-commit:1.1

The server advertising this capability indicates it accepts two consecutive <commit> RPC method requests to save any changes in the candidate datastore to the running datastore. If the second request does not arrive within a specified time interval, the server will automatically revert the running configuration to the previous version.

*:interleave:
urn:ietf:params:netconf:capability:interleave:1.0

The server advertise this capability indicated it supports the basic notification delivery mechanisms defined in RFC 5277,

The :interleave capability indicates that the NETCONF peer supports the ability to interleave other NETCONF operations within a notification subscription. This means the NETCONF server MUST receive, process, and respond to NETCONF requests on a session with an active notification subscription. This capability helps scalability by reducing the total number of NETCONF sessions required by a given operator or management application.

The server will accept <rpc> requests (besides <close-session> while notification delivery is active. The :notification capability must also be present if this capability is advertised.

*:notification
urn:ietf:params:xml:ns:netconf:notification:1.0

The server advertise this capability indicated it supports the basic notification delivery mechanisms defined in RFC 5277.

:partial-lock
urn:ietf:params:netconf:capability:partial-lock:1.0

The server advertise this capability indicated it supports the <partial-lock> and <partial-unlock> operations, defined in RFC 5717. This allows multiple clients to write to a different part of the <running> configuration at the same time.

*:rollback-on-error
urn:ietf:params:netconf:capability:rollback-on-error:1.0

This capability indicates that the server will support the  rollback-on-error" value in the <error-option> parameter to the <edit-config> operation. In other words,if any error occurs during the <edit-config>  operation, the target datastore (usually the running configuration) can be be left unaffected.

*:startup
urn:ietf:params:netconf:capability:startup:1.0

The server advertises this capability indicates it supports the <startup/> configuration datastore. It allows the running configuration to be copied to the <startup/> datastore. A server is not required to allow the <startup/> datastore to be edited.

*:url
urn:ietf:params:netconf:capability:url:1.0?scheme={name,...}

The :url capability URI MUST contain a "scheme" argument assigned a comma-separated list of scheme names indicating which schemes the NETCONF peer supports. For example:

urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file

The capability URI for this feature indicates which schemes (file, http, https, sftp, ftp, etc.) that the server supports. For example, the 'file' scheme allows the client to edit a local configuration datastore.

*:validate
urn:ietf:params:netconf:capability:validate:1.0
urn:ietf:params:netconf:capability:validate:1.1

Validation consists of checking a complete configuration for syntactical and semantic errors before applying the configuration to the device. If this capability is advertised, the device supports the <validate> protocol operation and checks at least for syntax errors.

In addition to checking a complete configuration, tocheck a single edit request against a target datastore, the version 1.1 of this capability supports the <test-option> parameter to the <edit-config> operation and, when it is provided, checks at least for syntax errors in the <edit-config> requests.

*:with-default
urn:ietf:params:netconf:capability:with-defaults:1.0

A networking device may have a large number of default values. Often the default values are specifically defined with a reasonable value,
documented and well-known, so that the management user does not need  to handle them. For these reasons, it is quite common for networking
devices to suppress the output of parameters having the default value. However, there are use-cases when a NETCONF client will need the default
data from the server. This capability identifies the server's default-handling behavior: report-all, trim or explicit.  See RFC6243 for details.

*:writable-running
urn:ietf:params:netconf:capability:writable-running:1.0

The :writable-running capability indicates that the device supports direct writes to the <running> configuration datastore. In other words, the device supports <edit-config> and <copy-config> operations where the <running> configuration is the target.

*:xpath
urn:ietf:params:netconf:capability:xpath:1.0

The XPath capability indicates that the NETCONF peer supports the use of XPath expressions in the <filter> element of <get> or <get-config> operation.

The data model used in the XPath expression is the same as that used in XPath 1.0, with the same extension for root node children as used by XSLT 1.0 . Specifically, it means that the root node MAY have any number of element nodes as its children.

Notifications

NETCONF has a notification delivery mechanism, defined in RFC 5277.

A NETCONF client indicates interest in receiving event notifications from a NETCONF server by creating a subscription to receive event notifications. The NETCONF server replies to indicate whether the subscription request was successful and, if it was successful, begins sending the event notifications to the NETCONF client as the events occur within the system. These event notifications will continue to be sent until either the NETCONF session is terminated by <close-session> or <kill-session> request or the subscription terminates for some other reason.

New protocol element defined in RFC5277

Get Notification streams:

A NETCONF client retrieves the list of supported event streams from a NETCONF server using the <get> operation.

The list of available event streams is retrieved by requesting the <streams> subtree via a <get> operation. Available event streams for the requesting session are returned in the reply containing the <name> and <description> elements, where the <name> element is mandatory, and its value is unique within the scope of a NETCONF server. An empty reply is returned if there are no available event streams, due to user-specified filters on the <get> operation.

Additional information available about a stream includes whether notification replay is available and, if so, the timestamp of the earliest possible notification to replay.

The following example shows retrieving the list of available event stream list using the <get> operation.

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
<streams/>
</netconf>
</filter>
</get>
</rpc>

The NETCONF server returns a list of event streams available for subscription: NETCONF, SNMP, and syslog-critical in this example.

<rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> 
<data>
<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
<streams>
<stream>
<name>NETCONF</name>
<description>default NETCONF event stream </description>
<replaySupport>true</replaySupport>
<replayLogCreationTime> 2007-07-08T00:00:00Z </replayLogCreationTime>
</stream>
<stream>
<name>SNMP</name>
<description>SNMP notifications</description>
<replaySupport>false</replaySupport>
</stream>
</streams>
</netconf>
</data>
<rpc-reply>

Subscription to Notification streams:

<create-subscription> Description:

This operation initiates an event notification subscription that will send asynchronous event notifications to the initiator of the command until the subscription terminates.

The following demonstrates creating a simple subscription.

<netconf:rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> 
</create-subscription>
</netconf:rpc>

 

Notification delivery:

<notification> Description:

An event notification is sent to the client who initiated a <create-subscription> command asynchronously when an event of interest (i.e., meeting the specified filtering criteria) has occurred. An event notification is a complete and well-formed XML document. Note that <notification> is not a Remote Procedure Call (RPC) method but rather the top-level element identifying the one-way message as a notification.

 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-07-08T00:01:00Z</eventTime>
<event xmlns="http://example.com/event/1.0">
<eventClass>fault</eventClass>
<reportingEntity>
<card>Ethernet0</card>
</reportingEntity>
<severity>major</severity>
</event>
</notification>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> 
<event xmlns="http://example.com/event/1.0">
<eventClass> fault</eventClass>
<reportingEntity>
<card>Ethernet2</card>
</reportingEntity>
<severity>critical</severity>
</event>
</notification>