Ansible Role: Certbot (for Let's Encrypt)

This role installs and sets up Certbot, which is a tool for managing Let's Encrypt certificates.

Requirements

If you want to install Certbot from its source code, you'll need to have Git installed. You can use the geerlingguy.git role to install Git.

Installing from source (see the section Source Installation from Git) can give you a better experience with Certbot and Let's Encrypt, especially on older operating systems.

Role Variables

The variable certbot_install_from_source determines whether to install Certbot from Git or through package management, with the default option being package management (no).

certbot_auto_renew: true
certbot_auto_renew_user: "{{ ansible_user | default(lookup('env', 'USER')) }}"
certbot_auto_renew_hour: 3
certbot_auto_renew_minute: 30
certbot_auto_renew_options: "--quiet --no-self-upgrade"

By default, this role sets up a cron job to renew certificates daily at 03:30 AM using the user specified in your Ansible playbook. It's better to set a custom user and time to ensure it runs during low-traffic periods and is executed by a non-root user.

Automatic Certificate Generation

Currently, this role has one method for generating certificates: standalone. More methods (like using nginx or apache) might be added later.

For an example: check the test playbook in molecule/default/playbook-standalone-nginx-aws.yml.

certbot_create_if_missing: false
certbot_create_method: standalone

Set certbot_create_if_missing to yes or True to enable certificate generation. Specify the method with certbot_create_method, where the current option is standalone.

certbot_admin_email: email@example.com

This is the email used to accept Let's Encrypt's terms of service and receive notifications about the certificates. Customize this with an email you or your organization regularly checks.

certbot_certs: []
  # - email: [email protected]
  #   domains:
  #     - example1.com
  #     - example2.com
  # - domains:
  #     - example3.com

This list contains the domains for which certificates should be created. You can add an email key for each domain list item to use a different email address.

certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}"

The certbot_create_command defines how the certificates are generated.

Standalone Certificate Generation

certbot_create_standalone_stop_services:
  - nginx

List of services that should be stopped while certbot runs its own server to generate certificates. If you use Apache, include apache2 (for Ubuntu) or httpd (for RHEL). If Nginx is on port 443 and something else is on port 80 (like Varnish or a Java app), add that to the list too. These services will only be stopped the first time a new certificate is generated.

Source Installation from Git

You can choose to install Certbot from its Git source code, which is helpful for older distributions that don't have Certbot packages available (like CentOS < 7, Ubuntu < 16.10, and Debian < 8).

certbot_install_from_source: false
certbot_repo: https://github.com/certbot/certbot.git
certbot_version: master
certbot_keep_updated: true

To install from source, set certbot_install_from_source to yes, which will clone the designated certbot_repo according to the certbot_version setting. If certbot_keep_updated is set to yes, the repository will be updated each time this role runs.

certbot_dir: /opt/certbot

This is the directory where Certbot will be cloned.

Wildcard Certificates

Let's Encrypt supports generating wildcard certificates, but the process is a bit more complicated. For usage examples, see comments in this pull request. Michael Porter also has a guide on Creating A Let’s Encrypt Wildcard Cert With Ansible that involves Cloudflare.

Dependencies

None.

Example Playbook

- hosts: servers

  vars:
    certbot_auto_renew_user: your_username_here
    certbot_auto_renew_minute: 20
    certbot_auto_renew_hour: 5

  roles:
    - geerlingguy.certbot

See more examples in the tests/ directory.

Manually creating certificates with certbot

Note: This role can automatically generate certificates. Refer to the "Automatic Certificate Generation" section above for details.

You can create certificates manually using the certbot script (or certbot-auto). On Ubuntu 16.04, use letsencrypt, or use /opt/certbot/certbot-auto if installed from source/Git. Here are example commands for working with Certbot:

# Automatically add certs for all Apache virtualhosts (use with caution!).
certbot --apache

# Generate certs but don't change Apache configuration (safer).
certbot --apache certonly

If you want to fully automate adding new certificates but don't want to use this role's features, you can do so using the command line to register, accept the terms of service, and generate a certificate with a standalone server:

1. Stop any services that use ports 80 and 443 (Apache, Nginx, etc.).
2. Register with certbot register --agree-tos --email [[email protected]] - Note: You won’t need to do this again for more certificates on the same server.
3. Generate a certificate for a domain pointing to this server: certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. Restart any services that were using ports 80 and 443.
5. Update your web server's configuration to use the new certificate (fullchain.pem) and private key (privkey.pem) generated by Certbot.
6. Reload or restart your web server to use the new HTTPS configuration.

Certbot certificate auto-renewal

By default, this role sets up a cron job that renews all installed certificates once a day at your specified time.

You can test the auto-renewal (without renewing the certificate) with the command:

/opt/certbot/certbot-auto renew --dry-run

Find full documentation and options on the Certbot website.

License

MIT / BSD

Author Information

This role was created in 2016 by Jeff Geerling, who is the author of Ansible for DevOps.