42 lines
3.6 KiB
Markdown
42 lines
3.6 KiB
Markdown
# Custom locations and path rules
|
||
|
||
Custom locations add exceptions to a Vhost's normal source. They are **not** required for the root path `/`: any request not matched by a custom rule continues to the Vhost's main backend pool or Web Service. Configure them under **Vhosts → Edit → Custom locations**.
|
||
|
||
## Path matching
|
||
|
||
| Match mode | Purpose | Priority |
|
||
|---|---|---|
|
||
| `exact` | One exact normalized path | Highest |
|
||
| `prefix_priority` | Longest prefix that suppresses regex evaluation | Ahead of regex when matched |
|
||
| `regex` / `regex_insensitive` | Case-sensitive or insensitive regular expression | Tested in configured order after priority-prefix rules |
|
||
| `prefix` | Ordinary longest matching path prefix | Fallback among matching rules |
|
||
|
||
Ambiguous and unsafe encoded path forms are rejected rather than treated as alternative spellings. Avoid overlapping regex rules when order matters; test paths with and without trailing `/`. A Vhost's main source handles paths without a matching custom location.
|
||
|
||
## Actions
|
||
|
||
- **Proxy:** use the Vhost backend pool or target a specific backend. A location can have an explicit cache override.
|
||
- **Web Server:** reference an existing Web Service with its saved document root and PHP/static settings.
|
||
- **Local response:** return a chosen `200–599` status, content type and body without connecting to an origin. `HEAD`, `204` and `304` do not return a body.
|
||
- **Redirect:** issue `301`, `302`, `303`, `307` or `308` to a valid absolute HTTP(S) target. Query preservation is configurable. Redirect rewrite expressions may reference regex captures.
|
||
|
||
### Path rewriting
|
||
|
||
`preserve` forwards the original path, `strip_prefix` removes the matched prefix, `replace_prefix` substitutes a new normalized prefix and `regex` rewrites using captures such as `$1` or `${name}`. Queries remain intact unless a redirect explicitly changes handling. Public cache keys are based on the client-facing URL, not an internal rewritten backend path.
|
||
|
||
**Example:** send `example.com/api/*` to a dedicated application while `/` remains on the main website. Create a `/api/` prefix location, select its backend and choose whether to preserve or strip `/api/`. Inspect the editor's effective-behavior preview before saving.
|
||
|
||
## Headers, access and method rules
|
||
|
||
Each location can add request/response header operations (`set`, `append`, `remove`), reusable ACL profiles, inline IP/CIDR rules, country access and HTTP-method allow/block lists. Every applicable host and Vhost policy must still pass; a location cannot remove a higher-level denial. Transport/forwarded-identity headers are protected from unsafe overrides. Authentication, rate limits, WebSocket policy and other Vhost settings continue to apply.
|
||
|
||
## Internal error fallback
|
||
|
||
Mark a location **Internal** to make it unavailable to ordinary public URI matching. A Vhost or location may direct specific origin responses (`403`, `404`, `500`, `502`, `503`, `504`) to a named internal location ID in the same Vhost. The dispatch is internal, not a browser redirect; request context and access evaluation are preserved. Invalid targets or loops are rejected.
|
||
|
||
If all you need is a different error **page body**, use **Vhost → Pages → Intercept application error responses**, which keeps the original status without making a second origin request.
|
||
|
||
## Not an Nginx configuration parser
|
||
|
||
The editor does not run arbitrary Nginx snippets, filesystem aliases, arbitrary `if` rules or per-location static roots. Configure static paths in a reusable Web Service, then assign that service to the location. Inspect [Vhosts](VHOSTS.md) and [Access](ACCESS.md) for the policies applied before connecting to the backend.
|