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.

Automating Purchases

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

sslmate --batch buy --no-wait --email=ADDRESS HOSTNAME

This command will generate a private key for HOSTNAME, place the order, send the approval email to ADDRESS, 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 --email=ADDRESS HOSTNAME fi

ADDRESS must be one of the following addresses:

  • The webmaster@, hostmaster@, postmaster@, admin@, or administrator@ addresses at either your domain or the sub-domain for which you are buying a certificate.
  • One of the email addresses listed in the publicly-available whois record for your domain. (Note: this is only available with TLDs that publish email addresses in the public whois system.)

Responding to the approval email is a manual step. To fully automate the process, you can use DNS-based approval, and have SSLMate automatically provision a DNS record to approve the certificate. For details, see the DNS approval page. Example:

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

SSLMate is currently testing HTTP-based approval that would allow you to approve a certificate by serving a file from your web server. Contact us if you'd like to take part in the beta.

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.

Get Started with SSLMate Today

Buy a new certificate, or import your existing certs for free.

Click to sign up