Shadowrocket .conf Guide: General, Rule, Host, and URL Rewrite Sections

Learn how Shadowrocket .conf files are structured, what [General], [Rule], [Host], and [URL Rewrite] do, and how rules are matched from top to bottom.

At a glance

This guide is for anyone reviewing or editing a local Shadowrocket configuration. First check which file is active and whether Global Routing is set to use it. Then choose a section based on the issue: check [Rule] if a connection takes the wrong route, [Host] and [General] if a hostname resolves to the wrong address, or [URL Rewrite] if you need to redirect based on a URL path.

.conf Sections and Syntax

A section name in square brackets determines how the following lines are parsed, up to the next section name. Both [General] and [Host] can contain an equals sign, but the text to its left means something different: a setting in the former and a hostname in the latter. [Rule] entries typically use commas to separate the type, match value, and policy; [URL Rewrite] redirect entries use spaces to separate the match expression, target URL, and action.

4 sections
Configuration sections covered
3 fields
Example DOMAIN rule: type, domain, policy
2 fields
FINAL rule: keyword, policy

To add a rule to an existing file, find its [Rule] section first, then choose where to insert the new entry. Don't append the entire example to the end of the file: the last lines may belong to another section, so the entry won't be read as a rule even if it looks like one.

Edit and Enable a File in Config

Seeing a file in the configuration list doesn't mean it's being used for the current connection. The steps below use the iPhone and iPad interface labels. For your first change, edit just one line and keep an untouched copy of the file so you can restore it and retest under the same conditions.

  1. Check the File

    Open Config, confirm the file you want to edit, and save an untouched copy first. If a remote configuration may update, test a local copy to avoid losing your changes when it refreshes.

  2. Edit the Source

    In Config, tap the file name and choose Edit Plain Text. Find the relevant section and add or change just one entry. Keep the original English punctuation and delimiters, then save.

  3. Enable the Configuration

    Go back to Config, tap the edited file, and choose Use Config. Make sure the edited file is active, not the backup copy.

  4. Start a New Request

    Go to Home → Global Routing → Config. Reconnect to the same destination. If the app reuses an existing connection, end it before testing again.

Config is both the name of the configuration screen and a mode under Global Routing. Use the screen to select a file; the mode determines whether traffic is routed according to that file's rules. When troubleshooting [Rule], check both locations.

Config

Recommended

Choose a connection policy based on the rules in the selected configuration. The order of exception entries, suffix entries, and FINAL can affect the result.

Best for: checking whether a rule in the active configuration matches.

Direct

Use direct mode. A successful direct connection only shows that the destination is reachable directly on your current network; it doesn't prove that a particular DIRECT rule in the configuration matched.

Best for: checking whether a destination is reachable directly, using the same target.

Proxy

Use proxy mode for connections handled by the client. Before testing, make sure your own server is selected in Home, then start a new connection to the same destination.

Best for: checking the proxy route without relying on routing rules.

[General] and [Host]: DNS Settings and Per-Hostname Mappings

[General] contains configuration-wide settings. For example, dns-server = system specifies the system DNS. [Host] assigns an address to a specific hostname. The former sets the usual DNS behavior; the latter creates a dedicated mapping when Shadowrocket handles resolution. Neither section replaces [Rule] for choosing a connection policy.

[General]
dns-server = system

[Host]
docs.example.com = 192.0.2.10

192.0.2.10 is a documentation-only example address, not for connectivity testing. The mapping above covers docs.example.com, not api.example.com. To test the mapping, send a request to the original hostname rather than changing the browser address to an IP. Doing so changes the hostname used for the request and may also affect HTTPS certificate validation.

Choose Checks Based on the Scope of the Issue

Several hostnames fail to resolve
  • Check dns-server in [General] and note whether the issue occurs only on a particular network.
  • With the same configuration, send a new request on each of two networks. Check whether the issue changes with the network used by system DNS.
Only one hostname fails
  • Check whether [Host] contains that exact hostname, paying particular attention to www and other subdomains.
  • In a copy of the file, remove the mapping and retry the same hostname to rule out interference from an old connection or cached data.

First determine whether the name resolves incorrectly or the address is correct but the connection fails. Each issue calls for different checks.

[Rule]: Top-to-Bottom Matching; First Match Wins

Rules aren't automatically sorted with the most specific entries first. To make a hostname an exception to a suffix rule, put its DOMAIN rule before the broader DOMAIN-SUFFIX rule. Connections that don't match earlier entries fall through to the final FINAL rule.

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

If you swap the first two entries, docs.example.com matches DOMAIN-SUFFIX first, so the later exact-match rule never takes effect. FINAL,DIRECT is only the fallback for this example configuration. Before editing an existing file, check its current fallback policy; don't change the route for other connections just to add an exception.

IP-CIDR matches the subnet containing the destination IP, for example IP-CIDR,192.0.2.0/24,DIRECT. GEOIP matches based on the IP's geographic location, not the domain suffix. When troubleshooting a domain request, first check whether a domain rule above has already matched, then check whether an IP rule has a destination address to match.

[URL Rewrite]: Redirect by URL Path

[Rule] determines how a connection is routed; [URL Rewrite] matches HTTP request URLs the client can process. The example below specifies the protocol, hostname, and path, then uses 302 to redirect to a new address. It demonstrates the syntax only and doesn't rely on a live page at the example domain.

[URL Rewrite]
^http://docs\.example\.com/old$ http://docs.example.com/new 302

An HTTPS request's path is encrypted, so knowing the destination hostname alone isn't enough to match it. If your test tool upgrades HTTP to HTTPS before sending the request, the expression above won't match as written. Check the actual protocol and URL being sent before deciding whether to change the expression.

Why Changes May Not Take Effect

Why does traffic still use the proxy when I added DIRECT?

First check whether Home → Global Routing is set to Config, then inspect [Rule] in the active file. If a DOMAIN-SUFFIX rule above already covers the hostname, move the exact DOMAIN exception ahead of it and reconnect to test.

Can I paste a new rule directly below FINAL?

Don't put regular rules after the fallback. If the file has a FINAL rule, insert the new entry before it, then check whether an earlier rule also covers the destination. After saving, test one destination that should match the new rule and another that should fall through to the fallback.

Why doesn't the browser address change after I edit Host?

[Host] changes the address mapped to a hostname, so it's normal for the browser's address bar to keep showing the original URL. To verify the mapping, use a destination service you control and check whether the new connection reaches the expected address. To redirect /old to /new, check URL rewriting, not hostname mapping.

After switching back to the original file, how can I find which change caused the issue?

On the same network, send the same request with the original file and the edited copy, keeping Global Routing and the selected server unchanged. If the issue occurs only with the copy, start with the section you edited most recently and revert it one line at a time. Change one thing and retest each time until you find the entry that triggers the issue.

Download Shadowrocket for Every Platform