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

1. .conf Sections and What Must Be Selected for Changes to Take Effect

A Shadowrocket .conf file is a text configuration organized into sections. Names in square brackets mark each section, such as [General]; content belongs to that section until the next section begins. Each section has its own syntax: General typically uses key-value pairs, Rule uses comma-separated rules, Host maps names to addresses, and URL Rewrite contains a match expression, a replacement target, and an action.

Home is where you select connection entries and check connection status; Config is for rule configuration files; Settings contains client settings. Importing a service subscription does not enable a .conf file, and selecting a .conf file does not provide a usable connection service. This guide covers configuration structure only, not where services come from.

To verify Rule routing, first check that Global Routing in Home is set to Config. Proxy and Direct are different global routing modes; neither can confirm whether a particular Config rule matched. If you use Scene, also check which routing configuration the active scene selects. The steps below are troubleshooting checks, not a claim that the four sections run in a strict internal sequence.

2. General: Global Settings Aren’t Routing Rules

[General] stores global settings, such as DNS options. Its typical format is parameter = value; don’t put Rule’s comma-separated syntax here. The example below uses system DNS to illustrate the key-value format. It is not a recommendation that every network use the same DNS setup.

[General]
dns-server = system

dns-server affects how the client handles DNS, but it does not route every request through a particular outbound. DNS answers “What address does this name resolve to?”; Rule determines “Which policy applies to this request?” They are related, but they are not the same setting. App caching, encrypted DNS, and whether a connection includes domain information can also affect what you observe. A webpage loading successfully alone does not prove that DNS is working as intended.

• Record the full current value of dns-server before changing it. Don’t change DNS, rules, and connection entries in the same test.
• When copying a key name, preserve its English spelling and ASCII punctuation. Don’t replace = with a full-width character.
• Keep one explicit setting per key. Don’t rely on duplicate-key precedence to manage the configuration.
• Leave unfamiliar parameters as they are; a parameter with the same name in another configuration format may not work here.

If many domain lookups fail after a change, first restore the General setting you just changed, then retest on the same network with the same connection entry. Broadening Rule matches is unlikely to fix a DNS problem and will only add more variables to troubleshoot.

3. Rule: The First Match Wins; Put FINAL Last

Rules in [Rule] are checked from top to bottom. A common format is type,match condition,policy. FINAL needs no match condition; it handles requests that haven’t matched an earlier rule. Put specific rules before broader ones and the fallback rule last.

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

example.com and 192.0.2.0/24 in this example are documentation-only values. The first line routes the domain and its subdomains through PROXY; the second sends requests matching the example address range to DIRECT. no-resolve means this IP rule won’t trigger a domain lookup; it does not disable DNS for the client.

DOMAIN-SUFFIX,example.com,PROXY does not match notexample.com; a matching substring anywhere in a name is not enough. GEOIP,CN,DIRECT depends on the destination IP and its database classification—not the page language, domain suffix, or service provider’s country of registration. If a request matches a domain rule above it, a later GEOIP rule won’t change its policy.

4. Host: Name Mapping Is Not Proxying or Redirecting

[Host] is used for local name mapping. The example below maps a sample domain to a documentation-reserved address to show the syntax. This address is not for real-world access and should not be used to test network availability.

[Host]
lab.example.com = 192.0.2.10

Host changes the address associated with a name, not the URL in the browser’s address bar. It also won’t automatically make a request use DIRECT. The policy still depends on the current routing mode, Rule, and available domain or address information. If domain and address rules both apply, check the record for a new request instead of assuming the mapping means routing will use only the IP.

• The port isn’t set by this line: https://lab.example.com/ uses port 443 by default; http://lab.example.com/ uses port 80. Host mapping does not change port 443 to another port.
• The certificate must still match the name: HTTPS connections still validate the domain in the certificate. Pointing a name to another server does not make a mismatched certificate valid.
• Caching can affect verification: An existing connection or an app’s internal cache may continue using the old result. After saving, close the old page connection and make a new request.
• Not all lookups use this mapping: If an app resolves names itself or connects directly to an IP address, you may not see the expected Host effect.

It’s best to test Host first with a domain you control, then decide whether to keep the mapping. To change outbound policy, edit Rule. To replace one webpage URL with another, check URL Rewrite—not by adding more Host entries.

5. URL Rewrite: Match a URL, Then Apply an Action

[URL Rewrite] processes URLs that are visible and match the rule. The example below redirects HTTP to HTTPS with a 302 response: the first part is a regular expression, the second is the replacement URL, and 302 is the action. The input deliberately uses plain HTTP to make the distinction between URL matching and encrypted HTTPS content clear.

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

1. ^ anchors the match to the start of the URL, so it won’t trigger just because the same text appears in the middle.
2. In example\.com, the backslash makes the period a literal dot. An unescaped . has a broader meaning in a regular expression.
3. (.*) captures everything after the slash following the domain, and $1 inserts the first captured group into the replacement URL.
4. 302 indicates a redirect response. Whether the app follows the redirect also depends on its own HTTP behavior.

For example, given http://example.com/docs?a=1, this rule builds the target https://example.com/docs?a=1. That doesn’t guarantee the destination site has that page or that the HTTPS connection will succeed. The rule changes how the request is handled; the server’s certificate, path, and access permissions must still be valid.

URL Rewrite is not an alternative to domain-based routing. To route an entire domain according to a policy, use Rule. To block a type of request, first determine whether you need domain-level blocking or URL-level handling; don’t mix syntax for different layers in the same section.

6. Applying Changes: Save, Select, and Verify with a New Connection

Saving a file and actively using it are two different things. If Config contains multiple local files or remote configurations, it’s easy to edit a copy while the old configuration remains active. A later remote update may also overwrite local edits, so create a clearly named local backup before experimenting.

1. Record the baseline: Note the connection entry selected in Home, the Global Routing mode, and the file currently selected in Config.
2. Back up and edit one item: Keep a copy of the original file in Config and change one item in one section. Disable test content by commenting out its rule line with #; don’t delete the entire section.
3. Save and check what’s active: Return to Config and confirm that the edited file is selected—not merely open in the editor.
4. Verify using Config: Return to Home, confirm that Global Routing is set to Config, and check that the selected connection entry is usable.
5. Start a new connection: Close the old page or session before testing again. If needed, disconnect and reconnect manually so the test doesn’t rely on an existing connection.
6. Record the result and roll back if needed: Check the destination domain, destination address, matching rule, and actual policy. If the result is unexpected, revert the item you changed and repeat the same test.

Also distinguish between two kinds of updates. Updating a service subscription in Home mainly changes connection entries; updating a remote configuration in Config may change text in sections such as General and Rule. Don’t assume they do the same thing just because both are described as “refreshing the configuration.” Check what you’re updating first, then verify the actual contents and selected item afterward.

Settings → On Demand manages automatic connection conditions, not Rule match conditions. If the client reconnects automatically after you disconnect manually, check On Demand and the system’s VPN settings first; that doesn’t mean the .conf file failed to save. Likewise, a successful automatic connection doesn’t prove a new rule matched.

7. Common Questions: Why Doesn’t the Result Match Expectations After Importing a File?

You can’t tell whether a .conf file is correct just by checking whether it imports. Section names and fields determine whether the syntax can be read; the selected file and routing mode determine whether it is used; and the actual record for a new request verifies its behavior. Checking in this order usually helps distinguish a syntax error, an inactive file, and a request that didn’t meet the match conditions.