From 9bec6bb5eb6e393072f91f265c8133802a093528 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Mon, 1 Nov 2021 11:31:40 -0700 Subject: [PATCH] docs: Extend Certbot troubleshooting documentation. This should help folks who have problems with Certbot renewal; we had a couple reported this week which I think were both caused by firewall issues. --- docs/production/install.md | 8 +++++--- docs/production/ssl-certificates.md | 32 ++++++++++++++++++++++++----- 2 files changed, 32 insertions(+), 8 deletions(-) diff --git a/docs/production/install.md b/docs/production/install.md index faccd115bc..37d512d39c 100644 --- a/docs/production/install.md +++ b/docs/production/install.md @@ -63,9 +63,11 @@ If the script gives an error, consult [Troubleshooting](#troubleshooting) below. suitable for production use, but may be convenient for testing. - `--certbot`: With this option, the Zulip installer automatically - obtains an SSL certificate for the server [using Certbot][doc-certbot]. - If you'd prefer to acquire an SSL certificate yourself in any other - way, it's easy to [provide it to Zulip][doc-ssl-manual]. + obtains an SSL certificate for the server [using + Certbot][doc-certbot], and configures a cron job to renew the + certificate automatically. If you'd prefer to acquire an SSL + certificate yourself in any other way, it's easy to [provide it to + Zulip][doc-ssl-manual]. You can see the more advanced installer options in our [deployment options][doc-deployment-options] documentation. diff --git a/docs/production/ssl-certificates.md b/docs/production/ssl-certificates.md index 44b5993c18..1710327b97 100644 --- a/docs/production/ssl-certificates.md +++ b/docs/production/ssl-certificates.md @@ -107,11 +107,33 @@ the server controls the website at that hostname; and is then given a certificate. (For details, refer to [Let's Encrypt](https://letsencrypt.org/how-it-works/).) -Then it records a flag in `/etc/zulip/zulip.conf` saying Certbot is in -use and should be auto-renewed. A cron job checks that flag, then -checks if any certificates are due for renewal, and if they are (so -approximately once every 60 days), repeats the process of request, -prove, get a fresh certificate. +### Renewal + +Let's Encrypt certificates expire after 90 days. Short expiration +periods are good for security, but they also mean that it's important +to automatically renew them to avoid regular maintenance work. + +Zulip configures automatic renewal for you. As a result, a Zulip +server configured with Certbot does not require any ongoing work to +maintain a current valid SSL certificate. + +Specifically, the `setup-certbot` tool (and by extension, the +installer option) enables the Certbot `auto_renew` property in +`/etc/zulip/zulip.conf`. This, in turn, configures a cron job +(`/etc/cron.d/certbot`) that will renew any Certbot certificates that +are due for renewal. The renewal process repeats the Certbot +proof-of-control process, receives the new certificate from Certbot, +installs the new certificate, and then reloads `nginx`. + +#### Troubleshooting + +If your Certbot certificate expires, it is usually because of firewall +rules preventing the Certbot renewal process (which is essentially +identical to the initial certificate request process) from +working. You can debug interactively by running the command from the +cron job, +`/home/zulip/deployments/current/scripts/lib/certbot-maybe-renew`, as +`root`. ## Self-signed certificate