Rule Actions

When any condition within any Rule matches, the specified action is executed. After being executed, actions can terminate the request (by sending a challenge, denying the user, or any other reason) to stop the processing of rules, otherwise rules will continue to be matched.

Action	Behavior	Terminating
PASS	Passes the request to the current backend immediately.	Yes
PROXY	Proxies request to a different backend, with optional path replacements.	Yes
DENY	Denies the request with a descriptive page.	Yes
BLOCK	Denies the request with only a minor response.	Yes
DROP	Drops the connection without sending a reply.	Yes
CHALLENGE	Issues a challenge that when passed, acts like PASS.	Yes
CHECK	Issues a challenge that when passed, continues executing rules.	No
CONTEXT	Modify the request context and apply different options, like changing headers or backend.	No
NONE	Do nothing, continue. Useful for specifying on checks or challenges.	No

---

PASS

Forwards the request to the current selected backend. No further rules will be executed afterward.

Example:

rules:
  - name: example
    conditions:
      - 'path == "/example/path"'
    action: pass

PROXY

Forwards the request to the specified backend. No further rules will be executed afterward.

Example:

rules:
  - name: example
    conditions:
      - 'path == "/example/path"'
    action: backend
    settings:
      # backend must be defined on cmd or config
      proxy-backend: "other.backend.example.com"

Rewrite rules

The path (not query) can be matched using a regex and replaced to implement most rewrite needs.

Matches/rewrites are implemented via regex/Regexp.ReplaceAllString, which allows for groups and expansion.

Example:

rules:
  - name: example
    conditions:
      - 'path == "/example/path"'
    action: backend
    settings:
      # backend must be defined on cmd or config
      proxy-backend: "other.backend.example.com"
      # rewrites /example/path to /path
      proxy-match: "^/example/"
      proxy-rewrite: "/"

DENY

Denies the request with a descriptive page based on the challenge template. No further rules will be executed afterward.

Example:

rules:
  - name: example
    conditions:
      - 'userAgent.matches("ExampleBot/")'
    action: deny

BLOCK

Denies the request with a simple text message. No further rules will be executed afterward.

In the future this action might be able to be used to trigger further blocking of the request properties like IP Address. We recommend using DENY unless matches here are desired to be blocked as a whole.

Example:

rules:
  - name: example
    conditions:
      - 'userAgent.matches("BadBot/")'
    action: block

DROP

Closes the request stream immediately. If unable, only an HTTP code is returned. No further rules will be executed afterward.

Example:

rules:
  - name: example
    conditions:
      - 'userAgent.matches("ExampleBot/")'
    action: drop

CHALLENGE

Challenges the client to pass a set of challenges. By default, it terminates rule processing.

See Challenges for a list of available pre-configured challenges.

Example:

rules:
  - name: example
    conditions:
      - 'userAgent.startsWith("Mozilla/")'
    action: challenge
    settings:
      # HTTP Code to present when serving a non-transparent challenge.
      # Defaults to global setting of 418
      #http-code: 418
      
      # Challenges that grant the client a pass. Required field.
      # If the client has passed any in the list previously, it is let through
      # Otherwise, challenges are presented in order of the list.
      # Transparent challenges (in this case preload-link is) will allow further challenges to be presented if they fail
      # Non-transparent challenges will abort the request and challenge the client.
      challenges: ["preload-link", "resource-load", "js-pow-sha256"]

      # Action to execute when we pass the challenge.
      # Default is pass, but you can override this
      # Settings can be also set
      #pass: pass
      #pass-settings:
        # [...]

      # Action to execute when we fail the challenge.
      # A challenge is failed when an error ocurrs or we run out of challenges.
      # Default is deny, but you can override this
      # Settings can be also set
      #fail: deny
      #deny-settings:
        # [...]

CHECK

Challenges the client to pass a set of challenges. By default, it continues rule processing if passed, but blocks if failed.

Almost similar to CHALLENGE except there is no pass action, it just continues.

See Challenges for a list of available pre-configured challenges.

Example:

rules:
  - name: example
    conditions:
      - 'userAgent.startsWith("Mozilla/")'
    action: check
    settings:
      # HTTP Code to present when serving a non-transparent challenge.
      # Defaults to global setting of 418
      #http-code: 418
      
      # Challenges that grant the client a pass. Required field.
      # If the client has passed any in the list previously, it is let through
      # Otherwise, challenges are presented in order of the list.
      # Transparent challenges (in this case preload-link is) will allow further challenges to be presented if they fail
      # Non-transparent challenges will abort the request and challenge the client.
      challenges: ["preload-link", "resource-load", "js-pow-sha256"]

      # Action to execute when we fail the challenge.
      # A challenge is failed when an error ocurrs or we run out of challenges.
      # Default is deny, but you can override this
      # Settings can be also set
      #fail: deny
      #deny-settings:
        # [...]

CONTEXT

Allows setting properties or headers on the current request context and flow. Rules will continue executing afterward.

response-headers

Set specific headers to be returned on the response back to the client. The header value is a list of strings, not a single one.

If the value is an empty list, the header will be explicitly removed.

Example:

rules:
  - name: example
    action: context
    conditions:
      - 'path == "/"'
    settings:
      response-headers:
        X-Clacks-Overhead:
          - GNU Terry Pratchett
        X-World-Domination:
          - "yes"
          - "no"

request-headers

Set specific headers to be sent to the backend. The header value is a list of strings, not a single one.

If the value is an empty list, the header will be explicitly removed.

Example:

rules:
  - name: example
    action: context
    conditions:
      - 'path == "/"'
    settings:
      request-headers:
        X-Requested-By:
          - go-away
        X-World-Domination:
          - "yes"
          - "no"

context-set

Sets specific settings available. This will grow in the future.

Available options:

Option	Description	Values
proxy-meta-tags	Enable OpenGraph and other safe <meta> tag fetching from the underlying pages from now on. These tags will be presented on challenge or error pages to allow tag fetchers to work, even when challenged or blocked. Values will be cached temporarily.	"true" "false"
proxy-safe-link-tags	Enable safe <link> tag fetching from the underlying pages from now on. These tags will be presented on challenge or error pages to allow other features to work, even when challenged or blocked. Values will be cached temporarily.	"true" "false"
backend-host	Overrides the current selected backend with a different one. Backend must exist in defined backends.	Backend key/host as defined.

Example for proxy-meta-tags and proxy-safe-link-tags:

rules:
  - name: example
    action: context
    conditions:
      - 'path == "/" || path == "/index.html"'
    settings:
      context-set:
        proxy-meta-tags: "true"
        proxy-safe-link-tags: "true"

Example for backend-host:

rules:
  - name: example
    action: context
    conditions:
      - 'path.startsWith("/other/")'
    settings:
      context-set:
        backend-host: "*.example.com"

NONE

Does nothing and continues. Useful to make advanced challenges with rule nesting and override pass/fail actions.

No example is provided.