SSLMate Agent Reference

Name

sslmate-agent — Daemon for managing SSL/TLS certificates on a server

Synopsis

sslmate-agent [OPTIONS…]

DESCRIPTION

sslmate-agent is a daemon that keeps the SSL/TLS certificates up-to-date across a cluster of one or more servers. sslmate-agent consults your SSLMate account to get a list of orders, obtains certificates for each one (by generating private keys and CSRs as necessary), and installs them on your server for other services (such as nginx or haproxy) to consume. sslmate-agent securely synchronizes private keys and certificates with other agents in the same cluster.

You can modify your list of orders using the sslmate(1) command line tool, the SSLMate REST API, or the SSLMate website. sslmate-agent monitors your SSLMate account for changes, and automatically installs new keys and certificates within minutes of you adding or modifying an order. sslmate-agent installs renewed certificates automatically before old ones expire, and can execute a command after updating a certificate to restart any services using the certificate.

CONFIGURATION

At a minimum, you must place your SSLMate API key (which can be obtained from https://sslmate.com/account/api_credentials), and information about a cluster (which can be obtained from the sslmate(1) command) in /etc/sslmate-agent/sslmate-agent.conf.

See the sslmate-agent.conf(5) man page for details.

COMMAND LINE OPTIONS

--pidfile FILENAME

Write the PID of sslmate-agent to FILENAME after starting. sslmate-agent will refuse to start if FILENAME already exists.

This option can be used by init scripts to help with daemonization.

--syslog

Send log messages to the system log instead of standard error.

-h, --help

Show a help message.

FILES

/etc/sslmate-agent/sslmate-agent.conf: Configuration file, documented in the sslmate-agent.conf(5) man page.
/var/lib/sslmate-agent/orders/ORDER_NAME/: Directory containing keys and certificates for the given order as described under ORDER FILES below. If the order name contains a wildcard character (*), it is replaced with an underscore (_) in the directory name.

ORDER FILES

By default, sslmate-agent installs the following files in /var/lib/sslmate-agent/orders/ORDER_NAME/ for each KEY_TYPE ("rsa" or "ecdsa") enabled for the order ("rsa" by default):

KEY_TYPE.key.pem: The private key of the given type ("rsa" or "ecdsa"), in PEM-encoded PKCS#8 format. This is the default private key format used by OpenSSL and is accepted by most Linux server software.
KEY_TYPE.chained.pem: A concatenation of the leaf and chain files for the given key, as PEM-encoded X.509 certificates. This is the default certificate format used by OpenSSL and is accepted by most Linux server software, although some software requires the leaf and chain to be configured separately.
KEY_TYPE.combined.pem: A concatenation of the private key of the given type and its corresponding certificate and chain files, in PEM encoding. This format is used by software which requires the key and certificate to be specified in the same file.
KEY_TYPE.p12: A PKCS#12 file (also known as a P12 or PFX file) containing the private key of the given type and its corresponding certificate and chain. The PKCS#12 file’s password is "sslmate". PKCS#12 files are primarily used on Windows.
KEY_TYPE.jks: A Java keystore file containing the private key of the given type and its corresponding certificate and chain. The keystore’s password is "sslmate" and its alias is "1". JKS files are generally used only by Java applications, such as Tomcat.

By default, sslmate-agent also installs the following files, which are typically only needed in advanced configurations:

KEY_TYPE.leaf.pem: The leaf certificate for the given key, in PEM-encoded X.509 format. Warning: This file does not work on its own since it does not contain the certificate chain. You must also configure the certificate chain using the .chain.pem file. This format is used by software which requires the leaf and chain certificates to be configured separately.
KEY_TYPE.chain.pem: The intermediate certificate chain for the given key, as a sequence of PEM-encoded X.509 certificates. The first certificate is the issuer of the leaf certificate, and the last certificate is signed by the root certificate. The leaf and root certificates are not included. This format is used by software which requires the leaf and chain certificates to be configured separately.
KEY_TYPE.root: The root certificate, in PEM encoding. Not needed in typical configurations.
KEY_TYPE.chain_and_root.pem: A concatenation of the chain and root files, as PEM-encoded X.509 certificates. This format is required for verifying OCSP responses and configuring OCSP stapling. You do not need it in a basic configuration.

You can customize the location of these files by modifying the files section in sslmate-agent.conf(5).

ENVIRONMENT VARIABLES

SSLMATE_AGENT_CONFIG_DIR: The directory containing sslmate-agent configuration. Default: /etc/sslmate-agent.
SSLMATE_AGENT_STATE_DIR: The directory containing sslmate-agent state. Default: /var/lib/sslmate-agent.

NON-ROOT OPERATION

sslmate-agent is intended to run as root so that it can restart the services which use your certificates. However, it is possible to run as a non-root user by specifying alternative $SSLMATE_AGENT_CONFIG_DIR and $SSLMATE_AGENT_STATE_DIR environment variables.