Sync docs

src/docs/markdown/caddyfile/concepts.md

@@ -343,11 +343,21 @@ You can use any placeholders in the Caddyfile, but for convenience you can also
 | `{hostport}`     | `{http.request.hostport}`           |
 | `{labels.*}`     | `{http.request.host.labels.*}`      |
 | `{method}`       | `{http.request.method}`             |
+| `{orig_method}`  | `{http.request.orig_method}`        |
+| `{orig_uri}`     | `{http.request.orig_uri}`           |
+| `{orig_path}`    | `{http.request.orig_uri.path}`      |
+| `{orig_dir}`     | `{http.request.orig_uri.path.dir}`  |
+| `{orig_file}`    | `{http.request.orig_uri.path.file}` |
+| `{orig_query}`   | `{http.request.orig_uri.query}`     |
+| `{orig_?query}`  | `{http.request.orig_uri.prefixed_query}` |
 | `{path.*}`       | `{http.request.uri.path.*}`         |
 | `{path}`         | `{http.request.uri.path}`           |
+| `{%path}`        | `{http.request.uri.path_escaped}`   |
 | `{port}`         | `{http.request.port}`               |
 | `{query.*}`      | `{http.request.uri.query.*}`        |
 | `{query}`        | `{http.request.uri.query}`          |
+| `{%query}`       | `{http.request.uri.query_escaped}`  |
+| `{?query}`       | `{http.request.uri.prefixed_query}` |
 | `{re.*}`         | `{http.regexp.*}`                   |
 | `{remote_host}`  | `{http.request.remote.host}`        |
 | `{remote_port}`  | `{http.request.remote.port}`        |
@@ -365,6 +375,7 @@ You can use any placeholders in the Caddyfile, but for convenience you can also
 | `{tls_version}`       | `{http.request.tls.version}`             |
 | `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` |
 | `{uri}`               | `{http.request.uri}`                     |
+| `{%uri}`              | `{http.request.uri_escaped}`             |
 | `{vars.*}`            | `{http.vars.*}`                          |
 
 Not all config fields support placeholders, but most do where you would expect it. Support for placeholders needs to have been explicitly added to those fields. Plugin authors can [read this article](/docs/extending-caddy/placeholders) to learn how to add support for placeholders in their own modules.

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

@@ -38,6 +38,7 @@ file_server [<matcher>] [browse] {
 	browse        [<template_file>] {
 		reveal_symlinks
 		sort <sort_field> [<direction>]
+		file_limit <number>
 	}
 	precompressed [<formats...>]
 	status        <status>
@@ -64,6 +65,8 @@ file_server [<matcher>] [browse] {
 
   - **sort** <span id="sort"/> changes the default sort for directory listings. The first parameter is the field/column to sort by: `name`, `namedirfirst`, `size`, or `time`. The second argument is an optional direction: `asc` or `desc`. For example, `sort name desc` will sort by name in descending order.
 
+  - **file_limit** <span id="file_limit"/> sets a maximum number of files to show in directory listings. Default: `10000`. If the number of files exceeds this limit, only the first N files will be shown, where N is the specified limit.
+
 - **precompressed** <span id="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`). If formats are omitted, they default to `br zstd gzip` (in that order).
 
   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](encode) is enabled, then it may compress the response on-the-fly if not precompressed.

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

@@ -56,7 +56,7 @@ header [<matcher>] [[+|-|?|>]<field> [<value>|<find>] [<replace>]] {
 
 - **&lt;value&gt;** is the header field value, when adding or setting a field.
 
-- **&lt;find&gt;** is the substring or regular expression to search for.
+- **&lt;find&gt;** is the regular expression to search for. Placeholders may be used for a dynamic input into the search pattern. The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax).
 
 - **&lt;replace&gt;** is the replacement value; required if performing a search-and-replace. Use `$1` or `$2` and so on to reference capture groups from the search pattern. If the replacement value is `""`, then the matching text is removed from the value. See the [Go documentation](https://golang.org/pkg/regexp/#Regexp.Expand) for details.
 

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

@@ -71,6 +71,11 @@ log [<logger_name>] {
 	output <writer_module> ...
 	format <encoder_module> ...
 	level  <level>
+	sampling {
+		interval   <duration>
+		first      <number>
+		thereafter <number>
+	}
 }
 ```
 
@@ -98,6 +103,15 @@ log [<logger_name>] {
 
   Note that access logs currently only emit `INFO` and `ERROR` level logs.
 
+- **sampling** <span id="sampling"/> configures log sampling to reduce log volume. If sampling is specified, then it is enabled, with the defaults below taking effect. Omitting this disables sampling.
+
+  - **interval** is the [duration window](/docs/conventions#durations) over which to conduct sampling. Default: `1s` (disabled).
+
+  - **first** is how many logs to keep within a given level and message for a each interval. Default: `100`.
+
+  - **thereafter** is how many logs to skip in each interval after the first kept logs. Default: `100`.
+
+  For example, with `interval 1s`, `first 5`, and `thereafter 10`, in each 10-second interval the first 5 log entries will be kept, then it will allow through every 10th log entry with the same level and message within that second.
 
 
 ### Output modules
@@ -605,3 +619,17 @@ foo.example.com {
 	log foo
 }
 ```
+
+<span id="sampling-example" /> To reduce log volume with sampling, for example to keep the first 5 requests per second, then 1 out of every 10 requests thereafter:
+
+```caddy
+example.com {
+	log {
+		sampling {
+			interval   1s
+			first      5
+			thereafter 10
+		}
+	}
+}
+```

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

@@ -266,6 +266,42 @@ The `http` module obtains the trusted certificates from HTTP endpoints. The `end
   - `once` allows a remote server to request renegotiation once per connection.
   - `freely` allows a remote server to repeatedly request renegotiation.
 
+### Verifiers
+
+Client certificate verifier modules are executed after validating they are issued from a trusted certificate authority, if the `trust_pool` is configured. The one verifier, currently, shipped in standard Caddy is `leaf`.
+
+#### Leaf
+
+The `leaf` verifier checks if the client certificate is one of a defined set of permitted certificates. The certificate set is loaded using [loader](https://caddyserver.com/docs/modules/tls.client_auth.verifier.leaf#leaf_certs_loaders) modules.
+
+##### Loaders
+
+Standard Caddy distribution bundles 4 loaders, 3 of them are available in Caddyfile.
+
+###### File
+
+The `file` loader loads the set of certificates from specified PEM files.
+
+```caddy-d
+... file <pem_files...>
+```
+
+###### Folder
+
+The `folder` loader recursively traverses the named directories searching for PEM files to be loaded as accepted client certificates.
+
+```caddy-d
+... folder <folders...>
+```
+
+###### PEM
+
+The `pem` loader accepts certificates inlined in the Caddyfile in PEM format.
+
+```caddy-d
+... pem <pem_strings...>
+```
+
 ### Issuers
 
 These issuers come standard with the `tls` directive:

src/docs/markdown/caddyfile/matchers.md

@@ -244,10 +244,10 @@ expression <cel...>
 
 By any [CEL (Common Expression Language)](https://github.com/google/cel-spec) expression that returns `true` or `false`.
 
-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.
-
 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.
 
+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. If a placeholder should be passed as a string argument to a matcher function, then the leading `{` should be escaped with a backslash `\` so that it is not preprocessed, for example `file('\{path}.md')`.
+
 For convenience, the matcher name may be omitted if defining a named matcher that consists solely of a CEL expression. The CEL expression must be [quoted](/docs/caddyfile/concepts#tokens-and-quotes) (backticks or heredocs recommended). This reads quite nicely:
 
 ```caddy-d
@@ -861,6 +861,9 @@ In a [CEL expression](#expression), it would look like this:
 
 ```caddy-d
 vars <variable> <values...>
+
+expression vars({'<variable>': '<value>'})
+expression 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).
@@ -898,12 +901,21 @@ example.com {
 }
 ```
 
+In a [CEL expression](#expression), it would look like this:
+
+```caddy-d
+@magic `vars({'magic_number': ['3', '5']})`
+```
+
 
 ---
 ### vars_regexp
 
 ```caddy-d
 vars_regexp [<name>] <variable> <regexp>
+
+expression vars_regexp('<name>', '<variable>', '<regexp>')
+expression vars_regexp('<variable>', '<regexp>')
 ```
 
 Like [`vars`](#vars), but supports regular expressions.
@@ -936,3 +948,9 @@ This can be simplified by omitting the name, which will be inferred from the nam
 ```caddy-d
 @magic vars_regexp {magic_number} ^(4.*)
 ```
+
+In a [CEL expression](#expression), it would look like this:
+
+```caddy-d
+@magic `vars_regexp('magic_number', '^(4.*)')`
+```

src/docs/markdown/caddyfile/options.md

@@ -126,8 +126,12 @@ Possible options are (click on each option to jump to its documentation):
 			idle        <duration>
 		}
 		keepalive_interval <duration>
+		keepalive_idle     <duration>
+		keepalive_count	   <number>
+
 		trusted_proxies <module> ...
 		client_ip_headers <headers...>
+
 		trace
 		max_header_size <size>
 		enable_full_duplex
@@ -938,6 +942,31 @@ The interval at which TCP keepalive packets are sent to keep the connection aliv
 ```
 
 
+##### `keepalive_idle`
+
+The duration a connection must be idle before TCP keepalive packets are sent when no other data is being transmitted. Defaults to `15s`.
+
+```caddy
+{
+	servers {
+		keepalive_idle 1m
+	}
+}
+```
+
+
+##### `keepalive_count`
+
+The maximum number of TCP keepalive packets to send before considering the connection dead. Defaults to `9`.
+
+```caddy
+{
+	servers {
+		keepalive_count 5
+	}
+}
+```
+
 
 ##### `trusted_proxies`
 

src/docs/markdown/command-line.md

@@ -119,7 +119,7 @@ The `--flags` may have a single-letter shortcut like `-f`.
 
 Adapts a configuration to Caddy's native JSON config structure and writes the output to stdout, along with any warnings to stderr, then exits.
 
-`--config` is the path to the config file. If omitted, assumes `Caddyfile` in current directory if it exists; otherwise, this flag is required.
+`--config` is the path to the config file. If omitted, assumes `Caddyfile` in current directory if it exists; otherwise, this flag is required. If you wish to use stdin instead of a regular file, use - as the path.
 
 `--adapter` specifies the config adapter to use; default is `caddyfile`.
 
@@ -194,6 +194,7 @@ Prints the environment as seen by caddy, then exits. Can be useful when debuggin
 	[-t, --templates]
 	[--access-log]
 	[-v, --debug]
+	[-f, --file-limit <number>]
 	[--no-compress]
 	[-p, --precompressed]</code></pre>
 
@@ -215,6 +216,8 @@ Spins up a simple but production-ready static file server.
 
 `--debug` enables verbose logging.
 
+`--file-limit` sets a maximum number of files to show in directory listings. Default: `10000`. If the number of files exceeds this limit, only the first N files will be shown, where N is the specified limit.
+
 `--no-compress` disables compression. By default, Zstandard and Gzip compression are enabled.
 
 `--precompressed` specifies encoding formats to search for precompressed sidecar files. Can be repeated for multiple formats. See the [file_server directive](/docs/caddyfile/directives/file_server#precompressed) for more information.
@@ -248,14 +251,15 @@ Formats or prettifies a Caddyfile, then exits. The result is printed to stdout u
 <pre><code class="cmd bash">caddy hash-password
 	[-p, --plaintext &lt;password&gt;]
 	[-a, --algorithm &lt;name&gt;]</code></pre>
+	[--bcrypt-cost &lt;cost&gt;]</code></pre>
 
 Convenient way to hash a plaintext password. The resulting hash is written to stdout as a format usable directly in your Caddy config.
 
 `--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 any installed hash algorithm. Default is `bcrypt`.
 
-
+`--bcrypt-cost` is the hashing cost for bcrypt algorithm. Default is `14`.
 
 
 ### `caddy help`

src/docs/markdown/conventions.md

@@ -90,7 +90,7 @@ Placeholders are a similar idea to variables in other software. For example, [ng
 
 Placeholders are bounded on either side by curly braces `{ }` and contain the identifier inside, for example: `{foo.bar}`. The opening placeholder brace can be escaped `\{like.this}` to prevent replacement. Placeholder identifiers are typically namespaced with dots to avoid collisions across modules.
 
-Which placeholders are available depends on the context. Not all placeholders are available in all parts of the config. For example, [the HTTP app sets placeholders](/docs/json/apps/http/#docs) that are only available in areas of the config related to handling HTTP requests.
+Which placeholders are available depends on the context. Not all placeholders are available in all parts of the config. For example, [the HTTP app sets placeholders](/docs/json/apps/http/#docs) that are only available in areas of the config related to handling HTTP requests. When a request passes through the [`reverse_proxy` handler](/docs/json/apps/http/servers/routes/handle/reverse_proxy/#docs), the handler sets several proxy-specific placeholders. These placeholders may be referenced during proxying as well as afterwards (in `handle_response`), for example when setting response headers or enriching access logs.
 
 The following placeholders are always available (global):