Cisco NX-OS XML Interface User Guide - Using the XML Management Interface [Cisco NX-OS Software]

Table Of Contents

Using the XML Management Interface

Information About the XML Management Interface

NETCONF Layers

SSH xmlagent

Licensing Requirements for the XML Management Interface

Prerequisites to Using the XML Management Interface

Using the XML Management Interface

Configuring SSH and the XML Server Options through the CLI

Starting an SSH Session

Sending the Hello Message

Obtaining the XSD Files

Sending an XML Document to the XML Server

Creating NETCONF XML Instances

RPC Request Tag <rpc>

NETCONF Operations Tags

Device Tags

Extended NETCONF Operations

NETCONF Replies

Example XML Instances

NETCONF close-session Instance

NETCONF kill-session Instance

NETCONF edit-config Instance

Additional References

Standards

RFCs

Using the XML Management Interface

This chapter describes how to use the XML management interface to configure devices.

This chapter includes the following sections:

•Information About the XML Management Interface

•Licensing Requirements for the XML Management Interface

•Prerequisites to Using the XML Management Interface

•Using the XML Management Interface

•Example XML Instances

•Additional References

Information About the XML Management Interface

You can use the XML management interface to configure a device. The interface uses the XML-based Network Configuration Protocol (NETCONF) that allows you to manage devices and communicate over the interface with an XML management tool or a program. The Cisco NX-OS implementation of NETCONF requires you to use a Secure Shell (SSH) session for communication with the device.

NETCONF is implemented with an XML Schema (XSD) that allows you to enclose device configuration elements within a remote procedure call (RPC) message. From within an RPC message, you select one of the NETCONF operations that matches the type of command that you want the device to execute. You can configure the entire set of CLI commands on the device with NETCONF. For information about using NETCONF, see the "Creating NETCONF XML Instances" section.

For more information about NETCONF, see RFC 4741.

For more information about using the NETCONF protocol over the Secure Shell (SSH), see RFC 4742.

This section includes the following topics:

•NETCONF Layers

•SSH xmlagent

NETCONF Layers

Table 1-1 shows the NETCONF layers.

Table 1-1 NETCONF Layers

Layer

Example

Transport protocol

SSHv2

RPC

<rpc>, <rpc-reply>

Operations

<get-config>, <edit-config>

Content

show or configuration command

Following is a description of the four NETCONF layers:

•SSH transport protocol—Provides a secure, encrypted connection between a client and server.

•RPC tag—Introduces a configuration command from the requestor and the corresponding reply from the XML server.

•NETCONF operation tag—Indicates the type of configuration command.

•Content—Indicates the XML representation of the feature that you want to configure.

SSH xmlagent

The device software provides a Secure Shell (SSH) service called xmlagent that supports NETCONF over SSH Version 2.

Note The xmlagent service is referred to as the XML server in the Cisco NX-OS software.

NETCONF over SSH is initiated by the exchange of a hello message between the client and the XML server. After the initial exchange, the client sends XML requests, which the server responds to with XML responses. The client and server terminate requests and responses with the character sequence ]]>]]>. Because this character sequence is not valid in XML, the client and the server can interpret when the messages end, which keeps communication synchronized.

The XML schemas that define XML configuration instances you can use are described in the "Creating NETCONF XML Instances" section.

Licensing Requirements for the XML Management Interface

The following table shows the licensing requirements for this feature:

Product

License Requirement

Cisco NX-OS

The XML management interface requires no license. Any feature not included in a license package is bundled with the Cisco NX-OS system images and is provided at no extra charge to you. For a complete explanation of the Cisco NX-OS licensing scheme, see the Cisco NX-OS Licensing Guide.

Prerequisites to Using the XML Management Interface

The XML management interface has the following prerequisites:

•SSHv2 installed on the client PC

•XML management tool that supports NETCONF over SSH installed on the client PC

•Options are set for the XML server on the device

Using the XML Management Interface

This section describes how to manually configure and use the XML management interface. You use the XML management interface with the default settings on the device.

This section includes the following topics:

•Configuring SSH and the XML Server Options through the CLI

•Starting an SSH Session

•Sending the Hello Message

•Obtaining the XSD Files

•Sending an XML Document to the XML Server

•Creating NETCONF XML Instances

Configuring SSH and the XML Server Options through the CLI

By default, the SSH server is enabled on the device. If you disable SSH, you must enable it before you start an SSH session on the client PC.

You can configure XML server options to control the number of concurrent sessions and the timeout for active sessions. You can also enable XML document validation and terminate XML sessions.

Note The XML server timeout applies only to active sessions.

For more information about configuring SSH, see the Cisco NX-OS Security Configuration Guide for your platform.

For more information about the XML commands, see one of the following documents:

•Cisco Nexus 7000 Series NX-OS System Management Configuration Guide, Release 5.x.

•Cisco Nexus 6000 Series NX-OS System Management Configuration Guide, Release 6.x

•Cisco Nexus 5000 Series NX-OS System Management Configuration Guide, Release 5.x

•Cisco Nexus 3000 Series NX-OS System Management Configuration Guide, Release 5.x

PROCEDURE

Command

Purpose

Step 1

configuration terminal

Enters configuration mode.

Step 2

show xml server status

(Optional) Displays information about XML server settings and active XML server sessions. You can find session numbers in the command output.

Step 3

xml server validate all

Causes validation of XML documents for the specified server session.

Step 4

xml server terminate session

Terminates the specified XML server session.

Step 5

no feature ssh

(Optional) Disables the SSH server so that you can generate keys.

For information about generating keys, see Configuring SSH and the XML Server Options through the CLI.

Step 6

feature ssh server

Enables the SSH server.

The default is enabled.

Step 7

show ssh server

(Optional) Displays the status of the SSH server.

Step 8

xml server max-session sessions

Sets the number of allowed XML server sessions.

The default is 8. The range is from 1 to 8.

Step 9

xml server timeout seconds

Sets the number of seconds after which the XML server session is terminated.

The default is 1200 seconds. The range is from 1 to 1200.

Step 10

show xml server status

(Optional) Displays information about the XML server settings and active XML server sessions.

Step 11

copy running-config startup-config

(Optional) Saves the running configuration to the startup configuration.

The following example shows how to configure SSH and the XML Server Options through the CLI:

switch# configuration terminal
switch(config)# xml server validate all
switch(config)# xml server terminate 8665
switch(config)# no feature ssh
switch(config)# feature ssh
switch(config)# xml server max-session 6
switch(config)# xml server timeout 2400
switch(config)# copy running-config startup-config

Starting an SSH Session

You can start an SSHv2 session on the client PC with a command similar to the following:
ssh2 username@ip-address -s xmlagent
You enter the login username, the IP address of the device, and the service to which to connect. The xmlagent service is referred to as the XML server in the device software.

Note The SSH command syntax may differ from the SSH software on the client PC.

If you do not receive a hello message from the XML server, verify the following conditions:

•The SSH server is enabled on the device

•The XML server max-sessions option is adequate to support the number of SSH connections to the device

•The active XML server sessions on the device are not all in use

Sending the Hello Message

When you start an SSH session to the XML server, the server responds immediately with a hello message that informs the client of the server's capabilities. You must advertise your capabilities to the server with a hello message before the server will process any other requests. The XML server supports only base capabilities and expects support only for the base capabilities from the client.

Example 1-1 and Example 1-2 show sample hello messages from the server and client.

Note You must end all XML documents with ]]>]]> to support synchronization in NETCONF over SSH.

Example 1-1 Hello Message from the Server
<?xml version="1.0"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capabilities>
  <capability>urn:ietf:params:xml:ns:netconf:base:1.0</capability>
  </capabilities>
  <session-id>25241</session-id>
</hello>]]>]]>
Example 1-2 Hello Message from the Client
<?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>]]>]]>
Obtaining the XSD Files

To obtain a copy of the XSD files, follow these steps:

Step 1 From your browser, navigate to the Cisco software download site at the following URL:

:http://www.cisco.com/public/sw-center/index.shtml

The Download Software page opens.

Step 2 In the Select a Software Product Category list, choose Switches Software.

Step 3 If you are not already logged in as a registered Cisco user, you are prompted to log in now.

Step 4 Under the Select a Device list, expand Data Center Switches by clicking the plus sign.

Step 5 Expand the product series by clicking the plus sign.

Step 6 Choose a product.

Step 7 From the Select a Software Type list, choose NX-OS XML Schema Definition.

Step 8 Under Select a Release, expand the releases by clicking the plus sign.

Step 9 Choose the release.

Step 10 Choose the Cisco NX-OS XSD gzip file to the right of the release.

Step 11 If you are requested, follow the instructions to apply for eligibility to download strong encryption software images.

Step 12 Click Download.

The Cisco End User License Agreement opens.

Step 13 Click Agree and follow the instructions to download the file to your PC.

Sending an XML Document to the XML Server

To 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. Although typically, you will use an automated method to send XML documents to the XML server, you can verify the SSH connection to the XML server with this method.

Follow these guidelines for this method:

•Verify that the XML server sent the hello message immediately after you started the SSH session by looking for the hello message text in the command shell output.

•Send the client hello message before you send any XML requests. Because the XML server sends the hello response immediately, no additional response is sent after you send the client hello message.

•Always terminate the XML document with the character sequence ]]>]]>.

Creating NETCONF XML Instances

You can create NETCONF XML instances by enclosing XML device elements within an RPC tag and NETCONF operation tags. The XML device elements are defined in feature-based XML schema definition (XSD) files, enclosing available CLI commands in an XML format.

Example 1-3 shows the tags used in the NETCONF XML request in framework context. Tag lines are marked with the following letter codes:

•X —XML declaration

•R—RPC request tag

•N—NETCONF operation tags

•D—Device tags

Example 1-3 NETCONF XML Framework Context
X <?xml version="1.0"?>
R <nc:rpc message-id="1" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
R  xmlns="http://www.cisco.com/nxos:1.0:nfcli">
N  <nc:get>
N    <nc:filter type="subtree">
D      <show>
D        <xml>
D          <server>
D            <status/>
D          </server>
D        </xml>
D      </show>
N    </nc:filter>
N  </nc:get>
R </nc:rpc>]]>]]>
Note You will need to use your own XML editor or XML management interface tool to create XML instances.

This section includes the following topics:

•RPC Request Tag <rpc>

•NETCONF Operations Tags

•Device Tags

RPC Request Tag <rpc>

All NETCONF XML instances must begin with the RPC request tag <rpc>. Example 1-4 shows the <rpc> element with its required message-id attribute. The message-id attribute is replicated in the <rpc-reply> and can be used to correlate requests and replies. The <rpc> node also contains XML namespace declarations:

NETCONF namespace declaration—The <rpc> and NETCONF tags are defined in the "urn:ietf:params:xml:ns:netconf:base:1.0" namespace, present in the netconf.xsd schema file.

Device namespace declaration—Device tags encapsulated by the <rpc> and NETCONF tags are defined in other namespaces. Device namespaces are feature oriented. Cisco NX-OS feature tags are defined in different namespaces. Example 1-4 is an example using the nfcli feature; it declares the device namespace "xmlns=http://www.cisco.com/nxos:1.0:nfcli". nfcli.xsd contains this namespace definition. For more information, see "Obtaining the XSD Files" section.

Example 1-4 RPC Request Tag <rpc>
<nc:rpc message-id="315" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns=http://www.cisco.com/nxos:1.0:nfcli">
...
</nc:rpc>]]>]]>
Example 1-5 is an example of a configuration request.

Example 1-5 Configuration Request
<?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/30</interface>
              <__XML__MODE_if-ethernet>
                <__XML__MODE_if-eth-base>
                  <description>
                    <desc_line>Marketing Network</desc_line>
                  </description>
                </__XML__MODE_if-eth-base>
              </__XML__MODE_if-ethernet>
            </ethernet>
          </interface>
        </__XML__MODE__exec_configure>
      </configure>
    </nc:config>
  </nc:edit-config>
</nc:rpc>]]>]]>
__XML__MODE tags are used internally by the NETCONF agent. Some tags are only present as children of a certain __XML__MODE. By examining the schema file, you should be able to find the correct mode tag that leads to the tags representing in XML the CLI command.

NETCONF Operations Tags

NETCONF provides the configuration operations listed in Table 1-2.

Table 1-2 NETCONF Operations in Cisco NX-OS

NETCONF Operation

Description

Example

close-session

Closes the current XML server session.

NETCONF close-session Instance

commit

Operation not supported.

—

copy-config

Operation not supported.

—

delete-config

Operation not supported.

—

edit-config

Configures features in the running configuration of the device. You use this operation for configuration commands.

NETCONF edit-config Instance

get

Receives configuration information from the device. You use this operation for show commands. The source of the data is the running configuration.

Example 1-3

get-config

Operation not supported.

—

kill-session

Closes the specified XML server session. You cannot close your own session. See the close-session NETCONF operation.

NETCONF kill-session Instance

lock

Operation not supported.

—

unlock

Operation not supported.

—

validate

Operation not supported.

—

Device Tags

The XML device elements represent the available CLI commands in XML format. The feature-specific schema files contain the XML tags for CLI commands of that particular feature. See the "Obtaining the XSD Files" section. Using this schema, it is possible to build an XML instance. For example, the relevant portions of the nfcli.xsd schema file that were used to build Example 1-3 are shown in Example 1-6 and Example 1-7.

Example 1-6 show xml Device Tags
<xs:element name="show" type="show_type_Cmd_show_xml"/>
  <xs:complexType name="show_type_Cmd_show_xml">
    <xs:annotation>
      <xs:documentation>to display xml agent information</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:choice maxOccurs="1">
        <xs:element name="xml" minOccurs="1" type="xml_type_Cmd_show_xml"/>
        <xs:element name="debug" minOccurs="1" type="debug_type_Cmd_show_debug"/>
      </xs:choice>
    </xs:sequence>
    <xs:attribute name="xpath-filter" type="xs:string"/>
    <xs:attribute name="uses-namespace" type="nxos:bool_true"/>
  </xs:complexType>
Example 1-7 server status Device Tags
<xs:complexType name="xml_type_Cmd_show_xml">
    <xs:annotation>
      <xs:documentation>xml agent</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="server" minOccurs="1" type="server_type_Cmd_show_xml"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="server_type_Cmd_show_xml">
    <xs:annotation>
      <xs:documentation>xml agent server</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:choice maxOccurs="1">
        <xs:element name="status" minOccurs="1" type="status_type_Cmd_show_xml"/>
        <xs:element name="logging" minOccurs="1" type="logging_type_Cmd_show_logging_facility"/>
      </xs:choice>
    </xs:sequence>
  </xs:complexType>
Example 1-8 shows the device tag response.

Example 1-8 Device Tag Response
<xs:complexType name="status_type_Cmd_show_xml">
    <xs:annotation>
      <xs:documentation>display xml agent information</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="__XML__OPT_Cmd_show_xml___readonly__" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:group ref="og_Cmd_show_xml___readonly__" minOccurs="0" maxOccurs="1"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
  <xs:group name="og_Cmd_show_xml___readonly__">
    <xs:sequence>
      <xs:element name="__readonly__" minOccurs="1" type="__readonly___type_Cmd_show_xml"/>
    </xs:sequence>
  </xs:group>
  <xs:complexType name="__readonly___type_Cmd_show_xml">
    <xs:sequence>
      <xs:group ref="bg_Cmd_show_xml_operational_status" maxOccurs="1"/>
      <xs:group ref="bg_Cmd_show_xml_maximum_sessions_configured" maxOccurs="1"/>
      <xs:group ref="og_Cmd_show_xml_TABLE_sessions" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
Note "__XML__OPT_Cmd_show_xml___readonly__" is optional. This tag represents the response. For more information on responses see the "RPC Response Tag" section.

You can use the | XML option to find out where you can find the tags you should use to execute a <get>. Example 1-9 shows an example of the | XML option.

Example 1-9 | XML Example
Switch#> show xml server status | xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<nf:rpc-reply xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" 
xmlns="http://www.cisco.com/nxos:1.0:nfcli">
 <nf: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>
       </__readonly__>
      </__XML__OPT_Cmd_show_xml___readonly__>
     </status>
    </server>
   </xml>
  </show>
 </nf:data>
</nf:rpc-reply>
]]>]]>
From this response, you can see that the namespace defining tags to execute operations on this component is http://www.cisco.com/nxos:1.0:nfcli and the nfcli.xsd file can be used to build requests for this feature.

You can enclose the NETCONF operation tags and the device tags within the RPC tag. You then follow the </rpc> end-tag with the XML termination character sequence.

Extended NETCONF Operations

Beginning in Release 5.2(1), Cisco NX-OS supports a new <rpc> operation named <exec-command>. The operation allows client applications to send CLI configure and show commands but receive the response to the command as XML tags.

Example 1-10 shows an example of the tags used to configure an interface. Tag lines are marked with the following letter codes:

•X —XML declaration

•R—RPC request tag

•EO—Extended Operation

Example 1-10 Configuration CLI commands sent through <exec-command>
X <?xml version="1.0"?>
R <nf:rpc xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" 
  xmlns:nxos="http://www.cisco.com/nxos:1.0" message-id="3">
EO   <nxos:exec-command>
EO      <nxos:cmd>conf t ; interface ethernet 2/1 </nxos:cmd>
EO      <nxos:cmd>channel-group 2000 ; no shut; </nxos:cmd>
EO   </nxos:exec-command>
R </nf:rpc>]]>]]>
Example Example 1-11 of the response to the operation.

Example 1-11 Response to CLI commands sent through <exec-command>
<?xml version="1.0" encoding="ISO-8859-1"?>
 <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="3">
  <nf:ok/>
 </nf:rpc-reply>
]]>]]> 
In Example 1-12, the show CLI commands that are sent through the<exec-command> show how the <exec-command> can be used to retrieve data.

Example 1-12 show CLI commands sent via <exec-command>
<?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>]]>]]>
Example 1-13 shows the response to the operation.

Example 1-13
<?xml version="1.0" encoding="ISO-8859-1"?>
<nf:rpc-reply xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" 
  xmlns:nxos="http://www.cisco.com/nxos:1.0" 
xmlns:mod="http://www.cisco.com/nxos:1.0:if_manager" message-id="110">
  <nf:data>
    <mod:show>
      <mod:interface>
        <mod:__XML__OPT_Cmd_show_interface_brief___readonly__>
          <mod:__readonly__>
            <mod:TABLE_interface>
              <mod:ROW_interface>
                <mod:interface>mgmt0</mod:interface>
                <mod:state>up</mod:state>
                <mod:ip_addr>172.23.152.20</mod:ip_addr>
                <mod:speed>1000</mod:speed>
                <mod:mtu>1500</mod:mtu>
              </mod:ROW_interface>
              <mod:ROW_interface>
                <mod:interface>Ethernet2/1</mod:interface>
                <mod:vlan>--</mod:vlan>
                <mod:type>eth</mod:type>
                <mod:portmode>routed</mod:portmode>
                <mod:state>down</mod:state>
                <mod:state_rsn_desc>Administratively down</mod:state_rsn_desc>
                <mod:speed>auto</mod:speed>
                <mod:ratemode>D</mod:ratemode>
              </mod:ROW_interface>
            </mod:TABLE_interface>
          </mod:__readonly__>
        </mod:__XML__OPT_Cmd_show_interface_brief___readonly__>
      </mod:interface>
    </mod:show>
  </nf:data>
</nf:rpc-reply>
]]>]]> 
Response to the show CLI commands sent through <exec-command>

Table 1-3 Tags

Tag

Description

<exec-command>.

Executes a CLI command.

<cmd>

Contains the CLI command. A command can be a show or configuration command. Multiple configuration commands should be separated by a semicolon " ; ". Multiple show commands are not supported. You can send multiple configuration commands in different <cmd> tags as part of the same request. For more information, see Example 1-10.

Table 1-3 provides a detailed explanation of the operation tags.

Replies to configuration commands that are sent through the <cmd> tag are as follows:

•<nf:ok> : All configure commands are executed successfully.

•<nf:rpc-error> : Some commands have failed. The operation stops on the first error and the <nf:rpc-error> sub-tree provides more information on what configuration failed. Notice that any configuration executed before the failed command would have been applied to the running configuration.

Example 1-14 shows a failed configuration.

Example 1-14 Failed Configuration
<?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="3">
    <nxos:exec-command>
      <nxos:cmd>configure terminal ; interface ethernet2/1 </nxos:cmd>
      <nxos:cmd>ip address 1.1.1.2/24 </nxos:cmd>
      <nxos:cmd>no channel-group 2000 ; no shut; </nxos:cmd>
    </nxos:exec-command>
  </nf:rpc>]]>]]>
<?xml version="1.0" encoding="ISO-8859-1"?>
<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="3">
  <nf:rpc-error>
    <nf:error-type>application</nf:error-type>
    <nf:error-tag>invalid-value</nf:error-tag>
    <nf:error-severity>error</nf:error-severity>
    <nf:error-message>Ethernet2/1: not part of port-channel 2000
</nf:error-message>
    <nf:error-info>
      <nf:bad-element>cmd</nf:bad-element>
    </nf:error-info>
  </nf:rpc-error>
</nf:rpc-reply>
]]>]]>
As a result of a command execution, the IP address of the interface is set but the administrative state is not modified (the no shut command is not executed) becasue the no port-channel 2000 command results in an error.

The <rpc-reply> as a result of a show command that is sent through the <cmd> tag contains the XML output of the show command.

You cannot combine configuration and show commands on the same <exec-command> instance. Example 1-15 show a configuration and show command are combined in the same instance.

Example 1-15
<?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>conf t ; interface ethernet 2/1 ; ip address 1.1.1.4/24 ; show xml 
server status </nxos:cmd>
    </nxos:exec-command>
  </nf:rpc>]]>]]>
<?xml version="1.0" encoding="ISO-8859-1"?>
<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:rpc-error>
    <nf:error-type>application</nf:error-type>
    <nf:error-tag>invalid-value</nf:error-tag>
    <nf:error-severity>error</nf:error-severity>
    <nf:error-message>Error: cannot mix config and show in exec-command. Config cmds 
before the show were executed.
 Cmd:show xml server status</nf:error-message>
    <nf:error-info>
      <nf:bad-element>cmd</nf:bad-element>
    </nf:error-info>
  </nf:rpc-error>
</nf:rpc-reply>
]]>]]>
A combination of configuration and show command

The show commands must be sent in its own <exec-command> instances as show in Example 1-16.

Example 1-16
<?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 xml server status ; show xml server status  </nxos:cmd>
    </nxos:exec-command>
  </nf:rpc>]]>]]>
<?xml version="1.0" encoding="ISO-8859-1"?>
<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:rpc-error>
    <nf:error-type>application</nf:error-type>
    <nf:error-tag>invalid-value</nf:error-tag>
    <nf:error-severity>error</nf:error-severity>
    <nf:error-message>Error: show cmds in exec-command shouldn't be followed by anything
</nf:error-message>
    <nf:error-info>
      <nf:bad-element>&lt;cmd&gt;</nf:bad-element>
    </nf:error-info>
  </nf:rpc-error>
</nf:rpc-reply>
]]>]]>
Show CLI commands sent via <exec-command>

NETCONF Replies

For every XML request sent by the client, the XML server sends an XML response enclosed in the RPC response tag <rpc-reply>.

This section contains the following topics:

•RPC Response Tag

•Interpreting Tags Encapsulated in the <Data> Tag

RPC Response Tag

Example 1-17 shows the RPC response tag <rpc-reply>.

Example 1-17 RPC Response Tag <rpc-reply>
<nc:rpc-reply message-id="315" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns=http://www.cisco.com/nxos:1.0:nfcli">
  <ok/>
</nc:rpc-reply>]]>]]>
The elements <ok>, <data>, or <rpc-error> can appear in the RPC response. Table 1-4 describes the RPC response elements that can appear in the <rpc-reply> tag.

Table 1-4 RPC Response Elements

Element

Description

<ok>

The RPC request completed successfully. This element is used when no data is returned in the response.

<data>

The RPC request completed successfully. The data associated with the RPC request is enclosed in the <data> element.

<rpc-error>

The RPC request failed. Error information is enclosed in the <rpc-error> element.

Interpreting Tags Encapsulated in the <Data> Tag

The device tags encapsulated by the <data> tag contain the request followed by the response. A client application can safely ignore all tags before the <readonly> tag. Example 1-18 shows an example.

Example 1-18 <rpc-reply><data>
<?xml version="1.0" encoding="ISO-8859-1"?>
<nf:rpc-reply xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" 
xmlns="http://www.cisco.com/nxos:1.0:if_manager">
 <nf:data>
  <show>
   <interface>
    <__XML__OPT_Cmd_show_interface_brief___readonly__>
     <__readonly__>
      <TABLE_interface>
       <ROW_interface>
        <interface>mgmt0</interface>
        <state>up</state>
        <ip_addr>xx.xx.xx.xx</ip_addr>
        <speed>1000</speed>
        <mtu>1500</mtu>
       </ROW_interface>
       <ROW_interface>
        <interface>Ethernet2/1</interface>
        <vlan>--</vlan>
        <type>eth</type>
        <portmode>routed</portmode>
        <state>down</state>
        <state_rsn_desc>Administratively down</state_rsn_desc>
        <speed>auto</speed>
        <ratemode>D</ratemode>
       </ROW_interface>
      </TABLE_interface>
     </__readonly__>
    </__XML__OPT_Cmd_show_interface_brief___readonly__>
   </interface>
  </show>
 </nf:data>
</nf:rpc-reply>
]]>]]>
<__XML__OPT.*> and <__XML__BLK.*> appear in responses and are sometimes used in requests. These tags are used by the NETCONF agent and are present in responses after the <__readonly__> tag. They are necessary in requests and should be added according to the schema file to reach the XML tag that represents the CLI command.

Example XML Instances

This section provides examples of XML instances.

This section includes the following example instances:

•NETCONF close-session Instance

•NETCONF kill-session Instance

•NETCONF edit-config Instance

NETCONF close-session Instance

The following example shows the use of NETCONF close-session.

Example 1-19 shows the close-session request. Example 1-20 shows the close-session response.

Example 1-19 close-session Request
<?xml version="1.0"?>
<nc:rpc message-id="101" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="http://www.cisco.com/nxos:1.0">
  <nc:close-session/>
</nc:rpc>]]>]]>
Example 1-20 close-session Response
<?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" message-id="101">
  <nc:ok/>
</nc:rpc-reply>]]>]]>
NETCONF kill-session Instance

The following example shows the use of NETCONF kill-session.

Example 1-21 shows the kill-session request. Example 1-22 shows the kill-session response.

Example 1-21 kill-session Request
<?xml version="1.0"?>
<nc:rpc message-id="101" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="http://www.cisco.com/nxos:1.0">
<nc:kill-session>
<nc:session-id>25241</nc:session-id>
</nc:kill-session>
</nc:rpc>]]>]]>
Example 1-22 kill-session Response
<?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" message-id="101">
<nc:ok/>
</nc:rpc-reply>]]>]]>
NETCONF edit-config Instance

The following example shows the use of NETCONF edit-config.

Example 1-23 shows the edit-config request. Example 1-24 shows the edit-config response.

Example 1-23 edit-config Request
<?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/30</interface>
              <__XML__MODE_if-ethernet>
                <__XML__MODE_if-eth-base>
                  <description>
                    <desc_line>Marketing Network</desc_line>
                  </description>
                </__XML__MODE_if-eth-base>
              </__XML__MODE_if-ethernet>
            </ethernet>
          </interface>
        </__XML__MODE__exec_configure>
      </configure>
    </nc:config>
  </nc:edit-config>
</nc:rpc>]]>]]>
Example 1-24 edit-config Response
<?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:if_manager" message-id="16">
  <nc:ok/>
</nc:rpc-reply>]]>]]>
Additional References

This section provides additional information related to implementing the XML management interface.

This section contains the following topics:

•Standards

•RFCs

Standards

Standards

Title

No new or modified standards are supported by this feature. Support for existing standards has not been modified by this feature.

—

RFCs

RFCs

Title

RFC 4741

NETCONF Configuration Protocol

RFC 4742

Using the NETCONF Configuration Protocol over Secure SHell (SSH)