Shadowrocket .conf File Structure: General, Rule, Host, and URL Rewrite Explained

At a glance

A Shadowrocket .conf file defines connection settings, rule matching, static hostname mappings, and URL rewriting. This guide is for users who already have their own connection configuration and want to adjust routing behavior. Identify the four sections, check the syntax with a minimal example, then select the edited file in Config and verify the results in Home. Check connection settings and routing rules separately: saving a file does not automatically make it the active configuration.

1. Separate the file from connection settings

Home, Config, and Settings manage different things. Use Home to select an existing connection, check its status, and set Global Routing. Config manages configuration files and their rules. Settings contains app preferences, such as the conditions for an on-demand connection under Settings → On Demand. When troubleshooting, first decide whether you need to change when a connection starts, where it connects, or how a particular request is handled.

Subscription updates commonly maintain connection entries; they do not necessarily update the Rule section in the active .conf file. Remote configuration updates may also overwrite local changes, so keep a local copy before editing. This guide assumes you already have your own provider and subscription; it covers only file structure and verification.

Section	Main purpose	Does not replace
`[General]`	Set basic behavior, such as DNS and IPv6	Routing rules for specific domains
`[Rule]`	Choose a policy based on domains, IPs, and other criteria	Authentication parameters for connection entries
`[Host]`	Set a static address mapping for a specific domain	Server-side certificate and site configuration
`[URL Rewrite]`	Match URLs and perform actions such as redirects	Routing rules that send traffic to PROXY

Section names in square brackets are syntax and must remain in English. A common, easy-to-read order is General, Rule, Host, then URL Rewrite; these sections are not a four-step processing pipeline. The order that matters most is the order of rules within Rule. Do not think of the entire file as a sequence that runs from the first section to the last.

2. General: Basic connection behavior

General commonly uses the “key = value” format. Keep punctuation in standard ASCII, use true or false for Boolean values, and do not append Chinese explanations to field values. The snippet below illustrates the fields; it is not a one-size-fits-all template to replace your existing settings.

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

General fields

bypass-system: true: Keeps the app's system-related traffic bypass behavior.
dns-server: system: Uses the system DNS provided by the current network.
ipv6: false: Disables IPv6 at the configuration level; it does not fix network issues with your carrier.

Note the original value first. Change one field at a time, then repeat the same test.

Rule keywords

DOMAIN-SUFFIX: Matches the full domain suffix and its subdomains.
IP-CIDR: Matches an IPv4 address range.
FINAL: Catches requests that did not match any preceding rules.

General defines basic behavior; Rule determines which policy handles a request. They are not interchangeable.

dns-server = system does not guarantee that DNS on the current network will work; it only specifies the resolver. If a domain is unreachable but a connectivity test still responds, check the DNS results first rather than changing only the final Rule policy. A latency result from a connectivity test also does not prove that the target site's DNS, TLS, and HTTP requests are all working.

ipv6 = false is not a universal fix for websites. IPv4 and IPv6 reachability, proxy egress support, and target addresses can differ. If the original file has IPv6 settings for your network, keep them and compare one change at a time against a reproducible failure.

3. Rule: Match conditions and policies

A common Rule format is “type,match,policy,” with fields separated by standard ASCII commas. Rules are typically evaluated from top to bottom, and the matching rule's policy is applied. FINAL has no additional match value and belongs at the end to catch remaining requests. This example sends a specified domain to PROXY, sends the documentation-only address range and addresses with GEOIP set to CN to DIRECT, and sends everything else to DIRECT.

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

DOMAIN-SUFFIX,example.com,PROXY matches example.com and its subdomains. It does not match every domain that happens to contain that string.
IP-CIDR matches an IP address range. The example 192.0.2.0/24 is reserved for documentation and should not be treated as a live service network.
no-resolve means no additional DNS lookup is made for this IP rule. It does not disable DNS for the entire configuration.
GEOIP,CN,DIRECT matches based on the geographic classification of the destination IP in the geolocation database, not the webpage language, domain suffix, or user's current location.
FINAL,DIRECT sends unmatched traffic directly. Changing it to FINAL,PROXY changes where all unmatched requests go.

Put more specific exceptions before broader rules. For example, to send a subdomain to DIRECT while sending other requests for the same root domain to PROXY, add DOMAIN,static.example.com,DIRECT first, followed by DOMAIN-SUFFIX,example.com,PROXY. If the order is reversed, the suffix rule may match the subdomain first.

4. Host: Static hostname mappings

Host uses the “domain = address” format for mappings to a known, fixed address. It serves a different purpose from Rule: Host answers “What address does this domain resolve to?” while Rule answers “Which policy handles this request?” Changing one should not be expected to update the other automatically.

[Host]
lab.example.com = 192.0.2.10

The domain and address above are for illustrating the syntax only. 192.0.2.10 is a documentation-only address, not a working service. Use a destination address you have verified when filling this in, and confirm that the target server can correctly handle requests for the domain.

Static mappings do not update automatically when a site's address changes. If the site moves, the mapping may cause ongoing connection failures.
Multiple domains sharing an IP does not make them interchangeable. HTTPS still requires the domain, certificate, and server site configuration to match.
Webpages often request images, scripts, and APIs from other domains. Mapping only the main page's domain does not mean all resources will use the same address.
After removing a test mapping, reconnect to the affected services so an existing connection is not mistaken for a failure of the new configuration.

If you see a certificate error, do not hide a bad mapping by disabling certificate validation. Remove the new Host entry first, restore the original DNS resolution, and then verify the target domain's certificate and server address. Hard-coding addresses for public sites that change frequently can create extra maintenance work.

5. URL Rewrite: Keep rewriting separate from routing

URL Rewrite applies an action based on a URL-matching expression; it does not use Rule syntax such as DOMAIN-SUFFIX. The snippet below uses a regular expression to match an HTTP URL and return a 302 redirect to an HTTPS URL. It illustrates the format and is not a ready-to-deploy production rule.

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

Here, ^ anchors the match to the start of the URL, \. represents a literal period, and the trailing 302 is the redirect status code. This simple example redirects matched requests to a fixed address without preserving the original path or query parameters. Do not use it for login, payment, or API requests that need those parameters.

What to check	Rule	URL Rewrite
Match target	Domain, destination IP, and other criteria	Request URLs that can be processed
Example result	Use DIRECT or PROXY	Return 302 and redirect to another URL
Common mistake	A broad rule matches too early	Overly broad regex, lost paths, or redirect loops

The full path and query parameters in HTTPS are inside the encrypted request, so ordinary routing cannot read them. Rewriting HTTPS request content requires separate HTTPS decryption settings, certificate trust, and domain-scope management; adding a URL Rewrite line alone will not do it. If you are only verifying routing, you do not need to configure HTTPS decryption for this example.

6. Apply changes in Config

After editing, verify both that the file was saved and that it is the file currently in use. Seeing a file in the list only confirms that it exists. Likewise, if Home's Global Routing is still set to Proxy or Direct, the resulting traffic cannot confirm whether Rule behaved as expected. The steps below are for making a small change to an existing file.

Keep the original file

Open Config, note which file is currently selected, and save a local copy before editing. If the file comes from a remote update, test changes in a separate copy to avoid having the next update overwrite them.
Edit the copy

In Config, open the copy in the editor and change only one section. Check the square brackets, standard ASCII commas, equals signs, and policy names. Save the file, then reopen it to verify the contents.
Select the configuration

Return to the Config file list and select the edited file. Make sure the selection indicator is next to the copy, not the original or another remote file with a similar name.
Choose a routing mode

Go to Home → Global Routing → Config and check which connection entry is selected in Home. Reconnect if needed so subsequent requests use the new configuration.
Test a request

First, use Home → Connectivity Test to check the connection. Then revisit the same destination and check the domain, matched rule, and policy in the connection log. If it fails, restore the original file and test again.

Config

Recommended

Routes traffic according to the currently selected configuration. Use this mode to check Rule order, DOMAIN-SUFFIX, and FINAL behavior.

Best for: verifying the configuration changes and everyday rule-based routing described in this guide.

Proxy

Sends traffic handled by the app and not bypassed through a proxy, rather than applying the usual per-rule routing decisions. Basic behavior such as system-level bypasses still needs to be considered separately.

Best for: temporarily comparing connection availability to distinguish a proxy issue from a routing-rule issue.

Direct

Uses direct routing. If the destination opens in this mode, that only shows the current direct path works; it does not confirm that the PROXY entry or a specific proxy rule is working.

Best for: comparing the direct connection to the same destination to help narrow down the issue.

If you are using Scene, first check which configuration and policies that Scene actually uses. Do not infer its scope from the file name alone. To reduce variables during the initial check of these rules, use the explicit Config mode. On Demand controls automatic connection conditions; it does not determine which Rule matches a domain.

7. Common issues and rollback checks

Changed FINAL, but the site still takes the same route?

First check whether Home → Global Routing is set to Config, then verify which file is selected in Config. FINAL only catches requests that have not matched an earlier rule. If DOMAIN-SUFFIX or GEOIP already matches the request, changing FINAL will not affect it. Reconnect before checking the log again.

The file fails validation when saving. What should I check first?

Check that section names have complete square brackets, Rule fields are separated by standard ASCII commas, and General and Host use equals signs. Temporarily remove the new snippet to confirm the original content still saves, then add it back one line at a time. Avoid pasting large blocks from multiple sources at once.

Why did my manually added rules disappear after an update?

First identify whether you updated a subscription entry in Home or a remote file in Config. Updating a remote file may replace its contents. Restore the rules from your saved local copy, then merge in any new content you need. Do not mistake a connection-entry update for a backup of your rules.

I get a latency result, but the webpage will not load. Should I rewrite the entire file?

No need to rewrite it right away. First undo any Host or URL Rewrite entries you just added, then check DNS resolution, the policy actually matched, and the destination connection. A latency result from Connectivity Test covers only the tested connection path; it does not replace loading a real webpage. For more help, continue with the troubleshooting manual.

A useful change log should include at least the original file name, the fields changed, the test domain, the Global Routing mode, and the actual result. Keeping these five details makes it easier to roll back and reproduce a problem next time, instead of changing DNS, rules, and connection entries all at once and losing track of what caused it. For more background, see the glossary. For connection issues, continue with connection troubleshooting.