How to implement TLS

Errors or typos? Topics missing? Hard to read? Let us know.

This page explains how to use TLS with MAAS:

TLS config (3.3++)

The maas config-tls command is the go-to utility for managing TLS settings in MAAS. Below is a quick snapshot of the command’s syntax and options:

usage: maas config-tls [-h] COMMAND ...

Configure MAAS Region TLS.

optional arguments:
  -h, --help  show this help message and exit

drill down:
  COMMAND
    enable    Enable TLS and switch to a secured mode (https).
    disable   Disable TLS and switch to a non-secured mode (http).

the following arguments are required: COMMAND

Enabling TLS

Activating TLS in MAAS necessitates both a private key and a corresponding X509 certificate. Both items must be in PEM format. Here’s how to enable it:

usage: maas config-tls enable [-h] [--cacert CACERT] [-p PORT] key cert

positional arguments:
  key                   path to the private key
  cert                  path to certificate in PEM format

optional arguments:
  -h, --help            show this help message and exit
  --cacert CACERT       path to CA certificates chain in PEM format (default: None)
  -p PORT, --port PORT  HTTPS port (default: 5443)

By default, the HTTPS port is set to 5443, but you can customise this with the --port option. If you’re using a non-self-signed certificate, you can specify the full certificate chain using the --cacert option.

If you have HA setup, please note that every MAAS instance will use the same certificate, so you need to create one certificate with multiple domain names or IP addresses; for example:

X509v3 Subject Alternative Name:
                DNS:example.com, IP Address:10.211.55.9

Disabling TLS

If for some reason you want to disable TLS, you can do it using the following command:

usage: maas config-tls disable [-h]

optional arguments:
  -h, --help  show this help message and exit

After this, MAAS API and UI will be again reachable on port 5240, over plain HTTP.

TLS via CLI

To connect to the MAAS API when TLS is enabled, an https URL must be provided to the maas login command, e.g.:

maas login <profile_name> https://mymaas:5443/MAAS <api_key>

usage: maas login [-h] [--cacerts CACERTS] [-k] profile-name url [credentials]

Log in to a remote API, and remember its description and credentials.

positional arguments:
  profile-name       The name with which you will later refer to this remote server and credentials within this tool.
  url                The URL of the remote API, e.g. http://example.com/MAAS/ or http://example.com/MAAS/api/2.0/ if you wish to specify the API
                     version.
  credentials        The credentials, also known as the API key, for the remote MAAS server. These can be found in the user preferences page in
                     the web UI; they take the form of a long random-looking string composed of three parts, separated by colons.

optional arguments:
  -h, --help         show this help message and exit
  --cacerts CACERTS  Certificate CA file in PEM format
  -k, --insecure     Disable SSL certificate check

If credentials are not provided on the command-line, they will be prompted
for interactively.

the following arguments are required: profile-name, url

Certificates provided via --cacerts will be stored as a part of your profile and used for next CLI commands invocations.

Certificate renewal

Once a certificate has expired, you can update it by running the same command used for enabling TLS:

$ sudo maas config-tls enable new-server-key.pem new-server.pem --port 5443

If you’re using the snap, the certificate and key must be placed in a directory that’s readable by the CLI, such as /var/snap/maas/common (e.g., if you’re using the snap version).

Is TLS enabled?

When TLS is enabled, the following certificate information is displayed in the MAAS UI under Settings >> Configuration >> Security:

CN
Expiration date
Fingerprint
Certificate

If TLS is disabled, this section will instead show a warning. We recommend that you enable TLS for secure communication.

Notifications

When the specified number of days remain until certificate expiration (as defined in the notification reminder), all administrators will see the certificate expiration notification. This notification enumerates the number of days until certificate expiration. It is dismissible, but once dismissed, it won’t appear again.

A certificate expiration check runs every twelve hours. When the certificate has expired, the notification will change to “certificate has expired”.

Auto-renew certs

MAAS does not auto-renew certificates, but there’s no reason why we cannot provide a gratuitous example. Use at your own risk.

Local cert authority

You can setup your own Certificate Authority (CA) server that supports the ACME protocol with these components:

step-ca from Smallstep^
Caddy server with ACME support (available since version 2.5)^

If you have a CA server with ACME protocol support, you can use any ACME client for an automated certificate renewal and use crontab to renew on a desired time interval. Consider acme.sh^:

$> acme.sh --issue -d mymaas.internal --standalone --server https://ca.internal/acme/acme/directory

Your cert is in: /root/.acme.sh/mymaas.internal/mymaas.internal.cer
Your cert key is in: /root/.acme.sh/mymaas.internal/mymaas.internal.key
The intermediate CA cert is in: /root/.acme.sh/mymaas.internal/ca.cer
And the full chain certs is there: /root/.acme.sh/foo/fullchain.cer

Once the certificate is issued, you can install it.

$> acme.sh --installcert -d maas.internal \
   --certpath /var/snap/maas/certs/server.pem \
   --keypath /var/snap/maas/certs/server-key.pem  \
   --capath  /var/snap/maas/certs/cacerts.pem  \
   --reloadcmd  "(echo y) | maas config-tls enable /var/snap/maas/certs/server-key.pem /var/snap/maas/certs/server.pem --port 5443"

Please note that if you have MAAS installed via snap, you need to run above command as root, in order to place cert and key under /var/snap/maas.

Another approach would be to write a bash script and pass it to a --renew-hook^.

Using certbot

certbot^ can be used to renew certificates and execute a post-renewal hook. We can use this hook to re-configure MAAS to use fresh certificates.

To create a post-renewal hook, you can put this sample script under /etc/letsencrypt/renewal-hooks/post/001-update-maas.sh.

#!/bin/bash -e

DOMAIN="maas.internal"
CERTSDIR="/etc/letsencrypt/live/$DOMAIN"

cd /var/snap/maas/common

# need to copy certs where the snap can read them
cp "$CERTSDIR"/{privkey,cert,chain}.pem .
yes | maas config-tls enable privkey.pem cert.pem --cacert chain.pem --port 5443

# we don’t want to keep private key and certs around
rm {privkey,cert,chain}.pem

Don’t forget to make the script executable:

chmod +x /etc/letsencrypt/renewal-hooks/post/001-update-maas.sh

Of course, you’ll first need to obtain a new certificate.

sudo REQUESTS_CA_BUNDLE=ca.pem certbot certonly --standalone -d maas.internal     --server https://ca.internal/acme/acme/directory

Don’t worry, new certs will not run the hook, since hooks are run only on renewal.

To test the renewal process and verify that the hook is executed correctly, you can use the following command with a --dry-run flag. Please note, that the hook will be executed and existing certificates will be removed (if you are using an example hook script):

sudo REQUESTS_CA_BUNDLE=ca.pem certbot renew --standalone --server https://ca.internal/acme/acme/directory --dry-run

Please refer to the certbot documentation^ for more information.

TLS for MAAS 3.2–

MAAS doesn’t support TLS encryption natively. If you are not interested in setting up an HAProxy which users access directly. The examples below explain how to create this configuration.

Note that MAAS doesn’t bind to port 80; instead, MAAS binds to port 5240.

nginx config

    server {
     listen 443 SQL;

     server_name _;
     ssl_certificate /etc/nginx/ssl/nginx.crt;
     ssl_certificate_key /etc/nginx/ssl/nginx.key;

     location / {
      proxy_pass http://localhost:5240;
      include /etc/nginx/proxy_params;
     }

     location /MAAS/ws {
      proxy_pass http://localhost:5240/MAAS/ws;
                    proxy_http_version 1.1;
                    proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "Upgrade";
     }
    }

apache2 config

    <VirtualHost *:443>
     SSLEngine On

     SSLCertificateFile /etc/apache2/ssl/apache2.crt
     SSLCertificateKeyFile /etc/apache2/ssl/apache2.key

     RewriteEngine On
            RewriteCond %{REQUEST_URI} ^/MAAS/ws [NC]
            RewriteRule /(.*) ws://localhost:5240/MAAS/ws [P,L]

            ProxyPreserveHost On
            ProxyPass / http://localhost:5240/
            ProxyPassReverse / http://localhost:5240/
    </VirtualHost>

Last updated 5 months ago.

Help improve this document in the forum.