mirror of
https://github.com/caddyserver/website.git
synced 2025-04-22 21:16:15 -04:00
3f3e0fb9f8
* docs: Some cleanup, some v2.4.0 additions - Add `abort` directive docs - Add a note in `handle` to cross-link to `handle_path` - Add another example in `handle_errors` that shows how an `expression` matcher can be used to pair with it - Add a cat emoji to handle_errors because 😸 - Add `file_server` to one of the `php_fastcgi` examples, it's rare that you'll ever use it without `file_server` so might as well include it there - Add a TOC to `reverse_proxy` cause it's such a long page. Maybe we'll add one to other pages as well, but TBD - Clarify the upstream address stuff a bit after some discussion in https://caddy.community/t/reverse-proxy-with-multiple-different-upstreams-with-paths/11512/12 and mention `rewrite` as the alternative - Use the `{re.*.*}` shortcut in the Caddyfile matcher docs, links to the placeholder mapping to let people trace where that comes from * docs: Revise the `handle` cross-linking, add another example * docs: Bump minimum Go version to 1.15 * docs: A bunch more additions since v2.3.0 I went through the whole list of commits here: https://github.com/caddyserver/caddy/compare/v2.3.0...ec3ac84 * docs: Review feedback * docs: Link to https://golang.org/doc/install, better instructions
57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
---
|
|
title: handle (Caddyfile directive)
|
|
---
|
|
|
|
# handle
|
|
|
|
Evaluates a group of directives mutually exclusively from other `handle` blocks at the same level of nesting.
|
|
|
|
The `handle` directive is kind of similar to the `location` directive from nginx config: the first matching `handle` block will be evaluated. Handle blocks can be nested if needed. Only HTTP handler directives can be used inside handle blocks.
|
|
|
|
## Syntax
|
|
|
|
```caddy-d
|
|
handle [<matcher>] {
|
|
<directives...>
|
|
}
|
|
```
|
|
|
|
- **<directives...>** is a list of HTTP handler directives or directive blocks, one per line, just like would be used outside of a handle block.
|
|
|
|
|
|
## Utility
|
|
|
|
If you prefer crafting HTTP handler logic in a more inheritence-based way like nginx location blocks, you may prefer the use of `handle` blocks rather than defining mutually-exclusive matchers for your directives. If inheritence is a desired characteristic of your HTTP handler configurations, then the `handle` directive may suit you well.
|
|
|
|
## Similar directives
|
|
|
|
There are other directives that can wrap HTTP handler directives, but each has its use depending on the behavior you want to convey:
|
|
|
|
- [`handle_path`](handle_path) does the same as `handle`, but it strips a prefix from the request before running its handlers.
|
|
- [`handle_errors`](handle_errors) is like `handle`, but is only invoked when Caddy encounters an error during request handling.
|
|
- [`route`](route) wraps other directives like `handle` does, but with two distinctions: 1) route blocks are not mutually exclusive to each other, and 2) directives within a route are not [re-ordered]([directive order](/docs/caddyfile/directives#directive-order), giving you more control if needed.
|
|
|
|
## Examples
|
|
|
|
Handle requests in `/foo/` by the static file server, and send all other requests to the reverse proxy:
|
|
|
|
```caddy-d
|
|
handle /foo/* {
|
|
file_server
|
|
}
|
|
handle {
|
|
reverse_proxy 127.0.0.1:8080
|
|
}
|
|
```
|
|
|
|
You can mix `handle` and [`handle_path`](handle_path) directives in the same site, and they will still be mutually exclusive from each other:
|
|
|
|
```caddy-d
|
|
handle_path /foo/* {
|
|
# The path has the "/foo" prefix stripped
|
|
}
|
|
|
|
handle /bar/* {
|
|
# The path still retains "/bar"
|
|
}
|
|
```
|