HTTP API
Cumulus Linux implements an HTTP (Web) application programing interface to the OpenStack ML2 driver and the NCLU API. Rather than accessing Cumulus Linux using SSH, you can interact with the switch using an HTTP client, such as cURL, HTTPie or a web browser.
The HTTP API service is enabled by default on chassis hardware only. However, the associated server is configured to only listen to traffic originating from within the chassis.
The service is not enabled by default on non-chassis hardware.
HTTP API Basics
If you are upgrading from a version of Cumulus Linux earlier than 3.4.0, the supporting software for the API may not be installed. Install the required software with the following command.
cumulus@switch:~$ sudo apt-get install python-cumulus-restapi
Then restart the nginx
service to apply the API configuration.
cumulus@switch:~$ sudo 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/stop
the HTTP API service:
cumulus@switch:~$ sudo systemctl start restserver
cumulus@switch:~$ sudo systemctl stop restserver
Use the systemctl disable
command to disable the HTTP API service
from running at startup:
cumulus@switch:~$ sudo systemctl disable restserver
Each service runs as a background daemon once started.
Configuration
There are two configuration files associated with the HTTP API services:
/etc/nginx/sites-available/nginx-restapi.conf
/etc/nginx/sites-available/nginx-restapi-chassis.conf
The first configuration file is used for non-chassis hardware; the second, for chassis hardware.
Generally, only the configuration file relevant to your hardware needs to be edited, as the associated services determine the appropriate configuration file to use at run time.
Enable External Traffic on a Chassis
The HTTP API services are configured to listen on port 8080 for chassis hardware by default. However, only HTTP traffic originating from internal link local management IPv6s will be allowed. To configure the services to also accept HTTP requests originating from external sources:
Open
/etc/nginx/sites-available/nginx-restapi-chassis.conf
in a text editor.Uncomment the
server
block lines near the end of the file.Change the port on the now uncommented
listen
line if the default value, 8080, is not the preferred port, and save the configuration file.Verify the configuration file is still valid:
cumulus@switch:~$ sudo nginx -c /etc/nginx/sites-available/nginx-restapi-chassis.conf -t
If the configuration file is not valid, return to step 1; review any changes that were made, and correct the errors.
Restart the daemons:
cumulus@switch:~$ sudo systemctl restart restserver
IP and Port Settings
The IP:port combinations that services listen to can be modified by
changing the parameters of the listen
directive(s). By default,
nginx-restapi.conf
has only one listen
parameter, whereas
/etc/nginx/sites-available/nginx-restapi-chassis.conf
has two
independently configurable server
blocks, each with a listen
directive. One server block is for external traffic, and the other for
internal traffic.
All URLs must use HTTPS, rather than HTTP.
For more information on the listen directive, refer to the NGINX documentation.
Do not set the same listening port for internal and external chassis traffic.
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 should correspond to a user on the host switch.
Transport Layer Security
All traffic must be secured in transport using TLSv1.2 by default. Cumulus Linux contains a self-signed certificate and private key used server-side in this application so that it works out of the box, but using your own certificates and keys is recommended. Certificates must be in the PEM format.
For step by step documentation for generating self-signed certificates and keys, and installing them to the switch, refer to the Ubuntu Certificates and Security documentation.
Do not copy the cumulus.pem
or cumulus.key
files. After
installation, edit the ssl\_certificate
and ssl\_certificate\_key
values in the configuration file for your hardware.
cURL Examples
This section contains several example cURL commands for sending HTTP requests to a non-chassis 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 -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
To add a bridge using ML2:
cumulus@switch:~$ curl -X PUT -k -u user:pw https://192.168.0.32:8080/ml2/v1/bridge/"br1"/200
Caveats
The /etc/restapi.conf
file is not listed in the net show configuration files
command output.