The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes how to configure XML requests and includes the following sections:
•Starting a Session with the XML Server
The XML API interface has the following prerequisites:
•SSH Version 2 is installed and enabled on the client PC.
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.
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 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.
1. ssh username@ipaddress -s xmlagent
2. password
Use this procedure to create an XML request in a message to the XML server.
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.
Step 1 Enter a request start tag.
Example:
<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>
Step 6 Enter a request end tag followed by the ]]>]]> end of message character sequence.
Example:
</nc:rpc>]]>]]>
<?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>]]>]]>
Use this procedure to manually send an XML document or message to the server.
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.
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.
This section provides the following examples of XML messages.
•Example: Creating a Message with Multiple Operations
•Example: Creating a Port Profile
•Example: Deleting a Configuration
•Example: Closing Your Session
•Example: Closing a Session Other Than Your Own
•Example: Editing a Configuration
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:
This example shows two NETCONF get operations representing 2 CLI commands formatted in a single XML message.
The following are the CLI commands that are required in the XML request message.
switch# show ssh server
switch# show xml server status
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>]]>]]>
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>
]]>]]>
This example shows two NETCONF get operations representing one valid CLI command and one erroneous CLI command formatted in a single XML message.
The following are the CLI commands that are required in the XML request message.
switch# show version
switch# show version-error-does-not-exist
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>]]>]]>
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>
]]>]]>
The following example shows the XML request message for creating a port profile.
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
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>]]>]]>
The following example shows the NETCONF delete-config operation, which performs the equivalent of the write erase command on the startup configuration.
switch# write erase
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>]]>]]>
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>]]>]]>
The following example shows the NETCONF close-session operation which closes your session with the XML server, also terminating the SSH session.
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>]]>]]>
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>]]>]]>
The following example shows the NETCONF kill-session operation which terminates a server session other than your own.
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>]]>]]>
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>]]>]]>\
This example shows a request for editing a configuration using the NETCONF edit-config operation.
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
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>]]>]]>
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>]]>]]>
Table 3-1 lists the default SSH settings.
|
|
---|---|
SSH Version 6 |
Enabled |
For additional information related to implementing the XML management interface, see the following sections:
•RFCs
|
|
---|---|
No new or modified standards are supported by this feature, and support for existing standards has not been modified by this feature. |
— |
|
|
---|---|
NETCONF Configuration Protocol |
|
Using the NETCONF Configuration Protocol over Secure Shell (SSH) |