- ORM Rule Cookbook
- 1. Matching
- 2. Actions
- 3. Complete examples
- 3.1 Routing requests to a single backend and rewriting request headers
- 3.2 Routing requests to certain paths to one backend and redirecting everything else
- 3.3 Routing requests to different backends based on query parameters
- 3.4 Redirecting requests to a single URL
- 3.5 Redirecting requests and rewriting the request path
A collection of ORM rule examples and construction principles
Match paths that begin with either /secret/ or /topsecret/:
matches:
all:
- paths:
begins_with:
- '/secret/'
- '/topsecret/'
Match paths that end with .jpg:
matches:
all:
- paths:
ends_with:
- '.jpg'
Match paths that either begin with /images/ OR end with .jpg:
matches:
any:
- paths:
begins_with:
- '/images/'
- paths:
ends_with:
- '.jpg'
Match paths that begin with /images/ AND end with .jpg:
matches:
all:
- paths:
begins_with:
- '/images/'
- paths:
ends_with:
- '.jpg'
Match paths that either match one of a list of exact strings or a regex:
matches:
any:
- paths:
regex:
- '/path/to/matching/directory/.+'
- paths:
exact:
- '/a/very/specific/request/path/'
- '/another/path/'
- '/the/last/exact/path/'
Match a request based on a specific value for a parameter:
matches:
any:
- query:
parameter: my_parameter
exact:
- required_value
Match requests on multiple parameters, case-insensitive on the second parameter which can begin with either foo or bar:
matches:
all:
- query:
parameter: my_parameter
exact:
- required_value
- query:
parameter: other_parameter
ignore_case: true
begins_with:
- foo
- bar
Match any paths that are NOT the paths /public/ or /html/public/:
matches:
all:
- paths:
not: True
begins_with:
- '/public/'
- '/html/public/'
Match any path that does not END with /public/:
matches:
all:
- paths:
not: True
ends_with:
- '/public/'
Match paths that begin with either /secret/ or /topsecret/ EXCEPT the subdirectories public:
matches:
all:
- paths:
begins_with:
- '/secret/'
- '/topsecret/'
- paths:
not: True
begins_with:
- '/secret/public/'
- '/topsecret/public/'
As above, but using ends_with for negative matching instead:
matches:
all:
- paths:
begins_with:
- '/secret/'
- '/topsecret/'
- paths:
not: True
ends_with:
- '/public/'
The matches directive can only be present in a rule that does NOT have the domain_default property set, for obvious reasons. A rule that has domain_default: True will match any requests to that domain that are not matched by a rule for the same domain that does explicit matching.
Complete rule example:
- description: www.domain.example - domain default
domains:
- www.domain.example
domain_default: True
actions:
backend:
origin: 'https://default-origin.example'
header_southbound:
- set:
field: 'Host'
value: 'default-origin.example'
- set:
field: 'X-Forwarded-Host'
value: 'www.domain.example'
Routes all matched requests to the backend at https://my-backend.domain.example:
actions:
backend:
origin: 'https://my-backend.domain.example'
Spreads the matched requests over two servers:
actions:
backend:
servers:
- 'https://backend-1.domain.example'
- 'https://backend-2.domain.example'
actions:
backend:
servers:
- server: 'https://small-backend.domain.example'
max_connections: 32
max_queued_connections: 16
- server: 'https://large-backend.domain.example'
max_connections: 2048
max_queued_connections: 1024
Set a 20 seconds server timeout for two servers:
actions:
backend:
timeout_server: 20
servers:
- 'https://backend-1.domain.example'
- 'https://backend-2.domain.example'
Set a 5 seconds server timeout for one backend:
actions:
backend:
timeout_server: 5
origin: 'https://my-backend.domain.example'
Add a prefix to the request path:
actions:
req_path:
- prefix:
add: /myprefix
Replace a specific part of a path regardless of case:
actions:
req_path:
- replace:
from_exact: '/path/to/replace'
ignore_case: true
to: '/new/path'
Rewrite a path based on regular expression matching:
actions:
req_path:
- replace:
from_regex: '/some/path/(.*)'
to_regsub: '/\1'
The above actually removes the prefix '/some/path' from the path, which can also be achieved using the prefix structure:
actions:
req_path:
- prefix:
remove: /some/path
When manipulating headers, southbound is the direction of the incoming request, i.e. toward the origin, and northbound is the direction of the response, i.e. toward the client.
Setting the southbound host header:
actions:
header_southbound:
- set:
field: 'Host'
value: 'backend-host-name.domain.example'
Adding a southbound header that the backend application requires:
actions:
header_southbound:
- add:
field: 'Authorization'
value: 'My-secret-authorization-token'
Setting various northbound headers for access control:
actions:
header_northbound:
- set:
field: 'Access-Control-Allow-Origin'
value: '*'
- set:
field: 'Access-Control-Allow-Methods'
value: 'GET,POST'
- set:
field: 'Access-Control-Allow-Credentials'
value: 'false'
- set:
field: 'Access-Control-Max-Age'
value: '86400'
Removing a header sent by the origin that should not reach the client:
actions:
header_northbound:
- remove: 'X-Robots-Tag'
Temporary (HTTP 307) redirect of all matching requests to a new domain:
actions:
redirect:
type: temporary
domain: www.redirectdomain.example
Permanent (HTTP 308) redirect of the same type, but redirect to HTTP specifically:
actions:
redirect:
type: permament
scheme: http
domain: www.redirectdomain.example
Temporary (HTTP 307) redirect of all matching requests to a specific url:
actions:
redirect:
type: temporary
url: https://www.redirectdomain.example/redirected/
Temporarily redirect matching requests to a new domain using HTTPS and adjust the path:
actions:
redirect:
type: temporary
scheme: https
domain: www.redirectdomain.example
path:
- prefix:
add: /redirected
rules:
- description: My production web site
domains:
- www.domain.example
matches:
all:
- paths:
begins_with:
- '/'
- paths:
not: True
exact:
- '/xml'
begins_with:
- '/xml/'
actions:
backend:
origin: https://my.origin.example
header_southbound:
- set:
field: 'Host'
value: 'my.origin.example'
- set:
field: 'Authorization'
value: 'example-auth-header-content'
header_northbound:
- set:
field: 'Strict-Transport-Security'
value: 'max-age=7776000'
- remove: 'WWW-Authenticate'
rules:
- description: Domain default rule that redirects requests that do not match any other rule
domains:
- www.domain.example
domain_default: True
actions:
redirect:
type: permanent
url: https://my.redirect-url.example
- description: Rule to route requests to a certain path to a backend
domains:
- www.mydomain.example
matches:
all:
- paths:
begins_with:
- '/non-redirecting-path'
actions:
backend:
origin: https://my.origin.example
header_southbound:
- set:
field: 'Host'
value: 'my.origin.example'
rules:
- description: Rule to route requests with a specific query parameter to a separate backend
domains:
- www.domain.example
matches:
all:
- query:
parameter: special
exact:
- True
actions:
backend:
origin: https://special.origin.example
header_southbound:
- set:
field: 'Host'
value: 'special.origin.example'
- description: Rule to route requests without a specific query parameter to another backend
domains:
- www.domain.example
matches:
all:
- query:
parameter: special
exist: False
actions:
backend:
origin: https://other.origin.example
header_southbound:
- set:
field: 'Host'
value: 'other.origin.example'
rules:
- description: Redirect www.domain.example to www.redirect-domain.example using https
domains:
- www.domain.example
domain_default: True
actions:
redirect:
type: temporary
scheme: https
domain: www.redirect-domain.example
rules:
- description: Redirect domain.example/<path> to www.redirect-domain.example/newlocation/<path>
domains:
- domain.example
- www.domain.example
domain_default: True
actions:
redirect:
type: temporary
scheme: https
domain: www.redirect-domain.example
path:
- prefix:
add: /newlocation