From 655786d85e74ebdf168339f55955b52cfd1e7cb4 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Mon, 6 Jun 2022 14:36:50 -0400 Subject: [PATCH] docs: Some random polish (#241) * docs: Some random polish Just a bunch of little things that I think would help users from frequently asked forum questions. * Adjustments, fix `tls_server_name` docs * Update src/docs/markdown/caddyfile/concepts.md Co-authored-by: Matt Holt Co-authored-by: Matt Holt --- src/docs/markdown/caddyfile/concepts.md | 16 +++++++----- .../caddyfile/directives/reverse_proxy.md | 26 +++++++++---------- src/docs/markdown/caddyfile/options.md | 13 +++++++--- src/docs/markdown/caddyfile/patterns.md | 7 +++-- src/docs/markdown/conventions.md | 11 ++++++-- 5 files changed, 45 insertions(+), 28 deletions(-) diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index 76af7bb..f35092a 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -24,9 +24,9 @@ The Caddyfile's structure can be described visually: Key points: -- An optional **global options block** can be the very first thing in the file. -- Otherwise, the first line of the Caddyfile is **always** the address(es) of the site to serve. -- All directives and matchers **must** go in a site block. There is no global scope or inheritence across site blocks. +- An optional [**global options block**](#global-options) can be the very first thing in the file. +- 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 inheritence across site blocks. - If there is **only one site block**, its curly braces `{ }` are optional. A Caddyfile consists of at least one or more site blocks, which always starts with one or more [addresses](#addresses) for the site. Any directives appearing before the address will be confusing to the parser. @@ -145,7 +145,7 @@ Inside quoted tokens, all other characters are treated literally, including spac ```caddy-d directive "first line -second line" + second line" ``` You can also use a backtick ` to quote tokens; these are convenient when tokens themselves contain double quotes, e.g. JSON text: @@ -308,7 +308,8 @@ Comments start with `#` and proceed until the end of the line: directive # or go at the end ``` -The hash character `#` cannot appear in the middle of a token (i.e. it must be preceded by a space or appear at the beginning of a line). This allows the use of hashes within URIs or other values without requiring quoting. +The hash character `#` for a comment cannot appear in the middle of a token (i.e. it must be preceded by a space or appear at the beginning of a line). This allows the use of hashes within URIs or other values without requiring quoting. + ## Environment variables @@ -319,7 +320,7 @@ If your configuration relies on environment variables, you can use them in the C {$SITE_ADDRESS} ``` -Environment variables in this form are substituted before parsing begins, so they can expand to empty values, partial tokens, complete tokens, or even multiple tokens and lines. +Environment variables in this form are substituted before Caddyfile parsing begins, so they can expand to empty values, partial tokens, complete tokens, or even multiple tokens and lines. A default value can be specified for when the environment variable is not found, by using `:` as the delimiter between the variable name and the default value: @@ -327,7 +328,8 @@ A default value can be specified for when the environment variable is not found, {$DOMAIN:localhost} ``` -If you want to defer the substitution of an environment variable until runtime, you can use the [standard `{env.*}` placeholders](/docs/conventions#placeholders). +If you want to defer the substitution of an environment variable until runtime, you can use the [standard `{env.*}` placeholders](/docs/conventions#placeholders). Note that not all config parameters support these placeholders though, since module developers need to add a line of code to perform the replacement. If it doesn't seem to work, please file an issue to request support for it. + ## Global options diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index bc047b1..9af4083 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -213,13 +213,13 @@ Load balancing is used whenever more than one upstream is defined. - `random_choose ` - selects two or more upstreams randomly, then chooses one with least load (`n` is usually 2) - `first` - choose first available upstream, from the order they are defined in the config - `round_robin` - iterate each upstream in turn - - `least_conn` - choose upstream with fewest number of current requests - - `ip_hash` - map client IP to sticky upstream - - `uri_hash` - map URI to sticky upstream - - `header [field]` - map request header to sticky upstream. If the specified header is not present, a random upstream is selected. - - `cookie [ []]` - based on the given cookie (default name is `lb` if not specified), which value is hashed; optionally with a secret for HMAC-SHA256 + - `least_conn` - choose upstream with fewest number of current requests; if more than one host has the least number of requests, then one of the hosts is chosen at random + - `ip_hash` - map the client IP to sticky upstream + - `uri_hash` - map the request URI (path and query) to sticky upstream + - `header [field]` - map request header to sticky upstream; if the specified header is not present, a random upstream is selected + - `cookie [ []]` - based on the given cookie (default name is `lb` if not specified), the cookie value is hashed, optionally with a secret for HMAC-SHA256; on the first request from a client, a random upstream is selected -- **lb_try_duration** is a [duration value](/docs/conventions#durations) that defines how long to try selecting available backends for each request if the next available host is down. By default, this retry is disabled. Clients will wait for up to this long while the load balancer tries to find an available upstream host. +- **lb_try_duration** is a [duration value](/docs/conventions#durations) that defines how long to try selecting available backends for each request if the next available host is down. By default, this retry is disabled. Clients will wait for up to this long while the load balancer tries to find an available upstream host. A reasonable starting point might be `5s` since the HTTP transport's default dial timeout is `3s`, so that should allow for at least one retry if the first selected upstream cannot be reached; but feel free to experiment to find the right balance for your usecase. - **lb_try_interval** is a [duration value](/docs/conventions#durations) that defines how long to wait between selecting the next host from the pool. Default is `250ms`. Only relevant when a request to an upstream host fails. Be aware that setting this to 0 with a non-zero `lb_try_duration` can cause the CPU to spin if all backends are down and latency is very low. @@ -242,8 +242,8 @@ Active health checks perform health checking in the background on a timer: Passive health checks happen inline with actual proxied requests: -- **fail_duration** is a [duration value](/docs/conventions#durations) that defines how long to remember a failed request. A duration > 0 enables passive health checking. -- **max_fails** is the maximum number of failed requests within `fail_duration` that are needed before considering a backend to be down; must be >= 1; default is 1. +- **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. +- **max_fails** is the maximum number of failed requests within `fail_duration` that are needed before considering a backend to be down; must be >= `1`; default is `1`. - **unhealthy_status** counts a request as failed if the response comes back with one of these status codes. Can be a 3-digit status code or a status code class ending in `xx`, for example: `404` or `5xx`. - **unhealthy_latency** is a [duration value](/docs/conventions#durations) that counts a request as failed if it takes this long to get a response. - **unhealthy_request_count** is the permissible number of simultaneous requests to a backend before marking it as down. @@ -362,7 +362,7 @@ transport http { tls_insecure_skip_verify tls_timeout tls_trusted_ca_certs - tls_server_name + tls_server_name keepalive [off|] keepalive_interval keepalive_idle_conns @@ -381,12 +381,12 @@ transport http { - **response_header_timeout** is how long to wait for reading response headers from the upstream. Accepts [duration values](/docs/conventions#durations). Default: No timeout. - **expect_continue_timeout** is how long to wait for the upstreams's first response headers after fully writing the request headers if the request has the header `Expect: 100-continue`. Accepts [duration values](/docs/conventions#durations). Default: No timeout. - **resolvers** is a list of DNS resolvers to override system resolvers. -- **tls** uses HTTPS with the backend. This will be enabled automatically if you specify backends using the `https://` scheme or port `:443`. +- **tls** uses HTTPS with the backend. This will be enabled automatically if you specify backends using the `https://` scheme or port `:443`, or if any of the below `tls_*` options are configured. - **tls_client_auth** enables TLS client authentication one of two ways: (1) by specifying a domain name for which Caddy should obtain a certificate and keep it renewed, or (2) by specifying a certificate and key file to present for TLS client authentication with the backend. -- **tls_insecure_skip_verify** turns off security. _Do not use in production._ +- **tls_insecure_skip_verify** turns off TLS handshake verification, making the connection insecure and vulnerable to man-in-the-middle attacks. _Do not use in production._ - **tls_timeout** is a [duration value](/docs/conventions#durations) that specifies how long to wait for the TLS handshake to complete. Default: No timeout. - **tls_trusted_ca_certs** is a list of PEM files that specify CA public keys to trust when connecting to the backend. -- **tls_server_name** sets the ServerName (SNI) to put in the ClientHello; only needed if the remote server requires it. +- **tls_server_name** sets the server name used when verifying the certificate received in the TLS handshake. By default, this will use the upstream address' host part. You only need to override this if your upstream address does not match the certificate the upstream is likely to use. For example if the upstream address is an IP address, then you would need to configure this to the hostname being served by the upstream server. Currently, this does not support placeholders, so a static value must be used. - **keepalive** is either `off` or a [duration value](/docs/conventions#durations) that specifies how long to keep connections open (timeout). Default: `2m`. - **keepalive_interval** is a [duration value](/docs/conventions#durations) that specifies how often to probe for liveness. Default: `30s`. - **keepalive_idle_conns** defines the maximum number of connections to keep alive. Default: No limit. @@ -500,7 +500,7 @@ Configure some transport options: reverse_proxy localhost:8080 { transport http { dial_timeout 2s - tls_timeout 2s + response_header_timeout 30s } } ``` diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 8ba17bd..ef12414 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -14,10 +14,15 @@ $(function() { let url = '#' + item.innerText.replace(/_/g, "-"); $(item).html('' + text + ''); }); - $('pre.chroma .k:contains("servers")') + // Add links on comments to their respective sections + $('pre.chroma .c1') + .filter((k, item) => item.innerText.includes('#')) .map(function(k, item) { - let text = item.innerText.replace(//g,'>'); - $(item).html('' + text + ''); + let text = item.innerText; + let before = text.slice(0, text.indexOf('#')); + text = text.slice(text.indexOf('#')); + let url = '#' + text.replace(/#/g, '').trim().toLowerCase().replace(/ /g, "-"); + $(item).html(before + '' + text + ''); }); }); @@ -258,7 +263,7 @@ Configures the ACME DNS challenge provider to use for all ACME transactions. The ##### `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 `tls` subdirective](/docs/caddyfile/directives/tls#syntax)). Highly recommended if using 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 200 OK, Caddy will be authorized to obtain a certificate for that name. +- **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. - **interval** and **burst** allows `` certificate operations within `` interval. diff --git a/src/docs/markdown/caddyfile/patterns.md b/src/docs/markdown/caddyfile/patterns.md index 79bcd56..d904ea0 100644 --- a/src/docs/markdown/caddyfile/patterns.md +++ b/src/docs/markdown/caddyfile/patterns.md @@ -96,7 +96,7 @@ example.com { ``` -To remove it for **multiple domains** at once: +To remove it for **multiple domains** at once; this uses the `{labels.*}` placeholders which are the parts of the hostname, 0-indexed from the right (e.g. 0=com, 1=example-one, 2=www): ```caddy www.example-one.com, www.example-two.com { @@ -180,11 +180,12 @@ When a web page does its own routing, servers may receive lots of requests for p The main idea is to have the server "try files" to see if the requested file exists server-side, and if not, fall back to an index file where the client does the routing (usually with client-side JavaScript): `try_files {path} /index.html` -The most basic SPA config usually looks something like this: +A typical SPA config usually looks something like this: ```caddy example.com { root * /path/to/site + encode gzip try_files {path} /index.html file_server } @@ -194,6 +195,8 @@ If your SPA is coupled with an API or other server-side-only endpoints, you will ```caddy example.com { + encode gzip + handle /api/* { reverse_proxy backend:8000 } diff --git a/src/docs/markdown/conventions.md b/src/docs/markdown/conventions.md index 01a58fb..be6ccd4 100644 --- a/src/docs/markdown/conventions.md +++ b/src/docs/markdown/conventions.md @@ -15,7 +15,14 @@ When specifying a network address to dial or bind, Caddy accepts a string in the network/address ``` -The network part is optional, and is anything that [Go's `net` package](https://golang.org/pkg/net/) recognizes. The default network is `tcp`. If a network is specified, a single forward slash `/` must separate the network and address portions. +The network part is optional (defaulting to `tcp`), and is anything that [Go's `net.Dial` function](https://pkg.go.dev/net#Dial) recognizes. If a network is specified, a single forward slash `/` must separate the network and address portions. + +The network can be any of the following; ones suffixed with `4` or `6` are IPv4 or IPv6 only, respectively: + +- TCP: `tcp`, `tcp4`, `tcp6` +- UDP: `udp`, `udp4`, `udp6` +- IP: `ip`, `ip4`, `ip6` +- Unix: `unix`, `unixgram`, `unixpacket` The address part may be any of these forms: @@ -28,7 +35,7 @@ The host may be any hostname, resolvable domain name, or IP address. The port may be a single value (`:8080`) or an inclusive range (`:8080-8085`). A port range will be multiplied into singular addresses. Not all config fields accept port ranges. The special port `:0` means any available port. -A unix socket path is only acceptable when using a unix* network type. The forward slash that separates the network and address is not considered part of the path. +A unix socket path is only acceptable when using a `unix*` network type. The forward slash that separates the network and address is not considered part of the path. Valid examples: