Caddyfile Directives

Directives are functional keywords that appear within site 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
Directive Order
Sorting Algorithm

The following directives come standard with Caddy, and can be used in the HTTP Caddyfile:

Directive	Description
abort	Aborts the HTTP request
acme_server	An embedded ACME server
basic_auth	Enforces HTTP Basic Authentication
bind	Customize the server's socket address
encode	Encodes (usually compresses) responses
error	Trigger an error
file_server	Serve files from disk
forward_auth	Delegate authentication to an external service
fs	Set the file system to use for file I/O
handle	A mutually-exclusive group of directives
handle_errors	Defines routes for handling errors
handle_path	Like handle, but strips path prefix
header	Sets or removes response headers
import	Include snippets or files
intercept	Intercept responses written by other handlers
invoke	Invoke a named route
log	Enables access/request logging
log_append	Append a field to the access log
log_skip	Skip access logging for matched requests
log_name	Override the logger name(s) to write to
map	Maps an input value to one or more outputs
method	Change the HTTP method internally
metrics	Configures the Prometheus metrics exposition endpoint
php_fastcgi	Serve PHP sites over FastCGI
push	Push content to the client using HTTP/2 server push
redir	Issues an HTTP redirect to the client
request_body	Manipulates request body
request_header	Manipulates request headers
respond	Writes a hard-coded response to the client
reverse_proxy	A powerful and extensible reverse proxy
rewrite	Rewrites the request internally
root	Set the path to the site root
route	A group of directives treated literally as single unit
templates	Execute templates on the response
timeouts	Set idle read and write timeouts
tls	Customize TLS settings
tracing	Integration with OpenTelemetry tracing
try_files	Rewrite that depends on file existence
uri	Manipulate the URI
vars	Set arbitrary variables

Syntax

The syntax of each directive will look something like this:

directive [<matcher>] <args...> {
	subdirective [<args...>]
}

The <carets> indicate tokens to be substituted by actual values.

The[brackets] indicate optional parameters.

The ellipses ... indicates a continuation, i.e. one or more parameters or lines.

Subdirectives are typically optional unless documented otherwise, even though they don't appear in [brackets].

Matchers

Most—but not all—directives accept matcher tokens, which let you filter requests. Matcher tokens are usually optional. Directives support matchers if you see this in a directive's syntax:

[<matcher>]

Because matcher tokens all work the same, the various possibilities for the matcher token will not be described on every page, to reduce duplication. Instead, refer to the matcher documentation for a detailed explanation of the syntax.

Directive order

Many directives manipulate the HTTP handler chain. The order in which those directives are evaluated matters, so a default ordering is hard-coded into Caddy.

You can override/customize this ordering by using the order global option or the route directive.

tracing

map
vars
fs
root
log_append
log_skip
log_name

header
copy_response_headers # only in reverse_proxy's handle_response block
request_body
timeouts

redir

# incoming request manipulation
method
rewrite
uri
try_files

# middleware handlers; some wrap responses
basic_auth
forward_auth
request_header
encode
push
intercept
templates

# special routing & dispatching directives
invoke
handle
handle_path
route

# handlers that typically respond to requests
abort
error
copy_response # only in reverse_proxy's handle_response block
respond
metrics
reverse_proxy
php_fastcgi
file_server
acme_server

Sorting algorithm

For ease of use, the Caddyfile adapter sorts directives according to the following rules:

Differently named directives are sorted by their position in the default order. The default order can be overridden with the order global option. Directives from plugins do not have an order, so the order global option or the route directive should be used to set one.
Same-named directives are sorted according to their matchers.
- A directive with a single path matcher value, such as /foo*, is sorted by specificity relative to other directives with a single path, from most specific to least specific. This also applies to a named matcher with a path matcher that has only one path.
  
  In general, this is performed by sorting by the length of the path, ignoring a trailing *. If the paths of the two matchers are otherwise the same, the matcher with no * is considered more specific and sorted higher. Paths of the same length are sorted alphabetically.
  
  For example:
  - /foobar is more specific than /foo
  - /foo is more specific than /foo*
  - /foo/* is more specific than /foo*
- A directive with any other matcher, such as a named matcher or a path matcher with multiple values, keeps the order it appears in the Caddyfile. Directives with a single path are not sorted past it, so they are only sorted among the other single-path directives next to them.
  
  For example, these directives are not reordered at all, because the @api named matcher separates them:
```
respond /a*  "1"
respond @api "2"
respond /a/b "3"
respond /a   "4"
```
- A directive with no matcher (i.e. matching all requests) is sorted last.
If the sorted order is not what you need, use the route directive to set the order explicitly, or mutually exclusive handle blocks.
The vars directive has its ordering by matcher reversed, because it involves setting values which can overwrite each other, so the most specific matcher should be evaluated last.
The contents of the route directive ignores all the above rules, and preserves the order the directives appear within.