Match Rules

Match rules decide when a rewrite action should run. A rule is placed in one of these lists:

header-rewrite: []
body-rewrite: []
url-redirect: []

Common fields:

Field	Description
type	Match rule type
match-value	Value used by the matcher
match-header	Header name for Header matchers
action	Rewrite action to execute
continue	Continue evaluating later rules after this match

DOMAIN

DOMAIN matches the parsed request host exactly.

header-rewrite:
  - type: DOMAIN
    match-value: "example.com"
    action: DIRECT

It does not match subdomains.

DOMAIN-SUFFIX

DOMAIN-SUFFIX matches hosts ending with match-value.

header-rewrite:
  - type: DOMAIN-SUFFIX
    match-value: "example.com"
    action: DIRECT

Use it for a domain family such as example.com, api.example.com, and static.example.com.

DOMAIN-KEYWORD

DOMAIN-KEYWORD matches hosts containing match-value.

header-rewrite:
  - type: DOMAIN-KEYWORD
    match-value: "example"
    action: DIRECT

Use exact or suffix matching when substring matching is too broad.

DOMAIN-SET

DOMAIN-SET loads a domain list from a local file path or remote HTTP(S) URL and suffix-matches the parsed request host.

header-rewrite:
  - type: DOMAIN-SET
    match-value: "/etc/ua3f/domain-set.txt"
    action: DIRECT

Domain set files are parsed line by line. Empty lines and lines beginning with # are ignored. The set is loaded asynchronously during rule initialization.

IP-CIDR

IP-CIDR matches the remote destination IP against a CIDR range.

header-rewrite:
  - type: IP-CIDR
    match-value: "203.0.113.0/24"
    action: DIRECT

If the value does not include a prefix length, UA3F treats it as a single IPv4 host by appending /32.

SRC-IP

SRC-IP matches the client source IP against a CIDR range.

header-rewrite:
  - type: SRC-IP
    match-value: "192.168.1.0/24"
    action: REPLACE
    rewrite-header: "User-Agent"
    rewrite-value: "UA3F"

Use it to apply different policies to different LAN clients.

DEST-PORT

DEST-PORT matches the destination port as a string.

header-rewrite:
  - type: DEST-PORT
    match-value: "22"
    action: DIRECT

Quote the port in YAML to keep it as a string.

HEADER-KEYWORD

HEADER-KEYWORD matches when a request Header contains a keyword. Header value matching is case-insensitive.

header-rewrite:
  - type: HEADER-KEYWORD
    match-header: "User-Agent"
    match-value: "MicroMessenger"
    action: DIRECT

HEADER-REGEX

HEADER-REGEX matches a request Header with a case-insensitive regular expression.

header-rewrite:
  - type: HEADER-REGEX
    match-header: "User-Agent"
    match-value: "(Windows|Android|iPhone)"
    action: REPLACE-REGEX
    rewrite-header: "User-Agent"
    rewrite-regex: "(Windows|Android|iPhone)"
    rewrite-value: "UA3F"

Invalid expressions are logged and the rule will not match.

URL-REGEX

URL-REGEX matches the full request URL with a regular expression.

url-redirect:
  - type: URL-REGEX
    match-value: "^http://example.com/old"
    action: REDIRECT-302
    rewrite-regex: "^http://example.com/old(.*)"
    rewrite-value: "https://example.com/new$1"

Use anchors such as ^ when the rule should only match a URL prefix.

FINAL

FINAL always matches and is usually placed at the end of a rule list.

header-rewrite:
  - type: FINAL
    action: REPLACE
    rewrite-header: "User-Agent"
    rewrite-value: "UA3F"

Place specific rules before broad rules. If FINAL appears before other rules, later rules are normally unreachable unless continue: true is set.