certbot_certificate
certbot_certificate gets one TLS certificate with the certbot that is
installed on the node. certbot is a program that gets TLS certificates from
an ACME certificate authority, such as Let's Encrypt, and renews them. ACME
is the protocol in which a server asks such an authority for a certificate
and proves that the server controls the names in the certificate.
MMX gets each certificate once. Renewing is ongoing work between MMX runs,
and it stays with certbot's own systemd timer. A playbook installs certbot
with a package task and gets each certificate with certbot_certificate.
The playbook tells certbot what to run after a renewal and enables the timer.
Using certbot_certificate accepts the terms of service of the certificate
authority on your behalf, as certbot's --agree-tos option does.
A self-signed certificate needs no certificate authority and no certbot.
To create a self-signed certificate, write a separate shell task that runs
openssl, with skip_if_this_path_exists naming the certificate file.
Set up
certbot must be installed before the first certbot_certificate task, and
its timer must run. These node tasks install certbot on every supported
distribution and enable the right timer, chosen by the node's facts:
# certbot from the distribution's own packages. Rocky Linux and AlmaLinux
# have it in the EPEL repository, which the package epel-release adds.
- when: {equals: ["{{ .node.distribution.family }}", redhat]}
dnf_package: {packages: [{name: epel-release, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", apt]}
apt_package: {packages: [{name: certbot, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", dnf]}
dnf_package: {packages: [{name: certbot, version: newest_when_first_installed}]}
# certbot's own timer renews every certificate of the node.
- when: {equals: ["{{ .node.distribution.family }}", debian]}
systemd_service: {name: certbot.timer, state: running, start_at_boot: true}
- when: {not: {equals: ["{{ .node.distribution.family }}", debian]}}
systemd_service: {name: certbot-renew.timer, state: running, start_at_boot: true}
| Distribution | certbot comes from | The timer's unit |
|---|---|---|
| Debian 12 and 13, Ubuntu 24.04 and 26.04 | the distribution's own packages | certbot.timer |
| Rocky Linux 9, AlmaLinux 10 | the EPEL repository, which the package epel-release adds |
certbot-renew.timer |
The package of Debian and Ubuntu enables its timer when it is installed, and
the Red Hat family enables its timer by a system setting. MMX
installs a package without starting its services, so the timer starts with
the systemd_service task, or else at the next boot.
The example project certificate-with-certbot installs certbot on each of these distributions, gets one certificate, and enables the right timer.
Inputs
certificate_name(string; required): certbot's name for the certificate; its files are under/etc/letsencrypt/live/<certificate_name>/state(presentorabsent; defaultpresent): absent deletes the certificate, its key, and its renewal settings from the node with certbot delete, and accepts only certificate_name; it does not revoke the certificate at the certificate authoritydomains(list of strings; required): required with state: present; the names that the certificate covers, such as shop.example.com or*.example.com; the certificate covers exactly this list, and another list gets a new certificateaccount_email_when_registered(string; required): required with state: present; the contact address of the node's account at the certificate authority; certbot sends it when it registers that account, with the node's first certificate from that authority; MMX does not compare it afterwards, and certbot update_account changes it at the authoritychallenge(webroot,standalone, ordns; required): required with state: present, no default; how the certificate authority checks that the server controls the names: webroot through a file that the running web server serves, standalone through certbot's own server on port 80, where nothing else may listen, or dns through a DNS record, which a wildcard name needswebroot_path(string; optional): required with challenge: webroot; the web root; certbot writes challenge files below<webroot_path>/.well-known/acme-challenge/, which the web server must serve at /.well-known/acme-challenge/dns_plugin(string; optional): required with challenge: dns; the name of certbot's DNS plugin without dns-, such as cloudflare or rfc2136; install the plugin's package firstdns_credentials_file(string; optional): only with challenge: dns; the path, on the node, of the plugin's credentials file; write it with a file task from secrets, permissions_mode 0600; a plugin that reads its login from a file needs it, and route53, which gets its login another way, takes none; omit to keep the saved settingwait_after_creating_dns_record(string; optional): only with challenge: dns; how long certbot waits after it created the DNS record before the certificate authority looks for it: a duration of whole seconds, such as 30s; omit to keep the saved setting, or use the plugin's default for a new certificaterun_after_issue_and_renewal(string; optional): the path of a script on the node, which must exist and be executable; certbot runs it after the first certificate is issued and after every renewal, also between MMX runs; omit to keep the saved settingcertificate_authority_url(string; required): required with state: present; the HTTP or HTTPS ACME directory URL of the certificate authority, such as https://acme-v02.api.letsencrypt.org/directory; a certificate from another authority is replacedrenewal_settings_to_remove(list of strings; optional): List of saved settings to delete: run_after_issue_and_renewal, dns_credentials_file, or wait_after_creating_dns_record. Do not also give a setting that this list removes. An omitted setting stays unchanged.
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangereasonvalue.certificate_dirvalue.domains
What a dryrun reports
Requests nothing, starts no certbot, and writes nothing; reports would_change with the names when the certificate is missing, with both lists when the names differ, with both addresses when the certificate comes from another certificate authority, and with each setting that differs when only certbot's renewal settings would change, then also with the difference of certbot's renewal file; not_checked while certbot or the DNS plugin is missing, because an earlier node task may install it, and while the script or the credentials file is missing, unless an earlier node task of the same dryrun would install that file.
Retries and time limits
Runs once unless the task sets retry.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
A certificate for a web server
- apt_package:
packages:
- {name: certbot, version: newest_when_first_installed}
- file:
path: /usr/local/bin/reload-nginx-after-certificate-renewal
permissions_mode: "0755"
content: |
#!/bin/sh
systemctl reload nginx
- certbot_certificate:
certificate_name: shop.example.com
certificate_authority_url: https://acme-v02.api.letsencrypt.org/directory
domains: [shop.example.com, www.shop.example.com]
account_email_when_registered: admin@example.com
challenge: webroot
webroot_path: /var/www/certbot-challenges
run_after_issue_and_renewal: /usr/local/bin/reload-nginx-after-certificate-renewal
- systemd_service:
name: certbot.timer
state: running
start_at_boot: true
These tasks are for Debian and Ubuntu; Set up has the tasks for the other distributions. On the node, in order:
- MMX installs the certbot package and the script.
certbot_certificatestarts certbot, which asks Let's Encrypt for one certificate for the two names. The authority checks that the server controls the names: certbot puts a file under/var/www/certbot-challenges/.well-known/acme-challenge/, and the authority fetches it over plain HTTP from each name. The web server must maphttp://shop.example.com/.well-known/acme-challenge/<token>to/var/www/certbot-challenges/.well-known/acme-challenge/<token>. With document root/var/www/certbot-challenges, the web server serves/.well-known/acme-challenge/<token>from/var/www/certbot-challenges/.well-known/acme-challenge/<token>.- The certificate and its key are then under
/etc/letsencrypt/live/shop.example.com/:fullchain.pemis the certificate with the authority's chain, andprivkey.pemthe key. certbot runs the script once, now. - The last task enables the timer that renews every certificate of the node. certbot runs the script again after each renewal.
A second run starts no certbot: the node has the certificate for
shop.example.com and www.shop.example.com.
The three challenges, the ways in which the authority checks that the server controls the names:
webroot: the authority fetches a file from the running web server, as above. The web server stays up.standalone: certbot answers the authority itself on port 80, so nothing else may listen there while the task runs, and at each renewal.dns: certbot creates a DNS record through a plugin for your DNS service. A wildcard name such as*.example.comneeds the DNS challenge. A task with a wildcard name and another challenge is a validation error.
A certificate through DNS
- apt_package:
packages:
- {name: certbot, version: newest_when_first_installed}
- {name: python3-certbot-dns-cloudflare, version: newest_when_first_installed}
- file:
path: /etc/letsencrypt/cloudflare.ini
permissions_mode: "0600"
content: |
dns_cloudflare_api_token = {{ .secrets.cloudflare_api_token }}
- certbot_certificate:
certificate_name: example.com
certificate_authority_url: https://acme-v02.api.letsencrypt.org/directory
domains: [example.com, "*.example.com"]
account_email_when_registered: admin@example.com
challenge: dns
dns_plugin: cloudflare
dns_credentials_file: /etc/letsencrypt/cloudflare.ini
wait_after_creating_dns_record: 30s
The file task writes the plugin's credentials file from a secret, readable
only by root. certbot_certificate gets only the file's path, so its result
is not hidden, and the token is in no command line. certbot's plugin creates
the record _acme-challenge.example.com, waits 30 seconds, lets the
authority look, and removes the record.
Each plugin is a package of its own: python3-certbot-dns-<plugin>. Each
plugin's own documentation says what its credentials file holds. MMX keeps
no list of plugins: it passes dns_credentials_file and
wait_after_creating_dns_record to the plugin that the task names, and a
plugin that certbot cannot load fails the task with the plugin's name before
any request.
The first run: the certificate before the configuration that names it
A web server's TLS configuration names certificate files. On a new server, the certificate files do not exist yet, and the web server refuses a configuration that names a missing file. To install a TLS configuration in one playbook run, obtain the certificate before installing the TLS configuration:
- task_block:
id: plain_http_site
changes:
- file:
path: /etc/nginx/conf.d/shop-http.conf
permissions_mode: "0644"
source: files/shop-http.conf # serves /var/www/certbot-challenges
activate:
- systemd_service: {name: nginx, state: running, start_at_boot: true, refresh: reload}
- certbot_certificate:
certificate_name: shop.example.com
certificate_authority_url: https://acme-v02.api.letsencrypt.org/directory
domains: [shop.example.com, www.shop.example.com]
account_email_when_registered: admin@example.com
challenge: webroot
webroot_path: /var/www/certbot-challenges
run_after_issue_and_renewal: /usr/local/bin/reload-nginx-after-certificate-renewal
- task_block:
id: tls_site
changes:
- file:
path: /etc/nginx/conf.d/shop-tls.conf
permissions_mode: "0644"
source: files/shop-tls.conf # names /etc/letsencrypt/live/shop.example.com/
validate:
- shell: {script: nginx -t}
activate:
- systemd_service: {name: nginx, state: running, refresh: reload}
- The first node task block installs the plain HTTP site, which serves the challenge directory, and starts the web server.
certbot_certificategets the certificate through the plain HTTP site in/etc/nginx/conf.d/shop-http.conf.- The second node task block,
tls_site, installs the TLS site. Thetls_sitenode task block runsnginx -tto check the whole nginx configuration. Thenginx -tcheck passes because the certificate's files exist, and thetls_sitenode task block reloads the web server.
A webroot directory outside /var/www on a node with SELinux
- selinux_file_context:
path: /srv/certbot-challenges
also_apply_to_everything_inside: true
selinux_type: httpd_sys_content_t
- directory:
path: /srv/certbot-challenges
permissions_mode: "0755"
The selinux_file_context task gives the path the label for web content
before the directory task makes the directory, so the web server may read
the files that certbot puts there.
On a node with SELinux says why.
Remove a certificate
First remove the configuration that names the certificate files.
- certbot_certificate:
certificate_name: shop.example.com
state: absent
state: absent deletes the certificate, its key, and its renewal settings
from the node with certbot delete, and accepts only certificate_name.
certbot delete asks no certificate authority and does not revoke the
certificate at the authority. A certificate that the node does not have is
unchanged, also on a node without certbot.
How it works
What a rerun compares
MMX reads certbot's own files on the node and asks no authority:
- The names inside the existing certificate, with
domains. Another list gets a new certificate for exactly the listed names, under the existing certificate'scertificate_name. The order of the names does not count. - The authority in certbot's renewal settings of the certificate, with
certificate_authority_url. If the task names a different authority, MMX runs certbot to obtain a replacement certificate from the newly specified authority. Changing only the saved authority address cannot make an existing certificate renew through a different authority. certbot's renewal settings also name an account at the original authority, so changing only the address leaves renewals unable to succeed. - The settings of the next renewal:
challenge, its fields, andrun_after_issue_and_renewal. MMX writes a difference into certbot's renewal file,/etc/letsencrypt/renewal/<certificate_name>.conf, so the next renewal uses it. No certificate is requested, and no certbot starts.
A certificate whose names, authority, and renewal settings match the task is unchanged. MMX then does not start certbot at all, because certbot asks the authority also when no changes are needed. MMX never renews. Whether a certificate is close to its end is certbot's business, and a certificate that certbot renewed is still the task's certificate.
Omitting run_after_issue_and_renewal, dns_credentials_file, or
wait_after_creating_dns_record leaves that saved renewal setting alone,
also when another task setting changes. A replacement certificate retains
the saved script path, DNS credentials file path, and DNS propagation wait
when the corresponding task fields are omitted. Delete settings explicitly:
- certbot_certificate:
certificate_name: shop.example.com
certificate_authority_url: https://acme-v02.api.letsencrypt.org/directory
domains: [shop.example.com, www.shop.example.com]
account_email_when_registered: admin@example.com
challenge: webroot
webroot_path: /var/www/certbot-challenges
renewal_settings_to_remove: [run_after_issue_and_renewal]
The node removes the saved renewal script; omitting the removal list on the next run leaves the script absent. A setting cannot be both supplied and listed for removal. Removing a DNS setting removes that setting for saved DNS plugins, including a plugin used before a challenge change.
account_email_when_registered is not compared. One account serves every certificate that
the node has from an authority, and certbot keeps no copy of the account's
address. Another address in a later task changes nothing; on the node,
certbot update_account --email <address> changes it at the authority
(with --server and the authority's address for another authority than
Let's Encrypt).
Nobody tests changed settings until the next renewal. A wrong
webroot_path shows only when certbot's timer next renews, weeks later. To
test the settings now, run this on the node:
certbot renew --dry-run --cert-name shop.example.com
The dry run asks the test server of Let's Encrypt and keeps no certificate.
For a certificate of another authority, add --server with that authority's
address: without it, the dry run asks Let's Encrypt's test server all the
same.
How MMX reads and writes certbot's files
- Reading. The names come from the certificate file itself, and the settings from certbot's renewal file for the certificate, read by section and key. MMX never reads what certbot prints to learn a state.
- Before a request, MMX reads the renewal file and fails the task when it cannot read it as certbot's format; see Errors and what they mean.
- After a request, MMX reads the certificate in
/etc/letsencrypt/live/<certificate_name>/again and fails the task when it does not hold the task's names. certbot's exit code does not prove where the certificate is. - Writing changed settings. MMX changes the settings in the renewal
file, one setting at a time, and keeps every other line. No certbot
command does it on every supported version:
certbot reconfigureis missing in the certbot of Debian 12, and it always asks the authority. - Checks before certbot starts. The script in
run_after_issue_and_renewalmust exist and be executable when the task runs, and MMX checks that itself and says so. A DNS plugin whose package is missing fails the task as a missing prerequisite, with the plugin's name, before any request. MMX asks the Python interpreter that the certbot program names in its first line which plugins certbot can load; the commandcertbot pluginswould write certbot's log and make its directories, also in a dryrun. A credentials file that does not exist is a missing prerequisite too. - In a dryrun, a missing script or credentials file makes the task
not_checked, unless an earlier node task of the same dryrun would install that file: then the dryrun goes on and says what a run would do. So the first dryrun of a playbook that writes the script and then asks for the certificate shows that a certificate would be requested.
The result's .this_node_task.value.certificate_dir is
/etc/letsencrypt/live/<certificate_name>, and
.this_node_task.value.domains the names of the certificate. reason says
what the task did and why: the certificate was missing, covered other names,
or came from another authority, or which settings it wrote. With
state: absent the result has no value.
Another certbot
certbot works alone: a second certbot fails at once while the first holds
certbot's lock. A renewal can hold that lock for minutes: certbot sleeps for
up to eight minutes before it renews, unless its renewal service passes
--no-random-sleep-on-renew. So a task waits
until no other certbot runs, for at most ten minutes and never longer than
the task's own time_limit, and then makes its one try. Its reason says how
long it waited.
The lock is a POSIX record lock on the file .certbot.lock in each of
certbot's three directories. MMX asks the kernel whether a process holds
one, which takes no lock, and reads no message of certbot.
A run waits in the same way before it writes changed settings into certbot's renewal file: a renewal that runs has read the file and writes it again when it ends, so the change would be lost. After a wait the task compares again. A dryrun does not wait.
Retries
An authority limits how many certificates it issues for a name in a week.
So the task tries once, and a failed task is not repeated unless the node
task sets retry.
The script that certbot runs
run_after_issue_and_renewal is the step that each program which uses the
certificate needs after a new one: a reload, a copy, a combined file.
certbot runs the script independently during renewals, including when MMX
is not running. certbot runs the run_after_issue_and_renewal script as
root. certbot sets RENEWED_LINEAGE to the certificate's directory and
RENEWED_DOMAINS to the certificate's names, separated by spaces.
run_after_issue_and_renewal holds the path of one script, not a command.
certbot keeps a script as a shell command, so MMX writes the path for
certbot's shell; a path with a space works. Install the script with a
file task before the certificate task. Its exit code does not reach MMX:
certbot reports success also when the script fails, and says so only in
/var/log/letsencrypt/letsencrypt.log.
Do not let the script use /tmp or /var/tmp on Debian and Ubuntu.
Debian's and Ubuntu's packaged renewal service runs with systemd's
PrivateTmp=true. During a renewal by the timer, the renewal script sees
private, initially empty /tmp and /var/tmp directories, removed when
the service ends. The run_after_issue_and_renewal script sees the node's
normal /tmp and /var/tmp directories when MMX gets the first
certificate.
For certificates used on additional nodes, write a renewal script on the
issuing node. The script must copy the certificate to storage the receiving
nodes can read. Configure each receiving node with a systemd service that
copies the certificate files from storage and reloads the web server.
Give the service a timer, using systemd_unit and systemd_service.
On the Red Hat family, leave the hooks in
/etc/sysconfig/certbot empty. The packaged renewal service reads that
file. A DEPLOY_HOOK set there runs in place of each certificate's own
script at a renewal by the timer, and certbot then writes it into the
renewal settings of every certificate that it renewed (measured on Rocky
Linux 9 with certbot 3.1). The next MMX run finds another script than the
task's and writes the task's script back, and the timer's next renewal
replaces it again.
A certificate task inside a node task block
A tracked input is a resource, such as a file or package, that MMX remembers by hash. MMX uses changed hashes to decide whether the node task block must restart or reload a service.
A certbot_certificate task in a node task block's changes is not a
tracked input, so a new
certificate does not trigger the block's service restart or reload. The
script in run_after_issue_and_renewal is what reloads a program that uses
the certificate, after the first certificate and after every renewal.
After an interrupted run
The next playbook run compares the certificate's names, authority,
and saved renewal settings with the certificate task's requested values
again. If certbot stopped while saving a certificate, files of the
certificate's name can remain in /etc/letsencrypt/live/ or
/etc/letsencrypt/archive/ without a renewal file.
The task then fails and names the directories containing the remaining
certificate files, because certbot would obtain a certificate and fail to
save the new certificate. To remove the remaining files, use state: absent
with the interrupted task's certificate_name.
What a removal removes
state: absent also finishes a removal that stopped part of the way.
certbot knows a certificate by its renewal file and removes that file first.
A certbot delete that was stopped, or a first request that was stopped
while certbot saved the certificate, leaves
/etc/letsencrypt/live/<certificate_name> or
/etc/letsencrypt/archive/<certificate_name>, with the private key, and no
renewal file. The task first removes the key copies of an older certbot
(see below). MMX then removes
/etc/letsencrypt/live/<certificate_name> and
/etc/letsencrypt/archive/<certificate_name> and reports changed.
The task's reason says MMX removed files left by an unfinished removal or
request, and a dryrun says MMX would remove the remaining files.
MMX needs no certbot installation to remove the remaining key copies and
certificate directories when the renewal file is missing.
certbot older than 2.6, as in Debian 12, keeps a second
copy of each private key in /etc/letsencrypt/keys/ and the certificate
requests made with them in /etc/letsencrypt/csr/. certbot delete leaves
the private key copies in /etc/letsencrypt/keys/ and the certificate
requests in /etc/letsencrypt/csr/. MMX removes the files that carry a key
of the deleted certificate before it starts certbot delete: after it,
nothing on the node says which keys were the certificate's. certbot's timer
adds such files at each renewal between MMX runs; they go with the
certificate too. A request that failed before any certificate existed also
left a key in
/etc/letsencrypt/keys/, which belongs to no certificate and stays.
On a node with SELinux
SELinux confines some programs of a node and
leaves others alone. This is what a certificate needs on a node where
SELinux is enforcing (measured on Rocky Linux 9 with certbot 3.1 and
nginx):
- certbot needs nothing. The policy does not confine certbot. It gets a certificate through each of the three challenges, both when the task starts it and when the packaged renewal service does.
- The script needs no label. certbot runs the script of
run_after_issue_and_renewalfrom any directory (measured in/usr/local/bin,/opt,/root, and/var/lib), and the script is not confined either, also under the renewal service. - The web server may read the certificate. The policy does confine a
web server. nginx reads
fullchain.pemandprivkey.pemunder/etc/letsencrypt/live/without a label task. - The directory of
challenge: webrootneeds a label for web content. A web server may read only files with such a label, and each file that certbot puts into the directory gets the directory's label.
A webroot_path below /var/www has the label already: the policy gives
every path there the type httpd_sys_content_t, and MMX's directory task
makes a directory with the label that the policy has for its path. A
webroot_path anywhere else gets the label from a selinux_file_context
task before the task that makes the directory, as the
example above
shows.
Without the label, the web server answers the authority with the HTTP
status 403. The certificate task then fails with the authority's answer,
which names the address that the authority fetched and the status. A
/var/www that somebody made by hand with mkdir does not have the label,
and neither has a directory inside it; restorecon -R /var/www on the node
gives both the policy's label.
Errors and what they mean
- certbot is not installed. The task fails with
certbot is not installed on the node; install certbot with a package task before the certbot_certificate node task, and is not tried again. A dryrun reportsnot_checked. See Set up. - The script is missing or not executable, the DNS plugin's package is not installed, or the credentials file does not exist. The task names what is missing and starts no certbot. certbot itself would notice a missing credentials file only after it asked the authority, its message for a missing plugin does not always name the plugin, and it notices a missing script only at the first certificate: at a renewal certbot reports success without running it.
- The authority refuses. certbot ends in the same way for every
refusal, and what it prints differs between its versions; the certbot of
Debian 12 prints an error of its own program in place of the authority's
reason. The authority's own answer is in certbot's log. When MMX finds it
there, the task's reason holds it, with the kind of the error, for example
urn:ietf:params:acme:error:rateLimited, and with the time after which the authority takes another request when the answer names one. Otherwise the reason holds what certbot printed. The task tries once; see Retries. - Another certbot runs too long. A task that gives up waiting says which
lock file is held, and has started no certbot. When its
time_limitended the wait, the reason starts withtime_limit exceeded:and names the other certbot. - certbot's files of the certificate are damaged. When certbot cannot
read a certificate's renewal file, it gets a new certificate, puts it into
another directory,
<certificate_name>-0001, and reports success. MMX reads the renewal file first and fails the task before any request, with the file and the line that it cannot read. - Files of the name without a renewal file. Files of the certificate's
name in certbot's
live/orarchive/directory without a renewal file fail the task in the same way, before any request: certbot would get a certificate from the authority and then fail to save it. A task withstate: absentremoves such files. - The certificate does not hold the task's names after a request. MMX
reads the certificate in
/etc/letsencrypt/live/<certificate_name>/after each request and fails the task when it does not hold the task's names. - HTTP status 403 from the web server in the authority's answer, on a node with SELinux: the webroot directory lacks the label for web content; see On a node with SELinux.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9.
The suite tests/integration/certbot_certificates.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, and Rocky Linux 9, in Incus containers on the Debian family and in a virtual machine on Rocky Linux 9, with the certbot that each
distribution packages: certbot 2.1 on Debian 12, 4.0 on Debian 13,
2.9 on Ubuntu 24.04, 4.0 on Ubuntu 26.04, and 3.1 on Rocky Linux 9, from EPEL. EPEL's certbot does not install on AlmaLinux 10 at present: its python3-pyOpenSSL needs a newer cryptography than AlmaLinux 10 has. On Ubuntu 26.04
it is certbot 4.0.0. Every certificate of the suite comes from Pebble, the ACME test server of
Let's Encrypt, on the test guest. The suite also passed on Hetzner Cloud
servers with Debian 13.
Not tested: certbot's DNS plugins other than rfc2136 against their
services, certbot from snap or pip, and a certificate authority's real limit
on requests; the suite's authority refuses a request by its own rules.
Limits on each distribution says what is limited for this module on AlmaLinux 10, and why.
Why it works this way
-
The authority is required. Contacting a public certificate authority must be visible in each task, following required settings.
-
Omission preserves saved renewal settings. A partial task must not delete a renewal script or plugin setting.
renewal_settings_to_removefollows explicit deletion. -
The email name states when it applies.
account_email_when_registeredfollows the creation-only naming rule; changing that line does not update an existing authority account. -
The module is named for its tool, and it does not install certbot. Installing is a package task, which already handles versions and removal.
-
MMX gets a certificate once; certbot's own timer renews. Renewal is ongoing work between runs, which MMX does not do.
-
challengehas no default. It decides how the authority reaches the server, and what must be free or running on it, so it must be on the page. -
MMX reads certbot's files, never what certbot prints. certbot's messages differ between the versions that the supported distributions package, and its exit code does not say where a certificate went.
-
No certbot for an unchanged certificate. certbot sends the authority up to three requests also when it changes nothing, and a certbot command fails while another certbot runs.
-
Another authority gets a new certificate; its address is never written into certbot's settings. Those settings name an account at one authority. With only the address changed, every later renewal fails for good (measured on certbot 1.21 to 4.2).
-
Changed settings are written into the renewal file and not tested. A test needs the authority. certbot's own command for changed settings is missing in Debian 12, and its dry run asks Let's Encrypt's test server also for a certificate of another authority unless that authority is named again. One way that behaves the same on every distribution was preferred, and this page gives the command that tests.
-
MMX writes only the lines of the renewal file whose values differ from the task. certbot writes the names of a
webrootcertificate in another order at each renewal, and a person may keep a note in the file. A file that is written whole also loses settings: a renewal file withoutkey_typemade certbot change the key type at the next renewal. -
MMX checks the script, the DNS plugin, the credentials file, and certbot's own files of the certificate before certbot starts. certbot notices a missing credentials file only after 4 to 5 requests to the authority. For files of the name without a renewal file it sends 9 requests, gets the certificate, and then fails to save it (measured on certbot 3.1 and 4.0). Each such request counts against the authority's limits. certbot's message for a missing plugin does not name the plugin when the task gives a credentials file, and a missing script stops only the first certificate, not a renewal.
-
The task waits for another certbot instead of failing. The task tries once because of the authority's limits, and a packaged renewal service can hold certbot's lock for eight minutes. Without the wait, a run that meets a renewal would fail for no fault of its own.
-
MMX learns that another certbot runs from the kernel's answer about certbot's lock, not from certbot's message. Asking takes no lock and cannot disturb the certbot that runs. The message would need a certbot that fails first, and its text is not an interface.
-
dns_credentials_fileis optional, and the wait is a field.route53takes no credentials file, so a required field could not be written for it. Therfc2136plugin waits 60 seconds unless told otherwise, and a slow DNS service needs more than a plugin's default. -
state: absentalso removes the key copies of an older certbot. They are private keys of the deleted certificate, and the design promises that the key is gone.
This page is docs/reference/modules/certbot_certificate.md in the MMX repository.