Architectural Decision Records
Documentation of major architectural changes in Certbot
ADR
Status: Pending
Date: 2024-06-02
Context
The level of Windows support for Certbot varies depending on the core team's capacity to enhance and rectify issues with the Windows installer. Presently, Windows support is classified as Beta. This designation allows us the flexibility to deliberate on whether to sustain support long term, given the current resource constraints.
Decision Drivers
If we chose to maintain support for the Windows installer, we would be providing an installer with certain issues specific to Windows that may take significant time to address.
Off Ramps for Windows Users
We understand that it could be cumbersome to switch certificate management software. Below are options that are already highly popular for Windows users utilizing Let's Encrypt certificates. All options in most cases support automatically configuring the web server.
Options:
- Certify Certificate Manager
- win-acme
- WLS2 with the Certbot Snap distribution. With systemd officially supported in WSL2. This is also a possible route now.
Related Github Issues:
- Hooks on Windows unable to locate executables in PATH if .exe omitted
- Windows renew task created for groups "Administrators" results in multiple concurrent executions
- hooks: investigate decoding errors in subprocess code and related community note
Decision Outcome
Discontinue Windows beta program and provide users options to migrate to different ACME clients.
Consequences and Concerns
What happens to users that currently use the Windows installer?
All alternative options in most cases support automatically configuring the web server. And if manually configured, users would need to obtain certificates using the new ACME software and then update the paths in their web server config to use those certificates rather than the certificates managed by Certbot.
Links for Further Context
ADR
Status: Deployed🚀
Deploy Date: 2022-11-21
Context
Certbot will be switching to issuing ECDSA (secp256r1) certificates by default. This will happen in the release of Certbot 2.0.
Decision Drivers
ECDSA is widely supported in modern web software. Compatibility is no longer a concern, we feel this is the right time to make ECDSA the default certificate type to help people get the security and performance benefits offered by ECDSA.
Decision Outcome
- Existing certificates will not be affected.
- Renewing an existing certificate using
certbot renew(including via Certbot’s cron jobs, timers and scheduled tasks) will preserve the existing key type. - Renewing/replacing an existing certificate with
certbot certonly/runwill preserve the existing key type if running non-interactively and prompt the user to confirm the key type if running interactively.
Consequences and Concerns
The following was addressed prior to decision to release:
- Breaking changes that could occur with existing certificates
- Renewing an existing certificate using
certbot renew(including via Certbot’s cron jobs, timers and scheduled tasks) will preserve the existing key type. - Renewing/replacing an existing certificate with
certbot certonly/runwill preserve the existing key type if running non-interactively and prompt the user to confirm the key type if running interactively.
Other Changes Addressed with Certbot 2.0
acme API Changes
- acme.client.Client, acme.client.BackwardsCompatibleClientV2, and acme.magic_typing will be removed.
certbot API Changes
- Certbot’s zope based interfaces in certbot.interfaces will be removed in favor of the abc based interfaces found in the same module.
- The attributes FileDisplay, NoninteractiveDisplay, SIDE_FRAME, input_with_timeout, separate_list_input, summarize_domain_list, WIDTH, HELP, and ESC from certbot.display.util will be removed.
- certbot.crypto_util.init_save_csr, certbot.crypto_util.init_save_key, and certbot.compat.misc.execute_command will be removed in favor of certbot.crypto_util.generate_csr, certbot.crypto_util.generate_key, and certbot.compat.misc.execute_command_status respectively.
- certbot.tests.util.patch_get_utility, certbot.tests.util.patch_get_utility_with_stdout, and certbot.util.get_strict_version will be removed.
- Functions in certbot.tests.util were previously using the third party mock module if it was available for backwards compatibiliy. This behavior will be removed and unittest.mock from the standard library will always be used instead.
certbot UI Changes
- Certbot will drop support for versions of ACME from before the RFC 8555 standard.
- Our Apache plugin will no longer support Apache 2.2 which reached its end-of-life in 2018.
- When Certbot was first released, 3rd party plugins names had to have the format dist_name:plugin_name instead of just plugin_name both on the CLI and in configuration files. Certbot has accepted the shorter plugin_name version for a while now and support for the format dist_name:plugin_name will be dropped.
Links for Further Context
Roadmap Certbot 2.0 Checklist
- Community Announcement
- ADR
- 2.0 branch created (after feature branches are)
- Complete PR review on all feature branches on 2.0
- Nightly and Beta snap channel for public testing
- Move to stable - 2.0 [Docker and Pypi first, then Progressive Release in Snap]
Post Release Notes
ADR
Status: Deployed 🚀
Deploy Date: 2020-04
Context and Problem Statement
The standard app delivery model across different operating systems and distros is convoluted and often plagued with version problems and support is often needed for older libraries. Creating complexity that is often hard to solve unless the software distributor is directly on the distro's team to urge updates for various packaging types.
Decision Drivers
- Most modern Linux distributions (basically any that use systemd) can use the Certbot snap.
- This would make deployment of Certbot more streamlined not only for maintainers, but updates for users would be as well
Decision Outcome
- Certbot automatically stays up-to-date, giving you access to the latest features including updates to the TLS configuration Certbot uses when installing certificates with Apache and Nginx.
- Automatic renewal comes preconfigured, so there is no need to manually set up a cron job or systemd timer.
Consequences and Concerns
- Concern over centralization of Canonical's control in the Snap atmosphere
- We support the ARMv7, ARMv8, and x86_64 architectures. But not all of course.
Links for Further Context
ADR
Status: Deployed 🚀
Deploy Date: December 2020
Context and Problem Statement
The standard app delivery model across different operating systems and distros is convoluted and often plagued with version problems and it became infeasible for our small team to maintain. It's a custom, self-updating shell script that tries to support all popular UNIX OSes. Keeping this script working in all the different environments out there and the changes being made to them was just too much work.
Decision Drivers
The biggest factor that drove this deprecation now was Python 2 reaching its end-of-life this year. When this script was initially written 5 years ago, it was written to use Python 2 on most systems. While Python 2 is still receiving security support by various distros, the Python ecosystem has moved on and many of our dependencies are dropping support for Python 2. In order to continue to provide updates to our users, we have to get them on Python 3. We tried to migrate certbot-auto users to Python 3 in the past, but it's a ton of work and extremely error prone. Instead of trying to do this work and hope we didn't break anything (like we did last time 3), we decided to sunset the script in favor of other distribution methods.
Decision Outcome
In our 1.10.0 release on Tuesday, we deprecated certbot-auto, one of the ways to install Certbot, on Debian based systems including Ubuntu. In our 1.11.0 release, we plan to deprecate the script on every OS. It is only certbot-auto that we deprecated. Our other distribution methods or Certbot more generally was not deprecated on Debian.
Consequences and Concerns
While we do not recommend this, if certbot-auto was working for you, it's possible to continue to use the last version of the script that worked on Debian based OSes. Taking this approach means you will not receive any bug fixes, security fixes, or compatibility fixes with Let's Encrypt's servers. If that does not deter you, you can find the last version of the script that worked on Debian at https://raw.githubusercontent.com/certbot/certbot/v1.9.0/certbot-auto 89. If you use this, make sure you are fully comfortable with all of these downsides and include --no-self-upgrade on the command line to prevent the script from updating itself to a deprecated version.
Links for Further Context