Lots of minor adjustments

This commit is contained in:
Francis Lavoie 2023-08-20 04:16:11 -04:00
parent c6a6daf3f9
commit 43b3329375
No known key found for this signature in database
GPG key ID: 0F66EE1687682239
18 changed files with 146 additions and 284 deletions

View file

@ -278,6 +278,6 @@ One last thing that you will find most helpful: if you want to remark or note an
## Further reading
- [Common patterns](/docs/caddyfile/patterns)
- [Caddyfile concepts](/docs/caddyfile/concepts)
- [Directives](/docs/caddyfile/directives)
- [Common patterns](/docs/caddyfile/patterns)

View file

@ -9,11 +9,12 @@ The **Caddyfile** is a convenient Caddy configuration format for humans. It is m
It looks like this:
```caddy
example.com
root * /var/www/wordpress
php_fastcgi unix//run/php/php-version-fpm.sock
file_server
example.com {
root * /var/www/wordpress
encode gzip
php_fastcgi unix//run/php/php-version-fpm.sock
file_server
}
```
(That's a real, production-ready Caddyfile that serves WordPress with fully-managed HTTPS.)

View file

@ -10,14 +10,15 @@ This document will help you learn about the HTTP Caddyfile in detail.
- [Blocks](#blocks)
- [Directives](#directives)
- [Tokens and quotes](#tokens-and-quotes)
2. [Addresses](#addresses)
3. [Matchers](#matchers)
4. [Placeholders](#placeholders)
5. [Snippets](#snippets)
6. [Named Routes](#named-routes)
7. [Comments](#comments)
8. [Environment variables](#environment-variables)
9. [Global options](#global-options)
2. [Global options](#global-options)
3. [Addresses](#addresses)
4. [Matchers](#matchers)
5. [Placeholders](#placeholders)
6. [Snippets](#snippets)
7. [Named Routes](#named-routes)
8. [Comments](#comments)
9. [Environment variables](#environment-variables)
## Structure
@ -174,13 +175,30 @@ example.com {
}
```
The opening heredoc marker must start with `<<`, followed by any text (uppercase letters recommended). The closing heredoc marker must be the same text (in the above example, `HTML`).
The opening heredoc marker must start with `<<`, followed by any text (uppercase letters recommended). The closing heredoc marker must be the same text (in the above example, `HTML`). The opening marker can be escaped with `\<<` to prevent heredoc parsing, if needed.
The closing marker can be indented, which causes every line of text to have that much indentation stripped (inspired by [PHP](https://www.php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc)) which is nice for readability inside [blocks](#blocks) while giving great control of the whitespace in the token text. The trailing newline is also stripped, but can be retained by adding an extra blank line before the closing marker.
Additional tokens may follow the closing marker as arguments to the directive (such as in the example above, the status code `200`).
## Global options
A Caddyfile may optionally start with a special block that has no keys, called a [global options block](/docs/caddyfile/options):
```caddy
{
...
}
```
If present, it must be the very first block in the config.
It is used to set options that apply globally, or not to any one site in particular. Inside, only global options can be set; you cannot use regular site directives in them.
[Learn more](/docs/caddyfile/options) about the global options block.
## Addresses
@ -210,7 +228,9 @@ From the address, Caddy can potentially infer the scheme, host and port of your
If you specify a hostname, only requests with a matching `Host` header will be honored. In other words, if the site address is `localhost`, then Caddy will not match requests to `127.0.0.1`.
Wildcards (`*`) may be used, but only to represent precisely one label of the hostname. For example, `*.example.com` matches `foo.example.com` but not `foo.bar.example.com`, and `*` matches `localhost` but not `example.com`. To catch all hosts, omit the host portion of the address.
Wildcards (`*`) may be used, but only to represent precisely one label of the hostname. For example, `*.example.com` matches `foo.example.com` but not `foo.bar.example.com`, and `*` matches `localhost` but not `example.com`. See the [wildcard certificates pattern](/docs/caddyfile/patterns#wildcard-certificates) for a practical example.
To catch all hosts, omit the host portion of the address, for example, simply `https://`. This is useful when using [On-Demand TLS](/docs/automatic-https#on-demand-tls), when you don't know the domains ahead of time.
If multiple sites share the same definition, you can list all of them together; notice how the commas indicate the continuation of addresses:
@ -226,7 +246,7 @@ example.com,
www.example.com
```
An address must be unique; you cannot specify the same address more than once.
An address must be unique; you cannot specify the same address more than once. [Placeholders](#placeholders) **cannot** be used in addresses, but you may use Caddyfile-style [environment variables](#environment-variables) in them.
By default, sites bind on all network interfaces. If you wish to override this, use the [`bind` directive](/docs/caddyfile/directives/bind) or the [`default_bind` global option](/docs/caddyfile/options#default-bind) to do so.
@ -236,7 +256,7 @@ By default, sites bind on all network interfaces. If you wish to override this,
HTTP handler directives apply to all requests by default (unless otherwise documented).
[Request matchers](/docs/caddyfile/matchers) can be used to classify requests by a given criteria. This concept originates in the [underlying JSON](/docs/json/apps/http/servers/routes/match/) structure, and it's important to know how to use them in the Caddyfile. With matchers, you can specify exactly which requests a certain directive applies to.
[Request matchers](/docs/caddyfile/matchers) can be used to classify requests by a given criteria. With matchers, you can specify exactly which requests a certain directive applies to.
For directives that support matchers, the first argument after the directive is the **matcher token**. Here are some examples:
@ -389,20 +409,3 @@ A default value can be specified for when the environment variable is not found,
If you want to defer the substitution of an environment variable until runtime, you can use the [standard `{env.*}` placeholders](/docs/conventions#placeholders). Note that not all config parameters support these placeholders though, since module developers need to add a line of code to perform the replacement. If it doesn't seem to work, please file an issue to request support for it.
## Global options
A Caddyfile may optionally start with a special block that has no keys, called a [global options block](/docs/caddyfile/options):
```caddy
{
...
}
```
If present, it must be the very first block in the config.
It is used to set options that apply globally, or not to any one site in particular. Inside, only global options can be set; you cannot use regular site directives in them.
[Learn more](/docs/caddyfile/options) about the global options block.

View file

@ -24,9 +24,10 @@ Forcefully close a connection received for unknown domains when using a wildcard
respond "This is foo!" 200
}
# Unhandled domains fall through to here, but we don't want to accept their requests
handle {
# Unhandled domains fall through to here,
# but we don't want to accept their requests
abort
}
}
```
```

View file

@ -34,9 +34,13 @@ encode [<matcher>] <formats...> {
```
- **&lt;formats...&gt;** is the list of encoding formats to enable. If multiple encodings are enabled, the encoding is chosen based the request's Accept-Encoding header; if the client has no strong preference (q-factor), then the first supported encoding is used.
- **gzip** <span id="gzip"/> enables Gzip compression, optionally at the specified level.
- **zstd** <span id="zstd"/> enables Zstandard compression.
- **minimum_length** <span id="minimum_length"/> the minimum number of bytes a response should have to be encoded (default: 512).
- **match** <span id="match"/> is a [response matcher](#response-matcher). Only matching responses are encoded. The default looks like this:
```caddy-d

View file

@ -30,7 +30,7 @@ import <pattern> [<args...>]
- `{args[n:]}` where the arguments beginning with `n` are inserted
- `{args[n:m]}` where the arguments in the range between `n` and `m` are inserted
For the forms that insert many tokens, the placeholder _must_ be a [token](/docs/caddyfile/concepts#tokens-and-quotes) on its own, it cannot be part of another token. In other words, it must have spaces around it, and cannot be in quotes.
For the forms that insert many tokens, the placeholder **must** be a [token](/docs/caddyfile/concepts#tokens-and-quotes) on its own, it cannot be part of another token. In other words, it must have spaces around it, and cannot be in quotes.
Note that prior to v2.7.0, the syntax was `{args.N}` but this form was deprecated in favor of the more flexible syntax above.

View file

@ -152,15 +152,16 @@ By default, connections are made to the upstream over plaintext HTTP. When using
Additionally, you may need to override the `Host` header such that it matches the TLS SNI value, which is used by servers for routing and certificate selection. See the [HTTPS](#https) section below for more details.
- Using `h2c://` as the scheme will use the [`http` transport](#the-http-transport) with [HTTP versions](#versions) set to allow cleartext HTTP/2 connections.
- Using `http://` as the scheme is identical to having omitted the scheme, since HTTP is already the default. This syntax is included for symmetry with the other scheme shortcuts.
Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport.
When using the [network address](/docs/conventions#network-addresses) form, the network type is specified as a prefix to the upstream address. This cannot be combined with a URL scheme. As a special case, `unix+h2c/` is supported as a shortcut for the `unix/` network plus the same effects as the `h2c://` scheme. Port ranges are supported as a shortcut, which expands to multiple upstreams with the same host.
Upstream addresses _cannot_ contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported. You may use the [`rewrite`](/docs/caddyfile/directives/rewrite) directive should you need this.
Upstream addresses **cannot** contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported. You may use the [`rewrite`](/docs/caddyfile/directives/rewrite) directive should you need this.
If the address is not a URL (i.e. does not have a scheme), then placeholders can be used, but this makes the upstream _dynamically static_, meaning that potentially many different backends act as a single, static upstream in terms of health checks and load balancing. We recommend using a [dynamic upstreams](#dynamic-upstreams) module instead, if possible.
If the address is not a URL (i.e. does not have a scheme), then [placeholders](/docs/caddyfile/concepts#placeholders) can be used, but this makes the upstream _dynamically static_, meaning that potentially many different backends act as a single, static upstream in terms of health checks and load balancing. We recommend using a [dynamic upstreams](#dynamic-upstreams) module instead, if possible. When using placeholders, a port **must** be included (either by the placeholder replacement, or as a static suffix to the address).
#### Dynamic upstreams
@ -243,7 +244,14 @@ Load balancing is used whenever more than one upstream is defined. This is enabl
For policies that involve hashing, the [highest-random-weight (HRW)](https://en.wikipedia.org/wiki/Rendezvous_hashing) algorithm is used to ensure that a client or request with the same hash key is mapped to the same upstream, even if the list of upstreams change.
Some policies support fallback as an option, if noted, in which case they take a [block](/docs/caddyfile/concepts#blocks) with `fallback <policy>` which takes another load balancing policy. For those policies, the default fallback is `random`. Configuring a fallback allows using a secondary policy if the primary does not select one, allowing for powerful combinations. Fallbacks can be nested multiple times if desired. For example, `header` can be used as primary to allow for developers to choose a specific upstream, with a fallback of `first` for all other connections to implement primary/secondary failover.
Some policies support fallback as an option, if noted, in which case they take a [block](/docs/caddyfile/concepts#blocks) with `fallback <policy>` which takes another load balancing policy. For those policies, the default fallback is `random`. Configuring a fallback allows using a secondary policy if the primary does not select one, allowing for powerful combinations. Fallbacks can be nested multiple times if desired.
For example, `header` can be used as primary to allow for developers to choose a specific upstream, with a fallback of `first` for all other connections to implement primary/secondary failover.
```caddy-d
lb_policy header X-Upstream {
fallback first
}
```
- `random` randomly chooses an upstream

View file

@ -55,11 +55,19 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
- **&lt;email&gt;** is the email address to use for the ACME account managing the site's certificates.
<aside class="tip">
Keep in mind that Let's Encrypt may send you emails about your certificate nearing expiry, but this may be misleading because Caddy may have chosen to use a different issuer (e.g. ZeroSSL) when renewing. Check your logs and/or the certificate itself (in your browser for example) to see which issuer was used, and that its expiry is still valid; if so, you may safely ignore the email from Let's Encrypt.
</aside>
- **&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** <span id="protocols"/> specifies the minimum and maximum protocol versions. Default min: `tls1.2`. Default max: `tls1.3`
- **protocols** <span id="protocols"/> specifies the minimum and maximum protocol versions. DO NOT change these unless you know what you're doing. Configuring this is rarely necessary, because Caddy will always use modern defaults.
Default min: `tls1.2`, Default max: `tls1.3`
- **ciphers** <span id="ciphers"/> specifies the list of cipher suite names in descending preference order. It is recommended to not change these unless you know what you're doing. Note that cipher suites are not customizable for TLS 1.3; and not all TLS 1.2 ciphers are enabled by default. The supported names are (in no particular order here):
- **ciphers** <span id="ciphers"/> specifies the list of cipher suite names in descending preference order. DO NOT change these unless you know what you're doing. Note that cipher suites are not customizable for TLS 1.3; and not all TLS 1.2 ciphers are enabled by default. The supported names are (in no particular order here):
- `TLS_RSA_WITH_3DES_EDE_CBC_SHA`
- `TLS_RSA_WITH_AES_128_CBC_SHA`
- `TLS_RSA_WITH_AES_256_CBC_SHA`
@ -147,7 +155,7 @@ These issuers come standard with the `tls` directive:
#### acme
Obtains certificates using the ACME protocol.
Obtains certificates using the ACME protocol. Note that `acme` is a default issuer (using Let's Encrypt), so configuring it explicitly is usually unnecessary.
```caddy
... acme [<directory_url>] {
@ -174,9 +182,13 @@ Obtains certificates using the ACME protocol.
}
```
- **dir** <span id="dir"/> is the URL to the ACME CA's directory. Default: `https://acme-v02.api.letsencrypt.org/directory`
- **dir** <span id="dir"/> is the URL to the ACME CA's directory.
Default: `https://acme-v02.api.letsencrypt.org/directory`
- **test_dir** <span id="test_dir"/> is an optional fallback directory to use when retrying challenges; if all challenges fail, this endpoint will be used during retries; useful if a CA has a staging endpoint where you want to avoid rate limits on their production endpoint. Default: `https://acme-staging-v02.api.letsencrypt.org/directory`
- **test_dir** <span id="test_dir"/> is an optional fallback directory to use when retrying challenges; if all challenges fail, this endpoint will be used during retries; useful if a CA has a staging endpoint where you want to avoid rate limits on their production endpoint.
Default: `https://acme-staging-v02.api.letsencrypt.org/directory`
- **email** <span id="email"/> is the ACME account contact email address.
@ -216,7 +228,7 @@ Obtains certificates using the ACME protocol.
#### zerossl
Obtains certificates using the ACME protocol, specifically with ZeroSSL.
Obtains certificates using the ACME protocol, specifically with ZeroSSL. Note that `zerossl` is a default issuer, so configuring it explicitly is usually unnecessary.
```caddy
... zerossl [<api_key>] {
@ -224,13 +236,11 @@ Obtains certificates using the ACME protocol, specifically with ZeroSSL.
}
```
The syntax for `zerossl` is exactly the same as for `acme`, except that its name is `zerossl` and it can optionally take your ZeroSSL API key.
The syntax for `zerossl` is exactly the same as for [`acme`](#acme), except that its name is `zerossl` and it can optionally take your ZeroSSL API key.
The functionality of the `zerossl` issuer is the same as the `acme` issuer, except that it will use ZeroSSL's directory by default and it can automatically negotiate EAB credentials (whereas with the `acme` issuer, you have to manually provide EAB credentials and set the directory endpoint).
Its functionality is also the same, except that it will use ZeroSSL's directory by default and it can automatically negotiate EAB credentials (whereas with the `acme` issuer, you have to manually provide EAB credentials and set the directory endpoint).
When explicitly configuring `zerossl`, an email address is required so that your certificates can appear in your ZeroSSL dashboard.
Note that ZeroSSL is a default issuer, so configuring it explicitly is usually unnecessary.
When explicitly configuring `zerossl`, configuring an `email` is required so that your certificates can appear in your ZeroSSL dashboard.
#### internal
@ -244,9 +254,13 @@ Obtains certificates from an internal certificate authority.
}
```
- **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.
- **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 the `local` CA, or to create 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 change this, unless absolutely necessary.
By default, the root CA certificate has a `3600d` lifetime (10 years) and the intermediate has a `7d` lifetime (7 days).
Caddy will attempt to install the root CA certificate to the system trust store, but this may fail when Caddy is running as an unprivileged user, or when running in a Docker container. In that case, the root CA certificate will need to be manually installed, either by using the [`caddy trust`](/docs/command-line#caddy-trust) command, or by [copying out of the container](/docs/running#usage).
- **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 change this, unless absolutely necessary. It must be shorter than the intermediate's lifetime.
- **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).

View file

@ -31,8 +31,6 @@ $(function() {
**Request matchers** can be used to filter (or classify) requests by various criteria.
### Menu
- [Syntax](#syntax)
- [Examples](#examples)
- [Wildcard matchers](#wildcard-matchers)
@ -368,9 +366,9 @@ 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.
- If enclosed by `*`, it performs a fast substring match.
- If prefixed with `*`, it performs a fast suffix match (appears at the end).
- If suffixed with `*`, it performs a fast prefix match (appears at the start).
- If enclosed by `*`, it performs a fast substring match (appears anywhere).
- Otherwise, it is a fast exact match.
Different header fields within the same set are AND-ed. Multiple values per field are OR'ed.
@ -398,6 +396,10 @@ Match requests that do not have the `Foo` header field at all:
@not_foo header !Foo
```
Match WebSocket requests by checking for the `Connection` header containing `Upgrade` and the `Upgrade` header equalling `websocket`, using an [expression](#expression) matcher:
```caddy-d
@websockets `header({'Connection':'*Upgrade*','Upgrade':'websocket'})`
```
---

View file

@ -41,7 +41,7 @@ The very top of your Caddyfile can be a **global options block**. This is a bloc
There can only be one at most, and it must be the first block of the Caddyfile.
Possible options are:
Possible options are (click on each option to jump to its documentation):
```caddy
{
@ -282,6 +282,12 @@ See the [Automatic HTTPS](/docs/automatic-https) page for more details.
##### `email`
Your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates.
<aside class="tip">
Keep in mind that Let's Encrypt may send you emails about your certificate nearing expiry, but this may be misleading because Caddy may have chosen to use a different issuer (e.g. ZeroSSL) when renewing. Check your logs and/or the certificate itself (in your browser for example) to see which issuer was used, and that its expiry is still valid; if so, you may safely ignore the email from Let's Encrypt.
</aside>
##### `default_sni`
Sets a default TLS ServerName for when clients do not use SNI in their ClientHello.
@ -317,10 +323,16 @@ Configures the ACME DNS challenge provider to use for all ACME transactions. The
##### `on_demand_tls`
Configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [on_demand `tls` subdirective](/docs/caddyfile/directives/tls#syntax)). Highly recommended if using in production environments, to prevent abuse.
Configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [`on_demand` subdirective of the `tls` directive](/docs/caddyfile/directives/tls#syntax)). Required for use in production environments, to prevent abuse.
- **ask** will cause Caddy to make an HTTP request to the given URL with a query string of `?domain=` containing the value of the domain name. If the endpoint returns a `2xx` status code, Caddy will be authorized to obtain a certificate for that name. Any other status code will result in cancelling issuance of the certificate.
<aside class="tip">
The ask endpoint should return _as fast as possible_, in a few milliseconds, ideally. Typically, your endpoint should do a constant-time lookup in an database with an index by domain name; avoid loops. Avoid making DNS queries or other network requests.
</aside>
- **interval** and **burst** allows `<n>` certificate operations within `<duration>` interval.
@ -586,7 +598,7 @@ The name to put in the CommonName field of the root certificate. Default: `{pki.
The name to put in the CommonName field of the intermediate certificates. Default: `{pki.ca.name} - ECC Intermediate`
##### `intermediate_lifetime`
The [duration](/docs/conventions#durations) for which intermediate certificates are valid. This value must be less than the lifetime of the root cert (`3600d`). Default: `7d`. It is recommended not to change this unless absolutely necessary.
The [duration](/docs/conventions#durations) for which intermediate certificates are valid. This value must be less than the lifetime of the root cert (`3600d` or 10 years). Default: `7d`. It is recommended not to change this unless absolutely necessary.
##### `root`
A key pair (certificate and private key) to use as the root for the CA. If not specified, one will be generated and managed automatically.

View file

@ -8,8 +8,6 @@ This page demonstrates a few complete and minimal Caddyfile configurations for c
These are not drop-in solutions; you will have to customize your domain name, ports/sockets, directory paths, etc. They are intended to illustrate some of the most common configuration patterns.
#### Menu
- [Static file server](#static-file-server)
- [Reverse proxy](#reverse-proxy)
- [PHP](#php)

View file

@ -1,203 +0,0 @@
---
title: Caddyfile Spec
---
TODO: this page is unfinished
<style>
</style>
# Caddyfile Specification
This page describes the syntax of the Caddyfile. If it is your first time writing a Caddyfile, try the <a href="/v1/tutorial/caddyfile">Caddyfile primer</a> tutorial instead. This page is not beginner-friendly; it is technical and kind of boring.
Although this article is verbose, the Caddyfile is designed to be easily readable and writable by humans. You will find that it is easy to remember, not cumbersome, and flows off the fingers.
The term "Caddyfile" often refers to a file, but more generally means a blob of Caddy configuration text. A Caddyfile can be used to configure any Caddy server type: HTTP, DNS, etc. The basic structure and syntax of the Caddyfile is the same for all server types, but semantics change. Because of this variability, this document treats the Caddyfile only as the generic configuration syntax as it applies to all server types. Caddyfile documentation for specific types may be found within their respective docs. For instance, the HTTP server <a href="/v1/docs/http-caddyfile">documents the semantics of its Caddyfile</a>.
#### Topics
1. [File format & encoding](#)
2. [Lexical syntax](#)
3. [Structure](#)
4. [Labels](#)
5. [Directives](#)
6. [Environment variables](#)
7. [Import](#)
8. [Reusable snippets](#)
9. [Examples](#)
## File Format &amp; Encoding
The Caddyfile is plain Unicode text encoded with UTF-8. Each code point is distinct; specifically, lowercase and uppercase characters are different. A leading byte order mark (0xFEFF), if present, will be ignored.
## Lexical Syntax
A <b>token</b> is a sequence of whitespace-delimited characters in the Caddyfile. A token that starts with quotes <code>"</code> is read literally (including whitespace) until the next instance of quotes <code>"</code> that is not escaped. Quote literals may be escaped with a backslash like so: <code>\"</code>. Only quotes are escapable. <!-- Those stupid --> &ldquo;Smart quotes&rdquo; are not valid as quotes.
<b>Lines</b> are delimited with the <code>\n</code> (newline) character only. Carriage return <code>\r</code> is discarded unless quoted. Blank, unquoted lines are allowed and ignored.
<b>Comments</b> are discarded by the lexer. Comments begin with an unquoted hash <code>#</code> and continue to the end of the line. Comments may start a line or appear in the middle of a line as part of an unquoted token. For the purposes of this document, commented and blank lines are no longer considered.
Tokens are then evaluated by the parser for structure.
## Structure
A Caddyfile has no global scope or inheritance between separate blocks. The most global unit of the Caddyfile is an <b>entry</b>. An entry consists of a list of labels and a definition associated with those labels. A <b>label</b> is a string identifier, and a <b>definition</b> is a body (one or more lines) of tokens grouped together in a <i>block</i>:
<code class="block"><span class="cf-label-bg">list of labels</span>
<span class="cf-block-bg">definition (block)</span></code>
A Caddyfile with <i>only one</i> entry may consist simply of the label line(s) followed by the definition on the next line(s), as shown above. However, a Caddyfile with <i>more than one</i> entry <b>must</b> enclose each definition in curly braces <code>{ }</code>. The opening curly brace <code>{</code> must be at the end of the label line, and the closing curly brace <code>}</code> must be the only token on its line:
<code class="block"><span class="cf-label-bg">list of labels</span> <span class="cf-bigbrace">{</span>
<span class="cf-block-bg indent">definition (block)</span>
<span class="cf-bigbrace">}</span>
<span class="cf-label-bg">list of labels</span> <span class="cf-bigbrace">{</span>
<span class="cf-block-bg indent">definition (block)</span>
<span class="cf-bigbrace">}</span></code>
<p>
Consistent tab indentation is encouraged within blocks enclosed by curly braces.
</p>
<p>
<b>The first line of a Caddyfile is always a label line.</b> Comment lines, empty lines, and <a href="/v1/docs/import">import</a> lines are the exceptions.
</p>
<h3 id="labels">Labels</h3>
<p>
Labels are the only tokens that appear outside of blocks (with one exception being the <a href="/v1/docs/import">import</a> directive). A label line may have just one label:
</p>
<code class="block"><span class="cf-addr">label</span></code>
<p>
or several labels, separated by spaces:
</p>
<code class="block"><span class="cf-addr">label1 label2</span> ...</code>
<p>
If many labels are to head a block, the labels may be suffixed with a comma. A comma-suffixed label may be followed by a newline, in which case the next line will be considered part of the same line:
</p>
<code class="block"><span class="cf-addr">label1</span>,
<span class="cf-addr">label2</span></code>
<p>
Mixing of these patterns is valid (but discouraged), as long as the last label of the line has a comma if the next line is to continue the list of labels:
</p>
<code class="block"><span class="cf-addr">label1 label2</span>,
<span class="cf-addr">label3</span>, <span class="cf-addr">label4</span>,
<span class="cf-addr">label5</span></code>
<p>
A definition with multiple labels is replicated across each label as if they had been defined separately but with the same definition.
</p>
<h3 id="directives">Directives</h3>
<p>
The body of the definition follows label lines. The first token of each line in a definition body is a <b>directive</b>. Every token <i>after</i> the directive on the same line is an <b>argument</b>. Arguments are optional:
</p>
<code class="block"><span class="cf-dir">directive1</span>
<span class="cf-dir">directive2</span> <span class="cf-arg">arg1 arg2</span>
<span class="cf-dir">directive3</span> <span class="cf-arg">arg3</span></code>
<p>
Commas are not acceptable delimiters for arguments; they will be treated as part of the argument value. Arguments are delimited solely by same-line whitespace.
</p>
<p>
Directives may span multiple lines by opening a block. Blocks are enclosed by curly braces <code>{ }</code>. The opening curly brace <code>{</code> must be at the end of the directive's first line, and the closing curly brace <code>}</code> must be the only token on its line:
</p>
<code class="block"><span class="cf-dir">directive</span> {
...
}</code>
<p>
Within a directive block, the first token of each line may be considered a <b>subdirective</b> or <b>property</b>, depending on how it is used (other terms may be applied). And as before, they can have arguments:
</p>
<code class="block"><span class="cf-dir">directive</span> <span class="cf-arg">arg1</span> {
<span class="cf-subdir">subdir</span> arg2 arg3
...
}</code>
<p>
Subdirectives cannot open new blocks. In other words, nested directive blocks are not supported. If a directive block is empty, the curly braces should be omitted entirely.
</p>
<h3 id="env">Environment Variables</h3>
<p>
Any token (label, directive, argument, etc.) may contain or consist solely of an environment variable, which takes the Unix form or Windows form, enclosed in curly braces <code>{ }</code> without extra whitespace:
</p>
<code class="block"><span class="cf-addr">label_{$ENV_VAR_1}</span>
<span class="cf-dir">directive</span> <span class="cf-arg">{%ENV_VAR_2%}</span></code>
<p>
Either form works on any OS. A single environment variable does not expand out into multiple tokens, arguments, or values.
</p>
<h3 id="import">Import</h3>
<p>
The <a href="/v1/docs/import">import</a> directive is a special case, because it can appear outside a definition block. The consequence of this is that no label can take on the value of "import".
</p>
<p>
Where an import line is, that line will be replaced with the contents of the imported file, unmodified. See the <a href="/v1/docs/import">import docs</a> for more information.
</p>
<h3 id="snippets">Reusable Snippets</h3>
<p>
You can define snippets to be reused later in your Caddyfile by defining a block with a single-token label surrounded by parentheses:
</p>
<code class="block"><span class="cf-addr">(mysnippet)</span> {
...
}</code>
<p>
Then you can invoke the snippet with the <code>import</code> directive:
</p>
<p>
<code class="block"><span class="cf-dir">import</span> <span class="cf-arg">mysnippet</span></code>
<h3 id="examples">Examples</h3>
<p>
A very simple Caddyfile with only one entry:
<code class="block"><span class="cf-addr">label1</span>
<span class="cf-dir">directive1</span> <span class="cf-arg">argument1</span>
<span class="cf-dir">directive2</span></code>
</p>
<p>
Appending the prior example with another entry introduces the need for curly braces:
<code class="block"><span class="cf-addr">label1</span> {
<span class="cf-dir">directive1</span> <span class="cf-arg">arg1</span>
<span class="cf-dir">directive2</span>
}
<span class="cf-addr">label2</span>, <span class="cf-addr">label3</span> {
<span class="cf-dir">directive3</span> <span class="cf-arg">arg2</span>
<span class="cf-dir">directive4</span> <span class="cf-arg">arg3</span> <span class="cf-arg">arg4</span>
}
</code>
</p>
<p>
Some people prefer to always use braces even if there's just one entry; this is fine, but unnecessary:
<code class="block"><span class="cf-addr">label1</span> {
<span class="cf-dir">directive1</span> <span class="cf-arg">arg1</span>
<span class="cf-dir">directive2</span>
}</code>
</p>
<p>
Example in which a directive opens a block:
<code class="block"><span class="cf-addr">label1</span>
<span class="cf-dir">directive</span> <span class="cf-arg">arg1</span> {
<span class="cf-subdir">subdir</span> arg2 arg3
}
<span class="cf-dir">directive</span> <span class="cf-arg">arg4</span></code>
</p>
<p>
Similarly, but in an indented definition body, and with a comment:
<code class="block"><span class="cf-addr">label1</span> {
<span class="cf-dir">directive1</span> <span class="cf-arg">arg1</span>
<span class="cf-dir">directive2</span> <span class="cf-arg">arg2</span> {
<span class="cf-subdir">subdir1</span> arg3 arg4
<span class="cf-subdir">subdir2</span>
<span class="cf-comment"># nested blocks not supported</span>
}
<span class="cf-dir">directive3</span>
}</code>
</p>

View file

@ -178,7 +178,7 @@ Additionally, you should avoid performing expensive operations in `Provision`, s
#### Logs
If your module needs logging, do not use `log.Print*()` from the Go standard library. In other words, **do not use Go's global logger**. Caddy uses high-performance, highly flexible, structured logging with [zap](https://github.com/uber-go/zap).
See [how logging works](/docs/logging) in Caddy. If your module needs logging, do not use `log.Print*()` from the Go standard library. In other words, **do not use Go's global logger**. Caddy uses high-performance, highly flexible, structured logging with [zap](https://github.com/uber-go/zap).
To emit logs, get a logger in your module's Provision method:

View file

@ -18,7 +18,6 @@ If the HTTP and HTTPS ports (80 and 443, respectively) are privileged ports on y
</aside>
Then hit enter and type what you want it to do, so it looks like this:
```caddy
@ -34,7 +33,9 @@ Save this and run Caddy from the same folder that contains your Caddyfile:
You will probably be asked for your password, because Caddy serves all sites -- even local ones -- over HTTPS by default. (The password prompt should only happen the first time!)
<aside class="tip">
For local HTTPS, Caddy automatically generates certificates and unique private keys for you. The root certificate is added to your system's trust store, which is why the password prompt is necessary. It allows you to develop locally over HTTPS without certificate errors.
For local HTTPS, Caddy automatically generates certificates and unique private keys for you. The root certificate is added to your system's trust store, which is why the password prompt is necessary. It allows you to develop locally over HTTPS without certificate errors.
</aside>
(If you get permission errors, you may need to run with elevated privileges or choose a port higher than 1023.)
@ -78,6 +79,6 @@ When you are done with Caddy, make sure to stop it:
## Further reading
- [Common patterns](/docs/caddyfile/patterns)
- [Caddyfile concepts](/docs/caddyfile/concepts)
- [Directives](/docs/caddyfile/directives)
- [Common patterns](/docs/caddyfile/patterns)

View file

@ -11,6 +11,7 @@ While Caddy can be run directly with its [command line interface](/docs/command-
- [Unit Files](#unit-files)
- [Manual Installation](#manual-installation)
- [Using the Service](#using-the-service)
- [Local HTTPS](#local-https-with-systemd)
- [Overrides](#overrides)
- [SELinux Considerations](#selinux-considerations)
- [Windows service](#windows-service)
@ -19,6 +20,7 @@ While Caddy can be run directly with its [command line interface](/docs/command-
- [Docker Compose](#docker-compose)
- [Setup](#setup)
- [Usage](#usage)
- [Local HTTPS](#local-https-with-docker)
## Linux Service
@ -120,6 +122,14 @@ The Caddy process will run as the `caddy` user, which has its `$HOME` set to `/v
- The default [config storage location](/docs/conventions#configuration-directory) (for the auto-saved JSON config, primarily useful for the `caddy-api` service) will be in `/var/lib/caddy/.config/caddy`.
### Local HTTPS with systemd
When using Caddy for local development with HTTPS, you might use a [hostname](/docs/caddyfile/concepts#addresses) like `localhost` or `app.localhost`. This enables [Local HTTPS](/docs/automatic-https#local-https) using Caddy's local CA to issue certificates.
Since Caddy runs as the `caddy` user when running as a service, it won't have permission to install its root CA certificate to the system trust store. To do this, run [`sudo caddy trust`](/docs/command-line#caddy-trust) to perform installation.
If you want other devices to connect to your server when using the [`internal` issuer](/docs/caddyfile/directives/tls#internal), you will need to install the root CA certificate on those devices as well. You can find the root CA certificate at `/var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt`. Many web browsers now use their own trust store (ignoring the system's trust store), so you may also need to install the certificate manually there as well.
### Overrides
@ -158,14 +168,15 @@ Then, save the file and exit the text editor, and restart the service for it to
### SELinux Considerations
On SELinux enabled systems you have two options:
1. Install Caddy using the [COPR repo](https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/). Your systemd file and caddy binary will be created and labelled correctly. If you wish to use a custom build of Caddy, you'll need to label the executable as described below.
2. [Download Caddy from this site](https://caddyserver.com/download) or compile it with [`xcaddy`](https://github.com/caddyserver/xcaddy). In both cases you will need to label the files yourself.
1. Install Caddy using the [COPR repo](/docs/install#fedora-redhat-centos). Your systemd file and caddy binary will already be created and labelled correctly (so you may ignore this section). If you wish to use a custom build of Caddy, you'll need to label the executable as described below.
2. [Download Caddy from this site](/download) or compile it with [`xcaddy`](https://github.com/caddyserver/xcaddy). In either case, you will need to label the files yourself.
Systemd unit files and their executables will not be run unless labelled with `systemd_unit_file_t` and `bin_t` respectively.
The `systemd_unit_file_t` is automatically applied to files created in `/etc/systemd/...`, so be sure to create your `caddy.service` file there.
The `systemd_unit_file_t` label is automatically applied to files created in `/etc/systemd/...`, so be sure to create your `caddy.service` file there, as per the [manual installation](#manual-installation) instructions.
To tag the caddy binary, you can use the following commands:
To tag the `caddy` binary, you can use the following command:
<pre><code class="cmd bash">semanage fcontext -a -t bin_t /usr/bin/caddy && restorecon -Rv /usr/bin/caddy
</code></pre>
@ -308,6 +319,8 @@ To reload Caddy after making changes to your Caddyfile:
To see Caddy's 1000 most recent logs, and `f`ollow to see new ones streaming in:
<pre><code class="cmd bash">docker compose logs caddy -n=1000 -f</code></pre>
### Local HTTPS with Docker
When using Docker for local development with HTTPS, you might use a [hostname](/docs/caddyfile/concepts#addresses) like `localhost` or `app.localhost`. This enables [Local HTTPS](/docs/automatic-https#local-https) using Caddy's local CA to issue certificates. This means that HTTP clients outside the container will not trust the TLS certificate served by Caddy. To solve this, you may install Caddy's root CA cert on your host machine's trust store:
<div x-data="{ os: $persist(defaultOS(['linux', 'mac', 'windows'], 'linux')) }" class="tabs">
@ -345,3 +358,9 @@ When using Docker for local development with HTTPS, you might use a [hostname](/
</div>
</div>
Many web browsers now use their own trust store (ignoring the system's trust store), so you may also need to install the certificate manually there as well, using the `root.crt` file copied from the container in the command above.
- For Firefox, go to Preferences > Privacy & Security > Certificates > View Certificates > Authorities > Import, and select the `root.crt` file.
- For Chrome, go to Settings > Privacy and security > Security > Manage certificates > Authorities > Import, and select the `root.crt` file.

View file

@ -9,9 +9,6 @@ Caddy 2 is a whole new code base, written from scratch, to improve on Caddy 1. C
This guide won't delve into the new features available -- which are really cool, by the way, you should [learn them](/docs/getting-started) -- the goal here is to just get you up and running on Caddy 2 quickly.
### Menu
- [High-order bits](#high-order-bits)
- [Steps](#steps)
- [HTTPS and ports](#https-and-ports)

View file

@ -40,14 +40,14 @@
<li><a href="/docs/automatic-https">Automatic HTTPS</a></li>
<li class="heading">Articles</li>
<li><a href="/docs/v2-upgrade">Upgrading to Caddy 2</a></li>
<li><a href="/docs/architecture">Caddy Architecture</a></li>
<li><a href="/docs/conventions">Conventions</a></li>
<li><a href="/docs/config-adapters">Config Adapters</a></li>
<li><a href="/docs/running">Keep Caddy Running</a></li>
<li><a href="/docs/logging">How Logging Works</a></li>
<li><a href="/docs/metrics">Monitoring Caddy</a></li>
<li><a href="/docs/architecture">Caddy Architecture</a></li>
<li><a href="/docs/running">Keep Caddy Running</a></li>
<li><a href="/docs/signature-verification">Verifying Asset Signatures</a></li>
<li><a href="/docs/v2-upgrade">Upgrading to Caddy 2</a></li>
<li class="heading">Developers</li>
<li>

View file

@ -325,17 +325,22 @@ h2 {
}
h3 {
font-size: 34px;
font-size: 40px;
margin: 50px 0 20px;
}
h4 {
font-size: 24px;
font-size: 32px;
margin: 25px 0 15px;
}
h5 {
font-size: 22px;
font-size: 26px;
margin: 2em 0 1em;
}
h6 {
font-size: 20px;
margin: 2em 0 1em;
}