docs: Update for beta 15

src/docs/markdown/caddyfile/concepts.md

@@ -163,7 +163,7 @@ By default, a directive that injects an HTTP handler applies to all requests (un
 
 **Request matchers** can be used to classify requests by a given criteria. This concept originates in the [underlying JSON](/docs/json/apps/http/servers/routes/match/) structure, and it's important to know how to use them in the Caddyfile. With matchers, you can specify exactly which requests a directive applies to.
 
-To limit a directive's scope, use a **matcher token** immediately after the directive, [if the directive supports matchers](/docs/caddyfile/directives#matchers). The matcher token can be one of these forms:
+To limit a directive's scope, use a **matcher token** immediately following the directive, [if the directive supports matchers](/docs/caddyfile/directives#matchers). The matcher token can be one of these forms:
 
 1. **`*`** to match all requests (wildcard; default).
 2. **`/path`** start with a forward slash to match a request path.

src/docs/markdown/caddyfile/directives.md

@@ -14,6 +14,7 @@ Directive | Description
 **[file_server](/docs/caddyfile/directives/file_server)** | Serve files from disk
 **[handle](/docs/caddyfile/directives/handle)** | A mutually-exclusive group of directives
 **[header](/docs/caddyfile/directives/header)** | Sets or removes response headers
+**[log](/docs/caddyfile/directives/log)** | Enables access/request logging
 **[php_fastcgi](/docs/caddyfile/directives/php_fastcgi)** | Serve PHP sites over FastCGI
 **[redir](/docs/caddyfile/directives/redir)** | Issues an HTTP redirect to the client
 **[request_header](/docs/caddyfile/directives/request_header)** | Manipulates request headers

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

@@ -0,0 +1,186 @@
+---
+title: log (Caddyfile directive)
+---
+
+# log
+
+Enables and configures HTTP request logging (also known as access logs).
+
+## Syntax
+
+```
+log {
+	output <writer_module> ...
+	format <encoder_module> ...
+	level  <level>
+}
+```
+
+- **output** configures a where to write the logs to. 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`
+- **level** is the minimum entry level to log. Default: `INFO`
+
+### Output modules
+
+The **output** subdirective lets you customize where logs get written. It appears within a `log` block.
+
+#### stderr
+
+Standard error (console, default).
+
+```
+output stderr
+```
+
+#### stdout
+
+Standard output (console).
+
+```
+output stderr
+```
+
+#### discard
+
+No output.
+
+```
+output discard
+```
+
+#### file
+
+A file. By default, log files are rotated ("rolled") to prevent disk space exhaustion.
+
+```
+output file <filename> {
+	roll_disabled
+	roll_size     <size>
+	roll_keep     <num>
+	roll_keep_for <days>
+}
+```
+
+- **&lt;filename&gt;** is the path to the log file.
+- **roll_disabled** disables log rolling. This can lead to disk space depletion, so only use this if your log files are maintained some other way.
+- **roll_size** is the size at which to roll the log file. Default: `100MiB`
+- **roll_keep** is how many log files to keep before deleting the oldest ones. Default: `10`
+- **roll_keep_for** is how long to keep rolled files. Default: 90 days
+
+
+#### net
+
+A network socket.
+
+```
+output net <address>
+```
+
+- **&lt;address&gt;** is the [address](/docs/conventions#network-addresses) to write logs to.
+
+
+
+### Format modules
+
+The **format** subdirective lets you customize how logs get encoded (formatted). It appears within a `log` block.
+
+In addition to the syntax for each individual encoder, these common properties can be set on most encoders:
+
+```
+{
+	message_key <key>
+	level_key   <key>
+	time_key    <key>
+	name_key    <key>
+	caller_key  <key>
+	stacktrace_key <key>
+	line_ending  <char>
+	time_format  <format>
+	level_format <format>
+}
+```
+
+- **message_key** The key for the message field of the log entry. Default: `message`
+- **level_key** The key for the level field of the log entry. Default: `level`
+- **time_key** The key for the time field of the log entry. Default: `time`
+- **name_key** The key for the name field of the log entry (i.e. the name of the logger itself). Default: `name`
+- **caller_key** The key for the caller field of the log entry.
+- **stacktrace_key** The key for the stacktrace field of the log entry.
+- **line_ending** The line endings to use.
+- **time_format** The format for timestamps.
+- **level_format** The format for levels.
+
+#### console
+
+The console encoder formats the log entry for human readability while preserving some structure.
+
+```
+output console
+```
+
+#### json
+
+Formats each log entry as a JSON object.
+
+```
+output json
+```
+
+#### logfmt
+
+Formats each log entry as [logfmt](https://brandur.org/logfmt).
+
+```
+output logfmt
+```
+
+#### single_field
+
+Writes only a single field from the structure log entry. Useful if one of the fields has all the information you need.
+
+```
+output single_field <field_name>
+```
+
+- **&lt;field_name&gt;** is the name of the field whose value to use as the log entry.
+
+
+
+
+
+
+
+## Examples
+
+Enable access logging (to the console):
+
+```
+log
+```
+
+Write logs to a file (with log rolling, which is enabled by default):
+
+```
+log {
+	output file /var/log/access.log
+}
+```
+
+Customize log rolling:
+
+```
+log {
+	output file /var/log/access.log {
+		roll_size 1gb
+		roll_keep 5
+	}
+}
+```
+
+Use common log format (deprecated, but can be useful for older setups):
+
+```
+log {
+	format single_field common_log
+}
+```

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

@@ -52,6 +52,17 @@ reverse_proxy [<matcher>] [<upstreams...>] {
 - **&lt;upstreams...&gt;** is a list of upstreams (backends) to which to proxy.
 - **to** is an alternate way to specify the list of upstreams, one (or more) per line.
 
+Upstream addresses can take the form of a conventional [Caddy network address](/docs/conventions#network-addresses) or a URL that contains only scheme and host/port. Valid examples:
+
+- `localhost:4000`
+- `127.0.0.1:4000`
+- `http://localhost:4000`
+- `https://example.com`
+- `example.com`
+- `unix//var/php.sock`
+
+Note: Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Specifying ports 80 and 443 are the same as specifying the HTTP and HTTPS schemes, respectively. Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport. Additionally, schemes cannot contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported.
+
 **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:
@@ -93,6 +104,8 @@ It can also **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.
 
+By default, Caddy passes thru incoming headers to the backend&mdash;including the `Host` header&mdash;without modifications, with one exception: it adds or augments the [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) header field as is standard for well-mannered proxies.
+
 Caddy's proxy **transport** is pluggable:
 
 - **transport** defines how to communicate with the backend. Default is `http`.
@@ -119,7 +132,7 @@ The `http_ntlm` transport is identical to the `http` transport, but the HTTP ver
 - **read_buffer** is the size of the read buffer in bytes.
 - **write_buffer** is the size of the write buffer in bytes.
 - **dial_timeout** is how long to wait when connecting to the upstream socket.
-- **tls** uses HTTPS with the backend.
+- **tls** uses HTTPS with the backend. This will be enabled automatically if you specify backends using the `https://` scheme or port `:443`.
 - **tls_client_auth** specifies a certificate and key file to present for TLS client authentication with the backend.
 - **tls_insecure_skip_verify** turns off security. _Do not use in production._
 - **tls_timeout** is a [duration value](/docs/conventions#durations) that specifies how long to wait for the TLS handshake to complete.
@@ -164,13 +177,17 @@ reverse_proxy /api/* node1:80 node2:80 node3:80 {
 }
 ```
 
-Preserve original request Host and add common proxying headers:
+Set the upstream Host header to the address of the upstream (by default, it will retain its original, incoming value):
 
 ```
 reverse_proxy localhost:9000 {
-    header_up Host {host}
-    header_up X-Real-IP {remote_host}
-    header_up X-Forwarded-For {remote_host}
-    header_up X-Forwarded-Proto {scheme}
+    header_up Host {http.reverse_proxy.upstream.hostport}
 }
 ```
+
+Reverse proxy to an HTTPS endpoint:
+
+```
+reverse_proxy https://example.com
+```
+

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

@@ -21,6 +21,7 @@ tls <email>|[<cert_file> <key_file>] {
 	alpn      <values...>
 	load      <paths...>
 	ca        <ca_dir_url>
+	ca_root   <pem_file>
 }
 ```
 
@@ -55,6 +56,7 @@ tls <email>|[<cert_file> <key_file>] {
 - **alpn** is the list of values to advertise in the ALPN extension of the TLS handshake.
 - **load** specifies a list of folders from which to load PEM files that are certificate+key bundles.
 - **ca** changes the ACME CA endpoint. This is most often used to use [Let's Encrypt's staging endpoint](https://letsencrypt.org/docs/staging-environment/) or an internal ACME server. (To change this value for the whole Caddyfile, use the `acme_ca` [global option](/docs/caddyfile/options) instead.)
+- **ca_root** specifies a PEM file that contains a trusted root certificate for the ACME CA endpoint, if not in the system trust store.
 
 
 

src/docs/markdown/caddyfile/options.md

@@ -28,8 +28,10 @@ Possible options are:
 	}
 	experimental_http3
 	acme_ca <directory_url>
+	acme_ca_root <pem_file>
 	email   <yours>
-	admin   <addr>
+	admin   off|<addr>
+	debug
 }
 ```
 
@@ -39,5 +41,7 @@ Possible options are:
 - **storage** configures Caddy's storage mechanism. Default: `file_system`
 - **experimental_http3** enables experimental draft HTTP/3 support. Note that HTTP/3 is not a finished spec and client support is extremely limited. This option will go away in the future. _This option is not subject to compatibility promises._
 - **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: Let's Encrypt's production endpoint.
+- **acme_ca_root** specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store.
 - **email** is your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates.
-- **admin** customizes the admin API endpoint.
+- **admin** customizes the [admin API endpoint](/docs/api). If `off`, then the admin endpoint will be disabled.
+- **debug** enables debug mode, which sets all log levels to debug (unless otherwise specified).