Page 1
Cisco Nexus 5000 and 6000 Series NX-API Reference Guide, Release
7.x
NX-API 2
About NX-API 2
Using NX-API 3
Page 2
Revised: June 16, 2015,
NX-API
About NX-API
On Cisco Nexus devices, command-line interfaces (CLIs) are run only on the device. NX-API improves the accessibility of these
CLIs by making them available outside of the switch by using HTTP/HTTPS. You can use this extension to the existing Cisco Nexus
CLI system on the Cisco Nexus 5000 and 6000 Series devices. NX-API supports show commands and configurations.
NX-API supports JSON-RPC.
Transport
NX-API uses HTTP/HTTPS as its transport. CLIs are encoded into the HTTP/HTTPS POST body.
The NX-API backend uses the Nginx HTTP server. The Nginx process, and all of its children processes, are under Linux cgroup
protection where the CPU and memory usage is capped. If the Nginx memory usage exceeds the cgroup limitations, the Nginx process
is restarted and restored.
Message Format
NX-API is an enhancement to the Cisco Nexus 5000 and 6000 Series CLI system, which supports XML output. NX-API also supports
JSON output format for specific commands.
Note
NX-API XML output presents information in a user-friendly format.
•
NX-API XML does not map directly to the Cisco NX-OS NETCONF implementation.
•
NX-API XML output can be converted into JSON.
•
Security
NX-API supports HTTPS. All communication to the device is encrypted when you use HTTPS.
NX-API is integrated into the authentication system on the device. Users must have appropriate accounts to access the device through
NX-API. NX-API uses HTTP basic authentication. All requests must contain the username and password in the HTTP header.
You should consider using HTTPS to secure your user's login credentials.Note
You can enable NX-API by using the feature manager CLI command. NX-API is disabled by default.
NX-API provides a session-based cookie, nxapi_auth when users first successfully authenticate. With the session cookie, the username
and password are included in all subsequent NX-API requests that are sent to the device. The username and password are used with
the session cookie to bypass performing the full authentication process again. If the session cookie is not included with subsequent
2
Page 3
requests, another session cookie is required and is provided by the authentication process. Avoiding unnecessary use of the authentication
process helps to reduce the workload on the device.
A nxapi_auth cookie expires in 600 seconds (10 minutes). This value is a fixed and cannot be adjusted.Note
Note
NX-API performs authentication through a programmable authentication module (PAM) on the switch.
Use cookies to reduce the number of PAM authentications, which reduces the load on the PAM.
Using NX-API
The commands, command type, and output type for the Cisco Nexus 5000 and 6000 Series devices are entered using NX-API by
encoding the CLIs into the body of a HTTP/HTTPs POST. The response to the request is returned in XML or JSON output format.
You must enable NX-API with the feature manager CLI command on the device. By default, NX-API is disabled.
The following example shows how to enable NX-API:
Enable the management interface.
•
switch# configure terminal
switch(config)# interface mgmt 0
switch(config)# ip address 198.51.100.1/24
switch(config)# vrf context managment
switch(config)# ip route 203.0.113.1/0 1.2.3.1
Enable the NX-API nxapi feature.
•
switch# configure terminal
switch(config)# feature nxapi
The following example shows a request and its response in XML format:
Request:
<?xml version="1.0" encoding="ISO-8859-1"?>
<ins_api>
<version>0.1</version>
<type>cli_show</type>
<chunk>0</chunk>
<sid>session1</sid>
<input>show switchname</input>
<output_format>xml</output_format>
</ins_api>
Response:
<?xml version="1.0"?>
<ins_api>
<type>cli_show</type>
<version>0.1</version>
<sid>eoc</sid>
<outputs>
<output>
<body>
<hostname>switch</hostname>
</body>
<input>show switchname</input>
<msg>Success</msg>
<code>200</code>
</output>
3
Page 4
</outputs>
</ins_api>
The following example shows a request and its response in JSON format:
Request:
{
"ins_api": {
"version": "0.1",
"type": "cli_show",
"chunk": "0",
"sid": "session1",
"input": "show switchname",
"output_format": "json"
}
}
Response:
{
"ins_api": {
"type": "cli_show",
"version": "0.1",
"sid": "eoc",
"outputs": {
"output": {
"body": {
"hostname": "switch"
},
"input": "show switchname",
"msg": "Success",
"code": "200"
}
}
}
}
Sample NX-API Scripts
The sample scripts demonstrate how a script is used with NX-API. The scripts are available at
https://github.com/datacenter/nxos/tree/master/nxapi/samples.
Cable Checker (check_cable.py)
•
Cable Checker Blueprint (connectivity.json)
•
NX-API Sandbox
The NX-API Sandbox is the web-based user interface that you use to enter the commands, command type, and output type for the
Cisco Nexus 5000 and 6000 Series device using HTTP/HTTPS. After posting the request, the output response is displayed.
By default, NX-API is disabled. Begin enabling NX-API with the feature manager CLI command on the switch. Then enable NX-API
with the nxapi sandbox command.
Use a browser to access the NX-API Sandbox.
Note
The following example shows how to configure and launch the NX-API Sandbox:
When using the NX-API Sandbox, Cisco recommends that you use the Firefox browser, release 24.0 or
later.
4
Page 5
Enable the management interface.
•
switch# conf t
switch(config)# interface mgmt 0
switch(config)# ip address 198.51.100.1/24
switch(config)# vrf context managment
switch(config)# ip route 203.0.113.1/0 1.2.3.1
Enable the NX-API nxapi feature.
•
switch# conf t
switch(config)# feature nxapi
switch(config)# nxapi sandbox
Open a browser and enter http://mgmt-ip to launch the NX-API Sandbox. The following figure is an example of a request and
•
output response.
Figure 1: NX-API Sandbox with Example Request and Output Response
In the NX-API Sandbox, you specify the commands, command type, and output type in the top pane. Click the POST Request button
above the left pane to post the request. Brief descriptions of the request elements are displayed below the left pane.
After the request is posted, the output response is displayed in the right pane.
5
Page 6
The following sections describe the commands to manage NX-API and descriptions of the elements of the request and the output
response.
NX-API Management Commands
You can enable and manage NX-API with the CLI commands listed in the following table.
Table 1: NX-API Management Commands
DescriptionNX-API Management Command
Enables NX-API.feature nxapi
Disables NX-API.no feature nxapi
nxapi {http|https} port port
nxapi certificate {httpscrt |httpskey}
nxapi certificate enable
Specifies a port.
Disables HTTP/HTTPS.no nxapi {http|https}
Displays port information.show nxapi
Specifies the upload of the following:
HTTPS certificate when httpscrt is specified.
•
HTTPS key when httpskey is specified.
•
Enables a certificate.
NX-API Request Elements
NX-API request elements are sent to the device in XML format or JSON format. The HTTP header of the request must identify the
content type of the request.
You use the NX-API elements that are listed in the following table to specify a CLI command:
Table 2: NX-API Request Elements
6
DescriptionNX-API Request Element
Specifies the NX-API version.version
Page 7
DescriptionNX-API Request Element
type
Specifies the type of command to be executed.
The following types of commands are supported:
cli_show
•
CLI show commands that expect structured output. If the command does
not support XML output, an error message is returned.
cli_show_ascii
•
CLI show commands that expect ASCII output. This aligns with existing
scripts that parse ASCII output. Users are able to use existing scripts
with minimal changes.
cli_conf
•
CLI configuration commands.
Note
Each command is only executable with the current user's
•
authority.
The pipe operation is supported in the output when the message
•
type is ASCII. If the output is in XML format, the pipe operation
is not supported.
A maximum of 10 consecutive show commands are supported.
•
If the number of show commands exceeds 10, the 11th and
subsequent commands are ignored.
chunk
No interactive commands are supported.
•
Some show commands can return a large amount of output. For the NX-API
client to start processing the output before the entire command completes,
NX-API supports output chunking for show commands.
Enable or disable chunk with the following settings:
Do not chunk output.0
Chunk output.1
Note
Only show commands support chunking. When a series of show
commands are entered, only the first command is chunked and
returned.
The output message format is XML. (XML is the default.) Special
characters, such as < or >, are converted to form a valid XML message
(< is converted into < > is converted into >).
You can use XML SAX to parse the chunked output.
Note
When chunking is enabled, the message format is limited to XML.
JSON output format is not supported when chunking is enabled.
7
Page 8
DescriptionNX-API Request Element
sid
input
output_format
The session ID element is valid only when the response message is chunked.
To retrieve the next chunk of the message, you must specify a sid to match
the sid of the previous response message.
Input can be one command or multiple commands. However, commands that
belong to different message types should not be mixed. For example, show
commands are cli_show message type and are not supported in cli_conf mode.
Note
Multiple commands are separated with " ; ". (The ; must be
surrounded with single blank characters.)
The following are examples of multiple commands:
cli_show
cli_conf
show version ; show interface brief ; show vlan
interface Eth4/1 ; no shut ; switchport
The available output message formats are the following:
Specifies output in XML format.xml
Specifies output in JSON format.json
Note
The Cisco Nexus 5000 and 6000 Series CLI supports XML output,
which means that the JSON output is converted from XML. The
conversion is processed on the switch.
To manage the computational overhead, the JSON output is
determined by the amount of output. If the output exceeds 1 MB, the
output is returned in XML format. When the output is chunked, only
XML output is supported.
The content-type header in the HTTP/HTTPS headers indicate the
type of response format (XML or JSON).
NX-API Response Elements
The NX-API elements that respond to a CLI command are listed in the following table:
Table 3: NX-API Response Elements
DescriptionNX-API Response Element
NX-API version.version
Type of command to be executed.type
8
Page 9
DescriptionNX-API Response Element
sid
outputs
output
input
code
Session ID of the response. This element is valid only when the response message is
chunked.
Tag that encloses all command outputs.
When multiple commands are in cli_show or cli_show_ascii, each command output is
enclosed by a single output tag.
When the message type is cli_conf or bash, there is a single output tag for all the
commands because cli_conf and bash commands require context.
Tag that encloses the output of a single command output.
For cli_conf and bash message types, this element contains the outputs of all the
commands.
Tag that encloses a single command that was specified in the request. This element
helps associate a request input element with the appropriate response output element.
Body of the command response.body
Error code returned from the command execution.
NX-API uses standard HTTP error codes as described by the Hypertext Transfer Protocol
(HTTP) Status Code Registry
(http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
Error message associated with the returned error code.msg
Command Types
There are a number of command “types” available for sending show and configuration commands to a device using the NX-API. The
type you need to use depends on the actual command you want to send: cli_show: You should use the “cli_show” type when you
want to send a show command that supports structured XML output. To know whether a command supports XML output or not, you
can go to the CLI of the switch and run the command with the "| xml" option on the end—you will be able to see whether that command
returns XML output or not. If you try and use the "cli_show" command type with a command that does not support XML, you will
receive a message stating “structured output unsupported” from the API:
<?xml version="1.0" encoding="UTF-8"?>
<ins_api>
<type>cli_show</type>
<version>0.1</version>
<sid>eoc</sid>
<outputs>
<output>
<input>show clock</input>
<msg>Structured output unsupported</msg>
<code>501</code>
</output>
</outputs>
</ins_api>
If that happens, you will need to use the command type— "cli_show_ascii".
9
Page 10
• cli_show_ascii—This command type returns output in ASCII format with the entire output inside one <body> element. Any
command on the switch (including the ones that do not support structured XML output) should work with this command type,
although it will be more difficult to parse compared to those commands that return XML.
•
cli_conf— Use this command type when you want to send configuration commands (as opposed to show commands) to the
API.
10
Page 11
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,
INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH
THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY,
CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version
of the UNIX operating system. All rights reserved. Copyright©1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS.
CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT
LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS
HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network
topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional
and coincidental.
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)
This product includes software written by Tim Hudson (tjh@cryptsoft.com).
Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: http://
www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership
relationship between Cisco and any other company. (1110R)
©
2015 Cisco Systems, Inc. All rights reserved.
Page 12
Cisco Systems, Inc.
San Jose, CA 95134-1706
USA
Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on the
Cisco Website at www.cisco.com/go/offices.
Cisco Systems (USA) Pte. Ltd.
Singapore
Europe HeadquartersAsia Pacific HeadquartersAmericas Headquarters
Cisco Systems International BV
Amsterdam, The Netherlands
Loading...