Cisco Nexus 5000 Series, Nexus 6000 Series Reference Manual
Cisco Nexus 5000 and 6000 Series NX-API Reference Guide, Release
7.x
NX-API 2
About NX-API 2
Using NX-API 3
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
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
</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
Loading...