NX-API is an enhancement to the Cisco MDS 9000 Series CLI system.

Cisco MDS 9000 NX-API is an RPC-style API, taking and executing CLI commands. Based on HTTP or HTTPS protocols as common to other Representational State Transfer (REST) API frameworks, it allows programmatic access to a Cisco MDS switch. NX-API provides the configuration and management capabilities of Cisco MDS NX-OS CLI with a modern web-based API, enabling users to control a Cisco MDS switch using a web browser. When coupled with a programming language like Python and the appropriate libraries, it facilitates storage networking automation.

Cisco MDS NX-API supports certain show commands and configuration commands that are noninteractive.

Note	A noninteractive command is a command that does not prompt the user to enter an input from the keyboard to proceed further.

HTTP Header

A header allows a client and a server to pass extra information as colon separated property-value pairs in requests and responses.

This is where the content encoding is specified for an NX-API request. The supported content types are:

HTTP Method

Cisco MDS NX-API uses the POST method.

Message Body

The message body or payload contains the data for the HTTP method. For a list of supported objects see the NX-API Request Elements section.

Message Response

The message response is an HTTP return code and an HTTP response body that contains the data returned by the method. For a list of supported elements see the NX-API Respone Elements section. For a list of response codes refer to the NX-API Response Codes section.

Preparing an Identity Certificate for Use in NX-API

An identity certificate for NX-API must be created before it can be imported with the nxapi certificate command. The certificate must consist of the switch identity certificate only; all CA and intermediate authority certificates must be removed. The private key must be removed and the total size must be less than 4096 bytes.

If a switch identity certificate is already installed in the switch crypto infrastructure under a trustpoint, this may be exported and reformattted, and the private key extracted, to be used in NX-API. If there is no switch identity certificate already installed, then it needs to be created by the CA.

For information on how to create a certificate, see the Configuring Certificate Authorities and Digital Certificates chapter in the Cisco MDS 9000 Series Security Configuration Guide, Release 8.x.

Note	The tools to prepare an existing identity certificate for NX-API use are not available on the switch. This must be done on another device such as a host with OpenSSL installed.

1. (Optional) If a switch identity certificate is already installed on the switch, export it in PKCS12 format using the following command:

   switch(config)# crypto ca export trustpoint_name pkcs12 mytpexport.pkcs12 my_passphrase

2. Upload the file to a host with OpenSSL installed on it:

   switch# copy mytpexport.pkcs12 sftp://10.10.2.2

3. Extract the identity certificate:

   host$ openssl pkcs12 -in mytpexport.pkcs12 -nokeys -clcerts -out idcert.pem
   Enter Import Password: my_passphrase
   host$

4. Extract unencrypted private key:

   host$ openssl pkcs12 -in mytpexport.pkcs12 -nocerts -nodes | openssl rsa -out unencryptedprivkey.pem
   Enter Import Password:
   writing RSA key
   host$

5. Download the 2 files to the switch bootflash:

   switch# copy sftp://10.10.2.2/idcert.pem bootflash:
   switch# copy sftp://10.10.2.2/unencryptedprivkey.pem bootflash:

The files are now ready to be imported using the nxapi certificate command.

Using NX-API with cURL

Let us now examine the content of the show.version.json file on the host.

linux$ cat show.version.json
[{ "jsonrpc": "2.0", "method": "cli", "params": { "cmd": "show version", "version": 1 }, "id": 1 }]
EOF
 

Now use cURL on host to authenticate the switch and send it the desired POST request.

linux$ curl -v -u admin:cisco -H "Content-Type: application/json-rpc" -H "Cache-Control: no-cache" -d @show.version.json -X POST http://10.10.2.2:80/ins
 
Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying 10.10.2.2:80...
* Connected to 10.10.2.2:80 (10.10.2.2:80) port 80 (#0)
* Server auth using Basic with user 'admin'
> POST /ins HTTP/1.1
> Host: 10.10.2.2:80
> Authorization: Basic YWRtaW46bmJ2XzEyMzQ1
> User-Agent: curl/7.70.0
> Accept: */*
> Content-Type: application/json-rpc
> Cache-Control: no-cache
> Content-Length: 99
> 
* upload completely sent off: 99 out of 99 bytes
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Server: nginx/1.7.10
< Date: Mon, 14 Jun 1976 13:28:43 GMT
< Content-Type: application/json-rpc; charset=UTF-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Set-Cookie: nxapi_auth=dzqnf:1fNa+E8KGq0ZZM6TRZTFKTWejBg=; Secure; HttpOnly;
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
< Strict-Transport-Security: max-age=31536000; includeSubDomains
< Content-Security-Policy: block-all-mixed-content; base-uri 'self'; default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' ; connect-src 'self'; font-src 'self'; object-src 'none'; media-src 'self'; form-action 'self'; frame-ancestors 'self';
< 
{
        "jsonrpc":      "2.0",
        "result":       {
                "header_str":   "Cisco Nexus Operating System (NX-OS) Software\nTAC support: http://www.cisco.com/tac\nDocuments: http://www.cisco.com/en/US/products/ps9372/tsd_products_support_series_home.html\nCopyright (c) 2002-2020, Cisco Systems, Inc. All rights reserved.\nThe copyrights to certain works contained herein are owned by\nother third parties and are used and distributed under license.\nSome parts of this software are covered under the GNU Public\nLicense. A copy of the license is available at\nhttp://www.gnu.org/licenses/gpl.html.\n",
                "bios_ver_str": "2.1.17",
                "loader_ver_str":       "N/A",
                "kickstart_ver_str":    "8.4(1)SK(0) [build 8.4(1)SK(0.160)] [gdb]",
                "sys_ver_str":  "8.4(1)SK(0) [build 8.4(1)SK(0.160)] [gdb]",
                "bios_cmpl_time":       "01/08/14",
                "kick_file_name":       "bootflash:///kick-sky160",
                "kick_cmpl_time":       " 12/20/2020 12:00:00",
                "kick_tmstmp":  "09/08/2020 09:42:15",
                "isan_file_name":       "bootflash:///sky-sep14-02",
                "isan_cmpl_time":       " 12/20/2020 12:00:00",
                "isan_tmstmp":  "09/14/2020 05:56:35",
                "chassis_id":   "MDS 9250i 40 FC 2 IPS 8 FCoE (2 RU) Chassis",
                "module_id":    "40FC+8FCoE+2IPS Supervisor",
                "cpu_name":     "Motorola, e500v2",
                "memory":       4088480,
                "mem_type":     "kB",
                "proc_board_id":        "JAF1852AAFC",
                "host_name":    "host",
                "bootflash_size":       4001760,
                "kern_uptm_days":       0,
                "kern_uptm_hrs":        1,
                "kern_uptm_mins":       25,
                "kern_uptm_secs":       13,
                "rr_usecs":     715180,
                "rr_ctime":     "Mon Jun 14 12:02:47 1976",
                "rr_reason":    "Reset Requested by CLI command reload",
                "rr_sys_ver":   "8.4(1)SK(0.160)",
                "rr_service":   "",
                "manufacturer": "Cisco Systems, Inc."
        },
        "id":   1,
        "cmd":  "show version"
* Connection #0 to host 10.197.155.246 left intact

You can access sample scripts that demonstrate how to use a script with NX-API. To access a sample script, click the following link then choose the directory that corresponds to the required software release: https://github.com/datacenter/nxos/tree/master/nxapi/samples.

Configuring NX-API Sandbox

1. Enable and configure the NX-API feature. For information on how to enable and configure the NX-API feature, refer the Configuring NX-API CLI section.

2. Enable the NX-API sandbox:

   switch# configure terminal
   switch(config)# nxapi sandbox

To view the NX-API settings, use show nxapi command.

switch# show nxapi

NX-API:       Enabled         Sandbox:      Enabled     
HTTP Port:    Disabled        HTTPS Port:  8443         

Certificate Information:
    Issuer:   C=US, ST=CA, L=San Jose, O=Cisco Systems Inc., OU=dcnxos, CN=nxos
    Expires:  Nov 26 09:26:12 2019 GMT                                         
    Content:  -----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIJAObmdczeHJL8MA0GCSqGSIb3DQEBCwUAMGoxCzAJBgNV
BAYTAlVTMQswCQYDVQQIDAJDQTERMA8GA1UEBwwIU2FuIEpvc2UxGzAZBgNVBAoM
EkNpc2NvIFN5c3RlbXMgSW5jLjEPMA0GA1UECwwGZGNueG9zMQ0wCwYDVQQDDARu
eG9zMB4XDTE5MTEyNTA5MjYxMloXDTE5MTEyNjA5MjYxMlowajELMAkGA1UEBhMC
VVMxCzAJBgNVBAgMAkNBMREwDwYDVQQHDAhTYW4gSm9zZTEbMBkGA1UECgwSQ2lz
Y28gU3lzdGVtcyBJbmMuMQ8wDQYDVQQLDAZkY254b3MxDTALBgNVBAMMBG54b3Mw
ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDreVT3LAYarHxZxELwNwst
ZQqlmah5PJHBGUx+3YQcRi8v8wrEsRI7bZrQgDzXkFEH9yroJUghdc0nkM1GYHNF
avbj4qRaEveRejtGZNMPi11tAOWbRsU0ldxODV3+SeG/A220Bal58JzJjje5wyi8
Wu8UR8w4Lb32GYXI8ifBtlU0LrNsS0pE68yJt782y8IJIAEjGWX3L8dle4qwRqXg
6GBDPbwKFCvi+NX8JN48olONASSHXGdcmZSfiYUNKPD7+AwjG/luxSyIqnFW2w06
zwQLoIbXJx7zvl0Adt3H4ZnaRZOG5UvsWLgEdJZJkaqQPe0+7cpwcubN9/PJlO0l
AgMBAAGjUDBOMB0GA1UdDgQWBBTUI4IqOqmoKy5LEjygiJzd2nEGWzAfBgNVHSME
GDAWgBTUI4IqOqmoKy5LEjygiJzd2nEGWzAMBgNVHRMEBTADAQH/MA0GCSqGSIb3
DQEBCwUAA4IBAQC+7TPfDAz1t4yvG4rpypinU2Plp2FOBRdU85CIVREIplbRX8Vv
VMXYySnrKDjVRPcWtY+EtDW91BfS2I2usHkiKcnOYazDoxpamFI3D6lmb82JAAqG
NMV56hIJAYMpVqfbI+vtC93NR3F2fLD8/Hm/X4L8U6kdu2o+vgqYtc4OOl87lhJS
R8xA2N9kihOA1FUMVL89cFgRvxONjAyQImTB8uWl1stUGpH2kE3dABHC1sbZ1dNw
2/OxpfGnj1Qjvi4wKqjGpX/Kqc0AIx2zsKEX9hpPMQK/wlaRg8hlNCXJzzTQ7IVX
7PWJSqn7gpfyZIgZ9JQQ/WieCH32mQ2xGMDD
-----END CERTIFICATE-----

To access the NX-API Developer Sandbox, follow these steps:

Note	When using the NX-API Developer Sandbox, we recommend that you use Firefox Release 24.0 or later. The browser must be installed with the latest Adobe Flash player for the Copy and Python buttons in the NX-API Developer Sandbox to function.

1. Open a browser and enter http://switch_ip_address :port-number for HTTP, or https://switch_ip_address :port-number for HTTPS in the address bar.

   The NX-API Developer Sandbox Authentication window is displayed:

   
   

   

   
   

2. Log in using your switch credentials.

   The NX-API Developer Sandbox window is displayed.

The NX-API Developer Sandbox is a web form that is hosted on the switch. It translates NX-OS CLI commands into equivalent XML or JSON payloads, and converts NX-API payloads into their CLI equivalents.

The web form is a single screen with three panes—Command (top pane), Request, and Response—as shown in the Figure 3.

Controls in the Command pane allow you to choose a message format for a supported API, such as NX-API, and a command type, such as XML or JSON. The available command type options vary depending on the selected message format.

To generate an output of a command using the NX-API Developer Sandbox, follow these steps:

1. Click the Message format type (json-rpc, xml, json) in which the command output is to be displayed. (By default, json-rpc is selected.)

2. Click the Command type you have entered. The options differ based on the Message format type selected. (By default, cli is selected.)

   You can erase the contents of the text entry box (and the Request and Response panes) by clicking Reset at the bottom of the top pane.

   Note

   If you select the xml Message format, you can enable chunk mode for the cli_show and cli_show_ascii Command types. Check the Enable chunk mode check box to chunk large show command outputs. To view the next chunk of the output, copy the session ID (SID) mentioned in between <sid> and </sid> tags in the RESPONSE area and paste it in the SID box below the Enable chunk mode check box.

3. Type or paste NX-OS CLI configuration commands, one command per line, into the text entry box in the top pane.

4. The command that you entered is displayed in the selected Message format in the REQUEST area.

   The Request pane also has a series of tabs. Each tab represents a different language: Python, Java, and JavaScript. Each tab enables you to view the request in the respective language. For example, after converting CLI commands into an XML or JSON payload, click the Python tab to view the request in Python, which you can use to create scripts.

   • To copy the data populated in the REQUEST area, click Copy.

   • To generate a Python code for the command entered, click Python.

     Note	The xml Message format does not support the Python button.

5. Click POST to generate the output of the command.

   The output of the command is displayed in the RESPONSE area.

   • To copy the data populated in the RESPONSE area, click Copy.

   To clear the command and the corresponding output, and reset the page, click Reset.

6. Click Command Reference to view the list of show commands that are supported for NX-API.

   The Command Schema pane displays the details of the command that is selected in the Show commands pane.

   Note	Currently, the Command Reference tab supports only the show commands.

   

   1	Show commands—Displays the list of supported show commands.
   2	Command Schema—Displays the NX-API schema (keywords and description) for a command selected in the Show commands pane.

Example: Displaying NX-API Status

The following example displays the NX-API status response in different output formats:

XML Format

show nxapi

Request:

<?xml version="1.0"?>
<ins_api>
  <version>1.2</version>
  <type>cli_show</type>
  <chunk>0</chunk>
  <sid>sid</sid>
  <input>show nxapi</input>
  <output_format>xml</output_format>
</ins_api>

Response:

<ins_api>
  <type>cli_show</type>
  <version>1.2</version>
  <sid>eoc</sid>
  <outputs>
    <output>
      <body>
     <nxapi_status>Enabled</nxapi_status>
     <sandbox_status>Enabled</sandbox_status>
     <http_port>8080</http_port>
    </body>
      <input>show nxapi</input>
      <msg>Success</msg>
      <code>200</code>
    </output>
  </outputs>
</ins_api>

JSON Format

show nxapi

Request:

{
  "ins_api": {
    "version": "1.2",
    "type": "cli_show",
    "chunk": "0",
    "sid": "1",
    "input": "show nxapi",
    "output_format": "json"
  }
}
 

Response:

{
  "ins_api": {
    "type": "cli_show",
    "version": "1.2",
    "sid": "eoc",
    "outputs": {
      "output": {
        "input": "show nxapi",
        "msg": "Success",
        "code": "200",
        "body": {
          "nxapi_status": "Enabled",
          "sandbox_status": "Enabled",
          "http_port": "8080"
        }
      }
    }
  }
}
 

JSON-RPC Format

show nxapi

Request:

[
  {
    "jsonrpc": "2.0",
    "method": "cli",
    "params": {
      "cmd": "show nxapi",
      "version": 1.2
    },
    "id": 1
  }
]
 

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "body": {
      "nxapi_status": "Enabled",
      "sandbox_status": "Enabled",
      "http_port": "8080"
    }
  },
  "id": 1
}
 

Example: Configuring VSAN to VLAN Mapping

The following example shows how to configure VSAN to VLAN mapping in global configuration mode (cli_conf):

vlan 3
fcoe vsan 3
vsan database
vsan 3
vsan 3 interface vfc1/8

Request:

<?xml version="1.0"?>
<ins_api>
  <version>1.2</version>
  <type>cli_conf</type>
  <chunk>0</chunk>
  <sid>sid</sid>
  <input>vlan 3 ;fcoe vsan 3 ;vsan database ;vsan 3 ;vsan 3 interface vfc1/8</input>
  <output_format>xml</output_format>
</ins_api>

Response:

<?xml version="1.0"?>
<ins_api>
  <type>cli_conf</type>
  <version>1.2</version>
  <sid>eoc</sid>
  <outputs>
    <output>
      <body/>
      <input>vlan 3</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body/>
      <input>fcoe vsan 3</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body/>
      <input>vsan database</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body/>
      <input>vsan 3</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body/>
      <input>vsan 3 interface vfc1/8</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
  </outputs>
</ins_api>

Example: Configuring Zones and Zonesets

The following example shows how to configure a zone in global configuration mode (cli_conf):

zone name zone2 vsan 1
member pwwn 10:00:00:23:45:67:89:ab
member pwwn 10:00:00:23:45:67:89:cd

Request:

<?xml version="1.0"?>
<ins_api>
  <version>1.2</version>
  <type>cli_conf</type>
  <chunk>0</chunk>
  <sid>sid</sid>
  <input>zone name zone2 vsan 1 ;member pwwn 10:00:00:23:45:67:89:ab ;member pwwn 10:00:00:23:45:67:89:cd</input>
  <output_format>xml</output_format>
</ins_api>

Response:

<?xml version="1.0"?>
<ins_api>
  <type>cli_conf</type>
  <version>1.2</version>
  <sid>eoc</sid>
  <outputs>
    <output>
      <body/>
      <input>zone name zone2 vsan 1</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body/>
      <input>member pwwn 10:00:00:23:45:67:89:ab</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body/>
      <input>member pwwn 10:00:00:23:45:67:89:cd</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
  </outputs>
</ins_api>

The following example shows how to configure a zoneset in global configuration mode (cli_conf):

zoneset name Zoneset1 vsan 1
member zone2
zoneset activate name Zoneset1 vsan 1

Request:

<?xml version="1.0"?>
<ins_api>
  <version>1.2</version>
  <type>cli_conf</type>
  <chunk>0</chunk>
  <sid>sid</sid>
  <input>zoneset name Zoneset1 vsan 1 ;member zone2 ;zoneset activate name Zoneset1 vsan 1</input>
  <output_format>xml</output_format>
</ins_api>

Response:

<?xml version="1.0"?>
<ins_api>
  <type>cli_conf</type>
  <version>1.2</version>
  <sid>eoc</sid>
  <outputs>
    <output>
      <body/>
      <input>zoneset name Zoneset1 vsan 1</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body/>
      <input>member zone2</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body>Zoneset activation initiated. check zone status
</body>
      <input>zoneset activate name Zoneset1 vsan 1</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
  </outputs>
</ins_api>

If a show command is not NX-API-aware, the output can still be accessed by setting the Command type element to cli_show_ascii for JSON and XML encoded requests, or show_ascii for JSON-RPC encoded requests. The command output is returned in the response body as a single flat string.

The following figure provides an example for a show command output that is not NX-API-aware, in the NX-API Developer Sandbox.

NX-API request elements are sent to a device in XML, JSON, or JSON-RPC formats. The HTTP header of the request must identify the content type of the request.

Note	A lock will be released by the system if the session that holds the lock is terminated for any reason. The session that acquired the lock can only perform necessary configurations.