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

@ -31,6 +31,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
ca_root <pem_file>
key_type ed25519|p256|p384|rsa2048|rsa4096
dns <provider_name> [<params...>]
dns_challenge_domain_override <domain>
resolvers <dns_servers...>
eab <key_id> <mac_key>
on_demand
@ -79,7 +80,8 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
- **ca** <span id="ca"/> changes the ACME CA endpoint. This is most often used to set [Let's Encrypt's staging endpoint](https://letsencrypt.org/docs/staging-environment/) when testing, or an internal ACME server. (To change this value for the whole Caddyfile, use the `acme_ca` [global option](/docs/caddyfile/options) instead.)
- **ca_root** <span id="ca_root"/> specifies a PEM file that contains a trusted root certificate for the ACME CA endpoint, if not in the system trust store.
- **key_type** <span id="key_type"/> is the type of key to use when generating CSRs. Only set this if you have a specific requirement.
- **dns** <span id="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)
- **dns** <span id="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)
- **dns_challenge_domain_override** <span id="dns_challenge_domain_override"/> overrides the domain to use for the DNS challenge. This is to delegate the challenge to a different domain, e.g. one whose DNS provider has a [`caddy-dns`](https://github.com/caddy-dns) plugin.
- **resolvers** <span id="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** <span id="eab"/> configures ACME external account binding (EAB) for this site, using the key ID and MAC key provided by your CA.
- **on_demand** <span id="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.
@ -177,12 +179,15 @@ Obtains certificates from an internal certificate authority.
```caddy
... internal {
ca <name>
ca <name>
lifetime <duration>
sign_with_root
}
```
- **ca** is the name of the internal CA to use. Default: `local`
- **ca** <span id="ca"/> is the name of the internal CA to use. Default: `local`. See the [PKI app global options](/docs/caddyfile/options#pki-options) to configure alternate CAs.
- **lifetime** <span id="lifetime"/> is a [duration value](/docs/conventions#durations) that sets the validity period for interally issued leaf certificates. Default: 12h. It is NOT recommended to not change this, unless absolutely necessary.
- **sign_with_root** <span id="sign_with_root"/> forces the root to be the issuer instead of the intermediate. This is NOT recommended and should only be used when devices/clients do not properly validate certificate chains (very uncommon).
## Examples
@ -207,6 +212,16 @@ tls internal {
}
```
Use custom options for the internal CA (cannot use the `tls internal` shortcut):
```caddy-d
tls {
issuer internal {
ca foo
}
}
```
Specify an email address for your ACME account (but if only one email is used for all sites, we recommend the `email` [global option](/docs/caddyfile/options) instead):
```caddy-d