diff --git a/Caddyfile b/Caddyfile index 4bb9ed9b..71280931 100644 --- a/Caddyfile +++ b/Caddyfile @@ -22,4 +22,7 @@ rewrite /docs/json/* /docs/json/index.html rewrite /docs/modules/* /docs/modules/index.html rewrite /docs/* /docs/index.html +redir /docs/caddyfile/directives/basicauth /docs/caddyfile/directives/basic_auth 308 +redir /docs/caddyfile/directives/skip_log /docs/caddyfile/directives/log_skip 308 + reverse_proxy /api/* localhost:4444 diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index e2827009..e3fbf921 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -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`). - - ## Global options @@ -333,8 +327,8 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd | `{cookie.*}` | `{http.request.cookie.*}` | | `{client_ip}` | `{http.vars.client_ip}` | | `{dir}` | `{http.request.uri.path.dir}` | -| `{err.*}` | `{http.error.*}` | -| `{file_match.*}` | `{http.matchers.file.*}` | +| `{err.*}` | `{http.error.*}` | +| `{file_match.*}` | `{http.matchers.file.*}` | | `{file.base}` | `{http.request.uri.path.file.base}` | | `{file.ext}` | `{http.request.uri.path.file.ext}` | | `{file}` | `{http.request.uri.path.file}` | @@ -348,11 +342,11 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd | `{port}` | `{http.request.port}` | | `{query.*}` | `{http.request.uri.query.*}` | | `{query}` | `{http.request.uri.query}` | -| `{re.*.*}` | `{http.regexp.*.*}` | +| `{re.*}` | `{http.regexp.*}` | | `{remote_host}` | `{http.request.remote.host}` | | `{remote_port}` | `{http.request.remote.port}` | | `{remote}` | `{http.request.remote}` | -| `{rp.*}` | `{http.reverse_proxy.*}` | +| `{rp.*}` | `{http.reverse_proxy.*}` | | `{scheme}` | `{http.request.scheme}` | | `{tls_cipher}` | `{http.request.tls.cipher_suite}` | | `{tls_client_certificate_der_base64}` | `{http.request.tls.client.certificate_der_base64}` | diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 43db14f7..35336102 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -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 @@ -56,6 +57,8 @@ Directive | Description **[import](/docs/caddyfile/directives/import)** | Include snippets or files **[invoke](/docs/caddyfile/directives/invoke)** | Invoke a named route **[log](/docs/caddyfile/directives/log)** | Enables access/request logging +**[log_append](/docs/caddyfile/directives/log_append)** | Append a field to the access log +**[log_skip](/docs/caddyfile/directives/log_skip)** | Skip access logging for matched requests **[map](/docs/caddyfile/directives/map)** | Maps an input value to one or more outputs **[method](/docs/caddyfile/directives/method)** | Change the HTTP method internally **[metrics](/docs/caddyfile/directives/metrics)** | Configures the Prometheus metrics exposition endpoint @@ -69,7 +72,6 @@ Directive | Description **[rewrite](/docs/caddyfile/directives/rewrite)** | Rewrites the request internally **[root](/docs/caddyfile/directives/root)** | Set the path to the site root **[route](/docs/caddyfile/directives/route)** | A group of directives treated literally as single unit -**[skip_log](/docs/caddyfile/directives/skip_log)** | Skip access logging for matched requests **[templates](/docs/caddyfile/directives/templates)** | Execute templates on the response **[tls](/docs/caddyfile/directives/tls)** | Customize TLS settings **[tracing](/docs/caddyfile/directives/tracing)** | Integration with OpenTelemetry tracing @@ -120,8 +122,10 @@ tracing map vars +fs root -skip_log +log_append +log_skip header copy_response_headers # only in reverse_proxy's handle_response block @@ -136,7 +140,7 @@ uri try_files # middleware handlers; some wrap responses -basicauth +basic_auth forward_auth request_header encode diff --git a/src/docs/markdown/caddyfile/directives/acme_server.md b/src/docs/markdown/caddyfile/directives/acme_server.md index d30bbc8c..a074ab8e 100644 --- a/src/docs/markdown/caddyfile/directives/acme_server.md +++ b/src/docs/markdown/caddyfile/directives/acme_server.md @@ -18,9 +18,19 @@ Using ACME server defaults, ACME clients should simply be configured to use `htt ```caddy-d acme_server [] { - ca - lifetime - resolvers + ca + lifetime + resolvers + challenges + allow_wildcard_names + allow { + domains + ip_ranges + } + deny { + domains + ip_ranges + } } ``` @@ -30,6 +40,15 @@ acme_server [] { - **resolvers** are the addresses of DNS resolvers to use when looking up the TXT records for solving ACME DNS challenges. Accepts [network addresses](/docs/conventions#network-addresses) defaulting to UDP and port 53 unless specified. If the host is an IP address, it will be dialed directly to resolve the upstream server. If the hot is not an IP address, the addresses are resolved using the [name resolution convention](https://golang.org/pkg/net/#hdr-Name_Resolution) of the Go standard library. If multiple resolvers are specified, then one is chosen at random. +- **challenges** sets the enabled challenge types. If not set or the directive is used without values, then all challenge types are enabled. Accepted values are: http-01, tls-alpn-01, dns-01. + +- **allow_wildcard_names** enables issuing of certificates with wildcard SAN (Subject Alternative Name) + +- **allow**, **deny** configure the operational policy of the `acme_server`. The policy evaluation follows the criteria described by Step-CA [here](https://smallstep.com/docs/step-ca/policies/#policy-evaluation). + + - **domains** sets the subject domain names to be allowed or denied per the policy evaluation criteria. + + - **ip_ranges** sets the subject IP ranges to be allowed or denied per the policy evaluation criteria. ## Examples diff --git a/src/docs/markdown/caddyfile/directives/basicauth.md b/src/docs/markdown/caddyfile/directives/basic_auth.md similarity index 82% rename from src/docs/markdown/caddyfile/directives/basicauth.md rename to src/docs/markdown/caddyfile/directives/basic_auth.md index 43c3f7db..3ac0b7a0 100644 --- a/src/docs/markdown/caddyfile/directives/basicauth.md +++ b/src/docs/markdown/caddyfile/directives/basic_auth.md @@ -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,12 +14,14 @@ 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 [] [ []] { - [] +basic_auth [] [ []] { + ... } ``` @@ -32,8 +34,6 @@ basicauth [] [ []] { - **<hashed_password>** is the password hash. -- **<salt_base64>** is the base-64 encoding of the password salt, if an external salt is required. This was only needed for the `scrypt` algorithm which is now deprecated. Subject to removal. - ## Examples @@ -41,7 +41,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 +55,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 } diff --git a/src/docs/markdown/caddyfile/directives/encode.md b/src/docs/markdown/caddyfile/directives/encode.md index 3f417f67..410bd86c 100644 --- a/src/docs/markdown/caddyfile/directives/encode.md +++ b/src/docs/markdown/caddyfile/directives/encode.md @@ -45,13 +45,39 @@ encode [] { ```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/* } ``` diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index 31dc4b78..6434e3e3 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -33,7 +33,9 @@ file_server [] [browse] { root hide index - browse [] + browse [] { + reveal_symlinks + } precompressed status disable_canonical_uris @@ -43,6 +45,8 @@ file_server [] [browse] { - **fs** specifies an alternate (perhaps virtual) file system to use. Any Caddy module in the `caddy.fs` namespace can be used here. Any root path/prefix will still apply to alternate file system modules. By default, the local disk is used. + [`xcaddy`](/docs/build#xcaddy) v0.4.0 introduces the [`--embed` flag](https://github.com/caddyserver/xcaddy#custom-builds) to embed a filesystem tree into the custom Caddy build, and registers an `fs` module named `embedded` which allows your static site to be distributed as a Caddy executable. + - **root** sets the path to the site root. It's similar to the [`root`](root) directive except it applies to this file server instance only and overrides any other site root that may have been defined. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this handler. For other directives (like [`try_files`](try_files) or [`templates`](templates)) to know the same site root, use the [`root`](root) directive instead. - **hide** is a list of files or folders to hide; if requested, the file server will pretend they do not exist. Accepts placeholders and glob patterns. Note that these are _file system_ paths, NOT request paths. In other words, relative paths use the current working directory as a base, NOT the site root; and all paths are transformed to their absolute form before comparisons (if possible). Specifying a file name or pattern without a path separator will hide all files with a matching name regardless of its location; otherwise, a path prefix match will be attempted, and then a globular match. Since this is a Caddyfile config, the active configuration file(s) will be added by default. @@ -53,6 +57,8 @@ file_server [] [browse] { - **** 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 ![external link](/old/resources/images/external-link.svg)](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** 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** 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. diff --git a/src/docs/markdown/caddyfile/directives/fs.md b/src/docs/markdown/caddyfile/directives/fs.md new file mode 100644 index 00000000..4d921875 --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/fs.md @@ -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 [] +``` + +## 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 +} +``` diff --git a/src/docs/markdown/caddyfile/directives/handle_errors.md b/src/docs/markdown/caddyfile/directives/handle_errors.md index 3f110f67..699b162b 100644 --- a/src/docs/markdown/caddyfile/directives/handle_errors.md +++ b/src/docs/markdown/caddyfile/directives/handle_errors.md @@ -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 [] { } ``` +- **** 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. + - **** 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 { diff --git a/src/docs/markdown/caddyfile/directives/log.md b/src/docs/markdown/caddyfile/directives/log.md index b0f4fed4..a560fd4a 100644 --- a/src/docs/markdown/caddyfile/directives/log.md +++ b/src/docs/markdown/caddyfile/directives/log.md @@ -32,7 +32,9 @@ To configure Caddy's runtime logs, see the [`log` global option](/docs/caddyfile The `log` directive applies to the hostnames of the site block it appears in, unless overridden with the `hostnames` subdirective. -When configured, by default all requests to the site will be logged. To conditionally skip some requests from logging, use the [`skip_log` directive](skip_log). +When configured, by default all requests to the site will be logged. To conditionally skip some requests from logging, use the [`log_skip` directive](log_skip). + +To add custom fields to the log entries, use the [`log_append` directive](log_append). - [Syntax](#syntax) @@ -54,6 +56,7 @@ When configured, by default all requests to the site will be logged. To conditio - [cookie](#cookie) - [regexp](#regexp) - [hash](#hash) + - [append](#append) - [Examples](#examples) Since Caddy v2.5, by default, headers with potentially sensitive information (`Cookie`, `Set-Cookie`, `Authorization` and `Proxy-Authorization`) will be logged with empty values. This behaviour can be disabled with the [`log_credentials`](/docs/caddyfile/options#log-credentials) global server option. @@ -281,14 +284,15 @@ format json #### filter -Wraps another encoder module, allowing per-field filtering. +Allows per-field filtering. ```caddy-d format filter { - wrap ... fields { ... } + ... + wrap ... } ``` @@ -296,6 +300,11 @@ 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 +346,7 @@ Most commonly, the fields to filter would be: - `request>headers>X-Forwarded-For` if behind a reverse proxy ```caddy-d - ip_mask { + ip_mask [ []] { ipv4 ipv6 } @@ -411,6 +420,26 @@ Useful to obscure the value if it's sensitive, while being able to notice whethe hash ``` +#### append + +Appends field(s) to all log entries. + +```caddy-d +format append { + fields { + + } + + wrap ... +} +``` + +It is most useful for adding information about the Caddy instance that is producing the log entries, possibly via an environment variable. The field values may be global placeholders (e.g. `{env.*}`), but _not_ per-request placeholders due to logs being written outside of the HTTP request context. + +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. + +The `fields` block can be omitted and the fields can be specified directly within the `append` block. + ## Examples @@ -458,10 +487,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 +500,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,12 +518,23 @@ 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 + } + } +} +``` + + +To append a server ID from an environment variable to all log entries, and chain it with a `filter` to delete a header: + +```caddy +example.com { + log { + format append { + server_id {env.SERVER_ID} + wrap filter { + request>headers>Cookie delete } } } diff --git a/src/docs/markdown/caddyfile/directives/log_append.md b/src/docs/markdown/caddyfile/directives/log_append.md new file mode 100644 index 00000000..a9968947 --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/log_append.md @@ -0,0 +1,39 @@ +--- +title: log_append (Caddyfile directive) +--- + +# log_append + +Appends a field to the access log for the current request. + +This should be used alongside the [`log` directive](log) which is required to enable access logging in the first place. + +The value may be a static string, or a [placeholder](/docs/caddyfile/concepts#placeholders) which will be replaced with the value of the placeholder at the time of the request. + + +## Syntax + +```caddy-d +log_append [] +``` + + +## Examples + +Display in the logs the area of the site that the request is being served from, either `static` or `dynamic`: + +```caddy +example.com { + log + + handle /static* { + log_append area "static" + respond "Static response!" + } + + handle { + log_append area "dynamic" + reverse_proxy localhost:9000 + } +} +``` diff --git a/src/docs/markdown/caddyfile/directives/skip_log.md b/src/docs/markdown/caddyfile/directives/log_skip.md similarity index 65% rename from src/docs/markdown/caddyfile/directives/skip_log.md rename to src/docs/markdown/caddyfile/directives/log_skip.md index 291f90ab..c08f0089 100644 --- a/src/docs/markdown/caddyfile/directives/skip_log.md +++ b/src/docs/markdown/caddyfile/directives/log_skip.md @@ -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. +This should be used alongside the [`log` directive](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 [] +log_skip [] ``` @@ -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 } ``` diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 3e1c911a..1fdc564c 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -509,8 +509,9 @@ transport http { tls tls_client_auth | tls_insecure_skip_verify + tls_curves tls_timeout - tls_trusted_ca_certs + tls_trust_pool tls_server_name tls_renegotiation tls_except_ports @@ -552,9 +553,11 @@ transport http { - **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** 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** is the maximum [duration](/docs/conventions#durations) to wait for the TLS handshake to complete. Default: No timeout. -- **tls_trusted_ca_certs** is a list of PEM files that specify CA public keys to trust when connecting to the backend. +- **tls_trust_pool** configures the source of trusted certificate authorities similar to the [`trust_pool` sub-directive](/docs/caddyfile/directives/tls#trust_pool) described on the `tls` directive documentation. The list of trust pool sources available in standard Caddy installation is available [here](/docs/caddyfile/directives/tls#trust-pool-providers). - **tls_server_name** sets the server name used when verifying the certificate received in the TLS handshake. By default, this will use the upstream address' host part. diff --git a/src/docs/markdown/caddyfile/directives/rewrite.md b/src/docs/markdown/caddyfile/directives/rewrite.md index c1285e52..86d13389 100644 --- a/src/docs/markdown/caddyfile/directives/rewrite.md +++ b/src/docs/markdown/caddyfile/directives/rewrite.md @@ -23,6 +23,8 @@ rewrite [] - **<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, the `` 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 { } ``` + + Prefixing all requests with `/api`, preserving the rest of the URI, then reverse proxying to an app: ```caddy diff --git a/src/docs/markdown/caddyfile/directives/root.md b/src/docs/markdown/caddyfile/directives/root.md index d2c3b018..0e19ba79 100644 --- a/src/docs/markdown/caddyfile/directives/root.md +++ b/src/docs/markdown/caddyfile/directives/root.md @@ -19,7 +19,7 @@ root [] - **<path>** is the path to use for the site root. -Note that the `` 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, the `` 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 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 ``` diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index ad27477a..c1c122d8 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -38,12 +38,13 @@ tls [internal|] | [ ] { resolvers eab on_demand + reuse_private_keys client_auth { mode [request|require|verify_if_given|require_and_verify] - trusted_ca_cert - trusted_ca_cert_file + trust_pool trusted_leaf_cert trusted_leaf_cert_file + verifier } issuer [] get_certificate [] @@ -127,6 +128,8 @@ Keep in mind that Let's Encrypt may send you emails about your certificate neari - **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** 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** enables and configures TLS client authentication: - **mode** is the mode for authenticating the client. Allowed values are: @@ -139,9 +142,9 @@ Keep in mind that Let's Encrypt may send you emails about your certificate neari Default: `require_and_verify` if any `trusted_ca_cert` or `trusted_leaf_cert` are provided; otherwise, `require`. - - **trusted_ca_cert** is a base64 DER-encoded CA certificate against which to validate client certificates. - - - **trusted_ca_cert_file** is a path to a PEM CA certificate file against which to validate client certificates. + - **trust_pool** configures the source of certificate authorities (CA) providing certificates against which to validate client certificates. + + The certificate authority used providing the pool of trusted certificates and the configuration within the segment depends on the configured source of trust pool module. The standard modules available in Caddy are [listed below](#trust-pool-providers). The full list of modules, including 3rd-party, is listed in the [`trust_pool` JSON documentation](/docs/json/apps/http/servers/tls_connection_policies/client_authentication/#trust_pool). - **trusted_leaf_cert** is a base64 DER-encoded client leaf certificate to accept. @@ -149,6 +152,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** 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** 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. @@ -159,6 +164,112 @@ Keep in mind that Let's Encrypt may send you emails about your certificate neari - **insecure_secrets_log** enables logging of TLS secrets to a file. This is also known as `SSLKEYLOGFILE`. Uses NSS key log format, which can then be parsed by Wireshark or other tools. ⚠️ **Security Warning:** This is insecure as it allows other programs or tools to decrypt TLS connections, and therefore completely compromises security. However, this capability can be useful for debugging and troubleshooting. +### Trust Pool Providers + +These are the standard trust pool providers that can be used in the `trust_pool` subdirective: + +#### inline + +The `inline` module parses the trusted root certificates as listed in the Caddyfile directly in base64 DER-encoded format. The `trust_der` directive may be repeated multiple times. + +```caddy-d +trust_pool inline { + trust_der +} +``` + +- **trust_der** is a base64 DER-encoded CA certificate against which to validate client certificates. + +#### file + +The `file` module reads the trusted root certificates from PEM files from disk. The `pem_file` directive can accept multiple file paths on the same line and may be repeated multiple times. + +```caddy-d +... file [...] { + pem_file ... +} +``` + +- **pem_file** is a path to a PEM CA certificate file against which to validate client certificates. + +#### pki_root + +The `pki_root` module obtains the _root_ and trusts certificates from the certificate authority defined in the [PKI app](/docs/caddyfile/options#pki-options). The `authority` directive can accept multiple authorities at the same time and may be repeated multiple times. + +```caddy-d +... pki_root [...] { + authority ... +} +``` + +- **authority** is the name of the certificate authority configured in the PKI app. + +#### pki_intermediate + +The `pki_intermediate` module obtains the _intermediate_ and trusts certificates from the certificate authority defined in the [PKI app](/docs/caddyfile/options#pki-options). The `authority` directive can accept multiple authorities at the same time and may be repeated multiple times. + +```caddy-d +... pki_intermediate [...] { + authority ... +} +``` + +- **authority** is the name of the certificate authority configured in the PKI app. + +#### storage + +The `storage` module extracts the trusted certificates root from Caddy [storage](/docs/caddyfile/options#storage). The `authority` directive can accept multiple authorities at the same time and may be repeated multiple times. + +```caddy-d +... storage [...] { + storage + keys ... +} +``` + +- **storage** is an optional storage module to use. If not specified, the default storage module will be used. If specified, it may be specified only once. + +- **keys** is the list of storage keys at which the PEM files of the certificates are stored. The directive accepts multiple values on the same line and may be specified multiple times. + +#### http + +The `http` module obtains the trusted certificates from HTTP endpoints. The `endpoints` directive can accept multiple endpoints at the same time and may be repeated multiple times. + +```caddy-d +... http [] { + endpoints + tls +} +``` + +- **endpoints** is the list of HTTP endpoints from which to obtain certificates. The directive accepts multiple values on the same line and may be specified multiple times. + +- **tls** is an optional TLS configuration to use when connecting to the HTTP endpoint. The segment parsing is defined in the [following section](#tls-1). + +##### TLS + +```caddy-d +... { + ca + insecure_skip_verify + handshake_timeout + server_name + renegotiation +} +``` + +- **ca** is an optional directive to define the provider of trust pool. The configuration follows the same behavior of [`trust_pool`](#trust_pool). If specified, it may be specified only once. + +- **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._ The verification is done against either the certificate authorities trusted by the system or as determined by the [`ca`](#ca) directive. + +- **handshake_timeout** is the maximum [duration](/docs/conventions#durations) to wait for the TLS handshake to complete. Default: No timeout.. + +- **server_name** sets the server name used when verifying the certificate received in the TLS handshake. By default, this will use the upstream address' host part. + +- **renegotiation** sets the TLS renegotiation level. TLS renegotiation is the act of performing subsequent handshakes after the first. The level may be one of: + - `never` (the default) disables renegotiation. + - `once` allows a remote server to request renegotiation once per connection. + - `freely` allows a remote server to repeatedly request renegotiation. ### Issuers diff --git a/src/docs/markdown/caddyfile/directives/vars.md b/src/docs/markdown/caddyfile/directives/vars.md index 23a24a43..36f8af97 100644 --- a/src/docs/markdown/caddyfile/directives/vars.md +++ b/src/docs/markdown/caddyfile/directives/vars.md @@ -8,6 +8,9 @@ Sets one or more variables to a particular value, to be used later in the reques The primary way to access variables is with placeholders, which have the form `{vars.variable_name}`, or with the [`vars`](/docs/caddyfile/matchers#vars) and [`vars_regexp`](/docs/caddyfile/matchers#vars_regexp) request matchers. +As a special case, it's possible to override the variable named `http.auth.user.id`, which is stored in the replacer, to update the `user_id` field in access logs. + + ## Syntax ```caddy-d diff --git a/src/docs/markdown/caddyfile/matchers.md b/src/docs/markdown/caddyfile/matchers.md index e4ec61ec..344822e4 100644 --- a/src/docs/markdown/caddyfile/matchers.md +++ b/src/docs/markdown/caddyfile/matchers.md @@ -456,20 +456,37 @@ expression header_regexp('', '', '') expression header_regexp('', '') ``` -Like [`header`](#header), but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on. +Like [`header`](#header), but supports regular expressions. The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax). +As of v2.8.0, if `name` is _not_ provided, the name will be taken from the named matcher's name. For example a named matcher `@foo` will cause this matcher to be named `foo`. The main advantage of specifying a name is if more than one regexp matcher is used in the same named matcher. + +Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) in directives after matching: +- `{re..}` where: + - `` is the name of the regular expression, + - `` is either the name or number of the capture group in the expression. + +- `{re.}` without a name, is also populated for convenience. The caveat is that if multiple regexp matchers are used in sequence, then the placeholder values will be overwritten by the next matcher. + +Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on. So `{re.foo.1}` or `{re.1}` will both hold the value of the first capture group. + Only one regular expression is supported per header field. Multiple different fields will be AND'ed. #### Example: -Match requests where the Cookie header contains `login_` followed by a hex string, with a capture group that can be accessed with `{re.login.1}`. +Match requests where the Cookie header contains `login_` followed by a hex string, with a capture group that can be accessed with `{re.login.1}` or `{re.1}`. ```caddy-d @login header_regexp login Cookie login_([a-f0-9]+) ``` +This can be simplified by omitting the name, which will be inferred from the named matcher: + +```caddy-d +@login header_regexp Cookie login_([a-f0-9]+) +``` + Or the same, using a [CEL expression](#expression): ```caddy-d @@ -684,26 +701,41 @@ expression path_regexp('', '') expression path_regexp('') ``` -Like [`path`](#path), but supports regular expressions. Write the pattern on the URI-decoded/unescaped form of the path. +Like [`path`](#path), but supports regular expressions. Runs against the URI-decoded/unescaped path. The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax). -Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on. +As of v2.8.0, if `name` is _not_ provided, the name will be taken from the named matcher's name. For example a named matcher `@foo` will cause this matcher to be named `foo`. The main advantage of specifying a name is if more than one regexp matcher is used in the same named matcher. + +Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) in directives after matching: +- `{re..}` where: + - `` is the name of the regular expression, + - `` is either the name or number of the capture group in the expression. + +- `{re.}` without a name, is also populated for convenience. The caveat is that if multiple regexp matchers are used in sequence, then the placeholder values will be overwritten by the next matcher. + +Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on. So `{re.foo.1}` or `{re.1}` will both hold the value of the first capture group. There can only be one `path_regexp` pattern per named matcher. #### Example: -Match requests where the path ends a 6 character hex string followed by `.css` or `.js` as the file extension, with capture groups that can be accessed with `{re.static.1}` and `{re.static.2}` for each part enclosed in `( )`, respectively: +Match requests where the path ends a 6 character hex string followed by `.css` or `.js` as the file extension, with capture groups (parts enclosed in `( )`), that can be accessed with `{re.static.1}` and `{re.static.2}` (or `{re.1}` and `{re.2}`), respectively: ```caddy-d @static path_regexp static \.([a-f0-9]{6})\.(css|js)$ ``` +This can be simplified by omitting the name, which will be inferred from the named matcher: + +```caddy-d +@static path_regexp \.([a-f0-9]{6})\.(css|js)$ +``` + Or the same, using a [CEL expression](#expression), also validating that the [`file`](#file) exists on disk: ```caddy-d -@static `path_regexp('static', '\.([a-f0-9]{6})\.(css|js)$') && file()` +@static `path_regexp('\.([a-f0-9]{6})\.(css|js)$') && file()` ``` @@ -749,7 +781,7 @@ expression query({'': ['']}) 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 +813,16 @@ Matching both `q` and `sort`, with a [CEL expression](#expression): ### remote_ip ```caddy-d -remote_ip [forwarded] +remote_ip expression remote_ip('') -expression remote_ip('forwarded', '') ``` 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. @@ -852,16 +883,33 @@ vars {magic_number} 3 5 vars_regexp [] ``` -Like [`vars`](#vars), but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on. +Like [`vars`](#vars), but supports regular expressions. The regular expression language used is RE2, included in Go. See the [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) and the [Go regexp syntax overview](https://pkg.go.dev/regexp/syntax). +As of v2.8.0, if `name` is _not_ provided, the name will be taken from the named matcher's name. For example a named matcher `@foo` will cause this matcher to be named `foo`. The main advantage of specifying a name is if more than one regexp matcher is used in the same named matcher. + +Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) in directives after matching: +- `{re..}` where: + - `` is the name of the regular expression, + - `` is either the name or number of the capture group in the expression. + +- `{re.}` without a name, is also populated for convenience. The caveat is that if multiple regexp matchers are used in sequence, then the placeholder values will be overwritten by the next matcher. + +Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on. So `{re.foo.1}` or `{re.1}` will both hold the value of the first capture group. + There can only be one `vars_regexp` matcher per named matcher. #### Example: -Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for a value starting with `4`, capturing the value in a capture group: +Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for a value starting with `4`, capturing the value in a capture group that can be accessed with `{re.magic.1}` or `{re.1}`: + +```caddy-d +@magic vars_regexp magic {magic_number} ^(4.*) +``` + +This can be simplified by omitting the name, which will be inferred from the named matcher: ```caddy-d -vars_regexp magic {magic_number} ^(4.*) +@magic vars_regexp {magic_number} ^(4.*) ``` diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 75aef22a..cf588744 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -118,6 +118,7 @@ Possible options are (click on each option to jump to its documentation): write idle } + keepalive_interval trusted_proxies ... client_ip_headers metrics @@ -128,6 +129,11 @@ Possible options are (click on each option to jump to its documentation): strict_sni_host [on|insecure_off] } + # File Systems + filesystem { + + } + # PKI Options pki { ca [] { @@ -557,7 +563,7 @@ The ask endpoint should return _as fast as possible_, in a few milliseconds, ide -- **interval** and **burst** allows `` certificate operations within `` interval. +- **interval** and **burst** allows `` certificate operations within `` interval. These are deprecated and will be removed in a future version, due to not working as intended. ```caddy { @@ -818,11 +824,25 @@ Also included is the [`proxy_protocol`](/docs/json/apps/http/servers/listener_wr ``` +##### `keepalive_interval` + +The interval at which TCP keepalive packets are sent to keep the connection alive at the TCP layer when no other data is being transmitted. Defaults to `15s`. + +```caddy +{ + servers { + keepalive_interval 30s + } +} +``` + + + ##### `trusted_proxies` Allows configuring IP ranges (CIDRs) of proxy servers from which requests should be trusted. By default, no proxies are trusted. -Enabling this causes trusted requests to have the _real_ client IP parsed from HTTP headers (by default, `X-Forwarded-For`; see [`client_ip_headers`](#client-ip-headers) to configure other headers). If trusted, the client IP is added to [access logs](/docs/caddyfile/directives/log), is available as a `{client_ip}` [placeholder](/docs/caddyfile/concepts#placeholders), and allows the use of the [`client_ip` matcher](/docs/caddyfile/matchers#client-ip). If the request is not from a trusted proxy, then the client IP is set to the remote IP address of the direct incoming connection. +Enabling this causes trusted requests to have the _real_ client IP parsed from HTTP headers (by default, `X-Forwarded-For`; see [`client_ip_headers`](#client-ip-headers) to configure other headers). If trusted, the client IP is added to [access logs](/docs/caddyfile/directives/log), is available as a `{client_ip}` [placeholder](/docs/caddyfile/concepts#placeholders), and allows the use of the [`client_ip` matcher](/docs/caddyfile/matchers#client-ip). If the request is not from a trusted proxy, then the client IP is set to the remote IP address of the direct incoming connection. By default, the IPs in headers are parsed left-to-right. See [`trusted_proxies_strict`](#trusted-proxies-strict) to alter this behaviour. Some matchers or handlers may use the trust status of the request to make decisions. For example, if trusted, the [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy#defaults) handler will proxy and augment the sensitive `X-Forwarded-*` request headers. @@ -851,6 +871,27 @@ Here's a complete example, trusting an example IPv4 range and an IPv6 range: } ``` +##### `trusted_proxies_strict` + +When [`trusted_proxies`](#trusted-proxies) is enabled, the IPs in the headers (configured by [`client_ip_headers`](#client-ip-headers)) are parsed from left-to-right by default. The first untrusted IP address found becomes the real client address. Since v2.8, you can opt-in to right-to-left parsing of these headers with `trusted_proxies_strict`. By default, this option is disabled for backwards compatibility. + +Upstream proxies such as HAProxy, CloudFlare, AWS ALB, CloudFront, etc. will append each new connecting remote address to the right of `X-Forwarded-For`. It is recommended to enable `trusted_proxies_strict` when working with these, as the left-most IP address may be spoofed by the client. + +```caddy +{ + servers { + trusted_proxies static private_ranges + trusted_proxies_strict + } +} +``` + + + ##### `client_ip_headers` @@ -971,6 +1012,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. diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 69f0cac2..90196d12 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -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] + [-v, --debug] + [--no-compress] + [-p, --precompressed] 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,19 +243,11 @@ 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. - - - ### `caddy hash-password` 
caddy hash-password
 	[-p, --plaintext <password>]
-	[-a, --algorithm <name>]
-	[-s, --salt <string>]
+ [-a, --algorithm <name>] Convenient way to hash a plaintext password. The resulting hash is written to stdout as a format usable directly in your Caddy config. @@ -254,10 +255,6 @@ Convenient way to hash a plaintext password. The resulting hash is written to st `--algorithm` may be `bcrypt` or any installed hash algorithm. Default is `bcrypt`. -`--salt` is used only if the algorithm requires an external salt (like `scrypt`). - -Note that `scrypt` is deprecated. Please use `bcrypt` instead. - diff --git a/src/docs/markdown/v2-upgrade.md b/src/docs/markdown/v2-upgrade.md index 22440f73..fd686ccc 100644 --- a/src/docs/markdown/v2-upgrade.md +++ b/src/docs/markdown/v2-upgrade.md @@ -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 } ``` diff --git a/src/features.html b/src/features.html index a9d4c25c..6315313c 100644 --- a/src/features.html +++ b/src/features.html @@ -906,7 +906,7 @@

Authelia

Authentication

- 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.
  • HTTP Basic authentication