diff --git a/src/docs/markdown/api.md b/src/docs/markdown/api.md index 1486d39..57277c6 100644 --- a/src/docs/markdown/api.md +++ b/src/docs/markdown/api.md @@ -7,7 +7,7 @@ title: "API" Caddy is configured through an administration endpoint which can be accessed via HTTP using a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. You can [configure this endpoint](/docs/json/admin/) in your Caddy config. **Default address: `localhost:2019`** - +` @@ -246,7 +246,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. -- **healthy** reflects whether Caddy believes the upstream to be healthy or not. Note that "health" is a distinct concept from "availability". A healthy backend might not be available to proxy to, but an unhealthy backend will always be unavailable. Health is a global characteristic regardless of specific reverse proxy handler configuration, whereas availability is determined by the configuration of the specific reverse proxy handler. For example, a healthy backend would be unavailable if the handler is configured to only allow N requests at a time and it currently has N active requests. The "healthy" property does not reflect availability. +- **healthy** reflects whether Caddy believes the upstream to be healthy or not. Note that "health" is a distinct concept from "availability". An unhealthy backend will always be unavailable, but a healthy backend might not be available. Health is a global characteristic regardless of specific reverse proxy handler configuration, whereas availability is determined by the configuration of the specific reverse proxy handler. For example, a healthy backend would be unavailable if the handler is configured to only allow N requests at a time and it currently has N active requests. The "healthy" property does not reflect availability. - **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. diff --git a/src/docs/markdown/caddyfile/directives/encode.md b/src/docs/markdown/caddyfile/directives/encode.md index 4f55273..8d34f33 100644 --- a/src/docs/markdown/caddyfile/directives/encode.md +++ b/src/docs/markdown/caddyfile/directives/encode.md @@ -10,14 +10,15 @@ Encodes responses using the configured encoding(s). A typical use for encoding i ```caddy-d encode [] { + # encoding formats gzip [] zstd + minimum_length - prefer # response matcher single line syntax match [header []] | [status ] - # or response matcher block + # or response matcher block for multiple conditions match { status header [] @@ -25,12 +26,10 @@ encode [] { } ``` -- **<formats...>** is the list of encoding formats to enable. +- **<formats...>** is the list of encoding formats to enable. If multiple encodings are enabled, the encoding is chosen based the request's Accept-Encoding header; if the client has no strong preference (q-factor), then the first supported encoding is used. - **gzip** enables Gzip compression, optionally at the specified level. - **zstd** enables Zstandard compression. -- **minimum_length** the minimum number of bytes a response should have to be encoded. (Default is 512) -- **prefer** is the ordered list of enabled encoding formats to determine, which encoding to choose if the client has no strong preference (via q-factors in the `Accept-Encoding` header). - If **prefer** is not specified the first supported encoding from the `Accept-Encoding` header is used. +- **minimum_length** the minimum number of bytes a response should have to be encoded (default: 512). - **match** is a [Response matcher](#responsematcher). Only matching Responses are encoded. The default looks like this: ```caddy-d @@ -71,18 +70,8 @@ Enable Gzip compression: encode gzip ``` -Enable Zstandard and Gzip compression: +Enable Zstandard and Gzip compression (with Zstandard implicitly preferred, since it is first): ```caddy-d encode zstd gzip ``` - -Enable Zstandard and Gzip compression and prefer Zstandard over Gzip: - -```caddy-d -encode zstd gzip { - prefer zstd gzip -} -``` - -Without the **prefer** setting, a `--compressed` HTTP request via [curl](https://curl.se/) (meaning `Accept-Encoding: deflate, gzip, br, zstd` in curl >=7.72.0) would be served with Gzip encoding, because it is the first accepted encoding that both client and server support. With the **prefer** setting Zstandard encoding is served, because the client has no preference but the server (caddy) has. diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index 52fcf64..191b09b 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -25,7 +25,7 @@ file_server [] [browse] { - **root** sets the path to the site root for just this file server instance, overriding any other. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this directive. For other directives (like [`try_files`](/docs/caddyfile/directives/try_files) or [`templates`](/docs/caddyfile/directives/templates)) to know the same site root, use the [`root`](/docs/caddyfile/directives/root) directive, not this subdirective. - **hide** is a list of files or folders to hide; if requested, the file server will pretend they do not exist. Accepts placeholders and glob patterns. Note that these are _file system_ paths, NOT request paths. In other words, relative paths use the current working directory as a base, NOT the site root; and all paths are transformed to their absolute form before comparisons (if possible). Specifying a file name or pattern without a path separator will hide all files with a matching name regardless of its location; otherwise, a path prefix match will be attempted, and then a globular match. Since this is a Caddyfile config, the active configuration file(s) will be added by default. - **index** is a list of filenames to look for as index files. Default: `index.html index.txt` -- **** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code ![external link](/resources/images/external-link.svg)](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browsetpl.go). +- **** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code ![external link](/resources/images/external-link.svg)](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browsetpl.go). Browse templates can use actions from [the standard templates module](/docs/modules/http.handlers.templates#docs) as well. - **precompressed** is the list of encoding formats to search for precompressed sidecar files. - **<formats...>** is the ordered list of encoding formats to search for precompressed sidecar files. Supported formats are `gzip`, `zstd` and `br`. - **status** is an optional status code override to be used when writing the response. Particularly useful when responding to a request with a custom error page. Can be a 3-digit status code, For example: `404`. Placeholders are supported. By default, the written status code will typically be `200`, or `206` for partial content. diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index b20bb97..9f986bc 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -65,6 +65,15 @@ reverse_proxy [] [] { transport { ... } + + # optionally intercept responses from upstream + @name { + status + header [] + } + handle_response [] [status_code] { + + } } ``` @@ -246,6 +255,15 @@ transport fastcgi { - **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout. +### Intercepting responses + +The reverse proxy can be configured to intercept responses from the backend. To facilitate this, response matchers can be defined (similar to the syntax for request matchers) and the first matching `handle_response` route will be invoked. When this happens, the response from the backend is not written to the client, and the configured `handle_response` route will be executed instead, and it is up to that route to write a response. + +- **@name** is the name of a response matcher. As long as each response matcher has a unique name, multiple matchers can be defined. A response can be matched on the status code and presence or value of a response header. +- **handle_response** defines the route to execute when matched by the given matcher (or, if a matcher is omitted, all responses). The first matching block will be applied. Inside a `handle_response` block, any other [directives](/docs/caddyfile/directives) can be used. + + + ## Examples @@ -302,3 +320,16 @@ handle_path /old-prefix/* { reverse_proxy localhost:9000 } ``` + +X-Accel-Redirect support: + +```caddy-d +reverse_proxy localhost:8080 { + @accel header X-Accel-Redirect * + handle_response @accel { + root * /path/to/private/files + rewrite {http.response.header.X-Accel-Redirect} + file_server + } +} +``` diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index f873e84..22a86fd 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -41,7 +41,7 @@ tls [internal|] | [ ] { - **<email>** is the email address to use for the ACME account managing the site's certificates. - **<cert_file>** and **<key_file>** are the paths to the certificate and private key PEM files. Specifying just one is invalid. - **protocols** specifies the minimum and maximum protocol versions. Default min: `tls1.2`. Default max: `tls1.3` -- **ciphers** specifies the list of cipher suite names in descending preference order. Note that cipher suites are not customizable with TLS 1.3. The supported names are (in no particular order here): +- **ciphers** specifies the list of cipher suite names in descending preference order. It is recommended to not change these unless you know what you're doing. Note that cipher suites are not customizable for TLS 1.3; and not all TLS 1.2 ciphers are enabled by default. The supported names are (in no particular order here): - TLS_RSA_WITH_3DES_EDE_CBC_SHA - TLS_RSA_WITH_AES_128_CBC_SHA - TLS_RSA_WITH_AES_256_CBC_SHA @@ -61,7 +61,7 @@ tls [internal|] | [ ] { - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 -- **curves** specifies the list of EC curves to support. Supported values are: +- **curves** specifies the list of EC curves to support. It is recommended to not change these. Supported values are: - x25519 - secp256r1 - secp384r1 @@ -73,7 +73,7 @@ tls [internal|] | [ ] { - **dns** enables the [DNS challenge](/docs/automatic-https#dns-challenge) using the specified provider plugin, which must be plugged in from one of the [caddy-dns](https://github.com/caddy-dns) repositories. Each provider plugin may have their own syntax following their name; refer to their docs for details. Maintaining support for each DNS provider is a community effort. [Learn how to enable the DNS challenge for your provider at our wiki.](https://caddy.community/t/how-to-use-dns-provider-modules-in-caddy-2/8148) - **resolvers** customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones. If set here, the resolvers will propagate to all configured certificate issuers. - **eab** configures ACME external account binding (EAB) for this site, using the key ID and MAC key provided by your CA. -- **on_demand** enables [on-demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es). +- **on_demand** enables [on-demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es). **Security warning:** Doing so in production is insecure unless you also configure the [`on_demand_tls` global option](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to mitigate abuse. - **client_auth** enables and configures TLS client authentication: - **mode** is the mode for authenticating the client. Allowed values are: diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 4288c58..fb19f84 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -40,9 +40,10 @@ Possible options are: include exclude } + grace_period # TLS Options - auto_https off|disable_redirects + auto_https off|disable_redirects|ignore_loaded_certs email default_sni local_certs @@ -119,10 +120,14 @@ Customizes the named logger. The name can be passed to indicate a specific logge - **exclude** identifies the loggers that are excluded from this log configuration. See the [JSON documentation](/docs/json/logging/logs/exclude/) for more information. +##### `grace_period` +Defines the grace period for shutting down HTTP servers during config reloads. 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. + + ## TLS Options ##### `auto_https` -Configure automatic HTTPS. It can either disable it entirely (`off`) or disable only HTTP-to-HTTPS redirects (`disable_redirects`). See the [Automatic HTTPS](/docs/automatic-https) page for more details. +Configure automatic HTTPS. It can be disabled entirely (`off`), disable only HTTP-to-HTTPS redirects (`disable_redirects`), or be configured to automate certificates even for names which appear on manually-loaded certificates (`ignore_loaded_certs`). See the [Automatic HTTPS](/docs/automatic-https) page for more details. ##### `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. diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index c100a6d..d2aa7c6 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -123,7 +123,7 @@ To adapt a Caddyfile to JSON that you can easily read and tweak manually: 
caddy build-info
-Prints information provided by Go about the build (main module path, package versions, replacements). +Prints information provided by Go about the build (main module path, package versions, module replacements). @@ -297,6 +297,7 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode. 
caddy start
 	[--config <path>]
 	[--adapter <name>]
+	[--envfile <file>]
 	[--pidfile <file>]
 	[--watch]
diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md index a4d8b18..77a8bdb 100644 --- a/src/docs/markdown/install.md +++ b/src/docs/markdown/install.md @@ -200,3 +200,12 @@ _Note: This is a community-maintained installation method._ 
ansible-galaxy install nvjacobo.caddy
[**View the Ansible role repository**](https://github.com/nvjacobo/caddy) + + +## Scoop + +_Note: This is a community-maintained installation method._ + +
scoop install caddy
+ +[**View the Scoop manifest**](https://github.com/ScoopInstaller/Main/blob/master/bucket/caddy.json)