WELLKNOWN documentation gives conflicting statements #95

New Issue

2025-12-29T00:24:41+01:00

adam commented

2025-12-29 00:24:41 +01:00

Originally created by @assistcontrol on GitHub (May 8, 2016).

The documentation for WELLKNOWN gives conflicting instructions.

your WELLKNOWN variable must include the "acme-challenge" subdirectory
(eg, WELLKNOWN="/etc/wellknown/acme-challenge", not WELLKNOWN="/etc/wellknown"

An example config would be to create a directory /var/www/letsencrypt,
set WELLKNOWN=/var/www/letsencrypt

So does WELLKNOWN have to have "acme-challenge" at the end or not? What is the difference between:

WELLKNOWN="/etc/wellknown/acme-challenge" not WELLKNOWN="/etc/wellknown"

and

create directory '/var/www/letsencrypt", set WELLKNOWN=/var/www/letsencrypt"

Originally created by @assistcontrol on GitHub (May 8, 2016). The documentation for WELLKNOWN gives conflicting instructions. > your WELLKNOWN variable **must** include the "acme-challenge" subdirectory > (eg, `WELLKNOWN="/etc/wellknown/acme-challenge"`, **not** `WELLKNOWN="/etc/wellknown"` > > An example config would be to create a directory `/var/www/letsencrypt`, > set `WELLKNOWN=/var/www/letsencrypt` So does `WELLKNOWN` have to have `"acme-challenge"` at the end or not? What is the difference between: > `WELLKNOWN="/etc/wellknown/acme-challenge"` **not** `WELLKNOWN="/etc/wellknown"` and > create directory `'/var/www/letsencrypt"`, set `WELLKNOWN=/var/www/letsencrypt"`

adam closed this issue

2025-12-29 00:24:41 +01:00

adam commented

2025-12-29 00:24:42 +01:00

@lukas2511 commented on GitHub (May 8, 2016):

I agree that documentation may be a bit confusing, I'll have to work on that.

For now I hope this is easy to understand:

Let's say you have a page http://example.org. In that case the ACME server will look under http://example.org/.well-known/acme-challenge/[...] for challenge responses.

If you have a simple setup with basically just one webpage you could do something like WELLKNOWN=/var/www/.well-known/acme-challenge, so letsencrypt.sh will store the challenge responses directly in that directory.

If you have a more complicated setup it's easier to add an Alias or location or whatever part to your webserver config telling it to serve /.well-known/acme-challenge on your domain from a different directory.

With that in mind you'd probably do something like location /.well-known/acme-challenge { alias /var/www/letsencrypt; }, and in that case you obviously don't need to add the .well-known/[...] part to your actual path.

@lukas2511 commented on GitHub (May 8, 2016): I agree that documentation may be a bit confusing, I'll have to work on that. For now I hope this is easy to understand: Let's say you have a page `http://example.org`. In that case the ACME server will look under `http://example.org/.well-known/acme-challenge/[...]` for challenge responses. If you have a simple setup with basically just one webpage you could do something like `WELLKNOWN=/var/www/.well-known/acme-challenge`, so letsencrypt.sh will store the challenge responses directly in that directory. If you have a more complicated setup it's easier to add an Alias or location or whatever part to your webserver config telling it to serve `/.well-known/acme-challenge` on your domain from a different directory. With that in mind you'd probably do something like `location /.well-known/acme-challenge { alias /var/www/letsencrypt; }`, and in that case you obviously don't need to add the `.well-known/[...]` part to your actual path.

adam commented

2025-12-29 00:24:42 +01:00

@assistcontrol commented on GitHub (May 8, 2016):

So if you set WELLKNOWN=/var/www/letsencrypt does letsencrypt.sh automatically create .well-known/acme-challenge/ in it?

Does "your WELLKNOWN variable must include the "acme-challenge" subdirectory" mean

The WELLKNOWN variable must have "acme-challenge" at the end (i.e. WELLKNOWN=/foo/bar/acme-challenge)

or

The path set by WELLKNOWN must have an "acme-challenge" directory in it (i.e. WELLKNOWN=/foo/bar; mkdir /foo/bar/acme-challenge)

Sorry for being dense, but the docs sortof imply two different things at once.

@assistcontrol commented on GitHub (May 8, 2016): So if you set `WELLKNOWN=/var/www/letsencrypt` does letsencrypt.sh automatically create `.well-known/acme-challenge/` in it? Does "your `WELLKNOWN` variable **must** include the "acme-challenge" subdirectory" mean - The `WELLKNOWN` variable must have "acme-challenge" at the end (i.e. `WELLKNOWN=/foo/bar/acme-challenge`) or - The path set by `WELLKNOWN` must have an "acme-challenge" directory in it (i.e. `WELLKNOWN=/foo/bar; mkdir /foo/bar/acme-challenge`) Sorry for being dense, but the docs sortof imply two different things at once.

adam commented

2025-12-29 00:24:43 +01:00

@lukas2511 commented on GitHub (May 8, 2016):

As i already said there is some work to be done about documentation.

If you use the simple approach I explained in my last response you'll have to set WELLKNOWN=/var/www/.well-known/acme-challenge and it will create files like /var/www/.well-known/acme-challenge/TOKEN, that can then be served as http://example.org/.well-known/acme-challenge/TOKEN.

If you define an alias you'll have WELLKNOWN=/var/www/letsencrypt with /var/www/letsencrypt/TOKEN and still everything served as http://example.org/.well-known/acme-challenge/TOKEN.

@lukas2511 commented on GitHub (May 8, 2016): As i already said there is some work to be done about documentation. If you use the simple approach I explained in my last response you'll have to set `WELLKNOWN=/var/www/.well-known/acme-challenge` and it will create files like `/var/www/.well-known/acme-challenge/TOKEN`, that can then be served as `http://example.org/.well-known/acme-challenge/TOKEN`. If you define an alias you'll have `WELLKNOWN=/var/www/letsencrypt` with `/var/www/letsencrypt/TOKEN` and still everything served as `http://example.org/.well-known/acme-challenge/TOKEN`.

adam commented

2025-12-29 00:24:43 +01:00

@assistcontrol commented on GitHub (May 8, 2016):

Okay it just clicked there, thank you :-)

@assistcontrol commented on GitHub (May 8, 2016): Okay it just clicked there, thank you :-)

adam commented

2025-12-29 00:24:44 +01:00

@seefood commented on GitHub (May 9, 2016):

Yeah, the wording could be clearer. the WELLKNOWN needs to point to the directory that the webserver will serve as the absolute path URI, etc.
Cheers!

@seefood commented on GitHub (May 9, 2016): Yeah, the wording could be clearer. the WELLKNOWN needs to point to the directory that the webserver will serve as the absolute path URI, etc. Cheers!

adam commented

2025-12-29 00:24:44 +01:00

@mortenf commented on GitHub (May 21, 2016):

Slightly related: Apparently the default value for WELLKNOWN is "$BASEDIR/.acme-challenges" (note the "s" at the end), but everywhere else discusses just ".acme-challenge". I got around it by overriding the default in the config.sh file.

@mortenf commented on GitHub (May 21, 2016): Slightly related: Apparently the default value for WELLKNOWN is "$BASEDIR/.acme-challenges" (note the "s" at the end), but everywhere else discusses just ".acme-challenge". I got around it by overriding the default in the config.sh file.

adam commented

2025-12-29 00:24:45 +01:00

@lukas2511 commented on GitHub (May 22, 2016):

@mortenf since you shouldn't expose your basedir to the web anyway this shouldn't make much of a difference. i think i'll change the default value to something completely different to make this a bit clearer.

@lukas2511 commented on GitHub (May 22, 2016): @mortenf since you shouldn't expose your basedir to the web anyway this shouldn't make much of a difference. i think i'll change the default value to something completely different to make this a bit clearer.

adam commented

2025-12-29 00:24:46 +01:00