NETCONF (Network Configuration Protocol) is a network management protocol developed and standardized by the IETF Netconf Working Group. It was first published in December 2006 as RFC 4741 with a revised version published in June 2011 as RFC 6241. It provides mechanisms to install, manipulate, and delete the configuration of network devices.
The same IETF Working Group also produced supporting RFCs for various transport mappings, including:
- RFC 4742 – Using the NETCONF Configuration Protocol over Secure SHell (SSH). Obsoleted by RFC 6242 (2011) which introduced a new framing mechanism to address some potential security issues with the initial design
- RFC 4743 – Using NETCONF over the SOAP (Simple Object Access Protocol)
- RFC 5539 – NETCONF over Transport Layer Security (TLS)
- RFC 5277 – NETCONF Event Notifications. Describes an asynchronous notification mechanism allowing clients to subscribe to named event streams
- RFC 6243 – With-defaults Capability for NETCONF. Describes an extension to the NETCONF protocol that allows clients to identify how defaults are processed by the server
NETCONF is an RPC-based protocol which uses XML (Extensible Markup Language) to encode data as well as the protocol messages. The protocol messages are exchanged on top of a secure transport protocol such as SSL or TLS.
The NETCONF protocol can be conceptually partitioned into four layers:
- The Content layer consists of configuration data and notification data.
- The Operations layer defines a set of base protocol operations to retrieve and edit the configuration data.
- The Messages layer provides a mechanism for encoding remote procedure calls and notifications
- The Secure Transport layer provides a secure and reliable transport of messages between a client and a server.
The NETCONF protocol was designed to address the shortcomings of existing practices and protocols for configuration management. According to Tail-F, a Network Service Orchestration company:
CLI scripting was the primary approach to making automated configuration changes to the network prior to NETCONF. CLI scripting has several limitations including lack of transaction management, no structured error management and ever changing structure and syntax of commands that makes scripts fragile and costly to maintain. These are all side-effects of the basic fact that CLIs are designed to be used by humans and not an API for programmatic access.
SNMP is another approach that could be used to write changes, but, in practice, is mostly used for performance and monitoring applications. Reasons for this include the lack of a defined discovery process that makes it hard to find the correct MIB modules, limitations inherent in the use of the UDP protocol, and the lack of useful standard security and commit mechanisms.
Closely tied to NETCONF is YANG which is a data modeling language used to model configuration and state data manipulated by the NETCONF protocol, NETCONF remote procedure calls, and NETCONF notifications. YANG was developed by the IETF NETCONF Data Modeling Language Working Group (NETMOD), and is defined in RFC 6020. YANG structures the data definitions into tree structures and provides many modeling features, including an extensible type system, formal separation of state and configuration data and a variety of syntactic and semantic constraints. YANG data deï¬nitions are contained in modules and provide a rich set of features for extensibility and reuse.
The Cisco NX-OS implementation of NETCONF requires you to use a SSHv2 (Secure Shell Version 2) session for communication with the target device. See RFC 4742 for more information about using NETCONF over SSH . The target device provides an SSHv2 subsystem service called xmlagent that supports NETCONF over SSH Version 2.
SSHv2 subsystems are a layer of abstraction for defining and conveniently invoking remote commands on a server. For example, the default /etc/sshd/sshd_config file for Fedora 20 defines a subsystem for the sftpd server:
# override default of no subsystems Subsystem sftp /usr/libexec/openssh/sftp-server
As shown below, you invoke the xmlagent subsystem with the -s xmlagent command line argument. Note that some Cisco NETCONF documentation incorrectly states that the requisite subsystem is named netconf. Only SSH version 2 supports subsystems.
As you can see, all NETCONF messages are in the form of conforming XML documents with valid namespaces. You must end all the XML documents with ]]>]]> to support synchronization in NETCONF over SSH. You can obtain the NX-OS XML Schema Definition at the Cisco download website.
The following are some examples of how to use NETCONF on a Nexus 7000. By the way, in case you are unaware of it, the operating system on a Nexus 7000 is NX-OS and not IOS. For more information about the NX-OS XML interfaces, see here.
Example 1 – Hello
The hello message (XML document) must be the first message sent by a NETCONF-aware client after the NETCONF server emits it’s hello message.
To manually send an XML document to the XML server through an SSH session that you opened in a command shell, you can copy the XML text from an editor and paste it into the SSH session as I did above.
<?xml version="1.0"?>
<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<nc:capabilities>
<nc:capability>urn:ietf:params:xml:ns:netconf:base:1.0</nc:capability>
</nc:capabilities>
</nc:hello>]]>]]>
Example 2 – Show Server Status
<?xml version="1.0"?>
<nc:rpc message-id="1" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="http://www.cisco.com/nxos:1.0:xml">
<nc:get>
<nc:filter type="subtree">
<show>
<xml>
<server>
<status/>
</server>
</xml>
</show>
</nc:filter>
</nc:get>
</nc:rpc>]]>]]>
<?xml version="1.0" encoding="ISO-8859-1"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="http://www.cisco.com/nxos:1.0:xml" message-id="1">
<nc:data>
<show>
<xml>
<server>
<status>
<__XML__OPT_Cmd_show_xml___readonly__>
<__readonly__>
<operational_status>
<o_status>enabled</o_status>
</operational_status>
<maximum_sessions_configured>
<max_session>8</max_session>
</maximum_sessions_configured>
<TABLE_sessions>
<ROW_sessions>
<session_id>3940</session_id>
<user_name>admin</user_name>
<start_time>Sat May 10 15:08:31 2014</start_time>
<sap_id>2627</sap_id>
<timeout>1200</timeout>
<time_remaining_to_timeout>1197</time_remaining_to_timeout>
<ip_addr>192.168.100.1</ip_addr>
</ROW_sessions>
</TABLE_sessions>
</__readonly__>
</__XML__OPT_Cmd_show_xml___readonly__>
</status>
</server>
</xml>
</show>
</nc:data>
</nc:rpc-reply>
]]>]]>
Example 3 – Show Version
<?xml version="1.0"?>
<nc:rpc message-id="1" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="http://www.cisco.com/nxos:1.0:sysmgrcli">
<nc:get>
<nc:filter type="subtree">
<show>
<version>
</version>
</show>
</nc:filter>
</nc:get>
</nc:rpc>]]>]]>
<?xml version="1.0" encoding="ISO-8859-1"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="http://www.cisco.com/nxos:1.0:sysmgrcli" message-id="1">
<nc:data>
<show>
<version>
<__XML__OPT_Cmd_sysmgr_show_version___readonly__>
<__readonly__>
<header_str>Cisco Nexus Operating System (NX-OS) Software
TAC support: http://www.cisco.com/tac
Documents: http://www.cisco.com/en/US/products/ps9372/tsd_products_support_series_home.html
Copyright (c) 2002-2010, Cisco Systems, Inc. All rights reserved.
The copyrights to certain works contained herein are owned by
other third parties and are used and distributed under license.
Some parts of this software are covered under the GNU Public
License. A copy of the license is available at
http://www.gnu.org/licenses/gpl.html.
</header_str>
<loader_ver_str>N/A</loader_ver_str>
<kickstart_ver_str>5.1(2) [gdb]</kickstart_ver_str>
<sys_ver_str>5.1(2) [gdb]</sys_ver_str>
<kick_file_name>bootflash:/titanium-d1-kickstart.5.1.2.gbin</kick_file_name>
<kick_cmpl_time> 12/25/2020 12:00:00</kick_cmpl_time>
<kick_tmstmp>12/18/2010 09:53:29</kick_tmstmp>
<isan_file_name>bootflash:/titanium-d1.5.1.2.gbin</isan_file_name>
<isan_cmpl_time> 11/29/2010 12:00:00</isan_cmpl_time>
<isan_tmstmp>12/18/2010 11:47:03</isan_tmstmp>
<chassis_id>Unknown MDS Chassis</chassis_id>
<module_id>Unknown Module</module_id>
<cpu_name>Intel(R) Core(TM) i5-3450 CP</cpu_name>
<memory>2066644</memory>
<mem_type>kB</mem_type>
<proc_board_id>T0C29978A3B</proc_board_id>
<host_name>n7k</host_name>
<bootflash_size>0</bootflash_size>
<kern_uptm_days>0</kern_uptm_days>
<kern_uptm_hrs>1</kern_uptm_hrs>
<kern_uptm_mins>56</kern_uptm_mins>
<kern_uptm_secs>5</kern_uptm_secs>
</__readonly__>
</__XML__OPT_Cmd_sysmgr_show_version___readonly__>
</version>
</show>
</nc:data>
</nc:rpc-reply>
]]>]]>
Example 4 – Show Running Configuration
<?xml version="1.0"?>
<nc:rpc message-id="1" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="http://www.cisco.com/nxos:1.0:sysmgrcli">
<nc:get>
<nc:filter type="subtree">
<show>
<running-config>
</running-config>
</show>
</nc:filter>
</nc:get>
</nc:rpc>]]>]]>
<?xml version="1.0"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="http://www.cisco.com/nxos:1.0:sysmgrcli" message-id="1">
<nc:data>
!Command: show running-config
!Time: Sat May 10 16:34:25 2014
version 5.1(2)
license grace-period
hostname n7k
vdc n7k id 1
limit-resource vlan minimum 16 maximum 4094
limit-resource vrf minimum 2 maximum 1000
limit-resource port-channel minimum 0 maximum 768
limit-resource u4route-mem minimum 96 maximum 96
limit-resource u6route-mem minimum 24 maximum 24
limit-resource m4route-mem minimum 58 maximum 58
limit-resource m6route-mem minimum 8 maximum 8
feature ospf
feature hsrp
feature vtp
username adminbackup password 5 ! role network-operator
username admin password 5 $1$ek7G4QLQ$YqLUwOCmeIaQFjFRPaznZ0 role network-admin
username all password 5 !! role network-operator
banner motd .
*****************
Username: admin
Password: cisco
*****************
ip domain-lookup
vlan dot1Q tag native
system default switchport
system jumbomtu 0
no logging event trunk-status enable
snmp-server user all engineID 128:0:0:9:3:0:80:86:159:0:13
snmp-server user admin auth md5 0x1c4527bd2809f91d57d71d49e3871168 priv 0x1c4527bd2809f91d57d71d49e3871168 localizedkey engineID 128:0:0:9:3:0:80:86:159:0:13
rmon event 1 log trap public description FATAL(1) owner PMON@FATAL
rmon event 2 log trap public description CRITICAL(2) owner PMON@CRITICAL
rmon event 3 log trap public description ERROR(3) owner PMON@ERROR
rmon event 4 log trap public description WARNING(4) owner PMON@WARNING
rmon event 5 log trap public description INFORMATION(5) owner PMON@INFO
snmp-server enable traps link
vrf context management
ip route 0.0.0.0/0 192.168.1.1
interface Ethernet2/1
shutdown
no switchport
interface Ethernet2/2
shutdown
no switchport
interface Ethernet2/3
shutdown
no switchport
interface Ethernet2/4
shutdown
no switchport
interface Ethernet2/5
shutdown
no switchport
interface Ethernet2/6
shutdown
no switchport
interface Ethernet2/7
shutdown
no switchport
interface Ethernet2/8
shutdown
no switchport
interface Ethernet2/9
shutdown
no switchport
interface mgmt0
vrf member management
ip address 192.168.100.10/24
line console
line vty
boot kickstart bootflash:/titanium-d1-kickstart.5.1.2.gbin
boot system bootflash:/titanium-d1.5.1.2.gbin
ip route 0.0.0.0/0 192.168.100.1
no system default switchport shutdown
</nc:data>
</nc:rpc-reply>
]]>]]>
Example 5 – Error Message
<?xml version="1.0"?>
<nc:rpc message-id="1" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="http://www.cisco.com/nxos:1.0:sysmgrcli">
<nc:get>
<nc:filter type="subtree">
<show>
<murphy />
</show>
</nc:filter>
</nc:get>
</nc:rpc>]]>]]>
<?xml version="1.0"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="http://www.cisco.com/nxos:1.0:sysmgrcli" message-id="1">
<nc:rpc-error>
<nc:error-type>application</nc:error-type>
<nc:error-tag>invalid-value</nc:error-tag>
<nc:error-severity>error</nc:error-severity>
<nc:error-message>Syntax error while parsing 'show murphy '</nc:error-message>
<nc:error-info>
<nc:bad-element>show</nc:bad-element>
</nc:error-info>
</nc:rpc-error>
</nc:rpc-reply>
]]>]]>
Example 6 – Retrieve SSH Keys
<?xml version="1.0"?>
<nc:rpc message-id="1" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="http://www.cisco.com/nxos:1.0:security_tree">
<nc:get>
<nc:filter type="subtree">
<show>
<ssh>
<key />
</ssh>
</show>
</nc:filter>
</nc:get>
</nc:rpc>]]>]]>
<?xml version="1.0"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="http://www.cisco.com/nxos:1.0:security_tree" message-id="1">
<nc:data>**************************************
rsa Keys generated:Sat May 10 13:53:00 2014
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC8leN2v8FrXVwxCbgOt4l64Ch5Zty7rkc8DOa4twNzP04DdsP0YE1UWRWOeFlY5WMI1KRR62ermxGVxVYUvl+RMZMBejRvTzvmAFpGjxihdfN6fvCLceRyPV4+G3lg1CIfH2bbl1CmN2kCh+cTc+eFT9jcdwrvncR+ABwpggYHzQ==
bitcount:1024
fingerprint:
44:9a:02:62:11:60:b2:15:e9:2b:36:08:1e:1c:eb:a5
**************************************
could not retrieve dsa key information
**************************************
</nc:data>
</nc:rpc-reply>
]]>]]>
Example 7 – Configure Interface
<?xml version="1.0"?>
<nc:rpc message-id="16" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="http://www.cisco.com/nxos:1.0:if_manager">
<nc:edit-config>
<nc:target>
<nc:running/>
</nc:target>
<nc:config>
<configure>
<__XML__MODE__exec_configure>
<interface>
<ethernet>
<interface>2/1</interface>
<__XML__MODE_if-ethernet>
<__XML__MODE_if-eth-base>
<ip>
<address>
<ip_addr>192.168.100.11 255.255.255.0</ip_addr>
</address>
</ip>
<description>
<desc_line>Configured by NETCONF</desc_line>
</description>
<no>
<shutdown/>
</no>
</__XML__MODE_if-eth-base>
</__XML__MODE_if-ethernet>
</ethernet>
</interface>
</__XML__MODE__exec_configure>
</configure>
</nc:config>
</nc:edit-config>
</nc:rpc>]]>]]>
<nf:rpc-reply xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nxos="http://www.cisco.com/nxos:1.0" message-id="110">
<nf:data/>
</nf:rpc-reply>
]]>]]>
Example 7 – Configure Interface Using Cisco NETCONF Extension
Cisco NX-OS supports an RPC operation named exec-command. The operation allows client applications to send CLI configuration and show commands and to receive responses to those commands as XML tags.
<?xml version="1.0"?>
<nf:rpc xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nxos="http://www.cisco.com/nxos:1.0" message-id="110">
<nxos:exec-command>
<nxos:cmd>configure terminal ;
interface ethernet 2/1 ;
ip address 192.168.100.15 255.255.255.0 ;
no shutdown </nxos:cmd>
</nxos:exec-command>
</nf:rpc>]]>]]>
<?xml version="1.0"?>
<nf:rpc-reply xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nxos="http://www.cisco.com/nxos:1.0" message-id="110">
<nf:data/>
</nf:rpc-reply>
]]>]]>
Example 7 – Show Interface Brief Using Cisco NETCONF Extension
<?xml version="1.0"?>
<nf:rpc xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nxos="http://www.cisco.com/nxos:1.0" message-id="110">
<nxos:exec-command>
<nxos:cmd>show interface brief</nxos:cmd>
</nxos:exec-command>
</nf:rpc>]]>]]>
<?xml version="1.0"?>
<nf:rpc-reply xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nxos="http://www.cisco.com/nxos:1.0" message-id="110">
<nf:data>
--------------------------------------------------------------------------------
Port VRF Status IP Address Speed MTU
--------------------------------------------------------------------------------
mgmt0 -- up 192.168.100.10 -- 1500
--------------------------------------------------------------------------------
Ethernet VLAN Type Mode Status Reason Speed Port
Interface Ch #
--------------------------------------------------------------------------------
Eth2/1 -- eth routed up none 1000(D) --
Eth2/2 -- eth routed down Administratively down auto(D) --
Eth2/3 -- eth routed down Administratively down auto(D) --
Eth2/4 -- eth routed down Administratively down auto(D) --
Eth2/5 -- eth routed down Administratively down auto(D) --
Eth2/6 -- eth routed down Administratively down auto(D) --
Eth2/7 -- eth routed down Administratively down auto(D) --
Eth2/8 -- eth routed down Administratively down auto(D) --
Eth2/9 -- eth routed down Administratively down auto(D) --
</nf:data>
</nf:rpc-reply>
]]>]]>
You may think that NETCONF is some exotic network device configuration protocol. That was true a number of years ago. However NETCONF is becoming quite popular and is supported by most network equipment vendors nowadays. Network Function Virtualization (NFV) is an emerging operational model where service providers want to virtualize entire classes of network node functions into building blocks that may be connected, or chained, together to create communication services. NFV is built around a very strong assumption of deep automation. This deep automation aligns directly with NETCONF with its standardized protocols and models, Another area where NETCONF is actively being used is with Software Defined Networking (SDN).
Enjoy!
