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.
| Section | What it does | What it doesn’t do |
|---|---|---|
[General] | Core runtime settings, such as DNS | Doesn’t replace individual website routing rules |
[Rule] | Selects policies such as DIRECT or PROXY based on conditions | Doesn’t modify the request URL |
[Host] | Sets a DNS result for specific hostnames | Doesn’t determine on its own whether traffic uses a proxy |
[URL Rewrite] | Applies an action to URLs that match a regular expression | Isn’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 Examples | Match criteria | What to check |
|---|---|---|
DOMAIN-SUFFIX,example.com,PROXY | Domain suffix | Useful for explicitly targeting a group of related domains |
GEOIP,CN,DIRECT | The geographic classification of the destination IP in the GeoIP database | Doesn’t check webpage language or domain suffix |
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve | The IPv4 address’s network range | no-resolve prevents this rule from triggering a DNS lookup just for the match |
FINAL,DIRECT | No other rule matched | The 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.
- To proxy only specified websites: add specific DOMAIN-SUFFIX rules first, then end with FINAL,DIRECT.
- To change where the remaining traffic goes: change the policy on FINAL instead of casually deleting the fallback rule.
- If your rules use a custom policy name, make sure that destination is defined in the current configuration and spelled exactly the same way.
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
^anchors a match to the beginning, and$anchors it to the end, preventing matches on extra paths or query parameters.\.matches a literal period; an unescaped.in a regular expression can match other characters.- The second part is the redirect target and the third is the action type. Don’t rewrite this line using Rule’s comma-separated format.
- A browser may upgrade HTTP on its own or reuse a cached redirect. Seeing an HTTPS URL doesn’t prove this rule matched.
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.
-
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.
-
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.
-
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.
-
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.
-
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
RecommendedRequests 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.