diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index 34475ce..df512ce 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -21,6 +21,7 @@ file_server [] [browse] { precompressed status disable_canonical_uris + pass_thru } ``` @@ -32,6 +33,7 @@ file_server [] [browse] { - **precompressed** is the list of encoding formats to search for precompressed sidecar files. Arguments are an ordered list of encoding formats to search for precompressed sidecar files. Supported formats are `gzip`, `zstd` and `br`. - **status** is an optional status code override to be used when writing the response. Particularly useful when responding to a request with a custom error page. Can be a 3-digit status code, For example: `404`. Placeholders are supported. By default, the written status code will typically be `200`, or `206` for partial content. - **disable_canonical_uris** disables the default behaviour of redirecting to add a trailing slash if the request path is a directory, or remove the trailing slash if the request path is a file. Note that by default, canonicalization will not happen if the last element of the request's path (the filename) underwent an internal rewrite, to avoid clobbering an explicit rewrite with implicit behaviour. +- **pass_thru** enables pass-thru mode, which continues to the next HTTP handler in the route if the requested file is not found, instead of returning a 404. ## Examples diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 371d89e..a01675d 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -48,8 +48,8 @@ Proxies requests to one or more backends with configurable transport, load balan ```caddy-d reverse_proxy [] [] { # backends - to - ... + to + dynamic ... # load balancing lb_policy [] @@ -106,6 +106,10 @@ reverse_proxy [] [] { - **<upstreams...>** 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. +- **dynamic** configures a _dynamic upstreams_ module. This allows getting the list of upstreams dynamically for every request. See [dynamic upstreams](#dynamic-upstreams) below for a description of standard dynamic upstream modules. Dynamic upstreams are retrieved at every proxy loop iteration (i.e. potentially multiple times per request if load balancing retries are enabled) and will be preferred over static upstreams. If an error occurs, the proxy will fall back to using any statically-configured upstreams. + + +### Upstream addresses 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, with a special exception that the scheme may be prefixed by `srv+` to enable SRV DNS record lookups for load balancing. Valid examples: @@ -128,6 +132,61 @@ If the address is not a URL (i.e. does not have a scheme), then placeholders can When proxying over HTTPS, you may need to override the `Host` header (which by default, retains the value from the original request) such that the `Host` header matches the TLS SNI value, which is used by servers for routing and certificate selection. See the [Headers](#headers) section below for more details. +#### Dynamic upstreams + +Caddy's reverse proxy comes standard with some dynamic upstream modules. Note that using dynamic upstreams has implications for load balancing and health checks, depending on specific policy configuration: active health checks do not run for dynamic upstreams; and load balancing and passive health checks are best served if the list of upstreams is relatively stable and consistent (especially with round-robin). + + +##### SRV + +Retrieves upstreams from SRV DNS records. + +```caddy-d + dynamic srv [] { + service + proto + name + refresh + resolvers + dial_timeout + dial_fallback_delay + } +``` + +- **<name>** - The full domain name of the record to look up (i.e. `_service._proto.name`). +- **service** - The service component of the full name. +- **proto** - The protocol component of the full name. Either `tcp` or `udp`. +- **name** - The name component. Or, if `service` and `proto` are empty, the full domain name to query. +- **refresh** - How often to refresh cached results. Default: `1m` +- **resolvers** - List of resolvers to override system resolvers. +- **dial_timeout** - Timeout for dialing the query. +- **dial_fallback_delay** - Timeout for falling back from IPv6 to IPv6 via RFC 6555. Default: `300ms` + + + +##### A/AAAA + +Retrieves upstreams from A/AAAA DNS records. + +```caddy-d + dynamic a [ ] { + name + port + refresh + resolvers + dial_timeout + dial_fallback_delay + } +``` + +- **<name>, name** - The domain name to query. +- **<port>, port** - The port to use for the backend. +- **refresh** - How often to refresh cached results. Default: `1m` +- **resolvers** - List of resolvers to override system resolvers. +- **dial_timeout** - Timeout for dialing the query. +- **dial_fallback_delay** - Timeout for falling back from IPv6 to IPv6 via RFC 6555. Default: `300ms` + + ### Load balancing @@ -420,3 +479,19 @@ reverse_proxy localhost:8080 { } } ``` + +Get backends dynamically from A/AAAA record DNS queries: + +```caddy-d +reverse_proxy { + dynamic a example.com 9000 +} +``` + +Get backends dynamically from SRV record DNS queries: + +```caddy-d +reverse_proxy { + dynamic srv _api._tcp.example.com +} +``` diff --git a/src/docs/markdown/caddyfile/matchers.md b/src/docs/markdown/caddyfile/matchers.md index 2951c9f..e273cf1 100644 --- a/src/docs/markdown/caddyfile/matchers.md +++ b/src/docs/markdown/caddyfile/matchers.md @@ -518,7 +518,7 @@ query sort=asc remote_ip [forwarded] ``` -By remote (client) IP address. Accepts exact IPs or CIDR ranges. If the first argument is `forwarded`, then the first IP in the `X-Forwarded-For` request header, if present, will be preferred as the reference IP, rather than the immediate peer's IP, which is the default. +By remote (client) IP address. Accepts exact IPs or CIDR ranges. If the first argument is `forwarded`, then the first IP in the `X-Forwarded-For` request header, if present, will be preferred as the reference IP, rather than the immediate peer's IP, which is the default. IPv6 zones are supported. Multiple `remote_ip` matchers will be OR'ed together. diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 01cdfcd..0e6d5bf 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -65,7 +65,7 @@ Possible options are: grace_period # TLS Options - auto_https off|disable_redirects|ignore_loaded_certs + auto_https off|disable_redirects|ignore_loaded_certs|disable_certs email default_sni local_certs @@ -205,7 +205,14 @@ Defines the grace period for shutting down HTTP servers during config reloads. I ## TLS Options ##### `auto_https` -Configure automatic HTTPS. It can be disabled entirely (`off`), disable only HTTP-to-HTTPS redirects (`disable_redirects`), or be configured to automate certificates even for names which appear on manually-loaded certificates (`ignore_loaded_certs`). See the [Automatic HTTPS](/docs/automatic-https) page for more details. +Configure automatic HTTPS. There are a few modes to choose from: + +- `off`: Disabled entirely. No certificate management or redirects. +- `disable_redirects`: Disable only HTTP-to-HTTPS redirects. +- `disable_certs`: Disable only certificate automation. +- `ignore_loaded_certs`: Automate certificates even for names which appear on manually-loaded certificates + +See the [Automatic HTTPS](/docs/automatic-https) page for more details. ##### `email`