Currently any ACME challenge for unknown virtual host returns 503. This
is inconvenient because if the user does not use wildcard certificates,
then the user must match the configuration of certificate renewal script
to what virtual hosts are enabled at the time.
This must be done automatically, because due to short certificate
lifetime the renewal script runs automatically. Additionally, enabling a
previously disabled virtual host forces certificate renewal.
Accordingly, it's worthwhile supporting unknown virtual hosts for the
purposes of passing ACME challenges. This is done by introducing a
global ACME_HTTP_CHALLENGE_ACCEPT_UNKNOWN_HOST variable to control this.
Previous instructions could make the impression that user have to create a directory named as the virtual host and also a file named as the virutal host.
Users may not be aware that the filename chosen to add extra
configuration in /etc/nginx/conf.d may interfere with nginx-proxy.
nginx-proxy stores its configuration at /etc/nginx/conf.d/default.conf.
Any files that come before default.conf in alphabetical order will be
applied before default.conf and vice-versa.
This is confusing, because the documentation does not specify how
exactly nginx-proxy interacts with nginx.
This can be remedied by a simple note alerting the users of the
importance of filename choices.
Values:
* `legacy` (default): generate location blocks for ACME HTP Challenge
excepted when `HTTPS_METHOD=noredirect` or there is no certificate for
the domain
* `true`: generate location blocks for ACME HTP Challenge in all cases
* `false`: do not generate location blocks for ACME HTP Challenge
This feature is currently needed because acme-companion may generate
the HTTP Challenge configuration while it was done already by nginx-proxy
(see #2465#issuecomment-2136361373).
Also sometimes a hardcoded ACME challenge location is not wanted because
the challenge validation is not done with acme-companion / Let's Encrypt,
and with a challenge location setup differently.
* chore/doc: explicit policy on missing certificate
This doesn't change the current nginx-proxy behavior, but makes explicit
the current HTTPS_METHOD policy on missing certificate.
* fix: bad wording about missing certificate
Co-authored-by: Nicolas Duchon <nicolas.duchon@gmail.com>
* docs: typo in suggestion
---------
Co-authored-by: Nicolas Duchon <nicolas.duchon@gmail.com>
