diff --git a/cmd/flags.go b/cmd/flags.go index cc551f63..46df12ce 100644 --- a/cmd/flags.go +++ b/cmd/flags.go @@ -70,7 +70,7 @@ func CreateFlags(defaultPath string) []cli.Flag { }, cli.StringFlag{ Name: "http.webroot", - Usage: "Set the webroot folder to use for HTTP based challenges to write directly in a file in .well-known/acme-challenge.", + Usage: "Set the webroot folder to use for HTTP based challenges to write directly in a file in .well-known/acme-challenge. This disables the built-in server and expects the given directory to be publicly served with access to .well-known/acme-challenge", }, cli.StringSliceFlag{ Name: "http.memcached-host", diff --git a/docs/content/usage/cli/_index.md b/docs/content/usage/cli/_index.md index 7e662722..6494c7da 100644 --- a/docs/content/usage/cli/_index.md +++ b/docs/content/usage/cli/_index.md @@ -41,7 +41,7 @@ GLOBAL OPTIONS: --http Use the HTTP challenge to solve challenges. Can be mixed with other types of challenges. --http.port value Set the port and interface to use for HTTP based challenges to listen on.Supported: interface:port or :port. (default: ":80") --http.proxy-header value Validate against this HTTP header when solving HTTP based challenges behind a reverse proxy. (default: "Host") - --http.webroot value Set the webroot folder to use for HTTP based challenges to write directly in a file in .well-known/acme-challenge. + --http.webroot value Set the webroot folder to use for HTTP based challenges to write directly in a file in .well-known/acme-challenge. This disables the built-in server and expects the given directory to be served at /.well-known/acme-challenge --http.memcached-host value Set the memcached host(s) to use for HTTP based challenges. Challenges will be written to all specified hosts. --tls Use the TLS challenge to solve challenges. Can be mixed with other types of challenges. --tls.port value Set the port and interface to use for TLS based challenges to listen on. Supported: interface:port or :port. (default: ":443") diff --git a/docs/content/usage/cli/examples.md b/docs/content/usage/cli/examples.md index 46e7065b..e6f3059e 100644 --- a/docs/content/usage/cli/examples.md +++ b/docs/content/usage/cli/examples.md @@ -1,6 +1,6 @@ --- title: "Examples" -date: 2019-03-03T16:39:46+01:00 +date: 2019-11-15T23:25:46+01:00 draft: false --- @@ -54,3 +54,22 @@ lego --email="foo@bar.com" --http --csr=/path/to/csr.pem run ``` (lego will infer the domains to be validated based on the contents of the CSR, so make sure the CSR's Common Name and optional SubjectAltNames are set correctly.) + +## Misc HTTP-01 CLI Examples + +### Write HTTP-01 token to already "served" directory + +If you have an existing server running on port 80 the `--http` option needs to also use the `--http.webroot` option. +This just writes the token to the given directory in the folder `.well-known/acme-challenge` and does not start a server. + +The given directory **should** be publicly served as `/` on the domain(s) for the validation to complete. + +If the given directory is not publicly served you will have to support rewriting the request to the directory; + +You could also implement a rewrite to rewrite `.well-known/acme-challenge` to the given directory `.well-known/acme-challenge`. + +You should be able to run an existing webserver on port 80 and have lego write the token file with the HTTP-01 challenge key authorization to `/.well-known/acme-challenge/` by running something like: + +```bash +lego --accept-tos -m foo@bar.com --http --http.webroot /path/to/webroot -d example.com run +```