• NX-API CLI spawns VSH to execute Cisco NX-OS CLIs on a switch. The VSH timeout limit is 5 minutes. If the Cisco NX-OS CLIs take longer than 5 minutes to execute, the commands fail with the message: "Back-end processing error.". This is governed by the NX-API command timeout, which governs how long a command requested via NX-API can run. It is fixed at 300s and cannot be changed.

• Beginning with Cisco NX-OS Release 10.2(1)F, can use system server session cmd-timeout to increase the timeout.

• NX-API spawns the worker processes and load balances the request between the worker processes.

  • The number of nginx backend worker processes is 4.

  • The number of nginx backend worker processes in N3k and the low memory-based platform is 2.

• Each worker process maintains a pool of 5 persistent VSH sessions. Each VSH session is uniquely identified with a combination of username and remote IP from the incoming request. Whenever a new request comes, the worker process checks if a matching username and remote IP entry is already present, if yes then use the corresponding VSH session else a new VSH session is created based on the availability in the pool and a new entry is added into the pool. If a worker process is already running with the max allowed VSH sessions, then the new request will be rejected, and an appropriate error message will be returned in the response.

• The number of VSH sessions per worker process is a hardcoded value and cannot be configured. The total number of sessions that can exist at any point in time is 20.

• Whenever the trustpoint, certificate, or key associated with NX-API is deleted, NX-API still keeps NX-API certificate, trustpoint, or NX-API client certificate authentication configurations. Therefore, the NX-API functionality gets impacted. Though the current instance of NX-API works fine, the reconfigurations of any NX-API commands can cause breakage to it. To prevent this, it is important to delete or update the NX-API configurations also when trustpoint or certiifcate is deleted using no crypto ca trustpoint command.

Chunk-mode

• Chunk mode supports only 2 concurrent sessions. If the chunk option is selected, then it can be given only in 2 parallel sessions at a time.

• The maximum size of response supported for chunk mode is 200MB until the release 10.3(1)F release.

• After the 10.3(1)F release, the chunk mode supports the response size, until the space is available in the volatile (which is approximately 2.0GB). The size of chunk mode response supports depends on the space in the volatile. Once volatile is 90% full, chunk mode returns failure when first the show output is collected to file. The chunk size supported for each response is 10MB.

Certificate authentication has the following guidelines and limitations:

• The NX-API client must be configured with a user name and password.

• The NX-API client and the switch communicate over HTTP by default on its well-known port. For flexibility HTTP is also supported on its well-known port. However, you can configure additional ports.

• Python scripting of client certificate authentication is supported. If the client certificate is encrypted with a passphrase, python successfully prompts for the passphrase. However, the passphrase cannot be passed into the script due to a current limitation with the Python requests library.

• The NX-API client and switch must use the same trustpoint.

• The maximum number of trustpoints supported is 26 for each switch.

• The list of trusted CAs must be the same for all NX-API clients and the switch. Separate lists of trusted CAs are not supported.

• Certificate authentication is not supported for the NX-API sandbox.

• The following conditions determine if the NX-API sandbox loads on the switch:

  • The NX-API sandbox loads only when nxapi client certificate authentication optional or no nxapi client certificate authentication are configured.

  • The NX-API sandbox does not load for strict and two-step authentication modes unless a valid client certificate is presented to the browser when a connection is being established.

• The switch has an embedded NGINX server. If multiple trustpoints are configured, but a certificate revocation list (CRL) is installed for only one of the trustpoints, NX-API client certificate authentication fails because of an NGINX limitation. To workaround this limitation, configure CRLs for all trustpoints.

• Certificates can expire or become out of date, which can affect the validity of the CRL set by the CA (trustpoint). To ensure the switch uses valid CRLs, always install CRLs for all of the configured trustpoints. If no certificates were revoked by the trustpoints, an empty CRL should be generated, installed, and updated periodically, for example, once a week.

  After you update the CRLs through the crypto CLIs, issue nxapi client cert authentication to reapply the newly updated CRLs.

• If you use ASCII reload when NX-API client certificate authentitcation is enabled, you must issue nxapi client certificate authentication after the reload is complete.

• The certificate path must terminate with a trusted CA certificate.

• Server certificates that are presented for TLS must have the Server Authentication purpose (id-kp 1 with OID 1.3.6.1.5.5.7.3.1) in the extendedKeyUsage field.

• Client certificates that are presented for TLS must have the Server Authentication purpose (id-kp 1 with OID 1.3.6.1.5.5.7.3.2) in the extendedKeyUsage field.

• The feature supports CRLs (certificate revocation lists). Online Certificate Status Protocol (OSCP) is not supported.

• Follow the additional Guidelines and Limitations in the NX-OS Security Guide.

  • Use both certificate and basic authentication. By doing so, the correct user and password is still required if the certificate somehow gets compromised.

  • Keep private keys private, as the servers public key is accessible to anyone attempting a connection.

  • CRLs should be downloaded from the central CA and kept current. Out-of-date CRLs can lead to a security risk.

  • Keep trustpoints updated. When a trust point or configuration change is made to the certificate authentication feature, explicitly disable then reenable the feature to reload the updated information.

• There is a maximum file size limit of 8K for the client certificate identity file associated to NX-API with nxapi certificate httpscert certfile bootflash:<> " CLI." This is a day-1 limitation.

• In the NX-API Management Commands Table 1 for the row associated with the command nxapi certificate {httpscrt certfile | httpskey keyfile} filename, the maximum certfile size supported is less than 8K.

Before configuring certificate authentication, make sure the following are present on the switch:

1. Configure the client with a username and password. For information see Configuring User Accounts and RBAC.

2. Configure the CA(s) (trustpoint) and CRL(s) (if any).

If no certificates were revoked by a trustpoint, create a blank CRL for each trustpoint.

For information, see the Cisco Nexus 9000 Series NX-OS Security Configuration Guide.

The following example shows a Python script with a client certificate for authentication.

import requests
import json

"""
Modify these please
"""
switchuser='USERID'
switchpassword='PASSWORD' 
mgmtip='NXOS MANAGEMENT IP/DOMAIN NAME'

client_cert_file='PATH_TO_CLIENT_CERTIFICATE'
client_key_file='PATH_TO_CLIENT_KEY_FILE'
ca_cert='PATH_TO_CA_CERT_THAT_SIGNED_NXAPI_SERVER_CERT'

url='https://' + mgmtip + '/ins'
myheaders={'content-type':'application/json-rpc'}
payload=[
  {
    "jsonrpc": "2.0",
    "method": "cli",
    "params": {
      "cmd": "show clock",
      "version": 1
    },
    "id": 1
  }
]
response = requests.post(url,data=json.dumps(payload), headers=myheaders,auth=(switchuser,switchpassword),cert=(client_cert_file_path,client_key_file),verify=ca_cert).json()

If needed, you can change the script:

• Depending on the client certificate authentication mode, you can omit the switch password by setting the switch password to a null value (switchpassword= ):

  • For optional and strict modes, the switchpassword= can be left blank. In this situation, NX-API authenticates the client based on username and client certificate alone.

  • For two-step mode, a password is required, so you must specify a value for switchpassword= .

• You can bypass verifying that the NX-API server's certificate is valid by setting verify=False in the POST command.

The following example shows a correctly structured cURL certificate request for NX-API client authentication.

/usr/bin/curl --user admin: --tlsv1.2 --cacert ./ca.pem --cert ./user.crt:pass123! --key ./user.key -v -X POST -H "Accept: application/json" -H "Content-type: application/json" --data '{"ins_api":{"version": "1.0", "type": "cli_show", "chunk": "0", "sid": "1", "input": "show clock","output_format": "json"}}' https://<device-management-ip>:443/ins

Syntax Elements

The following table shows the parameters that are used in this request.