Please document the webroot ".well-known" request path

Hello,

I would like to see the webroot/.well-known directory (aka request path) documented in the certbot documentation. In the man page and so forth. It may be documented in the acme protocol, but this is not really discoverable when working directly with certbot and a person's webserver configuration.

I like to use --webroot with certbot and manually configure the webserver. Part of the webserver configuration always involves redirecting http requests to https. But in order to do http validation the .well-known path must not be redirected.

I suggest putting the following sentence at the top of the "webroot" section of the mange page above all the --webroot* options. (I would suggest putting it in the classic FILES section, but you don't have one.)

"To use http domain validation challenges the ACME protocol requires that files in <webroot>/.well-known/ be retrievable using the HTTP protocol."

Without such documentation it is difficult to use certbot and manually configure a websever.

(As long as your making documentation changes, I'd also like to see the sentence 'The certbot "webroot" is also commonly known as the web server's Document Root.' inserted somewhere. But I expect you want a separate feature request.)

Welcome to the community @kop

I don't speak for the Certbot devs but are you looking for more than this?

The webroot plugin works by creating a temporary file for each of your requested domains in ${webroot-path}/.well-known/acme-challenge. Then the Let’s Encrypt validation server makes HTTP requests to validate that the DNS for each requested domain resolves to the server running certbot. An example request made to your web server would look like:
66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"

From:
https://eff-certbot.readthedocs.io/en/stable/using.html#webroot

3 Likes

@MikeMcQ The text you quoted is great, but AFAIK it is not distributed as part of the certbot package installed on the OS. I'm looking for something in the certbot(1) man page, that being where I look when I want to use certbot.

At the moment I'm looking on:
Ubuntu 22.04.1 LTS
Package: certbot
Version: 1.21.0-1build1

1 Like

Hmm. On my Ubuntu 22 I don't even have a man certbot page at all. But, maybe that's because I am using the snap version.

You'll have to wait for expert on certbot packaging b/c I am not it :slight_smile:

4 Likes

One nice thing about man pages is that you know that they go with the version of the software you have installed. No fussing about discovering version numbers and finding the right docs.

1 Like

man 7 certbot includes this information.

3 Likes

Ok. Then it'd be nice to see certbot(1) have a see-also
section referring to certbot(7), so its existence
is clear.

I don't see a certbot(7) on my system. Is this
something introduced after version 1.21.0?
(If not I will make a bug report on the OS packaging.)

I still think adding a single sentence to certbot(1)
wouldn't hurt.

Thanks for the info.

Regards,

Karl
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

1 Like

It seems that the Debian packager chose to only include certbot.1 in the deb: debian/certbot.manpages · master · Debian Lets Encrypt Team / certbot / certbot · GitLab.

Let's Encrypt will happily follow redirects for HTTP validation FWIW. Whatever did not work for you, was probably some other factor.

Yeah, on second thought the descriptions are not very helpful. I've made this basic change at: docs: give webroot and standalone better descriptions by alexzorin · Pull Request #9536 · certbot/certbot · GitHub.

5 Likes

It seems that the Debian packager chose to only include certbot.1
in the deb:
debian/certbot.manpages · master · Debian Lets Encrypt Team / certbot / certbot · GitLab.

Bug report filed:
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1028535

[quote="kop, post:1, topic:191024"]
But in order to do http validation the .well-known path must not be
redirected. [/quote]

Let's Encrypt will happily follow redirects for HTTP validation FWIW.
Whatever did not work for you, was probably some other factor.

By redirect, I meant redirected to a HTTPS URL. As one
would typically do after enabling TLS communication.
Sorry if that wasn't clear.

Without real awareness of the protocol it's an easy
mistake.

Yeah, on second thought the descriptions are not very helpful. I've
made this basic change at:
docs: give webroot and standalone better descriptions by alexzorin · Pull Request #9536 · certbot/certbot · GitHub.

That looks good to me. Thanks.

To my mind you could remove the word "separate"
from the line 61 sentence: "A seperate HTTP server ...".
It's a bit of a distraction and seems unnecessary,
at least to me.

I like the "nominated webroot path" phrase.

While you're at it. I don't find the beginning sentence
of the --webroot-path description, "public_html / webroot path."
to be helpful. Much more clear would be something like:
"Path in the file system from the HTTP server obtains
web content."

And, so long as I'm reviewing the whole man page,
the first occurrence of the term "webroot" uses
the word "folder". Elsewhere "directory" is used.
I don't know if this is an issue but if the man
page is focused on a Un*x audience then "directory"
might be better than "folder".

While I've got your attention it's not clear to me
how to discover the github pages from the letsencrypt.org
website. (I'd have found it easier to open an issue there.)
No need to reply to this unless you'd care to.

Thanks for the help.

Regards,

Karl
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

1 Like

Er, that should be:
"Path in the file system from which the HTTP server obtains web content."

Regards,

Karl
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

As _az noted, the Let's Encrypt servers will follow redirects of the HTTP Challenge to HTTP or HTTPS. I agree it is best to handle the challenge in your web server when it first arrives without redirecting. But, an HTTPS redirect in and of itself will not cause failure of an HTTP Challenge.

See the below topic for Let's Encrypt challenges. Note the Certbot ACME client is developed by EFF and supports CA's other than Let's Encrypt. Other CA's may do things differently.

3 Likes

Thanks much for the info. Once upon a time http challenges
were http only.

regards,

Karl
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

2 Likes

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.