This documentation applies to the SSLMate for SaaS service. If you are using SSLMate Basic, please see the CLI Help instead.

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.

Choose your operating system:

Debian 9 (Stretch)

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/stretch/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/stretch/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Debian 8 (Jessie)

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/jessie/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/jessie/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Debian 7 (Wheezy)

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/wheezy/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/wheezy/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Ubuntu 18.10

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1810/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1810/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Ubuntu 18.04

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1804/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1804/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Ubuntu 17.10

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1710/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1710/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Ubuntu 17.04

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1704/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1704/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Ubuntu 16.10

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1610/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1610/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Ubuntu 16.04

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1604/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1604/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

Ubuntu 14.04

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1404/sslmate2.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1404/sslmate.gpg

apt-get update

apt-get install sslmate sslmate-agent

RHEL/CentOS/SL 7

Prerequisite: the wget and ca-certificates packages must be installed.

wget -P /etc/yum.repos.d https://sslmate.com/yum/centos/SSLMate2.repo

wget -P /etc/pki/rpm-gpg https://sslmate.com/yum/centos/RPM-GPG-KEY-SSLMate

yum install sslmate sslmate-agent

Or: Direct .rpm download

After installing sslmate-agent, you need to enable and start it with systemctl enable sslmate-agent and systemctl start sslmate-agent.

RHEL/CentOS/SL 6

Prerequisite: the wget and ca-certificates packages must be installed.

wget -P /etc/yum.repos.d https://sslmate.com/yum/centos/SSLMate2.repo

wget -P /etc/pki/rpm-gpg https://sslmate.com/yum/centos/RPM-GPG-KEY-SSLMate

yum install sslmate sslmate-agent

Or: Direct .rpm download

After installing sslmate-agent, you need to enable and start it with chkconfig sslmate-agent on and service sslmate-agent start.

Amazon Linux

Prerequisite: the wget and ca-certificates packages must be installed.

wget -P /etc/yum.repos.d https://sslmate.com/yum/amzn1/SSLMate2.repo

wget -P /etc/pki/rpm-gpg https://sslmate.com/yum/amzn1/RPM-GPG-KEY-SSLMate

yum install sslmate sslmate-agent

Or: Direct .rpm download

After installing sslmate-agent, you need to enable and start it with chkconfig sslmate-agent on and service sslmate-agent start.

Fedora (27+)

Prerequisite: the wget and ca-certificates packages must be installed.

wget -P /etc/yum.repos.d https://sslmate.com/yum/fedora/SSLMate2.repo

wget -P /etc/pki/rpm-gpg https://sslmate.com/yum/fedora/RPM-GPG-KEY-SSLMate

yum install sslmate sslmate-agent

Or: Direct .rpm download

After installing sslmate-agent, you need to enable and start it with chkconfig sslmate-agent on and service sslmate-agent start.

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 hostname in the certificate, using one of the following two approval methods:

  • With HTTP approval, the certificate authority connects to each hostname 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.

    To use HTTP approval, specify http when creating the order, as described in the next section.

  • With DNS approval, the certificate authority looks up a special DNS record published under the hostname. If you integrate SSLMate with your DNS provider, we'll take care of publishing the special DNS records. SSLMate integrates with Route 53, DNSimple, NS1, Cloudflare, and DigitalOcean.

    DNS approval is best when you own the domains which need certificates.

    To use DNS approval, specify dns when creating the order, as described in the next section.

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 hostnames, belonging to a certain cluster, and using a particular approval method, run:

sslmate add --cluster CLUSTER_NAME --approval APPROVAL_METHOD HOSTNAME...

Example:

sslmate add --cluster webservers --approval http 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 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", "identifiers": [{"type": "dns", "value": "example.com", "approval": "http"}, {"type": "dns", "value": "www.example.com", "approval": "http"}]}' 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 hostname 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 hostname to an existing order, you can use the sslmate command like this:

sslmate edit --approval APPROVAL_METHOD --add-identifier HOSTNAME ORDER_NAME

ORDER_NAME is the name of the order, which defaults to the first hostname at the time you added the order.

To remove a hostname from an order:

sslmate edit --rm-identifier HOSTNAME 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 hostnames, 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 hostnames), allowing zero-downtime cutover to the new certificate.

Any new hostname must be approved as described above, just as with a new order.

Get Started with SSLMate Today

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

Click to sign up