Cisco Nexus 5000 series User 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

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.

Anxapi_auth cookie expires in 600 seconds (10 minutes). This value is a fixed and cannot be adjusted.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.

Note

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>

<sid>session1</sid>

<input>show switchname</input>

<output_format>xml</output_format>

</ins_api>

Response:

<?xml version="1.0"?>

<ins_api>

<body>

<hostname>switch</hostname>

</body>

<input>show switchname</input>

<msg>Success</msg>

</output>

</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.

When using the NX-API Sandbox, Cisco recommends that you use the Firefox browser, release 24.0 or

later.

Note

The following example shows how to configure and launch the NX-API Sandbox:

•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.

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

Specifies a port.

nxapi {http|https}port 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.

nxapi certificate {httpscrt |httpskey}

Enables a certificate.

nxapi certificate enable

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

DescriptionNX-API Request Element

Specifies the NX-API version.version

DescriptionNX-API Request Element

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.

•No interactive commands are supported.

type

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

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 &gt).

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.

Note

chunk

DescriptionNX-API Request Element

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.

sid

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.

Multiple commands are separated with " ; ". (The ; must be

surrounded with single blank characters.)

Note

The following are examples of multiple commands:

show version ; show interface brief ; show vlan

cli_show

interface Eth4/1 ; no shut ; switchport

cli_conf

input

The available output message formats are the following:

Specifies output in XML format.xml

Specifies output in JSON format.json

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).

Note

output_format

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

DescriptionNX-API Response Element

Session ID of the response. This element is valid only when the response message is

chunked.

sid

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.

outputs

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.

output

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.

input

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).

code

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>

<input>show clock</input>

<msg>Structured output unsupported</msg>

</output>

</outputs>

</ins_api>

If that happens, you will need to use the command type—"cli_show_ascii".

•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.

Other manuals for Nexus 5000 Series

This manual suits for next models

Table of contents

Other Cisco Switch manuals

Cisco

Cisco Catalyst 3040 User manual

Cisco

Cisco Aironet 350 Series User manual

Cisco

Cisco Nexus B22HP Guide

Cisco

Cisco Catalyst 6807-XL Manual

Cisco

Cisco Catalyst 2900 Series XL Operator's manual

Cisco

Cisco SRW2008MP User manual

Cisco

Cisco Catalyst 3560-8PC User manual

Cisco

Cisco Nexus 9332D-GX2B Manual

Cisco

Cisco SG300-52P-K9-NA User manual

Cisco

Cisco Catalyst 2960-L User manual

Cisco

Cisco SGE2000 - Cisco - Gigabit Switch Instruction Manual

Cisco

Cisco Catalyst 2960-S Series User manual

Cisco

Cisco CSS11501 - 100Mbps Ethernet Load Balancing... Dimensions

Cisco

Cisco 4900M - Catalyst Switch User manual

Cisco

Cisco 3524-PWR - Catalyst XL Enterprise Edition... User manual

Cisco

Cisco RSP8 Operator's manual

Cisco

Cisco Meraki MS210-24 User manual

Cisco

Cisco Catalyst 6500-E Series User manual

Cisco

Cisco Catalyst 3550 Installation manual

Cisco

Cisco SF220-24 User manual

Cisco

Cisco Catalyst 2960X-48FPD-L Manual

Cisco

Cisco LRE CPE Manual

Cisco

Cisco Nexus 3500 Manual

Cisco

Cisco SG 102-24 User manual

Popular Switch manuals by other brands

SMC Networks

SMC Networks SMC6224M Technical specifications

Aeotec

Aeotec ZWA003-S operating manual

TRENDnet

TRENDnet TK-209i Quick installation guide

Planet

Planet FGSW-2022VHP user manual

Avocent

Avocent AutoView 2000 AV2000BC AV2000BC Installer/user guide

Moxa Technologies

Moxa Technologies PT-7728 Series user manual

Intos Electronic

Intos Electronic inLine 35392I operating instructions

Asante

Asante IntraCore IC3648 Specifications

Siemens

Siemens SIRIUS 3SE7310-1AE Series Original operating instructions

Edge-Core

Edge-Core DCS520 quick start guide

RGBLE

RGBLE S00203 user manual

Thrustmaster

Thrustmaster FLIGHT SIMULATOR X quick guide

Southwire

Southwire SURGE GUARD 41390 RVC troubleshooting guide

Buhler

Buhler Nivotemp NT 61 Brief instructions

Kramer

Kramer VS-41HDCP user manual

Techly

Techly IDATA AU-270 user manual

Belkin

Belkin F1U109 user manual

Emerson

Emerson Rosemount 2521 Series quick start guide

Cisco Nexus 5000 Series User manual

Popular Switch manuals by other brands