mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-22 04:56:17 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Update for v2.3; refactor install information

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

100
src/docs/markdown/automatic-https.md
View file

@ -6,50 +6,66 @@ title: "Automatic HTTPS"
**Caddy is the first and only web server to use HTTPS automatically _and by default_.** **Caddy is the first and only web server to use HTTPS automatically _and by default_.**
Automatic HTTPS provisions TLS certificates for all your sites and keeps them renewed. It also redirects HTTP to HTTPS for you! Caddy uses safe and modern defaults -- no downtime or extra configuration required. Automatic HTTPS provisions TLS certificates for all your sites and keeps them renewed. It also redirects HTTP to HTTPS for you! Caddy uses safe and modern defaults -- no downtime, extra configuration, or separate tooling is required.
<aside class="tip">Caddy innovated automatic HTTPS technology; we've been doing this since the first day it was possible in 2015. Caddy's HTTPS automation logic is the most mature and robust in the world.</aside> <aside class="tip">Caddy innovated automatic HTTPS technology; we've been doing this since the first day it was feasible in 2015. Caddy's HTTPS automation logic is the most mature and robust in the world.</aside>
Here's a 28-second video showing how it works: Here's a 28-second video showing how it works:
<iframe width="100%" height="480" src="https://www.youtube-nocookie.com/embed/nk4EWHvvZtI?rel=0" frameborder="0" allowfullscreen=""></iframe> <iframe width="100%" height="480" src="https://www.youtube-nocookie.com/embed/nk4EWHvvZtI?rel=0" frameborder="0" allowfullscreen=""></iframe>
**Menu:**
- [Overview](#overview)
- [Activation](#activation)
- [Effects](#effects)
- [Hostname requirements](#hostname-requirements)
- [Local HTTPS](#local-https)
- [Testing](#testing)
- [ACME Challenges](#acme-challenges)
- [On-Demand TLS](#on-demand-tls)
- [Errors](#errors)
- [Storage](#storage)
- [Wildcard certificates](#wildcard-certificates)
## Overview ## Overview
**Caddy serves all sites over HTTPS by default.** **By default, Caddy serves all sites over HTTPS.**
- Caddy serves IP addresses and local/internal hostnames over HTTPS with locally-trusted certificates. Examples: `localhost`, `127.0.0.1`. - Caddy serves IP addresses and local/internal hostnames over HTTPS using self-signed certificates that are automatically trusted locally (if permitted).
- Caddy serves public DNS names over HTTPS with certificates from [Let's Encrypt](https://letsencrypt.org). Examples: `example.com`, `sub.example.com`, `*.example.com`. - Examples: `localhost`, `127.0.0.1`
- Caddy serves public DNS names over HTTPS using certificates from a public ACME CA such as [Let's Encrypt](https://letsencrypt.org) or [ZeroSSL](https://zerossl.com).
- Examples: `example.com`, `sub.example.com`, `*.example.com`
Caddy keeps all certificates renewed, and redirects HTTP (default port 80) to HTTPS (default port 443) automatically. Caddy keeps all managed certificates renewed and redirects HTTP (default port 80) to HTTPS (default port 443) automatically.
**For local HTTPS:** **For local HTTPS:**
- Caddy may prompt for a password to install its root certificate into your trust store. This happens only once per root. - Caddy may prompt for a password to install its unique root certificate into your trust store. This happens only once per root; and you can remove it at any time.
- Any client accessing the site without trusting the root cert will show security errors. - Any client accessing the site without trusting Caddy's root will show security errors.
**For public domain names:** **For public domain names:**
<aside class="tip">These are common requirements for any basic production website, not just Caddy. The main difference is to set your DNS records properly <b>before</b> running Caddy.</aside> <aside class="tip">These are common requirements for any basic production website, not just Caddy. The main difference is to set your DNS records properly <b>before</b> running Caddy so it can provision certificates.</aside>
- If your domain's A/AAAA records point to your server, - If your domain's A/AAAA records point to your server,
- ports 80 and 443 are open externally, - ports 80 and 443 are open externally,
- Caddy can bind to those ports (_or_ those ports are forwarded to Caddy), - Caddy can bind to those ports (_or_ those ports are forwarded to Caddy),
- your `$HOME` folder is writeable and persistent, - your [data directory](/docs/conventions#data-directory) is writeable and persistent,
- and your domain name appears somewhere relevant in the config, - and your domain name appears somewhere relevant in the config,
then sites will be served over HTTPS automatically and without problems. You won't have to know or do anything else about it. It should "just work"! then sites will be served over HTTPS automatically. You won't have to do anything else about it. It just works!
If you are still testing your setup, however, please read on or you risk being rate limited by your CA. The rest of this page goes over the details for advanced use cases and troubleshooting purposes. Because HTTPS utilizes a shared, public infrastructure, you as the server admin should understand the rest of the information on this page so that you can avoid unnecessary problems, troubleshoot them when they occur, and properly configure advanced deployments.
## Activation ## Activation
Caddy implicitly activates automatic HTTPS when it knows a domain name (i.e. hostname) it is serving. Depending on how you run or configure Caddy, there are various ways to tell Caddy which domain names to use: Caddy implicitly activates automatic HTTPS when it knows a domain name (i.e. hostname) or IP address it is serving. There are various ways to tell Caddy your domain/IP, depending on how you run or configure Caddy:
- A [site address](/docs/caddyfile/concepts#addresses) in the [Caddyfile](/docs/caddyfile) - A [site address](/docs/caddyfile/concepts#addresses) in the [Caddyfile](/docs/caddyfile)
- A [host matcher](/docs/json/apps/http/servers/routes/match/host/) in a [route](/docs/modules/http#servers/routes) - A [host matcher](/docs/json/apps/http/servers/routes/match/host/) in a [route](/docs/modules/http#servers/routes)
@ -74,12 +90,12 @@ When automatic HTTPS is activated, the following occurs:
Automatic HTTPS never overrides explicit configuration. Automatic HTTPS never overrides explicit configuration.
You can [customize or disable automatic HTTPS](/docs/json/apps/http/servers/automatic_https/) if necessary. You can [customize or disable automatic HTTPS](/docs/json/apps/http/servers/automatic_https/) if necessary; for example, you can skip certain domain names or disable redirects.
## Hostname requirements ## Hostname requirements
All hostnames (domain names and IP addresses) qualify for fully-managed certificates if they: All hostnames (domain names) qualify for fully-managed certificates if they:
- are non-empty - are non-empty
- consist only of alphanumerics, hyphens, dots, and wildcard (`*`) - consist only of alphanumerics, hyphens, dots, and wildcard (`*`)
@ -87,12 +103,11 @@ All hostnames (domain names and IP addresses) qualify for fully-managed certific
In addition, hostnames qualify for publicly-trusted certificates if they: In addition, hostnames qualify for publicly-trusted certificates if they:
- are not localhost - are not localhost (including `.localhost` and `.local` TLDs)
- are not an IP address - are not an IP address
- have only a single wildcard `*` as the left-most label - have only a single wildcard `*` as the left-most label
## Local HTTPS ## Local HTTPS
To serve non-public sites over HTTPS, Caddy generates its own certificate authority (CA) and uses it to sign certificates. The trust chain consists of a root and intermediate certificate. Leaf certificates are signed by the intermediate. To serve non-public sites over HTTPS, Caddy generates its own certificate authority (CA) and uses it to sign certificates. The trust chain consists of a root and intermediate certificate. Leaf certificates are signed by the intermediate.
@ -121,25 +136,21 @@ An intermediate certificate and key will also be generated, which will be used f
Unlike the root certificate, intermediate certificates have a much shorter lifetime and will automatically be renewed as needed. Unlike the root certificate, intermediate certificates have a much shorter lifetime and will automatically be renewed as needed.
## Testing ## Testing
To test or experiment with your Caddy configuration, make sure you [change the ACME endpoint](/docs/modules/tls.issuance.acme#ca) to a staging or development URL, otherwise you are likely to hit rate limits which can block your access to HTTPS for up to a week, depending on which rate limit you hit. To test or experiment with your Caddy configuration, make sure you [change the ACME endpoint](/docs/modules/tls.issuance.acme#ca) to a staging or development URL, otherwise you are likely to hit rate limits which can block your access to HTTPS for up to a week, depending on which rate limit you hit.
Caddy's default CA is [Let's Encrypt](https://letsencrypt.org/), which has a [staging endpoint](https://letsencrypt.org/docs/staging-environment/) that is not subject to the same [rate limits](https://letsencrypt.org/docs/rate-limits/): One of Caddy's default CAs is [Let's Encrypt](https://letsencrypt.org/), which has a [staging endpoint](https://letsencrypt.org/docs/staging-environment/) that is not subject to the same [rate limits](https://letsencrypt.org/docs/rate-limits/):
``` ```
https://acme-staging-v02.api.letsencrypt.org/directory https://acme-staging-v02.api.letsencrypt.org/directory
``` ```
## ACME challenges ## ACME challenges
Obtaining a publicly-trusted TLS certificate requires validation from a publicly-trusted, third-party authority. These days, this validation process is automated with the [ACME protocol](https://tools.ietf.org/html/rfc8555), and can be performed one of three ways ("challenge types"), described below. Obtaining a publicly-trusted TLS certificate requires validation from a publicly-trusted, third-party authority. These days, this validation process is automated with the [ACME protocol](https://tools.ietf.org/html/rfc8555), and can be performed one of three ways ("challenge types"), described below.
The first two challenge types are enabled by default. If multiple challenges are enabled, Caddy chooses one at random to avoid accidental dependence on a particular challenge. The first two challenge types are enabled by default. If multiple challenges are enabled, Caddy chooses one at random to avoid accidental dependence on a particular challenge. Over time, it learns which challenge type is most successful and will begin to prefer it first, but will fall back to other available challenge types if necessary.
### HTTP challenge ### HTTP challenge
@ -171,16 +182,21 @@ DNS provider support is a community effort. [Learn how to enable the DNS challen
## On-Demand TLS ## On-Demand TLS
Caddy pioneered a new technology we call On-Demand TLS, which obtains the certificate for a name during the first TLS handshake that requires it, rather than at config load. You can enable it using the [on_demand](/docs/json/apps/tls/automation/on_demand/) property in your TLS automation config, or the [on_demand Caddyfile subdirective](/docs/caddyfile/directives/tls#syntax). Caddy pioneered a new technology we call **On-Demand TLS**. Many businesses rely on this feature to scale their TLS deployments at lower cost and without operational headaches when serving tens of thousands of sites.
This feature can be useful if you do not know all the domain names up front, or if domain names you know of may not be properly configured right away (e.g. DNS records not yet set correctly). Certificates managed on-demand will be obtained and renewed in the foreground of TLS handshakes that require it. This process slows down only the initial TLS handshake; all others will not be affected. This unique feature obtains the certificate for a name during the first TLS handshake that requires it, rather than at config load. This is useful if:
To prevent abuse, you should specify rate limits and/or an endpoint that Caddy can query to ask if a certificate is allowed to be obtained for a hostname. Essentially, you still need a way to provide a whitelist, but this can be managed dynamically using your own scripts or programs if you'd rather keep Caddy's config more static. - you do not know all the domain names up front,
- domain names might not be properly configured right away (e.g. DNS records not yet set),
- or you are not in control of the domain names (e.g. they are customer domains).
When on-demand TLS is enabled, a TLS handshake may trigger maintenance for the relevant certificate. If no existing certificate is available, this process slows down only the initial TLS handshake while a certificate is obtained in the foreground; all other handshakes will not be affected (except those waiting on the same certificate). If an existing certificate can be used, the handshake will complete immediately, and maintenance (i.e. renewal) will happen in the background.
You can enable it using the [on_demand](/docs/json/apps/tls/automation/on_demand/) property in your TLS automation config, or the [on_demand Caddyfile subdirective](/docs/caddyfile/directives/tls#syntax). Note that enabling on-demand TLS is separate from configuring how it works. To prevent abuse, you should specify rate limits and/or an endpoint that Caddy can query to ask if a certificate is allowed to be obtained for a hostname.
**Future support:** This feature relies on the CA issuing certificates without delay. If instantaneous issuance becomes uncommon among ACME CAs, we may discontinue this feature in Caddy. **Future support:** This feature relies on the CA issuing certificates without delay. If instantaneous issuance becomes uncommon among ACME CAs, we may discontinue this feature in Caddy.
Due to its deferred nature and the possibility that some ACME challenges can take more than a few seconds (especially when using the DNS challenge), we typically recommend using On-Demand TLS only when there are specific technical or operational advantages to you; namely, if the DNS records for a domain are not in your control, and you do not know when they will be properly set and ready to get certificates. Due to its deferred nature and potential for abuse (if not mitigated through proper configuration), we recommend enabling on-demand TLS only when your actual use case is described above.
## Errors ## Errors
@ -192,31 +208,43 @@ Here's what happens if there's an error obtaining or renewing a certificate:
1. Caddy retries once after a brief pause just in case it was a fluke 1. Caddy retries once after a brief pause just in case it was a fluke
2. Caddy pauses briefly, then switches to the next enabled challenge type 2. Caddy pauses briefly, then switches to the next enabled challenge type
3. After all enabled challenge types have been tried, it backs off exponentially 3. After all enabled challenge types have been tried, [it tries the next configured issuer](#issuer-fallback)
- Let's Encrypt
- ZeroSSL
4. After all issuers have been tried, it backs off exponentially
- Maximum of 1 day between attempts - Maximum of 1 day between attempts
- For up to 30 days - For up to 30 days
During retries with Let's Encrypt, Caddy switches to their [staging environment](https://letsencrypt.org/docs/staging-environment/) to avoid rate limit concerns. This isn't a perfect strategy, but in general it's helpful. During retries with Let's Encrypt, Caddy switches to their [staging environment](https://letsencrypt.org/docs/staging-environment/) to avoid rate limit concerns. This isn't a perfect strategy, but in general it's helpful.
ACME challenges take at least a few seconds, and internal rate limiting helps mitigate accidental abuse. Caddy uses internal rate limiting in addition to what you or the CA configure so that you can hand Caddy a platter with a million domain names and it will gradually -- but as fast as it can -- obtain certificates for all of them. ACME challenges take at least a few seconds, and internal rate limiting helps mitigate accidental abuse. Caddy uses internal rate limiting in addition to what you or the CA configure so that you can hand Caddy a platter with a million domain names and it will gradually -- but as fast as it can -- obtain certificates for all of them. Caddy's internal rate limit is currently 10 attempts per ACME account per minute.
Caddy's internal rate limit is currently 10 attempts per ACME account per minute. To avoid leaking resources, Caddy aborts in-flight tasks (including ACME transactions) when config is changed. While Caddy is capable of handling frequent config reloads, be mindful of operational considerations such as this, and consider batching config changes to reduce reloads and give Caddy a chance to actually finish obtaining certificates in the background.
### Issuer fallback
Caddy is the first (and so far only) server to support fully-redundant, automatic failover to other CAs in the event it cannot successfully get a certificate.
By default, Caddy enables two ACME-compatible CAs: [**Let's Encrypt**](https://letsencrypt.org) and [**ZeroSSL**](https://zerossl.com). If Caddy cannot get a certificate from Let's Encrypt, it will try with ZeroSSL; if both fail, it will backoff and retry again later. In your config, you can customize which issuers Caddy uses to obtain certificates, either universally or for specific names.
## Storage ## Storage
Caddy will store public certificates, private keys, and other assets in its [configured storage facility](/docs/json/storage/) (or the default one, if not configured -- see link for details). Caddy will store public certificates, private keys, and other assets in its [configured storage facility](/docs/json/storage/) (or the default one, if not configured -- see link for details).
**The main thing you need to know is that the `$HOME` folder must be writeable and persistent.** **The main thing you need to know using the default config is that the `$HOME` folder must be writeable and persistent.** To help you troubleshoot, Caddy prints its environment variables at startup if the `--environ` flag is specified.
Any Caddy instances that are configured to use the same storage will automatically share those resources and coordinate certificate management as a cluster. Any Caddy instances that are configured to use the same storage will automatically share those resources and coordinate certificate management as a cluster.
Before attempting any ACME transactions, Caddy will test the configured storage to ensure it is writeable and has sufficient capacity. This helps reduce unnecessary rate limit contention. Before attempting any ACME transactions, Caddy will test the configured storage to ensure it is writeable and has sufficient capacity. This helps reduce unnecessary lock contention.
## Wildcard certificates ## Wildcard certificates
Caddy can obtain and manage wildcard certificates when it is configured to serve a site with a qualifying wildcard name. A site name qualifies for a wildcard if only its left-most domain label is a wildcard. For example, `*.example.com` qualifies, but these do not: `sub.*.example.com`, `foo*.example.com`, `*bar.example.com`, and `*.*.example.com`. Caddy can obtain and manage wildcard certificates when it is configured to serve a site with a qualifying wildcard name. A site name qualifies for a wildcard if only its left-most domain label is a wildcard. For example, `*.example.com` qualifies, but these do not: `sub.*.example.com`, `foo*.example.com`, `*bar.example.com`, and `*.*.example.com`.
To get a wildcard from Let's Encrypt, you simply need to enable the [DNS challenge](#dns-challenge) and use a wildcard domain in your config. We recommend using wildcards only when you have so many subdomains that you would encounter CA rate limits trying to obtain certificates for them all. If using the Caddyfile, Caddy takes site names literally with regards to the certificate subject names. In other words, a site defined as `sub.example.com` will cause Caddy to manage a certificate for `sub.example.com`, and a site defined as `*.example.com` will cause Caddy to manage a wildcard certificate for `*.example.com`. If you need different behavior, the [JSON config](/docs/json/) gives you precise control over certificate subjects and site names ("host matchers").
Wildcard certificates represent a wide degree of authority and should only be used when you have so many subdomains that managing individual certificates for them would strain the PKI or cause you to hit CA-enforced rate limits.
**Note:** [Let's Encrypt requires](https://letsencrypt.org/docs/challenge-types/) the [DNS challenge](#dns-challenge) to obtain wildcard certificates.

6
src/docs/markdown/build.md
View file

@ -20,7 +20,7 @@ Build:
<span class="bash">go build</span></code></pre> <span class="bash">go build</span></code></pre>
<aside class="tip"> <aside class="tip">
Due to <a href="https://github.com/golang/go/issues/29228">a bug in Go</a>, these basic steps do not embed version information. If you want the version (<code>caddy version</code>), you need to compile Caddy as a dependency rather than as the main module. Instructions for this are in Caddy's <a href="https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go">main.go</a> file. Or, you can use <b>xcaddy</b> which automates this. Due to <a href="https://github.com/golang/go/issues/29228">a bug in Go</a>, these basic steps do not embed version information. If you want the version (<code>caddy version</code>), you need to compile Caddy as a dependency rather than as the main module. Instructions for this are in Caddy's <a href="https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go">main.go</a> file. Or, you can use <a href="#xcaddy"><code>xcaddy</code></a> which automates this.
</aside> </aside>
## xcaddy ## xcaddy
@ -30,7 +30,7 @@ The [`xcaddy` command](https://github.com/caddyserver/xcaddy) is the easiest way
Requirements: Requirements:
- Go installed (see above) - Go installed (see above)
- Make sure [xcaddy](https://github.com/caddyserver/xcaddy/releases) is in your PATH - Make sure [`xcaddy`](https://github.com/caddyserver/xcaddy/releases) is in your PATH
You do **not** need to download the Caddy source code (it will do that for you). You do **not** need to download the Caddy source code (it will do that for you).
@ -44,7 +44,7 @@ To build with plugins, use `--with`:
--with github.com/caddyserver/nginx-adapter --with github.com/caddyserver/nginx-adapter
--with github.com/caddyserver/ntlm-transport@v0.1.1</code></pre> --with github.com/caddyserver/ntlm-transport@v0.1.1</code></pre>
As you can see, you can customize the versions of plugins with `@` syntax. Versions can be a tag name or commit SHA. As you can see, you can customize the versions of plugins with `@` syntax. Versions can be a tag name, commit SHA, or branch.
Cross-platform compilation with `xcaddy` works the same as with the `go` command (see below). Cross-platform compilation with `xcaddy` works the same as with the `go` command (see below).

6
src/docs/markdown/caddyfile/directives/tls.md
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. - **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;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` - **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): - **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 - TLS_RSA_WITH_3DES_EDE_CBC_SHA
@ -67,7 +67,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
- secp521r1 - secp521r1
- **alpn** is the list of values to advertise in the ALPN extension of the TLS handshake. - **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. - **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. - **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) - **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. - **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. 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 ### Issuers

10
src/docs/markdown/caddyfile/matchers.md
View file

@ -237,12 +237,13 @@ file {
### header ### header
```caddy-d ```caddy-d
header <field> <value> header <field> [<value>]
``` ```
By request header fields. By request header fields.
- `<field>` is the name of the HTTP header field to check. - `<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. - `<value>` is the value the field must have to match.
- If prefixed with `*`, it performs a fast suffix match. - If prefixed with `*`, it performs a fast suffix match.
- If suffixed with `*`, it performs a fast prefix 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 ### header_regexp

2
src/docs/markdown/caddyfile/options.md
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. 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` ##### `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` ##### `acme_ca_root`
Specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store. Specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store.

4
src/docs/markdown/command-line.md
View file

@ -203,9 +203,9 @@ Prints CLI help text, optionally for a specific subcommand, then exits.
<pre><code class="cmd bash">caddy list-modules <pre><code class="cmd bash">caddy list-modules
[--versions]</code></pre> [--versions]</code></pre>
Prints the Caddy modules that are installed, optionally with version information from their associated Go modules, then exits. Prints the Caddy modules that are installed, optionally with package and/or version information from their associated Go modules, then exits.
NOTE: Due to [a bug in Go](https://github.com/golang/go/issues/29228), version information is only available if Caddy is built as a dependency and not as the main module. TODO: Link to docs that explain how to build Caddy with version info NOTE: Due to [a bug in Go](https://github.com/golang/go/issues/29228), version information is only available if Caddy is built as a dependency and not as the main module. Use [xcaddy](/docs/build#xcaddy) to make this easier.

103
src/docs/markdown/download.md
View file

@ -1,103 +0,0 @@
---
title: "Download Caddy"
---
# Download Caddy
All our [official distributions](https://github.com/caddyserver/dist) come with only the standard modules. If you need third-party plugins, [build from source with xcaddy](/docs/build#xcaddy).
## Static binaries
You can **[download Caddy from GitHub](https://github.com/caddyserver/caddy/releases)**, where new releases are immediately published, and place it in your PATH.
Using `curl`:
<pre><code class="cmd"><span class="bash">curl -OL "https://github.com/caddyserver/caddy/releases/latest/download/ASSET"</span></code></pre>
Using `wget`:
<pre><code class="cmd"><span class="bash">wget "https://github.com/caddyserver/caddy/releases/latest/download/ASSET"</span></code></pre>
Replace `ASSET` with the filename for your platform.
## Docker
<pre><code class="cmd bash">docker pull caddy</code></pre>
[**View on Docker Hub**](https://hub.docker.com/_/caddy)
## Debian, Ubuntu, Raspbian
<pre><code class="cmd"><span class="bash">echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \
| sudo tee -a /etc/apt/sources.list.d/caddy-fury.list</span>
<span class="bash">sudo apt update</span>
<span class="bash">sudo apt install caddy</span></code></pre>
Installing this package automatically starts and runs Caddy for you as a systemd service named `caddy` using the [caddy.service](https://github.com/caddyserver/dist/blob/master/init/caddy.service) unit file.
## Fedora, RedHat, CentOS
Fedora or RHEL/CentOS 8:
<pre><code class="cmd"><span class="bash">dnf install 'dnf-command(copr)'</span>
<span class="bash">dnf copr enable @caddy/caddy</span>
<span class="bash">dnf install caddy</span></code></pre>
RHEL/CentOS 7:
<pre><code class="cmd"><span class="bash">yum install yum-plugin-copr</span>
<span class="bash">yum copr enable @caddy/caddy</span>
<span class="bash">yum install caddy</span></code></pre>
[**View the Caddy COPR**](https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/)
## Linux & Raspberry Pi
You can use Webi to automate the processes of downloading the latest release and putting it in your PATH, without requiring admin permissions.
<pre><code class="cmd bash">curl -sS https://webinstall.dev/caddy | bash</code></pre>
If you'd like a simple way to launch Caddy as a system service and bind to privilege ports, see the Webi [Caddy Cheat Sheet](https://webinstall.dev/caddy).
To allow non-root users to bind to ports 80 and 443, use setcap.
<pre><code class="cmd bash">sudo setcap cap_net_bind_service=+ep $(readlink $(command -v caddy))</code></pre>
## DigitalOcean
[**Deploy a Caddy droplet on DigitalOcean**](https://marketplace.digitalocean.com/apps/caddy)
## macOS
**Homebrew**
<pre><code class="cmd bash">brew install caddy</code></pre>
[**View the Homebrew formula**](https://formulae.brew.sh/formula/caddy)
**Webi**
<pre><code class="cmd bash">curl -sS https://webinstall.dev/caddy | bash</code></pre>
[**View the Webi installer**](https://github.com/webinstall/webi-installers/tree/master/caddy)
## Windows 10 (Powershell)
<pre><code class="cmd pwsh">curl.exe -A MS https://webinstall.dev/caddy | powershell</code></pre>
You may need to adjust the Windows firewall rules to allow non-localhost incoming connections.
## Windows (Chocolatey)
<pre><code class="cmd pwsh">choco install caddy</code></pre>
[**View the Chocolatey package**](https://chocolatey.org/packages/caddy)

2
src/docs/markdown/getting-started.md
View file

@ -26,7 +26,7 @@ Welcome to Caddy! This tutorial will explore the basics of using Caddy and help
--- ---
**If you [installed Caddy](/docs/download) from a package manager, Caddy might already be running as a service. If so, please stop the service before doing this tutorial.** **If you [installed Caddy](/docs/install) from a package manager, Caddy might already be running as a service. If so, please stop the service before doing this tutorial.**
Let's start by running it: Let's start by running it:

105
src/docs/markdown/install.md
View file

@ -4,18 +4,80 @@ title: "Install"
# Install # Install
This page describes how to manually install Caddy as a service. This page describes various methods for installing Caddy on your system.
**Official:**
- [Static binaries](#static-binaries)
- [Debian, Ubuntu, Raspbian](#debian-ubuntu-raspbian)
- [Fedora, RedHat, CentOS](#fedora-redhat-centos)
- [Docker](#docker)
- [DigitalOcean](#digitalocean)
- [Linux service](#linux-service)
<aside class="tip"> <aside class="tip">
If you <a href="/docs/download">downloaded Caddy</a> using a package manager such as <code>apt</code> or <code>dnf</code>, then Caddy is already installed, and you should jump to <a href="/docs/getting-started">Getting Started</a>. Our <a href="https://github.com/caddyserver/dist">official packages</a> come only with the standard modules. If you need third-party plugins, <a href="/docs/build#xcaddy">build from source with <code>xcaddy</code></a> or use <a href="/download">our download page</a>.
</aside> </aside>
**Community-maintained:**
- [Homebrew](#homebrew)
- [Webi](#webi)
- [Chocolatey](#chocolatey)
## Static binaries
Simply downloading a Caddy binary does not <a href="#linux-service">install it as a service</a>, but can be useful in dev or when upgrading an existing installation.
- [**View releases on GitHub**](https://github.com/caddyserver/caddy/releases) (expand "Assets")
- [**Use our download page**](/download)
## Debian, Ubuntu, Raspbian
<pre><code class="cmd"><span class="bash">echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \
| sudo tee -a /etc/apt/sources.list.d/caddy-fury.list</span>
<span class="bash">sudo apt update</span>
<span class="bash">sudo apt install caddy</span></code></pre>
Installing this package automatically starts and runs Caddy for you as a systemd service named `caddy` using our official [caddy.service](https://github.com/caddyserver/dist/blob/master/init/caddy.service) unit file.
## Fedora, RedHat, CentOS
Fedora or RHEL/CentOS 8:
<pre><code class="cmd"><span class="bash">dnf install 'dnf-command(copr)'</span>
<span class="bash">dnf copr enable @caddy/caddy</span>
<span class="bash">dnf install caddy</span></code></pre>
RHEL/CentOS 7:
<pre><code class="cmd"><span class="bash">yum install yum-plugin-copr</span>
<span class="bash">yum copr enable @caddy/caddy</span>
<span class="bash">yum install caddy</span></code></pre>
[**View the Caddy COPR**](https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/)
## Docker
<pre><code class="cmd bash">docker pull caddy</code></pre>
[**View on Docker Hub**](https://hub.docker.com/_/caddy)
## DigitalOcean
[**Deploy a Caddy droplet on DigitalOcean**](https://marketplace.digitalocean.com/apps/caddy)
## Linux service ## Linux service
Requirements: Manually install Caddy as a service on Linux with these instructions.
- `caddy` binary that you [downloaded](/docs/download) or [built from source](/docs/build) **Requirements:**
- `caddy` binary that you [downloaded](/download) or [built from source](/docs/build)
- `systemctl --version` 232 or newer - `systemctl --version` 232 or newer
- `sudo` privileges - `sudo` privileges
@ -72,4 +134,37 @@ You can stop the service with:
Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead. Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
</aside> </aside>
Now that Caddy is installed, see our [Getting Started](/docs/getting-started) tutorial to learn how to use it!
## Homebrew
_Note: This is a community-maintained installation method._
<pre><code class="cmd bash">brew install caddy</code></pre>
[**View the Homebrew formula**](https://formulae.brew.sh/formula/caddy)
## Webi
_Note: This is a community-maintained installation method._
Linux and macOS:
<pre><code class="cmd bash">curl -sS https://webinstall.dev/caddy | bash</code></pre>
Windows:
<pre><code class="cmd">curl.exe -A MS https://webinstall.dev/caddy | powershell</code></pre>
You may need to adjust the Windows firewall rules to allow non-localhost incoming connections.
[**View on Webi**](https://webinstall.dev/caddy)
## Chocolatey
_Note: This is a community-maintained installation method._
<pre><code class="cmd">choco install caddy</code></pre>
[**View the Chocolatey package**](https://chocolatey.org/packages/caddy)

2
src/docs/markdown/v2-upgrade.md
View file

@ -71,7 +71,7 @@ Caddy's default port is no longer `:2015`. Caddy 2's default port is `:443` or,
Caddy 2's default protocol is [_always_ HTTPS if a hostname or IP is known](/docs/automatic-https#overview). This is different from Caddy 1, where only public-looking domains used HTTPS by default. Now, _every_ site uses HTTPS (unless you disable it by explicitly specifying port `:80` or `http://`). Caddy 2's default protocol is [_always_ HTTPS if a hostname or IP is known](/docs/automatic-https#overview). This is different from Caddy 1, where only public-looking domains used HTTPS by default. Now, _every_ site uses HTTPS (unless you disable it by explicitly specifying port `:80` or `http://`).
IP addresses and localhost domains will be issued certificates from a [locally-trusted, embedded CA](/docs/automatic-https#local-https). All other domains will use Let's Encrypt. (This is all configurable.) IP addresses and localhost domains will be issued certificates from a [locally-trusted, embedded CA](/docs/automatic-https#local-https). All other domains will use ZeroSSL or Let's Encrypt. (This is all configurable.)
The storage structure of certificates and ACME resources has changed. Caddy 2 will probably obtain new certificates for your sites; but if you have a lot of certificates you can migrate them manually if it does not do it for you. See issues [#2955](https://github.com/caddyserver/caddy/issues/2955) and [#3124](https://github.com/caddyserver/caddy/issues/3124) for details. The storage structure of certificates and ACME resources has changed. Caddy 2 will probably obtain new certificates for your sites; but if you have a lot of certificates you can migrate them manually if it does not do it for you. See issues [#2955](https://github.com/caddyserver/caddy/issues/2955) and [#3124](https://github.com/caddyserver/caddy/issues/3124) for details.

3
src/includes/docs-nav.html
View file

@ -4,9 +4,8 @@
<li><a href="https://caddy.community/c/wiki/13">Wiki <img src="/resources/images/external-link.svg"></a></li> <li><a href="https://caddy.community/c/wiki/13">Wiki <img src="/resources/images/external-link.svg"></a></li>
<li class="heading">Get Caddy</li> <li class="heading">Get Caddy</li>
<li><a href="/docs/download">Download</a></li>
<li><a href="/docs/build">Build from source</a></li>
<li><a href="/docs/install">Install</a></li> <li><a href="/docs/install">Install</a></li>
<li><a href="/docs/build">Build from source</a></li>
<li class="heading">Tutorials</li> <li class="heading">Tutorials</li>
<li><a href="/docs/getting-started">Getting Started</a></li> <li><a href="/docs/getting-started">Getting Started</a></li>