Getting started¶
There are two “modes” how this role can be run:
- Scheduler mode: Role will request new certificate based on an existing
certificate request, replace the old certificate and restart the affected
service. Ansible should be run with dedicated minimally privileged user
account (by default
acmetiny
). - Setup mode: Role will run the initial setup for a new domain certificate
such as create required directories, generate RSA key and certificate
request. Further it will make sure that a dedicated user acount for the
scheduler mode is created and install the necessary sudo rules
for the service restart. Role has to be run with
root
privileges.
Prerequisites¶
Let’s Encrypt Account Key¶
Before the role can be run to send certificate requests an account key has to be generated. This can be done with the official Certbot client. Make sure the key is converted into the correct format for acme-tiny as described in Use existing Let’s Encrypt key.
Eventually store the account key in /etc/ssl/acme-tiny/account.key
.
Web Server Configuration¶
When requesting the certificate acme-tiny will place a challenge
file in /var/www/acme-challenges
which has to be accessible through
http://<fqdn>/.well-known/acme-challenge
for every domain requested in
the certificate. Make sure to point the DNS entry of the domain name
configured onto the system running this role and to add a corresponding
definition in your Web server configuration.
The following snippets are meant as an example. Depending on the Web server configuration they need to be slightly adjusted.
Apache 2
Alias /.well-known/acme-challenge/ /var/www/acme-challenges/
<LocationMatch "/.well-known/acme-challenge/*">
Header set Content-Type "text/plain"
</LocationMatch>
Nginx
location /.well-known/acme-challenge {
alias /var/www/acme-challenges;
location ~ /.well-known/acme-challenge/(.*) {
default_type text/plain;
}
}
Lighttpd
alias.url += (
"/.well-known/acme-challenge/" => "/var/www/acme-challenges/",
)
Example playbook¶
A minimal playbook which would run the ganto.acme_tiny
role to request a
SSL certificate would looke like this:
---
- name: "Request and setup Let's encrypt SSL certificate"
hosts: acme_tiny
roles:
- ganto.acme_tiny
Example inventory¶
When using the example playbook the host to run the role has to be added
to the [acme_tiny]
host group in the Ansible inventory:
[acme_tiny]
hostname
Obviously, the Default role variables might not be suitable for everybody. Especially
the acme_tiny__domain
variable needs to be defined individually.
This can be done via Ansible host variables in
/etc/ansible/host_vars/<hostname>/acme_tiny.yml
.
If there are multiple certificates that should be managed with this Ansible
role, the individual configurations could be defined in separate “domain”
files (e.g. /etc/ansible/vars/<domain>.yml
) and then passed with the
Ansible --extra-vars
argument to the playbook execution.
Such a variable file would look like this:
---
#
# acme_tiny role configuration for: mydomain.com
#
acme_tiny__domain: [ 'mydomain.com', 'www.mydomain.com' ]
acme_tiny__service: 'nginx'