mirror of
https://github.com/caddyserver/website.git
synced 2025-04-24 22:16:15 -04:00
Updated for v2.8.0
This commit is contained in:
Francis Lavoie
parent
0b35d1a195
commit
5b59f48e57
19 changed files with 223 additions and 69 deletions
|
|
@ -126,7 +126,7 @@ localhost {
|
|||
|
||||
Here, `lb_policy` is a subdirective to [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) (it sets the load balancing policy to use between backends).
|
||||
|
||||
**Unless otherwise documented, directives cannot be used within other directive blocks.** For example, [`basicauth`](/docs/caddyfile/directives/basicauth) cannot be used within [`file_server`](/docs/caddyfile/directives/file_server) because the file server does not know how to do authentication; but you can use directives within [`route`](/docs/caddyfile/directives/route), [`handle`](/docs/caddyfile/directives/handle), and [`handle_path`](/docs/caddyfile/directives/handle_path) blocks because they are specifically designed to group directives together.
|
||||
**Unless otherwise documented, directives cannot be used within other directive blocks.** For example, [`basic_auth`](/docs/caddyfile/directives/basic_auth) cannot be used within [`file_server`](/docs/caddyfile/directives/file_server) because the file server does not know how to do authentication; but you can use directives within [`route`](/docs/caddyfile/directives/route), [`handle`](/docs/caddyfile/directives/handle), and [`handle_path`](/docs/caddyfile/directives/handle_path) blocks because they are specifically designed to group directives together.
|
||||
|
||||
Note that when the HTTP Caddyfile is adapted, HTTP handler directives are sorted according to a specific default [directive order](/docs/caddyfile/directives#directive-order) unless in a [`route`](/docs/caddyfile/directives/route) block, so the order of appearance of the directives does not matter except in `route` blocks.
|
||||
|
||||
|
|
@ -187,12 +187,6 @@ The closing marker can be indented, which causes every line of text to have that
|
|||
|
||||
Additional tokens may follow the closing marker as arguments to the directive (such as in the example above, the status code `200`).
|
||||
|
||||
<aside class="advice">
|
||||
|
||||
The [`caddy fmt`](/docs/command-line#caddy-fmt) command [does not support](https://github.com/caddyserver/caddy/issues/5930#issuecomment-1797709061) heredocs.
|
||||
|
||||
</aside>
|
||||
|
||||
|
||||
## Global options
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ title: Caddyfile Directives
|
|||
|
||||
# Caddyfile Directives
|
||||
|
||||
Directives are functional keywords that appear within site [blocks](/docs/caddyfile/concepts#blocks). Sometimes, they may open blocks of their own which can contain _subdirectives_, but directives **cannot** be used within other directives unless noted. For example, you can't use `basicauth` inside a `file_server` block, because `file_server` does not know how to do authentication. However, you _may_ use some directives within special directive blocks like `handle` and `route` because they are specifically designed to group HTTP handler directives.
|
||||
Directives are functional keywords that appear within site [blocks](/docs/caddyfile/concepts#blocks). Sometimes, they may open blocks of their own which can contain _subdirectives_, but directives **cannot** be used within other directives unless noted. For example, you can't use `basic_auth` inside a `file_server` block, because `file_server` does not know how to do authentication. However, you _may_ use some directives within special directive blocks like `handle` and `route` because they are specifically designed to group HTTP handler directives.
|
||||
|
||||
- [Syntax](#syntax)
|
||||
- [Directive Order](#directive-order)
|
||||
|
|
@ -43,12 +43,13 @@ Directive | Description
|
|||
----------|------------
|
||||
**[abort](/docs/caddyfile/directives/abort)** | Aborts the HTTP request
|
||||
**[acme_server](/docs/caddyfile/directives/acme_server)** | An embedded ACME server
|
||||
**[basicauth](/docs/caddyfile/directives/basicauth)** | Enforces HTTP Basic Authentication
|
||||
**[basic_auth](/docs/caddyfile/directives/basic_auth)** | Enforces HTTP Basic Authentication
|
||||
**[bind](/docs/caddyfile/directives/bind)** | Customize the server's socket address
|
||||
**[encode](/docs/caddyfile/directives/encode)** | Encodes (usually compresses) responses
|
||||
**[error](/docs/caddyfile/directives/error)** | Trigger an error
|
||||
**[file_server](/docs/caddyfile/directives/file_server)** | Serve files from disk
|
||||
**[forward_auth](/docs/caddyfile/directives/forward_auth)** | Delegate authentication to an external service
|
||||
**[fs](/docs/caddyfile/directives/fs)** | Set the file system to use for file I/O
|
||||
**[handle](/docs/caddyfile/directives/handle)** | A mutually-exclusive group of directives
|
||||
**[handle_errors](/docs/caddyfile/directives/handle_errors)** | Defines routes for handling errors
|
||||
**[handle_path](/docs/caddyfile/directives/handle_path)** | Like handle, but strips path prefix
|
||||
|
|
@ -120,6 +121,7 @@ tracing
|
|||
|
||||
map
|
||||
vars
|
||||
fs
|
||||
root
|
||||
skip_log
|
||||
|
||||
|
|
@ -136,7 +138,7 @@ uri
|
|||
try_files
|
||||
|
||||
# middleware handlers; some wrap responses
|
||||
basicauth
|
||||
basic_auth
|
||||
forward_auth
|
||||
request_header
|
||||
encode
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
title: basicauth (Caddyfile directive)
|
||||
title: basic_auth (Caddyfile directive)
|
||||
---
|
||||
|
||||
# basicauth
|
||||
# basic_auth
|
||||
|
||||
Enables HTTP Basic Authentication, which can be used to protect directories and files with a username and hashed password.
|
||||
|
||||
|
|
@ -14,11 +14,13 @@ Caddy configuration does not accept plaintext passwords; you MUST hash them befo
|
|||
|
||||
After a successful authentication, the `{http.auth.user.id}` placeholder will be available, which contains the authenticated username.
|
||||
|
||||
Prior to v2.8.0, this directive was named `basicauth`, but was renamed for consistency with other directives.
|
||||
|
||||
|
||||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
basicauth [<matcher>] [<hash_algorithm> [<realm>]] {
|
||||
basic_auth [<matcher>] [<hash_algorithm> [<realm>]] {
|
||||
<username> <hashed_password> [<salt_base64>]
|
||||
...
|
||||
}
|
||||
|
|
@ -41,7 +43,7 @@ Require authentication for all requests to `example.com`:
|
|||
|
||||
```caddy
|
||||
example.com {
|
||||
basicauth {
|
||||
basic_auth {
|
||||
# Username "Bob", password "hiccup"
|
||||
Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
|
||||
}
|
||||
|
|
@ -55,7 +57,7 @@ Protect files in `/secret/` so only `Bob` can access them (and anyone can see ot
|
|||
example.com {
|
||||
root * /srv
|
||||
|
||||
basicauth /secret/* {
|
||||
basic_auth /secret/* {
|
||||
# Username "Bob", password "hiccup"
|
||||
Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
|
||||
}
|
||||
|
|
@ -45,13 +45,39 @@ encode [<matcher>] <formats...> {
|
|||
|
||||
```caddy-d
|
||||
match {
|
||||
header Content-Type text/*
|
||||
header Content-Type application/json*
|
||||
header Content-Type application/javascript*
|
||||
header Content-Type application/xhtml+xml*
|
||||
header Content-Type application/atom+xml*
|
||||
header Content-Type application/rss+xml*
|
||||
header Content-Type image/svg+xml*
|
||||
header Content-Type application/atom+xml*
|
||||
header Content-Type application/eot*
|
||||
header Content-Type application/font*
|
||||
header Content-Type application/geo+json*
|
||||
header Content-Type application/graphql+json*
|
||||
header Content-Type application/javascript*
|
||||
header Content-Type application/json*
|
||||
header Content-Type application/ld+json*
|
||||
header Content-Type application/manifest+json*
|
||||
header Content-Type application/opentype*
|
||||
header Content-Type application/otf*
|
||||
header Content-Type application/rss+xml*
|
||||
header Content-Type application/truetype*
|
||||
header Content-Type application/ttf*
|
||||
header Content-Type application/vnd.api+json*
|
||||
header Content-Type application/vnd.ms-fontobject*
|
||||
header Content-Type application/wasm*
|
||||
header Content-Type application/x-httpd-cgi*
|
||||
header Content-Type application/x-javascript*
|
||||
header Content-Type application/x-opentype*
|
||||
header Content-Type application/x-otf*
|
||||
header Content-Type application/x-perl*
|
||||
header Content-Type application/x-protobuf*
|
||||
header Content-Type application/x-ttf*
|
||||
header Content-Type application/xhtml+xml*
|
||||
header Content-Type application/xml*
|
||||
header Content-Type font/*
|
||||
header Content-Type image/svg+xml*
|
||||
header Content-Type image/vnd.microsoft.icon*
|
||||
header Content-Type image/x-icon*
|
||||
header Content-Type multipart/bag*
|
||||
header Content-Type multipart/mixed*
|
||||
header Content-Type text/*
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,9 @@ file_server [<matcher>] [browse] {
|
|||
root <path>
|
||||
hide <files...>
|
||||
index <filenames...>
|
||||
browse [<template_file>]
|
||||
browse [<template_file>] {
|
||||
reveal_symlinks
|
||||
}
|
||||
precompressed <formats...>
|
||||
status <status>
|
||||
disable_canonical_uris
|
||||
|
|
@ -53,6 +55,8 @@ file_server [<matcher>] [browse] {
|
|||
|
||||
- **<template_file>** <span id="template_file"/> is an optional custom template file to use for directory listings. Defaults to the template that can be extracted using the command `caddy file-server export-template`, which will print the defaut template to stdout. The embedded template can also be found [here in the source code ](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browse.html). Browse templates can use actions from [the standard templates module](/docs/modules/http.handlers.templates#docs) as well.
|
||||
|
||||
- **reveal_symlinks** <span id="reveal_symlinks"/> enables revealing the targets of symbolic links in directory listings. By default, the symlink targets are hidden, and only the link file itself is shown.
|
||||
|
||||
- **precompressed** <span id="precompressed"/> is the list of encoding formats to search for precompressed sidecar files. Arguments are an ordered list of encoding formats to search for precompressed [sidecar files](https://en.wikipedia.org/wiki/Sidecar_file). Supported formats are `gzip` (`.gz`), `zstd` (`.zst`) and `br` (`.br`).
|
||||
|
||||
All file lookups will look for the existence of the uncompressed file first. Once found Caddy will look for sidecar files with the file extension of each enabled format. If a precompressed sidecar file is found, Caddy will respond with the precompressed file, with the `Content-Encoding` response header set appropriately. Otherwise, Caddy will respond with the uncompressed file as normal. If the [`encode` directive](encode) is enabled, then it may compress the response on-the-fly if not precompressed.
|
||||
|
|
|
|||
48
src/docs/markdown/caddyfile/directives/fs.md
Normal file
48
src/docs/markdown/caddyfile/directives/fs.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
title: fs (Caddyfile directive)
|
||||
---
|
||||
|
||||
# fs
|
||||
|
||||
Sets which file system should be used for performing file I/O.
|
||||
|
||||
This could let you connect to a remote filesystem running in the cloud, or a database with a file-like interface, or even to read from files embedded within the Caddy binary.
|
||||
|
||||
First, you must declare a file system name using the [`filesystem` global option](/docs/caddyfile/options#filesystem), then you can use this directive to specify which file system to use.
|
||||
|
||||
This directive is often used in conjunction with the [`file_server` directive](file_server) to serve static files, or the [`try_files` directive](try_files) to perform rewrites based on the existence of files. Typically also used with [`root` directive](root) to set the root path within the file system.
|
||||
|
||||
|
||||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
fs [<matcher>] <filesystem>
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
Using an file system named `foo`, using an imaginary module named `custom` which might require authentication:
|
||||
|
||||
```caddy
|
||||
{
|
||||
filesystem foo custom {
|
||||
api_key abc123
|
||||
}
|
||||
}
|
||||
|
||||
example.com {
|
||||
fs foo
|
||||
root /srv
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
To only serve images from the `foo` file system, and the rest from the default file system:
|
||||
|
||||
```caddy
|
||||
example.com {
|
||||
fs /images* foo
|
||||
root /srv
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
|
@ -8,6 +8,8 @@ Sets up error handlers.
|
|||
|
||||
When the normal HTTP request handlers return an error, normal processing stops and the error handlers are invoked. Error handlers form a route which is just like normal routes, and they can do anything that normal routes can do. This enables great control and flexibility when handling errors during HTTP requests. For example, you can serve static error pages, templated error pages, or reverse proxy to another backend to handle errors.
|
||||
|
||||
The directive may be repeated with different status codes to handle different errors differently. If no status codes are specified, then it will match any error, acting as a fallback if any other error handlers does not match.
|
||||
|
||||
A request's context is carried into error routes, so any values set on the request context such as [site root](root) or [vars](vars) will be preserved in error handlers, too. Additionally, [new placeholders](#placeholders) are available when handling errors.
|
||||
|
||||
Note that certain directives, for example [`reverse_proxy`](reverse_proxy) which may write a response with an HTTP status which is classified as an error, will _not_ trigger the error routes.
|
||||
|
|
@ -18,11 +20,13 @@ You may use the [`error`](error) directive to explicitly trigger an error based
|
|||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
handle_errors {
|
||||
handle_errors <status_codes...> {
|
||||
<directives...>
|
||||
}
|
||||
```
|
||||
|
||||
- **<status_codes...>** is one or more HTTP status codes to match against the error being handled. The status codes may be 3-digit numbers, or a special case of `4xx` or `5xx` which match against all status codes in the range of 400-499 or 500-599, respectively. If no status codes are specified, then it will match any error, acting as a fallback if any other error handlers does not match.
|
||||
|
||||
- **<directives...>** is a list of HTTP handler [directives](/docs/caddyfile/directives) and [matchers](/docs/caddyfile/matchers), one per line.
|
||||
|
||||
|
||||
|
|
@ -93,7 +97,23 @@ handle_errors {
|
|||
}
|
||||
```
|
||||
|
||||
To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher, using [`handle`](handle) for mutual exclusivity:
|
||||
To handle specific error codes differently:
|
||||
|
||||
```caddy-d
|
||||
handle_errors 404 410 {
|
||||
respond "It's a 404 or 410 error!"
|
||||
}
|
||||
|
||||
handle_errors 5xx {
|
||||
respond "It's a 5xx error."
|
||||
}
|
||||
|
||||
handle_errors {
|
||||
respond "It's another error"
|
||||
}
|
||||
```
|
||||
|
||||
The above behaves the same as the below, which uses an [`expression`](/docs/caddyfile/matchers#expression) matcher against the status codes, and using [`handle`](handle) for mutual exclusivity:
|
||||
|
||||
```caddy-d
|
||||
handle_errors {
|
||||
|
|
|
|||
|
|
@ -289,6 +289,7 @@ format filter {
|
|||
fields {
|
||||
<field> <filter> ...
|
||||
}
|
||||
<field> <filter> ...
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -296,6 +297,10 @@ Nested fields can be referenced by representing a layer of nesting with `>`. In
|
|||
|
||||
The following fields are fundamental to the log and cannot be filtered because they are added by the underlying logging library as special cases: `ts`, `level`, `logger`, and `msg`.
|
||||
|
||||
Specifying `wrap` is optional; if omitted, a default is chosen depending on whether the current output module is [`stderr`](#stderr) or [`stdout`](#stdout), and is an interactive terminal, in which case [`console`](#console) is chosen, otherwise [`json`](#json) is chosen.
|
||||
|
||||
As a shortcut, the `fields` block can be omitted and the filters can be specified directly within the `filter` block.
|
||||
|
||||
These are the available filters:
|
||||
|
||||
##### delete
|
||||
|
|
@ -337,7 +342,7 @@ Most commonly, the fields to filter would be:
|
|||
- `request>headers>X-Forwarded-For` if behind a reverse proxy
|
||||
|
||||
```caddy-d
|
||||
<field> ip_mask {
|
||||
<field> ip_mask [<ipv4> [<ipv6>]] {
|
||||
ipv4 <cidr>
|
||||
ipv6 <cidr>
|
||||
}
|
||||
|
|
@ -458,10 +463,7 @@ Delete the `User-Agent` request header from the logs:
|
|||
example.com {
|
||||
log {
|
||||
format filter {
|
||||
wrap console
|
||||
fields {
|
||||
request>headers>User-Agent delete
|
||||
}
|
||||
request>headers>User-Agent delete
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -474,12 +476,9 @@ Redact multiple sensitive cookies. (Note that some sensitive headers are logged
|
|||
example.com {
|
||||
log {
|
||||
format filter {
|
||||
wrap console
|
||||
fields {
|
||||
request>headers>Cookie cookie {
|
||||
replace session REDACTED
|
||||
delete secret
|
||||
}
|
||||
request>headers>Cookie cookie {
|
||||
replace session REDACTED
|
||||
delete secret
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -495,13 +494,8 @@ Note that as of Caddy v2.7, both `remote_ip` and `client_ip` are logged, where `
|
|||
example.com {
|
||||
log {
|
||||
format filter {
|
||||
wrap console
|
||||
fields {
|
||||
request>remote_ip ip_mask {
|
||||
ipv4 16
|
||||
ipv6 32
|
||||
}
|
||||
}
|
||||
request>remote_ip ip_mask 16 32
|
||||
request>client_ip ip_mask 16 32
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,18 +1,20 @@
|
|||
---
|
||||
title: skip_log (Caddyfile directive)
|
||||
title: log_skip (Caddyfile directive)
|
||||
---
|
||||
|
||||
# skip_log
|
||||
# log_skip
|
||||
|
||||
Skips access logging for matched requests.
|
||||
|
||||
This should be used alongside the [`log` directive](/docs/caddyfile/directives/log) to skip logging requests that are not relevant for your needs.
|
||||
|
||||
Prior to v2.8.0, this directive was named `skip_log`, but was renamed for consistency with other directives.
|
||||
|
||||
|
||||
## Syntax
|
||||
|
||||
```caddy-d
|
||||
skip_log [<matcher>]
|
||||
log_skip [<matcher>]
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -25,7 +27,7 @@ example.com {
|
|||
root * /srv
|
||||
|
||||
log
|
||||
skip_log /static*
|
||||
log_skip /static*
|
||||
|
||||
file_server
|
||||
}
|
||||
|
|
@ -36,7 +38,7 @@ Skip access logging for requests matching a pattern; in this case, for files wit
|
|||
|
||||
```caddy-d
|
||||
@skip path_regexp \.(js|css|png|jpe?g|gif|ico|woff|otf|ttf|eot|svg|txt|pdf|docx?|xlsx?)$
|
||||
skip_log @skip
|
||||
log_skip @skip
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -45,7 +47,7 @@ The matcher is not needed if it's found within a route which is already within a
|
|||
```caddy-d
|
||||
handle_path /static* {
|
||||
root * /srv/static
|
||||
skip_log
|
||||
log_skip
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
|
@ -509,6 +509,7 @@ transport http {
|
|||
tls
|
||||
tls_client_auth <automate_name> | <cert_file> <key_file>
|
||||
tls_insecure_skip_verify
|
||||
tls_curves <curves...>
|
||||
tls_timeout <duration>
|
||||
tls_trusted_ca_certs <pem_files...>
|
||||
tls_server_name <server_name>
|
||||
|
|
@ -552,6 +553,8 @@ transport http {
|
|||
|
||||
- **tls_insecure_skip_verify** <span id="tls_insecure_skip_verify"/> turns off TLS handshake verification, making the connection insecure and vulnerable to man-in-the-middle attacks. _Do not use in production._
|
||||
|
||||
- **tls_curves** <span id="tls_curves"/> is a list of elliptic curves to support for the upstream connection. Caddy's defaults are modern and secure, so you should only need to configure this if you have specific requirements.
|
||||
|
||||
- **tls_timeout** <span id="tls_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait for the TLS handshake to complete. Default: No timeout.
|
||||
|
||||
- **tls_trusted_ca_certs** <span id="tls_trusted_ca_certs"/> is a list of PEM files that specify CA public keys to trust when connecting to the backend.
|
||||
|
|
|
|||
|
|
@ -23,6 +23,8 @@ rewrite [<matcher>] <to>
|
|||
|
||||
- **<to>** is the URI to rewrite the request to. Only the components of the URI (path or query string) that are specified in the rewrite will be operated on. The URI path is any substring that comes before `?`. If `?` is omitted, then the whole token is considered to be the path.
|
||||
|
||||
Prior to v2.8.0, that the `<to>` argument could be confused by the parser for a [matcher token](/docs/caddyfile/matchers#syntax) if it began with `/`, so it was necessary to specify a wildcard matcher token (`*`).
|
||||
|
||||
|
||||
## Similar directives
|
||||
|
||||
|
|
@ -44,6 +46,12 @@ example.com {
|
|||
}
|
||||
```
|
||||
|
||||
<aside class="tip">
|
||||
|
||||
Note that prior to v2.8.0, a [wildcard matcher](/docs/caddyfile/matchers#wildcard-matchers) was required here because the first argument is ambiguous with a [path matcher](/docs/caddyfile/matchers#path-matchers), i.e. `rewrite * /foo`, but it can now be simplified to `rewrite /foo`.
|
||||
|
||||
</aside>
|
||||
|
||||
Prefixing all requests with `/api`, preserving the rest of the URI, then reverse proxying to an app:
|
||||
|
||||
```caddy
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ root [<matcher>] <path>
|
|||
|
||||
- **<path>** is the path to use for the site root.
|
||||
|
||||
Note that the `<path>` argument could be confused by the parser for a [matcher token](/docs/caddyfile/matchers#syntax) if it begins with `/`. To disambiguate, specify a wildcard matcher token (`*`). See examples below.
|
||||
Prior to v2.8.0, that the `<path>` argument could be confused by the parser for a [matcher token](/docs/caddyfile/matchers#syntax) if it began with `/`, so it was necessary to specify a wildcard matcher token (`*`).
|
||||
|
||||
|
||||
## Examples
|
||||
|
|
@ -40,15 +40,13 @@ root * /home/bob/public_html
|
|||
|
||||
<aside class="tip">
|
||||
|
||||
Note that a [wildcard matcher](/docs/caddyfile/matchers#wildcard-matchers) is required here because the first argument is ambiguous with a [path matcher](/docs/caddyfile/matchers#path-matchers).
|
||||
Note that prior to v2.8.0, a [wildcard matcher](/docs/caddyfile/matchers#wildcard-matchers) was required here because the first argument is ambiguous with a [path matcher](/docs/caddyfile/matchers#path-matchers), i.e. `root * /srv`, but it can now be simplified to `root /srv`.
|
||||
|
||||
</aside>
|
||||
|
||||
|
||||
Set the site root to `public_html` (relative to current working directory) for all requests:
|
||||
|
||||
(No matcher token is required here because our site root is a relative path, so it does not start with a forward slash and thus is not ambiguous.)
|
||||
|
||||
```caddy-d
|
||||
root public_html
|
||||
```
|
||||
|
|
|
|||
|
|
@ -38,12 +38,14 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
|
|||
resolvers <dns_servers...>
|
||||
eab <key_id> <mac_key>
|
||||
on_demand
|
||||
reuse_private_keys
|
||||
client_auth {
|
||||
mode [request|require|verify_if_given|require_and_verify]
|
||||
trusted_ca_cert <base64_der>
|
||||
trusted_ca_cert_file <filename>
|
||||
trusted_leaf_cert <base64_der>
|
||||
trusted_leaf_cert_file <filename>
|
||||
verifier <module>
|
||||
}
|
||||
issuer <issuer_name> [<params...>]
|
||||
get_certificate <manager_name> [<params...>]
|
||||
|
|
@ -127,6 +129,8 @@ Keep in mind that Let's Encrypt may send you emails about your certificate neari
|
|||
|
||||
- **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.
|
||||
|
||||
- **reuse_private_keys** <span id="reuse_private_keys"/> enables reuse of private keys when renewing certificates. By default, a new key is created for every new certificate to mitigate pinning and reduce the scope of key compromise. Key pinning is against industry best practices. This option is not recommended unless you have a specific reason to use it; this may be subject to removal in a future version.
|
||||
|
||||
- **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:
|
||||
|
||||
|
|
@ -149,6 +153,8 @@ Keep in mind that Let's Encrypt may send you emails about your certificate neari
|
|||
|
||||
Multiple `trusted_*` directives may be used to specify multiple CA or leaf certificates. Client certificates which are not listed as one of the leaf certificates or signed by any of the specified CAs will be rejected according to the **mode**.
|
||||
|
||||
- **verifier** <span id="verifier"/> enables the use of a custom client certificate verifier module. These can perform custom client authentication checks, such as ensuring the certificate is not revoked.
|
||||
|
||||
- **issuer** <span id="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](#issuers) that are available. 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.
|
||||
|
|
|
|||
|
|
@ -749,7 +749,7 @@ expression query({'<key>': ['<vals...>']})
|
|||
|
||||
By query string parameters. Should be a sequence of `key=value` pairs. Keys are matched exactly (case-sensitively) but also support `*` to match any value. Values can use placeholders.
|
||||
|
||||
There can be multiple `query` matchers per named matcher, and pairs with the same keys will be OR'ed together.
|
||||
There can be multiple `query` matchers per named matcher, and pairs with the same keys will be OR'ed together. Different keys will be AND'ed together. So, all keys in the matcher must have at least one matching value.
|
||||
|
||||
Illegal query strings (bad syntax, unescaped semicolons, etc.) will fail to parse and thus will not match.
|
||||
|
||||
|
|
@ -781,17 +781,16 @@ Matching both `q` and `sort`, with a [CEL expression](#expression):
|
|||
### remote_ip
|
||||
|
||||
```caddy-d
|
||||
remote_ip [forwarded] <ranges...>
|
||||
remote_ip <ranges...>
|
||||
|
||||
expression remote_ip('<ranges...>')
|
||||
expression remote_ip('forwarded', '<ranges...>')
|
||||
```
|
||||
|
||||
By remote IP address (i.e. the IP address of the immediate peer). Accepts exact IPs or CIDR ranges. IPv6 zones are supported.
|
||||
|
||||
As a shortcut, `private_ranges` can be used to match all private IPv4 and IPv6 ranges. It's the same as specifying all of these ranges: `192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8 fd00::/8 ::1`
|
||||
|
||||
⚠️ The `forwarded` option is deprecated, and will be removed in a future version. Its implementation is insecure. Use the [`client_ip`](#client-ip) matcher instead, which allows for securely matching the real client IP if parsed from an HTTP header. If enabled, then the first IP in the `X-Forwarded-For` request header, if present, will be preferred as the reference IP, rather than the immediate peer's IP, which is the default.
|
||||
if you wish to match the "real IP" of the client, as parsed from HTTP headers, use the [`client_ip`](#client-ip) matcher instead.
|
||||
|
||||
There can be multiple `remote_ip` matchers per named matcher, and their ranges will be merged and OR'ed together.
|
||||
|
||||
|
|
|
|||
|
|
@ -128,6 +128,11 @@ Possible options are (click on each option to jump to its documentation):
|
|||
strict_sni_host [on|insecure_off]
|
||||
}
|
||||
|
||||
# File Systems
|
||||
filesystem <name> <module> {
|
||||
<options...>
|
||||
}
|
||||
|
||||
# PKI Options
|
||||
pki {
|
||||
ca [<id>] {
|
||||
|
|
@ -557,7 +562,7 @@ The ask endpoint should return _as fast as possible_, in a few milliseconds, ide
|
|||
|
||||
</aside>
|
||||
|
||||
- **interval** and **burst** allows `<n>` certificate operations within `<duration>` interval.
|
||||
- **interval** and **burst** allows `<n>` certificate operations within `<duration>` interval. These are deprecated and will be removed in a future version, due to not working as intended.
|
||||
|
||||
```caddy
|
||||
{
|
||||
|
|
@ -971,6 +976,44 @@ This option will automatically be turned on if [client authentication](/docs/cad
|
|||
|
||||
|
||||
|
||||
## File Systems
|
||||
|
||||
The `filesystem` global option allows declaring one or more file systems that can be used for file I/O.
|
||||
|
||||
This could let you connect to a remote filesystem running in the cloud, or a database with a file-like interface, or even to read from files embedded within the Caddy binary.
|
||||
|
||||
File systems are declared with a name to identify them. This means you can connect to more than one file system of the same type, if you need to.
|
||||
|
||||
By default, Caddy doesn't have any file system modules, so you'll need to build Caddy with a plugin for the file system you want to use.
|
||||
|
||||
#### Example
|
||||
|
||||
Using an imaginary `custom` file system module, you could declare two file systems:
|
||||
|
||||
```caddy
|
||||
{
|
||||
filesystem foo custom {
|
||||
...
|
||||
}
|
||||
|
||||
filesystem bar custom {
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
foo.example.com {
|
||||
fs foo
|
||||
file_server
|
||||
}
|
||||
|
||||
foo.example.com {
|
||||
fs bar
|
||||
file_server
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## PKI Options
|
||||
|
||||
The PKI (Public Key Infrastructure) app is the foundation for Caddy's [Local HTTPS](/docs/automatic-https#local-https) and [ACME server](/docs/caddyfile/directives/acme_server) features. The app defines certificate authorities (CAs) which are capable of signing certificates.
|
||||
|
|
|
|||
|
|
@ -190,9 +190,12 @@ Prints the environment as seen by caddy, then exits. Can be useful when debuggin
|
|||
[--listen <addr>]
|
||||
[-d, --domain <example.com>]
|
||||
[-b, --browse]
|
||||
[--reveal-symlinks]
|
||||
[-t, --templates]
|
||||
[--access-log]
|
||||
[-v, --debug]</code></pre>
|
||||
[-v, --debug]
|
||||
[--no-compress]
|
||||
[-p, --precompressed]</code></pre>
|
||||
|
||||
Spins up a simple but production-ready static file server.
|
||||
|
||||
|
|
@ -204,12 +207,18 @@ Spins up a simple but production-ready static file server.
|
|||
|
||||
`--browse` will enable directory listings if a directory without an index file is requested.
|
||||
|
||||
`--reveal-symlinks` will show the target of symbolic links in directory listings, when `--browse` is enabled.
|
||||
|
||||
`--templates` will enable template rendering.
|
||||
|
||||
`--access-log` enables the request/access log.
|
||||
|
||||
`--debug` enables verbose logging.
|
||||
|
||||
`--no-compress` disables compression. By default, Zstandard and Gzip compression are enabled.
|
||||
|
||||
`--precompressed` specifies encoding formats to search for precompressed sidecar files. Can be repeated for multiple formats. See the [file_server directive](/docs/caddyfile/directives/file_server#precompressed) for more information.
|
||||
|
||||
This command disables the admin API, making it easier to run multiple instances on a local development machine.
|
||||
|
||||
|
||||
|
|
@ -234,13 +243,6 @@ Formats or prettifies a Caddyfile, then exits. The result is printed to stdout u
|
|||
`--diff` causes the output to be compared against the input, and lines will be prefixed with `-` and `+` where they differ. Note that unchanges lines are prefixed with two spaces for alignment, and that this is not a valid patch format; it's just meant as a visual tool.
|
||||
|
||||
|
||||
<aside class="advice">
|
||||
|
||||
The `caddy fmt` command [does not support](https://github.com/caddyserver/caddy/issues/5930#issuecomment-1797709061) [heredocs](/docs/caddyfile/concepts#heredocs).
|
||||
|
||||
</aside>
|
||||
|
||||
|
||||
### `caddy hash-password`
|
||||
|
||||
<pre><code class="cmd bash">caddy hash-password
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@ We'll list some of the most common v1 directives here and describe how to conver
|
|||
|
||||
### basicauth
|
||||
|
||||
HTTP Basic Authentication is still configured with the [`basicauth`](/docs/caddyfile/directives/basicauth) directive. However, Caddy 2 configuration does not accept plaintext passwords. You must hash them, which the [`caddy hash-password`](/docs/command-line#caddy-hash-password) can help with.
|
||||
HTTP Basic Authentication is still configured with the [`basic_auth`](/docs/caddyfile/directives/basic_auth) directive. However, Caddy 2 configuration does not accept plaintext passwords. You must hash them, which the [`caddy hash-password`](/docs/command-line#caddy-hash-password) can help with.
|
||||
|
||||
- **v1:**
|
||||
```
|
||||
|
|
@ -127,7 +127,7 @@ basicauth /secret/ Bob hiccup
|
|||
|
||||
- **v2:**
|
||||
```caddy-d
|
||||
basicauth /secret/* {
|
||||
basic_auth /secret/* {
|
||||
Bob JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -906,7 +906,7 @@
|
|||
<div class="feature-row">
|
||||
<h4>Authentication</h4>
|
||||
<div class="benefits">
|
||||
Authenticate users with an extensible authentication module. Extended by auth providers, this handler returns an error if the user cannot be authenticated by any configured providers. HTTP basicauth is included standard, and unlike other servers, passwords are hashed when setting up basicauth (since it's essentially a password database), enhancing security.
|
||||
Authenticate users with an extensible authentication module. Extended by auth providers, this handler returns an error if the user cannot be authenticated by any configured providers. HTTP basic auth is included standard, and unlike other servers, passwords are hashed when setting up basic auth (since it's essentially a password database), enhancing security.
|
||||
</div>
|
||||
<ul class="detail">
|
||||
<li>HTTP Basic authentication</li>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue