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 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 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. The highest priority is a directive with a single path matcher. Path matchers are sorted by specificity, from most specific to least specific. In general, this is performed by sorting by the length of the path matcher. There is one exception where if the path ends in a * and the paths of the two matchers are otherwise the same, the matcher with no * is considered more specific and sorted higher. 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 is sorted next, in the order it appears in the Caddyfile. This includes path matchers with multiple values, and named matchers. A directive with no matcher (i.e. matching all requests) is sorted last. 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.
Project
