Updated for v2.8.0 (#389)

Co-authored-by: Mohammed Al Sahaf <[email protected]> Co-authored-by: Francis Lavoie <[email protected]> Co-authored-by: Nebez Briefkani <[email protected]> Co-authored-by: Mohammed Al Sahaf <[email protected]>
caddyserver · May 29, 2024 · ca9ce7b · ca9ce7b
1 parent 1a82466
commit ca9ce7b
Show file tree

Hide file tree

Showing 22 changed files with 549 additions and 107 deletions.
diff --git 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
@@ -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
 
@@ -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
@@ -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,19 +43,22 @@ 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
 **[header](/docs/caddyfile/directives/header)** | Sets or removes response headers
 **[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
@@ -18,9 +18,19 @@ Using ACME server defaults, ACME clients should simply be configured to use `htt
 
 ```caddy-d
 acme_server [<matcher>] {
-	ca        <id>
-	lifetime  <duration>
-	resolvers <resolvers...>
+	ca         <id>
+	lifetime   <duration>
+	resolvers  <resolvers...>
+	challenges <challenges...>
+	allow_wildcard_names
+	allow {
+		domains <domains...>
+		ip_ranges <addresses...>
+	}
+	deny {
+		domains <domains...>
+		ip_ranges <addresses...>
+	}
 }
 ```
 
@@ -30,6 +40,15 @@ acme_server [<matcher>] {
 
 - **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/...arkdown/caddyfile/directives/basicauth.md → ...rkdown/caddyfile/directives/basic_auth.md b/...arkdown/caddyfile/directives/basicauth.md → ...rkdown/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 [<matcher>] [<hash_algorithm> [<realm>]] {
-	<username> <hashed_password> [<salt_base64>]
+basic_auth [<matcher>] [<hash_algorithm> [<realm>]] {
+	<username> <hashed_password>
 	...
 }
 ```
@@ -32,16 +34,14 @@ basicauth [<matcher>] [<hash_algorithm> [<realm>]] {
 
 - **&lt;hashed_password&gt;** is the password hash.
 
-- **&lt;salt_base64&gt;** 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
 
 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
@@ -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/*
   }
   ```
 

diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md
@@ -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
@@ -43,6 +45,8 @@ file_server [<matcher>] [browse] {
 
 - **fs** <span id="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** <span id="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** <span id="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 [<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 ![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** <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.

diff --git a/src/docs/markdown/caddyfile/directives/fs.md 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 [<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
+}
+```