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.