Installs TLS (SSL) certificates to the target, in one of two ways depending on configuration:
- Installs your provided TLS certificate, private key, and CA certificate bundle to target system.
- Deploys a new self-signed certificate + key to target system.
In either case, automatically creates a "full chain" file (containing certificate + CA bundle, suitable for use with Nginx) as well.
Supports Ubuntu 12+ and CentOS 5+, adding support for other distros would be easy.
Caveats / notices:
On CentOS, file permissions for the private key are set to owner root and mode 600, because the enclosing /etc/pki/tls/private
is permissively visible. (Compare to Ubuntu where the system-wide /etc/ssl/private
directory already has restricted permissions.) Beyond that, this role does not do anything with file permissions, like configuring additional users/groups which can read the private key. That is left for the deployer to handle in a playbook. This role also does not configure other services that use the installed certificates.
If using this role to deploy a provided certificate then openssl
must be available on the deployment host.
If using this role to create and deploy a self-signed certificate then openssl
must be available on the target host.
(These are likely already true for any modern Linux system.)
Variable | Required | Default | Choices | Comments |
---|---|---|---|---|
TLS_PRIVKEY_SRC_FILE | no | Path to private key on deployer system | ||
TLS_CERT_SRC_FILE | no | Path to certificate on deployer system | ||
TLS_CACHAIN_SRC_FILE | no | Path to CA chain on deployer system | ||
TLS_DEST_BASENAME | no | provided cert CN* | Base filename of installed certificate | |
TLS_CREATE_SELFSIGNED | no | false | true, false | Explicitly creates self-signed certificate |
TLS_CERT_DEST_DIR | no | (distro-specific) | Directory for certificates on target host | |
TLS_PRIVKEY_DEST_DIR | no | (distro-specific) | Directory for private keys on target host | |
TLS_SUBJECT_ALTERNATE_NAME | depends | The fully qualified domain name, only required | ||
if creating a self-signed cert |
If you specify at least a TLS_PRIVKEY_SRC_FILE, TLS_CERT_SRC_FILE, and TLS_CACHAIN_SRC_FILE, then the provided files will be installed to the target. (Ansible will look in "files" directory relative to playbook if you specify a bare filename or relative path.) If these variables are not set by the deployer, then the role will create a self-signed certificate instead, with files selfsigned.crt and selfsigned.key. You can explicitly set TLS_CREATE_SELFSIGNED: true
to override the default behavior and force creation of a self-signed certificate.
In order to create a valid self-signed certificate, you must provide TLS_SUBJECT_ALTERNATE_NAME
. The Subject Alternate Name (SAN) is the field in the generated certificate which indicates the server's hostname. A valid example would be 'local.atmo.cloud'. The Chrome browser recently made this field mandatory. If you would like to learn about the history read this SO answer.
*
If the deployer provides a certificate, then the certificate's indicated CN (domain) will be used as the base name of the files on the target (e.g. example.com.key
, example.com.crt
, example.com.cachain.crt
, and example.com.fullchain.crt
for example.com). If this role creates a self-signed certificate, the files will be named with "selfsigned" as the base name. In either case, setting TLS_DEST_BASENAME
overrides this filename.
**
By default, certificates and private keys are placed in the distro-specific system-wide default directories (but this can be overridden).
None
If you already have a certificate to install:
- hosts: all
roles:
- tls-cert
vars:
- TLS_PRIVKEY_SRC_FILE: example.com.key
- TLS_CERT_SRC_FILE: example.com.crt
- TLS_CACHAIN_SRC_FILE: example.com.cachain.crt
If you want to create a self-signed certificate, just call the role with no variables:
- hosts: all
roles:
- tls-cert
See license.md
Chris Martin