mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-24 05:56:15 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Big Caddyfile docs update (#374)

Browse source
This commit is contained in:
Francis Lavoie 2024-02-20 06:49:30 -05:00 • committed by GitHub
parent 3ec3033602
commit 22301d6a81
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
34 changed files with 1732 additions and 512 deletions
Download patch file Download diff file Expand all files Collapse all files

567
src/docs/markdown/caddyfile/options.md
View file

@ -33,6 +33,7 @@ window.$(function() {
});
</script>
# Global options
The Caddyfile has a way for you to specify options that apply globally. Some options act as default values; others customize HTTP servers and don't apply to just one particular site; while yet others customize the behavior of the Caddyfile [adapter](/docs/config-adapters).
@ -61,8 +62,6 @@ Possible options are (click on each option to jump to its documentation):
<options...>
}
storage_clean_interval <duration>
renew_interval <duration>
ocsp_interval <duration>
admin off|<addr> {
origins <origins...>
enforce_origin
@ -96,6 +95,8 @@ Possible options are (click on each option to jump to its documentation):
}
key_type ed25519|p256|p384|rsa2048|rsa4096
cert_issuer <name> ...
renew_interval <duration>
ocsp_interval <duration>
ocsp_stapling off
preferred_chains [smallest] {
root_common_name <common_names...>
@ -165,11 +166,19 @@ Enables debug mode, which sets the log level to `DEBUG` for the [default logger]
##### `http_port`
The port for the server to use for HTTP. For internal use only; does not change the HTTP port for clients. Default: `80`
The port for the server to use for HTTP.
**For internal use only**; does not change the HTTP port for clients. This is typically used if within your internal network, you needed to port forward `80` to a different port (e.g. `8080`) before it reaches Caddy, for routing purposes.
Default: `80`
##### `https_port`
The port for the server to use for HTTPS. For internal use only; does not change the HTTPS port for clients. Default: `443`
The port for the server to use for HTTPS.
**For internal use only**; does not change the HTTPS port for clients. This is typically used if within your internal network, you needed to port forward `443` to a different port (e.g. `8443`) before it reaches Caddy, for routing purposes.
Default: `443`
##### `default_bind`
@ -181,6 +190,12 @@ Keep in mind that this will only apply to servers which are generated by the Cad
</aside>
```caddy
{
default_bind 10.0.0.1
}
```
##### `order`
@ -188,8 +203,10 @@ Assigns an order to HTTP handler directive(s). As HTTP handlers execute in a seq
For example, to use the [`replace-response` plugin](https://github.com/caddyserver/replace-response), you'd want to make sure its directive is ordered after `encode` so that it can perform replacements before the response is encoded (because responses flow up the handler chain, not down):
```caddy-d
order replace after encode
```caddy
{
order replace after encode
}
```
@ -198,76 +215,186 @@ Configures Caddy's storage mechanism. The default is [`file_system`](/docs/json/
For example, to change the file system's storage location:
```caddy-d
storage file_system /path/to/custom/location
```caddy
{
storage file_system /path/to/custom/location
}
```
Customizing the storage module is typically needed when syncing Caddy's storage across multiple instances of Caddy to make sure they all use the same certificates and keys. See the [Automatic HTTPS section on storage](/docs/automatic-https#storage) for more details.
##### `storage_clean_interval`
How often to scan storage units for old or expired assets and remove them. These scans exert lots of reads (and list operations) on the storage module, so choose a longer interval for large deployments. Accepts [duration values](/docs/conventions#durations). Default: `24h`.
How often to scan storage units for old or expired assets and remove them. These scans exert lots of reads (and list operations) on the storage module, so choose a longer interval for large deployments. Accepts [duration values](/docs/conventions#durations).
Storage will always be cleaned when the process first starts. Then, a new cleaning will be started this duration after the previous cleaning started if the previous cleaning finished in less than half the time of this interval (otherwise next start will be skipped).
Default: `24h`
##### `renew_interval`
How often to scan all loaded, managed certificates for expiration, and trigger renewal if expired. Default: `10m`.
```caddy
{
storage_clean_interval 7d
}
```
##### `ocsp_interval`
How often to check if OCSP staples need updating. Default: `1h`.
##### `admin`
Customizes the [admin API endpoint](/docs/api). Accepts placeholders. If `off`, then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server. Remember to use the `--address` CLI flag to specify the current admin endpoint when changing this value if the currently-running admin endpoint is not at the default address.
Customizes the [admin API endpoint](/docs/api). Accepts placeholders. Takes [network addresses](/docs/conventions#network-addresses).
- **origins** configures the list of remotes/origins that are allowed to connect to the endpoint.
Default: `localhost:2019`, unless the `CADDY_ADMIN` environment variable is set.
If set to `off`, then the admin endpoint will be disabled. When disabled, **config changes will be impossible** without stopping and starting the server, since the [`caddy reload` command](/docs/command-line#caddy-reload) uses the admin API to push the new config to the running server.
Remember to use the `--address` CLI flag with compatible [commands](/docs/command-line) to specify the current admin endpoint, if the address of the running server was changed from the default.
Also supports these sub-options:
- **origins** configures the list of origins that are allowed to connect to the endpoint.
A default is intelligently chosen:
- if the listen address is loopback (e.g. `localhost` or a loopback IP, or a unix socket) then the allowed origins are `localhost`, `::1` and `127.0.0.1`, joined with the listen address port (so `localhost:2019` is a valid origin).
- if the listen address is not loopback, then the allowed origin is the same as the listen address.
If the listen address host is not a wildcard interface (wildcards include: empty string, or `0.0.0.0`, or `[::]`), then `Host` header enforcement is performed. Effectively, this means that by default, the `Host` header is validated to be in `origins`, since the interface is `localhost`. But for an address like `:2020` which has a wildcard interface, `Host` header validation is not performed.
- **enforce_origin** enables enforcement of the `Origin` request header.
This is most useful when the listen address is a wildcard interface (since `Host` is not validated), and the admin API is exposed to the public internet. It enables CORS preflight checks and ensures that the `Origin` header is validated against the `origins` list. Only use this if you're running Caddy on your development machine and need to access the admin API from a web browser.
For example, to expose the admin API on a different port, on all interfaces — ⚠️ this port **should not be exposed publicly**, otherwise anyone can control your server; consider enabling origin enforcement if you need it to be public:
```caddy
{
admin :2020
}
```
To turn off the admin API — ⚠️ this makes **config reloads impossible** without stopping and starting the server:
```caddy
{
admin off
}
```
To use a [unix socket](/docs/conventions#network-addresses) for the admin API, allowing access control via file permissions:
```caddy
{
admin unix//run/caddy-admin.sock
}
```
To only allow requests having a matching `Origin` header:
```caddy
{
admin :2019 {
origins localhost
enforce_origin
}
}
```
- **enforce_origin** enables enforcement of the Origin header. (This is different from enforcing origins generally, which is always done.)
##### `persist_config`
Controls whether the current JSON config should be persisted to the [configuration directory](/docs/conventions#configuration-directory), to avoid losing config changes performed via the admin API. Currently, only the `off` option is supported. By default, the config is persisted.
```caddy
{
persist_config off
}
```
##### `log`
Configures named loggers. The name can be passed to indicate a specific logger for which to customize the behavior. If no name is specified, the behavior of the `default` logger is modified. Multiple loggers with different names can be configured by using the `log` multiple times. You can read more about the `default` logger and an explanation of [how logging works in Caddy](/docs/logging).
Configures named loggers.
The name can be passed to indicate a specific logger for which to customize the behavior. If no name is specified, the behavior of the `default` logger is modified. You can read more about the `default` logger and an explanation of [how logging works in Caddy](/docs/logging).
Multiple loggers with different names can be configured by using the `log` multiple times.
The differs from the [`log` directive](/docs/caddyfile/directives/log), which only configures HTTP request logging (also known as access logs). The `log` global option shares its configuration structure with the directive (except for `include` and `exclude`), and complete documentation can be found on the directive's page.
- **output** configures where to write the logs. See the [`log` directive](/docs/caddyfile/directives/log#output-modules) for complete documentation.
- **format** describes how to encode, or format, the logs. See the [`log` directive](/docs/caddyfile/directives/log#format-modules) for complete documentation.
- **level** is the minimum entry level to log. Possible values: `DEBUG`, `INFO`, `WARN`, `ERROR`, `PANIC`, `FATAL`. Default: `INFO`.
- **include** specifies the log names to be included in this logger. For example, to include only logs emitted by the admin API, you would include `admin.api`. By default, this list is empty (i.e. all logs are included).
- **exclude** specifies the log names to be excluded from this logger. For example, to exclude only HTTP access logs, you would exclude `http.log.access`. By default, this list is empty (i.e. no logs are excluded).
- **output** configures where to write the logs.
See the [`log` directive](/docs/caddyfile/directives/log#output-modules) for complete documentation.
- **format** describes how to encode, or format, the logs.
See the [`log` directive](/docs/caddyfile/directives/log#format-modules) for complete documentation.
- **level** is the minimum entry level to log.
Default: `INFO`.
Possible values: `DEBUG`, `INFO`, `WARN`, `ERROR`, and very rarely, `PANIC`, `FATAL`.
- **include** specifies the log names to be included in this logger.
By default, this list is empty (i.e. all logs are included).
For example, to include only logs emitted by the admin API, you would include `admin.api`.
- **exclude** specifies the log names to be excluded from this logger.
By default, this list is empty (i.e. no logs are excluded).
For example, to exclude only HTTP access logs, you would exclude `http.log.access`.
The logger names that `include` and `exclude` accept depend on the modules used, and easiest way to discover them is from prior logs.
Here is an example logging as json all http access logs and admin logs to stdout:
```caddy
log default {
output stdout
format json
include http.log.access admin.api
{
log default {
output stdout
format json
include http.log.access admin.api
}
}
```
##### `grace_period`
Defines the grace period for shutting down HTTP servers (i.e. during config changes or when Caddy is stopping). During the grace period, no new connections are accepted, idle connections are closed, and active connections are impatiently waited upon to finish their requests. If clients do not finish their requests within the grace period, the server will be forcefully terminated to allow the reload to complete and free up resources. Accepts [duration values](/docs/conventions#durations). By default, the grace period is eternal, which means connections are never forcefully closed.
Defines the grace period for shutting down HTTP servers (i.e. during config changes or when Caddy is stopping).
During the grace period, no new connections are accepted, idle connections are closed, and active connections are impatiently waited upon to finish their requests. If clients do not finish their requests within the grace period, the server will be forcefully terminated to allow the reload to complete and free up resources. Accepts [duration values](/docs/conventions#durations).
By default, the grace period is eternal, which means connections are never forcefully closed.
```caddy
{
grace_period 10s
}
```
##### `shutdown_delay`
Defines a duration before the grace period during which a server that is going to be stopped continues to operate normally, except the `{http.shutting_down}` placeholder evaluates to `true` and `{http.time_until_shutdown}` gives the time until the grace period begins. This causes a delay if any server is being shut down as part of a config change and effectively schedules the change for a later time. It is useful for announcing to health checkers of this server's impending doom and to give time for a load balancer to move it out of the rotation; for example:
Defines a [duration](/docs/conventions#durations)
_before_ the [grace period](#grace_period) during which a server that is going to be stopped continues to operate normally, except the `{http.shutting_down}` placeholder evaluates to `true` and `{http.time_until_shutdown}` gives the time until the grace period begins.
```caddy-d
handle /health-check {
@goingDown vars {http.shutting_down} true
respond @goingDown "Bye-bye in {http.time_until_shutdown}" 503
respond 200
This causes a delay if any server is being shut down as part of a config change, and effectively schedules the change for a later time. It is useful for announcing to health checkers of this server's impending doom and to give time for a load balancer to move it out of the rotation; for example:
```caddy
{
shutdown_delay 30s
}
example.com {
handle /health-check {
@goingDown vars {http.shutting_down} true
respond @goingDown "Bye-bye in {http.time_until_shutdown}" 503
respond 200
}
handle {
respond "Hello, world!"
}
}
```
@ -291,10 +418,16 @@ There are a few modes to choose from:
This option does not affect Caddy's default protocol, which is always HTTPS, when a site address has a valid domain name. This means that `auto_https off` will not cause your site to be served over HTTP, it will only disable automatic certificate management and redirects.
This means that if you wish to serve your site over HTTP, you should change your [site address](/docs/caddyfile/concepts#addresses) to be prefixed with `http://` or suffixed with `:80`.
This means that if you wish to serve your site over HTTP, you should change your [site address](/docs/caddyfile/concepts#addresses) to be prefixed with `http://` or suffixed with `:80` (or the [`http_port` option](#http_port)).
</aside>
```caddy
{
auto_https disable_redirects
}
```
##### `email`
Your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates.
@ -305,44 +438,112 @@ Keep in mind that Let's Encrypt may send you emails about your certificate neari
</aside>
```caddy
{
email admin@example.com
}
```
##### `default_sni`
Sets a default TLS ServerName for when clients do not use SNI in their ClientHello.
```caddy
{
default_sni example.com
}
```
##### `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>
⚠️ <i>Experimental</i>
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.
```caddy
{
fallback_sni example.com
}
```
##### `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.
Causes **all** certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful as a quick toggle in development environments.
```caddy
{
local_certs
}
```
##### `skip_install_trust`
Skips the attempts to install the local CA's root into the system trust store, as well as into Java and Mozilla Firefox trust stores.
```caddy
{
skip_install_trust
}
```
##### `acme_ca`
Specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint <img src="/old/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: ZeroSSL and Let's Encrypt's production endpoints.
Note that a globally-configured ACME CA may not apply to all sites; see the [hostname requirements](/docs/automatic-https#hostname-requirements) for using the default ACME issuer(s).
```caddy
{
acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}
```
##### `acme_ca_root`
Specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store.
```caddy
{
acme_ca_root /path/to/ca/root.pem
}
```
##### `acme_eab`
Specifies an External Account Binding to use for all ACME transactions.
For example, with mock ZeroSSL credentials:
```caddy
{
acme_eab GD-VvWydSVFuss_GhBwYQQ MjXU3MH-Z0WQ7piMAnVsCpD1shgMiWx6ggPWiTmydgUaj7dWWWfQfA
}
```
##### `acme_dns`
Configures the ACME DNS challenge provider to use for all ACME transactions. The tokens following the name of the provider set up the provider the same as if specified in the [`tls` directive's `acme` issuer](/docs/caddyfile/directives/tls#acme).
Configures the [ACME DNS challenge](/docs/automatic-https#dns-challenge) provider to use for all ACME transactions.
Requires a custom build of Caddy with a plugin for your DNS provider.
The tokens following the name of the provider set up the provider the same as if specified in the [`tls` directive's `acme` issuer](/docs/caddyfile/directives/tls#acme).
```caddy
{
acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}
```
##### `on_demand_tls`
Configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [`on_demand` subdirective of the `tls` directive](/docs/caddyfile/directives/tls#syntax)). Required for use in production environments, to prevent abuse.
- **ask** will cause Caddy to make an HTTP request to the given URL with a query string of `?domain=` containing the value of the domain name. If the endpoint returns a `2xx` status code, Caddy will be authorized to obtain a certificate for that name. Any other status code will result in cancelling issuance of the certificate.
- **ask** will cause Caddy to make an HTTP request to the given URL, asking whether a domain is allowed to have a certificate issued.
The request has a query string of `?domain=` containing the value of the domain name.
If the endpoint returns a `2xx` status code, Caddy will be authorized to obtain a certificate for that name. Any other status code will result in cancelling issuance of the certificate and erroring the TLS handshake.
<aside class="tip">
@ -352,33 +553,115 @@ The ask endpoint should return _as fast as possible_, in a few milliseconds, ide
- **interval** and **burst** allows `<n>` certificate operations within `<duration>` interval.
```caddy
{
on_demand_tls {
ask http://localhost:9123/ask
}
}
https:// {
tls {
on_demand
}
}
```
##### `key_type`
Specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it. The possible values are: `ed25519`, `p256`, `p384`, `rsa2048`, `rsa4096`.
Specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it.
The possible values are: `ed25519`, `p256`, `p384`, `rsa2048`, `rsa4096`.
```caddy
{
key_type ed25519
}
```
##### `cert_issuer`
Defines the issuer (or source) of TLS certificates. The tokens following the name of the issuer set up the issuer the same as if specified in the [`tls` directive](/docs/caddyfile/directives/tls#issuer). May be repeated if you wish to configure more than one issuer to try. They will be tried in the order they are defined.
Defines the issuer (or source) of TLS certificates.
This allows configuring issuers globally, instead of per-site as you would with the [`tls` directive's `issuer` subdirective](/docs/caddyfile/directives/tls#issuer).
May be repeated if you wish to configure more than one issuer to try. They will be tried in the order they are defined.
```caddy
{
cert_issuer acme {
...
}
cert_issuer zerossl {
...
}
}
```
##### `renew_interval`
How often to scan all loaded, managed certificates for expiration, and trigger renewal if expired.
Default: `10m`
```caddy
{
renew_interval 30m
}
```
##### `ocsp_interval`
How often to check if [OCSP staples <img src="/old/resources/images/external-link.svg" class="external-link">](https://en.wikipedia.org/wiki/OCSP_stapling) need updating.
Default: `1h`
```caddy
{
ocsp_interval 2h
}
```
##### `ocsp_stapling`
Can be set to `off` to disable OCSP stapling. Useful in environments where responders are not reachable due to firewalls.
```caddy
{
ocsp_stapling off
}
```
##### `preferred_chains`
If your CA provides multiple certificate chains, you can use this option to specify which chain Caddy should prefer. Set one of the following options:
- **smallest** will tell Caddy to prefer chains with the fewest amount of bytes.
- **root_common_name** is a list of one or more common names; Caddy will choose the first chain that has a root that matches with at least one of the specified common names.
- **any_common_name** is a list of one or more common names; Caddy will choose the first chain that has an issuer that matches with at least one of the specified common names.
Note that specifying `preferred_chains` as a global option will affect all issuers if there isn't any [overriding issuer level config](/docs/caddyfile/directives/tls#acme).
```caddy
{
preferred_chains smallest
}
```
```caddy
{
preferred_chains {
root_common_name "ISRG Root X2"
}
}
```
## Server Options
Customizes [HTTP servers](/docs/json/apps/http/servers/) with settings that potentially span multiple sites and thus can't be rightly configured in site blocks. These options affect the listener/socket or other facilities beneath the HTTP layer.
Customizes [HTTP servers](/docs/json/apps/http/servers/) with settings that potentially span multiple sites, and thus can't be rightly configured in site blocks. These options affect the listener/socket or other facilities beneath the HTTP layer.
Can be specified more than once with different `listener_address` values to configure different options per server. For example, `servers :443` will only apply to the server that is bound to the listener address `:443`. Omitting the listener address will apply the options to any remaining server.
@ -406,6 +689,8 @@ For example, to configure different options for the servers on ports `:80` and `
}
```
When using `servers`, it will **only** apply to servers that **actually appear** in your Caddyfile (i.e. are produced by a site block). Remember, [Automatic HTTPS](/docs/automatic-https) will create a server listening on port `80` (or the [`http_port` option](#http_port)), to serve HTTP->HTTPS redirects and to solve the ACME HTTP challenge; this happens at runtime, i.e. _after_ the Caddyfile adapter applies `servers`. So in other words, this means that `servers` **will not** apply to `:80` unless you explicitly declare a site block like `http://` or `:80`.
<aside class="tip">
@ -419,7 +704,7 @@ If you are using the [`bind` directive](/docs/caddyfile/directives/bind) or the
}
# This will work because it's an exact match
servers 192.168.1.2:8080 {
servers 192.168.1.2:8080 {
name public
}
}
@ -439,12 +724,11 @@ If you are using the [`bind` directive](/docs/caddyfile/directives/bind) or the
##### `name`
A custom name to assign to this server. Usually helpful to identify a server by its name in logs and metrics. If not set, Caddy will define it dynamically using a `srvX` pattern, where `X` starts with 0 and increments based on the number of servers in the config.
A custom name to assign to this server. Usually helpful to identify a server by its name in logs and metrics. If not set, Caddy will define it dynamically using a `srvX` pattern, where `X` starts with `0` and increments based on the number of servers in the config.
<aside class="tip">
Keep in mind that only servers produced by site blocks in your config will have settings applied. [Automatic HTTPS](/docs/automatic-https) creates an `:80` server (or [`http_port`](#http_port)) at runtime, so if you want rename it, you'll need at least an empty `http://` site block.
Keep in mind there's a caveat if you want to name your HTTP server and are using Auto-HTTPS. The server name config doesn't persist past adapting the config, and Auto-HTTPS happens at runtime, from the JSON config.
To overcome this, you'll need to create an empty `:80` or `http://` site block and set this option. With that Auto-HTTPS will add its redirect routes to that server. For example:
For example:
```caddy
{
@ -472,26 +756,34 @@ http:// {
Allows configuring [listener wrappers](/docs/json/apps/http/servers/listener_wrappers/), which can modify the behaviour of the socket listener. They are applied in the given order.
There is a special no-op [`tls`](/docs/json/apps/http/servers/listener_wrappers/tls/) listener wrapper provided as a standard module which marks where TLS should be handled in the chain of listener wrappers. It should only be used if another listener wrapper must be placed in front of the TLS handshake.
There is a special no-op [`tls`](/docs/json/apps/http/servers/listener_wrappers/tls/) listener wrapper provided as a standard module which marks where TLS should be handled in the chain of listener wrappers. It should only be used if another listener wrapper must be placed in front of the TLS handshake. This _does not_ enable TLS for a server; e.g. if this is used on your `:80` HTTP server, it will still act as a no-op.
The standard distribution of Caddy includes the [`http_redirect`](/docs/json/apps/http/servers/listener_wrappers/http_redirect/) listener wrapper, which can look at the first few bytes of an incoming request to determine if it's likely HTTP (instead of TLS), and trigger an HTTP-to-HTTPS redirect on the same port but using the `https://` scheme. It must be placed _before_ the `tls` listener wrapper. For example:
The included [`http_redirect`](/docs/json/apps/http/servers/listener_wrappers/http_redirect/) listener wrapper can look at the first few bytes of an incoming request to determine if it's likely HTTP (instead of TLS), and trigger an HTTP-to-HTTPS redirect on the same port but using the `https://` scheme. This is most useful when serving HTTPS on a non-standard port (other than `443`), since browsers will try HTTP unless the scheme is specified. Don't use this on an HTTP server. It must be placed _before_ the `tls` listener wrapper. For example:
```caddy-d
listener_wrappers {
http_redirect
tls
```caddy
{
servers {
listener_wrappers {
http_redirect
tls
}
}
}
```
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:
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://github.com/haproxy/haproxy/blob/master/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 {
proxy_protocol {
timeout 2s
allow 192.168.86.1/24 192.168.86.1/24
```caddy
{
servers {
listener_wrappers {
proxy_protocol {
timeout 2s
allow 192.168.86.1/24 192.168.86.1/24
}
tls
}
}
tls
}
```
@ -506,6 +798,18 @@ listener_wrappers {
- **idle** is a [duration value](/docs/conventions#durations) that sets the maximum time to wait for the next request when keep-alives are enabled. Defaults to 5 minutes to help avoid resource exhaustion.
```caddy
{
servers {
timeouts {
read_body 10s
read_header 5s
write 30s
idle 10m
}
}
}
```
##### `trusted_proxies`
@ -514,7 +818,7 @@ Allows configuring IP ranges (CIDRs) of proxy servers from which requests should
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.
Some matchers or handlers may use the trust status of the request to make 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.
@ -523,7 +827,9 @@ Currently, only the `static` [IP source module](/docs/json/apps/http/servers/tru
Takes a static (unchanging) list of IP ranges (CIDRs) to trust.
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`
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 syntax is as follows:
```caddy-d
trusted_proxies static [private_ranges] <ranges...>
@ -544,17 +850,41 @@ Here's a complete example, trusting an example IPv4 range and an IPv6 range:
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.
```caddy
{
servers {
trusted_proxies static private_ranges
client_ip_headers X-Forwarded-For X-Real-IP
}
}
```
##### `metrics`
Enables Prometheus metrics collection; necessary before scraping metrics. Note that metrics reduce performance on really busy servers. (Our community is working on improving this. Please get involved!)
```caddy
{
servers {
metrics
}
}
```
##### `max_header_size`
The maximum size to parse from a client's HTTP request headers. If the limit is exceeded, the server will respond with HTTP status `431 Request Header Fields Too Large`. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go). By default, the limit is `1MB`.
```caddy
{
servers {
max_header_size 5MB
}
}
```
##### `enable_full_duplex`
@ -562,12 +892,20 @@ Enable full-duplex communication for HTTP/1 requests. Only has an effect if Cadd
For HTTP/1 requests, the Go HTTP server by default consumes any unread portion of the request body before beginning to write the response, preventing handlers from concurrently reading from the request and writing the response. Enabling this option disables this behavior and permits handlers to continue to read from the request while concurrently writing the response.
For HTTP/2 requests, the Go HTTP server always permits concurrent reads and responses, so this option has no effect.
For HTTP/2+ requests, the Go HTTP server always permits concurrent reads and responses, so this option has no effect.
Test thoroughly with your HTTP clients, as some older clients may not support full-duplex HTTP/1 which can cause them to deadlock. See [golang/go#57786](https://github.com/golang/go/issues/57786) for more info.
⚠️ This is an experimental feature. Subject to change or removal.
```caddy
{
servers {
enable_full_duplex
}
}
```
##### `log_credentials`
@ -575,11 +913,23 @@ Since Caddy v2.5, by default, headers with potentially sensitive information (`C
If you wish to _not_ have these headers redacted, you may enable the `log_credentials` option.
```caddy
{
servers {
log_credentials
}
}
```
##### `protocols`
The space-separated list of HTTP protocols to support. Default: `h1 h2 h3`. Accepted values are:
The space-separated list of HTTP protocols to support.
Default: `h1 h2 h3`
Accepted values are:
- `h1` for HTTP/1.1
- `h2` For HTTP/2
- `h2c` for HTTP/2 over cleartext
@ -589,6 +939,15 @@ Currently, enabling HTTP/2 (including H2C) necessarily implies enabling HTTP/1.1
Note that H2C ("Cleartext HTTP/2" or "H2 over TCP") and HTTP/3 are not implemented by the Go standard library, so some functionality or features may be limited. We recommend against enabling H2C unless it is absolutely necessary for your application.
```caddy
{
servers :80 {
protocols h1 h2c
}
}
```
##### `strict_sni_host`
@ -596,6 +955,13 @@ Enabling this requires that a request's `Host` header matches the value of the `
This option will automatically be turned on if [client authentication](/docs/caddyfile/directives/tls#client_auth) is configured. This disallows TLS client auth bypass (domain fronting) which could otherwise be exploited by sending an unprotected SNI value during a TLS handshake, then putting a protected domain in the Host header after establishing connection. This behavior is a safe default, but you may explicitly turn it off with `insecure_off`; for example in the case of running a proxy where domain fronting is desired and access is not restricted based on hostname.
```caddy
{
servers {
strict_sni_host on
}
}
```
@ -606,16 +972,64 @@ The PKI (Public Key Infrastructure) app is the foundation for Caddy's [Local HTT
The default CA ID is `local`. If the ID is omitted when configuring the `ca`, then `local` is assumed.
##### `name`
The user-facing name of the certificate authority. Default: `Caddy Local Authority`
The user-facing name of the certificate authority.
Default: `Caddy Local Authority`
```caddy
{
pki {
ca local {
name "My Local CA"
}
}
}
```
##### `root_cn`
The name to put in the CommonName field of the root certificate. Default: `{pki.ca.name} - {time.now.year} ECC Root`
The name to put in the CommonName field of the root certificate.
Default: `{pki.ca.name} - {time.now.year} ECC Root`
```caddy
{
pki {
ca local {
root_cn "My Local CA - 2024 ECC Root"
}
}
}
```
##### `intermediate_cn`
The name to put in the CommonName field of the intermediate certificates. Default: `{pki.ca.name} - ECC Intermediate`
The name to put in the CommonName field of the intermediate certificates.
Default: `{pki.ca.name} - ECC Intermediate`
```caddy
{
pki {
ca local {
intermediate_cn "My Local CA - ECC Intermediate"
}
}
}
```
##### `intermediate_lifetime`
The [duration](/docs/conventions#durations) for which intermediate certificates are valid. This value must be less than the lifetime of the root cert (`3600d` or 10 years). Default: `7d`. It is recommended not to change this unless absolutely necessary.
The [duration](/docs/conventions#durations) for which intermediate certificates are valid. This value **must** be less than the lifetime of the root cert (`3600d` or 10 years).
Default: `7d`. It is _not recommended_ to change this, unless absolutely necessary.
```caddy
{
pki {
ca local {
intermediate_lifetime 30d
}
}
}
```
##### `root`
A key pair (certificate and private key) to use as the root for the CA. If not specified, one will be generated and managed automatically.
@ -631,6 +1045,25 @@ A key pair (certificate and private key) to use as the intermediate for the CA.
- **cert** is the certificate. This should be the path to a PEM file, when using `pem_file` format.
- **key** is the private key. This should be the path to a PEM file, when using `pem_file` format.
```caddy
{
pki {
ca local {
root {
format pem_file
cert /path/to/root.pem
key /path/to/root.key
}
intermediate {
format pem_file
cert /path/to/intermediate.pem
key /path/to/intermediate.key
}
}
}
}
```
## Event Options