3.6 KiB
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–599status, content type and body without connecting to an origin.HEAD,204and304do not return a body. - Redirect: issue
301,302,303,307or308to 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 and Access for the policies applied before connecting to the backend.