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

A practical guide to Shadowrocket .conf sections: global settings, first-match rules with a FINAL fallback, local hostname mappings and URL rewrites, with examples.

At a glance

Use [Rule] to change outbound routing, [Host] to map a hostname to an address, [URL Rewrite] to rewrite URL paths, and [General] to adjust configuration-wide behavior such as parsing. This guide uses Home and Config on iPhone / iPad to verify the steps. On Mac, Windows, Android or Linux, use the section names and rule syntax as a reference; the exact tap sequence may differ.

01. Check the active Config and Global Routing

A .conf file is plain text organized into sections. Bracketed headings show which section the following lines belong to. For example, the same hostname is a match condition in [Rule] and a mapping key in [Host]. The snippets below are standalone references; do not replace your entire active configuration with them.

Back up the originalEdit a copySelect the configTest requestsRoll back if needed
  1. Open Config, note the name of the active file, and keep the original. Save a copy before editing. If the file already contains the relevant section, add the new lines there rather than duplicating its heading just to paste a snippet.
  2. In Config, make sure the edited copy is selected, then return to Home and set Global Routing to Config. When testing [Rule], do not leave routing set to Proxy or Direct, or the current request will not verify per-rule routing.
  3. Keep the connection on and compare the same test target before and after each change. Change one condition in one section at a time. If you change DNS, rules and rewrites together, even a working page will not tell you which change made the difference.
4 sections
Config sections covered in this guide
1 rule
Routing uses the first matching rule, from top to bottom
302
Temporary redirect status code used in the rewrite example

02. [General]: Global settings and DNS basics

Most entries in [General] use the key = value format. This section defines general configuration behavior, not the outbound route for a particular website. When troubleshooting name resolution, note the original dns-server value before deciding whether to change it. Do not replace the whole section to fix a single hostname.

[General]
dns-server = system

system means use the system DNS; it does not specify a fixed resolver on this line. The system's DNS environment may change when switching between Wi-Fi and cellular. To compare results, keep the network the same and check the same hostname. A resolved IP address does not guarantee that the destination port is reachable or that the server will accept the connection.

  • If several hostnames fail to resolve after changing dns-server, restore the original value and test again on the same network.
  • If only one self-managed hostname resolves to an outdated address, check whether [Host] still contains a mapping for it. Do not conclude that system-wide DNS is broken based on one hostname.
  • If the hostname resolves but traffic takes the wrong route, check [Rule] and Global Routing. Changing resolvers will not fix rule order.

03. [Rule]: First match, IP conditions and FINAL

Standard rules use half-width commas to separate the match type, condition and policy. Shadowrocket checks rules from top to bottom and applies the policy of the first match; it does not continue searching for a more specific rule. FINAL has no separate match condition. It handles requests that matched none of the rules above, so place it at the end of the rule section.

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

Check the expected route line by line

Hostname matching

DOMAIN
api.example.com matches the first line exactly and uses PROXY.
DOMAIN-SUFFIX
www.example.com matches the suffix rule and uses DIRECT.
Changing rule order
Move the suffix rule to the top, and api.example.com will match it first and use DIRECT.

When a hostname is an exception to a shared suffix rule, put the exact match before the broader match.

Address matching and fallback

IP-CIDR
Match the target IP against a network range. A request with target IP 192.0.2.10 matches the example range.
no-resolve
This does not actively resolve a hostname just to match this rule, nor does it disable DNS globally.
FINAL
Use PROXY only when none of the preceding rules match. Testing proxy routing requires an available service.

The example network range is reserved for documentation. Use it to reason about matching, not to test public connectivity.

If one hostname takes the wrong route, find its first matching rule

Start at the top of the rule section and look for the first exact or suffix rule that covers the hostname. If a broad rule comes before an exception, move only the exception above it, then test the original hostname again. Do not change FINAL, which would also affect other requests that match no earlier rule.

GEOIP also matches by target IP. For example, GEOIP,CN,DIRECT matches a destination whose IP is classified as CN by the GeoIP data. It does not read the webpage language or infer a match from the hostname suffix. To give an exact-hostname exception priority, place it before any IP-based rule that could match first.

04. [Host]: Map hostnames to IP addresses without changing URLs

Use [Host] to define a local mapping for a specific hostname. This example uses a documentation-only address to show the syntax: the left side is a hostname only, with no scheme, port or path; the right side is the target IP. This does not assign DIRECT to the hostname in [Rule].

[Host]
lab.example.com = 192.0.2.10
  1. To test the mapping, replace the example hostname and IP with a test hostname you manage and a reachable server address. Check the server's access logs to confirm whether the request arrived at the expected server; do not rely only on the browser's address bar. The original hostname can still appear in the address bar when the mapping works.
  2. If you use an existing proxy service, also distinguish between resolving the destination locally and resolving it remotely. To troubleshoot a local mapping, start with a direct test destination you control so a remote resolution result is not mistaken for a failed local mapping.
  3. If the server receives the request but returns a certificate error, check that the certificate covers the original hostname in the URL. Changing the resolved address does not change the hostname used for HTTPS validation or change the server's port to the one specified in the URL.

05. [URL Rewrite]: Match URLs and return redirects

[URL Rewrite] applies to requests where the client can see the full URL. The example fields, from left to right, are a regular expression, destination URL and redirect type. It temporarily redirects a plain HTTP request for /old to /new on the same host. It does not map DNS names or use DIRECT or PROXY as a rewrite destination.

[URL Rewrite]
^http://lab\.example\.com/old$ http://lab.example.com/new 302
  • \. matches a literal dot, while ^ and $ anchor the entire URL. Neither /old/ nor /old?from=test matches, and the destination /new will not match this rule again.
  • Test with a website you manage that accepts plain HTTP. Compare the first response for /old and /old/: the former should return 302 with a Location pointing to /new; this rule should not redirect the latter. The browser's final address can be misleading because it may show the result after automatically following the redirect.
  • If the browser upgrades http:// to https:// first, the request no longer matches the example expression. The path in an HTTPS request is encrypted, so the hostname alone cannot show whether the path is /old. Do not use this HTTP example to judge whether HTTPS path rewriting works.

06. Troubleshooting: check in this order

Why is the old rule still being used after saving a copy?

First, check the selected filename in Config, then make sure Global Routing is set to Config on Home. Send a new request to the same target; if the connection is being reused, end the existing request before testing again. If the result is still unexpected, find the first rule from the top that covers the target.

Why didn't the address bar change after editing Host?

[Host] changes the resolved address, not the URL. Check on the destination server whether the new request arrived. To change /old to /new in the address bar, test a redirect instead; do not add a path to a [Host] key.

A site that used to work is now unreachable. What should I revert first?

In Config, reselect the original file from before the edits, then test the same address on the same network for comparison. If the original works, undo the most recent change in the copy and test each change individually. If the original also fails, check the connection status on Home and your current network. Do not keep changing FINAL or adding DNS settings.

Download Shadowrocket