How to Read a Shadowrocket .conf File: A Guide to [General], [Rule], [Host] and [URL Rewrite]

At a glance

This guide is for users who have added connection details in Home and are ready to read or edit a .conf file in Config. First, distinguish connection parameters from configuration rules. Then review DNS, matching order, local mappings, and request rewrites section by section. Finally, verify the changes with a single-setting test and request logs. Domain and address examples explain syntax only; they are not usable service configurations.

1. .conf Files vs. Connection Details in Home

A Shadowrocket .conf file is a text-based configuration divided into sections marked by square-bracketed headers. Each section starts at its header and ends before the next section header. Blank lines separate content for readability but do not replace section headers. The file is not JSON, so you do not need to wrap each line in double quotes or add commas at the end.

The server address, port, credentials, and protocol options in Home determine how a connection is established. The enabled configuration in Config determines how requests are handled. A rules file alone cannot establish a proxy connection without usable connection parameters. Get subscription details from your service provider. A connection subscription and a remote .conf configuration serve different purposes; an address starting with https does not tell you which one it is.

4 sections

This guide covers General, Rule, Host, and URL Rewrite

4 types

Rule examples include DOMAIN-SUFFIX, IP-CIDR, GEOIP, and FINAL

1 setting

Change one setting per test, then retry the same request

Start by locating each section header, then check the syntax used on each line. [General] and [Host] commonly use key-value pairs separated by an equals sign; [Rule] commonly uses fields separated by English commas; and [URL Rewrite] contains a regular expression, a target, and an action. Do not mix syntax from different sections.

2. [General]: Check Global Settings and DNS First

[General] contains global behavior settings. If a connection test responds but domain names will not load, check the DNS settings here before replacing all your rules. The example below shows one setting to illustrate key-value syntax; it is not a complete configuration.

[General]
dns-server = system

dns-server specifies the resolver source; system means to use system DNS. This does not guarantee that all DNS requests go through a proxy. The actual resolution path also depends on the network environment and other DNS options. Changing the resolver to a public address alone does not prove that the domain can be resolved.

Global settings quick reference

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

Check the current value first, then note how resolution behaves before and after the change.

Before testing rules

Connection details: Check in Home
Configuration file: Confirm it is enabled in Config
Routing mode: Global Routing → Config
Automatic connection: Settings → On Demand

On Demand controls when a connection is triggered; it does not replace the matching rules in [Rule].

Save the original value before making a change. If every domain starts failing to resolve after you switch resolvers, restore the setting and test again. Avoid changing outbound policies, mappings, and rewrites at the same time. This helps distinguish an unreachable resolver from a request that resolved successfully but failed later in the connection process.

3. [Rule]: Understand Matching Order and Policies

Rules in [Rule] are matched from top to bottom, and the corresponding policy is applied when a rule matches. Specific domain rules usually go before broader IP or geographic rules. Put FINAL last to handle requests that did not match earlier rules. The rules below illustrate the syntax; PROXY requires a corresponding usable proxy outbound.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

Keyword	Example meaning	What to look for
`DOMAIN-SUFFIX`	Matches example.com and its subdomains.	This is not a substring match for any arbitrary text.
`IP-CIDR`	Matches addresses in the 192.0.2.0/24 range.	`no-resolve` means the rule will not actively resolve a domain just to match this rule.
`GEOIP`	Matches CN using an IP geolocation database.	The match is based on IP data, not the language used by the website.
`FINAL`	Sends requests that have not matched earlier rules to PROXY.	There is no domain field, so do not write this as a three-field rule.

DIRECT means a direct connection, not that networking stops. PROXY selects a proxy policy; it does not create connection parameters. If the original file uses a custom policy name, confirm that the policy exists. Do not simply replace the text and ignore its definition.

First check the routing mode, then adjust rule order

To test [Rule], set Global Routing to Config, then check which rule matched the request. If the mode is Proxy or Direct, switch back to Config and test again before concluding that the rule syntax is invalid. Scene is not the same as a fixed FINAL rule.

The 192.0.2.0/24 range above is reserved for documentation examples, not for everyday browsing. Domain rules and IP rules solve different problems: the former match domain names, while the latter match addresses. In particular, when using no-resolve, do not treat a domain request failing to match an IP rule as proof of a DNS issue.

4. [Host]: Local Mappings Are Not Routing Rules

[Host] configures local name mappings. The example below points a sample domain to a documentation address to show the format. If you use that address to access a real service, you should not expect a valid service response.

[Host]
demo.example.com = 192.0.2.10

This line answers “Which address does this domain resolve to?”, not “Which connection handles this request?” The routing mode and rules still determine the policy applied after the mapping. A mapping does not change the domain in the browser’s address bar or automatically change the hostname used for HTTPS certificate verification.

Testing an address change: If you know the correct target server, you can test its new address with an explicit domain mapping. Remove the temporary entry when the test is complete.
Certificate errors: Check whether the target server presents a valid certificate for the original domain. Mapping a domain to an arbitrary address is not a solution to certificate problems.
Still routed through a proxy after mapping: Check the domain rules and final policy in [Rule]. Do not use [Host] changes as a substitute for setting a policy.
Only one domain is affected: Check for an old mapping first, then investigate public DNS so you do not overlook a local override.

5. [URL Rewrite]: Tell Address Mappings and Request Rewrites Apart

[URL Rewrite] matches and rewrites eligible request URLs. It is not DNS configuration or a domain routing rule. The example below shows the “regex, target, action” format by redirecting an HTTP URL to HTTPS.

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

^ and $ anchor the match to the full string, preventing a match on only part of the URL.
In example\.com, the backslash makes the period a literal dot. An unescaped period in a regular expression can match other characters.
(.*) captures everything after the slash, and $1 in the target refers to the first captured group.
302 indicates a temporary redirect. The rewritten request still needs to resolve its domain and establish a connection.

If a browser upgrades a URL before sending the request because of HSTS or its HTTPS-first behavior, the HTTP rule above may have no request to match. Check the URL that was actually requested rather than relying only on what was initially entered in the address bar.

Test rewrites and mappings separately: [Host] affects the result of resolving a name to an address, while [URL Rewrite] affects matching request URLs. Changing both broadens the scope of troubleshooting. If a redirect changes the hostname, check resolution and routing for the new hostname as well.

6. Edit, Enable, and Verify a Configuration in Config

Reading a file does not mean it is active. In Config, confirm which configuration is currently enabled before editing a copy; the filename alone does not tell you which file is running. Remote configuration updates may also overwrite local changes, so keep your own edits separate from remotely managed content.

Save a copyChange one settingEnable the configurationRetry the requestCheck the logs

Save the original. Note the current configuration name, the dns-server value, and the Global Routing mode. Keep a copy of the configuration before making changes.
Choose one test target. Use a domain you are authorized to access and whose expected behavior you know. The example.com domain and documentation IPs in this guide explain syntax; they are not targets for testing proxy availability.
Change one thing. For example, move a single DOMAIN-SUFFIX rule without changing DNS or adding a rewrite at the same time.
Save and confirm the configuration is enabled. Reconnect if needed, then make a new request so an existing connection or cached result is not mistaken for the result of the new rule.
Check the request logs. Compare the actual domain, matched rule, outbound policy, and error type. Resolution failures, connection timeouts, and certificate errors happen at different stages and should be handled separately.

If something goes wrong after a change, revert that change and repeat the same test. Narrow down the cause only when reverting reliably changes the result. A successful subscription update means the relevant content was retrieved and processed; it does not mean the rules in Config changed. Likewise, a successful remote configuration update does not mean the connection credentials in Home were updated.

7. Common Questions About Configuration Files

I changed [Rule]. Why is traffic still routed the same way?

First, confirm in Config that you edited the currently enabled file, then check Global Routing → Config. Make a new request and see whether a broader rule above it matched first. If so, move the specific rule above that rule and test again.

I added PROXY. Why can’t it connect?

Go to Home and check that the selected connection is valid. Confirm that the address, port, and credentials match the details from your service provider. PROXY only selects a policy; it cannot supply the connection parameters required by Shadowsocks, VMess, VLESS, or Trojan.

Will updating my subscription also update manually written rules?

First, determine whether you updated a connection subscription or a remote configuration. Connection subscriptions primarily manage server entries; check manually written rules in Config. Keep a local copy of remote configurations, then compare your custom content after each update to confirm it is still there.

Can I concatenate several .conf files?

Do not concatenate them directly. Organize the content by section and check for duplicate settings, repeated mappings, policy names, and rule order. Keep FINAL at the end of the rules. After merging, test a small number of known requests before adding more content.

For further troubleshooting, see Troubleshooting. To check setting and keyword definitions, see Features and Settings or the Glossary. Base your reading and tests on your own configuration and request logs; do not treat an example file as a general-purpose proxy configuration.