diff --git a/README.md b/README.md index f97fbb2..8bab586 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,12 @@ The variable `certbot_install_from_source` controls whether to install Certbot f certbot_auto_renew_hour: "3" certbot_auto_renew_minute: "30" certbot_auto_renew_options: "--quiet --no-self-upgrade" + certbot_auto_renew_use_systemd: false By default, this role configures a cron job to run under the provided user account at the given hour and minute, every day. The defaults run `certbot renew` (or `certbot-auto renew`) via cron every day at 03:30:00 by the user you use in your Ansible playbook. It's preferred that you set a custom user/hour/minute so the renewal is during a low-traffic period and done by a non-root user account. +Many operating-system specific packages ship with a systemd timer for automating renewals. Setting `certbot_auto_renew_use_systemd` to `true`, in combination with `cerbot_auto_renew: true`, enables the included systemd timer in leu of the cron job and its related settings. + ### Automatic Certificate Generation Currently there is one built-in method for generating new certificates using this role: `standalone`. Other methods (e.g. using nginx or apache and a webroot) may be added in the future. @@ -35,19 +38,30 @@ Set `certbot_create_if_missing` to `yes` or `True` to let this role generate cer certbot_admin_email: email@example.com + The email address used to agree to Let's Encrypt's TOS and subscribe to cert-related notifications. This should be customized and set to an email address that you or your organization regularly monitors. + certbot_create_options: "" + +Additional options to pass to `certbot` during the creation event. This is useful if you wish to use an alternative CA with an ACME-compliant directory. + certbot_certs: [] - # - email: janedoe@example.com - # domains: - # - example1.com - # - example2.com - # - domains: - # - example3.com + # - email: janedoe@example.com + # domains: + # - example1.com + # - example2.com + # renewal_config: + # authenticator: webroot + # webroot-path: /usr/share/nginx/html + # create_options: --server https://ca.internal/acme/acme/director + # - domains: + # - example3.com -A list of domains (and other data) for which certs should be generated. You can add an `email` key to any list item to override the `certbot_admin_email`. +A list of domains (and other data) for which certs should be generated. You can add an `email` key to any list item to override the `certbot_admin_email`. You can add a `create_options` key to override the `certbot_create_options` global setting. - certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}" +Specifying a `renewal_config` key will cause the generated auto-renewal configuration to be updated after the certificate has been generated. Useful for switching renewals over to another authentication method than `standalone`. The key's value should be a dictionary consisting of `key: value` pairs which are valid in the `renewalparams` section of the renewal configuration file. + + certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.create_options | default('certbot_create_options') }} {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}" The `certbot_create_command` defines the command used to generate the cert. diff --git a/defaults/main.yml b/defaults/main.yml index 7002b26..4783a9e 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -6,19 +6,28 @@ certbot_auto_renew_hour: "3" certbot_auto_renew_minute: "30" certbot_auto_renew_options: "--quiet --no-self-upgrade" +# Enable the systemd timer that ships with many OS packages, instead of creating a crontab +# If certbot_auto_renew is not set, this option has no effect +certbot_auto_renew_use_systemd: false + # Parameters used when creating new Certbot certs. certbot_create_if_missing: false certbot_create_method: standalone +certbot_create_options: "" certbot_admin_email: email@example.com certbot_certs: [] # - email: janedoe@example.com # domains: # - example1.com # - example2.com +# renewal_config: +# authenticator: webroot +# webroot-path: /usr/share/nginx/html +# create_options: --server https://ca.internal/acme/acme/director # - domains: # - example3.com certbot_create_command: >- - {{ certbot_script }} certonly --standalone --noninteractive --agree-tos + {{ certbot_script }} certonly --standalone --noninteractive --agree-tos {{ cert_item.create_options | default(certbot_create_options) }} --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }} diff --git a/tasks/create-cert-standalone.yml b/tasks/create-cert-standalone.yml index 6f25b8a..bb23d62 100644 --- a/tasks/create-cert-standalone.yml +++ b/tasks/create-cert-standalone.yml @@ -21,3 +21,13 @@ state: started when: not letsencrypt_cert.stat.exists with_items: "{{ certbot_create_standalone_stop_services }}" + +- name: Apply renewal configuration updates + ini_file: + path: "/etc/letsencrypt/renewal/{{ cert_item.domains | first | replace('*.', '') }}.conf" + section: renewalparams + option: "{{ item.key }}" + value: "{{ item.value }}" + create: no + loop: "{{ cert_item.renewal_config | dict2items }}" + when: cert_item.renewal_config is defined \ No newline at end of file diff --git a/tasks/renew-cron.yml b/tasks/renew-cron.yml index 394a30e..0405cb3 100644 --- a/tasks/renew-cron.yml +++ b/tasks/renew-cron.yml @@ -6,3 +6,13 @@ minute: "{{ certbot_auto_renew_minute }}" hour: "{{ certbot_auto_renew_hour }}" user: "{{ certbot_auto_renew_user }}" + when: not certbot_auto_renew_use_systemd + +- name: Enable certbot renewal timer + systemd: + name: certbot-renew.timer + state: started + enabled: yes + when: certbot_auto_renew_use_systemd + +