Using Certbot to get single domain certificates

June 17th, 2020

You can use Certbot to easily get single domain certificates (non-wildcard, you can actually get a certificate that covers several domains) using web root verification.

Requirements and preliminary information

  • You must be using a Linux OS

  • Certbot is supported on macOS but these instructions and the scripts provided in Mango may not work on macOS

  • Certbot is not supported on Windows, other LetsEncrypt clients do exist but these instructions are for Certbot

  • You must be running Mango version >= 3.5.4 so the certificate keystore can be automatically be reloaded and the scripts are present

  • Mango must be accessible on the internet via HTTP on port 80 using the domain name that you are trying to get a certificate for

  • Throughout these instructions Mango is assumed to be installed at /opt/mango, this may be different for your installation

  • You may need to set environment variables to customise the behaviour of the deploy/keygen script, see the section at the bottom

  • Run all the commands listed as root, be careful!

Install Certbot

Follow the instructions from https://certbot.eff.org/ to install Certbot on your particular Linux distribution. If you have trouble you might consider the alternative installation methods.

Configure your mango.properties file

Ensure Mango is stopped

/opt/mango/bin/mango-stop.sh > /dev/null 2>&1

Edit your mango.properties file

nano /opt/mango/mango.properties

Use the following settings

ssl.on=true
ssl.keystore.watchFile=true
ssl.keystore.location=/opt/mango-data/keystore.jks
ssl.keystore.password=<Enter a strong generated password here>
#Leave the following setting commented out
#ssl.key.password=
# mango must be accessible on port 80
web.port=80

Ensure that you have an initial temporary keystore

In order to start mango you need to have a keystore in the location specified in your env.properties file. You can generate a temporary one (a self signed certificate) by running

/opt/mango/bin/genkey.sh

Or you can manually generate one my using keytool which is supplied with your Java installation. As long as the
mango.properties file variable points to the keystore, the command will work.

keytool -genkey -alias mango -keystore /opt/mango-data/keystore.jks

Ensure your keystore has the correct owner and permissions so it remains private. Assuming that you run Mango under the user mango and group mango

chown mango:mango /opt/mango-data/keystore.jks

chmod 400 /opt/mango-data/keystore.jks

Start Mango

Start Mango and wait for it to fully initialise

/opt/mango/bin/mango-start.sh > /dev/null 2>&1

Run Certbot to get your initial certificate

You might need to use certbot-auto instead of certbot depending on your installation method.

certbot certonly --webroot --deploy-hook "/opt/mango/bin/certbot-deploy.sh" -w "/opt/mango/web" -d yourdomain.com -d domain2.com

Certbot will ask you for your email and ask you to agree to the terms of service. Provided you set everything up correctly it should tell you everything was successful. You should see that certbot ran the certbot-deploy.sh script. The deploy script will automatically use the keystore password from your env.properties file.

Check your ma.log file, you should see a line at the bottom telling you that Mango reloaded your keystore.

If you need to change any of the environment variables (see bottom of document) you can add them like so

certbot certonly --webroot --deploy-hook "sh -c 'mango_paths_home=/opt/mango /opt/mango/bin/certbot-deploy.sh'" -d yourdomain.com -d domain2.com

Renewing certificates

In order to renew all of your certificates you can just run

certbot renew

Certbot knows how to verify your domain from a configuration file located at /etc/letsencrypt/renewal/yourdomain.com, and knows to run the deploy script so Mango gets an updated Java keystore.

Scheduling automated renewal

You probably want to automate the renewal process, you simply need to setup a cron job to run Certbot renewal command.

Edit the root crontab

crontab -e

Add the following line so certbot runs twice a day (first number is the minutes, you can randomize this)

0 */12 * * * root /usr/bin/certbot renew --quiet

Re-creating your keystore

If you have any issues with getting certificates from Let’s Encrypt you might want to manually trigger the deploy script to create your keystore from the Certbot certificate directory.

RENEWED_LINEAGE=/etc/letsencrypt/live/yourdomain.com /opt/mango/bin/certbot-deploy.sh

Environment variables

You may need to customise the behaviour of the scripts by setting environment variables if you have a non-standard setup.

Environment variable Description Default
MA_HOME Path to the Mango installation directory The directory below where the script is located or /opt/mango
MA_ENV_PROPERTIES Path to env.properties file $MA_HOME/overrides/properties/env.properties
MA_KEYSTORE Path to the keystore file ssl.keystore.location from env.properties file
MA_KEYSTORE_PASSWORD Keystore password ssl.keystore.password from env.properties file
MA_KEY_PASSWORD Password for the individual key inside the keystore sl.key.password from env.properties or ssl.keystore.password if not specified
MA_KEY_ALIAS Alias for the individual key inside the keystore mango

Copyright © 2024 Radix IoT, LLC.