Shadowrocket Config File Guide: .conf Syntax for General, Rule, Host, and URL Rewrite

Learn Shadowrocket .conf syntax, including key [General] settings, [Rule] matching order and FINAL, plus [Host] and [URL Rewrite] examples.

At a Glance

Before editing a .conf file, back it up in Config, then review general settings, routing rules, host mappings, and URL rewrites separately. To route traffic by rule, set Home → Global Routing to Config. This guide is for users who already have their own provider and subscription and need to understand the configuration syntax. It offers examples you can test one at a time, along with rollback steps; a configuration file is not a set of connection credentials.

1. .conf Sections and When They Take Effect

A Shadowrocket .conf file is a text-based configuration. Section names appear in square brackets, and each section uses its own syntax for settings or rules. [General] typically uses key = value, while [Rule] uses comma-separated rule lines. Don't mix these syntaxes. Saving successfully doesn't mean the file is active; check which file is selected in Config.

4 sections
Covered here: General, Rule, Host, and URL Rewrite
32-bit
The /32 prefix identifies a single IPv4 address
302
Temporary redirect status code used in the rewrite example

This minimal example illustrates the file structure; it is not a complete connection setup or a replacement for your existing settings. PROXY uses the currently selected proxy. You must configure an available server and its authentication details beforehand. The example domains and documentation addresses explain the syntax only; they are not working services.

[General]
dns-server = system

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

[Host]
lab.example.com = 192.0.2.10

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302

Home is where you select a server and manage connections, Config handles configuration files, and Settings contains app preferences. Subscribe imports and updates the connection entries included in a subscription; that doesn't mean a local .conf file is updated too. Likewise, editing rules in a .conf file won't fix a server address, password, or subscription authorization. Keep these two areas separate when troubleshooting.

Back up the file Edit one section at a time Select the configuration Check routing Start a new request

2. [General]: Understand DNS and IPv6 Before Changing Settings

[General] controls basic configuration behavior. Start by checking the DNS source: dns-server = system uses DNS provided by the operating system. It doesn't specify a fixed public resolver. The system's DNS environment may change when you switch between Wi-Fi and cellular networks. If domain resolution fails, first determine whether the system network itself is having issues or the current configuration has changed how DNS works.

[General]
dns-server = system
ipv6 = false

ipv6 = false can help troubleshoot IPv6-related issues, but it shouldn't be treated as a universal network optimization. Disabling IPv6 changes which address families are available; some networks rely on IPv6, so copying this setting blindly may reduce connectivity. If your current configuration works, leave it unchanged unless you have a specific symptom to investigate. Test this setting on its own, then decide whether to keep or revert it.

General Settings Checklist

dns-server
system: Use the system's DNS source.
ipv6
false: Disable IPv6 for this configuration to troubleshoot a specific issue.
Change one setting at a time
After saving, verify the change with a new connection.

Don't attribute the result of changing several settings at once to just one of them.

Rule Syntax Checklist

DOMAIN-SUFFIX
example.com,PROXY: Match by domain suffix.
IP-CIDR
192.0.2.10/32,DIRECT,no-resolve: Match a single IPv4 address.
FINAL
DIRECT: Use as the fallback policy when no earlier rule matches.

Use English commas in rule lines. Don't add a domain or subnet to FINAL.

DNS settings in a configuration file and the DNS settings of the device's current network may reflect different layers. A browser may still be using an existing connection or cached data, so refreshing immediately after a change may not show a difference. Save the file, confirm it's active, and establish a new connection before testing. If needed, fully close and reopen the target app so an old connection doesn't skew the results.

3. [Rule]: Match in Order and Put FINAL Last

The key to [Rule] is top-to-bottom matching: the first applicable rule determines the policy for that request. Put specific exceptions before broader rules. For example, if status.example.com should connect directly while other example.com domains use a proxy, place the exact-domain rule before the suffix rule.

[Rule]
DOMAIN,status.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
Rule keywordWhat it matchesWhat to check
DOMAINA complete domain nameNo scheme, port, or path.
DOMAIN-SUFFIXA domain and its subdomainsexample.com can match api.example.com; it doesn't match any string that merely contains example.com.
IP-CIDRA target IPv4 address range/24 is a subnet. no-resolve avoids triggering DNS resolution just to match this rule.
GEOIPA region associated with an address in the databaseCN is a region code in the address database; matching depends on that database's records.
FINALRequests not matched by earlier rulesPut it last and specify DIRECT or PROXY.

no-resolve doesn't disable DNS for the entire app or mean “never resolve this domain.” It limits how the corresponding IP rule is matched. When a domain request reaches that rule, don't assume it will match if no destination IP is available for matching. For precise control of a domain, prefer DOMAIN or DOMAIN-SUFFIX instead of relying only on address geolocation.

Takeaway: Test Specific Rules First, Then the Fallback

First, test the specific exception using the actual target for status.example.com. Then check the suffix rule, and finally test a target you control that falls outside the earlier rules. If FINAL is moved higher in the list, later exceptions won't be considered as expected. Fix the rule order instead of adding duplicate rules.

Whether rules affect routing also depends on Home → Global Routing. Config routes traffic according to the current configuration. Proxy and Direct select global proxy or direct routing, so they aren't suitable for checking the full result of rule-based routing. Scene selects routing behavior based on configured conditions; it isn't another name for Config. For the examples in this guide, select Config first.

4. [Host]: Map Domains, Not URLs

[Host] defines local mappings from domains to addresses. Put the domain on the left and the target IP on the right. Don't include https://, a path, or :443. A port is connection-target information, not part of a domain mapping. The reserved documentation addresses below illustrate the format and can't be used to test real website connectivity.

[Host]
lab.example.com = 192.0.2.10
status.example.com = 192.0.2.20

A Host mapping doesn't force a direct connection. The final policy also depends on Global Routing and the rules. Don't assume that assigning an IP to a domain bypasses all domain rules. When testing an HTTPS service you manage, check the address mapping, routing match, certificate domain, and server response separately; none of these checks replaces the others.

5. [URL Rewrite]: Learn the Syntax with an HTTP Redirect

[URL Rewrite] handles URL matching and rewriting. It doesn't fix server authentication or act as a DNS mapping. A typical redirect rule contains a match expression, a target URL, and a status code, separated by spaces. The example below redirects HTTP requests for a sample domain to HTTPS while preserving the path.

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302
  1. ^ anchors the match at the start of the URL, preventing the expression from matching unintentionally elsewhere.
  2. In example\.com, the backslash escapes the dot so it matches a literal period instead of any character in a regular expression.
  3. (.*) captures the remaining content, and $1 in the target refers to the first captured group.
  4. 302 indicates a temporary redirect. The client makes a follow-up request to the redirect destination; this doesn't directly replace the server's response body.

This rule explicitly targets an HTTP source URL. Changing http to https in the expression doesn't let you read the full URL of every encrypted request. Ordinary tunnel forwarding doesn't reveal paths or content inside TLS. Some browsers also upgrade URLs before sending a request because of HSTS or HTTPS-first policies, so the HTTP example may never get a chance to match.

URL Rewrite and Rule address different problems: the former changes the URL behavior of matching requests, while the latter determines the routing policy for a connection. Even if a redirect works, whether the destination is reachable still depends on DNS, routing, and server status. If the page ultimately fails to load, identify whether the failure occurred on the initial request, during the redirect, or when connecting to the new destination.

6. Save, Activate, and Roll Back: Test One Change at a Time

Before editing, keep a copy of the working file in Config and note its name. Edit menus may look different across platforms, so use the editing, copy, or export options available in your version of the app. Don't overwrite your only working configuration. For remote configurations, keep a local copy too, so future updates don't make manual changes hard to track.

  1. In Config, open the file you want to edit. Change one setting in one section at a time, then save using English punctuation.
  2. Confirm that the file is the active configuration, then go to Home → Global Routing and select Config.
  3. Check that the currently selected proxy is available. Correct rules can't replace valid server credentials.
  4. Reconnect, visit a test target directly related to the rule, and check the connection details or logs provided by the app.
  5. Record the target domain, expected policy, actual result, and setting changed. If the test fails, switch back to the backup and repeat the same request for comparison.

Settings → On Demand controls when connections start based on conditions; that's separate from Rule matching order. If the connection resumes after you disconnect manually, check the On Demand conditions instead of deleting FINAL. To reduce variables while troubleshooting, you can temporarily turn off On Demand, then restore the original setting after testing.

I changed Rule. Why do all sites still use the same route?

First check that Home → Global Routing is set to Config, then confirm which file is selected in Config. Next, look for an overly broad rule before FINAL. Test again with a new connection rather than just refreshing a page on an existing long-lived connection.

My subscription updated. Why didn't my local rules change?

A server subscription and a local .conf file are separate configuration objects. Check the current file in Config. To update a remote configuration, update that specific configuration and confirm the result; don't use the Subscribe update time as proof that the file changed.

Why does HTTPS report a certificate mismatch after I added a Host mapping?

Check whether the mapped address serves that domain and whether the server's certificate includes it. Host changes the address mapping; it doesn't fix certificates. Remove the mapping first and test the original route, then ask the server administrator to check the certificate and site configuration.

Where should I look first if saving causes a parse error?

Start with the line number in the error message and check the section name and English punctuation: Rule uses commas, General and Host use equals signs, and URL Rewrite fields are separated by spaces. Undo the content you just added, confirm the original file works, then restore the changes one line at a time.

Download Shadowrocket