docs: Updates for Caddy v2.4.4 (#189)

* docs: Updates for Caddy v2.4.4

* Adjust wording

* Clarify HTTPS proxy usage, reorder lb policies for clarity

* Reorder directives, add comments

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}` |
+| `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` |
 
 
 

src/docs/markdown/caddyfile/directives.md

@@ -83,29 +83,33 @@ header
 request_body
 
 redir
-rewrite
 
+# URI manipulation
+rewrite
 uri
 try_files
 
+# middleware handlers; some wrap responses
 basicauth
 request_header
 encode
+push
 templates
 
+# special routing & dispatching directives
 handle
 handle_path
 route
-push
 
+# handlers that typically respond to requests
+abort
+error
 respond
 metrics
 reverse_proxy
 php_fastcgi
 file_server
 acme_server
-abort
-error
 ```
 
 You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).

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

@@ -20,6 +20,7 @@ file_server [<matcher>] [browse] {
 	browse        [<template_file>]
 	precompressed <formats...>
 	status        <status>
+	disable_canonical_uris
 }
 ```
 
@@ -30,6 +31,7 @@ file_server [<matcher>] [browse] {
 - **<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/browsetpl.go). 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. Supported formats are `gzip`, `zstd` and `br`.
 - **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.
 
 ## Examples
 

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

@@ -8,6 +8,24 @@ Enables and configures HTTP request logging (also known as access logs).
 
 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).
 
+- [Syntax](#syntax)
+- [Output modules](#output-modules)
+  - [stderr](#stderr)
+  - [stdout](#stdout)
+  - [discard](#discard)
+  - [file](#file)
+  - [net](#net)
+- [Format modules](#format-modules)
+  - [console](#console)
+  - [json](#json)
+  - [single_field](#single-field)
+  - [filter](#filter)
+    - [delete](#delete)
+	- [replace](#replace)
+	- [ip_mask](#ip-mask)
+- [Examples](#examples)
+
+
 ## Syntax
 
 ```caddy-d
@@ -20,7 +38,9 @@ log {
 
 - **output** configures where to write the logs. See [Output modules](#output-modules) below. Default: `stderr`
 - **format** describes how to encode, or format, the logs. See [Format modules](#format-modules) below. Default: `console` if `stdout` is detected to be a terminal, `json` otherwise.
-- **level** is the minimum entry level to log. Default: `INFO`
+- **level** is the minimum entry level to log. Default: `INFO`. Note that access logs currently only emit `INFO` and `ERROR` level logs.
+
+
 
 ### Output modules
 
@@ -133,6 +153,8 @@ format json
 
 #### single_field
 
+<span class="warning">⚠️ This format is deprecated, and will be removed in a future version.</span>
+
 Writes only a single field from the structure log entry. Useful if one of the fields has all the information you need.
 
 ```caddy-d
@@ -199,6 +221,7 @@ Enable access logging (to the console):
 log
 ```
 
+
 Write logs to a file (with log rolling, which is enabled by default):
 
 ```caddy-d
@@ -207,6 +230,7 @@ log {
 }
 ```
 
+
 Customize log rolling:
 
 ```caddy-d
@@ -219,7 +243,10 @@ log {
 }
 ```
 
-Use common log format (deprecated, but can be useful for older setups):
+
+Use Common Log Format (CLF):
+
+<span class="warning">⚠️ The `single_field` format is deprecated and will be removed in a future version. To encode logs in common log format, please use the [`format-encoder`](https://github.com/caddyserver/format-encoder) plugin.</span>
 
 ```caddy-d
 log {
@@ -227,6 +254,7 @@ log {
 }
 ```
 
+
 Delete the Authorization request header from the logs:
 
 ```caddy-d
@@ -240,6 +268,7 @@ log {
 }
 ```
 
+
 Mask the remote address from the request, keeping the first 16 bytes (i.e. 255.255.0.0) for IPv4 addresses, and the first 64 bytes from IPv6 addresses, and also deletes the `common_log` field which would normally contain an unmasked IP address:
 
 ```caddy-d

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

@@ -103,6 +103,8 @@ Additionally, upstream addresses cannot contain paths or query strings, as that
 
 If the address is not a URL (i.e. does not have a scheme), then placeholders can be used, but this makes the upstream dynamic, meaning that the potentially many different backends act as one upstream in terms of health checks and load balancing.
 
+When proxying over HTTPS, you may need to override the `Host` header (which by default, retains the value from the original request) such that the `Host` header matches the TLS SNI value, which is used by servers for routing and certificate selection. See the [Headers](#headers) section below for more details.
+
 
 
 ### Load balancing
@@ -110,14 +112,14 @@ If the address is not a URL (i.e. does not have a scheme), then placeholders can
 Load balancing is used whenever more than one upstream is defined.
 
 - **lb_policy** is the name of the load balancing policy, along with any options. Default: `random`. Can be:
-	- `first` - choose first available upstream
-	- `header` - map request header to sticky upstream
-	- `ip_hash` - map client IP to sticky upstream
-	- `least_conn` - choose upstream with fewest number of current requests
 	- `random` - randomly choose an upstream
 	- `random_choose <n>` - selects two or more upstreams randomly, then chooses one with least load (`n` is usually 2)
+	- `first` - choose first available upstream, from the order they are defined in the config
 	- `round_robin` - iterate each upstream in turn
+	- `least_conn` - choose upstream with fewest number of current requests
+	- `ip_hash` - map client IP to sticky upstream
 	- `uri_hash` - map URI to sticky upstream
+	- `header [field]` - map request header to sticky upstream
 	- `cookie [<name> [<secret>]]` - based on the given cookie (default name is `lb` if not specified), which value is hashed; optionally with a secret for HMAC-SHA256
 
 - **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.
@@ -155,7 +157,7 @@ Passive health checks happen inline with actual proxied requests:
 
 The proxy **buffers responses** by default for wire efficiency:
 
-- **flush_interval** is a [duration value](/docs/conventions#durations) that defines how often Caddy should flush the buffered response body to the client. Set to -1 to disable buffering. It is set to -1 automatically for requests that have a `text/event-stream` response or for HTTP/2 requests where the Content-Length is unspecified.
+- **flush_interval** is a [duration value](/docs/conventions#durations) that adjusts how often Caddy should flush the response buffer to the client. By default, no periodic flushing is done. A negative value disables response buffering, and flushes immediately after each write to the client. This option is ignored when the upstream's response is recognized as a streaming response, or if its content length is `-1`; for such responses, writes are flushed to the client immediately.
 - **buffer_requests** will cause the proxy to read the entire request body into a buffer before sending it upstream. This is very inefficient and should only be done if the upstream requires reading request bodies without delay (which is something the upstream application should fix).
 - **buffer_responses** will cause the entire response body to be read and buffered in memory before being proxied to the client. This should be avoided if at all possible for performance reasons, but could be useful if the backend has tighter memory constraints.
 - **max_buffer_size** if body buffering is enabled, this sets the maximum size of the buffers used for the requests and responses. This accepts all size formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go).
@@ -164,17 +166,31 @@ The proxy **buffers responses** by default for wire efficiency:
 
 ### Headers
 
-It can also **manipulate headers** between itself and the backend:
+The proxy can **manipulate headers** between itself and the backend:
 
 - **header_up** Sets, adds, removes, or performs a replacement in a request header going upstream to the backend.
 - **header_down** Sets, adds, removes, or performs a replacement in a response header coming downstream from the backend.
 
+
+#### Defaults
+
 By default, Caddy passes thru incoming headers to the backend&mdash;including the `Host` header&mdash;without modifications, with two exceptions:
 
 - It adds or augments the [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) header field.
 - It sets the [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) header field.
 
-Since these header fields are only de-facto standards, Caddy may stop setting them implicitly in the future if the standardized [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) header field becomes more widely adopted.
+
+#### HTTPS
+
+For HTTPS upstreams, since the `Host` header retains its original value, it is typically necessary to override the header with the configured upstream address, such that the `Host` header matches the TLS SNI value. A `X-Forwarded-Host` header may also be added to inform the upstream of the original `Host` header's value. For example:
+
+```caddy-d
+reverse_proxy https://example.com {
+	header_up Host {upstream_hostport}
+	header_up X-Forwarded-Host {host}
+}
+```
+
 
 
 
@@ -295,12 +311,14 @@ Reverse proxy all requests to a local backend:
 reverse_proxy localhost:9005
 ```
 
+
 Load-balance all requests between 3 backends:
 
 ```caddy-d
 reverse_proxy node1:80 node2:80 node3:80
 ```
 
+
 Same, but only requests within `/api`, and with header affinity:
 
 ```caddy-d
@@ -309,24 +327,11 @@ reverse_proxy /api/* node1:80 node2:80 node3:80 {
 }
 ```
 
-Set the upstream Host header to the address of the upstream (by default, it will retain its original, incoming value):
-
-```caddy-d
-reverse_proxy localhost:9000 {
-	header_up Host {http.reverse_proxy.upstream.hostport}
-}
-```
-
-Reverse proxy to an HTTPS endpoint:
-
-```caddy-d
-reverse_proxy https://example.com
-```
 
 Configure some transport options:
 
 ```caddy-d
-reverse_proxy https://example.com {
+reverse_proxy localhost:8080 {
 	transport http {
 		dial_timeout 2s
 		tls_timeout  2s
@@ -334,6 +339,17 @@ reverse_proxy https://example.com {
 }
 ```
 
+
+Reverse proxy to an HTTPS endpoint:
+
+```caddy-d
+reverse_proxy https://example.com {
+	header_up Host {upstream_hostport}
+	header_up X-Forwarded-Host {host}
+}
+```
+
+
 Replace a path prefix before proxying:
 
 ```caddy-d
@@ -343,6 +359,7 @@ handle_path /old-prefix/* {
 }
 ```
 
+
 X-Accel-Redirect support:
 
 ```caddy-d
@@ -356,6 +373,7 @@ reverse_proxy localhost:8080 {
 }
 ```
 
+
 Custom error page for errors from upstream:
 
 ```caddy-d