Docs for v2.6.3 (#296)

src/docs/markdown/api.md

@@ -8,6 +8,8 @@ Caddy is configured through an administration endpoint which can be accessed via
 
 **Default address: `localhost:2019`**
 
+The default address can be changed by setting the `CADDY_ADMIN` environment variable. Some installation methods may set this to something different. The address in the Caddy config always takes precedence over the default.
+
 <aside class="tip">
 	If you are running untrusted code on your server (yikes 😬), make sure you protect your admin endpoint by isolating processes, patching vulnerable programs, and configuring the endpoint to bind to a permissioned unix socket instead.
 </aside>

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

@@ -14,13 +14,21 @@ This directive is a special case: it is evaluated before the structure is parsed
 import <pattern> [<args...>]
 ```
 
-- **&lt;pattern&gt;** is the filename, glob pattern, or name of [snippet](/docs/caddyfile/concepts#snippets) to include. Its contents will replace this line as if that file's contents appeared here to begin with. It is an error if a specific file cannot be found, but an empty glob pattern is not an error. If the pattern is a filename or glob, it is always relative to the file the `import` appears in.
+- **&lt;pattern&gt;** is the filename, glob pattern, or name of [snippet](/docs/caddyfile/concepts#snippets) to include. Its contents will replace this line as if that file's contents appeared here to begin with.
+
+  It is an error if a specific file cannot be found, but an empty glob pattern is not an error.
+
+  If importing a specific file, a warning will be emitted if the file is empty.
+
+  If the pattern is a filename or glob, it is always relative to the file the `import` appears in.
+
+  If using a glob pattern `*` as the final path segment, hidden files (i.e. files starting with a `.`) are ignored. To import hidden files, use `.*` as the final segment.
 - **&lt;args...&gt;** is an optional list of arguments to pass to the imported tokens. They can be used with a placeholder of the form `{args.N}` where `N` is the 0-based positional index of the parameter. This placeholder is a special case and is evaluated at parse-time, not run-time.
 
 
 ## Examples
 
-Import all files in an adjacent sites-enabled folder:
+Import all files in an adjacent sites-enabled folder (except hidden files):
 
 ```caddy-d
 import sites-enabled/*

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

@@ -390,11 +390,11 @@ By default, Caddy passes thru incoming headers—including `Host`—to t
 - It sets the [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) header field.
 - It sets the [`X-Forwarded-Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) header field.
 
-<span id="trusted_proxies"/> For these `X-Forwarded-*` headers, by default, Caddy will ignore their values from incoming requests, to prevent spoofing. If Caddy is not the first server being connected to by your clients (for example when a CDN is in front of Caddy), you may configure `trusted_proxies` with a list of IP ranges (CIDRs) from which incoming requests are trusted to have sent good values for these headers. As a shortcut, `private_ranges` may be configured to trust all private IP ranges.
+<span id="trusted_proxies"/> For these `X-Forwarded-*` headers, by default, the proxy will ignore their values from incoming requests, to prevent spoofing.
 
-```caddy-d
+If Caddy is not the first server being connected to by your clients (for example when a CDN is in front of Caddy), you may configure `trusted_proxies` with a list of IP ranges (CIDRs) from which incoming requests are trusted to have sent good values for these headers.
-trusted_proxies private_ranges
+
-```
+It is recommended that you configure this via the [`servers > trusted_proxies` global option](/docs/caddyfile/options#trusted_proxies) so that this applies to all proxy handlers in your server, without repetition.
 
 <aside class="tip">
 
@@ -402,7 +402,8 @@ If you're using Cloudflare in front of Caddy, be aware that you may be vulnerabl
 
 </aside>
 
-Additionally, when using the [`http` transport](#the-http-transport), the `Accept-Encoding: gzip` header will be set, if it is missing in the request from the client. This behavior can be disabled with [`compression off`](#compression) on the transport.
+Additionally, when using the [`http` transport](#the-http-transport), the `Accept-Encoding: gzip` header will be set, if it is missing in the request from the client. This allows the upstream to serve compressed content if it can. This behavior can be disabled with [`compression off`](#compression) on the transport.
+
 
 #### HTTPS
 
@@ -678,15 +679,6 @@ handle_path /old-prefix/* {
 ```
 
 
-When Caddy is behind another proxy or load balancer whose IP is `123.123.123.123`, which may set `X-Forwarded-*` headers to identify details about the original client request, that downstream proxy must be listed as trusted, otherwise Caddy will ignore those incoming headers:
-
-```caddy-d
-reverse_proxy localhost:8080 {
-	trusted_proxies 123.123.123.123
-}
-```
-
-
 X-Accel-Redirect support, i.e. serving static files as requested by the proxy upstream:
 
 ```caddy-d

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

@@ -31,6 +31,9 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 	ca_root   <pem_file>
 	key_type  ed25519|p256|p384|rsa2048|rsa4096
 	dns       <provider_name> [<params...>]
+	propagation_timeout <duration>
+	propagation_delay   <duration>
+	dns_ttl             <duration>
 	dns_challenge_override_domain <domain>
 	resolvers <dns_servers...>
 	eab       <key_id> <mac_key>
@@ -95,6 +98,12 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 
 - **dns** <span id="dns"/> enables the [DNS challenge](/docs/automatic-https#dns-challenge) using the specified provider plugin, which must be plugged in from one of the [`caddy-dns`](https://github.com/caddy-dns) repositories. Each provider plugin may have their own syntax following their name; refer to their docs for details. Maintaining support for each DNS provider is a community effort. [Learn how to enable the DNS challenge for your provider at our wiki.](https://caddy.community/t/how-to-use-dns-provider-modules-in-caddy-2/8148)
 
+- **propagation_timeout** <span id="propagation_timeout"/> is a [duration value](/docs/conventions#durations) that sets the maximum time to wait for the DNS TXT records to appear when using the DNS challenge. Set to `-1` to disable propagation checks. Default 2 minutes.
+
+- **propagation_delay** <span id="propagation_delay"/> is a [duration value](/docs/conventions#durations) that sets how long to wait before starting DNS TXT records propagation checks when using the DNS challenge. Default 0 (no wait).
+
+- **dns_ttl** <span id="dns_ttl"/> is a [duration value](/docs/conventions#durations) that sets the TTL of the TXT record used for the DNS challenge.
+
 - **dns_challenge_override_domain** <span id="dns_challenge_override_domain"/> overrides the domain to use for the DNS challenge. This is to delegate the challenge to a different domain, e.g. one whose DNS provider has a [`caddy-dns`](https://github.com/caddy-dns) plugin.
 
 - **resolvers** <span id="resolvers"/> customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones. If set here, the resolvers will propagate to all configured certificate issuers.
@@ -155,6 +164,8 @@ Obtains certificates using the ACME protocol.
 	dns <provider_name> [<options>]
 	propagation_timeout <duration>
 	propagation_delay   <duration>
+	dns_ttl             <duration>
+	dns_challenge_override_domain <domain>
 	resolvers <dns_servers...>
 	preferred_chains [smallest] {
 		root_common_name <common_names...>
@@ -189,6 +200,10 @@ Obtains certificates using the ACME protocol.
 
 - **propagation_delay** <span id="propagation_delay"/> is a [duration value](/docs/conventions#durations) that sets how long to wait before starting DNS TXT records propagation checks when using the DNS challenge. Default 0 (no wait).
 
+- **dns_ttl** <span id="dns_ttl"/> is a [duration value](/docs/conventions#durations) that sets the TTL of the TXT record used for the DNS challenge.
+
+- **dns_challenge_override_domain** <span id="dns_challenge_override_domain"/> overrides the domain to use for the DNS challenge. This is to delegate the challenge to a different domain, e.g. one whose DNS provider has a [`caddy-dns`](https://github.com/caddy-dns) plugin.
+
 - **resolvers** <span id="resolvers"/> customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones.
 
 - **preferred_chains** <span id="preferred_chains"/> specifies which certificate chains Caddy should prefer; useful if your CA provides multiple chains. Use one of the following options:

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

@@ -20,7 +20,9 @@ tracing {
 }
 ```
 
-- **<span_name>** - is a span name. Please see span naming [guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/specification/trace/api.md).
+- **<span_name>** is a span name. Please see span [naming guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/specification/trace/api.md).
+
+  [Placeholders](/docs/caddyfile/concepts#placeholders) may be used in span names; keep in mind that tracing happens as early as possible, so only request placeholders may be used, and not response placeholders.
 
 ## Configuration
 
@@ -43,10 +45,10 @@ export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://my-otlp-endpoint:55680
 
 Here is a **Caddyfile** example:
 
-```
+```caddy-d
-handle /myHandler {
+handle /example* {
 	tracing {
-		span my-span
+		span example
 	}
 	reverse_proxy 127.0.0.1:8081
 }

src/docs/markdown/caddyfile/options.md

@@ -61,6 +61,7 @@ Possible options are:
 		origins <origins...>
 		enforce_origin
 	}
+	persist_config off
 	log [name] {
 		output  <writer_module> ...
 		format  <encoder_module> ...
@@ -106,6 +107,7 @@ Possible options are:
 			write       <duration>
 			idle        <duration>
 		}
+		trusted_proxies <module> ...
 		metrics
 		max_header_size <size>
 		log_credentials
@@ -216,6 +218,12 @@ Customizes the [admin API endpoint](/docs/api). Accepts placeholders. If `off`,
 - **enforce_origin** enables enforcement of the Origin header. (This is different from enforcing origins generally, which is always done.)
 
 
+##### `persist_config`
+
+Controls whether the current JSON config should be persisted to the [configuration directory](/docs/conventions#configuration-directory), to avoid losing config changes performed via the admin API. Currently, only the `off` option is supported. By default, the config is persisted.
+
+
+
 ##### `log`
 Configures named loggers. The name can be passed to indicate a specific logger for which to customize the behavior. If no name is specified, the behavior of the `default` logger is modified. Multiple loggers with different names can be configured by using the `log` multiple times. You can read more about the `default` logger and an explanation of [how logging works in Caddy](/docs/logging).
 
@@ -432,6 +440,37 @@ listener_wrappers {
 - **idle** is a [duration value](/docs/conventions#durations) that sets the maximum time to wait for the next request when keep-alives are enabled. Defaults to 5 minutes to help avoid resource exhaustion.
 
 
+
+##### `trusted_proxies`
+
+Allows configuring IP ranges (CIDRs) of proxy servers from which requests should be trusted. By default, no proxies are trusted.
+
+On its own, this configuration will not do anything, but it can be used to signal to handlers or matchers in HTTP routes that the request is trusted. See the [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy#defaults) handler for example, which uses this to trust sensitive incoming `X-Forwarded-*` headers.
+
+Currently, only the `static` [IP source module](/docs/json/apps/http/servers/trusted_proxies) is included with the standard distribution of Caddy, but this can be [extended](/docs/extending-caddy) with plugins to maintain a dynamic list of IP ranges.
+
+###### `static`
+
+Takes a static (unchanging) list of IP ranges (CIDRs) to trust.
+
+As a shortcut, `private_ranges` can be used to match all private IPv4 and IPv6 ranges. It's the same as specifying all of these ranges: `192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8 fd00::/8 ::1`
+
+```caddy-d
+trusted_proxies static [private_ranges] <ranges...>
+```
+
+Here's a complete example, trusting an example IPv4 range and an IPv6 range:
+
+```caddy
+{
+	servers {
+		trusted_proxies static 12.34.56.0/24 1200:ab00::/32
+	}
+}
+```
+
+
+
 ##### `metrics`
 
 Enables Prometheus metrics collection; necessary before scraping metrics. Note that metrics reduce performance on really busy servers. (Our community is working on improving this. Please get involved!)

src/docs/markdown/command-line.md

@@ -208,7 +208,7 @@ This command disables the admin API, making it easier to run multiple instances
 
 <pre><code class="cmd bash">caddy fmt [--overwrite] [--diff] [&lt;path&gt;]</code></pre>
 
-Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless `--overwrite` is used.
+Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless `--overwrite` is used, and will exit with code `1` if there are any differences.
 
 `<path>` specifies the path to the Caddyfile. If `-`, the input is read from stdin. If omitted, a file named Caddyfile in the current directory is assumed instead.
 
@@ -376,6 +376,7 @@ Pipe in a maintenance page:
 	[--from &lt;addr&gt;]
 	--to &lt;addr&gt;
 	[--change-host-header]
+	[--disable-redirects]
 	[--internal-certs]
 	[--debug]</code></pre>
 
@@ -387,6 +388,8 @@ Spins up a simple but production-ready HTTP(S) reverse proxy.
 
 `--change-host-header` will cause Caddy to change the Host header from the incoming value to the address of the upstream.
 
+`--disable-redirects` prevents Automatic HTTPS from enabling the HTTP->HTTPS redirects, if the `--from` address would enable HTTPS.
+
 `--internal-certs` will cause Caddy to issue certificates using its internal issuer (effectively self-signed) for the domain specified in the `--from` address.
 
 `--debug` enables verbose logging.
@@ -548,7 +551,8 @@ Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest
 
 <pre><code class="cmd bash">caddy validate
 	[--config &lt;path&gt;]
-	[--adapter &lt;name&gt;]</code></pre>
+	[--adapter &lt;name&gt;]
+	[--envfile &lt;file&gt;]</code></pre>
 
 Validates a configuration file, then exits. This command deserializes the config, then loads and provisions all of its modules as if to start the config, but the config is not actually started. This exposes errors in a configuration that arise during loading or provisioning phases and is a stronger error check than merely serializing a config as JSON.
 
@@ -556,6 +560,8 @@ Validates a configuration file, then exits. This command deserializes the config
 
 `--adapter` is the name of the config adapter to use, if the config file is not in Caddy's native JSON format. If the config file starts with `Caddyfile`, the `caddyfile` adapter is used by default.
 
+`--envfile` loads environment variables from the specified file, in `KEY=VALUE` format. Comments starting with `#` are supported; keys may be prefixed with `export`; values may be double-quoted (double-quotes within can be escaped); multi-line values are supported.
+
 
 
 ### `caddy version`