Shadowrocket Rules Guide
Configuration & Match Order

01 Configuration Structure & Scope

Are a configuration and a subscription the same thing?

No. A subscription typically maintains a set of server connection details. A configuration describes how requests are handled—for example, which policies to use, which domain rules to apply, and whether specific DNS or rewrite behavior is needed. Importing an existing subscription and seeing servers in the list does not mean a rules configuration is active. To troubleshoot, check the available servers in Home, the active configuration in Config, and the Global Routing mode separately. One check cannot replace the others.

Where should I start? Identify the section names in square brackets, then read the lines within each section. Each section has its own syntax: General commonly contains key-value settings, Rule contains match conditions listed line by line, Host maps domains to addresses, and URL Rewrite uses match expressions and actions. Don’t paste a domain rule into General. A file saving successfully does not mean its contents will produce the behavior you expect.

[General]
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,DIRECT

[Host]
portal.example.com = 192.0.2.10

What does this minimal snippet do?

In General, it uses the system DNS settings. In Rule, it handles an example domain suffix first, checks the address range next, then sets a fallback policy. The address in Host comes from a documentation-only range and demonstrates the mapping format. The snippet contains no server credentials and does not show every available setting. Whether PROXY can establish a connection still depends on the selected server and its parameters. Read each line in the context of its section rather than focusing on a single keyword.

How can I make changes that are easy to roll back? In Config, find the configuration currently in use. Keep the original, then create a clearly named copy. Record the current Global Routing mode, selected server, and target domain you plan to test. Change one logical item at a time—for example, add one DOMAIN rule instead of changing DNS, the server, and the fallback policy together. After saving, confirm that the copy is active so you don’t edit one file and test another.

Should I copy all the settings in General?

No. General contains basic behavior settings, which should be checked individually in light of the issue you’re investigating. Your existing configuration may already include DNS, connection-handling, or network options; replacing it wholesale could disrupt things that currently work. For unfamiliar keys, check their names and accepted values in the in-app editor. If you can’t confirm what a setting does, leave it unchanged. This guide shows only snippets whose purpose can be explained; adding parameters indiscriminately is not a path to a universal configuration.

What happens to local changes when a remote configuration is updated? If the current file comes from a remote source, check the actual in-app behavior to see whether edits are retained. Don’t assume every change will be merged automatically. A safer approach is to keep the original source and a local test copy, then compare the rules you changed after an update. If behavior changes, first compare the active file, rule order, and basic settings rather than immediately concluding that the server has failed.

What should I include in notes? You can record a rule’s purpose, test target, and rollback steps, but don’t put your subscription URL, password, or other connection credentials in an example you plan to share publicly. When sharing troubleshooting details, keep the section names, keywords, and rule order; remove sensitive fields, then check screenshots and text for any remaining query parameters. A configuration describes network behavior—it’s more than a list of text to save for later.

03 IP-CIDR, GEOIP & USER-AGENT

What does the number after the slash in IP-CIDR mean?

It is the network prefix length, which defines an address range. It is not a port or a rule priority. In IPv4, /32 represents a single address, while /24 is commonly used for a network block of 256 addresses. A broader range can cover more destinations. Before writing a rule, decide whether you need to match one host or an entire network. Don’t shorten the prefix just because addresses look similar; a range that is too broad may send unrelated requests to the same policy.

[Rule]
IP-CIDR,192.0.2.25/32,DIRECT
IP-CIDR,198.51.100.0/24,PROXY
IP-CIDR6,2001:db8::/32,DIRECT
FINAL,DIRECT

Can these addresses be used to test a service? No. They are documentation examples. The first line shows a single-address rule, the second an IPv4 network range, and the third an IPv6 prefix. IP-CIDR6 and IP-CIDR handle different address families; an IPv4 rule won’t automatically cover the same service’s IPv6 address. If a device receives both address types, check the destination actually used during testing so an address-family change isn’t mistaken for an intermittent rule failure.

When should I consider no-resolve?

IP rules may require resolving a domain to an address before checking its range. no-resolve expresses the intent not to trigger an additional domain lookup for that rule. It does not disable DNS throughout the app or guarantee that a request will never have address information. If the request already uses an IP or an address is available, interpret the match in light of the actual conditions. Before using it, decide whether the rule should handle only known addresses or include addresses obtained by resolving a domain.

[Rule]
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

Why not add the same option after every address rule? It changes the conditions under which a domain request reaches that rule. For a destination you want to identify by its resolved address, limiting additional lookups may mean the request reaches FINAL more often. For an exception that applies only to an existing IP, it may fit the intent. Compare the result for one target before and after the change. Don’t assume more options make a configuration more complete; confirm supported syntax in the app.

Does GEOIP tell you where a website is based?

No. GEOIP uses geographic data associated with the destination IP; it cannot infer a result from a site’s language, registration details, or page content. A domain using a CDN may resolve to different addresses, and results may change when the network changes. GEOIP,CN,DIRECT means requests matching the relevant address classification use DIRECT. It does not mean “connect to all Chinese-language sites directly” or that a domain will always use the same policy.

When should domain rules go before GEOIP? Put an explicit domain exception earlier when you want a domain to use a specific policy regardless of changes to its resolved address. GEOIP is useful for broad address classification, but it shouldn’t replace every precise rule. If a service behaves differently across networks, compare its resolved addresses and matched rules before adding a domain exception. Avoid repeatedly adjusting geographic ranges without evidence.

Can USER-AGENT reliably route traffic by app?

Don’t treat it as a general-purpose way to identify apps. USER-AGENT matches a corresponding field visible in a request, not an app’s name in the operating system. Whether the field is visible in an encrypted connection and whether a particular request includes it both affect whether the rule can work. Multiple apps may use the same string, and one app may use different strings. Confirm the actual field before choosing a match expression.

[Rule]
USER-AGENT,ExampleClient*,DIRECT
FINAL,PROXY

This example only shows where USER-AGENT appears and how a wildcard is written. It does not imply that a real request named ExampleClient exists. If the record doesn’t show a field you can verify, prefer confirmed domain or address conditions. Don’t broaden how encrypted traffic is handled just to make this rule match. An unavailable match condition and an unavailable server are different problems and should be checked separately.

05 Match Order, Exceptions & FINAL

Are rules automatically sorted by type?

No. The key to understanding Rule is that conditions are checked from top to bottom, and the matching rule’s policy is applied. DOMAIN doesn’t automatically move ahead of DOMAIN-SUFFIX just because it is more specific, and a later rule doesn’t automatically override an earlier one. Treat the file as an ordered series of decisions, not a set of labels that automatically calculates the best result. To explain any match, start at the top and find the first rule that fits.

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

How should I read this snippet line by line? First check whether the target is api.example.com. If so, use PROXY; later suffix rules won’t change the result. Otherwise, check whether it falls within the example.com domain, then consider address exceptions and GEOIP. FINAL handles requests that matched nothing above it. This also suggests a useful maintenance order: specific exceptions first, broader classifications next, and the fallback last. Each rule should have a clear reason for its position.

Why does FINAL need careful consideration?

FINAL is the policy for requests that don’t match any preceding rule. It isn’t a comment or a fallback used only when something goes wrong. If the configuration doesn’t cover every request, many may reach FINAL. FINAL,DIRECT and FINAL,PROXY define different defaults; there is no single right answer for every situation. Before choosing one, consider which targets your rules list and what should happen to everything else. Don’t copy a familiar-looking final line without understanding its effect.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

What’s the logic behind this minimal configuration? It sends only the listed example domains through a proxy and lets everything else use DIRECT. If you instead want “only explicitly allowed destinations to connect directly,” reorganize the preceding rules and choose the appropriate fallback; don’t change FINAL alone and assume everything else will still work as expected. Changing the fallback affects every destination not already listed. Expand your tests accordingly, including at least one exception and one unlisted destination.

Do duplicate rules make matching more reliable?

No. If the same condition already appears earlier, a duplicate later in the file usually won’t fix it. If the policies differ, it may mislead someone into thinking the later setting takes effect. Before removing duplicates, confirm the conditions really are identical: DOMAIN and DOMAIN-SUFFIX, for example, are not duplicates. You can group rules by purpose—exact exceptions, domain ranges, address ranges, and final policy—but don’t change a verified priority order just to make the file look neater.

How can I check whether a new rule is shadowed by an earlier one? Start at the first line and trace the target domain through the rules. Check whether a broad condition before the new rule already matches. If it does, decide whether to move the new rule up or narrow the existing one. Don’t put every new rule at the end, especially after FINAL, and expect it to participate in the normal matching process. For overlapping rules, document which one is the exception and why it takes priority.

Why didn’t the new order immediately affect an existing connection?

Rule evaluation is tied to connection setup. An established long-lived or reused connection may continue under its previous handling. After saving the configuration, start a new test request and, if needed, reconnect only when doing so won’t disrupt important activity. Don’t conclude that saving failed based on refreshing a page that is still reusing a connection. Keep the request, network, and server unchanged in comparisons, and distinguish an old connection still in use from a new connection matching the wrong rule.

How can I confirm the change didn’t affect unrelated traffic? In addition to testing the intended exception, test another subdomain with the same suffix, an unrelated domain, and an address-based destination. Testing only the request you care about can miss the effects of a broad rule. Keep before-and-after snippets in your change notes, not a full configuration containing sensitive information. This makes it easier to tell whether a future difference comes from scope, rule order, or the environment.

07 URL Rewrite: Uses & Limitations

What does URL Rewrite change, and what does Rule change?

Rule primarily selects the policy used for a connection. URL Rewrite applies an action to a matching URL. Redirecting a request to another URL doesn’t tell it to use PROXY; setting a domain to DIRECT doesn’t change the page path. If you need path-based behavior, first confirm that a rewrite is actually necessary rather than putting a full URL in DOMAIN. Both sections can be used together, but verify their effects separately.

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

What does this snippet do? It contains a match expression, a destination URL, and a redirect status code. It demonstrates redirecting a visible request beginning with http://example.com/ to the specified HTTPS address. The backslash before the dot makes the expression match the literal dot in the domain, and the ^ at the beginning anchors the match to the start of the URL. This example illustrates the structure; don’t assume it’s a universal rule you can apply to any site.

Why should an expression have a clearly defined scope?

In regular expressions, symbols such as dots, asterisks, and parentheses have special meanings; they don’t always match the literal characters you see. An unescaped dot may match any character, and a missing start boundary may allow a match in an unintended position. Before writing an expression, list examples that should and shouldn’t match, then check each one. Similar-looking domains don’t guarantee that the expression affects only the intended domain. The broader the match, the harder it is to trace effects on logins, APIs, and resource loading.

Why does the destination URL also need careful review? A redirect changes where the request goes next. The target domain, path, and query parameters can all affect page behavior. If a rule sends every path to the homepage, the original page location and parameters may not be preserved. Use replacement syntax supported by the app only when you need to retain captured content, and test it in a limited copy. Don’t paste an expression you don’t understand into a configuration you use long-term.

Can an ordinary rule read an HTTPS path directly?

Don’t assume it can. HTTPS encrypts request contents; ordinary domain-routing information doesn’t imply that the full URL path is visible. If a path-based rewrite doesn’t work, first check whether the request meets the visibility requirements instead of continually broadening the domain match. Verify the conditions for the request in the app. This guide does not treat decryption-related settings as necessary for ordinary routing, and does not recommend changing system trust settings casually for a single rewrite.

What should I do if I only want a domain to use a proxy? Use Rule and a clear DOMAIN or DOMAIN-SUFFIX condition; there’s no need to add URL Rewrite. Consider a rewrite only when you really need to change the request URL and can verify visibility and the target behavior. The closer a feature gets to request contents, the more carefully you need to limit its scope. Express a simple routing goal with a simple routing rule.

How should I troubleshoot redirect loops and unexpected path changes?

Temporarily remove the new rewrite line and check whether the original request works again in a configuration copy. If the rewritten target also matches the same expression, it may create a redirect loop. The server could also redirect back to the original URL, even if the expression itself isn’t looping. Record the starting URL, redirect destination, and point of failure rather than looking only at the final page. Keep only one candidate rewrite at a time to make its effects easier to isolate.

Why doesn’t changing HTTP to HTTPS always work? The target service must support HTTPS for the specified domain and path, with a valid certificate and correctly configured service. A rewrite cannot give a service capabilities it doesn’t have. If the connection fails after redirecting, test the destination directly, then check the expression. Don’t mask the problem by changing FINAL or GEOIP: URL changes and connection policies require separate checks.