I had assumed that when certbot does an http authentication of a domain name as part of getting Let’s Encrypt to issue or renew a cert, it would do so by touching the appropriately named file in http://domain.name.tld/.well-known/acme-challenge, waiting for the challenge to resolve, and then deleting it.

And sure, that’s what it does with --webroot. And I assumed that if you passed it --nginx, certbot would use that to look for the right config to parse to get the right domain to directory mapping, and then reload nginx afterwards.

It does not do that.

Instead, it inserts new config into nginx to just return a 200 success code for the challenge name as though it were a 0-length file on disk. Nothing hits disk in the .well-known directory.

It turns out that this can backfire in a number of very hard to debug ways.

So, if you are having an authentication problem with certbot, try passing --webroot and the appropriate -w directory.

And if you’re writing some bit of utility code, howzabout not being so clever. Do the expected things.