mirror of
https://github.com/caddyserver/website.git
synced 2025-04-21 12:36:16 -04:00
Docs for v2.7.0
This commit is contained in:
Francis Lavoie
parent
17dcddef01
commit
10c5c5b443
13 changed files with 272 additions and 82 deletions
|
|
@ -334,7 +334,7 @@ Returns the current status of the configured reverse proxy upstreams (backends)
|
|||
|
||||
Each entry in the JSON array is a configured [upstream](/docs/json/apps/http/servers/routes/handle/reverse_proxy/upstreams/) stored in the global upstream pool.
|
||||
|
||||
- **address** is the dial address of the upstream. For SRV upstreams, this is the `lookup_srv` DNS name.
|
||||
- **address** is the dial address of the upstream.
|
||||
- **num_requests** is the amount of active requests currently being handled by the upstream.
|
||||
- **fails** the current number of failed requests remembered, as configured by passive health checks.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,6 +7,9 @@ title: Caddyfile Concepts
|
|||
This document will help you learn about the HTTP Caddyfile in detail.
|
||||
|
||||
1. [Structure](#structure)
|
||||
- [Blocks](#blocks)
|
||||
- [Directives](#directives)
|
||||
- [Tokens and quotes](#tokens-and-quotes)
|
||||
2. [Addresses](#addresses)
|
||||
3. [Matchers](#matchers)
|
||||
4. [Placeholders](#placeholders)
|
||||
|
|
@ -156,6 +159,25 @@ directive "first line
|
|||
second line"
|
||||
```
|
||||
|
||||
Heredocs <span id="heredocs"/> are also supported:
|
||||
|
||||
```caddy
|
||||
example.com {
|
||||
respond <<HTML
|
||||
<html>
|
||||
<head><title>Foo</title></head>
|
||||
<body>Foo</body>
|
||||
</html>
|
||||
HTML 200
|
||||
}
|
||||
```
|
||||
|
||||
The opening heredoc marker must start with `<<`, followed by any text (uppercase letters recommended). The closing heredoc marker must be the same text (in the above example, `HTML`).
|
||||
|
||||
The closing marker can be indented, which causes every line of text to have that much indentation stripped (inspired by [PHP](https://www.php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc)) which is nice for readability inside [blocks](#blocks) while giving great control of the whitespace in the token text. The trailing newline is also stripped, but can be retained by adding an extra blank line before the closing marker.
|
||||
|
||||
Additional tokens may follow the closing marker as arguments to the directive (such as in the example above, the status code `200`).
|
||||
|
||||
|
||||
|
||||
## Addresses
|
||||
|
|
@ -236,6 +258,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd
|
|||
| Shorthand | Replaces |
|
||||
|-----------------|-----------------------------------|
|
||||
| `{cookie.*}` | `{http.request.cookie.*}` |
|
||||
| `{client_ip}` | `{http.vars.client_ip}` |
|
||||
| `{dir}` | `{http.request.uri.path.dir}` |
|
||||
| `{err.*}` | `{http.error.*}` |
|
||||
| `{file_match.*}` | `{http.matchers.file.*}` |
|
||||
|
|
@ -297,7 +320,7 @@ You can pass arguments to imported configuration and use them like so:
|
|||
|
||||
```caddy
|
||||
(snippet) {
|
||||
respond "Yahaha! You found {args.0}!"
|
||||
respond "Yahaha! You found {args[0]}!"
|
||||
}
|
||||
|
||||
a.example.com {
|
||||
|
|
|
|||
|
|
@ -18,10 +18,14 @@ Using ACME server defaults, ACME clients should simply be configured to use `htt
|
|||
|
||||
```caddy-d
|
||||
acme_server [<matcher>] {
|
||||
ca <id>
|
||||
lifetime <duration>
|
||||
ca <id>
|
||||
lifetime <duration>
|
||||
resolvers <resolvers...>
|
||||
}
|
||||
```
|
||||
|
||||
- **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.
|
||||
|
||||
- **lifetime** (Default: `12h`) is a [duration](/docs/conventions#durations) which specifies the validity period for issued certificates. This value must be less than the lifetime of the [intermediate certificate](/docs/caddyfile/options#intermediate-lifetime) used for signing. It is not recommended to change this unless absolutely necessary.
|
||||
|
||||
- **resolvers** are the addresses of DNS resolvers to use when looking up the TXT records for solving ACME DNS challenges. Accepts [network addresses](/docs/conventions#network-addresses) defaulting to UDP and port 53 unless specified. If the host is an IP address, it will be dialed directly to resolve the upstream server. If the hot is not an IP address, the addresses are resolved using the [name resolution convention](https://golang.org/pkg/net/#hdr-Name_Resolution) of the Go standard library. If multiple resolvers are specified, then one is chosen at random.
|
||||
|
|
|
|||
|
|
@ -12,12 +12,18 @@ By default, header operations are performed immediately unless any of the header
|
|||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
header [<matcher>] [[+|-|?]<field> [<value>|<find>] [<replace>]] {
|
||||
header [<matcher>] [[+|-|?|>]<field> [<value>|<find>] [<replace>]] {
|
||||
# Replace
|
||||
<field> <find> <replace>
|
||||
|
||||
# Add or Set
|
||||
[+]<field> <value>
|
||||
# Add
|
||||
+<field> <value>
|
||||
|
||||
# Set
|
||||
<field> <value>
|
||||
|
||||
# Set with defer
|
||||
><field> <value>
|
||||
|
||||
# Delete
|
||||
-<field>
|
||||
|
|
@ -37,13 +43,15 @@ header [<matcher>] [[+|-|?]<field> [<value>|<find>] [<replace>]] {
|
|||
|
||||
Prefix with `?` to set a default value for the field. The field is only written if it doesn't yet exist.
|
||||
|
||||
Prefix with `>` to set the field, and enable `defer`, as a shortcut.
|
||||
|
||||
- **<value>** is the header field value, if adding or setting a field.
|
||||
|
||||
- **<find>** is the substring or regular expression to search for.
|
||||
|
||||
- **<replace>** is the replacement value; required if performing a search-and-replace.
|
||||
|
||||
- **defer** will force the header operations to be deferred until the response is being written out to the client. This is automatically enabled if any of the header fields are being deleted with `-`, or when setting a default value with `?`.
|
||||
- **defer** will force the header operations to be deferred until the response is being written out to the client. This is automatically enabled if any of the header fields are being deleted with `-`, when setting a default value with `?`, or when having used the `>` prefix.
|
||||
|
||||
For multiple header manipulations, you can open a block and specify one manipulation per line in the same way.
|
||||
|
||||
|
|
@ -106,3 +114,10 @@ Set a default cache expiration if upstream doesn't define one:
|
|||
header ?Cache-Control "max-age=3600"
|
||||
reverse_proxy upstream:443
|
||||
```
|
||||
|
||||
To override the cache expiration that a proxy upstream had set for paths starting with `/no-cache`; enabling `defer` is necessary to ensure the header is set _after_ the proxy writes its headers:
|
||||
|
||||
```caddy-d
|
||||
header /no-cache* >Cache-Control nocache
|
||||
reverse_proxy upstream:443
|
||||
```
|
||||
|
|
|
|||
|
|
@ -23,7 +23,16 @@ import <pattern> [<args...>]
|
|||
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.
|
||||
- **<args...>** is an optional list of arguments to pass to the imported tokens. This placeholder is a special case and is evaluated at Caddyfile-parse-time, not at run-time. They can be used in various forms, similarly to [Go's slice syntax](https://gobyexample.com/slices):
|
||||
- `{args[n]}` where `n` is the 0-based positional index of the parameter
|
||||
- `{args[:]}` where all the arguments are inserted
|
||||
- `{args[:m]}` where the arguments before `m` are inserted
|
||||
- `{args[n:]}` where the arguments beginning with `n` are inserted
|
||||
- `{args[n:m]}` where the arguments in the range between `n` and `m` are inserted
|
||||
|
||||
For the forms that insert many tokens, the placeholder _must_ be a [token](/docs/caddyfile/concepts#tokens-and-quotes) on its own, it cannot be part of another token. In other words, it must have spaces around it, and cannot be in quotes.
|
||||
|
||||
Note that prior to v2.7.0, the syntax was `{args.N}` but this form was deprecated in favor of the more flexible syntax above.
|
||||
|
||||
|
||||
## Examples
|
||||
|
|
@ -38,8 +47,8 @@ Import a snippet that sets CORS headers using an import argument:
|
|||
|
||||
```caddy
|
||||
(cors) {
|
||||
@origin header Origin {args.0}
|
||||
header @origin Access-Control-Allow-Origin "{args.0}"
|
||||
@origin header Origin {args[0]}
|
||||
header @origin Access-Control-Allow-Origin "{args[0]}"
|
||||
header @origin Access-Control-Allow-Methods "OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE"
|
||||
}
|
||||
|
||||
|
|
@ -47,3 +56,32 @@ example.com {
|
|||
import cors example.com
|
||||
}
|
||||
```
|
||||
|
||||
Import a snippet which takes a list of proxy upstreams as arguments:
|
||||
|
||||
```caddy
|
||||
(https-proxy) {
|
||||
reverse_proxy {args[:]} {
|
||||
transport http {
|
||||
tls
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
example.com {
|
||||
import https-proxy 10.0.0.1 10.0.0.2 10.0.0.3
|
||||
}
|
||||
```
|
||||
|
||||
Import a snippet which creates a proxy with a prefix rewrite rule as the first argument:
|
||||
|
||||
```caddy
|
||||
(proxy-rewrite) {
|
||||
rewrite * {args[0]}{uri}
|
||||
reverse_proxy {args[1:]}
|
||||
}
|
||||
|
||||
example.com {
|
||||
import proxy-rewrite /api 10.0.0.1 10.0.0.2 10.0.0.3
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -54,3 +54,14 @@ respond /secret/* "Access denied" 403 {
|
|||
close
|
||||
}
|
||||
```
|
||||
|
||||
Write an HTML response, using [heredoc syntax](/docs/caddyfile/concepts#heredocs) to control whitespace:
|
||||
|
||||
```caddy-d
|
||||
respond <<HTML
|
||||
<html>
|
||||
<head><title>Foo</title></head>
|
||||
<body>Foo</body>
|
||||
</html>
|
||||
HTML 200
|
||||
```
|
||||
|
|
|
|||
|
|
@ -141,6 +141,7 @@ Static upstream addresses can take the form of a URL that contains only scheme a
|
|||
- `example.com`
|
||||
- `unix//var/php.sock`
|
||||
- `unix+h2c//var/grpc.sock`
|
||||
- `localhost:8001-8006`
|
||||
|
||||
By default, connections are made to the upstream over plaintext HTTP. When using the URL form, a scheme can be used to set some [`transport`](#transports) defaults as a shorthand.
|
||||
- Using `https://` as the scheme will use the [`http` transport](#the-http-transport) with [`tls`](#tls) enabled.
|
||||
|
|
@ -152,7 +153,7 @@ By default, connections are made to the upstream over plaintext HTTP. When using
|
|||
|
||||
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.
|
||||
|
||||
When using the [network address](/docs/conventions#network-addresses) form, the network type is specified as a prefix to the upstream address. This cannot be combined with a URL scheme. As a special case, `unix+h2c/` is supported as a shortcut for the `unix/` network plus the same effects as the `h2c://` scheme.
|
||||
When using the [network address](/docs/conventions#network-addresses) form, the network type is specified as a prefix to the upstream address. This cannot be combined with a URL scheme. As a special case, `unix+h2c/` is supported as a shortcut for the `unix/` network plus the same effects as the `h2c://` scheme. Port ranges are supported as a shortcut, which expands to multiple upstreams with the same host.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -203,6 +204,7 @@ Retrieves upstreams from A/AAAA DNS records.
|
|||
resolvers <ip...>
|
||||
dial_timeout <duration>
|
||||
dial_fallback_delay <duration>
|
||||
versions ipv4|ipv6
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -212,6 +214,7 @@ Retrieves upstreams from A/AAAA DNS records.
|
|||
- **resolvers** is the list of DNS resolvers to override system resolvers.
|
||||
- **dial_timeout** is the timeout for dialing the query.
|
||||
- **dial_fallback_delay** is how long to wait before spawning an RFC 6555 Fast Fallback connection. Default: `300ms`
|
||||
- **versions** is the list of IP versions to resolve for. Default: `ipv4 ipv6` which correspond to both A and AAAA records respectively.
|
||||
|
||||
|
||||
##### Multi
|
||||
|
|
@ -237,25 +240,31 @@ Load balancing is used whenever more than one upstream is defined.
|
|||
|
||||
For policies that involve hashing, the [highest-random-weight (HRW)](https://en.wikipedia.org/wiki/Rendezvous_hashing) algorithm is used to ensure that a client or request with the same hash key is mapped to the same upstream, even if the list of upstreams change.
|
||||
|
||||
Some policies support fallback as an option, if noted, in which case they take a [block](/docs/caddyfile/concepts#blocks) with `fallback <policy>` which takes another load balancing policy. For those policies, the default fallback is `random`. Configuring a fallback allows using a secondary policy if the primary does not select one, allowing for powerful combinations. Fallbacks can be nested multiple times if desired. For example, `header` can be used as primary to allow for developers to choose a specific upstream, with a fallback of `first` for all other connections to implement primary/secondary failover.
|
||||
|
||||
- `random` randomly chooses an upstream
|
||||
|
||||
- `random_choose <n>` selects two or more upstreams randomly, then chooses one with least load (`n` is usually 2)
|
||||
|
||||
- `first` chooses the first available upstream, from the order they are defined in the config
|
||||
- `first` chooses the first available upstream, from the order they are defined in the config, allowing for primary/secondary failover; remember to enable health checks along with this, otherwise failover will not occur
|
||||
|
||||
- `round_robin` iterates each upstream in turn
|
||||
|
||||
- `least_conn` choose upstream with fewest number of current requests; if more than one host has the least number of requests, then one of those hosts is chosen at random
|
||||
|
||||
- `ip_hash` maps the client IP to a sticky upstream
|
||||
- `ip_hash` maps the remote IP (the immediate peer) to a sticky upstream
|
||||
|
||||
- `client_ip_hash` maps the client IP to a sticky upstream; this is best paired with the [`servers > trusted_proxies` global option](/docs/caddyfile/options#trusted-proxies) which enables real client IP parsing, otherwise it behaves the same as `ip_hash`
|
||||
|
||||
- `uri_hash` maps the request URI (path and query) to a sticky upstream
|
||||
|
||||
- `header [field]` maps a request header to a sticky upstream, by hashing the header value; if the specified header field is not present, a random upstream is selected
|
||||
- `query [key]` maps a request query to a sticky upstream, by hashing the query value; if the specified key is not present, the fallback policy will be used to select an upstream (`random` by default)
|
||||
|
||||
- `cookie [<name> [<secret>]]` on the first request from a client (when there's no cookie), a random upstream is selected, and a `Set-Cookie` header is added to the response (default cookie name is `lb` if not specified). The cookie value is the upstream dial address of the chosen upstream, hashed with HMAC-SHA256 (using `<secret>` as the shared secret, empty string if not specified).
|
||||
- `header [field]` maps a request header to a sticky upstream, by hashing the header value; if the specified header field is not present, the fallback policy will be used to select an upstream (`random` by default)
|
||||
|
||||
- `cookie [<name> [<secret>]]` on the first request from a client (when there's no cookie), the fallback policy will be used to select an upstream (`random` by default), and a `Set-Cookie` header is added to the response (default cookie name is `lb` if not specified). The cookie value is the upstream dial address of the chosen upstream, hashed with HMAC-SHA256 (using `<secret>` as the shared secret, empty string if not specified).
|
||||
|
||||
On subsequent requests where the cookie is present, the cookie value will be mapped to the same upstream if it's available; if not available or not found, a new random upstream is selected and the cookie is added to the response.
|
||||
On subsequent requests where the cookie is present, the cookie value will be mapped to the same upstream if it's available; if not available or not found, a new upstream is selected with the fallback policy, and the cookie is added to the response.
|
||||
|
||||
If you wish to use a particular upstream for debugging purposes, you may hash the upstream address with the secret, and set the cookie in your HTTP client (browser or otherwise). For example, with PHP, you could run the following to compute the cookie value, where `10.1.0.10:8080` is the address of one of your upstreams, and `secret` is your configured secret.
|
||||
```php
|
||||
|
|
@ -364,12 +373,18 @@ To delete a request header, preventing it from reaching the backend:
|
|||
header_up -Some-Header
|
||||
```
|
||||
|
||||
To delete all matching request, using a suffix match:
|
||||
To delete all matching request headers, using a suffix match:
|
||||
|
||||
```caddy-d
|
||||
header_up -Some-*
|
||||
```
|
||||
|
||||
To delete _all_ request headers, to be able to individually add the ones you want (not recommended):
|
||||
|
||||
```caddy-d
|
||||
header_up -*
|
||||
```
|
||||
|
||||
To perform a regular expression replacement on a request header:
|
||||
|
||||
```caddy-d
|
||||
|
|
@ -391,7 +406,7 @@ By default, Caddy passes thru incoming headers—including `Host`—to t
|
|||
|
||||
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.
|
||||
It is strongly recommended that you configure this via the [`servers > trusted_proxies` global option](/docs/caddyfile/options#trusted-proxies) instead of in the proxy, so that this applies to all proxy handlers in your server, and this has the benefit of enabling client IP parsing.
|
||||
|
||||
<aside class="tip">
|
||||
|
||||
|
|
@ -446,6 +461,7 @@ transport http {
|
|||
read_buffer <size>
|
||||
write_buffer <size>
|
||||
max_response_header <size>
|
||||
proxy_protocol v1|v2
|
||||
dial_timeout <duration>
|
||||
dial_fallback_delay <duration>
|
||||
response_header_timeout <duration>
|
||||
|
|
@ -475,6 +491,8 @@ transport http {
|
|||
|
||||
- **max_response_header** <span id="max_response_header"/> is the maximum amount of bytes to read from response headers. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go). Default: `10MiB`.
|
||||
|
||||
- **proxy_protocol** <span id="proxy_protocol"/> enables [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) (popularized by HAProxy) on the connection to the upstream, prepending the real client IP data. This is best paired with the [`servers > trusted_proxies` global option](/docs/caddyfile/options#trusted-proxies) if Caddy is behind another proxy. Versions `v1` and `v2` are supported. This should only be used if you know the upstream server is able to parse PROXY protocol. By default, this is disabled.
|
||||
|
||||
- **dial_timeout** <span id="dial_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait when connecting to the upstream socket. Default: `3s`.
|
||||
|
||||
- **dial_fallback_delay** <span id="dial_fallback_delay"/> is the maximum [duration](/docs/conventions#durations) to wait before spawning an RFC 6555 Fast Fallback connection. A negative value disables this. Default: `300ms`.
|
||||
|
|
|
|||
|
|
@ -12,6 +12,8 @@ It is based on [github.com/open-telemetry/opentelemetry-go](https://github.com/o
|
|||
|
||||
It uses [gRPC](https://github.com/grpc/) as an exporter protocol and W3C [tracecontext](https://www.w3.org/TR/trace-context/) and [baggage](https://www.w3.org/TR/baggage/) as propagators.
|
||||
|
||||
The trace ID is added to [access logs](/docs/caddyfile/directives/log) as the standard `traceID` field.
|
||||
|
||||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
|
|
|
|||
|
|
@ -39,6 +39,7 @@ $(function() {
|
|||
- [Path matchers](#path-matchers)
|
||||
- [Named matchers](#named-matchers)
|
||||
- [Standard matchers](#standard-matchers)
|
||||
- [client_ip](#client-ip)
|
||||
- [expression](#expression)
|
||||
- [file](#file)
|
||||
- [header](#header)
|
||||
|
|
@ -184,6 +185,41 @@ Full matcher documentation can be found [in each respective matcher module's doc
|
|||
|
||||
Requests can be matched the following ways:
|
||||
|
||||
|
||||
|
||||
### client_ip
|
||||
|
||||
```caddy-d
|
||||
client_ip <ranges...>
|
||||
|
||||
expression client_ip('<ranges...>')
|
||||
```
|
||||
|
||||
By the client IP address. Accepts exact IPs or CIDR ranges. IPv6 zones are supported.
|
||||
|
||||
This matcher is best used when the [`trusted_proxies`](/docs/caddyfile/options#trusted-proxies) global option is configured, otherwise it acts identically to the [`remote_ip`](#remote-ip) matcher. Only requests from trusted proxies will have their client IP parsed at the start of the request; untrusted requests will use the remote IP address of the immediate peer.
|
||||
|
||||
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`
|
||||
|
||||
There can be multiple `client_ip` matchers per named matcher, and their ranges will be merged and OR'ed together.
|
||||
|
||||
#### Example:
|
||||
|
||||
Match requests from private IPv4 addresses:
|
||||
|
||||
```caddy-d
|
||||
client_ip 192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8
|
||||
```
|
||||
|
||||
This matcher is commonly paired with the [`not`](#not) matcher to invert the match. For example, to abort all connections from _public_ IPv4 and IPv6 addresses (which is the inverse of all private ranges):
|
||||
|
||||
```caddy-d
|
||||
@denied not client_ip private_ranges
|
||||
abort @denied
|
||||
```
|
||||
|
||||
|
||||
|
||||
### expression
|
||||
|
||||
```caddy-d
|
||||
|
|
@ -599,10 +635,12 @@ expression remote_ip('<ranges...>')
|
|||
expression remote_ip('forwarded', '<ranges...>')
|
||||
```
|
||||
|
||||
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.
|
||||
By remote IP address (i.e. the IP address of the immediate peer). Accepts exact IPs or CIDR ranges. IPv6 zones are supported.
|
||||
|
||||
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`
|
||||
|
||||
⚠️ The `forwarded` option is deprecated, and will be removed in a future version. Its implementation is insecure. Use the [`client_ip`](#client-ip) matcher instead, which allows for securely matching the real client IP if parsed from an HTTP header. If enabled, 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.
|
||||
|
||||
There can be multiple `remote_ip` matchers per named matcher, and their ranges will be merged and OR'ed together.
|
||||
|
||||
#### Example:
|
||||
|
|
|
|||
|
|
@ -76,6 +76,7 @@ Possible options are:
|
|||
auto_https off|disable_redirects|ignore_loaded_certs|disable_certs
|
||||
email <yours>
|
||||
default_sni <name>
|
||||
fallback_sni <name>
|
||||
local_certs
|
||||
skip_install_trust
|
||||
acme_ca <directory_url>
|
||||
|
|
@ -108,6 +109,7 @@ Possible options are:
|
|||
idle <duration>
|
||||
}
|
||||
trusted_proxies <module> ...
|
||||
client_ip_headers <headers...>
|
||||
metrics
|
||||
max_header_size <size>
|
||||
log_credentials
|
||||
|
|
@ -284,6 +286,10 @@ Your email address. Mainly used when creating an ACME account with your CA, and
|
|||
Sets a default TLS ServerName for when clients do not use SNI in their ClientHello.
|
||||
|
||||
|
||||
##### `fallback_sni`
|
||||
If configured, the fallback becomes the TLS ServerName in the ClientHello if the original ServerName doesn't match any certificates in the cache. The uses for this are very niche; typically if a client is a CDN and passes through the ServerName of the downstream handshake but can accept a certificate with the origin's hostname instead, then you would set this as your origin's hostname. Note that Caddy must be managing a certificate for this name. <i>⚠️ Experimental</i>
|
||||
|
||||
|
||||
##### `local_certs`
|
||||
Causes all certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful in development environments.
|
||||
|
||||
|
|
@ -447,7 +453,7 @@ listener_wrappers {
|
|||
}
|
||||
```
|
||||
|
||||
Another example, assuming you have the [`proxy_protocol`](/docs/json/apps/http/servers/listener_wrappers/proxy_protocol/) plugin installed, which must be used _before_ the `tls` listener wrapper:
|
||||
Also included is the [`proxy_protocol`](/docs/json/apps/http/servers/listener_wrappers/proxy_protocol/) listener wrapper (prior to v2.7.0 it was only available via a plugin), which enables [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) parsing (popularized by HAProxy). This must be used _before_ the `tls` listener wrapper since it parses plaintext data at the start of the connection:
|
||||
|
||||
```caddy-d
|
||||
listener_wrappers {
|
||||
|
|
@ -476,10 +482,13 @@ listener_wrappers {
|
|||
|
||||
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.
|
||||
Enabling this causes trusted requests to have the _real_ client IP parsed from HTTP headers (by default, `X-Forwarded-For`; see [`client_ip_headers`](#client-ip-headers) to configure other headers). If trusted, the client IP is added to [access logs](/docs/caddyfile/directives/log), is available as a `{client_ip}` [placeholder](/docs/caddyfile/concepts#placeholders), and allows the use of the [`client_ip` matcher](/docs/caddyfile/matchers#client-ip). If the request is not from a trusted proxy, then the client IP is set to the remote IP address of the direct incoming connection.
|
||||
|
||||
Some matchers or handlers may use the trust status of the request to make additional decisions. For example, if trusted, the [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy#defaults) handler will proxy and augment the sensitive `X-Forwarded-*` request 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.
|
||||
|
|
@ -501,6 +510,11 @@ Here's a complete example, trusting an example IPv4 range and an IPv6 range:
|
|||
```
|
||||
|
||||
|
||||
##### `client_ip_headers`
|
||||
|
||||
Pairing with [`trusted_proxies`](#trusted-proxies), allows configuring which headers to use to determine the client's IP address. By default, only `X-Forwarded-For` is considered. Multiple header fields can be specified, in which case the first non-empty header value is used.
|
||||
|
||||
|
||||
|
||||
##### `metrics`
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ caddy <command> [<args...>]
|
|||
|
||||
The `<carets>` indicate parameters that get replaced by your input.
|
||||
|
||||
The`[brackets]` indicate optional parameters.
|
||||
The`[brackets]` indicate optional parameters. The`(brackets)` indicate required parameters.
|
||||
|
||||
The ellipses `...` indicates a continuation, i.e. one or more parameters.
|
||||
|
||||
|
|
@ -101,9 +101,9 @@ The ellipses `...` indicates a continuation, i.e. one or more parameters.
|
|||
### `caddy adapt`
|
||||
|
||||
<pre><code class="cmd bash">caddy adapt
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[--pretty]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[-p, --pretty]
|
||||
[--validate]</code></pre>
|
||||
|
||||
Adapts a configuration to Caddy's native JSON config structure and writes the output to stdout, along with any warnings to stderr, then exits.
|
||||
|
|
@ -175,13 +175,13 @@ Prints the environment as seen by caddy, then exits. Can be useful when debuggin
|
|||
### `caddy file-server`
|
||||
|
||||
<pre><code class="cmd bash">caddy file-server
|
||||
[--root <path>]
|
||||
[-r, --root <path>]
|
||||
[--listen <addr>]
|
||||
[--domain <example.com>]
|
||||
[--browse]
|
||||
[--templates]
|
||||
[-d, --domain <example.com>]
|
||||
[-b, --browse]
|
||||
[-t, --templates]
|
||||
[--access-log]
|
||||
[--debug]</code></pre>
|
||||
[-v, --debug]</code></pre>
|
||||
|
||||
Spins up a simple but production-ready static file server.
|
||||
|
||||
|
|
@ -206,7 +206,9 @@ This command disables the admin API, making it easier to run multiple instances
|
|||
|
||||
### `caddy fmt`
|
||||
|
||||
<pre><code class="cmd bash">caddy fmt [--overwrite] [--diff] [<path>]</code></pre>
|
||||
<pre><code class="cmd bash">caddy fmt [<path>]
|
||||
[-w, --overwrite]
|
||||
[-d, --diff]</code></pre>
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -222,17 +224,19 @@ Formats or prettifies a Caddyfile, then exits. The result is printed to stdout u
|
|||
### `caddy hash-password`
|
||||
|
||||
<pre><code class="cmd bash">caddy hash-password
|
||||
[--plaintext <password>]
|
||||
[--algorithm <name>]
|
||||
[--salt <string>]</code></pre>
|
||||
[-p, --plaintext <password>]
|
||||
[-a, --algorithm <name>]
|
||||
[-s, --salt <string>]</code></pre>
|
||||
|
||||
Hashes a password and writes the output to stdout, then exits.
|
||||
Convenient way to hash a plaintext password. The resulting hash is written to stdout as a format usable directly in your Caddy config.
|
||||
|
||||
`--plaintext` is the plaintext form of the password. If omitted, interactive mode will be assumed and the user will be shown a prompt to enter the password manually.
|
||||
|
||||
`--algorithm` may be bcrypt or any installed hash algorithm. Default is bcrypt.
|
||||
`--algorithm` may be `bcrypt` or any installed hash algorithm. Default is `bcrypt`.
|
||||
|
||||
`--salt` is used only if the algorithm requires an external salt (like scrypt).
|
||||
`--salt` is used only if the algorithm requires an external salt (like `scrypt`).
|
||||
|
||||
Note that `scrypt` is deprecated. Please use `bcrypt` instead.
|
||||
|
||||
|
||||
|
||||
|
|
@ -250,7 +254,7 @@ Prints CLI help text, optionally for a specific subcommand, then exits.
|
|||
<pre><code class="cmd bash">caddy list-modules
|
||||
[--packages]
|
||||
[--versions]
|
||||
[--skip-standard]</code></pre>
|
||||
[-s, --skip-standard]</code></pre>
|
||||
|
||||
Prints the Caddy modules that are installed, optionally with package and/or version information from their associated Go modules, then exits.
|
||||
|
||||
|
|
@ -263,7 +267,7 @@ NOTE: Due to [a bug in Go](https://github.com/golang/go/issues/29228), version i
|
|||
### `caddy manpage`
|
||||
|
||||
<pre><code class="cmd bash">caddy manpage
|
||||
--directory <path></code></pre>
|
||||
(-o, --directory <path>)</code></pre>
|
||||
|
||||
Generates manual/documentation pages for Caddy commands and writes them to the directory at the specified path. The output of this command can be read by the `man` command.
|
||||
|
||||
|
|
@ -283,13 +287,14 @@ Manual pages are separate documentation from what is on our website. Our website
|
|||
|
||||
|
||||
|
||||
|
||||
### `caddy reload`
|
||||
|
||||
<pre><code class="cmd bash">caddy reload
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[--address <interface>]
|
||||
[--force]</code></pre>
|
||||
[-f, --force]</code></pre>
|
||||
|
||||
Gives the running Caddy instance a new configuration. This has the same effect as POSTing a document to the [/load endpoint](/docs/api#post-load), but this command is convenient for simple workflows revolving around config files. Compared to the `stop`, `start`, and `run` commands, this single command is the correct, semantic way to change/reload the running configuration.
|
||||
|
||||
|
|
@ -304,15 +309,17 @@ Because this command uses the API, the admin endpoint must not be disabled.
|
|||
`--force` will cause a reload to happen even if the specified config is the same as what Caddy is already running. Can be useful to force Caddy to reprovision its modules, which can have side-effects, for example: reloading manually-loaded TLS certificates.
|
||||
|
||||
|
||||
|
||||
|
||||
### `caddy respond`
|
||||
|
||||
<pre><code class="cmd bash">caddy respond
|
||||
[--status <code>]
|
||||
[--header "<Field>: <value>"]
|
||||
[--body <content>]
|
||||
[--listen <addr>]
|
||||
[-s, --status <code>]
|
||||
[-H, --header "<Field>: <value>"]
|
||||
[-b, --body <content>]
|
||||
[-l, --listen <addr>]
|
||||
[-v, --debug]
|
||||
[--access-log]
|
||||
[--debug]
|
||||
[<status|body>]</code></pre>
|
||||
|
||||
|
||||
|
|
@ -326,9 +333,9 @@ Starts one or more simple, hard-coded HTTP servers that are useful for developme
|
|||
|
||||
`--listen` is the listener address, which can be any [network address](/docs/conventions#network-addresses) recognized by Caddy, and may include a port range to start multiple servers.
|
||||
|
||||
`--access-log` enables access/request logging.
|
||||
`--debug` enables verbose debug logging.
|
||||
|
||||
`--debug` enables more verbose debug logging.
|
||||
`--access-log` enables access/request logging.
|
||||
|
||||
With no options specified, this command listens on a random available port and answers HTTP requests with an empty 200 response. The listen address can be customized with the `--listen` flag and will always be printed to stdout. If the listen address includes a port range, multiple servers will be started.
|
||||
|
||||
|
|
@ -370,45 +377,62 @@ Pipe in a maintenance page:
|
|||
--header "Content-Type: text/html"</code></pre>
|
||||
|
||||
|
||||
|
||||
|
||||
### `caddy reverse-proxy`
|
||||
|
||||
<pre><code class="cmd bash">caddy reverse-proxy
|
||||
[--from <addr>]
|
||||
--to <addr>
|
||||
[--change-host-header]
|
||||
[--disable-redirects]
|
||||
[--internal-certs]
|
||||
[--debug]</code></pre>
|
||||
[-f, --from <addr>]
|
||||
(-t, --to <addr>)
|
||||
[-H, --header-up "<Field>: <value>"]
|
||||
[-d, --header-down "<Field>: <value>"]
|
||||
[-c, --change-host-header]
|
||||
[-r, --disable-redirects]
|
||||
[-i, --internal-certs]
|
||||
[-v, --debug]
|
||||
[--access-log]
|
||||
[--insecure]</code></pre>
|
||||
|
||||
Spins up a simple but production-ready HTTP(S) reverse proxy.
|
||||
A simple but production-ready reverse proxy. Useful for quick deployments, demos, and development.
|
||||
|
||||
`--from` is the address to proxy from.
|
||||
Simply shuttles HTTP(S) traffic from the `--from` address to the `--to` address. Multiple `--to` addresses may be specified by repeating the flag. At least one `--to` address is required. The `--to` address may have a port range as a shortcut to expand to multiple upstreams.
|
||||
|
||||
`--to` is the address(es) to proxy to. Can be repeated to load balance between multiple upstreams.
|
||||
Unless otherwise specified in the addresses, the `--from` address will be assumed to be HTTPS if a hostname is given, and the `--to` address will be assumed to be HTTP.
|
||||
|
||||
`--change-host-header` will cause Caddy to change the Host header from the incoming value to the address of the upstream.
|
||||
If the `--from` address has a host or IP, Caddy will attempt to serve the proxy over HTTPS with a certificate (unless overridden by the HTTP scheme or port).
|
||||
|
||||
`--disable-redirects` prevents Automatic HTTPS from enabling the HTTP->HTTPS redirects, if the `--from` address would enable HTTPS.
|
||||
If serving HTTPS:
|
||||
- `--disable-redirects` can be used to avoid binding to the HTTP port.
|
||||
|
||||
`--internal-certs` will cause Caddy to issue certificates using its internal issuer (effectively self-signed) for the domain specified in the `--from` address.
|
||||
- `--internal-certs` can be used to force issuance certs using the internal CA instead of attempting to issue a public certificate.
|
||||
|
||||
`--debug` enables verbose logging.
|
||||
For proxying:
|
||||
- `--header-up` can be used to set a request header to send to the upstream.
|
||||
|
||||
- `--header-down` can be used to set a response header to send back to the client.
|
||||
|
||||
- `--change-host-header` sets the Host header on the request to the address of the upstream, instead of defaulting to the incoming Host header.
|
||||
|
||||
Both `--from` and `--to` parameters can be URLs, as scheme and domain name will be inferred from the provided URL (paths and query strings ignored). Or they can be a simple network address and not a complete URL.
|
||||
This is a shortcut for `--header-up "Host: {http.reverse_proxy.upstream.hostport}"`
|
||||
|
||||
- `--insecure` disables TLS verification with the upstream. WARNING: THIS DISABLES SECURITY BY NOT VERIFYING THE UPSTREAM'S CERTIFICATE.
|
||||
|
||||
- `--debug` enables verbose logging.
|
||||
|
||||
This command disables the admin API so it is easier to run multiple instances on a local development machine.
|
||||
|
||||
|
||||
|
||||
### `caddy run`
|
||||
|
||||
<pre><code class="cmd bash">caddy run
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[--pidfile <file>]
|
||||
[--environ]
|
||||
[-e, --environ]
|
||||
[--envfile <file>]
|
||||
[--resume]
|
||||
[--watch]</code></pre>
|
||||
[-r, --resume]
|
||||
[-w, --watch]</code></pre>
|
||||
|
||||
Runs Caddy and blocks indefinitely; i.e. "daemon" mode.
|
||||
|
||||
|
|
@ -435,15 +459,15 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode.
|
|||
### `caddy start`
|
||||
|
||||
<pre><code class="cmd bash">caddy start
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[--envfile <file>]
|
||||
[--pidfile <file>]
|
||||
[--watch]</code></code></pre>
|
||||
[-w, --watch]</code></code></pre>
|
||||
|
||||
Same as [`caddy run`](#caddy-run), but in the background. This command only blocks until the background process is running successfully (or fails to run), then returns.
|
||||
|
||||
Note: the flag `--config` doesn't support `-` to read the config from stdin.
|
||||
Note: the flag `--config` does _not_ support `-` to read the config from stdin.
|
||||
|
||||
Use of this command is discouraged with system services or on Windows. On Windows, the child process will remain attached to the terminal, so closing the window will forcefully stop Caddy, which is not obvious. Consider running Caddy [as a service](/docs/running) instead.
|
||||
|
||||
|
|
@ -455,7 +479,7 @@ Once started, you can use [`caddy stop`](#caddy-stop) or the [`POST /stop`](/doc
|
|||
|
||||
<pre><code class="cmd bash">caddy stop
|
||||
[--address <interface>]
|
||||
[--config <path> [--adapter <name>]]</code></pre>
|
||||
[-c, --config <path> [-a, --adapter <name>]]</code></pre>
|
||||
|
||||
<aside class="tip">
|
||||
|
||||
|
|
@ -476,7 +500,7 @@ If you want to stop the current configuration but do not want to exit the proces
|
|||
<pre><code class="cmd bash">caddy trust
|
||||
[--ca <id>]
|
||||
[--address <interface>]
|
||||
[--config <path> [--adapter <name>]]</code></pre>
|
||||
[-c, --config <path> [-a, --adapter <name>]]</code></pre>
|
||||
|
||||
Installs a root certificate for a CA managed by Caddy's [PKI app](/docs/json/apps/pki/) into local trust stores.
|
||||
|
||||
|
|
@ -492,10 +516,10 @@ You may also use the `caddy` binary with this command to install certificates on
|
|||
### `caddy untrust`
|
||||
|
||||
<pre><code class="cmd bash">caddy untrust
|
||||
[--cert <path>]
|
||||
[-p, --cert <path>]
|
||||
[--ca <id>]
|
||||
[--address <interface>]
|
||||
[--config <path> [--adapter <name>]]</code></pre>
|
||||
[-c, --config <path> [-a, --adapter <name>]]</code></pre>
|
||||
|
||||
Untrusts a root certificate from the local trust store(s).
|
||||
|
||||
|
|
@ -513,7 +537,7 @@ If the admin API is used, then the CA ID defaults to "local". You may specify th
|
|||
### `caddy upgrade`
|
||||
|
||||
<pre><code class="cmd bash">caddy upgrade
|
||||
[--keep-backup]</code></pre>
|
||||
[-k, --keep-backup]</code></pre>
|
||||
|
||||
Replaces the current Caddy binary with the latest version from [our download page](https://caddyserver.com/download) with the same modules installed, including all third-party plugins that are registered on the Caddy website.
|
||||
|
||||
|
|
@ -528,7 +552,7 @@ This command may require elevated privileges if your user does not have permissi
|
|||
### `caddy add-package`
|
||||
|
||||
<pre><code class="cmd bash">caddy add-package <packages...>
|
||||
[--keep-backup]</code></pre>
|
||||
[-k, --keep-backup]</code></pre>
|
||||
|
||||
Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest version with the same modules installed, _plus_ the packages listed as arguments included in the new binary. Find the list of packages you can install from [our download page](https://caddyserver.com/download). Each argument should be the full package name.
|
||||
|
||||
|
|
@ -541,7 +565,7 @@ For example:
|
|||
### `caddy remove-package`
|
||||
|
||||
<pre><code class="cmd bash">caddy remove-package <packages...>
|
||||
[--keep-backup]</code></pre>
|
||||
[-k, --keep-backup]</code></pre>
|
||||
|
||||
Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest version with the same modules installed, but _without_ the packages listed as arguments, if they existed in the current binary. Run `caddy list-modules --packages` to see the list of package names of non-standard modules included in the current binary.
|
||||
|
||||
|
|
@ -550,8 +574,8 @@ Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest
|
|||
### `caddy validate`
|
||||
|
||||
<pre><code class="cmd bash">caddy validate
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[--envfile <file>]</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.
|
||||
|
|
|
|||
|
|
@ -92,6 +92,7 @@ Placeholder | Description
|
|||
`{system.arch}` | The system's architecture
|
||||
`{system.wd}` | The current working directory
|
||||
`{time.now}` | The current time as a Go Time struct
|
||||
`{time.now.http}` | The current time in the format used in [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified)
|
||||
`{time.now.unix}` | The current time as a unix timestamp in seconds
|
||||
`{time.now.unix_ms}` | The current time as a unix timestamp in milliseconds
|
||||
`{time.now.common_log}` | The current time in Common Log Format
|
||||
|
|
|
|||
|
|
@ -56,6 +56,7 @@ Now compare an equivalent structured log message from Caddy, encoded as JSON and
|
|||
"request": {
|
||||
"remote_ip": "127.0.0.1",
|
||||
"remote_port": "41342",
|
||||
"client_ip": "127.0.0.1",
|
||||
"proto": "HTTP/2.0",
|
||||
"method": "GET",
|
||||
"host": "localhost",
|
||||
|
|
@ -73,6 +74,7 @@ Now compare an equivalent structured log message from Caddy, encoded as JSON and
|
|||
"server_name": "example.com"
|
||||
}
|
||||
},
|
||||
"bytes_read": 0,
|
||||
"user_id": "",
|
||||
"duration": 0.000929675,
|
||||
"size": 10900,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue