From af47d0574b58d6e73db9cb89d3696b60da30ad05 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Mon, 17 Oct 2022 13:23:48 -0400 Subject: [PATCH] docs: Various updates since 2.5.2 that got missed (#274) * docs: Various updates since 2.5.2 that got missed * Cleanup protocols global options * Sort caddyfile placeholder shortcuts alphabetically for now --- src/docs/markdown/caddyfile/concepts.md | 36 ++++---- src/docs/markdown/caddyfile/directives.md | 2 + .../caddyfile/directives/basicauth.md | 6 +- .../caddyfile/directives/file_server.md | 41 ++++++--- src/docs/markdown/caddyfile/directives/log.md | 3 + .../caddyfile/directives/php_fastcgi.md | 41 ++++++--- .../markdown/caddyfile/directives/respond.md | 3 + .../caddyfile/directives/reverse_proxy.md | 22 ++++- .../markdown/caddyfile/directives/skip_log.md | 44 +++++++++ src/docs/markdown/caddyfile/directives/tls.md | 90 ++++++++++++++----- .../caddyfile/directives/try_files.md | 13 ++- src/docs/markdown/caddyfile/matchers.md | 24 ++++- src/docs/markdown/caddyfile/options.md | 17 ++-- src/docs/markdown/command-line.md | 4 +- 14 files changed, 267 insertions(+), 79 deletions(-) create mode 100644 src/docs/markdown/caddyfile/directives/skip_log.md diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index 84a5511..08a4f51 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -237,36 +237,38 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd |-----------------|-----------------------------------| | `{cookie.*}` | `{http.request.cookie.*}` | | `{dir}` | `{http.request.uri.path.dir}` | -| `{err.*}` | `{http.error.*}` | +| `{err.*}` | `{http.error.*}` | +| `{file_match.*}` | `{http.matchers.file.*}` | +| `{file.base}` | `{http.request.uri.path.file.base}` | +| `{file.ext}` | `{http.request.uri.path.file.ext}` | | `{file}` | `{http.request.uri.path.file}` | -| `{file.*}` | `{http.request.uri.path.file.*}` | | `{header.*}` | `{http.request.header.*}` | | `{host}` | `{http.request.host}` | -| `{labels.*}` | `{http.request.host.labels.*}` | | `{hostport}` | `{http.request.hostport}` | -| `{port}` | `{http.request.port}` | +| `{labels.*}` | `{http.request.host.labels.*}` | | `{method}` | `{http.request.method}` | -| `{path}` | `{http.request.uri.path}` | | `{path.*}` | `{http.request.uri.path.*}` | -| `{query}` | `{http.request.uri.query}` | +| `{path}` | `{http.request.uri.path}` | +| `{port}` | `{http.request.port}` | | `{query.*}` | `{http.request.uri.query.*}` | -| `{re.*.*}` | `{http.regexp.*.*}` | -| `{remote}` | `{http.request.remote}` | +| `{query}` | `{http.request.uri.query}` | +| `{re.*.*}` | `{http.regexp.*.*}` | | `{remote_host}` | `{http.request.remote.host}` | | `{remote_port}` | `{http.request.remote.port}` | -| `{rp.*}` | `{http.reverse_proxy.*}` | +| `{remote}` | `{http.request.remote}` | +| `{rp.*}` | `{http.reverse_proxy.*}` | | `{scheme}` | `{http.request.scheme}` | | `{tls_cipher}` | `{http.request.tls.cipher_suite}` | -| `{tls_version}` | `{http.request.tls.version}` | -| `{tls_client_fingerprint}` | `{http.request.tls.client.fingerprint}` | -| `{tls_client_issuer}` | `{http.request.tls.client.issuer}` | -| `{tls_client_serial}` | `{http.request.tls.client.serial}` | -| `{tls_client_subject}` | `{http.request.tls.client.subject}` | -| `{tls_client_certificate_pem}` | `{http.request.tls.client.certificate_pem}` | | `{tls_client_certificate_der_base64}` | `{http.request.tls.client.certificate_der_base64}` | -| `{uri}` | `{http.request.uri}` | +| `{tls_client_certificate_pem}` | `{http.request.tls.client.certificate_pem}` | +| `{tls_client_fingerprint}` | `{http.request.tls.client.fingerprint}` | +| `{tls_client_issuer}` | `{http.request.tls.client.issuer}` | +| `{tls_client_serial}` | `{http.request.tls.client.serial}` | +| `{tls_client_subject}` | `{http.request.tls.client.subject}` | +| `{tls_version}` | `{http.request.tls.version}` | | `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` | -| `{vars.*}` | `{http.vars.*}` | +| `{uri}` | `{http.request.uri}` | +| `{vars.*}` | `{http.vars.*}` | diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 02f14fb..1019427 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -64,6 +64,7 @@ Directive | Description **[rewrite](/docs/caddyfile/directives/rewrite)** | Rewrites the request internally **[root](/docs/caddyfile/directives/root)** | Set the path to the site root **[route](/docs/caddyfile/directives/route)** | A group of directives treated literally as single unit +**[skip_log](/docs/caddyfile/directives/skip_log)** | Skip access logging for matched requests **[templates](/docs/caddyfile/directives/templates)** | Execute templates on the response **[tls](/docs/caddyfile/directives/tls)** | Customize TLS settings **[tracing](/docs/caddyfile/directives/tracing)** | Integration with OpenTelemetry tracing @@ -115,6 +116,7 @@ tracing map vars root +skip_log header copy_response_headers # only in reverse_proxy's handle_response block diff --git a/src/docs/markdown/caddyfile/directives/basicauth.md b/src/docs/markdown/caddyfile/directives/basicauth.md index 7010ffc..9631563 100644 --- a/src/docs/markdown/caddyfile/directives/basicauth.md +++ b/src/docs/markdown/caddyfile/directives/basicauth.md @@ -25,10 +25,14 @@ basicauth [] [ []] { ``` - **<hash_algorithm>** is the name of the password hashing algorithm (or KDF) used for the hashes in this configuration. Default: `bcrypt` + - **<realm>** is a custom realm name. + - **<username>** is a username or user ID. + - **<hashed_password>** is the password hash. -- **<salt_base64>** is the base-64 encoding of the password salt, if an external salt is required. + +- **<salt_base64>** is the base-64 encoding of the password salt, if an external salt is required. This was only needed for the `scrypt` algorithm which is now deprecated. Subject to removal. ## Examples diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index 09dcf12..be5ff34 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -2,6 +2,18 @@ title: file_server (Caddyfile directive) --- + + # file_server A static file server that supports real and virtual file systems. It forms file paths by appending the request's URI path to the [site's root path](/docs/caddyfile/directives/root). @@ -26,18 +38,27 @@ file_server [] [browse] { } ``` -- **browse** enables file listings for requests to directories that do not have an index file. -- **fs** specifies an alternate (perhaps virtual) file system to use. Any Caddy module in the `caddy.fs` namespace can be used here. Any root path/prefix will still apply to alternate file system modules. By default, the local disk is used. -- **root** sets the path to the site root. It's similar to the [`root`](/docs/caddyfile/directives/root) directive except it applies to this file server instance only and overrides any other site root that may have been defined. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this handler. For other directives (like [`try_files`](/docs/caddyfile/directives/try_files) or [`templates`](/docs/caddyfile/directives/templates)) to know the same site root, use the [`root`](/docs/caddyfile/directives/root) directive, not this subdirective. -- **hide** is a list of files or folders to hide; if requested, the file server will pretend they do not exist. Accepts placeholders and glob patterns. Note that these are _file system_ paths, NOT request paths. In other words, relative paths use the current working directory as a base, NOT the site root; and all paths are transformed to their absolute form before comparisons (if possible). Specifying a file name or pattern without a path separator will hide all files with a matching name regardless of its location; otherwise, a path prefix match will be attempted, and then a globular match. Since this is a Caddyfile config, the active configuration file(s) will be added by default. -- **index** is a list of filenames to look for as index files. Default: `index.html index.txt` -- **** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code ![external link](/resources/images/external-link.svg)](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browse.html). Browse templates can use actions from [the standard templates module](/docs/modules/http.handlers.templates#docs) as well. -- **precompressed** is the list of encoding formats to search for precompressed sidecar files. Arguments are an ordered list of encoding formats to search for precompressed [sidecar files](https://en.wikipedia.org/wiki/Sidecar_file). Supported formats are `gzip` (`.gz`), `zstd` (`.zst`) and `br` (`.br`). +- **fs** specifies an alternate (perhaps virtual) file system to use. Any Caddy module in the `caddy.fs` namespace can be used here. Any root path/prefix will still apply to alternate file system modules. By default, the local disk is used. + +- **root** sets the path to the site root. It's similar to the [`root`](/docs/caddyfile/directives/root) directive except it applies to this file server instance only and overrides any other site root that may have been defined. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this handler. For other directives (like [`try_files`](/docs/caddyfile/directives/try_files) or [`templates`](/docs/caddyfile/directives/templates)) to know the same site root, use the [`root`](/docs/caddyfile/directives/root) directive, not this subdirective. + +- **hide** is a list of files or folders to hide; if requested, the file server will pretend they do not exist. Accepts placeholders and glob patterns. Note that these are _file system_ paths, NOT request paths. In other words, relative paths use the current working directory as a base, NOT the site root; and all paths are transformed to their absolute form before comparisons (if possible). Specifying a file name or pattern without a path separator will hide all files with a matching name regardless of its location; otherwise, a path prefix match will be attempted, and then a globular match. Since this is a Caddyfile config, the active configuration file(s) will be added by default. + +- **index** is a list of filenames to look for as index files. Default: `index.html index.txt` + +- **browse** enables file listings for requests to directories that do not have an index file. + + - **** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code ![external link](/resources/images/external-link.svg)](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browse.html). Browse templates can use actions from [the standard templates module](/docs/modules/http.handlers.templates#docs) as well. + +- **precompressed** is the list of encoding formats to search for precompressed sidecar files. Arguments are an ordered list of encoding formats to search for precompressed [sidecar files](https://en.wikipedia.org/wiki/Sidecar_file). Supported formats are `gzip` (`.gz`), `zstd` (`.zst`) and `br` (`.br`). All file lookups will look for the existence of the uncompressed file first. Once found Caddy will look for sidecar files with the file extension of each enabled format. If a precompressed sidecar file is found, Caddy will respond with the precompressed file, with the `Content-Encoding` response header set appropriately. Otherwise, Caddy will respond with the uncompressed file as normal. If the [`encode` directive](/docs/caddyfile/directives/encode) is enabled, then it may compress the response on-the-fly if not precompressed. -- **status** is an optional status code override to be used when writing the response. Particularly useful when responding to a request with a custom error page. Can be a 3-digit status code, For example: `404`. Placeholders are supported. By default, the written status code will typically be `200`, or `206` for partial content. -- **disable_canonical_uris** disables the default behaviour of redirecting to add a trailing slash if the request path is a directory, or remove the trailing slash if the request path is a file. Note that by default, canonicalization will not happen if the last element of the request's path (the filename) underwent an internal rewrite, to avoid clobbering an explicit rewrite with implicit behaviour. -- **pass_thru** enables pass-thru mode, which continues to the next HTTP handler in the route if the requested file is not found, instead of returning a `404`. Practically, this is likely only be useful inside of a [`route`](/docs/caddyfile/directives/route) block, because the `file_server` directive is effectively [ordered last](/docs/caddyfile/directives#directive-order) otherwise. + +- **status** is an optional status code override to be used when writing the response. Particularly useful when responding to a request with a custom error page. Can be a 3-digit status code, For example: `404`. Placeholders are supported. By default, the written status code will typically be `200`, or `206` for partial content. + +- **disable_canonical_uris** disables the default behaviour of redirecting to add a trailing slash if the request path is a directory, or remove the trailing slash if the request path is a file. Note that by default, canonicalization will not happen if the last element of the request's path (the filename) underwent an internal rewrite, to avoid clobbering an explicit rewrite with implicit behaviour. + +- **pass_thru** enables pass-thru mode, which continues to the next HTTP handler in the route if the requested file is not found, instead of returning a `404`. Practically, this is likely only be useful inside of a [`route`](/docs/caddyfile/directives/route) block, because the `file_server` directive is effectively [ordered last](/docs/caddyfile/directives#directive-order) otherwise. ## Examples diff --git a/src/docs/markdown/caddyfile/directives/log.md b/src/docs/markdown/caddyfile/directives/log.md index f5661ba..3ab02c1 100644 --- a/src/docs/markdown/caddyfile/directives/log.md +++ b/src/docs/markdown/caddyfile/directives/log.md @@ -22,6 +22,9 @@ If you're looking to configure Caddy's runtime logs, you're looking for the [`lo The `log` directive applies to the host/port of the site block it appears in, not any other part of the site address (e.g. path). +When configured, by default all requests to the site will be logged. To conditionally skip some requests from logging, use the [`skip_log` directive](/docs/caddyfile/directives/skip_log). + + - [Syntax](#syntax) - [Output modules](#output-modules) - [stderr](#stderr) diff --git a/src/docs/markdown/caddyfile/directives/php_fastcgi.md b/src/docs/markdown/caddyfile/directives/php_fastcgi.md index 1bcf918..996ec70 100644 --- a/src/docs/markdown/caddyfile/directives/php_fastcgi.md +++ b/src/docs/markdown/caddyfile/directives/php_fastcgi.md @@ -2,6 +2,13 @@ title: php_fastcgi (Caddyfile directive) --- + + # php_fastcgi An opinionated directive that proxies requests to a PHP FastCGI server such as php-fpm. @@ -32,21 +39,33 @@ php_fastcgi [] { dial_timeout read_timeout write_timeout + capture_stderr } ``` - **** are the [addresses](/docs/conventions#network-addresses) of the FastCGI servers. -- **root** sets the root folder to the site. Default: [`root` directive](/docs/caddyfile/directives/root). -- **split** sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the "path info" from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the CGI script to use. Default: `.php` -- **env** sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables. -- **index** specifies the filename to treat as the directory index file. This affects the file matcher in the [expanded form](#expanded-form). Default: `index.php`. Can be set to `off` to disable rewriting to `index.php` when a matching file is not found. -- **try_files** specifies an override for the default try-files rewrite. See the [`try_files` directive](/docs/caddyfile/directives/try_files) for details. Default: `{path} {path}/index.php index.php`. -- **resolve_root_symlink** enables resolving the `root` directory to its actual value by evaluating a symbolic link, if one exists. -- **dial_timeout** is how long to wait when connecting to the upstream socket. Accepts [duration values](/docs/conventions#durations). Default: `3s`. -- **read_timeout** is how long to wait when reading from the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. -- **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. + +- **root** sets the root folder to the site. Default: [`root` directive](/docs/caddyfile/directives/root). + +- **split** sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the "path info" from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the CGI script to use. Default: `.php` + +- **env** sets an extra environment variable to the given value. Can be specified more than once for multiple environment variables. + +- **index** specifies the filename to treat as the directory index file. This affects the file matcher in the [expanded form](#expanded-form). Default: `index.php`. Can be set to `off` to disable rewriting to `index.php` when a matching file is not found. + +- **try_files** specifies an override for the default try-files rewrite. See the [`try_files` directive](/docs/caddyfile/directives/try_files) for details. Default: `{path} {path}/index.php index.php`. + +- **resolve_root_symlink** enables resolving the `root` directory to its actual value by evaluating a symbolic link, if one exists. + +- **dial_timeout** is how long to wait when connecting to the upstream socket. Accepts [duration values](/docs/conventions#durations). Default: `3s`. + +- **read_timeout** is how long to wait when reading from the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. + +- **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. + +- **capture_stderr** enables capturing and logging of any messages sent by the upstream fastcgi server on `stderr`. Logging is done at `WARN` level by default. If the response has a `4xx` or `5xx` status, then the `ERROR` level will be used instead. By default, `stderr` is ignored. Since this directive is an opinionated wrapper over a reverse proxy, you can use any of [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy#syntax)'s subdirectives to customize it. @@ -63,14 +82,14 @@ route { file {path}/index.php not path */ } - redir @canonicalPath {path}/ 308 + redir @canonicalPath {http.request.orig_uri.path}/ 308 # If the requested file does not exist, try index files @indexFiles file { try_files {path} {path}/index.php index.php split_path .php } - rewrite @indexFiles {http.matchers.file.relative} + rewrite @indexFiles {file_match.relative} # Proxy PHP files to the FastCGI responder @phpFiles path *.php diff --git a/src/docs/markdown/caddyfile/directives/respond.md b/src/docs/markdown/caddyfile/directives/respond.md index 01358cc..2e7d5c5 100644 --- a/src/docs/markdown/caddyfile/directives/respond.md +++ b/src/docs/markdown/caddyfile/directives/respond.md @@ -19,8 +19,11 @@ respond [] | [] { ``` - **<status>** is the HTTP status code to write. If 103 (Early Hints), the response will be written without a body and the handler chain will continue. (HTTP 1xx responses are informational, not final.) Default: 200. + - **<body>** is the response body to write. + - **body** is an alternate way to provide a body; convenient if it is multiple lines. + - **close** will close the client's connection to the server after writing the response. To clarify, the first non-matcher argument can be either a 3-digit status code or a response body string. If it is a body, the next argument can be the status code. diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 7ea2299..802d083 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -59,8 +59,10 @@ reverse_proxy [] [] { # load balancing lb_policy [] + lb_retries lb_try_duration lb_try_interval + lb_retry_match # active health checking health_uri @@ -217,6 +219,9 @@ Append the results of multiple dynamic upstream modules. Useful if you want redu - **<source>** is the name of the module for the dynamic upstreams, followed by its configuration. More than one may be specified. + + + ### Load balancing Load balancing is used whenever more than one upstream is defined. @@ -256,9 +261,19 @@ Load balancing is used whenever more than one upstream is defined. document.cookie = "lb=cdd96966817dd14a99f47ee17451464f29998da170814a16b483e4c1ff4c48cf"; ``` -- **lb_try_duration** is a [duration value](/docs/conventions#durations) that defines how long to try selecting available backends for each request if the next available host is down. By default, this retry is disabled. Clients will wait for up to this long while the load balancer tries to find an available upstream host. A reasonable starting point might be `5s` since the HTTP transport's default dial timeout is `3s`, so that should allow for at least one retry if the first selected upstream cannot be reached; but feel free to experiment to find the right balance for your usecase. +- **lb_retries** is how many times to retry selecting available backends for each request if the next available host is down. By default, retries are disabled (zero). -- **lb_try_interval** is a [duration value](/docs/conventions#durations) that defines how long to wait between selecting the next host from the pool. Default is `250ms`. Only relevant when a request to an upstream host fails. Be aware that setting this to 0 with a non-zero `lb_try_duration` can cause the CPU to spin if all backends are down and latency is very low. + If [`lb_try_duration`](#lb_try_duration) is also configured, then retries may stop early if the duration is reached. In other words, the retry duration takes precedence over the retry count. + +- **lb_try_duration** is a [duration value](/docs/conventions#durations) that defines how long to try selecting available backends for each request if the next available host is down. By default, retries are disabled (zero duration). + + Clients will wait for up to this long while the load balancer tries to find an available upstream host. A reasonable starting point might be `5s` since the HTTP transport's default dial timeout is `3s`, so that should allow for at least one retry if the first selected upstream cannot be reached; but feel free to experiment to find the right balance for your usecase. + +- **lb_try_interval** is a [duration value](/docs/conventions#durations) that defines how long to wait between selecting the next host from the pool. Default is `250ms`. Only relevant when a request to an upstream host fails. Be aware that setting this to `0` with a non-zero `lb_try_duration` can cause the CPU to spin if all backends are down and latency is very low. + +- **lb_retry_match** restricts with which requests retries are allowed. A request must match this condition in order to be retried if the connection to the upstream succeded but the subsequent round-trip failed. If the connection to the upstream failed, a retry is always allowed. By default, only `GET` requests are retried. + + The syntax for this option is the same as for [named request matchers](/docs/caddyfile/matchers#named-matchers), but without the `@name`. If you only need a single matcher, you may configure it on the same line. For multiple matchers, a block is necessary. @@ -518,6 +533,7 @@ transport fastcgi { dial_timeout read_timeout write_timeout + capture_stderr } ``` @@ -535,6 +551,8 @@ transport fastcgi { - **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. +- **capture_stderr** enables capturing and logging of any messages sent by the upstream fastcgi server on `stderr`. Logging is done at `WARN` level by default. If the response has a `4xx` or `5xx` status, then the `ERROR` level will be used instead. By default, `stderr` is ignored. + -Upon matching, two new placeholders will be made available: +Upon matching, four new placeholders will be made available: + +- `{file_match.relative}` The root-relative path of the file. This is often useful when rewriting requests. +- `{file_match.absolute}` The absolute path of the matched file, including the root. +- `{file_match.type}` The type of file, `file` or `directory`. +- `{file_match.remainder}` The portion remaining after splitting the file path (if `split_path` is configured) -- `{http.matchers.file.relative}` The root-relative path of the file. This is often useful when rewriting requests. -- `{http.matchers.file.absolute}` The absolute path of the matched file. #### Examples: diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index c790d9f..ab84a9b 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -200,7 +200,7 @@ How often to check if OCSP staples need updating. Default: `1h`. ##### `admin` -Customizes the [admin API endpoint](/docs/api). If `off`, then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server. +Customizes the [admin API endpoint](/docs/api). Accepts placeholders. If `off`, then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server. - **origins** configures the list of remotes/origins that are allowed to connect to the endpoint. @@ -336,9 +336,7 @@ For example, to configure different options for the servers on ports `:80` and ` } servers :80 { - protocols { - allow_h2c - } + protocols h1 h2c } } ``` @@ -401,18 +399,27 @@ If you wish to _not_ have these headers redacted, you may enable the `log_creden ##### `protocols` -The space-separated list of HTTP protocols to support. Accepted values are: `h1 h2 h2c h3` for HTTP/1.1, HTTP/2, HTTP/2 over cleartext, and HTTP/3, respectively. Default: `h1 h2 h3`. +The space-separated list of HTTP protocols to support. Default: `h1 h2 h3`. Accepted values are: + +- `h1` for HTTP/1.1 +- `h2` For HTTP/2 +- `h2c` for HTTP/2 over cleartext +- `h3` for HTTP/3 Currently, enabling HTTP/2 (including H2C) necessarily implies enabling HTTP/1.1 because the Go standard library does not let us disable HTTP/1.1 when using its HTTP server. However, either HTTP/1.1 or HTTP/3 can be enabled independently. Note that H2C ("Cleartext HTTP/2" or "H2 over TCP") and HTTP/3 are not implemented by the Go standard library, so some functionality or features may be limited. We recommend against enabling H2C unless it is absolutely necessary for your application. + ##### `strict_sni_host` Enabling this requires that a request's `Host` header matches the value of the `ServerName` sent by the client's TLS ClientHello, a necessary safeguard when using TLS client authentication. If there's a mismatch, HTTP status `421 Misdirected Request` response is written to the client. This option will automatically be turned on if [client authentication](/docs/caddyfile/directives/tls#client_auth) is configured. This disallows TLS client auth bypass (domain fronting) which could otherwise be exploited by sending an unprotected SNI value during a TLS handshake, then putting a protected domain in the Host header after establishing connection. This behavior is a safe default, but you may explicitly turn it off with `insecure_off`; for example in the case of running a proxy where domain fronting is desired and access is not restricted based on hostname. + + + ## PKI Options The PKI (Public Key Infrastructure) app is the foundation for Caddy's [Local HTTPS](/docs/automatic-https#local-https) and [ACME server](/docs/caddyfile/directives/acme_server) features. The app defines certificate authorities (CAs) which are capable of signing certificates. diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 559da7a..03c5a93 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -383,7 +383,7 @@ Spins up a simple but production-ready HTTP(S) reverse proxy. `--from` is the address to proxy from. -`--to` is the address to proxy to. +`--to` is the address(es) to proxy to. Can be repeated to load balance between multiple upstreams. `--change-host-header` will cause Caddy to change the Host header from the incoming value to the address of the upstream. @@ -591,4 +591,4 @@ Code | Meaning `2` | Forced quit. Caddy was forced to exit without cleaning up resources. `3` | Failed quit. Caddy exited with some errors during cleanup. -In bash, you can get the exit code of the last command with `echo $?`. \ No newline at end of file +In bash, you can get the exit code of the last command with `echo $?`.