Shadowrocket
Rules and Configuration Reference

Configuration Structure and General

A configuration file describes how requests are resolved, matched, and handled. Server details provide the parameters for an actual connection; neither replaces the other. Having PROXY in a file does not mean you have a usable server. Conversely, importing a server does not mean a particular rules file is active. Before editing, check the active configuration in Config and the connection target in Home. Keep “which rules are in use” separate from “where the connection goes.”

What Each of the Four Sections Does

Bracketed headings divide the file into sections. [General] contains general options, [Rule] contains rules checked in order, [Host] maps names to static addresses, and [URL Rewrite] rewrites or redirects matching URLs. These sections are not interchangeable rule sets. Rule specifies which policy a domain uses; Host or DNS determines which address a domain resolves to.

[General]
bypass-system = true
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

[Host]
example.com = 192.0.2.10

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

This snippet shows section names and syntax; it is not a ready-to-use configuration. example.com is a sample domain, and 192.0.2.10 is a documentation-only address. Host and URL Rewrite are shown to illustrate syntax, not as sections you must enable together. When experimenting, keep General and a few Rule entries, verify the basic connection, then add only the sections you need to test. This helps prevent examples from affecting one another.

Understand General Options by Their Purpose

dns-server = system uses the system DNS configuration. It’s a useful starting point for checking current network behavior, but it doesn’t prove that every remote request is resolved by the same local resolver. The server protocol, connection method, and request path can all affect where resolution occurs. If resolution behaves unexpectedly, check the domain and destination address in the request log rather than drawing conclusions from this line alone.

bypass-system = true is an option for bypassing system-related traffic. It does not mean “send all local addresses direct,” nor does it replace explicit IP range rules. It affects how system traffic is handled and may change which requests you see. If you only want a LAN subnet to use DIRECT, add that subnet in Rule and verify the requests. Don’t change unrelated General fields at the same time.

Saving, Applying, and Updating Are Separate Actions

Saving in the editor only confirms that the content was written; it doesn’t confirm that the file is selected. After editing, return to Config to check the active configuration, then confirm that Global Routing is set to Config. For remotely maintained configurations, distinguish local edits from the upstream file: an update may overwrite local changes. Keep custom rules you want to retain in a separate backup and note where they belong. Don’t leave your only copy in text that could be replaced during an update.

When troubleshooting a configuration, first save a recoverable copy, then change just one field. Note the network, Global Routing mode, test domain, and expected policy before editing. Afterward, repeat the same request and verify it again. If the result differs from what you expected, restore that field and retest; this is easier to diagnose than adding several unexplained options. Avoid merging General sections from unrelated sources: duplicate keys or conflicting settings make results hard to explain.

Rule and Rule Types

A Rule typically consists of a type, a match value, and a policy, separated by commas. FINAL needs no match value, so it usually has just two fields: the type and the policy. Keep rule keywords in English, and don’t add a scheme, path, or query string to a domain field. The examples below assume Config is selected and PROXY has a working connection available; a correct match alone does not guarantee that the request will succeed.

DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD

DOMAIN matches one exact hostname, making it useful for a specific subdomain. DOMAIN-SUFFIX matches on a domain suffix boundary and is commonly used for a root domain and its subdomains. For example, a suffix rule for example.com also matches api.example.com, but not every hostname that merely ends with the same characters. DOMAIN-KEYWORD matches a keyword anywhere in a domain name. Its scope is usually broader, so check which other hostnames it may include.

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

With this order, api.example.com matches DOMAIN first; the later DIRECT rule is never considered. The second line handles other subdomains of example.com. The third line can only match requests containing example in the hostname if neither of the first two rules matches. Don’t treat this as a general recommendation: the example deliberately uses overlapping conditions to show why order matters when a request matches multiple rules.

GEOIP and IP-CIDR

GEOIP matches based on the target IP’s location in an IP database, as in GEOIP,CN,DIRECT. It does not check a webpage’s language, the site’s country of registration, or the user’s location. A domain may resolve to different addresses, and databases have coverage and update limits. If the same site uses different policies on different networks, compare the actual destination IPs before concluding that the rule failed.

IP-CIDR specifies an IPv4 address and prefix length. 192.168.0.0/16 covers a range of addresses, not just 192.168.0.0; use /32 for a single IPv4 address. IP-CIDR6 is for IPv6. For IP-based rules, you can match against a known destination address. For requests that only have a domain, check the rule options and request logs to see whether an additional lookup is performed for matching.

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

no-resolve prevents an IP rule from actively triggering a domain lookup just for matching. It does not ignore a destination IP that is already available, nor does it guarantee that a domain request will match the subnet rule. If you access a LAN service by hostname, you may also need an explicit DOMAIN rule. Before adding a subnet, check for overlap with remote resource addresses. The broader the range, the greater the risk of matching unintended requests.

USER-AGENT and FINAL: What They Do

USER-AGENT matches a request’s visible User-Agent value. It is not a reliable way to authenticate an app, and it does not mean every encrypted request reveals the app’s name. Results depend on whether the field is present, visible, and unchanged. If you need to handle a consistent set of hosts, check the domain conditions first. Don’t broaden the scope to unverified traffic just because a USER-AGENT rule didn’t match.

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

FINAL is the fallback for requests that haven’t matched any earlier rule, and usually belongs at the end of Rule. It is not an error handler and won’t take over if a server connection fails after an earlier rule matches. Putting FINAL first prevents later ordinary rules from being checked. In a long configuration, find FINAL first and confirm that all rules you want to run appear before it. This is often faster than reading every line from the top.

Host and DNS Resolution

Host answers “which address does this name resolve to?” Rule answers “which policy handles this request?” Setting an address in Host does not select DIRECT or bypass a server or network restriction. To check whether a mapping does what you intend, verify three separate facts: the hostname in the actual request, the mapped address, and the policy that ultimately matched. Seeing an address change alone doesn’t confirm that the entire connection is working correctly.

A Minimal Static Mapping

[Host]
example.com = 192.0.2.10
api.example.com = 192.0.2.20

The hostname goes on the left and the address on the right. The sample address is for documentation and does not point to a usable service. Before using a real mapping, confirm the address from a network you manage or from existing service documentation; a single lookup does not guarantee that an address will remain valid. Listing specific hostnames individually also helps distinguish exact name mappings from domain-wide routing rules. Check the resolution of each hostname you need to handle.

A mapping changes address information; it does not automatically change the hostname in the original request. For HTTPS, certificate validation and hostname verification by the server still matter. Even if a connection can be made to the destination address, the service may not serve the original hostname correctly. This can lead to a certificate mismatch, the wrong site, or a terminated connection. If that happens, remove the mapping to compare results. Don’t lower verification requirements to hide an incorrect address.

Host Does Not Pin an Entire Website

A webpage often contacts multiple hosts: the main document, images, APIs, login, and static files may each use different names. Mapping the main host does not mean other resources use the same address. If the page loads but some content is missing, check the request log to find the hostname used by each failed resource, then see whether the mapping is involved. Don’t broaden mappings blindly to fill in missing content, and never point every subdomain to the same unverified address.

A static address also changes the load balancing normally handled by DNS. DNS results may vary by network, location, or service status; a fixed local mapping won’t reflect those changes automatically. A mapping can help test whether a particular DNS result is the problem during short-term troubleshooting, but keeping it long term requires a clear reason and a maintenance plan. For services you don’t control whose addresses can change, a static mapping usually isn’t a permanent fix.

Check DNS, Caches, and Request Paths Separately

After changing Host, refreshing an old page may reuse an existing connection rather than make a new request. The app, system, or network path may also have cached data. To verify the change, note the address before editing, close the relevant pages or end existing requests, then make a new request to the same host and check the latest log entry. If nothing changes, confirm that the right configuration is active and the request follows the expected path instead of repeatedly saving the same line.

Some connections resolve domain names remotely; some apps perform their own resolution or connect directly to an IP. So “I added a hostname to Host” doesn’t mean “every connection uses that mapping.” Check the actual connection type to see where the name and address are visible. A request to an IP address has no corresponding domain lookup in the first place, so adding a hostname mapping usually won’t change its destination.

In a Host test, change only one hostname, define the expected address, and keep a record of how to undo the change. If removing the mapping fixes the issue, the mapping was involved, but you still need to determine whether the address is invalid, the certificate mismatches, or the route is unreachable. Record the cause before deciding whether to keep the mapping. Otherwise, a temporary diagnostic entry can become difficult to trace when the address changes weeks later.

URL Rewrite

URL Rewrite processes matching requests using URL expressions. A common use is redirecting a specific HTTP URL to HTTPS. It is not another way to write a DOMAIN rule and cannot replace the policy selection made by PROXY, DIRECT, or REJECT. Before configuring it, be clear about the goal: change the URL or change the connection path? If you only want a domain to use a different policy, you usually need to edit Rule, not add a redirect.

Start with a Narrowly Scoped Redirect

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

This example consists of a match expression, a destination URL, and a status code. The leading ^ matches from the start of the string, and the trailing $ matches to its end. \. represents a literal period in a domain name, rather than the any-character wildcard used in regular expressions. The example matches only the HTTP root URL for the specified hostname and redirects it with a 302. It does not cover every path or query string on that host.

A narrow expression makes test results easier to interpret. If you match only the domain without restricting what follows, the rule may cover more paths. If you also set the destination to the root URL, the original path and query may be lost. Before designing an expression, list the root URL, a subpath, and a URL with query parameters, then decide which parts to preserve and test them. Don’t start with a broad match and troubleshoot by trial and error.

Request Visibility Determines What You Can Match

An HTTP URL and a complete URL inside an encrypted connection are not equally visible. Seeing the destination domain does not mean you can also read the HTTPS path, query string, or User-Agent. Check separately whether the relevant request data is available. The examples here start with explicit HTTP requests; there’s no need to change certificate trust or expand decryption just to make a rewrite work.

A browser may upgrade HTTP to HTTPS based on an existing security policy, so the request actually sent may differ from what was first entered in the address bar. If you don’t see the expected 302, that alone doesn’t prove the expression is wrong. First confirm that a matching HTTP request was actually sent. The browser, navigation history, and redirects from the site itself can all affect what you observe. Test records should include the original request and each subsequent request.

A Redirect Triggers a New Request

After receiving a redirect, the client usually sends a new request to the destination URL. That request must resolve its address again and is processed by the rules in effect. The policy that matched the original request does not necessarily carry over unchanged to the destination request. If the redirect changes the hostname, check whether another DOMAIN or DOMAIN-SUFFIX rule applies to the new host, and whether its resolution and connection work.

Redirect loops often result from conflicting conditions—for example, a local rule redirects an address to HTTPS while the server sends the same entry point back to HTTP. You may see repeated redirects, a failed page load, or a browser message that there are too many redirects. Disable the new rewrite first, confirm the site’s original behavior, and check the destination at each step. Don’t add a broader rewrite just to mask the symptom; that makes the source of the loop harder to identify.

Take extra care with login pages, forms, or URLs containing temporary credentials. Query parameters may contain sensitive information; remove them before sharing test records. Don’t infer the interaction between request methods and redirect status codes from a URL change alone. Start by testing an ordinary page you control, without a signed-in session. Confirm that the expression affects only the intended request before considering it for a real use case.

Policies and Global Routing

A policy determines how a matching request is handled; Global Routing determines the overall routing mode currently in use. When troubleshooting, check Global Routing first, then the policy field in the rules. Otherwise, you could carefully inspect Rule while testing a configuration that isn’t being used as expected. In this guide, the interface terms are Config, Proxy, and Direct.

PROXY、DIRECT、REJECT

PROXY sends a request through a proxy path and requires an existing, usable connection target. It is not a server address and doesn’t supply missing authentication details. DIRECT connects to the destination directly, but that doesn’t guarantee it’s reachable; network routes, DNS, and the destination service still matter. REJECT blocks a matching request. Use it for a target you explicitly want to block; it does not mean “try another path if this one fails.”

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN,printer.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
FINAL,PROXY

The names in this example illustrate three different actions. A match for api.example.com uses PROXY; if the connection fails, the next DIRECT rule is not tried automatically. printer.example.com uses a direct connection, but success still depends on its resolved address and whether the current network can reach it. blocked.example.com is explicitly rejected, so a failure is the expected result—not a server problem.

How to Compare the Three Global Routing Modes

If a site works in Proxy but fails in Config, check which policy the request actually matches in Config. Don’t immediately assume a rule keyword is wrong. The two modes may use different resolution points, destination addresses, or connection paths. For a meaningful comparison, record the hostname, actual address, and handling policy. Find where the results start to differ rather than noting only whether the page eventually opens.

If a request fails in Direct but succeeds in Proxy, that doesn’t mean you should change the entire configuration to PROXY. LAN devices, services available only on the current network, and other specific resources may still need DIRECT. Temporarily switching Global Routing can help narrow down a problem; for a long-term policy, add rules only after understanding the needs of each resource. Restore the original mode after comparing results so you don’t troubleshoot future rules under the wrong conditions.

Check Policy Names Separately from Connection Availability

Some configurations refer to custom policy names. Don’t assume every value that looks like an English label is built in. Check whether the current configuration defines the name, what connection target it points to, and whether that target still exists. If you’re learning basic routing, start with PROXY, DIRECT, and REJECT. They’re easier to verify than a configuration with several layers of selection.

A connection target can fail even when a rule matches correctly. Authentication details may have changed, the server may be temporarily unreachable, or the service may not support the current parameters. That means the right policy was selected but the connection failed. Changing the DOMAIN match scope won’t fix a server problem. Check the address, port, and authentication against your existing service details, then run Connectivity Test and record its result separately from the actual request.

Likewise, a successful connectivity test only confirms that the specific path tested received a response. It doesn’t guarantee that every destination, protocol, or task will work. Web requests, persistent connections, and other transport methods may have different requirements. If only one service fails, identify its hostname and request type instead of ruling out server-side or destination-side problems based on a single successful test.

Servers in an existing subscription and local rules are two separate things to maintain. Updating a subscription may change the available connection targets; it does not fix the order of local rules. Editing Rule does not update expired server details. For more on what each update changes, see Subscription Updates and Why Connections Fail. This helps distinguish changes to server details from changes to a configuration file.

Match Order and Priority

Rule checks entries from top to bottom; the first match determines the policy. “Put more specific rules first” is a configuration practice, not an automatic sorting feature. DOMAIN won’t jump ahead of an earlier DOMAIN-SUFFIX just because it’s more specific. IP-CIDR won’t automatically yield to a later domain condition either. To get the priority you want, place exceptions above the broader rules that would otherwise match them.

Trace Each Rule Against the Same Request

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

For api.example.com, the first line matches exactly, so the later domain suffix, keyword, IP location, and FINAL rules don’t determine its policy. For www.example.com, the first line doesn’t match; the suffix rule on the second line does, so the request uses DIRECT. The keyword rule on the third line can apply only if neither of the first two matches. When tracing a request, write down whether each condition matches and what action it selects. This is more reliable than skipping ahead based on a keyword.

If you move the second line above the first, api.example.com matches the suffix rule first, and the exact exception no longer takes effect. DOMAIN hasn’t changed; the evaluation order has. When a new rule appears to do nothing, first check whether an earlier rule already matches the request instead of adding the same condition repeatedly at the end of the file.

Ordering Broad and Narrow Rules

A common layout puts explicit exceptions first, followed by domain groups or broader conditions, then any IP rules, with FINAL at the end. This is an organizational pattern, not a mandatory order for every use case. If a particular managed subnet must use DIRECT, it may need to appear before a broader rule that would match it. State the requirement first, then check how the conditions overlap for specific requests; don’t follow a template mechanically.

A single destination can match both a domain condition and an IP condition. For example, its hostname may belong to a domain suffix while its resolved address falls within a GEOIP range. Which rule takes effect depends on the information available and the order of the rules. If an IP rule uses no-resolve, also consider whether a domain-only request triggers an additional lookup. Don’t confuse the order in the file with information that may not be available when the request is processed.

FINAL Is Not a Second Chance

FINAL handles only requests that have not matched an earlier rule. If a rule selects PROXY and the server connection then fails, that does not mean the request was unmatched, so Rule will not continue to DIRECT or FINAL. If you need a backup connection path, check what the relevant connection or policy settings actually support. Repeating FINAL won’t recover from a connection error. Rule selects a policy; connection failures happen afterward.

When troubleshooting, distinguish “the expected rule didn’t match” from “the expected rule matched but failed to execute.” In the first case, check the hostname, rule type, order, and active configuration. In the second, check the connection target, resolved address, and destination service. Mixing these up can lead you to change routing conditions and connection paths at the same time. Even if something works afterward, you may not know why.

For long rule lists, note which broader rule each exception overrides and why the exception is needed. Before removing duplicates, compare all fields, not just the domain. The same domain with different policies, or the same subnet with different options, may not be redundant. After reorganizing, test a few representative requests: an exact exception, a regular subdomain, and a target that should reach FINAL.

Common Patterns and Editing Workflow

The examples below break configurations down by goal. Each snippet shows one main intent; combining them all won’t make a configuration suitable for every network. Before using a snippet, replace its targets with the ones you need, preserve your existing server details, and check whether other rules in the active file might match first. If your configuration already has FINAL, place exceptions before the existing final rule rather than appending a second overlapping ending.

An Exact Exception Within a Domain

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

The goal is to send one specific API host through PROXY and other hosts in the same domain through DIRECT. Put the exact match first and the broader rule after it. Test api.example.com and another known subdomain, then check whether they use different policies. Don’t assume the exception is working just because the API succeeds: the overall Proxy mode could also make it succeed without the suffix rule being used.

If the API redirects or the page calls other domains, check the subsequent requests too. An exact match on the first request proves only that the first request was handled correctly. For a service that depends on multiple hosts, use the actual request logs to identify each one. Don’t assume a visible entry point represents every resource the service uses. Before expanding the scope, confirm that each additional host is needed.

Handle LAN Subnets and Hostnames Separately

[Rule]
DOMAIN,printer.example.com,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
FINAL,PROXY

This example expresses a direct-connection intent for a hostname and an address range separately. The hostname is an example; use a name from an environment you control. A subnet rule with no-resolve does not guarantee that every domain will be resolved and matched, so you can add an explicit LAN hostname separately. Before testing, confirm that you’re connected to a network that can reach the device. DIRECT won’t create a route to a different LAN.

If the same address range is used on another managed network, a subnet rule may also match destinations with a different purpose. This matters especially when private address ranges overlap across networks. Don’t choose a route just because an address “looks like a LAN address.” List the devices you need to reach, the network they’re on, and their actual addresses; then use the narrowest range that works. For a single device, consider a more specific prefix instead of covering a large range.

Route by IP Location, Then Use a Fallback

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

This snippet shows an exact exception, an IP location condition, and a fallback. It does not classify requests by website content or language. For services using distributed addresses, different resolved IPs may produce different GEOIP matches. Record the actual address when testing, not just the URL. If your goal is to handle a known set of domains, explicit domain rules may be easier to reason about, but choose based on your resources and network conditions.

Using PROXY for FINAL also has clear requirements: you need an existing, usable server and must want unmatched requests to use that path. If you want a different fallback, you can choose another policy, but be aware that it will affect many requests that weren’t explicitly listed. Changing FINAL can have a broad impact. Don’t assess it based on just one page; test representative resources you use regularly.

Keep, Edit, Verify, Roll Back

1. Save the current configuration text and note the selected file, Global Routing mode, and connection target.
2. Write down one testable goal, such as “change this hostname from DIRECT to PROXY.”
3. Search existing rules, find the earliest condition that could match the hostname, and choose where to insert the new rule.
4. Make one change and save it. Confirm that the same file is still active.
5. Make a new request and check the matched rule, destination address, policy, and result.
6. If the result is unexpected, restore the original text and retest with the same target. Keep a record of the difference.

Don’t use a rollback file as a substitute for a source that is updated automatically. After a subscription or remote configuration update, check that custom rules are still in the intended position and that their connection targets haven’t changed. A completed update only confirms that the fetch finished; it doesn’t verify functionality. If you have several changes to make, apply them in stages and keep a working state between each stage. That makes it easier to find which change caused a problem than replacing the entire configuration at once.

Verification and Troubleshooting

Verification means more than seeing that the connection switch is on. Confirm that a specific request uses the expected configuration, matches the intended condition, and gets a result through the expected path. Choose one test target and check in this order: server, Global Routing, DNS, rules, destination service. After each step, note what you’ve confirmed and what remains uncertain. Don’t update a subscription, switch servers, and change DNS in the same test.

From Connection Target to Actual Request

First check the address, port, authentication, and protocol parameters for your existing server, then run Connectivity Test to get an initial indication of reachability. If it fails, check the current network and service details before rearranging Rule. If it responds, make an actual request and see whether only one host is failing. A basic test and a real service request are different: a response to the first doesn’t prove that every path and parameter required by the second is correct.

Next, check Global Routing. If the current mode is Proxy or Direct, note it before switching to Config to test your rules. If the result is unexpected in Config, check the hostname and destination address in the actual request and confirm they match your test target. A page may redirect or call a separate API; the failing hostname may differ from the one in the address bar. Don’t keep adding rules for the entry-point domain without checking the request logs.

Use Logs to Tell Three Types of Failure Apart

The first type is a rule that didn’t match as expected: the wrong configuration may be active, the match value may be incorrect, or an earlier rule may have taken precedence. The second is a matching policy followed by a failed connection: check server reachability, the address, and the destination service. The third is a DNS resolution problem: check whether the domain resolved, whether the address is expected, and whether Host overrides the result. Separating these cases usually narrows down what you need to change.

If the log shows REJECT, find the matching condition in the configuration and check whether it was meant to block that target. If it shows DIRECT for a resource that is only reachable through an existing remote connection, check whether that policy was intended. If it shows PROXY but server authentication fails, check your existing service details first. Error messages can help narrow down the cause, but they don’t replace checking the matched rule and connection target.

Test On Demand Separately from Rule Routing

On Demand triggers a connection or disconnection based on conditions; Rule handles requests while the connection is active. If automatic connection doesn’t trigger, don’t assume a domain rule is wrong. Check whether the current network meets the On Demand conditions and whether a connection was actually established. Conversely, an active connection doesn’t mean every request uses PROXY; in Config, some requests may still use DIRECT or REJECT.

To verify automatic behavior, first connect manually and confirm that the same configuration handles requests correctly. Then test the trigger after switching networks. Record the network, connection status, and request time before and after the switch; don’t change On Demand conditions and Rule at the same time. For scenario details, see On Demand: Wi-Fi, Cellular, and Domain Conditions. For background connection trade-offs, see Background Battery Use and Persistent Connections.

Common Questions to Check

Before sharing troubleshooting notes, remove the full subscription URL, authentication details, personal network names, and other sensitive information. In most cases, a redacted hostname, rule type, policy, and failure stage are enough to explain the problem. After troubleshooting, restore the original Global Routing mode, remove temporary Host or rewrite test entries, and save a verified configuration. If a similar issue comes up later, compare it with this baseline and test each possibility in turn.