diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index e599b1a..832a10c 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -141,15 +141,18 @@ Quotes can be escaped if you need to use quotes in quoted tokens, too: directive "\"abc def\"" ``` -Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. - -You can also use a backtick ` to quote tokens: +Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. Multi-line tokens are possible: ```caddy-d -directive `"foo bar"` +directive "first line +second line" ``` -Backtick strings are convenient when tokens contain quote literals, e.g. JSON text. +You can also use a backtick ` to quote tokens; these are convenient when tokens themselves contain double quotes, e.g. JSON text: + +```caddy-d +directive `{"foo": "bar"}` +``` @@ -254,6 +257,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd | `{tls_client_certificate_pem}` | `{http.request.tls.client.certificate_pem}` | | `{tls_client_certificate_der_base64}` | `{http.request.tls.client.certificate_der_base64}` | | `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` | +| `{vars.*}` | `{http.vars.*}` | diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 296dfd4..aec36d7 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -66,6 +66,7 @@ Directive | Description **[tracing](/docs/caddyfile/directives/tracing)** | Integration with OpenTelemetry tracing **[try_files](/docs/caddyfile/directives/try_files)** | Rewrite that depends on file existence **[uri](/docs/caddyfile/directives/uri)** | Manipulate the URI +**[vars](/docs/caddyfile/directives/vars)** | Set arbitrary variables @@ -109,6 +110,7 @@ Many directives manipulate the HTTP handler chain. The order in which those dire tracing map +vars root header diff --git a/src/docs/markdown/caddyfile/directives/map.md b/src/docs/markdown/caddyfile/directives/map.md index 5587f3c..89f9f82 100644 --- a/src/docs/markdown/caddyfile/directives/map.md +++ b/src/docs/markdown/caddyfile/directives/map.md @@ -29,6 +29,8 @@ map [] { As a special case, the Caddyfile parser treats outputs that are a literal hyphen (`-`) as null/nil values. This is useful if you want to fall back to a default value for that particular output in the case of the given input, but want to use non-default values for other outputs. + The outputs will be type converted if possible; `true` and `false` will be converted to boolean types, and numeric values will be converted to integer or float accordingly. To avoid this conversion, you may wrap the output with [quotes](/docs/caddyfile/concepts#tokens-and-quotes) and they will stay strings. + The number of outputs for each mapping must not exceed the number of destinations; however, for convenience, there may be fewer outputs than destinations, and any missing outputs will be filled in implicitly. If a regular expression was used as the input, then the capture groups can be referenced with `${group}` where `group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on. diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index 680f94d..d44d700 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -130,6 +130,7 @@ Obtains certificates using the ACME protocol. trusted_roots dns [] propagation_timeout + propagation_delay resolvers preferred_chains [smallest] { root_common_name @@ -149,7 +150,8 @@ Obtains certificates using the ACME protocol. - **eab** specifies an External Account Binding which may be required with some ACME CAs. - **trusted_roots** is one or more root certificates (as PEM filenames) to trust when connecting to the ACME CA server. - **dns** configures the DNS challenge. -- **propagation_timeout** is a [duration value](/docs/conventions#durations) that sets how long to wait for DNS TXT records to propagate when using the DNS challenge. Default 2 minutes. +- **propagation_timeout** is a [duration value](/docs/conventions#durations) that sets the maximum time to wait for the DNS TXT records to appear when using the DNS challenge. Set to `-1` to disable propagation checks. Default 2 minutes. +- **propagation_delay** is a [duration value](/docs/conventions#durations) that sets how long to wait before starting DNS TXT records propagation checks when using the DNS challenge. Default 0 (no wait). - **resolvers** customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones. - **preferred_chains** specifies which certificate chains Caddy should prefer; useful if your CA provides multiple chains. Use one of the following options: - **smallest** will tell Caddy to prefer chains with the fewest amount of bytes. diff --git a/src/docs/markdown/caddyfile/directives/vars.md b/src/docs/markdown/caddyfile/directives/vars.md new file mode 100644 index 0000000..9568be5 --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/vars.md @@ -0,0 +1,53 @@ +--- +title: vars (Caddyfile directive) +--- + +# vars + +Sets one or more variables to a particular value, to be used later in the request handling chain. + +The primary way to access variables is with placeholders, which have the form `{vars.variable_name}`, or with the [`vars`](/docs/caddyfile/matchers#vars) and [`vars_regexp`](/docs/caddyfile/matchers#vars_regexp) request matchers. + +## Syntax + +```caddy-d +vars [] [ ] { + + ... +} +``` + +- **<name>** is the variable name to set. + +- **<value>** is the value of the variable. + + The value will be type converted if possible; `true` and `false` will be converted to boolean types, and numeric values will be converted to integer or float accordingly. To avoid this conversion, you may wrap the output with [quotes](/docs/caddyfile/concepts#tokens-and-quotes) and they will stay strings. + +## Examples + +To set a single variable, the value being conditional based on the request path, then responding with the value: + +```caddy-d +vars /foo* isFoo "yep" +vars isFoo "nope" + +respond {vars.isFoo} +``` + +To set multiple variables, each converted to the appropriate scalar type: + +```caddy-d +vars { + # boolean + abc true + + # integer + def 1 + + # float + ghi 2.3 + + # string + jkl "example" +} +``` diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index fb720ec..0d81bbd 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -179,7 +179,7 @@ This command disables the admin API, making it easier to run multiple instances ### `caddy fmt` -
caddy fmt [--overwrite] [<path>]
+
caddy fmt [--overwrite] [--diff] [<path>]
Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless `--overwrite` is used. @@ -187,6 +187,8 @@ Formats or prettifies a Caddyfile, then exits. The result is printed to stdout u `--overwrite` causes the result to be written to the input file instead of being printed to the terminal. If the input is not a regular file, this flag has no effect. +`--diff` causes the output to be compared against the input, and lines will be prefixed with `-` and `+` where they differ. Note that unchanges lines are prefixed with two spaces for alignment, and that this is not a valid patch format; it's just meant as a visual tool. + @@ -294,7 +296,7 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode. `--environ` prints out the environment before starting. This is the same as the `caddy environ` command, but does not exit after printing. -`--envfile` loads environment variables from the specified file. +`--envfile` loads environment variables from the specified file, in `KEY=VALUE` format. Comments starting with `#` are supported; keys may be prefixed with `export`; values may be double-quoted (double-quotes within can be escaped); multi-line values are supported. `--resume` uses the last loaded configuration that was autosaved, overriding the `--config` flag (if present). Using this flag guarantees config durability through machine reboots or process restarts. It is most useful in [API](/docs/api)-centric deployments.