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

Explore Shadowrocket’s .conf file section by section. Learn what [General], [Rule], [Host] and [URL Rewrite] do, and how to apply your changes.

At a glance

Shadowrocket’s .conf file is a text-based configuration, not a subscription URL or a substitute for connection credentials. This guide is for users who already have their own service details. It explains the roles of runtime settings, routing rules, hostname mappings and URL redirects, then walks through backing up, editing, enabling and reverting a configuration. Test with a minimal set of rules first, then restore other settings one at a time to avoid conflating DNS, rule order and connection issues.

1. .conf Sections and Configuration Scope

Configuration files use square brackets to mark sections, such as [General]. Each section’s contents follow its own syntax until the next section begins. [General] commonly uses key = value, while [Rule] uses comma-separated rules. Don’t assume the same format applies to every section. Use English half-width brackets, commas and equals signs when editing; make sure your input method hasn’t replaced them with full-width punctuation.

SectionWhat it doesWhat it doesn’t do
[General]Core runtime settings, such as DNSDoesn’t replace individual website routing rules
[Rule]Selects policies such as DIRECT or PROXY based on conditionsDoesn’t modify the request URL
[Host]Sets a DNS result for specific hostnamesDoesn’t determine on its own whether traffic uses a proxy
[URL Rewrite]Applies an action to URLs that match a regular expressionIsn’t the same as DNS mapping or routing rules

You don’t need all four sections. For website routing alone, start with the required basic settings and [Rule]; you can leave out Host and URL Rewrite for now. A configuration may also contain other supported sections. Don’t delete them just because they aren’t covered here. Don’t use a configuration in another format by simply changing its file extension to .conf.

2. [General]: Check Your DNS Baseline Before Changing Other Settings

In [General], start with a small number of clearly supported settings. This example uses dns-server = system, which uses system DNS as the resolver here. It does not guarantee that every network will resolve domains successfully; results still depend on the current network, cache and other DNS settings.

[General]
dns-server = system

If the original configuration already has DNS settings, note their values before testing. Changing the resolver may change the IP returned for a hostname, which can affect matches for GEOIP or IP-CIDR. When troubleshooting a website, don’t change DNS, reorder rules and switch connection entries at the same time—or you won’t know which change affected the result.

Check the Basics

Section
[General]
Example key
dns-server
Example value
system
Syntax
key = value

Keep a known-working baseline. Don’t add unfamiliar settings based on their names alone.

Troubleshoot DNS Resolution

Test target
The same fully qualified domain name
Keep constant
The same network and connection entry
Record
Resolution result, matched rule and connection error
Revert
Restore the original value and establish a new connection

Successful DNS resolution doesn’t mean the destination port is reachable; check both separately.

3. [Rule]: Match Order, Policies and the FINAL Fallback

The key to [Rule] is that rules are checked from top to bottom. The first match determines the policy for that request. The example below sends example.com and its subdomains through PROXY, and everything else through DIRECT. It demonstrates routing logic only and contains no usable connection details. Before using PROXY, add and select your own working connection entry on Home.

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

DOMAIN-SUFFIX,example.com,PROXY matches example.com and www.example.com; it doesn’t search URL paths for a string. Don’t include https://, a port or /path. FINAL is the fallback when no earlier rule matches, so put it last. If you place it earlier, later rules won’t get a chance to match.

Rule ExamplesMatch criteriaWhat to check
DOMAIN-SUFFIX,example.com,PROXYDomain suffixUseful for explicitly targeting a group of related domains
GEOIP,CN,DIRECTThe geographic classification of the destination IP in the GeoIP databaseDoesn’t check webpage language or domain suffix
IP-CIDR,192.0.2.0/24,DIRECT,no-resolveThe IPv4 address’s network rangeno-resolve prevents this rule from triggering a DNS lookup just for the match
FINAL,DIRECTNo other rule matchedThe last rule, defining where remaining requests go

Each row explains a syntax; you don’t need to add them all to the same configuration. 192.0.2.0/24 is a documentation-only example range, not a real service address. If you add a broad rule such as GEOIP, place it after more specific website exceptions and before FINAL. Otherwise, a broad match may catch requests that later rules should handle.

4. [Host]: Domain Mapping Doesn’t Mean Direct Routing

Use [Host] to set a static resolution result for a specific hostname. This example maps a reserved test domain to a documentation-only address to demonstrate the format; it does not point to a real service. The left side is the hostname, without a scheme or path; the right side is the specified address.

[Host]
lab.example.test = 192.0.2.10

Host controls which address a domain resolves to; Rule controls which policy a request uses. Adding a Host entry does not mean the request will use DIRECT. Check the matched rule, the current Global Routing mode, and the destination and policy shown in the connection log.

Choose What to Change Based on the Issue

Need to pin a destination address
  • Add an explicit hostname-to-address mapping in Host.
  • Check whether the destination server still accepts requests for that hostname.
  • HTTPS still requires a valid certificate for the original hostname.
Need to change the request policy
  • Add a domain or IP condition in Rule.
  • Make sure exception rules come before broader rules.
  • Use Config mode to verify the policy that actually matches.

Test address mapping and routing separately. A fixed IP won’t fix a certificate mismatch or guarantee that a service will remain available.

5. [URL Rewrite]: Match URLs, Not a Substitute for Rule

[URL Rewrite] applies an action to URLs that match a regular expression. This example redirects an HTTP root URL to its HTTPS equivalent; the final 302 indicates a temporary redirect. It covers only the root path, not every page on the domain, making it easier to keep the test focused.

[URL Rewrite]
^http://example\.com/$ https://example.com/ 302

The full path of a regular HTTPS request is protected by encryption, so adding a URL Rewrite rule doesn’t mean it can match that path. Processing HTTPS content also depends on prerequisites such as the scope of decryption and certificate trust; they aren’t needed for the basic configuration checks in this guide. Don’t broaden processing for every domain just to test one redirect.

6. Apply Changes: Save, Select and Reconnect

Saving the file is only the first step. Make sure the edited configuration is selected in Config, then choose Config under Home → Global Routing. The steps below refer to the Home, Config and Settings layout on iPhone/iPad. On other platforms, check the corresponding features; don’t assume every platform has the same screen layout.

  1. Back Up the Original

    Go to Config, open the action menu for the current configuration, export it and keep a separate copy. Note the configuration name and the current mode under Home → Global Routing.

  2. Edit One Setting at a Time

    In Config, open the text editor for the target configuration and change just one section per test. Check section names, half-width punctuation and the position of FINAL, then save.

  3. Select the Configuration

    Return to the Config list and make sure the target file is selected. If you edited a copy, switch to that copy before testing instead of continuing with the original file.

  4. Switch Modes

    Go to Home → Global Routing and choose Config. If Settings → On Demand is enabled, note its settings first and avoid automatic connections interfering with manual mode changes during testing.

  5. Reconnect and Verify

    Disconnect and reconnect, then make a new test request. Check the domain, matched rule and policy in the connection log. If it fails, switch back to the backup configuration and repeat the same test.

Existing connections may keep using their original state, and browsers may retain connections or cached data. Refreshing an old page once after a configuration change doesn’t prove the new settings are active. Close relevant old connections, make a new request and keep the network and connection entry unchanged. If needed, test DNS resolution and the destination service connection separately.

7. How Global Routing Mode Affects Configuration Testing

If a rule appears to have no effect, check Global Routing before editing the file again. Config applies the current configuration’s routing rules. Proxy and Direct can help narrow down the issue, but their test results don’t verify whether a specific rule matched.

Config

Recommended

Requests follow the policies in the current configuration. Use this mode to check which rules, including DOMAIN-SUFFIX and FINAL, actually match.

Best for: everyday rule-based routing and verifying configuration changes.

Proxy

Routes traffic through a proxy to check whether the current connection works. A page loading successfully doesn’t prove that a particular Rule matched.

Best for: distinguishing a connection entry issue from a rule selection issue.

Direct

Routes traffic directly for comparison with the proxy path. While in this mode, don’t expect PROXY routing rules to work as they do in Config mode.

Best for: checking whether the current network can reach the destination.

Scene

The configured scenes determine how traffic is handled. When troubleshooting, check the scene conditions and actions first so a scene switch doesn’t change the test conditions.

Best for: switching between network environments with clearly configured scenes.

8. Common Configuration Issues and Recovery Checks

Why is the old policy still being used after I saved the .conf file?

Check these in order: the selected file in Config, Home → Global Routing → Config, and whether the target rule appears before FINAL. Then reconnect and make a new request. First rule out the possibility that the file is correct but you edited a configuration that isn’t currently in use.

Why does HTTPS show a certificate error after I add a Host entry?

Host changes only the address mapping; it doesn’t change the request hostname or certificate validation requirements. Remove the new mapping and test again, then confirm that the specified server actually serves that hostname. Don’t use certificate-error bypasses in place of correcting the address and certificate configuration.

Why didn’t the rules update when I updated my subscription?

Connection subscriptions and remote configurations are separate items. First check whether you updated service details on Home or a remote configuration in Config. Keep a local copy before updating; after fetching a remote configuration, check whether it overwrote any rules you edited yourself.

I can’t connect after making a change. Do I need to import everything again?

Switch back to the backed-up configuration first, keep the original connection entry unchanged and reconnect. If it works, compare the sections you changed, one at a time. If it still fails, check the service address, port and authentication details. Don’t delete all configurations and subscriptions; you could lose your working baseline for comparison.

Record at least four items during verification: the selected configuration, Global Routing mode, test domain and policy that actually matched. Change only one variable at a time when comparing results. This helps distinguish syntax errors, rule overrides, DNS differences and unreachable services without layering on more settings.

Official Shadowrocket Downloads