Skip to content

How to Automate SSLMate

By default, SSLMate commands prompt for user input and wait until certificates have been issued. However, this behavior can be changed with the --batch and --no-wait options, allowing SSLMate to be used unattended from configuration management or other provisioning systems. In addition, SSLMate certificates can be automatically approved by provisioning a DNS record instead of responding manually to an email.

SSLMate is extremely flexible and can be used in many different ways to accommodate your automation needs. This page provides an overview, with examples, of various automation options. You may also want to consult the sslmate(1) man page. SSLMate support is happy to discuss your automation needs and give advice.

To test your automation, you can use the sandbox website, where purchases are free and certificates are signed by an untrusted testing certificate authority.

SSLMate also has a REST API for more advanced automation.

Credentials

To prevent SSLMate from prompting for your username and password every time it is run, you must place your SSLMate API credentials in your /etc/sslmate.conf configuration file.

Automating Purchases

To automate a purchase, you should use the global --batch option, and the sslmate buy-specific --no-wait and --approval options.

sslmate --batch buy --no-wait --approval=APPROVAL HOSTNAME

This command will generate a private key for HOSTNAME, place the order using the given approval method, and return immediately, without installing any certificate files.

You may wish to test for the presence of the private key and avoid purchasing another certificate if a key file already exists:

if ! [ -e /etc/sslmate/HOSTNAME.key ] then sslmate --batch buy --no-wait --approval=APPROVAL HOSTNAME fi

APPROVAL can be either dns or http for DNS or HTTP approval. See the approval documentation for details.

Once the certificate is approved and issued, it needs to be downloaded with the sslmate download command, as described in the next section.

Automating Certificate Downloads

You should periodically run sslmate download, and restart system services if new certificates were downloaded:

if sslmate download --all then service apache2 restart fi

This script should be run from a cron job or from a configuration management script that is run regularly.

Running sslmate download serves two purposes: First, it allows recently-purchased certificates to be downloaded after being approved. Second, it allows updated certificate files to be downloaded after a certificate is renewed.

For more information on sslmate download, see the Download page.

Temporary Certificates

One disadvantage of the --no-wait option is that it installs no certificate files. Most server software refuses to run when SSL certificates are missing, meaning that you have to defer configuration of these services until the certificate is issued and downloaded.

Temporary certificates provide an elegant solution. If you pass the --temp option to sslmate buy instead of --no-wait, SSLMate will immediately install a temporary, self-signed certificate. The temporary certificate will not be trusted by clients, but you can use it to immediately configure and start services. When the certificate is finally issued, sslmate download will replace the temporary certificate with the real certificate.

Same Certificate on Several Servers

Using the same certificate on several servers requires the same private key to be present on each server. SSLMate does not currently manage private key distribution (sslmate download downloads only certificates, not keys), so you need to manage this yourself. It's recommended that you run sslmate buy on a single master system, and then use your configuration management infrastructure to install the resulting private key in /etc/sslmate on each of your servers.

Do not use your configuration management to install certificate files. Instead, have your configuration management run sslmate download as described above. Since private keys rarely change (they only need to be changed if they're compromised), but certificates need to be changed whenever they're renewed, this provides a good division of responsibility between SSLMate and your configuration management system.