docs: Update for v2.3; refactor install information

We now have only 1 download page, yay. Install docs are organized better. Less confusing.

Automatic HTTPS docs improved, and menu added.

Other minor updates to bring up to speed for v2.3.
This commit is contained in:
Matthew Holt 2020-12-30 07:37:15 -07:00
parent 9dd9309a9b
commit 4827cff659
No known key found for this signature in database
GPG key ID: 2A349DD577D586A5
11 changed files with 186 additions and 159 deletions

View file

@ -38,7 +38,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
- **internal** means to use Caddy's internal, locally-trusted CA to produce certificates for this site.
- **&lt;email&gt;** is the email address to use for the ACME account managing the site's certificates.
- **&lt;cert_file&gt;** and **&lt;key_file&gt;** are the paths to the certificate and private key PEM files. Specifying just one is invalid; specifying both will disable automatic HTTPS.
- **&lt;cert_file&gt;** and **&lt;key_file&gt;** 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):
- TLS_RSA_WITH_3DES_EDE_CBC_SHA
@ -67,7 +67,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
- secp521r1
- **alpn** is the list of values to advertise in the ALPN extension of the TLS handshake.
- **load** specifies a list of folders from which to load PEM files that are certificate+key bundles.
- **ca** changes the ACME CA endpoint. This is most often used to use [Let's Encrypt's staging endpoint](https://letsencrypt.org/docs/staging-environment/) or an internal ACME server. (To change this value for the whole Caddyfile, use the `acme_ca` [global option](/docs/caddyfile/options) instead.)
- **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** specifies a PEM file that contains a trusted root certificate for the ACME CA endpoint, if not in the system trust store.
- **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)
- **eab** configures ACME external account binding (EAB) for this site, using the key ID and MAC key provided by your CA.
@ -91,7 +91,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
Multiple `trusted_*` directives may be specified as a way to chain multiple CA or leaf certificates.
- **issuer** configures a custom certificate issuer, or a source from which to obtain certificates. Which issuer is used and the options that follow in this segment depend on the issuer modules that are available (see below for the standard issuers). Some of the other subdirectives such as `ca` and `dns` are actually shortcuts for configuring the `acme` issuer (and this subdirective was added later), so specifying this directive and some of the others is confusing and thus prohibited.
- **issuer** configures a custom certificate issuer, or a source from which to obtain certificates. Which issuer is used and the options that follow in this segment depend on the issuer modules that are available (see below for the standard issuers; plugins may add others). Some of the other subdirectives such as `ca` and `dns` are actually shortcuts for configuring the `acme` issuer (and this subdirective was added later), so specifying this directive and some of the others is confusing and thus prohibited. This subdirective can be specified multiple times to configure multiple, redundant issuers; if one fails to issue a cert, the next one will be tried.
### Issuers

View file

@ -237,12 +237,13 @@ file {
### header
```caddy-d
header <field> <value>
header <field> [<value>]
```
By request header fields.
- `<field>` is the name of the HTTP header field to check.
- If prefixed with `!`, the field must not exist to match (omit value arg).
- `<value>` is the value the field must have to match.
- If prefixed with `*`, it performs a fast suffix match.
- If suffixed with `*`, it performs a fast prefix match.
@ -267,6 +268,13 @@ Match requests with the `Foo` header containing `bar` OR `baz`.
}
```
Match requests that do not have the `Foo` header field at all:
```caddy-d
@not_foo {
header !Foo
}
```
---
### header_regexp

View file

@ -112,7 +112,7 @@ Sets a default TLS ServerName for when clients do not use SNI in their ClientHel
Causes all certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful in development environments.
##### `acme_ca`
Specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: Let's Encrypt's production endpoint.
Specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: ZeroSSL and Let's Encrypt's production endpoints.
##### `acme_ca_root`
Specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store.