· Rules & Routing · About 8 min read

Shadowrocket Rule Syntax Guide: DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, GEOIP, IP-CIDR, and FINAL

Learn what six common rule keywords match, how rule order works, and how to use PROXY, DIRECT, and REJECT, with an example.com snippet.

At a glance

When Global Routing is set to Config, the first matching rule determines the policy for a connection. This guide is for first-time rule editors and anyone troubleshooting a rule that isn’t taking effect. You’ll learn to tell domain, address, and fallback rules apart, identify which line matches a request, and verify the result after making changes.

Rule order: from the first match to FINAL

Check a rule’s position in the file before considering how specific it is. Shadowrocket evaluates rules in the order they appear in the active configuration and applies the policy on the first match. A DOMAIN rule does not automatically move ahead of a DOMAIN-SUFFIX rule. To make an exception for a single host, place it before any broader rule that could match that host.

Target hostActive configurationRules checked in orderPolicy applied

Rules select a policy for each connection; they don’t assign a fixed label to an entire app. A single page load may connect to separate hosts for the page, static assets, and sign-in, and each connection can match a different rule. When troubleshooting, identify the host for the failed request—not just the host shown in the address bar.

Domain rules: exact hostnames, domain suffixes, and keywords

Domain rule values contain only a hostname or keyword. For https://www.example.com:443/docs, the hostname is www.example.com; leave out https://, port 443, and path /docs. The results below assume the destination hostname is available for matching.

Rule and match valueMatchesDoes not match
DOMAIN,example.comexample.comwww.example.com
DOMAIN-SUFFIX,example.comexample.com、www.example.comnotexample.com、example.com.example.net
DOMAIN-KEYWORD,exampleexample.net、notexample.comwww.test.invalid

Use DOMAIN to target one host. Use DOMAIN-SUFFIX to cover the root domain and its subdomains. Suffix matching respects domain-label boundaries; it doesn’t simply check whether a string ends in example.com. DOMAIN-KEYWORD searches for a string anywhere in the hostname without requiring a whole-label match. If you’re targeting one known domain, a keyword may also match unrelated domains.

Address rules: IP-CIDR ranges and GEOIP regions

IP-CIDR checks whether a destination IPv4 address falls within a specified range. GEOIP checks the location associated with the destination IP in the geolocation database. A region code does not indicate a domain suffix, where a website is registered, or where the device is located.

If a host must always use the same policy, don’t replace its domain rule with an IP address from a one-time lookup. Put the specific domain rule before address rules so the exception can be handled as soon as the hostname is known.

Example: match a single-host exception first

Use the snippet below to follow rule order; it is not a complete configuration. It rejects one specific host, proxies other requests under the same domain, then checks a keyword and an IP condition. When adding rules to an existing configuration, put only the rules you need in its [Rule] section and keep a single FINAL at the end.

[Rule]
DOMAIN,api.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,DIRECT
  1. api.example.com matches the domain conditions on the first three lines, but the first line takes precedence, so the result is REJECT. Move the suffix rule to the top and the result becomes PROXY.
  2. www.example.com does not match the first line. It matches the suffix on the second line and uses PROXY. Even if its destination IP is classified as CN, the later GEOIP rule won’t override the policy that already matched.
  3. example.net does not match the domain conditions on the first two lines. It matches the keyword on the third line and uses DIRECT. If the keyword rule were placed ahead of the suffix rule, www.example.com would also use DIRECT first.
  4. A destination address of 192.0.2.7 matches the fourth line. Only connections that match none of the first five lines reach FINAL,DIRECT. Since multiple lines can result in DIRECT, the policy name alone doesn’t tell you which rule matched.

Apply rules and verify the result

Before testing, confirm which configuration and routing mode are active, then start a new connection. The steps below use the iPhone / iPad interface. Saving a rule isn’t enough to complete a test: the selected configuration, reused connections, and proxy server status can all affect what you observe.

  1. Check the configuration

    Tap Config at the bottom and confirm which configuration file is selected. Keep a recoverable copy before editing so a single test doesn’t require changing multiple existing rules.

  2. Save your changes

    Add the rules you want to test to the [Rule] section of the same configuration. Check that fields are separated by English commas, exceptions appear before broader rules, and then save.

  3. Confirm routing mode

    Go back to Home, open Global Routing, and select Config. If Proxy, Direct, or a Scene was selected before, switch to Config before testing the rule order in this guide.

  4. Test a new connection

    On Home, confirm the connection is on. Close the connection used by the test app, then make a new request to a host you know is reachable. Check Data for the connection record at that time and verify the destination host, matched rule, and policy. A page loading successfully does not prove that PROXY matched.

Connection fails: check DNS and the server first

A browser error can indicate what kind of connection step failed, but it can’t prove on its own that a particular rule matched. Check the record for that request first. If there’s no matching record, confirm the test app opened a new connection and that Shadowrocket is still connected.

Browser errors and what to check

Error: ERR_NAME_NOT_RESOLVED

Cause: The browser couldn’t get a valid resolution for the destination hostname.

Fix: Check the hostname spelling first, then review the DNS settings in the active Config. Don’t try to fix a resolution issue by changing FINAL.

Error: ERR_CONNECTION_RESET

Cause: The connection was reset. This error alone can’t tell you whether the outbound connection or the destination closed it.

Fix: Check the policy in Data first. If PROXY matched, return to Home, run Connectivity Test for the current server, then test the same host again.

FAQ: Why didn’t changing a rule make a difference?

Troubleshoot by symptom

I added DOMAIN. Why is the connection still using the old policy?

First, check in Home → Global Routing that Config is selected. Then look in the active rule section for an earlier DOMAIN-SUFFIX, DOMAIN-KEYWORD, or other rule that already matches. Move the exact exception above it and start a new connection.

How do I send just one subdomain directly without changing the whole suffix rule?

Keep the existing suffix rule and add DOMAIN,files.example.com,DIRECT above it. This affects only files.example.com. When the page reloads, requests to other hosts are still handled by their respective matching rules.

Why can I connect by IP but not use that to verify my domain rule?

When you enter an IP directly, the test no longer uses the original hostname, so it can’t confirm whether DOMAIN matched. Test with the original hostname and check the connection record. If the browser reports a resolution error, troubleshoot DNS before testing the domain rule again.

How can I tell whether FINAL matched instead of an earlier DIRECT rule?

Check the rule for the connection in Data, not just whether the policy is DIRECT. If the record shows an earlier domain or address rule matched, choose a different test destination. The connection reaches FINAL only when none of the earlier conditions match.

Download Shadowrocket