HTTP API
Cumulus Linux implements an HTTP application programing interface to NCLU. Instead of accessing Cumulus Linux using SSH, you can interact with the switch using an HTTP client, such as cURL, HTTPie or a web browser.
HTTP API Basics
The supporting software for the API is installed with Cumulus Linux.
To use the REST API, you must enable nginx on the switch:
cumulus@switch:~$ sudo systemctl enable nginx; systemctl restart nginx
To enable the HTTP API service, run the following systemd command:
cumulus@switch:~$ sudo systemctl enable restserver
Use the systemctl start and systemctl stop commands to start or stop the service:
cumulus@switch:~$ sudo systemctl start restserver
cumulus@switch:~$ sudo systemctl stop restserver
Use the systemctl disable command to disable the service from running at startup:
cumulus@switch:~$ sudo systemctl disable restserver
Each service runs as a background daemon.
Configuration
To configure the HTTP API services, edit the /etc/nginx/sites-available/nginx-restapi.conf configuration file, enter in the IP address in which the REST API will listen on and then run the command sudo systemctl restart nginx.
IP and Port Settings
You can modify the IP:port combinations to which services listen by changing the parameters of the listen directive(s). By default, nginx-restapi.conf has only one listen parameter.
All URLs must use HTTPS instead of HTTP.
For more information on the listen directive, refer to the NGINX documentation.
Security
Authentication
The default configuration requires all HTTP requests from external sources (not internal switch traffic) to set the HTTP Basic Authentication header.
The user and password must correspond to a user on the host switch.
cURL Examples
This section includes several example cURL commands you can use to send HTTP requests to a host. The following settings are used for these examples:
- Username:
user - Password:
pw - IP:
192.168.0.32 - Port:
8080
Requests for NCLU require setting the Content-Type request header to be set to application/json.
The cURL -k flag is necessary when the server uses a self-signed certificate. This is the default configuration (see the Security section). To display the response headers, include the -D flag in the command.
To retrieve a list of all available HTTP endpoints:
cumulus@switch:~$ curl -X GET -k -u user:pw https://192.168.0.32:8080
To run net show counters on the host as a remote procedure call:
cumulus@switch:~$ curl -X POST -k -u user:pw -H "Content-Type: application/json" -d '{"cmd": "show counters"}' https://192.168.0.32:8080/nclu/v1/rpc
Caveats
The /etc/restapi.conf file is not listed in the net show configuration files command output.