Cumulus Linux implements an HTTP application programing interface to OpenStack ML2 driver and NCLU. 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.
Then restart the
nginx service to apply the API configuration.
To enable the HTTP API service, run the following
systemctl start and
systemctl stop commands to start/stop the HTTP API service:
There are two configuration files associated with the HTTP API services:
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:
/etc/nginx/sites-available/nginx-restapi-chassis.confin a text editor.
serverblock lines near the end of the file.
Change the port on the now uncommented
listenline if the default value, 8080, is not the preferred port, and save the configuration file.
Verify the configuration file is still valid:
If the configuration file is not valid, return to step 1; review any changes that were made, and correct the errors.
Restart the daemons:
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.
For more information on the listen directive, refer to the NGINX documentation.
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 Cumulus Networks recommends you use your own certificates and keys. 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.
cumulus.keyfiles. After installation, edit the “ssl_certificate” and “ssl_certificate_key” values in the configuration file for your hardware.
This section contains several example cURL commands for sending HTTP requests to a non-chassis host. The following settings are used for these examples:
-kflag 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
-Dflag in the command.
To retrieve a list of all available HTTP endpoints:
net show counters on the host as a remote procedure call:
To add a bridge using ML2: