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

Learn how each .conf section works: General settings, Rule order, Host mappings and URL Rewrite. Includes syntax tips and common mistakes.

At a glance

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.

4 sections
This guide covers: General, Rule, Host and URL Rewrite
4 types
Global Routing:Proxy / Direct / Config / Scene
/32
IPv4 CIDR prefix length for matching a single address

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.

Check the connection profile Check the routing mode Check the active file Review the configuration sections Verify the request result

.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.

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.

KeywordExampleWhat it matches
DOMAIN-SUFFIXDOMAIN-SUFFIX,example.com,PROXYMatches example.com and its subdomains, not every domain containing that text.
IP-CIDRIP-CIDR,192.0.2.0/24,DIRECT,no-resolveMatches the specified IPv4 range. no-resolve means no DNS lookup is initiated specifically for this match.
GEOIPGEOIP,CN,DIRECTUses an IP address database to determine the destination IP's region, not the page language or text in the domain name.
FINALFINAL,PROXYApplies 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.

  1. In Config, confirm which file is active, then go to Home → Global Routing and select Config.
  2. Put the exact condition you want to test before broader conditions. Keep a single FINAL rule at the end.
  3. 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.
  4. 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.

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.

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

Download Shadowrocket