How to Write Shadowrocket Rules: A Beginner’s Guide to DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL

Learn what DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, GEOIP, IP-CIDR, and FINAL match, how rules are evaluated from top to bottom, and how to use PROXY, DIRECT, and REJECT.

At a glance

In Home → Global Routing, select Config, then check the [Rule] section in the active configuration: rules are checked from top to bottom, and the first match determines the policy. This guide is for users with an existing configuration who want to add a domain exception or troubleshoot routing. You’ll learn to choose a rule type, place specific exceptions before broader rules, and verify routing with three requests.

Rule syntax: separate the match condition from the policy

In the [Rule] section, put one rule on each line. A standard rule specifies the type, match value, and policy, separated by commas. FINAL needs no match value; specify only the policy. For domain rules, enter a hostname or matching string—not https://, a port, or a path. The domains and addresses below illustrate syntax only; they are not for testing connectivity.

[Rule]
DOMAIN,docs.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example-test,REJECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
3 types
domain match types covered in this guide
/24
The first 24 bits of an IPv4 address form the network prefix
2 fields
A FINAL rule contains only the type and policy

Check which rule matches before changing the policy

To route a subdomain directly, first confirm the request’s hostname, then move its DOMAIN rule above any DOMAIN-SUFFIX rule that could match it. Don’t start by changing FINAL: requests already matched by an earlier rule never reach the last rule.

  • DIRECT: Sends the request straight to its destination, without using the selected proxy.
  • PROXY: Forwards the request through a proxy. Before testing, check the selected proxy on Home. Matching this rule does not mean the proxy is working or that the destination has responded.
  • REJECT: Rejects matching requests. It does not send them through a proxy or serve as a fallback route when a connection fails.

Domain matching: DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD

Use DOMAIN for one exact hostname, DOMAIN-SUFFIX to cover a root domain and its subdomains, and DOMAIN-KEYWORD only when you need to match the same string across multiple domains. Suffix matching respects domain-label boundaries; keyword matching does not require the string to occupy a whole label.

ConditionMatching exampleNon-matching example
DOMAIN,docs.example.comdocs.example.comcdn.docs.example.com、example.com
DOMAIN-SUFFIX,example.comexample.com、api.example.comnotexample.com、example.com.example.net
DOMAIN-KEYWORD,example-testcdn-example-test.example.netexampletest.example.net

The table checks each condition independently; the policy actually applied also depends on rule order. In this example, docs.example.com matches the first two rows. The exact-match rule comes first, so the request uses DIRECT. Move the suffix rule above it, and the same hostname will use PROXY. Shadowrocket does not gather all matching rules and automatically choose the most specific one.

Address matching: IP-CIDR, GEOIP, and no-resolve

IP-CIDR matches a destination by its IPv4 network range, making it useful for known address ranges. GEOIP matches a destination based on its region in the IP database. GEOIP,CN,DIRECT does not check whether a domain ends in .cn or where the device is located. Since a domain’s resolved IP can vary by network or over time, prefer a known domain rule when you need consistent routing for a specific service.

  • 192.0.2.0/24 covers addresses from 192.0.2.0 through 192.0.2.255. For example, destination IP 192.0.2.42 matches this range, but 192.0.3.42 does not. To match only the first address, use 192.0.2.42/32.
  • When a domain request reaches an address rule before its destination IP is known, the domain may need to be resolved first. In this example, no-resolve means not to resolve the domain just to evaluate this IP-CIDR rule. If the destination IP is already available, it can still be checked against the rule. This does not prevent DNS lookups required by later rules or the actual connection.
  • This IPv4 range in IP-CIDR does not cover IPv6. If the same host behaves differently across networks, first check the address family and destination IP actually used by the connection, then see whether an address rule failed to match. A different port does not change the range covered by this rule.

Place specific address exceptions before broad GEOIP rules. If GEOIP,CN,DIRECT comes first, a destination classified as CN by the database may already match DIRECT, and the later range exception will never be checked. FINAL at the end handles only requests that have not matched earlier; it does not reroute a request after an earlier connection times out.

Verify the first matching rule in Config

Write down the expected policy for each test destination before changing rules. To simulate a specific exception, choose a destination you know is reachable; documentation-only address ranges are not live services. Save a copy of the original configuration before editing, so you don’t change both rule order and connectivity at once.

  1. Check the configuration

    Open Config and confirm which configuration file is active. To test PROXY, also check on Home that your selected proxy is one you already have and know to be working.

  2. Save the rules

    In the active configuration’s [Rule] section, add an exact-match exception above any suffix, keyword, or address rules that could match the destination. Keep FINAL at the end.

  3. Switch to Config

    In Home → Global Routing, select Config. Don’t use results from Proxy or Direct mode to verify rules. If you were using Scene, switch explicitly to Config first to rule out scene selection as a factor.

  4. Send new requests

    Send requests to the exact-match exception, another host with the same suffix, and a destination that matches none of the preceding conditions. With the examples in this guide, the expected policies are DIRECT, PROXY, and the PROXY specified by FINAL, respectively. If the third destination matches GEOIP first, choose another destination to test the fallback.

  5. Compare the results

    Check the connection records for the new requests and compare the actual hostname, policy, and any visible match details. A page loaded from cache or a reused connection can’t tell you whether the new rules took effect; end the old connection and test again.

Rules not working? Separate policy issues from DNS and connection errors

If the same host uses the wrong policy, check the active configuration, Global Routing, and rule order first. If the policy is correct but the request fails, investigate DNS or the connection. The messages below are possible errors shown by the Chromium browser, not Shadowrocket rule-validation messages. A browser error alone cannot identify which rule caused the problem.

Error: ERR_NAME_NOT_RESOLVED

Cause: The browser could not resolve the requested hostname to a usable address. Fix: Check the hostname for typos, then review the current DNS settings. Don’t change FINAL to a different policy to troubleshoot the spelling or DNS.

Error: ERR_CONNECTION_TIMED_OUT

Cause: The connection was not established before the timeout; the destination or current forwarding path may not be responding. Fix: First check whether the new request uses the expected policy, then test a known-reachable destination with the same policy. This helps distinguish a timeout at one destination from an unavailable route.

If both destinations use PROXY, the policy name alone can’t tell you whether a suffix rule matched or FINAL provided the fallback. Check the match details in the connection record first. If the record doesn’t show the specific rule, make a test copy of the configuration, change only the rule you’re checking, and send a new request to a test destination you control. Compare the policies before and after, then restore the original configuration.

Download Shadowrocket for free