mirror of
https://github.com/caddyserver/website.git
synced 2025-04-21 12:36:16 -04:00
Docs for v2.7.2
This commit is contained in:
Francis Lavoie
parent
ee39c96c78
commit
d931345756
16 changed files with 143 additions and 42 deletions
|
|
@ -153,7 +153,7 @@ You should see:
|
|||
|
||||
<aside class="tip">
|
||||
|
||||
You can use the [`jq` command](https://stedolan.github.io/jq/) to prettify JSON output: **`curl ... | jq`**
|
||||
You can use the [`jq` command <img src="/resources/images/external-link.svg" class="external-link">](https://stedolan.github.io/jq/) to prettify JSON output: **`curl ... | jq`**
|
||||
|
||||
</aside>
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ title: "API"
|
|||
|
||||
# API
|
||||
|
||||
Caddy is configured through an administration endpoint which can be accessed via HTTP using a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. You can [configure this endpoint](/docs/json/admin/) in your Caddy config.
|
||||
Caddy is configured through an administration endpoint which can be accessed via HTTP using a [REST <img src="/resources/images/external-link.svg" class="external-link">](https://en.wikipedia.org/wiki/Representational_state_transfer) API. You can [configure this endpoint](/docs/json/admin/) in your Caddy config.
|
||||
|
||||
**Default address: `localhost:2019`**
|
||||
|
||||
|
|
@ -254,7 +254,7 @@ This section is for all `/config/` endpoints. It is experimental and subject to
|
|||
</aside>
|
||||
|
||||
|
||||
Caddy's config API provides [ACID guarantees](https://en.wikipedia.org/wiki/ACID) for individual requests, but changes that involve more than a single request are subject to collisions or data loss if not properly synchronized.
|
||||
Caddy's config API provides [ACID guarantees <img src="/resources/images/external-link.svg" class="external-link">](https://en.wikipedia.org/wiki/ACID) for individual requests, but changes that involve more than a single request are subject to collisions or data loss if not properly synchronized.
|
||||
|
||||
For example, two clients may `GET /config/foo` at the same time, make an edit within that scope (config path), then call `POST|PUT|PATCH|DELETE /config/foo/...` at the same time to apply their changes, resulting in a collision: either one will overwrite the other, or the second might leave the config in an unintended state since it was applied to a different version of the config than it was prepared against. This is because the changes are not aware of each other.
|
||||
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ Here's a 28-second video showing how it works:
|
|||
|
||||
- Caddy serves IP addresses and local/internal hostnames over HTTPS using self-signed certificates that are automatically trusted locally (if permitted).
|
||||
- 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).
|
||||
- Caddy serves public DNS names over HTTPS using certificates from a public ACME CA such as [Let's Encrypt <img src="/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org) or [ZeroSSL <img src="/resources/images/external-link.svg" class="external-link">](https://zerossl.com).
|
||||
- Examples: `example.com`, `sub.example.com`, `*.example.com`
|
||||
|
||||
Caddy keeps all managed certificates renewed and redirects HTTP (default port `80`) to HTTPS (default port `443`) automatically.
|
||||
|
|
@ -89,7 +89,7 @@ Any of the following will prevent automatic HTTPS from being activated, either i
|
|||
|
||||
**Special cases:**
|
||||
|
||||
- Domains ending in `.ts.net` will not be managed by Caddy. Instead, Caddy will automatically attempt to get these certificates at handshake-time from the locally-running [Tailscale](https://tailscale.com) instance. This requires that [HTTPS is enabled in your Tailscale account](https://tailscale.com/kb/1153/enabling-https/) and the Caddy process must either be running as root, or you must configure `tailscaled` to give your Caddy user [permission to fetch certificates](https://github.com/caddyserver/caddy/pull/4541#issuecomment-1021568348).
|
||||
- Domains ending in `.ts.net` will not be managed by Caddy. Instead, Caddy will automatically attempt to get these certificates at handshake-time from the locally-running [Tailscale <img src="/resources/images/external-link.svg" class="external-link">](https://tailscale.com) instance. This requires that [HTTPS is enabled in your Tailscale account <img src="/resources/images/external-link.svg" class="external-link">](https://tailscale.com/kb/1153/enabling-https/) and the Caddy process must either be running as root, or you must configure `tailscaled` to give your Caddy user [permission to fetch certificates](https://github.com/caddyserver/caddy/pull/4541#issuecomment-1021568348).
|
||||
|
||||
|
||||
## Effects
|
||||
|
|
@ -126,7 +126,7 @@ Caddy uses HTTPS automatically for all sites with a host (domain, IP, or hostnam
|
|||
|
||||
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. They are stored in [Caddy's data directory](/docs/conventions#data-directory) at `pki/authorities/local`.
|
||||
|
||||
Caddy's local CA is powered by [Smallstep libraries](https://smallstep.com/certificates/).
|
||||
Caddy's local CA is powered by [Smallstep libraries <img src="/resources/images/external-link.svg" class="external-link">](https://smallstep.com/certificates/).
|
||||
|
||||
Local HTTPS does not use ACME nor does it perform any DNS validation. It works only on the local machine and is trusted only where the CA's root certificate is installed.
|
||||
|
||||
|
|
@ -158,7 +158,7 @@ Unlike the root certificate, intermediate certificates have a much shorter lifet
|
|||
|
||||
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.
|
||||
|
||||
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/):
|
||||
One of Caddy's default CAs is [Let's Encrypt <img src="/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org/), which has a [staging endpoint <img src="/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org/docs/staging-environment/) that is not subject to the same [rate limits <img src="/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org/docs/rate-limits/):
|
||||
|
||||
```
|
||||
https://acme-staging-v02.api.letsencrypt.org/directory
|
||||
|
|
@ -166,7 +166,7 @@ https://acme-staging-v02.api.letsencrypt.org/directory
|
|||
|
||||
## 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 <img src="/resources/images/external-link.svg" class="external-link">](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. 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.
|
||||
|
||||
|
|
@ -247,7 +247,7 @@ Here's what happens if there's an error obtaining or renewing a certificate:
|
|||
- Maximum of 1 day between attempts
|
||||
- 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 <img src="/resources/images/external-link.svg" class="external-link">](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. Caddy's internal rate limit is currently 10 attempts per ACME account per 10 seconds.
|
||||
|
||||
|
|
@ -257,7 +257,7 @@ To avoid leaking resources, Caddy aborts in-flight tasks (including ACME transac
|
|||
|
||||
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.
|
||||
By default, Caddy enables two ACME-compatible CAs: [**Let's Encrypt** <img src="/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org) and [**ZeroSSL** <img src="/resources/images/external-link.svg" class="external-link">](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
|
||||
|
|
@ -279,4 +279,4 @@ If using the Caddyfile, Caddy takes site names literally with regards to the cer
|
|||
|
||||
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.
|
||||
**Note:** [Let's Encrypt requires <img src="/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org/docs/challenge-types/) the [DNS challenge](#dns-challenge) to obtain wildcard certificates.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ title: "Build from source"
|
|||
|
||||
Requirements:
|
||||
|
||||
- [Go](https://golang.org/doc/install) 1.19 or newer
|
||||
- [Go](https://golang.org/doc/install) 1.20 or newer
|
||||
|
||||
Clone the repository:
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ This procedure aims to simplify running custom `caddy` binaries while keeping su
|
|||
This procedure allows users to take advantage of the default configuration, systemd service files and bash-completion from the official package.
|
||||
|
||||
Requirements:
|
||||
- Install `caddy` package according to these [instructions](https://caddyserver.com/docs/install#debian-ubuntu-raspbian)
|
||||
- Install `caddy` package according to these [instructions](/docs/install#debian-ubuntu-raspbian)
|
||||
- Build your custom `caddy` binary according to the procedure listed in this document. (see above)
|
||||
- Your custom `caddy` binary should be located in the current directory.
|
||||
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ header [<matcher>] [[+|-|?|>]<field> [<value>|<find>] [<replace>]] {
|
|||
|
||||
For multiple header manipulations, you can open a block and specify one manipulation per line in the same way.
|
||||
|
||||
When using the `?` prefix to set a default header value, it is recommended to separate this into its own `header` directive. [Under the hood](https://caddyserver.com/docs/modules/http.handlers.headers#response/require), using `?` configures a response matcher which applies to the directive's entire handler which only applies the header operations if the field is not yet set. For example, if in the same directive, you have these two manipulations: `-Hidden` and `?Foo default`, then the `Hidden` header is _only_ removed if `Foo` is empty, which is typically not the intended effect.
|
||||
When using the `?` prefix to set a default header value, it is recommended to separate this into its own `header` directive. [Under the hood](/docs/modules/http.handlers.headers#response/require), using `?` configures a response matcher which applies to the directive's entire handler which only applies the header operations if the field is not yet set. For example, if in the same directive, you have these two manipulations: `-Hidden` and `?Foo default`, then the `Hidden` header is _only_ removed if `Foo` is empty, which is typically not the intended effect.
|
||||
|
||||
|
||||
## Examples
|
||||
|
|
|
|||
|
|
@ -52,15 +52,22 @@ Since Caddy v2.5, by default, headers with potentially sensitive information (`C
|
|||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
log {
|
||||
log [<logger_name>] {
|
||||
hostnames <hostnames...>
|
||||
output <writer_module> ...
|
||||
format <encoder_module> ...
|
||||
level <level>
|
||||
}
|
||||
```
|
||||
|
||||
- **output** configures where to write the logs. See [Output modules](#output-modules) below. Default: `stderr`
|
||||
- **format** describes how to encode, or format, the logs. See [Format modules](#format-modules) below. Default: `console` if `stdout` is detected to be a terminal, `json` otherwise.
|
||||
- **logger_name** is an optional override of the logger name for this site. By default, a logger name is generated automatically, e.g. `log0`, `log1`, and so on depending on the order of the sites in the Caddyfile. This is only useful if you wish to reliably refer to the output of this logger from another logger defined in global options. See [an example](#multiple-outputs) below.
|
||||
|
||||
- **hostnames** overrides the hostnames that this logger applies to. By default, the logger applies to the hostnames of the site block it appears in, i.e. the site addresses. This is useful if you wish to define different loggers per subdomain in a [wildcard site block](/docs/caddyfile/patterns#wildcard-certificates). See [an example](#wildcard-logs) below.
|
||||
|
||||
- **output** configures where to write the logs. See [Output modules](#output-modules) below. Default: `stderr`.
|
||||
|
||||
- **format** describes how to encode, or format, the logs. See [Format modules](#format-modules) below. Default: `console` if `stderr` is detected to be a terminal, `json` otherwise.
|
||||
|
||||
- **level** is the minimum entry level to log. Default: `INFO`. Note that access logs currently only emit `INFO` and `ERROR` level logs.
|
||||
|
||||
|
||||
|
|
@ -140,7 +147,7 @@ The **format** subdirective lets you customize how logs get encoded (formatted).
|
|||
|
||||
<aside class="tip">
|
||||
|
||||
**A note about Common Log Format (CLF):** CLF clashes with modern structured logs. To transform your access logs into the deprecated Common Log Format, please use the [`transform-encoder` plugin](https://github.com/caddyserver/transform-encoder).
|
||||
**A note about Common Log Format (CLF):** CLF clashes with modern structured logs. To transform your access logs into the deprecated Common Log Format, please use the [`transform-encoder` plugin <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/caddyserver/transform-encoder).
|
||||
|
||||
</aside>
|
||||
|
||||
|
|
@ -259,7 +266,7 @@ Masks IP addresses in the field using a CIDR mask, i.e. the number of bits from
|
|||
|
||||
There is separate configuration for IPv4 and IPv6 addresses, since they have a different total number of bits.
|
||||
|
||||
Most commonly, the fields to filter would be `request>remote_ip` for the directly connecting client, or `request>headers>X-Forwarded-For` if behind a reverse proxy.
|
||||
Most commonly, the fields to filter would be `request>remote_ip` for the directly connecting client, `request>client_ip` for the parsed "real client" when [`trusted_proxies`](/docs/caddyfile/options#trusted-proxies) is configured, or `request>headers>X-Forwarded-For` if behind a reverse proxy.
|
||||
|
||||
```caddy-d
|
||||
<field> ip_mask {
|
||||
|
|
@ -328,7 +335,9 @@ Useful to obscure the value if it's sensitive, while being able to notice whethe
|
|||
|
||||
## Examples
|
||||
|
||||
Enable access logging (to the console):
|
||||
Enable access logging to the default logger.
|
||||
|
||||
In other words, by default this logs to the console or stderr, but this can be changed by reconfiguring the default logger with the [`log` global option](/docs/caddyfile/options#log):
|
||||
|
||||
```caddy-d
|
||||
log
|
||||
|
|
@ -388,7 +397,9 @@ log {
|
|||
```
|
||||
|
||||
|
||||
Mask the remote address from the request, keeping the first 16 bits (i.e. 255.255.0.0) for IPv4 addresses, and the first 32 bits from IPv6 addresses. (Note that prior to Caddy v2.5, the field was named `remote_addr`, but is now `remote_ip`):
|
||||
Mask the remote address from the request, keeping the first 16 bits (i.e. 255.255.0.0) for IPv4 addresses, and the first 32 bits from IPv6 addresses.
|
||||
|
||||
Note that as of Caddy v2.7, both `remote_ip` and `client_ip` are logged, where `client_ip` is the "real IP" when [`trusted_proxies`](/docs/caddyfile/options#trusted-proxies) is configured:
|
||||
|
||||
```caddy-d
|
||||
log {
|
||||
|
|
@ -403,3 +414,52 @@ log {
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
<span id="wildcard-logs" /> To write separate log files for each subdomain in a [wildcard site block](/docs/caddyfile/patterns#wildcard-certificates), by overriding `hostnames` for each logger:
|
||||
|
||||
```caddy
|
||||
*.example.com {
|
||||
log {
|
||||
hostnames foo.example.com
|
||||
output file /var/log/foo.example.com.log
|
||||
}
|
||||
@foo host foo.example.com
|
||||
handle @foo {
|
||||
respond "foo"
|
||||
}
|
||||
|
||||
log {
|
||||
hostnames bar.example.com
|
||||
output file /var/log/bar.example.com.log
|
||||
}
|
||||
@bar host bar.example.com
|
||||
handle @bar {
|
||||
respond "bar"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<span id="multiple-outputs" /> To write the access logs for a particular subdomain to two different files, with different formats (one with [`transform-encoder` plugin <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/caddyserver/transform-encoder) and the other with [`json`](#json)).
|
||||
|
||||
This works by overriding the logger name as `foo` in the site block, then including the access logs produced by that logger in the two loggers in global options with `include http.log.access.foo`:
|
||||
|
||||
```caddy
|
||||
{
|
||||
log access-formatted {
|
||||
include http.log.access.foo
|
||||
output file /var/log/access-foo.log
|
||||
format transform "{common_log}"
|
||||
}
|
||||
|
||||
log access-json {
|
||||
include http.log.access.foo
|
||||
output file /var/log/access-foo.json
|
||||
format json
|
||||
}
|
||||
}
|
||||
|
||||
foo.example.com {
|
||||
log foo
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -38,6 +38,7 @@ Proxies requests to one or more backends with configurable transport, load balan
|
|||
- [Load balancing](#load-balancing)
|
||||
- [Active health checks](#active-health-checks)
|
||||
- [Passive health checks](#passive-health-checks)
|
||||
- [Events](#events)
|
||||
- [Streaming](#streaming)
|
||||
- [Headers](#headers)
|
||||
- [Rewrites](#rewrites)
|
||||
|
|
@ -334,6 +335,16 @@ Passive health checks happen inline with actual proxied requests. To enable this
|
|||
This should be a reasonably large number; configuring this means that the proxy will have a limit of `unhealthy_request_count × upstreams_count` total simultaneous requests, and any requests after that point will result in an error due to no upstreams being available.
|
||||
|
||||
|
||||
### Events
|
||||
|
||||
When an upstream transitions from being healthy to unhealthy or vice-versa, [an event](/docs/caddyfile/options#event-options) is emitted. These events can be used to trigger other actions, such as sending a notification or logging a message. The events are as follows:
|
||||
|
||||
- `healthy` is emitted when an upstream is marked healthy when it was previous unhealthy
|
||||
- `unhealthy` is emitted when an upstream is marked unhealthy when it was previous healthy
|
||||
|
||||
In both cases, the `host` is included as metadata in the event to identify the upstream that changed state. It can be used as a placeholder with `{event.data.host}` with the `exec` event handler, for example.
|
||||
|
||||
|
||||
|
||||
### Streaming
|
||||
|
||||
|
|
|
|||
|
|
@ -110,7 +110,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
|
|||
|
||||
- **eab** <span id="eab"/> configures ACME external account binding (EAB) for this site, using the key ID and MAC key provided by your CA.
|
||||
|
||||
- **on_demand** <span id="on_demand"/> enables [On-Demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es). **Security warning:** Doing so in production is insecure unless you also configure the [`on_demand_tls` global option](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to mitigate abuse.
|
||||
- **on_demand** <span id="on_demand"/> enables [On-Demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es). **Security warning:** Doing so in production is insecure unless you also configure the [`on_demand_tls` global option](/docs/caddyfile/options#on-demand-tls) to mitigate abuse.
|
||||
|
||||
- **client_auth** <span id="client_auth"/> enables and configures TLS client authentication:
|
||||
- **mode** <span id="mode"/> is the mode for authenticating the client. Allowed values are:
|
||||
|
|
|
|||
|
|
@ -112,6 +112,7 @@ Possible options are:
|
|||
client_ip_headers <headers...>
|
||||
metrics
|
||||
max_header_size <size>
|
||||
enable_full_duplex
|
||||
log_credentials
|
||||
protocols [h1|h2|h2c|h3]
|
||||
strict_sni_host [on|insecure_off]
|
||||
|
|
@ -299,7 +300,7 @@ Skips the attempts to install the local CA's root into the system trust store, a
|
|||
|
||||
|
||||
##### `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: ZeroSSL and Let's Encrypt's production endpoints.
|
||||
Specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint <img src="/resources/images/external-link.svg" class="external-link">](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: ZeroSSL and Let's Encrypt's production endpoints.
|
||||
|
||||
Note that a globally-configured ACME CA may not apply to all sites; see the [hostname requirements](/docs/automatic-https#hostname-requirements) for using the default ACME issuer(s).
|
||||
|
||||
|
|
@ -523,7 +524,20 @@ Enables Prometheus metrics collection; necessary before scraping metrics. Note t
|
|||
|
||||
##### `max_header_size`
|
||||
|
||||
The maximum size to parse from a client's HTTP request headers. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go).
|
||||
The maximum size to parse from a client's HTTP request headers. If the limit is exceeded, the server will respond with HTTP status `431 Request Header Fields Too Large`. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go). By default, the limit is `1MB`.
|
||||
|
||||
|
||||
##### `enable_full_duplex`
|
||||
|
||||
Enable full-duplex communication for HTTP/1 requests. Only has an effect if Caddy was built with Go 1.21 or later.
|
||||
|
||||
For HTTP/1 requests, the Go HTTP server by default consumes any unread portion of the request body before beginning to write the response, preventing handlers from concurrently reading from the request and writing the response. Enabling this option disables this behavior and permits handlers to continue to read from the request while concurrently writing the response.
|
||||
|
||||
For HTTP/2 requests, the Go HTTP server always permits concurrent reads and responses, so this option has no effect.
|
||||
|
||||
Test thoroughly with your HTTP clients, as some older clients may not support full-duplex HTTP/1 which can cause them to deadlock. See [golang/go#57786](https://github.com/golang/go/issues/57786) for more info.
|
||||
|
||||
⚠️ This is an experimental feature. Subject to change or removal.
|
||||
|
||||
|
||||
##### `log_credentials`
|
||||
|
|
@ -593,11 +607,27 @@ A key pair (certificate and private key) to use as the intermediate for the CA.
|
|||
|
||||
Caddy modules emit events when interesting things happen (or are about to happen).
|
||||
|
||||
Events typically include a metadata payload. The best way to learn about events and their payloads is from each module's documentation, but you may also see the events and their data payloads by enabling the [`debug` global option](#debug) and reading the logs.
|
||||
|
||||
##### `on`
|
||||
|
||||
Binds an event handler to the named event. Specify the name of the event handler module, followed by its configuration.
|
||||
|
||||
For example, to run a command after a certificate is obtained ([third-party plugin <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/mholt/caddy-events-exec) required):
|
||||
For example, to run a command after a certificate is obtained ([third-party plugin <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/mholt/caddy-events-exec) required), with a part of the event payload being passed to the script using a placeholder:
|
||||
|
||||
```caddy-d
|
||||
on cert_obtained exec systemctl reload mydaemon
|
||||
```caddy
|
||||
{
|
||||
events {
|
||||
on cert_obtained exec ./my-script.sh {event.data.certificate_path}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Events
|
||||
|
||||
These standard events are emitted by Caddy:
|
||||
|
||||
- [`tls` events <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/caddyserver/certmagic#events)
|
||||
- [`reverse_proxy` events](/docs/caddyfile/directives/reverse_proxy#events)
|
||||
|
||||
Plugins may also emit events, so check their documentation for details.
|
||||
|
|
|
|||
|
|
@ -603,7 +603,7 @@ If the admin API is used, then the CA ID defaults to "local". You may specify th
|
|||
<pre><code class="cmd bash">caddy upgrade
|
||||
[-k, --keep-backup]</code></pre>
|
||||
|
||||
Replaces the current Caddy binary with the latest version from [our download page](https://caddyserver.com/download) with the same modules installed, including all third-party plugins that are registered on the Caddy website.
|
||||
Replaces the current Caddy binary with the latest version from [our download page](/download) with the same modules installed, including all third-party plugins that are registered on the Caddy website.
|
||||
|
||||
Upgrades do not interrupt running servers; currently, the command only replaces the binary on disk. This might change in the future if we can figure out a good way to do it.
|
||||
|
||||
|
|
@ -620,7 +620,7 @@ This command may require elevated privileges if your user does not have permissi
|
|||
<pre><code class="cmd bash">caddy add-package <packages...>
|
||||
[-k, --keep-backup]</code></pre>
|
||||
|
||||
Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest version with the same modules installed, _plus_ the packages listed as arguments included in the new binary. Find the list of packages you can install from [our download page](https://caddyserver.com/download). Each argument should be the full package name.
|
||||
Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest version with the same modules installed, _plus_ the packages listed as arguments included in the new binary. Find the list of packages you can install from [our download page](/download). Each argument should be the full package name.
|
||||
|
||||
For example:
|
||||
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ unix//path/to/socket
|
|||
|
||||
<aside class="tip">
|
||||
|
||||
Caddy network addresses are not URLs. URLs couple the lower and higher layers of the [OSI model](https://en.wikipedia.org/wiki/OSI_model#Layer_architecture), but Caddy often uses network addresses independently of a specific application, so combining them would be problematic. In Caddy, network addresses refer precisely to resources that can be dialed or bound at L3-L5, but URLs combine L3-L7, which is too many. A network address requires a host+port and path to be mutually exclusive, but URLs do not. Network addresses sometimes support port ranges, but URLs do not.
|
||||
Caddy network addresses are not URLs. URLs couple the lower and higher layers of the [OSI model <img src="/resources/images/external-link.svg" class="external-link">](https://en.wikipedia.org/wiki/OSI_model#Layer_architecture), but Caddy often uses network addresses independently of a specific application, so combining them would be problematic. In Caddy, network addresses refer precisely to resources that can be dialed or bound at L3-L5, but URLs combine L3-L7, which is too many. A network address requires a host+port and path to be mutually exclusive, but URLs do not. Network addresses sometimes support port ranges, but URLs do not.
|
||||
|
||||
</aside>
|
||||
|
||||
|
|
@ -72,7 +72,7 @@ Caddy's configuration supports the use of _placeholders_ (variables). Using plac
|
|||
|
||||
<aside class="tip">
|
||||
|
||||
Placeholders are a similar idea to variables in other software. For example, [nginx has variables](https://nginx.org/en/docs/varindex.html) like `$uri` and `$document_root`.
|
||||
Placeholders are a similar idea to variables in other software. For example, [nginx has variables <img src="/resources/images/external-link.svg" class="external-link">](https://nginx.org/en/docs/varindex.html) like `$uri` and `$document_root`.
|
||||
|
||||
</aside>
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ Placeholder | Description
|
|||
`{system.arch}` | The system's architecture
|
||||
`{system.wd}` | The current working directory
|
||||
`{time.now}` | The current time as a Go Time struct
|
||||
`{time.now.http}` | The current time in the format used in [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified)
|
||||
`{time.now.http}` | The current time in the format used in [HTTP headers <img src="/resources/images/external-link.svg" class="external-link">](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified)
|
||||
`{time.now.unix}` | The current time as a unix timestamp in seconds
|
||||
`{time.now.unix_ms}` | The current time as a unix timestamp in milliseconds
|
||||
`{time.now.common_log}` | The current time in Common Log Format
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@ Caddy is easy to extend because of its modular architecture. Most kinds of Caddy
|
|||
**Prerequisites:**
|
||||
- Basic understanding of [Caddy's architecture](/docs/architecture)
|
||||
- Go language proficiency
|
||||
- [`go`](https://golang.org/doc/install)
|
||||
- [`xcaddy`](https://github.com/caddyserver/xcaddy)
|
||||
- [`go` <img src="/resources/images/external-link.svg" class="external-link">](https://golang.org/doc/install)
|
||||
- [`xcaddy` <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/caddyserver/xcaddy)
|
||||
|
||||
|
||||
## Quick Start
|
||||
|
|
|
|||
|
|
@ -73,7 +73,7 @@ After installing, please read the [service usage instructions](/docs/running#usi
|
|||
|
||||
[**View the Cloudsmith repos**](https://cloudsmith.io/~caddy/repos/)
|
||||
|
||||
If you wish to use the packaged support files (systemd services, bash completion and default configuration) with a custom Caddy build, instructions can be [found here](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian).
|
||||
If you wish to use the packaged support files (systemd services, bash completion and default configuration) with a custom Caddy build, instructions can be [found here](/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian).
|
||||
|
||||
|
||||
## Fedora, RedHat, CentOS
|
||||
|
|
|
|||
|
|
@ -92,7 +92,7 @@ You can see how the structured log is much more useful and contains much more in
|
|||
|
||||
Because the logs are structured and strongly-typed, they can be encoded into any format. So if you don't want to work with JSON, logs can be encoded into any other representation. Caddy supports others through [log encoder modules](/docs/json/logging/logs/encoder/), and even more can be added.
|
||||
|
||||
**Most importantly** in the distinction between structured logs and legacy formats, with a performance penalty a structured log [can be transformed into the legacy Common Log Format](https://github.com/caddyserver/transform-encoder), but not the other way around. It is non-trivial (or at least inefficient) to go from CLF to structured formats, and impossible considering the lack of information.
|
||||
**Most importantly** in the distinction between structured logs and legacy formats, with a performance penalty a structured log [can be transformed into the legacy Common Log Format <img src="/resources/images/external-link.svg" class="external-link">](https://github.com/caddyserver/transform-encoder), but not the other way around. It is non-trivial (or at least inefficient) to go from CLF to structured formats, and impossible considering the lack of information.
|
||||
|
||||
In essence, efficient, structured logging generally promotes these philosophies:
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ In other words, you're going to want to be able to _monitor_ Caddy.
|
|||
You'll need to turn metrics on. If using a Caddyfile, enable metrics [in global options](/docs/caddyfile/options#metrics):
|
||||
|
||||
> **Note**
|
||||
> Caddy 2.6 made metrics opt-in. To enable them, use either [Caddyfile global options](https://caddyserver.com/docs/caddyfile/options#metrics) or [the `metrics` parameter](https://caddyserver.com/docs/json/apps/http/servers/metrics/) of a server's JSON config.
|
||||
> Caddy 2.6 made metrics opt-in. To enable them, use either [Caddyfile global options](/docs/caddyfile/options#metrics) or [the `metrics` parameter](/docs/json/apps/http/servers/metrics/) of a server's JSON config.
|
||||
|
||||
```caddy
|
||||
{
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Upgrade Guide
|
|||
|
||||
Caddy 2 is a whole new code base, written from scratch, to improve on Caddy 1. Caddy 2 is not backwards-compatible with Caddy 1. But don't worry, for most basic setups, not much is different. This guide will help you transition as easily as possible.
|
||||
|
||||
This guide won't delve into the new features available -- which are really cool, by the way, you should [learn them](https://caddyserver.com/docs/getting-started) -- the goal here is to just get you up and running on Caddy 2 quickly.
|
||||
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
|
||||
|
|
@ -55,7 +55,7 @@ This guide won't delve into the new features available -- which are really cool,
|
|||
|
||||
## Steps
|
||||
|
||||
1. Get familiar with Caddy 2 by doing our [Getting Started](https://caddyserver.com/docs/getting-started) tutorial.
|
||||
1. Get familiar with Caddy 2 by doing our [Getting Started](/docs/getting-started) tutorial.
|
||||
2. Do step 1 if you haven't yet. Seriously -- we can't stress how important it is to at least know how to use Caddy 2. (It's more fun!)
|
||||
3. Use the guide below to transition your `caddy` command(s).
|
||||
4. Use the guide below to transition your Caddyfile.
|
||||
|
|
@ -313,7 +313,7 @@ You may find the new [`route`](/docs/caddyfile/directives/route) and [`handle`](
|
|||
|
||||
Because it accepts a matcher in v2, this means you can also change the site root depending on the request.
|
||||
|
||||
Remember to add a [`file_server` directive](https://caddyserver.com/docs/caddyfile/directives/file_server) if serving static files, since Caddy 2 does not assume this by default, whereas in v1 always had it enabled.
|
||||
Remember to add a [`file_server` directive](/docs/caddyfile/directives/file_server) if serving static files, since Caddy 2 does not assume this by default, whereas in v1 always had it enabled.
|
||||
|
||||
|
||||
### status
|
||||
|
|
@ -372,7 +372,7 @@ If you want to write a plugin for Caddy 2, [learn how to write a Caddy module](/
|
|||
|
||||
### Building Caddy 2 with plugins
|
||||
|
||||
Caddy 2 can be downloaded with plugins at the [interactive download page](https://caddyserver.com/download). Alternatively, you can [build Caddy yourself](https://caddyserver.com/docs/build) using `xcaddy` and choose which plugins to include. `xcaddy` automates the instructions in Caddy's [main.go](https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go) file.
|
||||
Caddy 2 can be downloaded with plugins at the [interactive download page](/download). Alternatively, you can [build Caddy yourself](/docs/build) using `xcaddy` and choose which plugins to include. `xcaddy` automates the instructions in Caddy's [main.go](https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go) file.
|
||||
|
||||
|
||||
## Getting help
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue