mirror of
https://github.com/caddyserver/website.git
synced 2025-04-21 04:26:16 -04:00
Docs for v2.7.0 (#322)
* Docs for v2.7.0 * Document named-routes & invoke, polish reverse_proxy * Storage import/export CLI docs * Header replacement defer * Proxy stream closing options, weighted round robin LB policy
This commit is contained in:
Francis Lavoie
GitHub
parent
0a8e6ef86b
commit
194beebc7c
15 changed files with 454 additions and 105 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,13 +7,17 @@ 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)
|
||||
5. [Snippets](#snippets)
|
||||
6. [Comments](#comments)
|
||||
7. [Environment variables](#environment-variables)
|
||||
8. [Global options](#global-options)
|
||||
6. [Named Routes](#named-routes)
|
||||
7. [Comments](#comments)
|
||||
8. [Environment variables](#environment-variables)
|
||||
9. [Global options](#global-options)
|
||||
|
||||
|
||||
## Structure
|
||||
|
|
@ -25,6 +29,7 @@ The Caddyfile's structure can be described visually:
|
|||
Key points:
|
||||
|
||||
- An optional [**global options block**](#global-options) can be the very first thing in the file.
|
||||
- [Snippets](#snippets) or [named routes](#named-routes) may optionally appear next.
|
||||
- Otherwise, the first line of the Caddyfile is **always** the [address(es)](#addresses) of the site to serve.
|
||||
- All [directives](#directives) and [matchers](#matchers) **must** go in a site block. There is no global scope or inheritance across site blocks.
|
||||
- If there is only one site block, its curly braces `{ }` are optional.
|
||||
|
|
@ -85,17 +90,17 @@ If a request matches multiple site blocks, the site block with the most specific
|
|||
[**Directives**](/docs/caddyfile/directives) are functional keywords which customize how the site is served. They **must** appear within site blocks. For example, a complete file server config might look like this:
|
||||
|
||||
```caddy
|
||||
localhost
|
||||
|
||||
file_server
|
||||
localhost {
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
Or a reverse proxy:
|
||||
|
||||
```caddy
|
||||
localhost
|
||||
|
||||
reverse_proxy localhost:9000
|
||||
localhost {
|
||||
reverse_proxy localhost:9000
|
||||
}
|
||||
```
|
||||
|
||||
In these examples, [`file_server`](/docs/caddyfile/directives/file_server) and [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) are directives. Directives are the first word on a line in a site block.
|
||||
|
|
@ -105,10 +110,10 @@ In the second example, `localhost:9000` is an **argument** because it appears on
|
|||
Sometimes directives can open their own blocks. **Subdirectives** appear on the beginning of each line within directive blocks:
|
||||
|
||||
```caddy
|
||||
localhost
|
||||
|
||||
reverse_proxy localhost:9000 localhost:9001 {
|
||||
lb_policy first
|
||||
localhost {
|
||||
reverse_proxy localhost:9000 localhost:9001 {
|
||||
lb_policy first
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -156,6 +161,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 +260,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 +322,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 {
|
||||
|
|
@ -310,6 +335,27 @@ b.example.com {
|
|||
```
|
||||
|
||||
|
||||
## Named Routes
|
||||
|
||||
Named routes use syntax similar to [snippets](#snippets); they're a special block defined outside of site blocks, prefixed with `&(` and ending in `)` with the name in between.
|
||||
|
||||
```caddy
|
||||
&(app-proxy) {
|
||||
reverse_proxy app-01:8080 app-02:8080 app-03:8080
|
||||
}
|
||||
```
|
||||
|
||||
And then you can reuse this named route within any site:
|
||||
|
||||
```caddy-d
|
||||
invoke app-proxy
|
||||
```
|
||||
|
||||
This is particularly useful to reduce memory usage if the same route is needed in many different sites, or if multiple different matcher conditions are needed to invoke the same route.
|
||||
|
||||
See the [`invoke` directive](/docs/caddyfile/directives/invoke) documentation for more details.
|
||||
|
||||
|
||||
## Comments
|
||||
|
||||
Comments start with `#` and proceed until the end of the line:
|
||||
|
|
|
|||
|
|
@ -54,6 +54,7 @@ Directive | Description
|
|||
**[handle_path](/docs/caddyfile/directives/handle_path)** | Like handle, but strips path prefix
|
||||
**[header](/docs/caddyfile/directives/header)** | Sets or removes response headers
|
||||
**[import](/docs/caddyfile/directives/import)** | Include snippets or files
|
||||
**[invoke](/docs/caddyfile/directives/invoke)** | Invoke a named route
|
||||
**[log](/docs/caddyfile/directives/log)** | Enables access/request logging
|
||||
**[map](/docs/caddyfile/directives/map)** | Maps an input value to one or more outputs
|
||||
**[method](/docs/caddyfile/directives/method)** | Change the HTTP method internally
|
||||
|
|
@ -143,6 +144,7 @@ push
|
|||
templates
|
||||
|
||||
# special routing & dispatching directives
|
||||
invoke
|
||||
handle
|
||||
handle_path
|
||||
route
|
||||
|
|
|
|||
|
|
@ -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,16 +12,25 @@ By default, header operations are performed immediately unless any of the header
|
|||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
header [<matcher>] [[+|-|?]<field> [<value>|<find>] [<replace>]] {
|
||||
# Replace
|
||||
<field> <find> <replace>
|
||||
header [<matcher>] [[+|-|?|>]<field> [<value>|<find>] [<replace>]] {
|
||||
# Add
|
||||
+<field> <value>
|
||||
|
||||
# Add or Set
|
||||
[+]<field> <value>
|
||||
# Set
|
||||
<field> <value>
|
||||
|
||||
# Set with defer
|
||||
><field> <value>
|
||||
|
||||
# Delete
|
||||
-<field>
|
||||
|
||||
# Replace
|
||||
<field> <find> <replace>
|
||||
|
||||
# Replace with defer
|
||||
><field> <find> <replace>
|
||||
|
||||
# Default
|
||||
?<field> <value>
|
||||
|
||||
|
|
@ -37,13 +46,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 +117,16 @@ 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
|
||||
```
|
||||
|
||||
To perform a deferred update of a `Set-Cookie` header to add `SameSite=None`; a regexp capture is used to grab the existing value, and `$1` re-inserts it at the start with the additional option appended:
|
||||
|
||||
```caddy-d
|
||||
header >Set-Cookie (.*) "$1; SameSite=None;"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
```
|
||||
|
|
|
|||
56
src/docs/markdown/caddyfile/directives/invoke.md
Normal file
56
src/docs/markdown/caddyfile/directives/invoke.md
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
---
|
||||
title: invoke (Caddyfile directive)
|
||||
---
|
||||
|
||||
# invoke
|
||||
|
||||
Invokes a [named route](/docs/caddyfile/concepts#named-routes).
|
||||
|
||||
This is useful when paired with HTTP handler directives that have their own in-memory state, or if they are expensive to provision on load. If you have hundreds of sites or more, invoking a named route can help reduce memory usage.
|
||||
|
||||
<aside class="tip">
|
||||
|
||||
Unlike [`import`](/docs/caddyfile/directives/import), `invoke` does not support arguments, but you may use [`vars`](/docs/caddyfile/directives/vars) to define variables that can be used within the named route.
|
||||
|
||||
</aside>
|
||||
|
||||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
invoke [<matcher>] <route-name>
|
||||
```
|
||||
|
||||
- **<route-name>** is the name of the previously defined route that should be invoked. If the route is not found, then an error will be triggered.
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
Defines a [named route](/docs/caddyfile/concepts#named-routes) with a [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) which can be reused in multiple sites, with the same in-memory load balancing state reused for every site.
|
||||
|
||||
```caddy
|
||||
&(app-proxy) {
|
||||
reverse_proxy app-01:8080 app-02:8080 app-03:8080 {
|
||||
lb_policy least_conn
|
||||
health_uri /healthz
|
||||
health_interval 5s
|
||||
}
|
||||
}
|
||||
|
||||
# Apex domain allows accessing the app via an /app subpath
|
||||
# and the main site otherwise.
|
||||
example.com {
|
||||
handle_path /app* {
|
||||
invoke app-proxy
|
||||
}
|
||||
|
||||
handle {
|
||||
root * /srv
|
||||
file_server
|
||||
}
|
||||
}
|
||||
|
||||
# The app is also accessible via a subdomain.
|
||||
app.example.com {
|
||||
invoke app-proxy
|
||||
}
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -83,9 +83,11 @@ reverse_proxy [<matcher>] [<upstreams...>] {
|
|||
unhealthy_request_count <num>
|
||||
|
||||
# streaming
|
||||
flush_interval <duration>
|
||||
request_buffers <size>
|
||||
response_buffers <size>
|
||||
flush_interval <duration>
|
||||
request_buffers <size>
|
||||
response_buffers <size>
|
||||
stream_timeout <duration>
|
||||
stream_close_delay <duration>
|
||||
|
||||
# request/header manipulation
|
||||
trusted_proxies [private_ranges] <ranges...>
|
||||
|
|
@ -141,6 +143,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 +155,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 +206,7 @@ Retrieves upstreams from A/AAAA DNS records.
|
|||
resolvers <ip...>
|
||||
dial_timeout <duration>
|
||||
dial_fallback_delay <duration>
|
||||
versions ipv4|ipv6
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -212,6 +216,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
|
||||
|
|
@ -231,31 +236,39 @@ Append the results of multiple dynamic upstream modules. Useful if you want redu
|
|||
|
||||
### Load balancing
|
||||
|
||||
Load balancing is used whenever more than one upstream is defined.
|
||||
Load balancing is used whenever more than one upstream is defined. This is enabled by default, with the `random` load balancing policy.
|
||||
|
||||
- **lb_policy** <span id="lb_policy"/> is the name of the load balancing policy, along with any options. Default: `random`.
|
||||
|
||||
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
|
||||
|
||||
- `weighted_round_robin <weights...>` iterates each upstream in turn, respecting the weights provided. The amount of weight arguments should match the amount of upstreams configured. Weights should be non-zero positive integers. For example with two upstreams and weights `5 1`, the first upstream would be selected 5 times in a row before the second upstream is selected once, then the cycle repeats.
|
||||
|
||||
- `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
|
||||
|
|
@ -286,13 +299,13 @@ Load balancing is used whenever more than one upstream is defined.
|
|||
|
||||
#### Active health checks
|
||||
|
||||
Active health checks perform health checking in the background on a timer:
|
||||
Active health checks perform health checking in the background on a timer. To enable this, `health_uri` or `health_port` are required.
|
||||
|
||||
- **health_uri** <span id="health_uri"/> is the URI path (and optional query) for active health checks.
|
||||
|
||||
- **health_port** <span id="health_port"/> is the port to use for active health checks, if different from the upstream's port.
|
||||
|
||||
- **health_interval** <span id="health_interval"/> is a [duration value](/docs/conventions#durations) that defines how often to perform active health checks.
|
||||
- **health_interval** <span id="health_interval"/> is a [duration value](/docs/conventions#durations) that defines how often to perform active health checks. Default: `30s`.
|
||||
|
||||
- **health_timeout** <span id="health_timeout"/> is a [duration value](/docs/conventions#durations) that defines how long to wait for a reply before marking the backend as down.
|
||||
|
||||
|
|
@ -306,7 +319,7 @@ Active health checks perform health checking in the background on a timer:
|
|||
|
||||
#### Passive health checks
|
||||
|
||||
Passive health checks happen inline with actual proxied requests:
|
||||
Passive health checks happen inline with actual proxied requests. To enable this, `fail_duration` is required.
|
||||
|
||||
- **fail_duration** <span id="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; the default is `0` (off). A reasonable starting point might be `30s` to balance error rates with responsiveness when bringing an unhealthy upstream back online; but feel free to experiment to find the right balance for your usecase.
|
||||
|
||||
|
|
@ -324,7 +337,15 @@ Passive health checks happen inline with actual proxied requests:
|
|||
|
||||
### Streaming
|
||||
|
||||
By default, the proxy partially buffers the response for wire efficiency:
|
||||
By default, the proxy partially buffers the response for wire efficiency.
|
||||
|
||||
The proxy also supports WebSocket connections, performing the HTTP upgrade request then transitioning the connection to a bidirectional tunnel.
|
||||
|
||||
<aside class="tip">
|
||||
|
||||
By default, WebSocket connections are forcibly closed (with a Close control message sent to both the client and upstream) when the config is reloaded. Each request holds a reference to the config, so closing old connections is necessary to keep memory usage in check. This closing behaviour can be customized with the [`stream_timeout`](#stream_timeout) and [`stream_close_delay`](#stream_close_delay) options.
|
||||
|
||||
</aside>
|
||||
|
||||
- **flush_interval** <span id="flush_interval"/> is a [duration value](/docs/conventions#durations) that adjusts how often Caddy should flush the response buffer to the client. By default, no periodic flushing is done. A negative value (typically -1) suggests "low-latency mode" which disables response buffering completely and flushes immediately after each write to the client, and does not cancel the request to the backend even if the client disconnects early. This option is ignored and responses are flushed immediately to the client if one of the following applies from the response:
|
||||
- `Content-Type: text/event-stream`
|
||||
|
|
@ -335,6 +356,10 @@ By default, the proxy partially buffers the response for wire efficiency:
|
|||
|
||||
- **response_buffers** <span id="response_buffers"/> will cause the proxy to read up to `<size>` amount of bytes from the response body to be read into a buffer before being returned to the client. This should be avoided if at all possible for performance reasons, but could be useful if the backend has tighter memory constraints. This accepts all size formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go).
|
||||
|
||||
- **stream_timeout** <span id="stream_timeout"/> is a [duration value](/docs/conventions#durations) after which streaming requests such as WebSockets will be forcibly closed atthe end of the timeout. This essentially cancels connections if they stay open too long. A reasonable starting point might be `24h` to cull connections older than a day. Default: no timeout.
|
||||
|
||||
- **stream_close_delay** <span id="stream_close_delay"/> is a [duration value](/docs/conventions#durations) which delays streaming requests such as WebSockets from being forcibly closed when the config is unloaded; instead, the stream will remain open until the delay is complete. In other words, enabling this prevents streams from immediately closing when Caddy's config is reloaded. Enabling this may be a good idea to avoid a thundering herd of reconnecting clients which had their connections closed by the previous config closing. A reasonable starting point might be something like `5m` to allow users 5 minutes to leave the page naturally after a config reload. Default: no delay.
|
||||
|
||||
|
||||
|
||||
### Headers
|
||||
|
|
@ -364,12 +389,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 +422,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 +477,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 +507,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,10 +12,12 @@ 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.
|
||||
|
||||
The `--flags` may have a single-letter shortcut like `-f`.
|
||||
|
||||
**Quick start: `caddy`, `caddy help`, or `man caddy` (if installed)**
|
||||
|
||||
---
|
||||
|
|
@ -71,6 +73,12 @@ The ellipses `...` indicates a continuation, i.e. one or more parameters.
|
|||
- **[caddy stop](#caddy-stop)**
|
||||
Stops the running Caddy process
|
||||
|
||||
- **[caddy storage export](#caddy-storage)**
|
||||
Exports the contents of the configured storage to a tarball
|
||||
|
||||
- **[caddy storage import](#caddy-storage)**
|
||||
Imports a previously exported tarball to the configured storage
|
||||
|
||||
- **[caddy trust](#caddy-trust)**
|
||||
Installs a certificate into local trust store(s)
|
||||
|
||||
|
|
@ -104,9 +112,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.
|
||||
|
|
@ -178,13 +186,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.
|
||||
|
||||
|
|
@ -213,7 +221,9 @@ Exports the default file browsing template to stdout
|
|||
|
||||
### `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.
|
||||
|
||||
|
|
@ -229,17 +239,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.
|
||||
|
||||
|
||||
|
||||
|
|
@ -257,7 +269,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.
|
||||
|
||||
|
|
@ -270,7 +282,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.
|
||||
|
||||
|
|
@ -290,13 +302,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.
|
||||
|
||||
|
|
@ -311,15 +324,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>
|
||||
|
||||
|
||||
|
|
@ -333,9 +348,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.
|
||||
|
||||
|
|
@ -377,45 +392,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.
|
||||
|
||||
|
|
@ -442,15 +474,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.
|
||||
|
||||
|
|
@ -462,7 +494,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">
|
||||
|
||||
|
|
@ -478,12 +510,57 @@ The address of this request can be customized using the `--address` flag, or fro
|
|||
If you want to stop the current configuration but do not want to exit the process, use [`caddy reload`](#caddy-reload) with a blank config, or the [`DELETE /config/`](/docs/api#delete-configpath) endpoint.
|
||||
|
||||
|
||||
### `caddy storage`
|
||||
|
||||
Allows export and import of the contents of Caddy's configured data storage.
|
||||
|
||||
This is useful when needing to transition from one [storage module](/docs/json/storage/) to another, by exporting from your old one, updating your config, then importing into the new one.
|
||||
|
||||
The following command can be used to do this all in one shot, using and old and new config with different configured storage modules, piping the export output into the
|
||||
|
||||
```
|
||||
$ caddy storage export -c Caddyfile.old -o- |
|
||||
caddy storage import -c Caddyfile.new -i-
|
||||
```
|
||||
|
||||
<aside class="advice">
|
||||
|
||||
Please note that when using [filesystem storage](/docs/conventions#data-directory), you must run the export command as the same user that Caddy normally runs as, otherwise the wrong storage location may be used.
|
||||
|
||||
For example, when running Caddy as a [systemd service](/docs/running#linux-service), it will run as the `caddy` user, so you should run the export or import commands as that user. This can typically be done with `sudo -u caddy <command>`.
|
||||
|
||||
</aside>
|
||||
|
||||
|
||||
#### `caddy storage export`
|
||||
|
||||
<pre><code class="cmd bash">caddy storage export
|
||||
-c, --config <path>
|
||||
[-o, --output <path>]</code></pre>
|
||||
|
||||
`--config` is the config file load. This is required, so that the correct storage module is connected to.
|
||||
|
||||
`--output` is the filename to write the tarball. If `-`, the output is written to stdout.
|
||||
|
||||
|
||||
|
||||
#### `caddy storage import`
|
||||
|
||||
<pre><code class="cmd bash">caddy storage import
|
||||
-c, --config <path>
|
||||
-i, --input <path></code></pre>
|
||||
|
||||
`--config` is the config file load. This is required, so that the correct storage module is connected to.
|
||||
|
||||
`--input` is the filename of the tarball to read from. If `-`, the input is read from stdin.
|
||||
|
||||
|
||||
### `caddy trust`
|
||||
|
||||
<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.
|
||||
|
||||
|
|
@ -499,10 +576,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).
|
||||
|
||||
|
|
@ -520,7 +597,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.
|
||||
|
||||
|
|
@ -535,7 +612,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.
|
||||
|
||||
|
|
@ -548,7 +625,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.
|
||||
|
||||
|
|
@ -557,8 +634,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