docs: Add headers to reverse_proxy docs for anchor linking (#77)

This commit is contained in:
Francis Lavoie 2020-08-17 16:12:20 -04:00 committed by GitHub
parent 1de532a465
commit 8e777706f9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -49,6 +49,8 @@ reverse_proxy [<matcher>] [<upstreams...>] {
}
```
### 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.
@ -65,7 +67,9 @@ Upstream addresses can take the form of a conventional [Caddy network address](/
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. 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.
**Load balancing** is used whenever more than one upstream is defined.
### Load balancing
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:
- `first` - choose first available upstream
@ -80,7 +84,9 @@ Note: Schemes cannot be mixed, since they modify the common transport configurat
- **lb_try_duration** is a [duration value](/docs/conventions#durations) that defines how long to try selecting available backends for each request if the next available host is down. By default, this retry is disabled. Clients will wait for up to this long while the load balancer tries to find an available upstream host.
- **lb_try_interval** is a [duration value](/docs/conventions#durations) that defines how long to wait between selecting the next host from the pool. Default is `250ms`. Only relevant when a request to an upstream host fails. Be aware that setting this to 0 with a non-zero `lb_try_duration` can cause the CPU to spin if all backends are down and latency is very low.
**Active health checks** perform health checking in the background on a timer:
#### Active health checks
Active health checks perform health checking in the background on a timer:
- **health_path** is the URI path for active health checks.
- **health_port** is the port to use for active health checks, if different from the upstream's port.
@ -89,7 +95,9 @@ Note: Schemes cannot be mixed, since they modify the common transport configurat
- **health_status** is the HTTP status code to expect from a healthy backend. Can be a 3-digit status code or a status code class ending in `xx`, for example: `200` (default) or `2xx`.
- **health_body** is a substring or regular expression to match on the response body of an active health check. If the backend does not return a matching body, it will be marked as down.
**Passive health checks** happen inline with actual proxied requests:
#### Passive health checks
Passive health checks happen inline with actual proxied requests:
- **fail_duration** is a [duration value](/docs/conventions#durations) that defines how long to remember a failed request. A duration > 0 enables passive health checking.
- **max_fails** is the maximum number of failed requests within fail_timeout that are needed before considering a backend to be down; must be >= 1; default is 1.
@ -97,10 +105,14 @@ Note: Schemes cannot be mixed, since they modify the common transport configurat
- **unhealthy_latency** is a [duration value](/docs/conventions#durations) that counts a request as failed if it takes this long to get a response.
- **unhealthy_request_count** is the permissible number of simultaneous requests to a backend before marking it as down.
### Streaming
The proxy **buffers responses** by default for wire efficiency:
- **flush_interval** is a [duration value](/docs/conventions#durations) that defines how often Caddy should flush the buffered response body to the client. Set to -1 to disable buffering.
### Headers
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.
@ -113,11 +125,13 @@ By default, Caddy passes thru incoming headers to the backend&mdash;including th
Since these header fields are only de-facto standards, Caddy may stop setting them implicitly in the future if the standardized [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) header field becomes more widely adopted.
### Transports
Caddy's proxy **transport** is pluggable:
- **transport** defines how to communicate with the backend. Default is `http`.
The `http` transport can look like this:
#### The `http` transport
```caddy-d
transport http {
@ -147,7 +161,7 @@ transport http {
- **keepalive** is either `off` or a [duration value](/docs/conventions#durations) that specifies how long to keep connections open.
- **keepalive_idle_conns** defines the maximum number of connections to keep alive.
The `fastcgi` transport can look like this:
#### The `fastcgi` transport
```caddy-d
transport fastcgi {