Using TLS with MAAS Site Manager

Using TLS with MAAS Site Manager

Below, we detail how to get a MAAS instance to enrol with a MAAS Site Manager instance that is using TLS.

Trusted CA

If MAAS Site Manager uses an SSL certificate that was issued by a trusted certificate authority, MAAS should be able to connect to Site Manager smoothly. Proceed with enrolment as shown below:

sudo maas msm enrol ${ENROLMENT_TOKEN} ${SITE_CONFIG_YAML} # Optional YAML config

MAAS will fetch the SSL certificate provided by Site Manager and ask for confirmation before proceeding. To do so, it uses the value of the enrolment-url claim within the payload of the $ENROLMENT_TOKEN. This URL is configurable within Site Manager (see TODO: primary doc for enrolment).

When given the prompt below, enter ‘y’ to proceed or ‘n’ to abort:

The URL of the Site Manager you want to enrol with is https://my-site-manager.

The certificate of the Site Manager you want to enrol with is the following:

        CN:                       my-site-manager
        Expiration date:    Wed, 30 Apr. 2025
        Fingerprint:           f3a6df9e26720df0cec5b68ee5eb40d697b2d2a0
        Issued By:            Super Awesome Authority

You can verify its authenticity by comparing the certificate shown above with the certificate shown in the settings/tokens page of Site Manager.
Are you sure you want to enrol with this site? [Y] [n]

Using a self-signed certificate

If your Site Manager instance uses a self-signed SSL certificate, you can allow MAAS to trust it by following these steps:

Upload the certificate to the Region Controller machine

First, upload Site Manager’s self-signed certificate (in PEM format) to the machine running the region controller and place it in /usr/local/share/ca-certificates. This may be done in a multitude of ways, for example with scp and ssh:

scp /path/on/your/machine/sitemanager.crt ${USER}@${REGION_CONTROLLER_IP}:/home/${USER}/
# scp cannot move files to protected folders, so we need to ssh and move it ourselves
ssh ${USER}@${REGION_CONTROLLER_IP} bash -c "sudo cp /home/${USER}/sitemanager.crt /usr/local/share/ca-certificates"

Update the list of trusted certificate authorities

To update the list of trusted CA’s, run the following command on the machine running the region controller:

sudo update-ca-certificates

Ensure Site Manager is reachable by hostname

Site Manager must be reachable by the hostname specified in the JWT token used for enrolment. This hostname must also match the subject’s Common Name (CN) specified by Site Manager’s SSL certificate. To check the certificate’s CN and add it to the list of hosts, run the following command on the machine running the region controller:

# replace "sitemanager.crt" with the actual filename
HOSTNAME=$(openssl x509 -noout -subject -in /usr/local/share/ca-certificates/sitemanager.crt -nameopt multiline | grep commonName | awk '{ print $3 }')
echo ${SITE_MANAGER_IP} ${HOSTNAME} | sudo tee --append /etc/hosts

Replace symbolic link with actual file (Snap Install Only)

To ensure the MAAS snap can access our newly trusted CA certificate, replace the symbolic link located in /etc/ssl/certs with an actual file on the region controller machine:

# replace "sitemanager.crt" with the name of the file you uploaded earlier.
# DO NOT change the ".pem" ending of the new file in /etc/ssl/certs/, but keep the
# same base name as the certificate in /usr/local/share/ca-certificates/
cp /usr/local/share/ca-certificates/sitemanager.crt /etc/ssl/certs/sitemanager.pem

Continue with enrolment

Once these steps are finished, you may continue with enrolment normally.