From 7c99a9ab17a5c04d5275ac8a443f1749bfb003d5 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Wed, 8 Feb 2023 17:10:09 -0500 Subject: [PATCH] Docs for v2.6.3 (#296) --- src/docs/markdown/api.md | 2 + .../markdown/caddyfile/directives/import.md | 12 +++++- .../caddyfile/directives/reverse_proxy.md | 20 +++------- src/docs/markdown/caddyfile/directives/tls.md | 17 +++++++- .../markdown/caddyfile/directives/tracing.md | 10 +++-- src/docs/markdown/caddyfile/options.md | 39 +++++++++++++++++++ src/docs/markdown/command-line.md | 10 ++++- 7 files changed, 87 insertions(+), 23 deletions(-) diff --git a/src/docs/markdown/api.md b/src/docs/markdown/api.md index b8f5b9a..d2d846d 100644 --- a/src/docs/markdown/api.md +++ b/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. + diff --git a/src/docs/markdown/caddyfile/directives/import.md b/src/docs/markdown/caddyfile/directives/import.md index f5fcda6..cfa849f 100644 --- a/src/docs/markdown/caddyfile/directives/import.md +++ b/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>** 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. +- **<pattern>** 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. - **<args...>** 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/* diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 09b2034..7557ad3 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/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. - 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. + For these `X-Forwarded-*` headers, by default, the proxy will ignore their values from incoming requests, to prevent spoofing. -```caddy-d -trusted_proxies private_ranges -``` +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. + +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. -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 diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index 2b02766..4d3665a 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -31,6 +31,9 @@ tls [internal|] | [ ] { ca_root key_type ed25519|p256|p384|rsa2048|rsa4096 dns [] + propagation_timeout + propagation_delay + dns_ttl dns_challenge_override_domain resolvers eab @@ -95,6 +98,12 @@ tls [internal|] | [ ] { - **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** 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** 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** is a [duration value](/docs/conventions#durations) that sets the TTL of the TXT record used for the DNS challenge. + - **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** 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. @@ -154,7 +163,9 @@ Obtains certificates using the ACME protocol. trusted_roots dns [] propagation_timeout - propagation_delay + propagation_delay + dns_ttl + dns_challenge_override_domain resolvers preferred_chains [smallest] { root_common_name @@ -189,6 +200,10 @@ Obtains certificates using the ACME protocol. - **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** is a [duration value](/docs/conventions#durations) that sets the TTL of the TXT record used for the DNS challenge. + +- **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** customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones. - **preferred_chains** specifies which certificate chains Caddy should prefer; useful if your CA provides multiple chains. Use one of the following options: diff --git a/src/docs/markdown/caddyfile/directives/tracing.md b/src/docs/markdown/caddyfile/directives/tracing.md index e74cd7e..39fecd4 100644 --- a/src/docs/markdown/caddyfile/directives/tracing.md +++ b/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: -``` -handle /myHandler { +```caddy-d +handle /example* { tracing { - span my-span + span example } reverse_proxy 127.0.0.1:8081 } diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index e780c28..adc253b 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -61,6 +61,7 @@ Possible options are: origins enforce_origin } + persist_config off log [name] { output ... format ... @@ -106,6 +107,7 @@ Possible options are: write idle } + trusted_proxies ... metrics max_header_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] +``` + +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!) diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 03c5a93..6edf556 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -208,7 +208,7 @@ This command disables the admin API, making it easier to run multiple instances 
caddy fmt [--overwrite] [--diff] [<path>]
-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. `` 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 <addr>] --to <addr> [--change-host-header] + [--disable-redirects] [--internal-certs] [--debug] @@ -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 
caddy validate
 	[--config <path>]
-	[--adapter <name>]
+ [--adapter <name>] + [--envfile <file>] 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`