Update docs for 2.6

src/docs/markdown/caddyfile/concepts.md

@@ -231,38 +231,40 @@ Matcher tokens can be omitted entirely to match all requests; for example, `*` d
 
 You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Caddyfile, but for convenience you can also use some equivalent shorthand ones:
 
-| Shorthand       | Replaces                        |
+| Shorthand       | Replaces                          |
-|-----------------|---------------------------------|
+|-----------------|-----------------------------------|
-| `{dir}`         | `{http.request.uri.path.dir}`   |
+| `{cookie.*}`    | `{http.request.cookie.*}`         |
-| `{file}`        | `{http.request.uri.path.file}`  |
+| `{dir}`         | `{http.request.uri.path.dir}`     |
-| `{header.*}`    | `{http.request.header.*}`       |
+| `{err.*}`       | `{http.error.*}`                  |
-| `{host}`        | `{http.request.host}`           |
+| `{file}`        | `{http.request.uri.path.file}`    |
-| `{labels.*}`    | `{http.request.host.labels.*}`  |
+| `{file.*}`      | `{http.request.uri.path.file.*}`  |
-| `{hostport}`    | `{http.request.hostport}`       |
+| `{header.*}`    | `{http.request.header.*}`         |
-| `{port}`        | `{http.request.port}`           |
+| `{host}`        | `{http.request.host}`             |
-| `{method}`      | `{http.request.method}`         |
+| `{labels.*}`    | `{http.request.host.labels.*}`    |
-| `{path}`        | `{http.request.uri.path}`       |
+| `{hostport}`    | `{http.request.hostport}`         |
-| `{path.*}`      | `{http.request.uri.path.*}`     |
+| `{port}`        | `{http.request.port}`             |
-| `{query}`       | `{http.request.uri.query}`      |
+| `{method}`      | `{http.request.method}`           |
-| `{query.*}`     | `{http.request.uri.query.*}`    |
+| `{path}`        | `{http.request.uri.path}`         |
-| `{re.*.*}`      | `{http.regexp.*.*}`             |
+| `{path.*}`      | `{http.request.uri.path.*}`       |
-| `{remote}`      | `{http.request.remote}`         |
+| `{query}`       | `{http.request.uri.query}`        |
-| `{remote_host}` | `{http.request.remote.host}`    |
+| `{query.*}`     | `{http.request.uri.query.*}`      |
-| `{remote_port}` | `{http.request.remote.port}`    |
+| `{re.*.*}`      | `{http.regexp.*.*}`               |
-| `{scheme}`      | `{http.request.scheme}`         |
+| `{remote}`      | `{http.request.remote}`           |
-| `{uri}`         | `{http.request.uri}`            |
+| `{remote_host}` | `{http.request.remote.host}`      |
+| `{remote_port}` | `{http.request.remote.port}`      |
+| `{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_pem}`        | `{http.request.tls.client.certificate_pem}`        |
 | `{tls_client_certificate_der_base64}` | `{http.request.tls.client.certificate_der_base64}` |
+| `{uri}` | `{http.request.uri}` |
 | `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` |
-| `{rp.*}` | `{http.reverse_proxy.*}` |
 | `{vars.*}` | `{http.vars.*}` |
-| `{err.*}` | `{http.error.*}` |
 
 
 

src/docs/markdown/caddyfile/directives.md

@@ -9,7 +9,7 @@ title: Caddyfile Directives
 }
 
 #directive-table tr:hover {
-	background: rgba(0, 0, 0, 10%);
+	background: rgba(109, 226, 255, 0.11);
 }
 
 #directive-table tr td:first-child {

src/docs/markdown/caddyfile/directives/basicauth.md

@@ -19,15 +19,15 @@ After a successful authentication, the `{http.auth.user.id}` placeholder will be
 
 ```caddy-d
 basicauth [<matcher>] [<hash_algorithm> [<realm>]] {
-	<username> <hashed_password_base64> [<salt_base64>]
+	<username> <hashed_password> [<salt_base64>]
 	...
 }
 ```
 
-- **&lt;hash_algorithm&gt;** is the name of the password hashing algorithm (or KDF) used for the hashes in this configuration. Can be `bcrypt` (default) or `scrypt`.
+- **&lt;hash_algorithm&gt;** is the name of the password hashing algorithm (or KDF) used for the hashes in this configuration. Default: `bcrypt`
 - **&lt;realm&gt;** is a custom realm name.
 - **&lt;username&gt;** is a username or user ID.
-- **&lt;hashed_password_base64&gt;** is the base-64 encoding of the hashed password.
+- **&lt;hashed_password&gt;** is the password hash.
 - **&lt;salt_base64&gt;** is the base-64 encoding of the password salt, if an external salt is required.
 
 
@@ -37,7 +37,7 @@ Protect all resources in /secret so only Bob can access them with the password "
 
 ```caddy-d
 basicauth /secret/* {
-	Bob JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
+	Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
 }
 ```
 

src/docs/markdown/caddyfile/directives/file_server.md

@@ -8,7 +8,7 @@ A static file server that supports real and virtual file systems. It forms file
 
 By default, it enforces canonical URIs; meaning HTTP redirects will be issued for requests to directories that do not end with a trailing slash (to add it) or requests to files that have a trailing slash (to remove it). Redirects are not issued, however, if an internal rewrite modifies the last element of the path (the filename).
 
-Most often, the `file_server` directive is paired with the [`root`](/docs/caddyfile/directives/root) directive to set file root for the whole site. A site root does not carry sandbox guarantees: the file server does prevent directory traversal, but symbolic links within the root can still allow accesses outside of the root.
+Most often, the `file_server` directive is paired with the [`root`](/docs/caddyfile/directives/root) directive to set the file root for the whole site, but this directive also has a `root` subdirective (below) to set the root only for this handler if preferred. Note that a site root does not carry sandbox guarantees: the file server does prevent directory traversal from path components, but symbolic links within the root can still allow accesses outside of the root.
 
 ## Syntax
 
@@ -27,8 +27,8 @@ file_server [<matcher>] [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 as long as it supports [`Stat()` calls](https://pkg.go.dev/io/fs#StatFS). Any root path/prefix will still apply to alternate file system modules. By default, the local disk is used.
+- **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 directive. 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.
+- **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`
 - **<template_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.
@@ -53,7 +53,7 @@ With file listings enabled:
 file_server browse
 ```
 
-Only serve static files out of the `/static` folder:
+Only serve static files within the `/static` folder:
 
 ```caddy-d
 file_server /static/*

src/docs/markdown/caddyfile/directives/respond.md

@@ -6,6 +6,8 @@ title: respond (Caddyfile directive)
 
 Writes a hard-coded/static response to the client.
 
+If the body is non-empty, this directive sets the `Content-Type` header if it is not already set. The default value is `text/plain; utf-8` unless the body is a valid JSON object or array, in which case it is set to `application/json`. For all other types of content, set the proper Content-Type explicitly using the [`header` directive](/docs/caddyfile/directives/header).
+
 
 ## Syntax
 
@@ -16,7 +18,7 @@ respond [<matcher>] <status>|<body> [<status>] {
 }
 ```
 
-- **&lt;status&gt;** is the HTTP status code to write. Default 200.
+- **&lt;status&gt;** 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.
 - **&lt;body&gt;** 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.

src/docs/markdown/caddyfile/directives/reverse_proxy.md

@@ -34,6 +34,7 @@ Proxies requests to one or more backends with configurable transport, load balan
   - [Dynamic upstreams](#dynamic-upstreams)
     - [SRV](#srv)
     - [A/AAAA](#aaaaa)
+	- [Multi](#multi)
 - [Load balancing](#load-balancing)
   - [Active health checks](#active-health-checks)
   - [Passive health checks](#passive-health-checks)
@@ -138,6 +139,7 @@ Static upstream addresses can take the form of a conventional [Caddy network add
 - `h2c://127.0.0.1`
 - `example.com`
 - `unix//var/php.sock`
+- `unix+h2c//var/grpc.sock`
 
 Note: Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport.
 
@@ -203,6 +205,17 @@ Retrieves upstreams from A/AAAA DNS records.
 - **dial_fallback_delay** is how long to wait before spawning an RFC 6555 Fast Fallback connection. Default: `300ms`
 
 
+##### Multi
+
+Append the results of multiple dynamic upstream modules. Useful if you want redundant sources of upstreams, for example: a primary cluster of SRVs backed up by a secondary cluster of SRVs.
+
+```caddy-d
+	dynamic multi {
+		<source> [...]
+	}
+```
+
+- **&lt;source&gt;** is the name of the module for the dynamic upstreams, followed by its configuration. More than one may be specified.
 
 ### Load balancing
 
@@ -441,13 +454,17 @@ transport http {
 
 - **max_response_header** <span id="max_response_header"/> is the maximum amount of bytes to read from response headers. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go). Default: `10MiB`.
 
-- **dial_timeout** <span id="dial_timeout"/> is how long to wait when connecting to the upstream socket. Accepts [duration values](/docs/conventions#durations). Default: No timeout.
+- **dial_timeout** <span id="dial_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait when connecting to the upstream socket. Default: No timeout.
 
-- **dial_fallback_delay** <span id="dial_fallback_delay"/> is how long to wait before spawning an RFC 6555 Fast Fallback connection. A negative value disables this. Accepts [duration values](/docs/conventions#durations). Default: `300ms`.
+- **dial_fallback_delay** <span id="dial_fallback_delay"/> is the maximum [duration](/docs/conventions#durations) to wait before spawning an RFC 6555 Fast Fallback connection. A negative value disables this. Default: `300ms`.
 
-- **response_header_timeout** <span id="response_header_timeout"/> is how long to wait for reading response headers from the upstream. Accepts [duration values](/docs/conventions#durations). Default: No timeout.
+- **response_header_timeout** <span id="response_header_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait for reading response headers from the upstream. Default: No timeout.
 
-- **expect_continue_timeout** <span id="expect_continue_timeout"/> is how long to wait for the upstreams's first response headers after fully writing the request headers if the request has the header `Expect: 100-continue`. Accepts [duration values](/docs/conventions#durations). Default: No timeout.
+- **expect_continue_timeout** <span id="expect_continue_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait for the upstreams's first response headers after fully writing the request headers if the request has the header `Expect: 100-continue`. Default: No timeout.
+
+- **read_timeout** <span id="read_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait for the next read from the backend. Default: No timeout.
+
+- **write_timeout** <span id="write_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait for the next writes to the backend. Default: No timeout.
 
 - **resolvers** <span id="resolvers"/> is a list of DNS resolvers to override system resolvers.
 
@@ -457,7 +474,7 @@ transport http {
 
 - **tls_insecure_skip_verify** <span id="tls_insecure_skip_verify"/> turns off TLS handshake verification, making the connection insecure and vulnerable to man-in-the-middle attacks. _Do not use in production._
 
-- **tls_timeout** <span id="tls_timeout"/> is a [duration value](/docs/conventions#durations) that specifies how long to wait for the TLS handshake to complete. Default: No timeout.
+- **tls_timeout** <span id="tls_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait for the TLS handshake to complete. Default: No timeout.
 
 - **tls_trusted_ca_certs** <span id="tls_trusted_ca_certs"/> is a list of PEM files that specify CA public keys to trust when connecting to the backend.
 
@@ -476,7 +493,7 @@ transport http {
 
 - **keepalive** <span id="keepalive"/> is either `off` or a [duration value](/docs/conventions#durations) that specifies how long to keep connections open (timeout). Default: `2m`.
 
-- **keepalive_interval** <span id="keepalive"/> is a [duration value](/docs/conventions#durations) that specifies how often to probe for liveness. Default: `30s`.
+- **keepalive_interval** <span id="keepalive"/> is the [duration](/docs/conventions#durations) between liveness probes. Default: `30s`.
 
 - **keepalive_idle_conns** <span id="keepalive_idle_conns"/> defines the maximum number of connections to keep alive. Default: No limit.
 

src/docs/markdown/caddyfile/directives/try_files.md

@@ -10,10 +10,13 @@ Rewrites the request URI path to the first of the listed files which exists in t
 ## Syntax
 
 ```caddy-d
-try_files <files...>
+try_files <files...> {
+	policy first_exist|smallest_size|largest_size|most_recently_modified
+}
 ```
 
-- **<files...>** is the list of files to try. The URI will be rewritten to the first one that exists. To match directories, append a trailing forward slash `/` to the path. All file paths are relative to the site [root](/docs/caddyfile/directives/root). Each argument may also contain a query string, in which case the query string will also be changed if it matches that particular file. The last item in the list may be a number prefixed by `=` (e.g. `=404`), which as a fallback, will emit an error with that code; the error can be caught and handled with [`handle_errors`](/docs/caddyfile/directives/handle_errors).
+- **<files...>** is the list of files to try. The URI path will be rewritten to the first one that exists. To match directories, append a trailing forward slash `/` to the path. All file paths are relative to the site [root](/docs/caddyfile/directives/root), and [glob patterns](https://pkg.go.dev/path/filepath#Match) will be expanded. Each argument may also contain a query string, in which case the query string will also be changed if it matches that particular file. The last item in the list may be a number prefixed by `=` (e.g. `=404`), which as a fallback, will emit an error with that code; the error can be caught and handled with [`handle_errors`](/docs/caddyfile/directives/handle_errors).
+- **policy** is the policy for choosing the file among the list of files. Default: `first_exist`
 
 
 ## Expanded form
@@ -55,3 +58,11 @@ Attempt to rewrite to a file or directory if it exists, otherwise emit a 404 err
 ```caddy-d
 try_files {path} {path}/ =404
 ```
+
+Choose the most recently deployed version of a static file (e.g. serve `index.be331df.html` when `index.html` is requested):
+
+```caddy-d
+try_files {file.base}.*.{file.ext} {
+	policy most_recently_modified
+}
+```

src/docs/markdown/caddyfile/matchers.md

@@ -120,7 +120,7 @@ redir /old.html /new.html
 
 Path matcher tokens must start with a forward slash `/`.
 
-**[Path matching](/docs/caddyfile/matchers#path) is an exact match by default, not a prefix match.** You must append a `*` for a fast prefix match. Note that `/foo*` will match `/foo` and `/foo/` as well as `/foobar`; you might actually want `/foo/*` instead.
+**[Path matching](#path) is an exact match by default, not a prefix match.** You must append a `*` for a fast prefix match. Note that `/foo*` will match `/foo` and `/foo/` as well as `/foobar`; you might actually want `/foo/*` instead.
 
 
 ### Named matchers
@@ -162,6 +162,12 @@ If the matcher set consists of only one matcher, a one-liner syntax also works:
 reverse_proxy @post localhost:6001
 ```
 
+As a special case, the [`expression` matcher](#expression) may be used without specifying its name as long as a single quoted argument (the CEL expression itself) follows the matcher name:
+
+```caddy-d
+@notFound `{err.status_code} == 404`
+```
+
 Like directives, named matcher definitions must go inside the site blocks that use them.
 
 A named matcher definition constitutes a _matcher set_. Matchers in a set are AND'ed together; i.e. all must match. For example, if you have both a `header` and `path` matcher in the set, both must match.
@@ -176,7 +182,7 @@ Multiple matchers of the same type may be unioned (e.g. multiple `path` matchers
 
 Full matcher documentation can be found [in each respective matcher module's docs](/docs/json/apps/http/servers/routes/match/).
 
-
+Requests can be matched the following ways:
 
 ### expression
 
@@ -188,7 +194,15 @@ By any [CEL (Common Expression Language)](https://github.com/google/cel-spec) ex
 
 Caddy [placeholders](/docs/conventions#placeholders) (or [Caddyfile shorthands](/docs/caddyfile/concepts#placeholders)) may be used in these CEL expressions, as they are preprocessed and converted to regular CEL function calls before being interpreted by the CEL environment.
 
-Since v2.5.2, most other request matchers can also be used in expressions as functions, which allows for more flexibility for boolean logic than outside expressions. See the documentation for each other matcher for the supported syntax within CEL expressions.
+Since v2.5.2, most other request matchers can also be used in expressions as functions, which allows for more flexibility for boolean logic than outside expressions. See the documentation for each matcher for the supported syntax within CEL expressions.
+
+For convenience, the matcher name may be omitted if defining a named matcher that consists solely of a CEL expression. This reads quite nicely:
+
+```caddy-d
+@mutable `{method}.startsWith("P")`
+```
+
+In this case the CEL matcher is assumed.
 
 #### Examples:
 
@@ -479,7 +493,7 @@ Slashes are significant. For example, `/foo*` will match `/foo`, `/foobar`, `/fo
 
 Request paths are cleaned to resolve directory traversal dots before matching. Additionally, multiple slashes are merged unless the match pattern has multiple slashes. In other words, `/foo` will match `/foo` and `//foo`, but `//foo` will only match `//foo`.
 
-The request path is normalized (URL-decoded, unescaped) except for escape sequences at positions where escape sequences are also present in the match pattern. For example, `/foo/bar` matches both `/foo/bar` and `/foo%2Fbar`, but `/foo%2Fbar` will match only `/foo%2Fbar`.
+Because there are multiple escaped forms of any given URI, the request path is normalized (URL-decoded, unescaped) except for those escape sequences at positions where escape sequences are also present in the match pattern. For example, `/foo/bar` matches both `/foo/bar` and `/foo%2Fbar`, but `/foo%2Fbar` will match only `/foo%2Fbar`, because the escape sequence is explicitly given in the configuration.
 
 The special wildcard escape `%*` can also be used instead of `*` to leave its matching span escaped. For example, `/bands/*/*` will not match `/bands/AC%2FDC/T.N.T` because the path will be compared in normalized space where it looks like `/bands/AC/DC/T.N.T`, which does not match the pattern; however, `/bands/%*/*` will match `/bands/AC%2FDC/T.N.T` because the span represented by `%*` will be compared without decoding escape sequences.
 
@@ -598,11 +612,13 @@ vars <variable> <values...>
 
 By the value of a variable in the request context, or the value of a placeholder. Multiple values may be specified to match any of those possible values (OR'ed).
 
+The **&lt;variable&gt;** argument may be either a variable name or a placeholder in curly braces `{ }`. (Placeholders are not expanded in the first parameter.)
+
 This matcher is most useful when paired with the [`map` directive](/docs/caddyfile/directives/map) which sets outputs, or with plugins which set some information in the request context.
 
 #### Example:
 
-Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for the values `3`, or `5`:
+Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for the values `3` or `5`:
 
 ```caddy-d
 vars {magic_number} 3 5

src/docs/markdown/caddyfile/options.md

@@ -29,7 +29,7 @@ $(function() {
 
 # Global options
 
-The Caddyfile has a way for you to specify options that apply globally. Some options act as default values, while others customize the behavior of the Caddyfile [adapter](/docs/config-adapters).
+The Caddyfile has a way for you to specify options that apply globally. Some options act as default values; others customize HTTP servers and don't apply to just one particular site; while yet others customize the behavior of the Caddyfile [adapter](/docs/config-adapters).
 
 The very top of your Caddyfile can be a **global options block**. This is a block that has no keys:
 
@@ -56,7 +56,7 @@ Possible options are:
 	}
 	storage_clean_interval <duration>
 	renew_interval <duration>
-	ocsp_interval <duration>
+	ocsp_interval  <duration>
 	admin   off|<addr> {
 		origins <origins...>
 		enforce_origin
@@ -68,7 +68,8 @@ Possible options are:
 		include <namespaces...>
 		exclude <namespaces...>
 	}
-	grace_period <duration>
+	grace_period   <duration>
+	shutdown_delay <duration>
 
 	# TLS Options
 	auto_https off|disable_redirects|ignore_loaded_certs|disable_certs
@@ -106,11 +107,8 @@ Possible options are:
 		}
 		max_header_size <size>
 		log_credentials
-		protocol {
+		protocols [h1|h2|h2c|h3]
-			allow_h2c
+		strict_sni_host [on|insecure_off]
-			experimental_http3
-			strict_sni_host [on|insecure_off]
-		}
 	}
 
 	# PKI Options
@@ -131,6 +129,11 @@ Possible options are:
 			}
 		}
 	}
+
+	# Event options
+	events {
+		on <event> <handler...>
+	}
 }
 ```
 
@@ -192,7 +195,7 @@ How often to scan all loaded, managed certificates for expiration, and trigger r
 
 
 ##### `ocsp_interval`
-How often to check if OCSP stapling needs updating. Default: `1h`.
+How often to check if OCSP staples need updating. Default: `1h`.
 
 
 ##### `admin`
@@ -211,14 +214,25 @@ The differs from the [`log` directive](/docs/caddyfile/directives/log), which on
 - **output** configures where to write the logs. See the [`log` directive](/docs/caddyfile/directives/log#output-modules) for complete documentation.
 - **format** describes how to encode, or format, the logs. See the [`log` directive](/docs/caddyfile/directives/log#format-modules) for complete documentation.
 - **level** is the minimum entry level to log. Default: `INFO`.
-- **include** specifies the log names to be included in this logger. For example, to include only logs emitted by the admin API, you would include `admin.api`.
+- **include** specifies the log names to be included in this logger. For example, to include only logs emitted by the admin API, you would include `admin.api`. By default, all logs are included.
-- **exclude** specifies the log names to be excluded from this logger. For example, to exclude only HTTP access logs, you would exclude `http.log.access`.
+- **exclude** specifies the log names to be excluded from this logger. For example, to exclude only HTTP access logs, you would exclude `http.log.access`. By default, no logs are excluded.
 
 
 ##### `grace_period`
-Defines the grace period for shutting down HTTP servers during config reloads. If clients do not finish their requests within the grace period, the server will be forcefully terminated to allow the reload to complete and free up resources. By default, no grace period is set.
+Defines the grace period for shutting down HTTP servers during config changes. During the grace period, no new connections are accepted, idle connections are closed, and active connections are impatiently waited upon to finish their requests. If clients do not finish their requests within the grace period, the server will be forcefully terminated to allow the reload to complete and free up resources. By default, no grace period is set.
 
 
+##### `shutdown_delay`
+Defines a duration before the grace period during which a server that is going to be stopped continues to operate normally, except the `{http.shutting_down}` placeholder evaluates to `true` and `{http.time_until_shutdown}` gives the time until the grace period begins. This causes a delay if any server is being shut down as part of a config change and effectively schedules the change for a later time. It is useful for announcing to health checkers of this server's impending doom and to give time for a load balancer to move it out of the rotation; for example:
+
+```caddy-d
+handle /health-check {
+	@goingDown vars {http.shutting_down} true
+	respond @goingDown "Bye-bye in {http.time_until_shutdown}" 503
+	respond 200
+}
+```
+
 
 ## TLS Options
 
@@ -298,9 +312,9 @@ Note that specifying `preferred_chains` as a global option will affect all issue
 
 ## Server Options
 
-Customizes [HTTP servers](/docs/json/apps/http/servers/) with settings that potentially span multiple sites and thus can't be rightly configured in site blocks. These options affect the listener/socket, or other behavior beneath the HTTP layer.
+Customizes [HTTP servers](/docs/json/apps/http/servers/) with settings that potentially span multiple sites and thus can't be rightly configured in site blocks. These options affect the listener/socket or other facilities beneath the HTTP layer.
 
-Can be specified more than once, with different `listener_address` values, to configure different options per server. For example, `servers :443` will only apply to the server that is bound to the listener address `:443`. Omitting the listener address will apply the options to any remaining server.
+Can be specified more than once with different `listener_address` values to configure different options per server. For example, `servers :443` will only apply to the server that is bound to the listener address `:443`. Omitting the listener address will apply the options to any remaining server.
 
 <aside class="tip">
 
@@ -309,18 +323,19 @@ Use the [`caddy adapt`](/docs/command-line#caddy-adapt) command to find the list
 </aside>
 
 
-For example, to configure different options for the servers on port `:80` and `:443`, you would specify two `servers` blocks:
+For example, to configure different options for the servers on ports `:80` and `:443`, you would specify two `servers` blocks:
 
 ```caddy
 {
 	servers :443 {
-		protocol {
+		listener_wrappers {
-			experimental_http3
+			http_redirect
+			tls
 		}
 	}
 
 	servers :80 {
-		protocol {
+		protocols {
 			allow_h2c
 		}
 	}
@@ -329,11 +344,11 @@ For example, to configure different options for the servers on port `:80` and `:
 
 ##### `listener_wrappers`
 
-Allows configuring [listener wrappers](/docs/json/apps/http/servers/listener_wrappers/), which can modify the behaviour of the base listener. They are applied in the given order.
+Allows configuring [listener wrappers](/docs/json/apps/http/servers/listener_wrappers/), which can modify the behaviour of the socket listener. They are applied in the given order.
 
 There is a special no-op [`tls`](/docs/json/apps/http/servers/listener_wrappers/tls/) listener wrapper provided as a standard module which marks where TLS should be handled in the chain of listener wrappers. It should only be used if another listener wrapper must be placed in front of the TLS handshake.
 
-The standard distribution of Caddy includes an [`http_redirect`](/docs/json/apps/http/servers/listener_wrappers/http_redirect/) listener wrapper, which can look at the first few bytes of an incoming request to determine if it's HTTP (instead of TLS), and trigger an HTTP->HTTPS redirect on the same port with the `https://` scheme. It must be placed _before_ the `tls` listener wrapper. For example:
+The standard distribution of Caddy includes the [`http_redirect`](/docs/json/apps/http/servers/listener_wrappers/http_redirect/) listener wrapper, which can look at the first few bytes of an incoming request to determine if it's likely HTTP (instead of TLS), and trigger an HTTP->HTTPS redirect on the same port but using the `https://` scheme. It must be placed _before_ the `tls` listener wrapper. For example:
 
 ```caddy-d
 listener_wrappers {
@@ -378,17 +393,19 @@ Since Caddy v2.5, by default, headers with potentially sensitive information (`C
 If you wish to _not_ have these headers redacted, you may enable the `log_credentials` option.
 
 
-##### `protocol`
+##### `protocols`
 
-- **allow_h2c** enables H2C ("Cleartext HTTP/2" or "H2 over TCP") support, which will serve HTTP/2 over plaintext TCP connections if a client support it. Because this is not implemented by the Go standard library, using H2C is incompatible with most of the other options for this server. Do not enable this only to achieve maximum client compatibility. In practice, very few clients implement H2C, and even fewer require it. This setting applies only to unencrypted HTTP listeners. ⚠️ Experimental feature; subject to change or removal.
+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`.
 
-- **experimental_http3** enables experimental draft HTTP/3 support. Note that HTTP/3 is not a finished spec and client support is extremely limited. This option will go away in the future. _This option is not subject to compatibility promises._
+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.
 
-- **strict_sni_host** require that a request's `Host` header matches the value of the ServerName sent by the client's TLS ClientHello; often a necessary safeguard when using TLS client authentication. If there's a mismatch, an HTTP status `421 Misdirected Request` response is written to the client.
+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.
 
-  This option will be implicitly 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 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.
+##### `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
 
@@ -418,3 +435,17 @@ A key pair (certificate and private key) to use as the intermediate for the CA.
 - **format** is the format in which the certificate and private key are provided. Currently, only `pem_file` is supported, which is the default, so this field is optional.
 - **cert** is the certificate. This should be the path to a PEM file, when using `pem_file` format.
 - **key** is the private key. This should be the path to a PEM file, when using `pem_file` format.
+
+
+## Event Options
+
+Caddy modules emit events when interesting things happen (or are about to happen).
+
+##### `on`
+Binds an event handler to the named event. Specify the name of the event handler module, followed by its configuration.
+
+For example, to run a command after a certificate is obtained ([third-party plugin <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/mholt/caddy-events-exec) required):
+
+```caddy-d
+on cert_obtained exec systemctl reload mydaemon
+```

src/docs/markdown/command-line.md

@@ -223,11 +223,11 @@ Formats or prettifies a Caddyfile, then exits. The result is printed to stdout u
 	[--algorithm <name>]
 	[--salt &lt;string&gt;]</code></pre>
 
-Hashes a password and writes the output to stdout in base64 encoding, then exits.
+Hashes a password and writes the output to stdout, then exits.
 
 `--plaintext` is the plaintext form of the password. If omitted, interactive mode will be assumed and the user will be shown a prompt to enter the password manually.
 
-`--algorithm` may be bcrypt or scrypt. Default is bcrypt.
+`--algorithm` may be bcrypt or any installed hash algorithm. Default is bcrypt.
 
 `--salt` is used only if the algorithm requires an external salt (like scrypt).
 
@@ -313,13 +313,13 @@ Because this command uses the API, the admin endpoint must not be disabled.
 	[&lt;status|body&gt;]</code></pre>
 
 
-Starts one or more simple, hard-coded HTTP servers that are useful for development, staging, and some production use cases.
+Starts one or more simple, hard-coded HTTP servers that are useful for development, staging, and some production use cases. It can be useful for verifying or debugging HTTP clients, scripts, or even load balancers.
 
 `--status` is the HTTP status code to return.
 
 `--header` adds an HTTP header; `Field: value` format is expected. This flag can be used multiple times.
 
-`--body` specifies the response body.
+`--body` specifies the response body. Alternatively, the body can be piped from stdin.
 
 `--listen` is the listener address, which can be any [network address](/docs/conventions#network-addresses) recognized by Caddy, and may include a port range to start multiple servers.
 

src/docs/markdown/extending-caddy/namespaces.md

@@ -15,7 +15,7 @@ Documentation for non-standard module namespaces can be found with the documenta
 Namespace | Expected Type | Description | Notes
 --------- | ------------- | ----------- | ----------
 |         | [`caddy.App`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#App) | Caddy app
-caddy.fs | [`fs.FS`](https://pkg.go.dev/io/fs#FS) or [`fs.StatFS`](https://pkg.go.dev/io/fs#StatFS) | Virtual file system |  <i>⚠️ Experimental</i>. Some host modules may require more specific FS interfaces. We recommend that all `caddy.fs` modules implement the `fs.StatFS` interface if possible.
+caddy.fs  | [`fs.FS`](https://pkg.go.dev/io/fs#FS) | Virtual file system |  <i>⚠️ Experimental</i>
 caddy.logging.encoders.filter | [`logging.LogFieldFilter`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging?tab=doc#LogFieldFilter) | Log field filter</i>
 caddy.logging.writers | [`caddy.WriterOpener`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#WriterOpener) | Log writers
 caddy.storage | [`caddy.StorageConverter`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#StorageConverter) | Storage backends

src/resources/css/docs.css

@@ -111,7 +111,8 @@ main > nav.sidebar {
 }
 
 main nav li img,
-article li img {
+article li img,
+img.external-link {
 	max-height: .9em;
 }