Docs for upcoming v2.5.0 release (#216)

* docs: new `log` filters in Caddyfile

* docs: `renew_interval` global option

* docs: Update access log example

* docs: `log_credentials` global option

* docs: `vars`, `vars_regexp` matchers

* docs: `roll_uncompressed`, `roll_local_time`

* docs: `http_redirect` listener wrapper

* docs: `pki` app

* docs: `strict_sni_host` options

* docs: `default_bind` option

* docs: `method` directive

* docs: `tls internal` subdirectives

* Apply suggestions from code review

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>

* Matchers, options, file_server, reverse_proxy

* More clarifications / corrections

* Corrections from review

* Typo fix

* One more note about dynamic upstreams

* Tab -> space

* Update module namespaces

* Update some docs about logging

* `copy_response`, `copy_response_headers`, `replace_status`

* `dns_challenge_domain_override`

* `caddy trust`, API endpoints

* `trusted_proxies`

* Note about `pass_thru` being only useful inside `route`

* Improve logging docs to clarify the difference

* A bit of polish on patterns

* request_body: Clarify error behavior

* review

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>
This commit is contained in:
Francis Lavoie 2022-03-11 16:26:00 -05:00 committed by GitHub
parent c734cc3e64
commit a1ddadf798
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 575 additions and 157 deletions

View file

@ -51,6 +51,8 @@ $(function() {
- [protocol](#protocol)
- [query](#query)
- [remote_ip](#remote-ip)
- [vars](#vars)
- [vars_regexp](#vars-regexp)
## Syntax
@ -317,7 +319,7 @@ Match requests that do not have the `Foo` header field at all:
header_regexp [<name>] <field> <regexp>
```
Like `header`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_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.
Like [`header`](#header), but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_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.
The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax).
@ -457,7 +459,7 @@ Multiple `path` matchers will be OR'ed together.
path_regexp [<name>] <regexp>
```
Like `path`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_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.
Like [`path`](#path), but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_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.
The request path is URL-decoded, and cleaned (to collapse doubled-up slashes and directory traversal dots) before matching. For example `/foo*` will also match `//foo` and `/%2F/foo`.
@ -516,7 +518,7 @@ query sort=asc
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.
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.
Multiple `remote_ip` matchers will be OR'ed together.
@ -527,3 +529,47 @@ Match requests from private IPv4 addresses.
```caddy-d
remote_ip 192.168.0.0/16 172.16.0.0/12 10.0.0.0/8
```
---
### vars
```caddy-d
vars <variable> <values...>
```
By the value of a variable in the request context, or the value of a placeholder. Multiple values may be specified to match any of those possible values (OR'ed).
This matcher is most useful when paired with the [`map` directive](/docs/caddyfile/directives/map) which sets outputs, or with plugins which set some information in the request context.
#### Example:
Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for the values `3`, or `5`.
```caddy-d
vars {magic_number} 3 5
```
---
### vars_regexp
```caddy-d
vars_regexp [<name>] <variable> <regexp>
```
Like [`vars`](#vars), but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_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.
The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax).
There can only be one `vars_regexp` matcher per named matcher.
#### Example:
Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for a value starting with `4`, capturing the value in a capture group.
```caddy-d
vars_regexp magic {magic_number} ^(4.*)
```