Docs for v2.7.2

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

@@ -58,7 +58,7 @@ header [<matcher>] [[+|-|?|>]<field> [<value>|<find>] [<replace>]] {
 
 For multiple header manipulations, you can open a block and specify one manipulation per line in the same way.
 
-When using the `?` prefix to set a default header value, it is recommended to separate this into its own `header` directive. [Under the hood](https://caddyserver.com/docs/modules/http.handlers.headers#response/require), using `?` configures a response matcher which applies to the directive's entire handler which only applies the header operations if the field is not yet set. For example, if in the same directive, you have these two manipulations: `-Hidden` and `?Foo default`, then the `Hidden` header is _only_ removed if `Foo` is empty, which is typically not the intended effect.
+When using the `?` prefix to set a default header value, it is recommended to separate this into its own `header` directive. [Under the hood](/docs/modules/http.handlers.headers#response/require), using `?` configures a response matcher which applies to the directive's entire handler which only applies the header operations if the field is not yet set. For example, if in the same directive, you have these two manipulations: `-Hidden` and `?Foo default`, then the `Hidden` header is _only_ removed if `Foo` is empty, which is typically not the intended effect.
 
 
 ## Examples

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

@@ -52,15 +52,22 @@ Since Caddy v2.5, by default, headers with potentially sensitive information (`C
 ## Syntax
 
 ```caddy-d
-log {
+log [<logger_name>] {
+	hostnames <hostnames...>
 	output <writer_module> ...
 	format <encoder_module> ...
 	level  <level>
 }
 ```
 
-- **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.
+- **logger_name** is an optional override of the logger name for this site. By default, a logger name is generated automatically, e.g. `log0`, `log1`, and so on depending on the order of the sites in the Caddyfile. This is only useful if you wish to reliably refer to the output of this logger from another logger defined in global options. See [an example](#multiple-outputs) below.
+
+- **hostnames** overrides the hostnames that this logger applies to. By default, the logger applies to the hostnames of the site block it appears in, i.e. the site addresses. This is useful if you wish to define different loggers per subdomain in a [wildcard site block](/docs/caddyfile/patterns#wildcard-certificates). See [an example](#wildcard-logs) below.
+
+- **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 `stderr` is detected to be a terminal, `json` otherwise.
+
 - **level** is the minimum entry level to log. Default: `INFO`. Note that access logs currently only emit `INFO` and `ERROR` level logs.
 
 
@@ -140,7 +147,7 @@ The **format** subdirective lets you customize how logs get encoded (formatted).
 
 <aside class="tip">
 
-**A note about Common Log Format (CLF):** CLF clashes with modern structured logs. To transform your access logs into the deprecated Common Log Format, please use the [`transform-encoder` plugin](https://github.com/caddyserver/transform-encoder).
+**A note about Common Log Format (CLF):** CLF clashes with modern structured logs. To transform your access logs into the deprecated Common Log Format, please use the [`transform-encoder` plugin <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/caddyserver/transform-encoder).
 
 </aside>
 
@@ -259,7 +266,7 @@ Masks IP addresses in the field using a CIDR mask, i.e. the number of bits from
 
 There is separate configuration for IPv4 and IPv6 addresses, since they have a different total number of bits.
 
-Most commonly, the fields to filter would be `request>remote_ip` for the directly connecting client, or `request>headers>X-Forwarded-For` if behind a reverse proxy.
+Most commonly, the fields to filter would be `request>remote_ip` for the directly connecting client, `request>client_ip` for the parsed "real client" when [`trusted_proxies`](/docs/caddyfile/options#trusted-proxies) is configured, or `request>headers>X-Forwarded-For` if behind a reverse proxy.
 
 ```caddy-d
 <field> ip_mask {
@@ -328,7 +335,9 @@ Useful to obscure the value if it's sensitive, while being able to notice whethe
 
 ## Examples
 
-Enable access logging (to the console):
+Enable access logging to the default logger.
+
+In other words, by default this logs to the console or stderr, but this can be changed by reconfiguring the default logger with the [`log` global option](/docs/caddyfile/options#log):
 
 ```caddy-d
 log
@@ -388,7 +397,9 @@ log {
 ```
 
 
-Mask the remote address from the request, keeping the first 16 bits (i.e. 255.255.0.0) for IPv4 addresses, and the first 32 bits from IPv6 addresses. (Note that prior to Caddy v2.5, the field was named `remote_addr`, but is now `remote_ip`):
+Mask the remote address from the request, keeping the first 16 bits (i.e. 255.255.0.0) for IPv4 addresses, and the first 32 bits from IPv6 addresses.
+
+Note that as of Caddy v2.7, both `remote_ip` and `client_ip` are logged, where `client_ip` is the "real IP" when [`trusted_proxies`](/docs/caddyfile/options#trusted-proxies) is configured:
 
 ```caddy-d
 log {
@@ -403,3 +414,52 @@ log {
 	}
 }
 ```
+
+
+<span id="wildcard-logs" /> To write separate log files for each subdomain in a [wildcard site block](/docs/caddyfile/patterns#wildcard-certificates), by overriding `hostnames` for each logger:
+
+```caddy
+*.example.com {
+	log {
+		hostnames foo.example.com
+		output file /var/log/foo.example.com.log
+	}
+	@foo host foo.example.com  
+	handle @foo {
+		respond "foo"
+	}
+
+	log {
+		hostnames bar.example.com
+		output file /var/log/bar.example.com.log
+	}
+	@bar host bar.example.com
+	handle @bar {
+		respond "bar"
+	}
+}
+```
+
+<span id="multiple-outputs" /> To write the access logs for a particular subdomain to two different files, with different formats (one with [`transform-encoder` plugin <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/caddyserver/transform-encoder) and the other with [`json`](#json)). 
+
+This works by overriding the logger name as `foo` in the site block, then including the access logs produced by that logger in the two loggers in global options with `include http.log.access.foo`:
+
+```caddy
+{
+	log access-formatted {
+		include http.log.access.foo
+		output file /var/log/access-foo.log
+		format transform "{common_log}"
+	}
+
+	log access-json {
+		include http.log.access.foo
+		output file /var/log/access-foo.json
+		format json
+	}
+}
+
+foo.example.com {
+	log foo
+}
+```

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

@@ -38,6 +38,7 @@ Proxies requests to one or more backends with configurable transport, load balan
 - [Load balancing](#load-balancing)
   - [Active health checks](#active-health-checks)
   - [Passive health checks](#passive-health-checks)
+  - [Events](#events)
 - [Streaming](#streaming)
 - [Headers](#headers)
 - [Rewrites](#rewrites)
@@ -334,6 +335,16 @@ Passive health checks happen inline with actual proxied requests. To enable this
   This should be a reasonably large number; configuring this means that the proxy will have a limit of `unhealthy_request_count × upstreams_count` total simultaneous requests, and any requests after that point will result in an error due to no upstreams being available.
 
 
+### Events
+
+When an upstream transitions from being healthy to unhealthy or vice-versa, [an event](/docs/caddyfile/options#event-options) is emitted. These events can be used to trigger other actions, such as sending a notification or logging a message. The events are as follows:
+
+- `healthy` is emitted when an upstream is marked healthy when it was previous unhealthy
+- `unhealthy` is emitted when an upstream is marked unhealthy when it was previous healthy
+
+In both cases, the `host` is included as metadata in the event to identify the upstream that changed state. It can be used as a placeholder with `{event.data.host}` with the `exec` event handler, for example.
+
+
 
 ### Streaming
 

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

@@ -110,7 +110,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 
 - **eab** <span id="eab"/> configures ACME external account binding (EAB) for this site, using the key ID and MAC key provided by your CA.
 
-- **on_demand** <span id="on_demand"/> enables [On-Demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es). **Security warning:** Doing so in production is insecure unless you also configure the [`on_demand_tls` global option](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to mitigate abuse.
+- **on_demand** <span id="on_demand"/> enables [On-Demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es). **Security warning:** Doing so in production is insecure unless you also configure the [`on_demand_tls` global option](/docs/caddyfile/options#on-demand-tls) to mitigate abuse.
 
 - **client_auth** <span id="client_auth"/> enables and configures TLS client authentication:
   - **mode** <span id="mode"/> is the mode for authenticating the client. Allowed values are:

src/docs/markdown/caddyfile/options.md

@@ -112,6 +112,7 @@ Possible options are:
 		client_ip_headers <headers...>
 		metrics
 		max_header_size <size>
+		enable_full_duplex
 		log_credentials
 		protocols [h1|h2|h2c|h3]
 		strict_sni_host [on|insecure_off]
@@ -299,7 +300,7 @@ Skips the attempts to install the local CA's root into the system trust store, a
 
 
 ##### `acme_ca`
-Specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: ZeroSSL and Let's Encrypt's production endpoints.
+Specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint <img src="/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: ZeroSSL and Let's Encrypt's production endpoints.
 
 Note that a globally-configured ACME CA may not apply to all sites; see the [hostname requirements](/docs/automatic-https#hostname-requirements) for using the default ACME issuer(s).
 
@@ -523,7 +524,20 @@ Enables Prometheus metrics collection; necessary before scraping metrics. Note t
 
 ##### `max_header_size`
 
-The maximum size to parse from a client's HTTP request headers. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go).
+The maximum size to parse from a client's HTTP request headers. If the limit is exceeded, the server will respond with HTTP status `431 Request Header Fields Too Large`. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go). By default, the limit is `1MB`.
+
+
+##### `enable_full_duplex`
+
+Enable full-duplex communication for HTTP/1 requests. Only has an effect if Caddy was built with Go 1.21 or later.
+
+For HTTP/1 requests, the Go HTTP server by default consumes any unread portion of the request body before beginning to write the response, preventing handlers from concurrently reading from the request and writing the response. Enabling this option disables this behavior and permits handlers to continue to read from the request while concurrently writing the response.
+
+For HTTP/2 requests, the Go HTTP server always permits concurrent reads and responses, so this option has no effect.
+
+Test thoroughly with your HTTP clients, as some older clients may not support full-duplex HTTP/1 which can cause them to deadlock. See [golang/go#57786](https://github.com/golang/go/issues/57786) for more info.
+
+⚠️ This is an experimental feature. Subject to change or removal.
 
 
 ##### `log_credentials`
@@ -591,13 +605,29 @@ A key pair (certificate and private key) to use as the intermediate for the CA.
 
 ## Event Options
 
-Caddy modules emit events when interesting things happen (or are about to happen).
+Caddy modules emit events when interesting things happen (or are about to happen). 
+
+Events typically include a metadata payload. The best way to learn about events and their payloads is from each module's documentation, but you may also see the events and their data payloads by enabling the [`debug` global option](#debug) and reading the logs.
 
 ##### `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):
+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), with a part of the event payload being passed to the script using a placeholder:
 
-```caddy-d
-on cert_obtained exec systemctl reload mydaemon
+```caddy
+{
+	events {
+		on cert_obtained exec ./my-script.sh {event.data.certificate_path}
+	}
+}
 ```
+
+### Events
+
+These standard events are emitted by Caddy:
+
+- [`tls` events <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/caddyserver/certmagic#events)
+- [`reverse_proxy` events](/docs/caddyfile/directives/reverse_proxy#events)
+
+Plugins may also emit events, so check their documentation for details.