Let's make Let's Encrypt easy and simple

Help
26

(Sorry in advance for the longwinded post.)

I've had many issues with getting letsencrypt certs working on my webservers (running Arch Linux / Nginx). Every guide I've looked at online seemed to provide a different set of commands to run, some of which worked partially and some which didn't work at all. I did manage to piece together the "magic command" which will get a certificate for my domains in the way I wanted, but now I am struggling to get renewing working, though I think I might have it now.

(To give some context, I am a systems administrator for a small web development company. I have a few years of experience in this position, and several years of prior experience hosting personal projects and dealing with Linux.)

Looking at the "Getting Started" docs, here are some questions that it raises (and consequently are potential areas for improvement).

Installing the Client Software

Last time I looked at this section, I don't think it provided instructions for installing letsencrypt through the native package manager, leaving me to question whether or not cloning the git repo was the "correct" way to do it. The link to https://certbot.eff.org/ fixes that issue, though.

I also did not understand the difference between letsencrypt and letsencrypt-auto, but I think the docs are much clearer on that now. However, now I'm confused as to what the difference is between letsencrypt and certbot. Are they just aliases for the same program? The way I understand it is:

  • If your Linux distro's package manager supports letsencrypt, install it from there and use the letsencrypt binary.
  • If not, then clone the git repo and use the certbot-auto binary.

That's a bit confusing, but if that is correct, then the docs are good in that regard.

How To Use The Client

This is the most difficult section to understand.

Certbot supports a number of different “plugins” that can be used to obtain and/or install certificates.

Based on what I read in this section, two possible plugins are apache and webroot, but there may be more. (Is there a list somewhere? I know there is, but there's no link to it.) The apache plugin

automates both obtaining and installing certs

This is good and descriptive. Unfortunately for me, this doesn't work, because I don't use Apache on a recent Debian OS, so I continue reading:

On other platforms automatic installation is not yet available, so you will have to use the certonly command. Here are some examples:

This is the first time certonly is mentioned on the entire page, and I have no idea what it does. Is it a plugin? I don't think so. But for some reason, I don't use it with the apache plugin, but I do use it with the webroot plugin. Why can't the script infer whether or not I want certonly based on the plugin I provide? The docs say that certonly is a "command"...are there other commands? Why didn't I specify a command when using the apache plugin?

This command will obtain a single cert for example.com, www.example.com, thing.is, and m.thing.is; it will place files below /var/www/example to prove control of the first two domains, and under /var/www/thing for the second pair.

I'm not sure if this is describing the certonly command (as it implies) or the webroot plugin.

To obtain a cert using a built-in “standalone” webserver (you may need to temporarily stop your existing webserver, if any) for example.com and www.example.com:

Based on the fact that there are two dashes in front of standalone, it seems that this might be another "plugin", but I'm not sure about that. This plugin is a bit confusing, but the parenthesized text (and my prior understanding of these plugins) is enough for me to figure out what is going on behind the scenes.

I'd like to get an understanding of what these plugins do and how many of them there are. In order to get to the official docs for the list of plugins, I had to click on the following sequence of links:

Two questions:

  1. Is this the correct place to look for the "official" docs?
  2. If so, did I miss an obvious link from somewhere on the home page? I would think that the "Documentation" link under the "Support" menu should take me to the official documentation, but instead it takes me to a forum.

So the documentation locations we have are:

  1. Getting Started - Let's Encrypt
  2. The forums (where we are now)
  3. Certbot Github wiki
  4. letsencrypt --help (discussed later)
  5. Welcome to the Certbot documentation! — Certbot 2.7.0.dev0 documentation

The last one looks like it is the most "official", but I'm not sure about that. Let's see how well it matches up with what I learned on the "Getting Started" page.

The Certbot client supports a number of different “plugins” that can be used to obtain and/or install certificates.

So far, so good.

Plugins that can obtain a cert are called “authenticators” and can be used with the “certonly” command. Plugins that can install a cert are called “installers”. Plugins that do both can be used with the “certbot run” command, which is the default.

What does "obtain a cert" mean? I think it means that it creates as certificate on the letsencrypt servers after proving domain ownership, downloads it, and saves it to the filesystem ; if so, this could be made clearer. So, these plugins can be used with the "certonly" command...can they also be used without the "certonly" command? Why would I use "certonly" versus leaving it out? There is still no clear explanation of what this does.

Plugins that can install a cert are called “installers”.

What does "install" mean? Does it mean that it puts the certificates somewhere on the file system (typically what is meant by "install"), or does it mean that it automatically modifies the webserver's config files to enable SSL and point the web server to the correct location for the certs (this is what I think it means)?

Plugins that do both can be used with the “certbot run” command, which is the default.

This is the first time I have seen reference to the "run" command. What does this do? What happens if I leave it off? How is it different from "certonly"?

Then we have a list of plugins and whether or not they are authenticators, installers, or both. The "Notes" for each of the plugins is very helpful. I finally understand what plugins are available for me to use and what exactly they do. Since nginx is "very experimental", I don't choose it, but I want things to be automated as possible, so I am left with choosing "webroot" or "standalone". I don't want my server to go down, so I choose "webroot".

The long descriptions of each of the plugins below is also very helpful. I discover in the "Webroot" section that I have to use certonly and --webroot (still don't know what certonly does, but I'll just go with it for now).

Unfortunately, the provided example command doesn't work (note that it has been a while since I did this, so perhaps things have changed since then). The fix that I pieced together from various guides on the internet was to include --server https://acme-v01.api.letsencrypt.org/directory in the command. I have no idea what this is or why I need it, but when I include it, fetching certificates works. This is not mentioned anywhere in the docs.

Renewal

Perhaps this should be obvious, but it's something that I didn't understand for quite a while...you only need to run letsencrypt successfully once. Each time you run it, it will fetch a brand new certificate and place it in your filesystem with a new name, which is probably undesirable. When your cert is about to expire, you should instead use letsencrypt renew. As far as I understand it, letsencrypt keeps track of all your previously successful certs and renews them using the exact same parameters. It also skips renewals that aren't close to expiration yet (unless you specify --force), so this is a good option for adding to a daily cron job.

The docs give examples of using other options passed to --renew:

For example, if you want to use the standalone plugin to renew your certificates, you may want to use a command like

certbot renew --standalone --pre-hook "service nginx stop" --post-hook "service nginx start"

The hooks are nice, but why specify --standalone? If I used --standalone when I first got my certs, do I need to specify it explicitly when I renew? What about --webroot? It works just fine without specifying my plugin, so when would I want to? Only when using hooks?

Later in the "Renewal" section it says:

An alternative form that provides for more fine-grained control over the renewal process (while renewing specified certificates one at a time), is certbot certonly with the complete set of subject domains of a specific certificate specified via -d flags.

At this point I've all but given up what certonly is supposed to be doing. Now it has something to do with renewal too? Will this command actually renew my certificates, or will it fetch new certificates? The next paragraph seems to partially answer my questions:

(... Specifying a subset of the domains creates a new, separate certificate containing only those domains, rather than replacing the original certificate.) The certonly form attempts to renew one individual certificate.

So, sometimes certonly creates a new certificate (if it hasn't seen the set of domains before), or it renews an existing certificate (if it has seen the set of domains before).

If my understanding of these things is correct, then the docs are on the right track, but they could be made clearer. I also just realized (when attempting to run letsencrypt with the incorrect --renew parameter) that the binary also has some documentation! Let's see what that says:

The Let's Encrypt agent can obtain and install HTTPS/TLS/SSL certificates.
By default, it will attempt to use a webserver both for obtaining and installing
the cert. Major SUBCOMMANDS are:

(default) run        Obtain & install a cert in your current webserver
certonly             Obtain cert, but do not install it (aka "auth")
install              Install a previously obtained cert in a server
renew                Renew previously obtained certs that are near expiry
revoke               Revoke a previously obtained certificate
rollback             Rollback server configuration changes made during install
config_changes       Show changes made to server config during installation
plugins              Display information about installed plugins

This helps greatly, and I wish these things were talked about in the docs. I will assume that "SUBCOMMANDS" are the same thing as "commands". My understanding from this output is:

  1. If you don't specify a command, then the command is "run".
  2. "install a cert in your current webserver" implies that it's going to mess with my server's config files, thus defining what "install" means.
  3. certonly obtains, but does not install. This means that it will authenticate with the letsencrypt server, generate the certificate, and download it to my filesystem, but it will not mess with my webserver's config files. What is the behavior then if I specify certonly with --apache or --nginx? Does that combination of parameters even make sense?
  4. "run" is the same as "certonly" followed by "install".

Other question that pops up regarding this specific text:

By default, it will attempt to use a webserver both for obtaining and installing the cert.

Does this mean that it will use my existing, running webserver (i.e. nginx), meaning that the --webroot plugin is used by default (I don't think so), or it will use it's own webserver (aka --standalone)? Which further raises the question, does running the command without specifying a plugin even make sense? If not, it might be good to explicitly say that specifying a plugin is required somewhere in the documentation.

All in all, I think reading the letsencrypt --help output is necessary (in combination with the online documentation) to understanding which options to pick and how to successfully get a cert. The online documentation could be improved in the following ways:

  1. Explain up front what "commands" are, particularly certonly. Fold in the explanations from the --help output to make it clear what each command does. Make it clearer that commands are different from plugins, and maybe say that using certain plugins together with some commands doesn't make sense (if my understanding is correct).
  2. Make it clearer what is happening at each stage. When example commands are given, explain why each of the parameters was chosen.
  3. Reduce the number of places where things are documented. Make it clear which site is the "official" host. The "Getting Started" page could be folded into the official documentation to reduce confusion, and all documentation links on the home page should point to this official place.
  4. Increase/add links between pages. For example, when discussing plugins and commands on the "Getting Started" page, you could link to the other pages that describe them in more detail.

To be clear, all of the above are merely suggestions based on what I found to be confusing when using letsencrypt and reading through the docs.

5 Likes