Rules, IP lists, and GeoIP

ConceptsCopy Anchor Link

The console parses expressions and checks their fields, types, and actions before publishing a syntax tree; nodes validate the whole configuration and compile the tree. The configuration contains no executable Lua text.

Edit site rulesCopy Anchor Link

1. Open Sites, select the site, and open the Rules tab.

2. Click Add rule next to the target phase.

3. Enter the rule name and Expression. Insert condition appends a common condition (path prefix, Host equals, file extension, IP range, IP list, country, ASN, User-Agent contains, request method, Cookie equals, query parameter equals, User-Agent wildcard, Referer wildcard) and selects its example value, so typing replaces it; Insert field appends a field, and for Cookie, Query parameter, and Request header you first enter the name in the field that appears and press Enter or click Insert; both join with and. When the expression is invalid, "Character N: reason" appears below the editor, for example "Character 11: Ordered comparisons need a number field"; an expression the console refuses on save shows its position and reason the same way.

4. Select Action, fill in its fields, and turn on Enabled. A new rule starts disabled with the expression true (every request), as does a rule saved through the API without enabled; check the condition and the action before you save.

5. Drag the handle on the left of a rule to reorder rules within a phase.

6. Click Save. The console shows Saved and publishes a new configuration revision ("Rules and IP lists updated").

7. Verify: for example, the expression http.request.uri.path eq "/blocked" with the Block action:

   Copy Text

   curl -sI -H 'Host: www.example.com' http://<node IP>/blocked

   The response is 403 with X-Edgeweir-Error: policy-denied.

Global rules are edited on the Global rules page with the same editor (Origin override has no Origin group), apply to every site, and are published to every cluster on save. API: GET and PUT /api/v1/platform-rules.

Disabled rules are not sent to nodes.

Phases and actionsCopy Anchor Link

Phases run in the order of this table.

Action fieldsCopy Anchor Link

Protected headers cannot be set or removed by rules: Host, Authorization, Proxy-Authorization, Cookie, Set-Cookie, Content-Length, Transfer-Encoding, Connection, Upgrade, TE, Trailer, CDN-Loop, and headers starting with X-Edgeweir-.

Origin override changes at least one thing: an origin group other than Default group, or one of Origin Host, SNI, and Port.

Override settingsCopy Anchor Link

Every setting of Override settings starts as Unchanged; numbers left empty stay unchanged.

A later matching rule overrides an earlier one setting by setting. Compression switches apply only among the algorithms the site has turned on; rules cannot turn on an algorithm the site has off.

Dynamic targets and query parametersCopy Anchor Link

1. Next to Target of a redirect or rewrite path rule, select Expression.

2. Enter a value expression. When "Character N: reason" appears below the editor, fix it using Functions and Fields.

3. Switch Keep query string as needed, and fill in Set query parameters and Remove query parameters.

4. Click Save.

5. Verify: for example, a redirect rule with the expression starts_with(http.request.uri.path, "/old/"), the target regex_replace(http.request.uri.path, "^/old/", "/new/"), Keep query string on, and utm_source in Remove query parameters:

   Copy Text

   curl -sI -H 'Host: www.example.com' 'http://<node IP>/old/a?utm_source=x&id=1'

   The response is 301 with Location: /new/a?id=1.

A value expression is a string literal, a string field, or a function call that returns a string:

concat("https://www.example.com", http.request.uri.path)
regex_replace(http.request.uri.path, "^/old/(.*)$", "/new/${1}")
wildcard_replace(http.request.full_uri, "https://*.example.com/*", "https://example.com/${1}/${2}")

Header and query parameter valuesCopy Anchor Link

1. Next to Value of a request or response header rule, or after the name in a row of Set query parameters, select Expression.

2. Enter a value expression, for example ip.geoip.country for a request header X-Client-Country of the origin phase and http.request.id for X-Req. When "Character N: reason" appears below the editor, fix it using Functions and Fields.

3. Turn on Append when a response header needs another line next to the response's own.

4. Click Save. Rule changes are hot updates; nginx does not reload.

5. Verify: for example, with a request header rule X-Req = http.request.id in the origin phase, the origin receives an X-Req equal to the response header X-Request-Id; two response transform rules that append Link give the response two Link lines:

   Copy Text

   curl -sI -H 'Host: www.example.com' 'http://<node IP>/' | grep -i '^link:'

Execution orderCopy Anchor Link

Action behaviorCopy Anchor Link

Rate limitingCopy Anchor Link

ExpressionsCopy Anchor Link

ip.src in $blocked
http.request.uri.path matches "^/(admin|private)/" and not ssl eq true
http.request.method in {"POST" "PUT"}
http.request.headers["x-region"] eq "nz"
ip.geoip.country eq "NZ" and ip.geoip.asnum in {64512 64513}
http.response.code ge 500
lower(http.host) eq "www.example.com"
len(http.request.uri.query) gt 1024
url_decode(http.request.uri.query) contains "<script"
not starts_with(http.request.uri.path, "/api/")
http.request.uri.path.extension in {"jpg" "png" "webp"}
http.request.cookies["role"] eq "admin"
http.user_agent wildcard "*curl*"
http.referer strict wildcard "https://*.example.com/*"
substring(sha256(http.request.uri.path), 0, 8) eq "a1b2c3d4"

FieldsCopy Anchor Link

Operators and literalsCopy Anchor Link

FunctionsCopy Anchor Link

Every string is handled as UTF-8 bytes. Arguments are fields, string literals, or other function calls.

IP semanticsCopy Anchor Link

Regular expressionsCopy Anchor Link

matches and regex_replace use the same subset. Console validation, node validation and node execution (PCRE) accept the same subset; constructs whose meaning differs between the engines are refused.

A saved rule or cache rule condition that uses a construct no longer supported (such as \s) makes saving its site or its rules fail with RULE_INVALID; rewrite it and save again. Other publications (other sites, ACME challenges, system settings) go on: the rule keeps its last compiled form and the alert "Stored rule no longer valid; its last compiled form is kept" fires; such a rule that was never compiled holds its site back from the nodes. Rules of disabled sites are not compiled.

The language is a wirefilter-style subset, not a complete wirefilter implementation.

Complexity limitsCopy Anchor Link

Bulk redirectsCopy Anchor Link

A site's table of exact-match redirects: each entry redirects one source to one static target. For prefix or wildcard redirects, use a redirect rule with wildcard_replace.

1. Open Sites, select the site, and open the Bulk redirects tab.

2. Click Add redirect, enter Source and Target, select Status code, and turn on Keep query string as needed.

3. Or click Import, enter one entry per line in Import redirects ("One per line: source target [status]"), turn on Replace existing entries as needed, and click Import.

4. Click Save. The console shows Saved and publishes a new configuration revision ("Rules and IP lists updated").

5. Verify:

   Copy Text

   curl -sI -H 'Host: www.example.com' http://<node IP>/old

   The response has the entry's status code and its target in Location.

IP listsCopy Anchor Link

1. Open IP lists and click Create list.
2. Enter Name: starts with a letter or underscore, contains only letters, digits, and underscores, 1–64 characters.
3. Select Action: Referenced by rules, Block, or Allow.
4. Enter entries in IP addresses and CIDRs, separated by newlines, spaces, or commas.
5. Click Save.
6. Verify: the list shows $name and "N entries", block and allow lists also a Block or Allow badge; reference it in rules or cache rule conditions with ip.src in $name.

API: GET and POST /api/v1/ip-lists, PUT and DELETE /api/v1/ip-lists/{id}.

Node capabilities and publishingCopy Anchor Link

Configure GeoIP databasesCopy Anchor Link

GeoIP fields read MMDB files on the node. Nodes download no updates and send no visitor addresses to data vendors.

1. Container nodes running a release image need no configuration for country and ASN; for newer data, pull a newer image, or mount a separately downloaded copy and set EDGEWEIR_GEOIP_IPINFO.

2. Package or archive nodes: download ipinfo_lite.mmdb from IPinfo. To match on subdivisions, also download a City MMDB. Check source, license, and integrity, and record the download date.

3. Put the files in a read-only directory the node can read, and set the node environment variables:

   Copy Text

   EDGEWEIR_GEOIP_IPINFO=/etc/edgeweir-node/geoip/ipinfo_lite.mmdb
   EDGEWEIR_GEOIP_CITY=/etc/edgeweir-node/geoip/dbip-city-lite.mmdb

   For container deployments, mount the directory and pass the same variables with -e.

4. Restart the node to load the databases:

   Copy Text

   sudo systemctl restart edgeweir-node

5. Verify: Protection settings → GeoIP databases shows "Country: Ready" and "ASN: Ready" for the node, plus "Subdivision: Ready" when a City MMDB is configured.

LimitsCopy Anchor Link

TroubleshootingCopy Anchor Link