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: