Skip to content

SSLMate Agent Config Reference

Name

sslmate-agent.conf — Configuration file for sslmate-agent(8)

MINIMAL EXAMPLE

A minimal /etc/sslmate-agent/sslmate-agent.conf file looks like this:

# Replace with your own API key found at https://sslmate.com/account/api_credentials
api_key = "123_AKRCEYZdHUrjegJ19oyI"

# Replace with your own cluster details generated by running `sslmate clusters add webservers`
cluster "webservers" {
        secret = "examplesecret:faC4ffCDuEaCv4SFn7mCHTLCqGGaEDrhBB7DI0PRCM8"
}

default {
        # Replace with a list of commands to restart the services which use your certificates
        on_update = [
                "service nginx restart",
                "service postfix restart",
        ]
}

SYNTAX

sslmate-agent.conf is a human-readable text file consisting primarily of lines of the following syntax:

name = value

name is a lowercase keyword which identifies the configuration option. Depending on the option, value may be a double-quoted string, a boolean (true or false), a number, or a comma-separated array of other values enclosed by square brackets. Whitespace is generally ignored except within quoted strings. Comments begin with a # character and continue until the end of the line.

Example:

# This is an example config file.
string_option = "Hello, world"
bool_option   = true
int_option    = 123    # This is a comment.
array_option  = ["Red", "Green", "Blue"]

Configuration options may be grouped together in a section:

default {
        on_update = ["service nginx restart"]
}

Sections may be named:

cluster "webservers" {
        secret = "examplesecret:faC4ffCDuEaCv4SFn7mCHTLCqGGaEDrhBB7DI0PRCM8"
}

Sections may also be nested:

default {
        files {
                combined = "/etc/haproxy/certs/${ORDER_NAME}.pem"
        }
}

CONTENTS

sslmate-agent.conf contains:

  • Global options that appear outside of any section.
  • One or more named cluster sections, which describe the cluster(s) to which this agent belongs.
  • Any number of named order sections, which configure installation options for a particular order.
  • An optional default section, which configures installation options for orders that do not have their own order section. It supports the same options as the order section.

These options are described in greater depth below.

GLOBAL CONFIGURATION

The following global options are placed outside of any section:

api_key = "KEY"
Your SSLMate API key, which can be found on your SSLMate account page (https://sslmate.com/account/api_credentials). This option is mandatory.
api_endpoint = "URI"
The URI to the SSLMate API endpoint. This option is only necessary if you are using the SSLMate sandbox.
refresh_interval = "INTERVAL"
How often sslmate-agent checks for updates in your account. INTERVAL is specified as a positive integer with a suffix of s (seconds), m (minutes), or h (hours). The default interval is 1 minute (1m).
on_update_env_vars = true|false
When executing on_update hooks, should sslmate-agent pass environment variables that list the updated orders? (See the description of the on_update option below for details.) Note that if you have thousands of certificates, these environment variables might become too long and your on_update hooks will fail with the error "argument list or environment is too big". Currently, the default value of this option is true, but in the future the default will be changed to false.

CLUSTER CONFIGURATION

The following configuration section configures sslmate-agent’s membership in the cluster named CLUSTER_NAME:

cluster "CLUSTER_NAME" {
        secret = "SECRET"
}

SECRET is the cluster’s secret key. This value is generated when you create a cluster, and must be kept secret. It is not stored on the SSLMate servers, so if you lose it you have to create a new cluster.

To create a cluster, run sslmate clusters add CLUSTER_NAME, replacing CLUSTER_NAME with a name of your choosing. sslmate will output a complete cluster configuration section which you can place in sslmate-agent.conf. See the sslmate(1) man page for details.

At least one cluster must be specified.

ORDER CONFIGURATION

The order and default sections configure how the certificates for an order are installed. If an order has its own order section with the same name, sslmate-agent uses the options in that section. Otherwise, it uses the options in the default section.

The following options are understood:

key_perm = PERMISSIONS
The UNIX permissions to apply to files containing the order’s private key. Must be specified as an octal permissions value, with leading 0 (e.g. 0644). Defaults to 0600. (Files that don’t contain private keys are always created with 0644 permissions.)
key_user = "USERNAME"
The UNIX user to own files containing the order’s private key. Defaults to the user running sslmate-agent.
key_group = "GROUPNAME"
The UNIX group to own files containing the order’s private key. Defaults to the group running sslmate-agent.
key_facls = ["ACL1", "ACL2", …]
Filesystem ACLs to apply to files containing the order’s private key, in setfacl(1) syntax. Only available on Linux; requires the setfacl(1) command.
on_update = ["COMMAND1", "COMMAND2", …]

Shell commands to execute when any file for an order is updated by sslmate-agent. Intended for restarting services that use certificates. Identical commands are coalesced, so if multiple orders are all updated at the same time and they all specify the same on_update command, the command is executed only once.

If the global on_update_env_vars option is true, the following environment variables are set when executing the commands:

UPDATED_ORDERS
Space-separated list of orders which were updated.
UPDATED_FILES
Space-separated list of file paths which were updated.

Wildcard characters (*) in order names are replaced with underscores (_).

Commands are executed by /bin/sh so they support standard shell substitutions.

temp = true|false
Whether to enable temporary certificates. When enabled, a temporary, self-signed certificate is installed if the real certificate hasn’t been issued yet. When disabled, no files are installed if the certificate hasn’t been issued yet. Temporary certificates can simplify the configuration of services which refuse to start when a virtual host is missing certificate files. Although temporary certificates aren’t trusted by clients, they allow services to start and serve the virtual hosts which do have trusted certificates. When the real certificate is issued and installed by sslmate-agent, you can restart your service to begin using the real certificate. Temporary certificates are disabled by default.

FILES CONFIGURATION

order and default sections can contain one files sub-section to configure where sslmate-agent installs the files for the order. See ORDER FILES in the sslmate-agent(8) man page for a description of these files.

sslmate-agent substitutes environment variables in the values of these options. The following environment variables are defined:

${ORDER_NAME}
The name of the order being installed. Wildcard characters (*) are replaced with underscores (_).
${KEY_TYPE}
The type of key being installed ("rsa" or "ecdsa").
${DNS_NAME}
The DNS name of the order being installed. Wildcard characters (*) are replaced with underscores (_). If the order has more than one DNS name, a file will be installed for each DNS name.
${SSLMATE_AGENT_STATE_DIR}
The directory containing sslmate-agent state (/var/lib/sslmate-agent by default).
$$
A literal dollar sign.

sslmate-agent automatically creates parent directories (with 0755 permissions) as necessary.

The following options are understood:

chain = "FILEPATH"
Location of the certificate chain file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.chain.pem
chain_and_root = "FILEPATH"
Location of the certificate chain with root file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.chain_and_root.pem
chained = "FILEPATH"
Location of the certificate with chain file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.chained.pem
combined = "FILEPATH"
Location of the combined chain and key file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.combined.pem
jks = "FILEPATH"
Location of the Java Key Store file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.jks
key = "FILEPATH"
Location of the private key file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.key.pem
leaf = "FILEPATH"
Location of the leaf certificate file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.leaf.pem
p12 = "FILEPATH"
Location of the PKCS#12 file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.p12
root = "FILEPATH"
Location of the root certificate file. Default: ${SSLMATE_AGENT_STATE_DIR}/orders/${ORDER_NAME}/${KEY_TYPE}.root.pem

To install a file type to more than one location, specify an array of file paths. To disable the installation of a file type, specify an empty array.

EXAMPLE

# API key found at https://sslmate.com/account/api_credentials
api_key = "123_AKRCEYZdHUrjegJ19oyI"

# Cluster configuration generated by running `sslmate clusters add webservers`
cluster "webservers" {
        secret = "examplesecret:faC4ffCDuEaCv4SFn7mCHTLCqGGaEDrhBB7DI0PRCM8"
}

order "mail.example.com" {
        # Restart Postfix and Dovecot when mail.example.com is updated:
        on_update = [
                "service postfix restart",
                "service dovecot restart",
        ]

        # Enable temporary certificates for mail.example.com, so Postfix and Dovecot
        # can start even if real certificates haven't been issued yet:
        temp = true
}

order "chat.example.com" {
        # Restart Prosody when chat.example.com is updated:
        on_update = [
                "service prosody restart",
        ]

        # Allow prosody user to read private key files for chat.example.com:
        key_facls = [
                "u:prosody:r",
        ]
}

default {
        # Install combined certificate files to an haproxy certificates directory:
        files {
                combined = "/etc/haproxy/certs/${ORDER_NAME}.pem"
        }

        # Reload haproxy when certificate files are updated:
        on_update = [
                "service haproxy reload",
        ]

}

SEE ALSO

sslmate-agent(8), sslmate(1)