This guide is for users who can connect from Home and are ready to read or edit a .conf file in Config. First, distinguish connection profiles from configuration files. Then check the syntax and behavior of General, Rule, Host and URL Rewrite, and troubleshoot with one change at a time and a rollback plan. Examples use reserved domains and documentation-only IP addresses; they are not working proxy configurations.
First, distinguish .conf files, connection profiles and Global Routing
A Shadowrocket .conf file is a text configuration that defines global settings, routing rules and other request-handling options. It is not a server subscription: connection profiles in Home specify how to connect to a server, while the active file in Config determines how traffic is handled. Get any subscriptions you already use from your provider. This site does not provide, sell or recommend proxy servers or subscriptions.
If changing a rule has no effect, first check Home → Global Routing. Proxy, Direct, Config and Scene are different routing modes. To test the Rule examples in this guide, select Config and make sure the file enabled in Config is the one you edited. Proxy does not test individual routing rules, and Direct is not suitable for validating proxy policies. When using Scene, also check which settings that scene actually applies.
You can break the configuration review into the following five steps. This is a troubleshooting sequence, not a claim about the client's fixed internal processing order. In particular, it does not mean URL Rewrite, DNS and rule matching form one simple pipeline for every request.
.conf basics: section names, equals signs and English separators
Section names go in English square brackets, for example [General]. General and Host commonly use key = value. Rule entries use English commas to separate the rule type, match value and policy, while URL Rewrite uses its own space-separated format. Do not carry the syntax of one section over to another.
Here is a minimal example to illustrate the structure. It sends example.com to PROXY and all other requests to DIRECT, then adds a documentation-only address mapping under Host. PROXY still requires an existing connection profile. 192.0.2.10 is reserved for documentation and cannot be used to test whether a public website is reachable. Remove this Host example before using the file.
# Structure example; documentation addresses only.
[General]
dns-server = system
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
[Host]
demo.example.com = 192.0.2.10
[URL Rewrite]
# Add rewrite rules only when needed.
- Save the
.conffile in a plain-text editor. Make sure it has not been saved as.conf.txtand does not contain rich-text formatting. - Keep the English
[ ],=and,; do not replace them with localized punctuation. The section nameURL Rewriteincludes a space. - Put comments on their own line and start them with
#. Do not assume you can append explanatory text to the end of any field. - Keep entries for each section together where possible. Duplicate sections or keys can make the file harder to maintain; if you are unsure how overrides work, consolidate the entries and test them.
General: global settings are not server settings
[General] defines global behavior, including DNS-related settings. In this example, dns-server = system uses the system DNS settings. It does not specify a proxy server or guarantee that DNS queries will use a particular proxy connection. The actual resolution path also depends on the connection method, other DNS options and whether the app performs its own resolution.
Start with a small set of settings you understand, then add options based on the issue you are troubleshooting. Replacing an existing file's General section with a large block of unfamiliar settings can change DNS resolution, IPv6 and traffic exclusion behavior at once, making a single issue difficult to reproduce. Server passwords, WireGuard keys and TLS connection settings do not belong here just because the section is called “General.”
General quick reference
- Section
[General]- Field format
key = value- DNS example
dns-server = system- What to check
- Field spelling, duplicate keys and existing DNS settings
Change one global option at a time, and note its original value.
Rule quick reference
- Section
[Rule]- Domain rule
DOMAIN-SUFFIX,example.com,PROXY- Fallback rule
FINAL,DIRECT- What to check
- Top-to-bottom order and the final policy
The rule type defines what matches; the policy at the end defines how matching traffic is handled.
Also distinguish connection triggers from request routing. Settings → On Demand defines when to connect; it is not a routing rule in General. If the connection comes back after you disconnect manually, check the On Demand conditions and system VPN status instead of repeatedly changing FINAL.
Rule: match from top to bottom; put FINAL last
[Rule] is the section users edit most often. Rules are evaluated from top to bottom, and the policy for the first matching rule is applied; evaluation does not continue in search of a “more specific” entry. Put specific domains and address rules before broader rules, and place FINAL at the end as the fallback.
| Keyword | Example | What it matches |
|---|---|---|
DOMAIN-SUFFIX | DOMAIN-SUFFIX,example.com,PROXY | Matches example.com and its subdomains, not every domain containing that text. |
IP-CIDR | IP-CIDR,192.0.2.0/24,DIRECT,no-resolve | Matches the specified IPv4 range. no-resolve means no DNS lookup is initiated specifically for this match. |
GEOIP | GEOIP,CN,DIRECT | Uses an IP address database to determine the destination IP's region, not the page language or text in the domain name. |
FINAL | FINAL,PROXY | Applies the PROXY policy if none of the preceding rules match. |
For example, the rules below put a specific domain before address and region-based rules. DIRECT means connect directly; PROXY uses the selected proxy. These are not protocol names like Shadowsocks, VMess, VLESS, Trojan, Hysteria2 or WireGuard. Do not use a protocol name as a generic policy.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
no-resolve does not “disable all DNS.” It only controls whether the related IP rule initiates a DNS lookup during matching. An address rule may still match if the request already uses an IP address or the destination address is available. Conversely, if the client only sees a destination IP and has no domain information, do not expect every DOMAIN-SUFFIX rule to match the text shown in the browser's address bar.
- In Config, confirm which file is active, then go to Home → Global Routing and select Config.
- Put the exact condition you want to test before broader conditions. Keep a single FINAL rule at the end.
- Make the target request again and check its destination, matching rule and applied policy in the request log. Do not rely on the connection toggle alone.
- If a domain rule does not match, first check the actual request domain, including any domain reached after a redirect. Then review rule order and available DNS information.
Host: local DNS mappings are not URL rewrites
[Host] maps a specified hostname to an IP address. The common format is a domain on the left and an address on the right, for example demo.example.com = 192.0.2.10. Do not include https://, a URL path or :443. This is a hostname-to-address mapping, not a complete URL.
[Host]
demo.example.com = 192.0.2.10
api.example.com = 198.51.100.20
Both addresses above are for documentation only. In a real configuration, use an address you are authorized to use that actually serves the intended destination. Host does not replace the domain in the browser's address bar with an IP, nor does it automatically change the HTTP Host header or TLS SNI. If the mapped server lacks a certificate for the domain, HTTPS may still show a certificate error.
- Address and port are separate: HTTPS commonly uses port
443, and HTTP commonly uses port80, but a Host mapping does not change 443 to another port. - Mapping and routing are separate: Host determines the resolution result; Rule determines the connection policy. Adding a mapping does not set the policy to DIRECT.
- Cache and new connections are separate: After making a change, send the request again. If needed, quit and reopen the target app so an existing connection does not keep using the previous address.
- Resolution paths are separate: An app that uses encrypted DNS or a fixed IP may not use this local mapping. A page that looks unchanged does not by itself prove the syntax is wrong.
URL Rewrite: apply an action to matching URLs
[URL Rewrite] operates on request URLs, not hostname-to-IP mappings. The example below uses a regular expression to match an HTTP URL and redirect paths starting with /old/ to /new/. Each line contains the match expression, destination and 302, separated by spaces.
[URL Rewrite]
^http://example\.com/old/(.*)$ http://example.com/new/$1 302
In the expression, ^ anchors the match at the start, $ anchors it at the end, \. matches a literal dot in the domain, (.*) captures the remaining text, and $1 in the destination refers to the first capture group. With this rule, http://example.com/old/help redirects to http://example.com/new/help. This illustrates the syntax; it does not mean the demo site serves that page.
A redirect can also affect subsequent requests. For logins, payments, uploads or API calls, a 302 is not necessarily a transparent replacement for every request method. First test the match scope, destination URL, query parameters and request method on an address you control before using the rule in a real scenario.
- Do not omit the escaped dot in the domain; otherwise, the dot in the regular expression matches any single character.
- Do not match a generic path without restricting the hostname, or requests to other domains may be affected.
- Make sure the destination does not match the same rule, to prevent redirect loops.
- Do not use the Rule syntax
DOMAIN-SUFFIXin URL Rewrite, or use a Host mapping as a substitute for rewriting paths.
Edit safely in Config: back up, enable and retest
Manage remote configurations, connection subscriptions and local copies separately. Updating a connection subscription usually refreshes the connection profiles in Home; updating a remote .conf file may replace the contents of the configuration file. Do not assume that manually added rules in a remote file will survive its next update.
- Save a baseline: In Config, find the currently active file and save a complete copy. Note the current Global Routing mode as well. Backups may contain sensitive settings, so do not upload them publicly.
- Find the right section: Open the text editor for the file and confirm that you are editing the intended section: General, Rule, Host or URL Rewrite.
- Make one change: Add one rule or change one key at a time. Test with a narrow match first; do not change DNS, routing and rewriting all at once.
- Save and enable: Return to Config and confirm that the file is selected. If prompted to reload or reconnect, follow the prompt, then check Global Routing in Home.
- Retest and roll back: Recreate the target request and note the matching rule, error type and destination. If something goes wrong, switch back to the backup and repeat the same test.
Record specific facts in your test notes, such as “Destination: api.example.com; expected DOMAIN-SUFFIX; actually matched FINAL,” rather than just “the network is broken.” If every destination fails to connect, first check the selected connection and provider details in Home. If only one group of domains is affected, inspect Rule, DNS and Host. If only one path redirects, start with URL Rewrite.
FAQ: Why doesn't the result match expectations even though the file saves?
I changed Rule. Why does everything still use the same policy?
Go to Home → Global Routing and check that Config is selected, then return to Config and confirm the active file. Next, check whether FINAL appears too early or a broader rule comes before the rule you are testing. Saving a file does not automatically switch to it.
I added a Host mapping. Why does HTTPS report a certificate mismatch?
Check whether the server at the mapped address presents a valid certificate for the original domain. Host does not change the domain used for TLS validation or configure the server's certificate. Remove the mapping and make the request again to see whether the error disappears.
URL Rewrite has no effect. Do I need to add a proxy rule?
First check whether the real URL's scheme, hostname, path and query parameters match the expression. HTTPS paths are also subject to encryption visibility and MITM requirements; adding a PROXY rule does not satisfy those conditions. Test the expression first with a controlled HTTP address.
Why did my custom rules disappear after an update?
First identify whether you updated the connection subscription in Home or the remote file in Config. If the remote configuration was replaced, restore a backup to a local copy and reapply any necessary changes. Compare changes before future updates; do not overwrite a local file you have already tested.
The key to reading a .conf file is understanding what each section does: General sets global behavior, Rule selects a policy in order, Host provides local mappings, and URL Rewrite acts on matching URLs. Limit each change to one section, one field and one request to identify its effect, rather than repeatedly importing a full configuration and guessing.
Shadowrocket Download and Setup Guide
Get Shadowrocket for iPhone and iPad from the App Store for a one-time payment of $2.99. The Mac (Apple Silicon and Intel), Windows, Android and Linux versions are free. Check the App Store listing for current iPhone and iPad system requirements. Client downloads and proxy services are separate; get subscriptions from your provider.