Cisco Nexus 1000V XML API Configuration Guide, Release 4.0(4)SV1(3)
Configuring XML Requests
Download this chapter
Configuring XML Requests Configuring XML Requests
Download the complete book
Cisco Nexus 1000V XML API Configuration Guide, Release 4.0(4)SV1(3) Cisco Nexus 1000V XML API Configuration Guide, Release 4.0(4)SV1(3) (PDF - 320 KB)
 Feedback

Table Of Contents

Configuring XML Requests

Prerequisites

Guidelines and Limitations

Starting a Session with the XML Server

Creating an XML Request

Manually Sending a Document to the Server

Example Configurations

Example: Creating a Message with Multiple Operations

Example 1

Example 2

Example: Creating a Port Profile

Example: Deleting a Port Profile

Example: Deleting a Configuration

Example: Closing Your Session

Example: Closing a Session Other Than Your Own

Example: Editing a Configuration

Default Settings

Additional References

Standards

RFCs


Configuring XML Requests

This chapter describes how to configure XML requests and includes the following sections:

•Prerequisites

•Guidelines and Limitations

•Starting a Session with the XML Server

•Creating an XML Request

•Example Configurations

•Default Settings

•Additional References

Prerequisites

The XML API interface has the following prerequisites:

•SSH Version 2 is installed and enabled on the client PC.

Guidelines and Limitations

Before you begin exchanging messages with the Cisco Nexus 1000VXML API, verify the following conditions:

•You must use your own XML editor or XML management interface tool to create XML instances.

•If using an XML management tool, it must support NETCONF over SSH.

Starting a Session with the XML Server

Use this procedure to start a NETCONF session between your XML client and the Cisco Nexus 1000V XML server.

Note The Cisco Nexus 1000V xmlagent service is referred to as the XML server.

BEFORE YOU BEGIN

Before beginning this procedure, you must know or do the following:

•You are logged in to your XML client PC where SSH Version 2 is enabled.

•You know the IP address for the Cisco Nexus 1000V XML server.

•There is an available XML server session.

For more information, see the "Configuring the Number of Allowed Sessions" procedure on page 2-1.

SUMMARY STEPS

1. ssh username@ipaddress -s xmlagent

2. password

DETAILED STEPS

 
Command
Purpose

Step 1 

ssh username@ip-address -s xmlagent

Example:

ssh admin@172.23.232.160 -s xmlagent

User Access Verification

Password:


Connects you to the Cisco Nexus 1000V XML agent over a secure SSH connection.

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

Step 2 

password

Example:

Password: *******

Authenticates your credentials and begins a NETCONF session between your client PC and the Cisco Nexus 1000V XML server.

Step 3 

<?xml version="1.0"?>

Example:

<?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>

Enter a declaration statement indicating the version of XML you are using. The server responds with a hello message indicating its capabilities.

Step 4 

<nc:hello xmlns:nc="urn:ietf:params :xml:ns:netconf:base:1.0" ><nc:capabilities><nc:cap ability>urn:ietf:params:x ml:ns:netconf:base:1.0</ nc:capability></ nc:capabilities></ nc:hello> 

Example:

<nc:hello xmlns:nc="urn:ietf:params 
:xml:ns:netconf:base:1.0" 
><nc:capabilities><nc:cap 
ability>urn:ietf:params:x 
ml:ns:netconf:base:1.0</ nc:capability></ 
nc:capabilities></ nc:hello>

  </capabilities>

  <session-id>17644</session-id>

</hello>

]]>]]>

Enter a hello message, indicating your client capabilities.

Your NETCONF session is started.

Creating an XML Request

Use this procedure to create an XML request in a message to the XML server.

BEFORE YOU BEGIN

Before beginning this procedure, you must know or do the following:

•You have already started a NETCONF session with the XML server from your client PC.

See the "Starting a Session with the XML Server" procedure.

•You will need to use your own XML editor or XML management interface tool to create XML messages.

DETAILED STEPS

Step 1 Enter a request start tag. 

   <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">

Step 2 Enter the NETCONF operations start tags for the operations you are requesting. 

   <nc:get>

    <nc:filter type="subtree">

Step 3 Enter the Cisco Nexus 1000V operation start tags for the operations you are requesting. 

           <show>

          <xml>

         <server>

        <status/>

Step 4 Enter the Cisco Nexus 1000V operation end tags for the operations you are requesting. 

      </server>

     </xml>

    </show>

Step 5 Enter the NETCONF operations end tags for the operations you are requesting. 

   </nc:filter>

  </nc:get>

  </nc:rpc>

Step 6 Enter a request end tag followed by the ]]>]]> end of message character sequence.

The following is what the entire XML request looks like: 

<?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>]]>]]>

Manually Sending a Document to the Server

Use this procedure to manually send an XML document or message to the server.

BEFORE YOU BEGIN.

Before beginning this procedure, you must know or do the following:

•Although you will generally use an automated method to send messages, you can verify the SSH connection to the XML server with this method.

•You are logged in to the XML client PC where SSH Version 2 is enabled.

•You have an XML editor application open on the client PC, and you have created an XML message that ends with the ]]>]]> character sequence.

•You have opened an SSH session with the XML server and have already exchanged hello messages.

DETAILED STEPS

Step 1 Copy the XML message from the editor application.

Step 2 Paste the XML message into the active SSH session.

The XML message is sent to the XML server where it is parsed and carried out, and then a response indicating the result is returned to your client.

Example Configurations

This section provides the following examples of XML messages.

•Example: Creating a Message with Multiple Operations

•Example: Creating a Port Profile

•Example: Deleting a Port Profile

•Example: Deleting a Configuration

•Example: Closing Your Session

•Example: Closing a Session Other Than Your Own

•Example: Editing a Configuration

Example: Creating a Message with Multiple Operations

You can include multiple NETCONF operations in a single XML message as long as all of the requests are for the same NETCONF operation.

The XML server ensures that all requests parse without errors before applying them. Any error causes the request to fail with a notification sent to you.

This section includes the following examples:

•Example 1

•Example 2

Example 1

This example shows two NETCONF get operations representing 2 CLI commands formatted in a single XML message.

CLI commands:

The following are the CLI commands that are required in the XML request message. 

switch# show ssh server

switch# show xml server status

Message

The following is the XML request message representing the required CLI commands. 

<?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>

          <server>

          </server>

        </ssh>

      </show>

      <show>

        <xml>

          <server>

            <status/>

          </server>

        </xml>

      </show>

    </nc:filter>

  </nc:get>

</nc:rpc>]]>]]>

Reply

The following is the RPC reply sent from the XML server after parsing and carrying out the request from your client.

Note The XML server may send replies in a different sequence than the requests were sent. 

<?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:security_tree" 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_c>

         <max_session>8</max_session>

        </maximum_sessions_c>

        <TABLE_sessions>

         <ROW_sessions>

          <session_id>24559</session_id>

          <user_name>admin</user_name>

          <start_time>Tue Mar 25 16:14:17 2008</start_time>

          <sap_id>10519</sap_id>

          <timeout>1200</timeout>

          <time_remaining_to_timeout>587</time_remaining_to_timeout>

          <ip_addr>171.71.55.134</ip_addr>

         </ROW_sessions>

        </TABLE_sessions>

       </__readonly__>

      </__XML__OPT_Cmd_show_xml___readonly__>

     </status>

    </server>

   </xml>

  </show>

 </nc:data>

</nc:rpc-reply>

]]>]]><?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>ssh is enabled

version 2 enabled

</nc:data>

</nc:rpc-reply>

]]>]]>

Example 2

This example shows two NETCONF get operations representing one valid CLI command and one erroneous CLI command formatted in a single XML message.

CLI commands:

The following are the CLI commands that are required in the XML request message. 

switch# show version

switch# show version-error-does-not-exist

Message

The following is the XML request message representing the required CLI commands. 

<?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>

        <show>

             <version-error-doesnotexist>

             </version-error-doesnotexist>

         </show>

       </nc:filter>

     </nc:get>

</nc:rpc>]]>]]>

Reply

The following is the RPC reply sent from the XML server after parsing and carrying out the request from your client. 

<?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

Copyright (c) 2002-2009, Cisco Systems, Inc. All rights reserved.

The copyrights to certain works contained in this software are

owned by other third parties and used and distributed under

license. Certain components of this software are licensed under

the GNU General Public License (GPL) version 2.0 or the GNU

Lesser General Public License (LGPL) Version 2.1. A copy of each

such license is available at

http://www.opensource.org/licenses/gpl-2.0.php and

http://www.opensource.org/licenses/lgpl-2.1.php

</header_str>

      <loader_ver_str>1.2(2) [last: image booted through mgmt0]</loader_ver_str>

      <kickstart_ver_str>4.0(4)SV1(2)</kickstart_ver_str>

      <sys_ver_str>4.0(4)SV1(2) [gdb]</sys_ver_str>

      <kick_file_name></kick_file_name>

      <kick_cmpl_time> 9/22/2009 2:00:00</kick_cmpl_time>

      <isan_file_name>bootflash:/isan.bin</isan_file_name>

      <isan_cmpl_time> 9/22/2009 2:00:00</isan_cmpl_time>

      <isan_tmstmp>09/26/2009 00:36:00</isan_tmstmp>

      <chassis_id>Nexus 1000V Chassis</chassis_id>

      <module_id>Virtual Supervisor Module</module_id>

      <cpu_name>Intel(R) Xeon(R) CPU        </cpu_name>

      <memory>2075012</memory>

      <mem_type>kB</mem_type>

      <proc_board_id>T5056BE7598</proc_board_id>

      <host_name>roshan-vsm</host_name>

      <bootflash_size>2332296</bootflash_size>

      <kern_uptm_days>3</kern_uptm_days>

      <kern_uptm_hrs>16</kern_uptm_hrs>

      <kern_uptm_mins>58</kern_uptm_mins>

      <kern_uptm_secs>3</kern_uptm_secs>

     </__readonly__>

    </__XML__OPT_Cmd_sysmgr_show_version___readonly__>

   </version>

  </show>

 </nc:data>

</nc:rpc-reply>

]]>]]>




<?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 version-error-doesnotexist '


</nc:error-message>

    <nc:error-info>

      <nc:bad-element>show</nc:bad-element>

    </nc:error-info>

  </nc:rpc-error>

</nc:rpc-reply>

]]>]]>

Example: Creating a Port Profile

The following example shows the XML request message for creating a port profile.

Commands

The following are the CLI commands that are required in the XML request message. 

switch# config t

switch(config)# port-profile testppf

switch(config-port-prof)# description portprofile-test-description

switch(config-port-prof)# vmware port-group portprofile-test

switch(config-port-prof)# state enabled

switch(config-port-prof)# no shut

Message

The following example shows the XML message for the required commands. 

<?xml version="1.0"?>

<nf:rpc xmlns="http://www.cisco.com/nxos:1.0:ppm" 
xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="110">

<nf:edit-config>

 <nf:target>

  <nf:running/>

</nf:target>

<nf:config>

<nxos:configure xmlns:nxos="http://www.cisco.com/nxos:1.0:ppm">

<nxos:__XML__MODE__exec_configure>


<port-profile>

  <name>

    <__XML__PARAM_value isKey="true">testppf</__XML__PARAM_value>

    <__XML__MODE_port-prof>

      <description>

            <desc_text>portprofile-test-description</desc_text>

      </description>

      <vmware>

              <port-group>

                <__XML__OPT_Cmd_ppm_port_group_pg_name>

                  <pg_name>portprofile-test</pg_name>

                </__XML__OPT_Cmd_ppm_port_group_pg_name>

              </port-group>

      </vmware>

      <state>

              <enabled />

      </state>

      <no>

              <shutdown />

      </no>

    </__XML__MODE_port-prof>

  </name>

</port-profile>


</nxos:__XML__MODE__exec_configure>

</nxos:configure>

</nf:config>

</nf:edit-config>

</nf:rpc>]]>]]>

Reply

The following is the XML server reply to the NETCONF message. 

<?xml version="1.0"?>

<nf:rpc-reply xmlns="http://www.cisco.com/nxos:1.0:ppm" 
xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="110">

  <nf:ok/>

</nf:rpc-reply>

]]>]]>

Example: Deleting a Port Profile

The following example shows the XML request message for deleting a port profile.

Commands

The following are the CLI commands that are required in the XML request message. 

switch# config t

switch(config)# no port-profile testppf

Message

The following example shows the XML message for the required commands. 

<?xml version="1.0"?>

<nf:rpc xmlns="http://www.cisco.com/nxos:1.0:ppm" 

xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="110">

<nf:edit-config>

 <nf:target>

  <nf:running/>

</nf:target>

<nf:config>

<nxos:configure xmlns:nxos="http://www.cisco.com/nxos:1.0:ppm">

<nxos:__XML__MODE__exec_configure>

<no>

<port-profile>

  <name>

    <__XML__PARAM_value isKey="true">testppf</__XML__PARAM_value>

  </name>

</port-profile>

</no>

</nxos:__XML__MODE__exec_configure>

</nxos:configure>

</nf:config>

</nf:edit-config>

</nf:rpc>]]>]]>

Reply

The following is the XML server reply to the NETCONF message. 

<?xml version="1.0"?>

<nf:rpc-reply xmlns="http://www.cisco.com/nxos:1.0:ppm" 
xmlns:nf="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="110">

  <nf:ok/>

</nf:rpc-reply>

]]>]]>

Example: Deleting a Configuration

The following example shows the NETCONF delete-config operation, which performs the equivalent of the write erase command on the startup configuration.

Caution This procedure removes the existing configuration entirely.

CLI Command

switch# write erase

Message

The following example shows the XML message for the required command. 

<?xml version="1.0"?>

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

  <delete-config>

    <target>

      <running/>

    </target>

  </delete-config>

</rpc>]]>]]>

Reply

The following is the XML server reply to the NETCONF message. 

<?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>]]>]]>

Example: Closing Your Session

The following example shows the NETCONF close-session operation which closes your session with the XML server, also terminating the SSH session.

Message

The following is the XML message for the NETCONF close-session operation. 

<?xml version="1.0"?>

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

  <close-session/>

</rpc>]]>]]>

Reply

The following is the XML server reply to the message. 

<?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>]]>]]>

Example: Closing a Session Other Than Your Own

The following example shows the NETCONF kill-session operation which terminates a server session other than your own.

Message

The following is the XML message for the NETCONF kill-session operation. 

<?xml version="1.0"?>

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

  <kill-session>

    <session-id>31990</session-id>

  </kill-session>

</rpc>]]>]]>

Reply

The following is the XML server reply to the message. 

<?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="110">

<nc:ok/>

</nc:rpc-reply>]]>]]>\

Example: Editing a Configuration

This example shows a request for editing a configuration using the NETCONF edit-config operation.

CLI Commands

The following are the CLI commands required in the message. 

switch# config t

switch(config)# interface ethernet 2/30

switch(config-if)# description Marketing Network

Message

The following is the XML message with the NETCONF edit-config operation and the required CLI commands. 

<?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-ethernet>

                  <description>

                    <desc_line>Marketing Network</desc_line>

                  </description>

                </__XML__MODE_if-ethernet>

              </__XML__MODE_if-ethernet>

            </ethernet>

          </interface>

        </__XML__MODE__exec_configure>

      </configure>

    </nc:config>

  </nc:edit-config>

</nc:rpc>]]>]]>

Reply

The following is the XML server reply to the message. 

<?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>]]>]]>

Default Settings

Table 3-1 lists the default SSH settings.

Table 3-1 SSH Defaults  

Parameters
Default

SSH Version 6

Enabled


Additional References

For additional information related to implementing the XML management interface, see the following sections:

•Standards

•RFCs

Standards

Standards
Title

No new or modified standards are supported by this feature, and 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)