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

A section-by-section guide to Shadowrocket .conf files: what General, Rule, Host and URL Rewrite do, how to write them, and how processing works.

At a glance

A Shadowrocket .conf file is neither a server list nor a script that runs line by line. This guide is for users who already have their own service details and need to read or edit a config. It explains the roles of the four sections, then uses rule examples, mode comparisons and verification steps to show where changes belong—and why they may not take effect after saving.

1. .conf Sections and How They’re Read

Config files use square brackets to mark section names, such as [General]. Content from a section name up to the next section name belongs to that section. Each section has its own syntax: General typically uses key-value pairs, Rule uses comma-separated matching rules, Host maps hostnames to addresses, and URL Rewrite uses match expressions and actions. Don’t move syntax from one section into another.

This minimal example illustrates the file structure. It contains no proxy server parameters and may not suit your network. The example domains are reserved for documentation and should not be used to test real-world connectivity. A standalone line beginning with # is a comment; it does not establish a connection or change a policy.

# Structure example: back up your current config before use
[General]
dns-server = system

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

[Host]
example.com = 192.0.2.10

[URL Rewrite]
^http://example\.org/(.*)$ https://example.org/$1 302
4 sections
General / Rule / Host / URL Rewrite, each with a distinct role
3 policies
The rules in this example use PROXY / DIRECT / REJECT
1 fallback
FINAL appears on the last line of the example’s Rule section

Section order does not determine request-processing order. Putting Host after Rule doesn’t mean rules are applied before Host mappings; moving URL Rewrite to the top of the file won’t make every network connection run through rewrite first. Each section is read by its corresponding feature. Only the order of rules within Rule has the “top to bottom, stop at the first match” meaning described here.

2. General: Global Options Aren’t Routing Rules

[General] contains config-wide options, such as DNS settings. In this example, dns-server = system means the system DNS settings are used. It doesn’t mean “send every connection direct” or “proxy every domain.” Connection handling still depends on Global Routing, Rule and the proxy settings currently available.

When editing this section, keep option names unchanged and check that each value has the right type. Boolean values, address lists and text parameters aren’t interchangeable. Don’t replace the entire section just to match another file: doing so may change existing network exceptions, DNS behavior or other general settings, causing specific features to behave unexpectedly without an obvious syntax error.

General: What to Check

Section name
[General]
Example key
dns-server
Example assignment
dns-server = system
What to check
General options in the currently selected config

Check what each key does before changing it; don’t infer priority from section order.

App settings: scope

Routing mode
Home → Global Routing
Select a config
Config → currently active config file
Automatic connection
Settings → On Demand
Proxy parameters
Home → a server entry you already have

On Demand determines when a connection starts. It doesn’t replace Rule or act as an execution switch for config sections.

A common pitfall is to edit General, then change automatic connection conditions in Settings → On Demand, making it hard to tell which change affected the result. When testing a config, keep the connection state and network environment constant; test automatic connection behavior separately. The paths in this guide refer to the Home, Config and Settings interfaces. Button layouts may vary by platform.

3. Rule: Match in Order and Put FINAL Last

[Rule] determines which policy applies to a matching request. A typical rule consists of a type, a match value and a policy; FINAL requires no match value. PROXY sends the request through the proxy path, DIRECT uses a direct connection, and REJECT blocks the request. PROXY doesn’t create a working server; you still need your own service details and a reachable server.

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT,no-resolve
FINAL,PROXY
Rule typeWhat the example matchesWhat to check
DOMAINMatches only the exact domain api.example.com.It doesn’t include other subdomains.
DOMAIN-SUFFIXMatches example.com and its subdomains.Put more specific exceptions above this rule.
IP-CIDRMatches the address range 192.0.2.0/24.no-resolve prevents this rule from triggering a DNS lookup solely for the match.
GEOIPChecks whether the address belongs to CN based on an IP location database.Uses IP data, not webpage language or the domain suffix.
FINALUses PROXY if none of the preceding rules match.Put it last so it doesn’t catch requests before later rules can be checked.

In this order, api.example.com matches DOMAIN first and uses DIRECT. www.example.com skips the first line, then matches DOMAIN-SUFFIX and uses PROXY. These are expected results inferred from the rules, not results from network tests against the example domains. If the suffix rule comes first, the exact-domain exception won’t run.

no-resolve doesn’t turn off DNS for the entire app. It controls whether the relevant IP-based rule triggers a lookup; a request that already has an IP may still match. Keep in mind that a domain request without a resolved address may fall through to later rules or FINAL. Don’t assume every address-based condition has been checked.

4. Host: Address Mapping Isn’t a Connection Policy

[Host] provides local, static hostname mappings. This line maps example.com to 192.0.2.10. That address is reserved for documentation, not a service address provided here. For actual use, replace it with a target address you’re authorized to use and have verified as correct.

[Host]
example.com = 192.0.2.10

Separate “where to connect” from “how to connect”

Host: Address mapping
  • Provides a local address mapping for a specified hostname.
  • Doesn’t automatically change a page’s address to a different domain.
  • Doesn’t automatically choose DIRECT or PROXY.
Rule: Connection path
  • Chooses a policy based on conditions such as domain or address.
  • Use DOMAIN to set a policy for an exact domain.
  • Doesn’t replace the website’s target hostname on its own.

To pin an address and choose a connection path, configure Host and Rule separately, then verify the mapping and the policy match independently.

Host mappings don’t fix certificate errors. For HTTPS, the website still needs to present a certificate that matches the hostname you visit, even when the connection address comes from a static mapping. Mapping to the wrong server can cause a certificate mismatch, a closed connection or unexpected site content. Check the mapping first; don’t weaken certificate validation to hide an incorrect target.

Behavior may differ if an app connects directly to an IP or uses its own resolution method. When troubleshooting, note the actual request hostname and target address; don’t assume Host was used just because of the URL in the browser’s address bar. Existing connections may also keep using the old address, so verify changes with a new connection.

5. URL Rewrite: Match a Request URL and Set an Action

[URL Rewrite] handles URL matching and rewriting, not network routing. This example uses a regular expression to match a plain HTTP URL on a specified domain, then returns a 302 redirect to the HTTPS URL. It starts with http:// to illustrate when a plaintext request is visible; this doesn’t mean the contents of every HTTPS request can be read directly.

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

Based on the expression, http://example.org/docs redirects to https://example.org/docs. The new request still needs to be resolved, matched against a connection policy and connected to. Rewrite isn’t a shortcut around Rule, and it can’t make an unreachable target reachable.

If redirects loop, check whether the replacement URL matches the same or another rewrite expression. If the path disappears, check that the capture group corresponds to $1. If the rule never triggers, first check whether the browser has already upgraded the actual request to HTTPS; don’t immediately change routing policies.

6. Config and Global Routing: Select the File and the Right Mode

The Config screen manages config files; Home → Global Routing selects the current routing mode. These names are similar, but their roles differ: a file appearing in the Config list doesn’t mean it’s selected for use, and selecting a file doesn’t mean the current mode routes traffic according to its rules.

Config

Recommended

Choose a connection policy using the selected config’s rules. How unmatched requests are handled depends on the last rule. FINAL can be DIRECT or PROXY; it doesn’t always mean “direct for everything else.”

Use it to: verify Rule order and routing for a specific domain.

Proxy

Uses a global proxy mode instead of routing according to everyday rules in Rule. System traffic scope, network exceptions and protocol availability may still affect the result.

Use it to: briefly check whether the proxy path works. It doesn’t prove that Rule is working.

Direct

Uses a direct connection mode to observe the local network path. It doesn’t rewrite every PROXY entry in the config as DIRECT.

Use it to: compare how the same target behaves over a direct connection.

Scene

Switches behavior according to configured scene conditions. The result depends on the scene definition; check which scene matches the current network before use.

Use it to: work with an environment that already has clearly defined scenes. For troubleshooting fixed rules, reduce this variable first.

Select Config when testing rules to make it easier to tie a request’s result to a specific Rule. If access works in Proxy mode but fails in Config mode, that only points to a difference in the paths or policy selection. Check the rule that actually matched, the resolved target and the available server before concluding that the config file is damaged.

7. Save, Enable and Troubleshoot: Change One Variable at a Time

Keep the original file before editing, especially if the config comes from a remote URL. A remote update may overwrite local changes. Updating a server subscription and updating a config file are also different operations: the former typically refreshes server entries, while the latter may change General, Rule and other sections. A successful subscription refresh doesn’t mean Rule has been reloaded.

  1. Keep a copy

    In Config, confirm which file is in use. Keep a recoverable copy of the original before opening the file for editing. Don’t overwrite your only usable config.

  2. Change one thing

    For example, move just one DOMAIN rule in Rule. Leave General, Host and URL Rewrite unchanged, and record the full line before and after the edit.

  3. Confirm it’s active

    After saving, return to Config and confirm that the edited file is selected. Then go to Home → Global Routing, select Config and check that the connection is enabled.

  4. Make a new request

    On the same network, make the request again and check the request log for the available domain, target IP and policy information. Recreate the connection if needed to rule out an existing session.

  5. Compare and restore

    If the result isn’t expected, restore the original line and test again. To check automatic connection behavior, go to Settings → On Demand separately; avoid changing multiple settings at once.

Observed behaviorCheck firstNext step
Policy doesn’t change after saving a ruleThe selected file and Global Routing mode.Confirm Config is selected, then check whether an earlier, broader rule already matches.
Certificate error on a specific domainWhether Host maps the domain to the wrong address.Remove the mapping and start a new connection; compare the certificate with the target hostname.
URL Rewrite doesn’t triggerWhether the request’s protocol, domain and path match the expression.First verify the plain HTTP example, then check whether the actual request is visible to the rule.
Custom rules disappear after an updateWhether the update was for a remote config or a server subscription.Restore the changes from a backup and identify the source of the file you’ll maintain going forward.
A PROXY match still fails to connectThe protocol parameters and connectivity of the server you already have.Troubleshoot a correct rule match separately from a successful proxy connection; don’t keep rearranging Rule.

Break the final diagnosis into four questions: Is the config selected? Did the request match the expected rule? Did it resolve to the right address? Can the selected path connect? General, Rule, Host and URL Rewrite each explain a different part; changing one section can’t replace the full troubleshooting process. For interface settings, see Settings guide; for protocol fields, see the protocol reference.

Download Shadowrocket