System configuration

File system layout

The role will setup a configurable directory layout to store the certificates and make them accessible by the services.

Example layout of the default configuration:

Server path Ansible role variable
/etc/ssl/acme-tiny acme_tiny__config_dir
/etc/ssl/acme-tiny/example.com acme_tiny__cert_dir
/etc/ssl/acme-tiny/example.com/example.com.key acme_tiny__private_key
/etc/ssl/acme-tiny/example.com/example.com.csr acme_tiny__cert_request
/etc/ssl/acme-tiny/example.com/example.com.crt acme_tiny__certificate

When acme_tiny__service is not empty and an additional layer of indirection through symlinks which will make the certificates accessible in a transparent way. For each service the role will create a ssl/ subdirectory from where the actual certificates and keys are symlinked. Like this the CA could be changed easily without reconfiguration of the secured services. This behavour can be disabled by setting acme_tiny__cert_symlink to False.

E.g. For for Apache httpd this would look like this:

/etc/apache2/ssl/example.com.crt -> /etc/ssl/acme-tiny/example.com/example.com_chain.crt
/etc/apache2/ssl/example.com.key -> /etc/ssl/acme-tiny/example.com/example.com.key

For lighttpd:

/etc/lighttpd/ssl/example.com.pem -> /etc/ssl/acme-tiny/example.com/example.com_keycert.pem
/etc/lighttpd/ssl/ca.crt          -> /etc/ssl/acme-tiny/intermediate.crt

Service configuration

To secure a service the key and certificate have to be referenced in the individual service configurations. When using the symlinks created by the role this only has to be done once. Any certificate changes and even the change of a certificate authority can be easily handled by pointing the symlinks to a new target.

Note

The configuration of the certificates in the service configuration files has to be done manually.

Apache httpd

SSLCertificateFile    /etc/apache2/ssl/example.com.crt
SSLCertificateKeyFile /etc/apache2/ssl/example.com.key

Dovecot

ssl_cert = </etc/dovecot/ssl/example.com.crt
ssl_key  = </etc/dovecot/ssl/example.com.key

Lighttpd

ssl.pemfile /etc/lighttpd/ssl/example.com.pem
ssl.cafile  /etc/lighttpd/ssl/ca.crt

Nginx

ssl_certificate     /etc/nginx/ssl/example.com.crt
ssl_certificate_key /etc/nginx/ssl/example.com.key

Postfix

smtpd_tls_cert_file = /etc/nginx/ssl/example.com.crt
smtpd_tls_key_file  = /etc/nginx/ssl/example.com.key

Custom services

The acme_tiny__service_map configuration dictionary can be overwritten from the Ansible inventory to extend the definition with a new service or adjust the current behaviour. Each element has the service name as key and needs to define the following properties:

cert_format
Certificate format. See acme_tiny__cert_format for valid options.
cert_directory
Custom directory from where the certificate and key will be symlinked. See File system layout for more details.
restart_command
Command which should be executed to restart this service (instance) as an unprivileged user. If this command contains sudo, a corresponding rule will be created for the acme_tiny__user_name account.

Example

Custom Ansible inventory definition for Pound:

acme_tiny__service_map:
  pound:
    cert_format: 'keycert'
    cert_directory: '/etc/pound/ssl'
    restart_command: '/usr/bin/sudo -n /bin/systemctl restart pound'

Certificate renewal

After adding a new domain the role has to be run once with root privileges. Among other things this will create a separate user account acmetiny which can be used to schedule unattended certificate renewals.

Note

See Example inventory for an example how to create a role configuration.

Here an example of a cron job (/etc/cron.d/acme-tiny) which whould renew the certificate every month:

PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin

@monthly acmetiny /usr/bin/ansible-playbook -e @/etc/ansible/vars/mydomain.com.yml /etc/ansible/playbooks/acme_tiny.yml >/dev/null