Ansible Role: Certbot (for Let's Encrypt)

This role installs and sets up Certbot for Let's Encrypt.

Requirements

If you are installing from source, you will need Git. You can use the geerlingguy.git role to install Git.

Installing from source (see the Source Installation from Git section) usually gives a better experience with Certbot and Let's Encrypt, especially if you are using an old operating system.

Role Variables

• certbot_install_method: package
  This controls how Certbot is installed. Options are 'package', 'snap', and 'source'.

• 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"

By default, this role sets up a cron job to run Certbot under the specified user account every day at the defined time. The default setting runs certbot renew at 03:30:00. It is suggested to customize the user, hour, and minute to ensure the renewal runs during off-peak hours and not by a root user.

Automatic Certificate Generation

Currently supported methods for generating new certificates are standalone and webroot using this role.

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

• certbot_create_if_missing: false
  Set this to yes or True to allow the role to generate certificates.

• certbot_create_method: standalone
  Use this variable to define the method for generating certificates. Allowed values are standalone or webroot.

• certbot_testmode: false
  Enable this to run a test request without creating actual certificates.

• certbot_hsts: false
  Enable HTTP Strict Transport Security for certificate generation.

• certbot_admin_email: [email protected]
  This email will agree to Let's Encrypt's terms and receive cert-related notifications. Use an email you or your organization checks regularly.

• certbot_certs: []
  A list of domains (and other data) for which certificates should be created. You can override the certbot_admin_email by adding an email key to any entry. If using the webroot method, specify which directory to use for authentication.

• certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}"
  This defines the command used to create the certificate.

Standalone Certificate Generation

• certbot_create_standalone_stop_services: [nginx]
  Services that should be stopped while Certbot runs its standalone server on ports 80 and 443. If using Apache, use apache2 or httpd. Add any service that listens on these ports to the list.

Snap Installation

Since December 2020, it is recommended to install Certbot from Snap instead of certbot-auto.
Set certbot_install_method: snap to install Certbot via Snap. This method is still experimental and may not work on all Linux distributions.

Webroot Certificate Generation

When using the webroot method, provide a webroot for every certbot_certs item to specify the authentication directory, ensuring the web server serves content correctly from it.

Source Installation from Git

If needed, you can install Certbot from its Git repository with certbot_install_method: source. This is helpful for older distributions without available Certbot packages (e.g., CentOS < 7, Ubuntu < 16.10, Debian < 8).

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

These settings allow you to clone Certbot from the specified repository and keep it updated if this option is enabled.

• certbot_dir: /opt/certbot
  The directory where Certbot will be cloned.

Wildcard Certificates

Let's Encrypt supports wildcard certificates, but the process is more complex. For examples and guidance, see comments in this pull request and a walkthrough by Michael Porter on Creating A Let’s Encrypt Wildcard Cert With Ansible, specifically with 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 other examples in the tests/ directory.

Manually Creating Certificates with Certbot

Note: You can automate certificate creation with this role; refer to the "Automatic Certificate Generation" section above.

To create certificates manually, you can use the certbot (or certbot-auto) script (use letsencrypt on Ubuntu 16.04 or /opt/certbot/certbot-auto if installing from Git). Here are some commands for configuring certificates with Certbot:

# Automatically add certificates for all Apache virtual hosts (use cautiously).
certbot --apache

# Generate certificates but keep Apache configuration untouched (safer).
certbot --apache certonly

For a fully automated process without using the built-in features of this role, follow these steps:

1. Stop any services on ports 80 and 443 (such as Apache or Nginx).
2. Register with: certbot register --agree-tos --email [[email protected]]
   • Note: You won't need to do this for future certs 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 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 with the new HTTPS settings.

Certbot Certificate Auto-Renewal

By default, this role adds a cron job to renew all installed certificates once per day at your specified time.

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

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

Visit the Certbot website for more documentation and options.

License

MIT / BSD

Author Information

This role was created by Jeff Geerling, author of Ansible for DevOps.