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
--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.
To automate a purchase, you should use the global
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:
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.
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
For more information on
sslmate download, see the
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
--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,
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
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.