Shadowrocket Config File Structure: General, Rule, Host, and URL Rewrite

1. Distinguish .conf files, subscriptions, and the active connection

A .conf file is a text-based configuration file; names in square brackets identify its sections. Each section has its own syntax: [General] commonly uses key-value pairs, [Rule] uses comma-separated rules, [Host] stores name mappings, and [URL Rewrite] uses a match expression, destination, and action. Do not copy syntax from one section directly into another.

Importing a subscription in Home mainly adds connection entries. Selecting a configuration in Config determines how traffic is handled. The two are related, but they are not the same operation. If you already have a provider and subscription, get the subscription link from your provider and check whether it contains connection details or a complete configuration. Do not infer its contents from the link suffix alone.

To test routing behavior in [Rule], select Config under Home → Global Routing. Proxy and Direct are not equivalent environments for testing this section. With Scene, also check the settings used by the current scene. If you only save the file without checking the active mode, it may seem as though “the rules have no effect.”

2. General: Read global settings before diagnosing DNS

[General] controls global behavior, including settings such as DNS. When reading this section, identify the key on the left of the equals sign first, then check its value. Keep field names, English punctuation, and Boolean values unchanged. Do not put Chinese explanations in values or replace half-width commas with full-width ones.

[General]
dns-server = system

Here, dns-server = system means to use the system DNS. It does not mean that every connection goes directly to its destination, nor does it assign a proxy to all requests. DNS handles how names are resolved; Rule determines which policy a connection uses. The actual resolution path may also depend on rule options, the proxy protocol, and other DNS settings.

If a connection entry works but a domain does not open, check the log to see whether name resolution failed or the connection failed after an IP address was returned. Check DNS first only in the former case. In the latter, also check the matched policy, destination port, and server status. HTTPS commonly uses port 443, but a provider's connection port may be different; do not confuse the two.

3. Rule: Match in order and put FINAL last

Rules in [Rule] are checked from top to bottom. The policy for the first matching rule is applied; Shadowrocket does not continue looking for a “more specific” match. Put exceptions before broader rules. FINAL handles remaining traffic and should be last.

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

The domain and 192.0.2.0/24 above are documentation examples, not connection resources. The first rule rejects the specified host; the second connects directly to example.com and its subdomains. Because the exact rejection rule comes first, the later suffix rule does not allow access to blocked.example.com.

4. Host: Change name resolution, not the URL

[Host] is used for local name mappings. The example below maps lab.example.com to the documentation-only address 192.0.2.10. This is not an accessible test service. Replace it with a reachable destination address that you are authorized to manage.

[Host]
lab.example.com = 192.0.2.10

• Do not include a scheme or path: The left side is a hostname, not https://lab.example.com/path.
• Do not use a port as an IP: An IP mapping on the right does not change the destination port.
• It does not replace Rule: The mapped connection still follows the active routing and policy settings.
• It does not bypass certificate checks: HTTPS connections still check the certificate for the hostname in the original request.

If a domain mapped to a server produces a certificate error, do not assume the Host configuration is correct just because the IP address is reachable. The server must also handle the original hostname and TLS correctly. If an app resolves names itself or uses a particular connection method, do not assume every request is affected by the same local mapping. Check the actual connection log.

5. URL Rewrite: Match request URLs and apply an action

[URL Rewrite] handles URL matching and rewriting; it is not a routing table that decides which connection a domain uses. The HTTP-to-HTTPS redirect below illustrates its three parts: a regular expression, a destination URL, and an action code.

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

^ and $ mark the start and end of the match, \. represents a literal period, and (.*) captures the following content. $1 in the destination refers to the first captured group. 302 indicates a redirect action; do not confuse it with the Rule policy PROXY.

When troubleshooting, first confirm that the original request is HTTP, then check for old redirect cache entries. If the browser uses HTTPS directly because of HSTS, an HTTP rule may never have a chance to match. Changing Rule order cannot fix this because the two sections handle different things. If you cannot confirm how a rewrite behaves, disable it first and restore the original access path.

6. Apply edits: Save, select, and rebuild the connection

A file appearing in the Config list does not mean it is selected, and saving the text does not mean existing long-lived connections will be re-established. First, copy the currently working configuration as a local backup, then verify one variable at a time as described below. Menus may differ across platforms; the steps use the page roles of Home, Config, and Settings.

1. Confirm the file: Find the currently selected file in Config, note its name, and open its edit option. Do not accidentally edit a different file that is not selected.
2. Change one thing at a time: Edit one rule or key-value pair, keeping the original section name and English punctuation. Check for duplicate FINAL rules or rules placed in the wrong section.
3. Save and select: Save the changes, then return to Config and confirm the file is still the active configuration. If a syntax warning appears, fix it before testing; do not treat an invalid configuration as usable.
4. Check the mode: Return to Home → Global Routing, select Config, and make sure the current connection entry works.
5. Start a new connection: If a brief disconnection is acceptable, reconnect and have the test app send a new request. Close the old page or restart the test app if needed to rule out connection reuse.
6. Check the result: Repeat a request to the same destination and check the matched rule, policy, and error type. Do not rely on whether a webpage merely “seems faster” to decide if the configuration took effect.

Manage remote configurations and local edits separately. Downloading a remote file again may overwrite local changes. Updating a connection subscription in Home is not the same as updating rules in Config. When maintaining custom rules, keep a separate copy and record each changed field and its expected result. After updating a subscription, also check that the policy names referenced by the configuration still exist.

7. Common issues: Find the relevant section by symptom

The key to maintaining a .conf file is understanding each section's role: General controls global settings, Rule determines policies, Host provides name mappings, and URL Rewrite handles matching request URLs. Change one part at a time and keep a restorable copy to connect configuration changes with their results.