docs: Adjustments for v2.4.6

src/docs/markdown/automatic-https.md

@@ -231,7 +231,7 @@ Here's what happens if there's an error obtaining or renewing a certificate:
 
 During retries with Let's Encrypt, Caddy switches to their [staging environment](https://letsencrypt.org/docs/staging-environment/) to avoid rate limit concerns. This isn't a perfect strategy, but in general it's helpful.
 
-ACME challenges take at least a few seconds, and internal rate limiting helps mitigate accidental abuse. Caddy uses internal rate limiting in addition to what you or the CA configure so that you can hand Caddy a platter with a million domain names and it will gradually -- but as fast as it can -- obtain certificates for all of them. Caddy's internal rate limit is currently 10 attempts per ACME account per minute.
+ACME challenges take at least a few seconds, and internal rate limiting helps mitigate accidental abuse. Caddy uses internal rate limiting in addition to what you or the CA configure so that you can hand Caddy a platter with a million domain names and it will gradually -- but as fast as it can -- obtain certificates for all of them. Caddy's internal rate limit is currently 10 attempts per ACME account per 10 seconds.
 
 To avoid leaking resources, Caddy aborts in-flight tasks (including ACME transactions) when config is changed. While Caddy is capable of handling frequent config reloads, be mindful of operational considerations such as this, and consider batching config changes to reduce reloads and give Caddy a chance to actually finish obtaining certificates in the background.
 

src/docs/markdown/caddyfile/concepts.md

@@ -252,6 +252,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd
 | `{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}` |
 | `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` |
 
 

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

@@ -8,7 +8,7 @@ An opinionated directive that proxies requests to a PHP FastCGI server such as p
 
 Caddy's [reverse_proxy](/docs/caddyfile/directives/reverse_proxy) is capable of serving any FastCGI application, but this directive is tailored specifically for PHP apps. This directive is actually just a convenient way to use a longer, more common configuration (below).
 
-It expects that any `index.php` at the site root acts as a router. If that is not desirable, either perform your own URI rewrite or use something like the [expanded form](#expanded-form) below and customize it to your needs.
+It expects that any `index.php` at the site root acts as a router. If that is not desirable, either reconfigure the `try_files` option to modify the default rewrite behaviour, or take the [expanded form](#expanded-form) below as a basis and customize it to your needs.
 
 It supports all the subdirectives of [reverse_proxy](/docs/caddyfile/directives/reverse_proxy) and passes them through to the underlying reverse_proxy handler, plus a few subdirectives that customize the FastCGI transport specifically.
 
@@ -22,6 +22,7 @@ php_fastcgi [<matcher>] <php-fpm_gateways...> {
 	split <substrings...>
 	env [<key> <value>]
 	index <filename>|off
+	try_files <files...>
 	resolve_root_symlink
 	dial_timeout  <duration>
 	read_timeout  <duration>
@@ -36,6 +37,7 @@ php_fastcgi [<matcher>] <php-fpm_gateways...> {
 - **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: no timeout.
 - **read_timeout** is how long to wait when reading from the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
@@ -104,3 +106,11 @@ root * /var/www/html
 php_fastcgi 127.0.0.1:9000
 file_server
 ```
+
+For a PHP site which does not use `index.php` as an entrypoint, you may fallback to emitting a `404` error instead. The error may be handled with the [`handle_errors` directive](/docs/caddyfile/directives/handle_errors):
+
+```caddy-d
+php_fastcgi localhost:9000 {
+	try_files {path} {path}/index.php =404
+}
+```

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

@@ -13,7 +13,7 @@ Rewrites the request URI path to the first of the listed files which exists in t
 try_files <files...>
 ```
 
-- **<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.
+- **<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).
 
 
 ## Expanded form
@@ -49,3 +49,9 @@ Same, but also match directories:
 ```caddy-d
 try_files {path} {path}/ /index.php?{query}&p={path}
 ```
+
+Attempt to rewrite to a file or directory if it exists, otherwise emit a 404 error (which can be caught and handled with [`handle_errors`](/docs/caddyfile/directives/handle_errors)):
+
+```caddy-d
+try_files {path} {path}/ =404
+```

src/docs/markdown/caddyfile/matchers.md

@@ -203,6 +203,7 @@ expression {http.error.status_code} == 404
 ```
 
 
+
 ---
 ### file
 
@@ -218,7 +219,7 @@ file {
 By files.
 
 - `root` defines the directory in which to look for files. Default is the current working directory, or the `root` [variable](/docs/modules/http.handlers.vars) (`{http.vars.root}`) if set (can be set via the [`root` directive](/docs/caddyfile/directives/root)).
-- `try_files` checks files in its list that match the try_policy.
+- `try_files` checks files in its list that match the try_policy. If the `try_policy` is `first_exist`, then 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).
 - `try_policy` specifies how to choose a file. Default is `first_exist`.
 	- `first_exist` checks for file existence. The first file that exists is selected.
 	- `smallest_size` chooses the file with the smallest size.
@@ -257,6 +258,13 @@ file {
 }
 ```
 
+Same as above, except using the one-line shortcut, and falling back to emitting a 404 error if a file is not found.
+
+```caddy-d
+file {path}.html {path} =404
+```
+
+
 
 ---
 ### header
@@ -301,6 +309,7 @@ Match requests that do not have the `Foo` header field at all:
 ```
 
 
+
 ---
 ### header_regexp
 
@@ -310,6 +319,8 @@ header_regexp [<name>] <field> <regexp>
 
 Like `header`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
+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).
+
 Only one regular expression is supported per header field. Multiple different fields will be AND'ed.
 
 #### Example:
@@ -321,6 +332,7 @@ header_regexp login Cookie login_([a-f0-9]+)
 ```
 
 
+
 ---
 ### host
 
@@ -339,6 +351,7 @@ host sub.example.com
 ```
 
 
+
 ---
 ### method
 
@@ -365,6 +378,7 @@ method PUT DELETE
 ```
 
 
+
 ---
 ### not
 
@@ -415,6 +429,7 @@ not {
 ```
 
 
+
 ---
 ### path
 
@@ -429,9 +444,12 @@ By request path, meaning the path component of the request's URI. Path matches a
 - On both sides, for a substring match (`*/contains/*`)
 - In the middle, for a globular match (`/accounts/*/info`)
 
+The request path is URL-decoded, lowercased (to be case insensitive), and cleaned (to collapse doubled-up slashes and directory traversal dots) before matching. For example `/foo*` will also match `/FOO`, `//foo` and `/%2F/foo`.
+
 Multiple `path` matchers will be OR'ed together.
 
 
+
 ---
 ### path_regexp
 
@@ -441,6 +459,10 @@ path_regexp [<name>] <regexp>
 
 Like `path`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
+The request path is URL-decoded, and cleaned (to collapse doubled-up slashes and directory traversal dots) before matching. For example `/foo*` will also match `//foo` and `/%2F/foo`.
+
+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).
+
 There can only be one `path_regexp` matcher per named matcher.
 
 #### Example:
@@ -452,6 +474,7 @@ path_regexp static \.([a-f0-9]{6})\.(css|js)$
 ```
 
 
+
 ---
 ### protocol
 
@@ -464,6 +487,7 @@ By request protocol.
 There can only be one `protocol` matcher per named matcher.
 
 
+
 ---
 ### query
 
@@ -484,6 +508,7 @@ query sort=asc
 ```
 
 
+
 ---
 ### remote_ip
 

src/docs/markdown/command-line.md

@@ -220,10 +220,13 @@ Prints CLI help text, optionally for a specific subcommand, then exits.
 
 <pre><code class="cmd bash">caddy list-modules
 	[--packages]
-	[--versions]</code></pre>
+	[--versions]
+	[--skip-standard]</code></pre>
 
 Prints the Caddy modules that are installed, optionally with package and/or version information from their associated Go modules, then exits.
 
+In some scripted situations, it may be redundant to print all of the standard modules as well, so you may use `--skip-standard` to omit those from the output.
+
 NOTE: Due to [a bug in Go](https://github.com/golang/go/issues/29228), version information is only available if Caddy is built as a dependency and not as the main module. Use [xcaddy](/docs/build#xcaddy) to make this easier.
 
 
@@ -362,13 +365,14 @@ Untrusts a root certificate from the local trust store(s). Intended for developm
 
 ### `caddy upgrade`
 
-<pre><code class="cmd bash">caddy upgrade</code></pre>
+<pre><code class="cmd bash">caddy upgrade
+	[--keep-backup]</code></pre>
 
 Replaces the current Caddy binary with the latest version from [our download page](https://caddyserver.com/download) with the same modules installed, including all third-party plugins that are registered on the Caddy website.
 
 Upgrades do not interrupt running servers; currently, the command only replaces the binary on disk. This might change in the future if we can figure out a good way to do it.
 
-The upgrade process is fault tolerant; the current binary is backed up first and automatically restored if anything goes wrong.
+The upgrade process is fault tolerant; the current binary is backed up first (copied beside the current one) and automatically restored if anything goes wrong. If you wish to keep the backup after the upgrade process is complete, you may use the `--keep-backup` option.
 
 This command may require elevated privileges if your user does not have permission to write to the executable file.
 
@@ -376,7 +380,8 @@ This command may require elevated privileges if your user does not have permissi
 
 ### `caddy add-package`
 
-<pre><code class="cmd bash">caddy add-package &lt;packages...&gt;</code></pre>
+<pre><code class="cmd bash">caddy add-package &lt;packages...&gt;
+	[--keep-backup]</code></pre>
 
 Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest version with the same modules installed, _plus_ the packages listed as arguments included in the new binary. Find the list of packages you can install from [our download page](https://caddyserver.com/download). Each argument should be the full package name.
 
@@ -388,7 +393,8 @@ For example:
 
 ### `caddy remove-package`
 
-<pre><code class="cmd bash">caddy remove-package &lt;packages...&gt;</code></pre>
+<pre><code class="cmd bash">caddy remove-package &lt;packages...&gt;
+	[--keep-backup]</code></pre>
 
 Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest version with the same modules installed, but _without_ the packages listed as arguments, if they existed in the current binary. Run `caddy list-modules --packages` to see the list of package names of non-standard modules included in the current binary.