mirror of
https://github.com/caddyserver/website.git
synced 2025-04-22 13:06:16 -04:00
Docs for upcoming v2.5.0 release (#216)
* docs: new `log` filters in Caddyfile * docs: `renew_interval` global option * docs: Update access log example * docs: `log_credentials` global option * docs: `vars`, `vars_regexp` matchers * docs: `roll_uncompressed`, `roll_local_time` * docs: `http_redirect` listener wrapper * docs: `pki` app * docs: `strict_sni_host` options * docs: `default_bind` option * docs: `method` directive * docs: `tls internal` subdirectives * Apply suggestions from code review Co-authored-by: Matt Holt <mholt@users.noreply.github.com> * Matchers, options, file_server, reverse_proxy * More clarifications / corrections * Corrections from review * Typo fix * One more note about dynamic upstreams * Tab -> space * Update module namespaces * Update some docs about logging * `copy_response`, `copy_response_headers`, `replace_status` * `dns_challenge_domain_override` * `caddy trust`, API endpoints * `trusted_proxies` * Note about `pass_thru` being only useful inside `route` * Improve logging docs to clarify the difference * A bit of polish on patterns * request_body: Clarify error behavior * review Co-authored-by: Matt Holt <mholt@users.noreply.github.com>
This commit is contained in:
Francis Lavoie
GitHub
parent
c734cc3e64
commit
a1ddadf798
19 changed files with 575 additions and 157 deletions
|
|
@ -22,5 +22,5 @@ acme_server [<matcher>] {
|
|||
}
|
||||
```
|
||||
|
||||
- **ca** specifies the ID of the certificate authority with which to sign certificates. The default is `local`, which is Caddy's default CA, intended for locally-used, self-signed certificates, which is most common in dev environments. For broader use, it is recommended to specify a different CA to avoid confusion. If the CA with the given ID does not already exist, it will be created.
|
||||
- **ca** specifies the ID of the certificate authority with which to sign certificates. The default is `local`, which is Caddy's default CA, intended for locally-used, self-signed certificates, which is most common in dev environments. For broader use, it is recommended to specify a different CA to avoid confusion. If the CA with the given ID does not already exist, it will be created. See the [PKI app global options](/docs/caddyfile/options#pki-options) to configure alternate CAs.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,6 +21,7 @@ file_server [<matcher>] [browse] {
|
|||
precompressed <formats...>
|
||||
status <status>
|
||||
disable_canonical_uris
|
||||
pass_thru
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -32,6 +33,7 @@ file_server [<matcher>] [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`. Practically, this is likely only be useful inside of a [`route`](/docs/caddyfile/directives/route) block, because the `file_server` directive is effectively [ordered last](/docs/caddyfile/directives#directive-order) otherwise.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -13,6 +13,10 @@ $(function() {
|
|||
|
||||
Enables and configures HTTP request logging (also known as access logs).
|
||||
|
||||
<aside class="tip">
|
||||
If you're looking to configure Caddy's runtime logs, you're looking for the <a href="/docs/caddyfile/options#log"><code>log</code> global option</a> instead.
|
||||
</aside>
|
||||
|
||||
The `log` directive applies to the host/port of the site block it appears in, not any other part of the site address (e.g. path).
|
||||
|
||||
- [Syntax](#syntax)
|
||||
|
|
@ -25,13 +29,18 @@ The `log` directive applies to the host/port of the site block it appears in, no
|
|||
- [Format modules](#format-modules)
|
||||
- [console](#console)
|
||||
- [json](#json)
|
||||
- [single_field](#single-field)
|
||||
- [filter](#filter)
|
||||
- [delete](#delete)
|
||||
- [replace](#replace)
|
||||
- [ip_mask](#ip-mask)
|
||||
- [query](#query)
|
||||
- [cookie](#cookie)
|
||||
- [regexp](#regexp)
|
||||
- [hash](#hash)
|
||||
- [Examples](#examples)
|
||||
|
||||
Since Caddy v2.5, by default, headers with potentially sensitive information (`Cookie`, `Set-Cookie`, `Authorization` and `Proxy-Authorization`) will be logged with empty values. This behaviour can be disabled with the [`log_credentials`](/docs/caddyfile/options#log-credentials) global server option.
|
||||
|
||||
|
||||
## Syntax
|
||||
|
||||
|
|
@ -85,6 +94,8 @@ A file. By default, log files are rotated ("rolled") to prevent disk space exhau
|
|||
output file <filename> {
|
||||
roll_disabled
|
||||
roll_size <size>
|
||||
roll_uncompressed
|
||||
roll_local_time
|
||||
roll_keep <num>
|
||||
roll_keep_for <days>
|
||||
}
|
||||
|
|
@ -93,6 +104,8 @@ output file <filename> {
|
|||
- **<filename>** 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. The current implementation supports megabyte resolution; fractional values are rounded up to the next whole megabyte. For example, `1.1MiB` is rounded up to `2MiB`. Default: `100MiB`
|
||||
- **roll_uncompressed** turns off gzip log compression. Default: gzip compression is enabled.
|
||||
- **roll_local_time** sets the rolling to use local timestamps in filenames. Default: uses UTC time.
|
||||
- **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 as a [duration string](/docs/conventions#durations). The current implementation supports day resolution; fractional values are rounded up to the next whole day. For example, `36h` (1.5 days) is rounded up to `48h` (2 days). Default: `2160h` (90 days)
|
||||
|
||||
|
|
@ -116,6 +129,10 @@ output net <address> {
|
|||
|
||||
The **format** subdirective lets you customize how logs get encoded (formatted). It appears within a `log` block.
|
||||
|
||||
<aside class="tip">
|
||||
<b>A note about Common Log Format (CLF):</b> CLF clashes with modern structured logs. To transform your access logs into the deprecated Common Log Format, please use the <a href="https://github.com/caddyserver/transform-encoder"><code>transform-encoder</code> plugin</a>.
|
||||
</aside>
|
||||
|
||||
In addition to the syntax for each individual encoder, these common properties can be set on most encoders:
|
||||
|
||||
```caddy-d
|
||||
|
|
@ -158,17 +175,6 @@ Formats each log entry as a JSON object.
|
|||
format json
|
||||
```
|
||||
|
||||
#### single_field
|
||||
|
||||
<span class="warning">⚠️ This format is deprecated, and will be removed in a future version.</span>
|
||||
|
||||
Writes only a single field from the structure log entry. Useful if one of the fields has all the information you need.
|
||||
|
||||
```caddy-d
|
||||
format single_field <field_name>
|
||||
```
|
||||
|
||||
- **<field_name>** is the name of the field whose value to use as the log entry.
|
||||
|
||||
#### filter
|
||||
|
||||
|
|
@ -207,8 +213,7 @@ Marks a field to be replaced with the provided string at encoding time.
|
|||
|
||||
##### ip_mask
|
||||
|
||||
Masks IP addresses in the field using a CIDR mask, i.e. the number of bytes from the IP to retain, starting from the left side. There is separate configuration for IPv4 and IPv6 addresses.
|
||||
|
||||
Masks IP addresses in the field using a CIDR mask, i.e. the number of bytes from the IP to retain, starting from the left side. There is separate configuration for IPv4 and IPv6 addresses. Most commonly, the field to filter would be `request>remote_ip`.
|
||||
|
||||
```caddy-d
|
||||
<field> ip_mask {
|
||||
|
|
@ -217,6 +222,59 @@ Masks IP addresses in the field using a CIDR mask, i.e. the number of bytes from
|
|||
}
|
||||
```
|
||||
|
||||
##### query
|
||||
|
||||
Marks a field to have one or more actions performed, to manipulate the query part of a URL field. Most commonly, the field to filter would be `uri`. The available actions are:
|
||||
|
||||
```caddy-d
|
||||
<field> query {
|
||||
delete <key>
|
||||
replace <key> <replacement>
|
||||
hash <key>
|
||||
}
|
||||
```
|
||||
|
||||
- **delete** removes the given key from the query.
|
||||
- **replace** replaces the value of the given query key with **replacement**. Useful to insert a redaction placeholder; you'll see that the query key was in the URL, but the value is hidden.
|
||||
- **hash** replaces the value of the given query key with the first 4 bytes of the SHA-256 hash of the value, lowercase hexadecimal. Useful to obscure the value if it's sensitive, while being able to notice whether each request had a different value.
|
||||
|
||||
##### cookie
|
||||
|
||||
Marks a field to have one or more actions performed, to manipulate a `Cookie` HTTP header's value. Most commonly, the field to filter would be `request>headers>Cookie`. The available actions are:
|
||||
|
||||
```caddy-d
|
||||
<field> cookie {
|
||||
delete <name>
|
||||
replace <name> <replacement>
|
||||
hash <name>
|
||||
}
|
||||
```
|
||||
|
||||
- **delete** removes the given cookie by name from the header.
|
||||
- **replace** replaces the value of the given cookie with **replacement**. Useful to insert a redaction placeholder; you'll see that the cookie was in the header, but the value is hidden.
|
||||
- **hash** replaces the value of the given cookie with the first 4 bytes of the SHA-256 hash of the value, lowercase hexadecimal. Useful to obscure the value if it's sensitive, while being able to notice whether each request had a different value.
|
||||
|
||||
If many actions are defined for the same cookie name, only the first action will be applied.
|
||||
|
||||
##### regexp
|
||||
|
||||
Marks a field to have a regular expression replacement applied at encoding time.
|
||||
|
||||
```caddy-d
|
||||
<field> regexp <pattern> <replacement>
|
||||
```
|
||||
|
||||
The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax).
|
||||
|
||||
In the replacement string, capture groups can be referenced with `${group}` where `group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
|
||||
|
||||
##### hash
|
||||
|
||||
Marks a field to be replaced with the first 4 bytes of the SHA-256 hash of the value at encoding time. Useful to obscure the value if it's sensitive, while being able to notice whether each request had a different value.
|
||||
|
||||
```caddy-d
|
||||
<field> hash
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
|
@ -250,18 +308,6 @@ log {
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
Use Common Log Format (CLF):
|
||||
|
||||
<span class="warning">⚠️ The `single_field` format is deprecated and will be removed in a future version. To encode logs in common log format, please use the [`format-encoder`](https://github.com/caddyserver/format-encoder) plugin.</span>
|
||||
|
||||
```caddy-d
|
||||
log {
|
||||
format single_field common_log
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Delete the Authorization request header from the logs:
|
||||
|
||||
```caddy-d
|
||||
|
|
@ -276,15 +322,31 @@ 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, and also deletes the `common_log` field which would normally contain an unmasked IP address:
|
||||
Redact multiple sensitive cookies:
|
||||
|
||||
```caddy-d
|
||||
log {
|
||||
format filter {
|
||||
wrap console
|
||||
fields {
|
||||
common_log delete
|
||||
request>remote_addr ip_mask {
|
||||
request>headers>Cookie cookie {
|
||||
replace session REDACTED
|
||||
delete secret
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
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`):
|
||||
|
||||
```caddy-d
|
||||
log {
|
||||
format filter {
|
||||
wrap console
|
||||
fields {
|
||||
request>remote_ip ip_mask {
|
||||
ipv4 16
|
||||
ipv6 32
|
||||
}
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ map [<matcher>] <source> <destinations...> {
|
|||
|
||||
The number of outputs for each mapping must not exceed the number of destinations; however, for convenience, there may be fewer outputs than destinations, and any missing outputs will be filled in implicitly.
|
||||
|
||||
If a regular expression was used as the input, then the capture groups can be referenced with `${capture_group}` where `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
|
||||
If a regular expression was used as the input, then the capture groups can be referenced with `${group}` where `group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
|
||||
|
||||
- **<default>** specifies the output values to store if no inputs are matched.
|
||||
|
||||
|
|
|
|||
25
src/docs/markdown/caddyfile/directives/method.md
Normal file
25
src/docs/markdown/caddyfile/directives/method.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: method (Caddyfile directive)
|
||||
---
|
||||
|
||||
# method
|
||||
|
||||
Changes the HTTP method on the request.
|
||||
|
||||
|
||||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
method [<matcher>] <method>
|
||||
```
|
||||
|
||||
- **<method>** is the HTTP method to change the request to.
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
Change the method for all requests under `/api` to `POST`:
|
||||
|
||||
```caddy-d
|
||||
method /api* POST
|
||||
```
|
||||
|
|
@ -15,7 +15,7 @@ request_body [<matcher>] {
|
|||
}
|
||||
```
|
||||
|
||||
- **max_size** is the maximum size in bytes allowed for the request body. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go).
|
||||
- **max_size** is the maximum size in bytes allowed for the request body. It accepts all size values supported by [go-humanize](https://pkg.go.dev/github.com/dustin/go-humanize#pkg-constants). Reads of more bytes will return an error with HTTP status 413.
|
||||
|
||||
|
||||
## Examples
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ $(function() {
|
|||
$(item).addClass('nd').removeClass('k')
|
||||
$(item).html('<a href="#response-matcher" style="color: inherit;" title="Response matcher">' + text + '</a>');
|
||||
});
|
||||
|
||||
|
||||
// Fix matcher placeholder
|
||||
$('pre.chroma .k:contains("handle_response")').first().nextAll().slice(0, 3)
|
||||
.wrapAll('<span class="nd">').parent()
|
||||
|
|
@ -30,6 +30,10 @@ Proxies requests to one or more backends with configurable transport, load balan
|
|||
|
||||
- [Syntax](#syntax)
|
||||
- [Upstreams](#upstreams)
|
||||
- [Upstream addresses](#upstream-addresses)
|
||||
- [Dynamic upstreams](#dynamic-upstreams)
|
||||
- [SRV](#srv)
|
||||
- [A/AAAA](#aaaaa)
|
||||
- [Load balancing](#load-balancing)
|
||||
- [Active health checks](#active-health-checks)
|
||||
- [Passive health checks](#passive-health-checks)
|
||||
|
|
@ -48,8 +52,8 @@ Proxies requests to one or more backends with configurable transport, load balan
|
|||
```caddy-d
|
||||
reverse_proxy [<matcher>] [<upstreams...>] {
|
||||
# backends
|
||||
to <upstreams...>
|
||||
...
|
||||
to <upstreams...>
|
||||
dynamic <module> ...
|
||||
|
||||
# load balancing
|
||||
lb_policy <name> [<options...>]
|
||||
|
|
@ -81,6 +85,7 @@ reverse_proxy [<matcher>] [<upstreams...>] {
|
|||
max_buffer_size <size>
|
||||
|
||||
# header manipulation
|
||||
trusted_proxies [private_ranges] <ranges...>
|
||||
header_up [+|-]<field> [<value|regexp> [<replacement>]]
|
||||
header_down [+|-]<field> [<value|regexp> [<replacement>]]
|
||||
|
||||
|
|
@ -94,8 +99,18 @@ reverse_proxy [<matcher>] [<upstreams...>] {
|
|||
status <code...>
|
||||
header <field> [<value>]
|
||||
}
|
||||
handle_response [<matcher>] [status_code] {
|
||||
replace_status [<matcher>] <status_code>
|
||||
handle_response [<matcher>] {
|
||||
<directives...>
|
||||
|
||||
# special directives only available in handle_response
|
||||
copy_response [<matcher>] [<status>] {
|
||||
status <status>
|
||||
}
|
||||
copy_response_headers [<matcher>] {
|
||||
include <fields...>
|
||||
exclude <fields...>
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -106,8 +121,12 @@ reverse_proxy [<matcher>] [<upstreams...>] {
|
|||
|
||||
- **<upstreams...>** is a list of upstreams (backends) to which to proxy.
|
||||
- **to** <span id="to"/> is an alternate way to specify the list of upstreams, one (or more) per line.
|
||||
- **dynamic** <span id="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 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:
|
||||
|
||||
#### Upstream addresses
|
||||
|
||||
Static 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`
|
||||
|
|
@ -116,16 +135,69 @@ Upstream addresses can take the form of a conventional [Caddy network address](/
|
|||
- `h2c://127.0.0.1`
|
||||
- `example.com`
|
||||
- `unix//var/php.sock`
|
||||
- `srv+http://internal.service.consul`
|
||||
- `srv+https://internal.service.consul`
|
||||
|
||||
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.
|
||||
Note: Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport.
|
||||
|
||||
Additionally, upstream addresses cannot contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported. You may use the [`rewrite`](/docs/caddyfile/directives/rewrite) directive should you need this.
|
||||
|
||||
If the address is not a URL (i.e. does not have a scheme), then placeholders can be used, but this makes the upstream dynamic, meaning that the potentially many different backends act as one upstream in terms of health checks and load balancing.
|
||||
If the address is not a URL (i.e. does not have a scheme), then placeholders can be used, but this makes the upstream _dynamically static_, meaning that potentially many different backends act as a single, static upstream in terms of health checks and load balancing.
|
||||
|
||||
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.
|
||||
When proxying over HTTPS, you may need to override the `Host` header such that it 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). Ideally, dynamic upstream modules only return healthy, usable backends.
|
||||
|
||||
|
||||
##### SRV
|
||||
|
||||
Retrieves upstreams from SRV DNS records.
|
||||
|
||||
```caddy-d
|
||||
dynamic srv [<name>] {
|
||||
service <service>
|
||||
proto <proto>
|
||||
name <name>
|
||||
refresh <interval>
|
||||
resolvers <ip...>
|
||||
dial_timeout <duration>
|
||||
dial_fallback_delay <duration>
|
||||
}
|
||||
```
|
||||
|
||||
- **<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 DNS resolvers to override system resolvers.
|
||||
- **dial_timeout** - Timeout for dialing the query.
|
||||
- **dial_fallback_delay** - Timeout for falling back from IPv6 to IPv4 via RFC 6555. Default: `300ms`
|
||||
|
||||
|
||||
|
||||
##### A/AAAA
|
||||
|
||||
Retrieves upstreams from A/AAAA DNS records.
|
||||
|
||||
```caddy-d
|
||||
dynamic a [<name> <port>] {
|
||||
name <name>
|
||||
port <port>
|
||||
refresh <interval>
|
||||
resolvers <ip...>
|
||||
dial_timeout <duration>
|
||||
dial_fallback_delay <duration>
|
||||
}
|
||||
```
|
||||
|
||||
- **<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 DNS resolvers to override system resolvers.
|
||||
- **dial_timeout** - Timeout for dialing the query.
|
||||
- **dial_fallback_delay** - Timeout for falling back from IPv6 to IPv4 via RFC 6555. Default: `300ms`
|
||||
|
||||
|
||||
|
||||
|
|
@ -193,24 +265,25 @@ The proxy can **manipulate headers** between itself and the backend:
|
|||
- **header_up** <span id="header_up"/> Sets, adds, removes, or performs a replacement in a request header going upstream to the backend.
|
||||
- **header_down** <span id="header_down"/> Sets, adds, removes, or performs a replacement in a response header coming downstream from the backend.
|
||||
|
||||
|
||||
#### Defaults
|
||||
|
||||
By default, Caddy passes thru incoming headers to the backend—including the `Host` header—without modifications, with two exceptions:
|
||||
By default, Caddy passes thru incoming headers—including `Host`—to the backend without modifications, with three exceptions:
|
||||
|
||||
- It adds or augments the [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) header field.
|
||||
- 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` <span id="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, `trusted_proxies private_ranges` may be configured to trust all private IP ranges.
|
||||
|
||||
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.
|
||||
|
||||
#### HTTPS
|
||||
|
||||
For HTTPS upstreams, since the `Host` header retains its original value, it is typically necessary to override the header with the configured upstream address, such that the `Host` header matches the TLS SNI value. A `X-Forwarded-Host` header may also be added to inform the upstream of the original `Host` header's value. For example:
|
||||
Since (most) headers retain their original value when being proxied, it is often necessary to override the `Host` header with the configured upstream address when proxying to HTTPS, such that the `Host` header matches the TLS ServerName value. For example:
|
||||
|
||||
```caddy-d
|
||||
reverse_proxy https://example.com {
|
||||
header_up Host {upstream_hostport}
|
||||
header_up X-Forwarded-Host {host}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -297,19 +370,28 @@ transport fastcgi {
|
|||
- **write_timeout** <span id="write_timeout"/> is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
|
||||
|
||||
|
||||
|
||||
|
||||
### Intercepting responses
|
||||
|
||||
The reverse proxy can be configured to intercept responses from the backend. To facilitate this, response matchers can be defined (similar to the syntax for request matchers) and the first matching `handle_response` route will be invoked. When this happens, the response from the backend is not written to the client, and the configured `handle_response` route will be executed instead, and it is up to that route to write a response.
|
||||
|
||||
- **@name** is the name of a [response matcher](#response-matcher). As long as each response matcher has a unique name, multiple matchers can be defined. A response can be matched on the status code and presence or value of a response header.
|
||||
- **replace_status** <span id="replace_status"/> simply changes the status code of response when matched by the given matcher.
|
||||
- **handle_response** <span id="handle_response"/> defines the route to execute when matched by the given matcher (or, if a matcher is omitted, all responses). The first matching block will be applied. Inside a `handle_response` block, any other [directives](/docs/caddyfile/directives) can be used.
|
||||
|
||||
Three placeholders will be made available to the `handle_response` routes:
|
||||
Additionally, inside `handle_response`, two special handler directives may be used:
|
||||
|
||||
- **copy_response** <span id="copy_response"/> copies the response from the backend back to the client. Optionally allows changing the status code of the response while doing so. This directive is [ordered before `respond`](/docs/caddyfile/directives#directive-order).
|
||||
- **copy_response_headers** <span id="copy_response_headers"/> copies the response headers from the backend to the client, optionally including _OR_ excluding a list of headers fields (cannot specify both `include` and `exclude`). This directive is [ordered after `header`](/docs/caddyfile/directives#directive-order).
|
||||
|
||||
Three placeholders will be made available within the `handle_response` routes:
|
||||
|
||||
- `{http.reverse_proxy.status_code}` The status code from the backend's response.
|
||||
- `{http.reverse_proxy.status_text}` The status text from the backend's response.
|
||||
- `{http.reverse_proxy.header.*}` The headers from the backend's response.
|
||||
|
||||
|
||||
#### Response matcher
|
||||
|
||||
**Response matchers** can be used to filter (or classify) responses by specific criteria.
|
||||
|
|
@ -326,7 +408,11 @@ By HTTP status code.
|
|||
|
||||
##### header
|
||||
|
||||
See the [header](/docs/caddyfile/matchers#header) request matcher for the supported syntax.
|
||||
See the [`header`](/docs/caddyfile/matchers#header) request matcher for the supported syntax.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -401,7 +487,7 @@ reverse_proxy localhost:8080 {
|
|||
@accel header X-Accel-Redirect *
|
||||
handle_response @accel {
|
||||
root * /path/to/private/files
|
||||
rewrite {http.reverse_proxy.header.X-Accel-Redirect}
|
||||
rewrite * {http.reverse_proxy.header.X-Accel-Redirect}
|
||||
file_server
|
||||
}
|
||||
}
|
||||
|
|
@ -420,3 +506,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
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -31,6 +31,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
|
|||
ca_root <pem_file>
|
||||
key_type ed25519|p256|p384|rsa2048|rsa4096
|
||||
dns <provider_name> [<params...>]
|
||||
dns_challenge_domain_override <domain>
|
||||
resolvers <dns_servers...>
|
||||
eab <key_id> <mac_key>
|
||||
on_demand
|
||||
|
|
@ -79,7 +80,8 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
|
|||
- **ca** <span id="ca"/> changes the ACME CA endpoint. This is most often used to set [Let's Encrypt's staging endpoint](https://letsencrypt.org/docs/staging-environment/) when testing, 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** <span id="ca_root"/> specifies a PEM file that contains a trusted root certificate for the ACME CA endpoint, if not in the system trust store.
|
||||
- **key_type** <span id="key_type"/> is the type of key to use when generating CSRs. Only set this if you have a specific requirement.
|
||||
- **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)
|
||||
- **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)
|
||||
- **dns_challenge_domain_override** <span id="dns_challenge_domain_override"/> 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.
|
||||
- **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.
|
||||
|
|
@ -177,12 +179,15 @@ Obtains certificates from an internal certificate authority.
|
|||
|
||||
```caddy
|
||||
... internal {
|
||||
ca <name>
|
||||
ca <name>
|
||||
lifetime <duration>
|
||||
sign_with_root
|
||||
}
|
||||
```
|
||||
|
||||
- **ca** is the name of the internal CA to use. Default: `local`
|
||||
|
||||
- **ca** <span id="ca"/> is the name of the internal CA to use. Default: `local`. See the [PKI app global options](/docs/caddyfile/options#pki-options) to configure alternate CAs.
|
||||
- **lifetime** <span id="lifetime"/> is a [duration value](/docs/conventions#durations) that sets the validity period for interally issued leaf certificates. Default: 12h. It is NOT recommended to not change this, unless absolutely necessary.
|
||||
- **sign_with_root** <span id="sign_with_root"/> forces the root to be the issuer instead of the intermediate. This is NOT recommended and should only be used when devices/clients do not properly validate certificate chains (very uncommon).
|
||||
|
||||
|
||||
## Examples
|
||||
|
|
@ -207,6 +212,16 @@ tls internal {
|
|||
}
|
||||
```
|
||||
|
||||
Use custom options for the internal CA (cannot use the `tls internal` shortcut):
|
||||
|
||||
```caddy-d
|
||||
tls {
|
||||
issuer internal {
|
||||
ca foo
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Specify an email address for your ACME account (but if only one email is used for all sites, we recommend the `email` [global option](/docs/caddyfile/options) instead):
|
||||
|
||||
```caddy-d
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue