- Read Me First
- Configuring Cisco Networking Services
- CNS Configuration Agent
- Cisco Networking Services Config Retrieve Enhancement with Retry and Interval
- Cisco Networking Services Interactive CLI
- Command Scheduler (Kron)
- Network Configuration Protocol
- NETCONF over SSHv2
- NETCONF Access for Configurations over BEEP
Network Configuration Protocol
The Network Configuration Protocol (NETCONF) defines a simple mechanism through which a network device can be managed, configuration data can be retrieved, and new configuration data can be uploaded and manipulated. NETCONF uses Extensible Markup Language (XML)-based data encoding for the configuration data and protocol messages.
- Finding Feature Information
- Prerequisites for NETCONF
- Information About NETCONF
- How to Configure NETCONF
- Configuration Examples for NETCONF
- Additional References for NETCONF
- Feature Information for NETCONF
- Glossary
Finding Feature Information
Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table at the end of this module.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Prerequisites for NETCONF
A vty line must be available for each NETCONF session as specified by the netconf max-session command.
Information About NETCONF
NETCONF Notifications
NETCONF sends notifications of any configuration change over NETCONF. A notification is an event indicating that a configuration change has occurred. The change can be a new configuration, deleted configuration, or changed configuration. The notifications are sent at the end of a successful configuration operation as one message that shows the set of changes rather than showing individual messages for each line that is changed in the configuration.
How to Configure NETCONF
Configuring the NETCONF Network Manager Application
Delivering NETCONF Payloads
Use the following XML string to deliver the NETCONF payload to the network manager application:
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://www.cisco.com/cpi_10/schema" elementFormDefault="qualified" attributeFormDefault="unqualified" xmlns="http://www.cisco.com/cpi_10/schema" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <!--The following elements define the cisco extensions for the content of the filter element in a <get-config> request. They allow the client to specify the format of the response and to select subsets of the entire configuration to be included.--> <xs:element name="config-format-text-block"> <xs:annotation> <xs:documentation>If this element appears in the filter, then the client is requesting that the response data be sent in config command block format.</xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element ref="text-filter-spec" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="config-format-text-cmd"> <xs:complexType> <xs:sequence> <xs:element ref="text-filter-spec"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="config-format-xml"> <xs:annotation> <xs:documentation>When this element appears in the filter of a get-config request, the results are to be returned in E-DI XML format. The content of this element is treated as a filter.</xs:documentation> </xs:annotation> <xs:complexType> <xs:complexContent> <xs:extension base="xs:anyType"/> </xs:complexContent> </xs:complexType> </xs:element> <!--These elements are used in the filter of a <get> to specify operational data to return.--> <xs:element name="oper-data-format-text-block"> <xs:complexType> <xs:sequence> <xs:element name="show" type="xs:string" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="oper-data-format-xml"> <xs:complexType> <xs:sequence> <xs:any/> </xs:sequence> </xs:complexType> </xs:element> <!--When confing-format-text format is specified, the following describes the content of the data element in the response--> <xs:element name="cli-config-data"> <xs:complexType> <xs:sequence> <xs:element name="cmd" type="xs:string" maxOccurs="unbounded"> <xs:annotation> <xs:documentation>Content is a command. May be multiple lines.</xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="cli-config-data-block" type="xs:string"> <xs:annotation> <xs:documentation>The content of this element is the device configuration as it would be sent to a terminal session. It contains embedded newline characters that must be preserved as they represent the boundaries between the individual command lines</xs:documentation> </xs:annotation> </xs:element> <xs:element name="text-filter-spec"> <xs:annotation> <xs:documentation>If this element is included in the config-format-text element, then the content is treated as if the string was appended to the "show running-config" command line.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="cli-oper-data-block"> <xs:complexType> <xs:annotation> <xs:documentation> This element is included in the response to get operation. Content of this element is the operational data in text format.</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="item" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="exec"/> <xs:element name="show"/> <xs:element name="response"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:schema>
Formatting NETCONF Notifications
The NETCONF network manager application uses .xsd schema files to describe the format of the XML NETCONF notification messages that are sent between a NETCONF network manager application and a device running NETCONF over SSHv2 or BEEP. These files can be displayed in a browser or a schema reading tool. You can use these schemas to validate that the XML is correct. These schemas describe the format, not the content, of the data being exchanged.
NETCONF uses the <edit-config> function to load all of a specified configuration to a specified target configuration. When this new configuration is entered, the target configuration is not replaced. The target configuration is changed according to the data and requested operations of the requesting source.
The following are schemas for the NETCONF <edit-config> function in CLI, CLI block, and XML format.
NETCONF <edit-config> Request: CLI Format
<?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> <cli-config-data> <cmd>hostname test</cmd> <cmd>interface fastEthernet0/1</cmd> <cmd>ip address 192.168.1.1 255.255.255.0</cmd> </cli-config-data> </config> </edit-config> </rpc>]]>]]>
NETCONF <edit-config> Response: CLI Format
<?xml version="1.0" encoding="UTF-8"?> <rpc-reply message-id="101" xmlns="urn:ietf:params:netconf:base:1.0"> <ok/> </rpc-reply>]]>]]>
NETCONF <edit-config> Request: CLI-Block Format
<?xml version="1.0" encoding="UTF-8"?> <rpc message-id="netconf.mini.edit.3"> <edit-config> <target> <running/> </target> <config> <cli-config-data-block> hostname bob interface fastEthernet0/1 ip address 192.168.1.1 255.255.255.0 </cli-config-data-block> </config> </edit-config> </rpc>]]>]]>
NETCONF <edit-config> Response: CLI-Block Format
<?xml version="1.0" encoding=\"UTF-8\"?> <rpc-reply message-id="netconf.mini.edit.3" xmlns="urn:ietf:params:netconf:base:1.0"> <ok/> </rpc-reply>]]>]]>
The following are schemas for the NETCONF <get-config> function in CLI and CLI-block format.
NETCONF <get-config> Request: CLI Format
<?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> <config-format-text-cmd> <text-filter-spec> | inc interface </text-filter-spec> </config-format-text-cmd> </filter> </get-config> </rpc>]]>]]>
NETCONF <get-config> Response: CLI Format
<?xml version="1.0" encoding=\"UTF-8\"?> <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <data> <cli-config-data> <cmd>interface FastEthernet0/1</cmd> <cmd>interface FastEthernet0/2</cmd> </cli-config-data> </data> </rpc-reply>]]>]]>
NETCONF <get-config> Request: CLI-Block Format
<?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> <config-format-text-block> <text-filter-spec> | inc interface </text-filter-spec> </config-format-text-block> </filter> </get-config> </rpc>]]>]]>
NETCONF <get-config> Response: CLI-Block Format
<?xml version="1.0" encoding=\"UTF-8\"?> <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <data> <cli-config-data-block> interface FastEthernet0/1 interface FastEthernet0/2 </cli-config-data-block> </data> </rpc-reply>]]>]]>
NETCONF uses the <get> function to retrieve configuration and device-state information. The NETCONF <get> format is the equivalent of a Cisco IOS show command. The <filter> parameter specifies the portion of the system configuration and device-state data to retrieve. If the <filter> parameter is empty, nothing is returned.
The following are schemas for the <get> function in CLI and CLI-block format.
NETCONF <get> Request: CLI Format
<?xml version="1.0" encoding=\"UTF-8\"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get> <filter> <config-format-text-cmd> <text-filter-spec> | include interface </text-filter-spec> </config-format-text-cmd> <oper-data-format-text-block> <exec>show interfaces</exec> <exec>show arp</exec> </oper-data-format-text-block> </filter> </get> </rpc>]]>]]>
NETCONF <get> Response: CLI Format
<?xml version="1.0" encoding=\"UTF-8\"?> <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <data> <cli-config-data> <cmd>interface Loopback0</cmd> <cmd>interface GigabitEthernet0/1</cmd> <cmd>interface GigabitEthernet0/2</cmd> </cli-config-data> <cli-oper-data-block> <item> <exec>show interfaces</exec> <response> <!-- output of "show interfaces" ------> </response> </item> <item> <exec>show arp</exec> <response> <!-- output of "show arp" ------> </response> </item> </cli-oper-data-block> </data> </rpc-reply>]]>]]>
NETCONF <get> Request: CLI-Block Format
<?xml version="1.0" encoding=\"UTF-8\"?> <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get> <filter> <config-format-text-block> <text-filter-spec> | include interface </text-filter-spec> </config-format-text-block> <oper-data-format-text-block> <exec>show interfaces</exec> <exec>show arp</exec> </oper-data-format-text-block> </filter> </get> </rpc>]]>]]>
NETCONF <get> Response: CLI-Block Format
<?xml version="1.0" encoding=\"UTF-8\"?> <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <data> <cli-config-data-block> interface Loopback0 interface GigabitEthernet0/1 interface GigabitEthernet0/2 </cli-config-data-block> <cli-oper-data-block> <item> <exec>show interfaces</exec> <response> <!-- output of "show interfaces" ------> </response> </item> <item> <exec>show arp</exec> <response> <!-- output of "show arp" ------> </response> </item> </cli-oper-data-block> </data> </rpc-reply>]]>]]>
Monitoring and Maintaining NETCONF Sessions
Note |
1.
enable
2.
show
netconf
{counters |
session|
schema}
3.
debug
netconf
{all |
error}
4.
clear
netconf
{counters |
sessions}
DETAILED STEPS
Command or Action | Purpose | |
---|---|---|
Step 1 |
enable
Example: Device> enable |
Enables privileged EXEC mode. |
Step 2 |
show
netconf
{counters |
session|
schema}
Example: Device# show netconf counters |
Displays NETCONF information. |
Step 3 |
debug
netconf
{all |
error}
Example: Device# debug netconf error |
Enables debugging of NETCONF sessions. |
Step 4 |
clear
netconf
{counters |
sessions}
Example: Device# clear netconf sessions |
Clears NETCONF statistics counters and NETCONF sessions, and frees associated resources and locks. |
Configuration Examples for NETCONF
Example: Configuring the NETCONF Network Manager Application
The following example shows how to configure the NETCONF network manager application to invoke NETCONF as an SSH subsystem:
Unix Side: ssh-2 -s companyname@10.1.1.1 netconf
As soon as the NETCONF session is established, indicate the server capabilities by sending an XML document containing a <hello>:
<?xml version="1.0" encoding="UTF-8"?> <hello> <capabilities> <capability> urn:ietf:params:xml:ns:netconf:base:1.0 </capability> <capability> urn:ietf:params:ns:netconf:capability:startup:1.0 </capability> </capabilities> <session-id>4<session-id> </hello>]]>]]>
The client also responds by sending an XML document containing a <hello>:
<?xml version="1.0" encoding="UTF-8"?> <hello> <capabilities> <capability> urn:ietf:params:xml:ns:netconf:base:1.0 </capability> </capabilities> </hello>]]>]]>
Use the following XML string to enable the NETCONF network manager application to send and receive NETCONF notifications:
<?xml version="1.0" encoding="UTF-8" ?> <rpc message-id="9.0"><notification-on/> </rpc>]]>]]>
Use the following XML string to stop the NETCONF network manager application from sending or receiving NETCONF notifications:
<?xml version="1.0" encoding="UTF-8" ?> <rpc message-id="9.13"><notification-off/> </rpc>]]>]]>
Example: Monitoring NETCONF Sessions
The following is sample output from the show netconf counters command:
Device# show netconf counters NETCONF Counters Connection Attempts:0: rejected:0 no-hello:0 success:0 Transactions total:0, success:0, errors:0 detailed errors: in-use 0 invalid-value 0 too-big 0 missing-attribute 0 bad-attribute 0 unknown-attribute 0 missing-element 0 bad-element 0 unknown-element 0 unknown-namespace 0 access-denied 0 lock-denied 0 resource-denied 0 rollback-failed 0 data-exists 0 data-missing 0 operation-not-supported 0 operation-failed 0 partial-operation 0
The following is sample output from the show netconf session command:
Device# show netconf session (Current | max) sessions: 3 | 4 Operations received: 100 Operation errors: 99 Connection Requests: 5 Authentication errors: 2 Connection Failures: 0 ACL dropped : 30 Notifications Sent: 20
The output of the show netconf schema command displays the element structure for a NETCONF request and the resulting reply. This schema can be used to construct proper NETCONF requests and parse the resulting replies. The nodes in the schema are defined in RFC 4741. The following is sample output from the show netconf schema command:
Device# show netconf schema New Name Space 'urn:ietf:params:xml:ns:netconf:base:1.0' <VirtualRootTag> [0, 1] required <rpc-reply> [0, 1] required <ok> [0, 1] required <data> [0, 1] required <rpc-error> [0, 1] required <error-type> [0, 1] required <error-tag> [0, 1] required <error-severity> [0, 1] required <error-app-tag> [0, 1] required <error-path> [0, 1] required <error-message> [0, 1] required <error-info> [0, 1] required <bad-attribute> [0, 1] required <bad-element> [0, 1] required <ok-element> [0, 1] required <err-element> [0, 1] required <noop-element> [0, 1] required <bad-namespace> [0, 1] required <session-id> [0, 1] required <hello> [0, 1] required <capabilities> 1 required <capability> 1+ required <rpc> [0, 1] required <close-session> [0, 1] required <commit> [0, 1] required <confirmed> [0, 1] required <confirm-timeout> [0, 1] required <copy-config> [0, 1] required <source> 1 required <config> [0, 1] required <cli-config-data> [0, 1] required <cmd> 1+ required <cli-config-data-block> [0, 1] required <xml-config-data> [0, 1] required <Device-Configuration> [0, 1] required <> any subtree is allowed <candidate> [0, 1] required <running> [0, 1] required <startup> [0, 1] required <url> [0, 1] required <target> 1 required <candidate> [0, 1] required <running> [0, 1] required <startup> [0, 1] required <url> [0, 1] required <delete-config> [0, 1] required <target> 1 required <candidate> [0, 1] required <running> [0, 1] required <startup> [0, 1] required <url> [0, 1] required <discard-changes> [0, 1] required <edit-config> [0, 1] required <target> 1 required <candidate> [0, 1] required <running> [0, 1] required <startup> [0, 1] required <url> [0, 1] required <default-operation> [0, 1] required <test-option> [0, 1] required <error-option> [0, 1] required <config> 1 required <cli-config-data> [0, 1] required <cmd> 1+ required <cli-config-data-block> [0, 1] required <xml-config-data> [0, 1] required <Device-Configuration> [0, 1] required <> any subtree is allowed <get> [0, 1] required <filter> [0, 1] required <config-format-text-cmd> [0, 1] required <text-filter-spec> [0, 1] required <config-format-text-block> [0, 1] required <text-filter-spec> [0, 1] required <config-format-xml> [0, 1] required <oper-data-format-text-block> [0, 1] required <exec> [0, 1] required <show> [0, 1] required <oper-data-format-xml> [0, 1] required <exec> [0, 1] required <show> [0, 1] required <get-config> [0, 1] required <source> 1 required <config> [0, 1] required <cli-config-data> [0, 1] required <cmd> 1+ required <cli-config-data-block> [0, 1] required <xml-config-data> [0, 1] required <Device-Configuration> [0, 1] required <> any subtree is allowed <candidate> [0, 1] required <running> [0, 1] required <startup> [0, 1] required <url> [0, 1] required <filter> [0, 1] required <config-format-text-cmd> [0, 1] required <text-filter-spec> [0, 1] required <config-format-text-block> [0, 1] required <text-filter-spec> [0, 1] required <config-format-xml> [0, 1] required <kill-session> [0, 1] required <session-id> [0, 1] required <lock> [0, 1] required <target> 1 required <candidate> [0, 1] required <running> [0, 1] required <startup> [0, 1] required <url> [0, 1] required <unlock> [0, 1] required <target> 1 required <candidate> [0, 1] required <running> [0, 1] required <startup> [0, 1] required <url> [0, 1] required <validate> [0, 1] required <source> 1 required <config> [0, 1] required <cli-config-data> [0, 1] required <cmd> 1+ required <cli-config-data-block> [0, 1] required <xml-config-data> [0, 1] required <Device-Configuration> [0, 1] required <> any subtree is allowed <candidate> [0, 1] required <running> [0, 1] required <startup> [0, 1] required <url> [0, 1] required <notification-on> [0, 1] required <notification-off> [0, 1] required
Additional References for NETCONF
Related Documents
Related Topic |
Document Title |
---|---|
Cicso IOS commands |
|
NETCONF commands: complete command syntax, command mode, command history, defaults, usage guidelines, and examples |
Cisco IOS Cisco Networking Services Command Reference |
Security and IP access lists commands: complete command syntax, command mode, command history, defaults, usage guidelines, and examples |
Cisco IOS Security Command Reference |
Standards and RFCs
Standard/RFC |
Title |
---|---|
RFC 4251 |
The Secure Shell (SSH) Protocol Architecture |
RFC 4252 |
The Secure Shell (SSH) Authentication Protocol |
RFC 4741 |
NETCONF Configuration Protocol |
RFC 4744 |
Using the NETCONF Protocol over the Blocks Extensible Exchange Protocol (BEEP) |
Technical Assistance
Description |
Link |
---|---|
The Cisco Support and Documentation website provides online resources to download documentation, software, and tools. Use these resources to install and configure the software and to troubleshoot and resolve technical issues with Cisco products and technologies. Access to most tools on the Cisco Support and Documentation website requires a Cisco.com user ID and password. |
Feature Information for NETCONF
The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Feature Name |
Releases |
Feature Information |
---|---|---|
NETCONF |
The NETCONF protocol defines a simple mechanism through which a network device can be managed, configuration data can be retrieved, and new configuration data can be uploaded and manipulated. NETCONF uses Extensible Markup Language (XML)-based data encoding for the configuration data and protocol messages. The following commands were introduced or modified by this feature: clear netconf, debug netconf, show netconf. |
|
NETCONF XML PI |
The NETCONF protocol was enhanced, adding format attribute support for all Cisco IOS exec commands. The following commands were modified: clear netconf, debug netconf, and show netconf. |
Glossary
BEEP —Blocks Extensible Exchange Protocol. A generic application protocol framework for connection-oriented, asynchronous interactions.
NETCONF —Network Configuration Protocol. A protocol that defines a simple mechanism through which a network device can be managed, configuration data can be retrieved, and new configuration data can be uploaded and manipulated.
SASL —Simple Authentication and Security Layer. An Internet standard method for adding authentication support to connection-based protocols. SASL can be used between a security appliance and a Lightweight Directory Access Protocol (LDAP) server to secure user authentication.
SSHv2 —Secure Shell Version 2. SSH runs on top of a reliable transport layer and provides strong authentication and encryption capabilities. SSHv2 provides a means to securely access and securely execute commands on another computer over a network.
TLS —Transport Layer Security. An application-level protocol that provides for secure communication between a client and server by allowing mutual authentication, the use of hash for integrity, and encryption for privacy. TLS relies upon certificates, public keys, and private keys.
XML —Extensible Markup Language. A standard maintained by the World Wide Web Consortium (W3C) that defines a syntax that lets you create markup languages to specify information structures. Information structures define the type of information (for example, subscriber name or address), not how the information appears (bold, italic, and so on). External processes can manipulate these information structures and publish them in a variety of formats. XML allows you to define your own customized markup language.