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 the XML API is used to configure and monitor the Cisco Nexus 1000V, and includes the following sections:
•Network Configuration Protocol
The eXtensible markup language (XML) application programming interface (API) lets you manage and monitor the Cisco Nexus 1000V using XML. From a client PC, you can encode CLI commands with XML API tags that are then sent to the device over a secure SSH connection.
Table 1-1 defines the words, acronyms, and actions used throughout this guide.
The XML interface is implemented with an XML schema definition (XSD). of the supported CLI commands in XML. You can download the feature-based XSD files from Cisco.com.
To obtain a copy of the XSD, from your browser, navigate to the Cisco software download site at the following URL:
http://www.cisco.com/go/1000v/
A Cisco Nexus 1000V XML agent, also called the XML server, enables configuration and monitoring using an exchange of XML formatted request and reply streams over a secure connection.
When you start an SSH session with the XML server, it sends an immediate hello message including its capabilities, as shown in Example 1-1. Before the server processes further requests, you must advertise your capabilities in a hello message to the server, as shown in Example 1-2.
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>
</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>]]>]]>
Communication with the XML API is accomplished in XML over the Network Configuration Protocol (NETCONF). NETCONF uses a simple remote procedure call (RPC) and SSH transport protocol for a secure connection.
To run NETCONF over SSHv2, the client establishes an SSH transport connection with the XML server. The client and server exchange keys for security and password encryption. The NETCONF SSHv2 session user ID and password are used for authorization and authentication. The user privilege level is enforced and the client session may not have full access to the NETCONF operations if the privilege level is not high enough.
If AAA is configured, the AAA service is used as if you had established an SSH session directly to the Cisco Nexus 1000V. Once the client is successfully authenticated, it starts the SSH connection protocol and the SSH session is established. After the SSH session is established, the user or application starts NETCONF as an SSH subsystem.
For detailed information about NETCONF, see RFC 4741.
For detailed information about using the NETCONF protocol over the Secure Shell (SSH), see RFC 4742.
The communication between client and server consists of a series of alternating request and reply messages.
A valid client ID is an unsigned 32-bit integer. If the request message contains a valid client ID, then the server also includes the same client ID in its reply. The client ID is treated as opaque data and ignored in every other way by the XML API.
Every request sent by a client application to the server begins with an XML declaration tag followed by a request tag and one or more operation tags. Each request can contain one or more operations for each supported operation type, and the operations can be repeated.
Similarly, every reply from the server begins with an XML declaration tag followed by a reply tag and one or more operation tags corresponding to those in the client request.
Figure 1-1 shows the tags used to identify each line of content in NETCONF XML messages:
Figure 1-1 NETCONF XML Message Format
Each request and reply begins with an XML declaration indicating which version of XML and (optionally) which character set are being used.
The following are the attributes of the XML declaration:
•Version—Specifies the version of XML to be used.
•Encoding—(optional) Specifies the standardized character set to be used.
Example 1-3 Declaration Statement
<?xml version="1.0"?>
In the XML message format, the client request follows the XML declaration tag. Each request must be enclosed within a set of RPC tags. Requests include NETCONF and device (CLI-based) operations.
As shown in Example 1-4, you first specify the NETCONF operation (for example, get) followed by the CLI commands (for example, show xml server status).
Example 1-4 Request
<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>]]>]]>
In your client request, you specify both NETCONF operations, and CLI command-based operations. Example 1-5 shows how the following operations appear in an XML API message.
|
|
---|---|
get |
|
filter type = subtree |
show xml server status |
Note To identify which of the NETCONF operations are supported, see Table 1-2.
Example 1-5 Operations
<nc:get>
<nc:filter type="subtree">
<show>
<xml>
<server>
<status/>
</server>
</xml>
</show>
</nc:filter>
</nc:get>
When your client request is received by an XML agent, the request is routed to the XML API library for processing. After all requested operations are processed, the XML agent sends an XML encoded reply stream back to your client. Table 1-2 shows which of the NETCONF operations are supported.
|
|
|
|
---|---|---|---|
close-session |
Yes |
Terminates your server session. |
|
commit |
No |
— |
— |
copy-config |
No |
— |
— |
delete-config |
Yes |
Performs the equivalent of the write erase command on the startup configuration. |
|
edit-config |
Yes |
Configures features in the running configuration of the device. You use this operation for configuration commands. |
|
get |
Yes |
Receives configuration information from the device. You use this operation for show commands. The source of the data is the running configuration. |
Example: Creating a Message with Multiple Operations, page 3-5 |
get-config |
No |
— |
— |
kill-session |
Yes |
Terminates another server session. |
|
lock |
No |
— |
— |
unlock |
No |
— |
— |
validate |
No |
— |
— |
For every XML request you send from the client, the XML server sends an XML reply, as shown in Example 1-6. Just as in your request message, every reply from the server begins with an XML declaration and includes one or more operations. The possible replies are described in Table 1-3.
Note Replies may be received in a different sequence than the requests were sent.
Example 1-6 Reply
<nc:rpc-reply message-id="315" xmlns xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</nc:rpc-reply>]]>]]>
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) |