SSLMate Agent Help
sslmate-agent
is a daemon that runs on your servers to keep SSL/TLS
certificates up-to-date. sslmate-agent monitors your SSLMate account for
updates, and automatically installs key and certificate files within
minutes of you placing an order for a certificate. sslmate-agent automatically installs renewed
certificates before old ones expire, and can
reload the services that use your certificates (such as your web server).
sslmate-agent takes care of the hard work of generating keys and CSRs, securely synchronizing private keys between servers, and installing new and renewed certificates. It is the best way to manage a large volume of certificates across a fleet of frontend servers.
This document describes how to use sslmate-agent to obtain certificates. If you have any questions, we are here to help.
Installation
The SSLMate client comes in two packages:
sslmate-agent
- The daemon that keeps certificate files up-to-date. Install this on every server which needs certificates. (Alternatively, you can install sslmate-agent on a central orchestration server and synchronize certificates to your frontends yourself, but sslmate-agent is designed to make this unnecessary.)
sslmate
- The command line administration tool for your SSLMate account. Install this on your administrative systems.
The following instructions install both sslmate-agent and sslmate; you can adjust the commands to install only one or the other.
Configuration
sslmate
configuration
To configure the sslmate
command,
you must place your SSLMate API key
in the .sslmate
file in your home directory. For example:
api_key 123_AKRCEYZdHUrjegJ19oyI
Cluster creation
Before you use sslmate-agent
for the first time, you need to create a cluster.
To create a cluster named "webservers", run:
sslmate clusters add webservers
The output of this command looks like:
cluster "webservers" {
secret = "examplesecret:faC4ffCDuEaCv4SFn7mCHTLCqGGaEDrhBB7DI0PRCM8"
}
Copy the output into your sslmate-agent.conf
file, as described in the next section.
Be sure to keep it secret.
You should use the same cluster configuration on all servers that need to share the same set of certificates. If you have some servers that need a different set of certificates, you can create another cluster for those servers.
sslmate-agent
configuration
sslmate-agent
is configured by
the /etc/sslmate-agent/sslmate-agent.conf
file.
At the very least, this file must contain your SSLMate API key
and the cluster configuration that you generated in the previous step. For example:
api_key = "123_AKRCEYZdHUrjegJ19oyI"
cluster "webservers" {
secret = "examplesecret:faC4ffCDuEaCv4SFn7mCHTLCqGGaEDrhBB7DI0PRCM8"
}
Generally, server software (e.g. Apache, nginx) needs to be restarted after certificates change, so you should configure sslmate-agent to execute one or more commands when it updates certificates. For example, the following configuration tells sslmate-agent to restart nginx and Postfix after updating certificates (consult your operating system documentation for the precise way to restart services):
default {
on_update = [
"service nginx restart",
"service postfix restart"
]
}
After changing the sslmate-agent.conf(5)
file,
you must restart sslmate-agent
by running:
service sslmate-agent restart
For more information about configuring sslmate-agent, see the sslmate-agent.conf(5)
man page.
Approving Your Certificates
Before you can get a certificate, you need to prove that you control every DNS name in the certificate, using one of the following two approval methods:
-
With HTTP approval, the certificate authority connects to each DNS name in the certificate over port 80 and retrieves a special URL. If you configure your web server to proxy these special URLs to SSLMate, we'll take care of the rest. For details, see your HTTP approval integration page.
HTTP approval is best when you host websites on behalf of your customers who delegate their vanity domains or sub-domains to your servers. HTTP approval is not available for wildcard DNS names.
-
With DNS approval, the certificate authority looks up a special DNS record published under the DNS name. If you integrate SSLMate with your DNS provider, we'll take care of publishing the special DNS records. SSLMate integrates with Route 53, Google Cloud DNS, Azure, DNSimple, DNS Made Easy, Gandi, Cloudflare, DigitalOcean, Linode, Name.com, and NS1.
DNS approval is best when you own the domains which need certificates.
Certificates need to be re-approved when they renew. As long as you keep your HTTP proxying or DNS integration intact, SSLMate will take care of everything automatically. (Your HTTP proxy rules stay they same when certificates renew, so no need to worry about updating your configuration.)
Ordering Certificates
There are two ways for you to order certificates:
-
The
sslmate
command line program. This is ideal when you are starting out, or when you don't need fully automated ordering of certificates. - The SSLMate REST API. This is ideal when you want to incorporate certificate ordering with your own systems. For example, if you're a SaaS company, you can automatically order a new certificate through the SSLMate API whenever you onboard a new customer with a vanity domain.
You do not need to track expiration dates and place new orders before certificates renew. SSLMate will obtain renewed certificates for you automatically and sslmate-agent will install them on your servers.
Ordering certificates with the sslmate
command line program
To order a certificate for certain DNS names, belonging to a certain cluster, run:
sslmate add --cluster CLUSTER_NAME DNS_NAME...
Example:
sslmate add --cluster webservers example.com www.example.com
Upon running the above command, SSLMate will request a certificate
that is valid for example.com
and www.example.com
. As long as
example.com
and www.example.com
are configured for HTTP or DNS approval
as described in the previous section, SSLMate will obtain a certificate.
Within a few minutes, sslmate-agent will install the new certificate
on every server that is part of your webservers
cluster.
Ordering certificates with the SSLMate REST API
Alternatively, you can create a new order resource using the SSLMate REST API.
For example, the following curl command is equivalent to the above sslmate add
command:
curl -X POST -u 123_AKRCEYZdHUrjegJ19oyI: -H 'Content-Type: application/json' -d '{"cluster": "webservers", "dns_names": ["example.com", "www.example.com"]}' https://sslmate.com/api/v3/orders
For details, see the APIv3 documentation.
Using Your Certificates
For every order, sslmate-agent creates a directory on your server
named /var/lib/sslmate-agent/orders/ORDER_NAME
, where ORDER_NAME
is the name of the order (which defaults to the first DNS name at
the time you added the order). (Wildcard characters are replaced with underscores.)
Inside this directory sslmate-agent places the private key and certificate files for this
order in a variety of formats. Most server software uses the following two files:
rsa.key.pem
- The private key for the order, in PEM-encoded PKCS#8 format.
rsa.chained.pem
- The leaf and intermediate certificate chain for the order, in PEM format.
Configure your server software to use these certificate files. Consult the documentation for your server software to determine the correct options to use.
sslmate-agent also creates files in several other formats, such as PKCS#12, which some applications use. You can also customize sslmate-agent to save certificate files in a different location. See the documentation for sslmate-agent and sslmate-agent.conf for details.
Modifying Orders
If you need to add a DNS name to an existing order, you can use the sslmate command like this:
sslmate edit --add-dnsname DNS_NAME ORDER_NAME
ORDER_NAME is the name of the order, which defaults to the first DNS name at the time you added the order.
To remove a DNS name from an order:
sslmate edit --rm-dnsname DNS_NAME ORDER_NAME
You can also use the REST API.
Within a few minutes of modifying an order, SSLMate will request a certificate for the new set of DNS names, and sslmate-agent will install the new certificate on every server that is part of the order's cluster. Until the new certificate is issued, your servers will continue using the existing certificate (with the old set of DNS names), allowing zero-downtime cutover to the new certificate.
Any new DNS name must be approved as described above, just as with a new order.
See Also
- Certificate Approval Process
- sslmate Command Line Tool Reference
- sslmate-agent Reference
- sslmate-agent.conf Reference
- APIv3 Reference
Please get in touch if you have any questions. We are happy to help!