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
- Upstream documentation: Apache Module mod_ssl
Dovecot¶
ssl_cert = </etc/dovecot/ssl/example.com.crt
ssl_key = </etc/dovecot/ssl/example.com.key
- Upstream documentation: Dovecot Wiki: SSL
Lighttpd¶
ssl.pemfile /etc/lighttpd/ssl/example.com.pem
ssl.cafile /etc/lighttpd/ssl/ca.crt
- Upstream documentation: Lighttpd Wiki: Secure HTTP
Nginx¶
ssl_certificate /etc/nginx/ssl/example.com.crt
ssl_certificate_key /etc/nginx/ssl/example.com.key
- Upstream documentation: Module ngx_http_ssl_module
Postfix¶
smtpd_tls_cert_file = /etc/nginx/ssl/example.com.crt
smtpd_tls_key_file = /etc/nginx/ssl/example.com.key
- Upstream documentation: Postfix TLS Support
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