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

A section-by-section guide to .conf files: General for global settings, Rule for routing order, Host for local DNS overrides, and URL Rewrite for request redirects, with practical examples.

At a glance

To change an outbound policy, check [Rule]; to change DNS resolution for a domain, check [Host]; to change a request URL, check [URL Rewrite]; and to adjust global settings such as DNS, check [General]. This guide is for users who already use configuration files in Shadowrocket and want to review or edit entries. The interface examples use iPhone / iPad; on other platforms, refer to the section names.

Confirm which configuration is active before choosing a section to edit

A .conf file is divided into sections by bracketed headings. Entries between one heading and the next belong to the same section. The four sections do not define a fixed request-processing order: moving [Host] above [Rule] does not give DNS entries higher routing priority. The order of lines matters within the [Rule] section.

4 sections
This guide covers General, Rule, Host, and URL Rewrite
1 rule
Rule uses first-match wins
302
Temporary redirect status code used in this rewrite example

Check Home → Global Routing first

In Config, confirm which file is selected. Then go to Home → Global Routing, select Config, and test the routing behavior. If the current mode is Proxy or Direct, don't change rule order based on the connection result yet.

The flow below shows how a routing policy is selected in Config mode; it does not mean DNS lookups and URL rewrites always happen at the same point. Scene selects a routing mode for a given context. When troubleshooting an individual rule, switch to Config first to reduce interference from scene changes.

App requestDestination identifiedRule matchedPolicy applied
  1. Keep the original configuration and make changes in a copy. If the original file updates from a remote URL, save local edits separately so they aren't overwritten by the next update.
  2. Change one thing at a time, then retest on the same device, network, and destination. Note the behavior before each change so you don't mistake a network switch or cache change for a configuration effect.

General: Set DNS and other global options

[General] uses the format key = value. These settings don't assign outbound policies to individual domains. The two lines below set system DNS and IPv6 separately; when testing DNS, you don't need to change IPv6 as well.

[General]
dns-server = system
ipv6 = false
  • dns-server = system: Use the DNS configured by the system. If a domain resolves incorrectly only on one Wi-Fi network, first check whether system DNS resolves it correctly on that network, then compare with mobile data or another known-good network. System DNS settings can vary between networks.
  • ipv6 = false: Disable IPv6 support in this configuration to isolate the effect of the IPv6 path. This isn't a system-wide switch, and it doesn't guarantee the destination has an IPv4 address. Restore the original setting after testing, then decide whether to keep the change.

If only one domain resolves to the wrong address, first check whether [Host] contains an entry for it; don't change global DNS yet. If the domain resolves correctly but uses the wrong outbound policy, check [Rule]. See the configuration field reference for more options.

Rule: Match lines in order; the first match determines the policy

The common [Rule] format is type,match value,policy; FINAL has no match value. In the example below, an exact-domain exception comes before a suffix rule, and requests that match neither are handled by FINAL. PROXY uses the selected proxy, DIRECT connects directly, and REJECT blocks the request. The domain and IP range are examples for illustrating matching, not usable service addresses.

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

Domain matching

DOMAIN
Exact match for lab.example.com; subdomains are not included.
DOMAIN-SUFFIX
Matches example.com and its subdomains.
FINAL
Selects DIRECT if none of the preceding rules match.

If you move the suffix rule above the exact-match rule, requests that satisfy both conditions will match PROXY first.

IP matching

IP-CIDR
Matches the specified IP range. For example, the literal IP 192.0.2.10 is within 192.0.2.0/24.
no-resolve
Don't resolve a domain just to test this IP rule.
GEOIP
Matches based on the geographic classification of the destination IP, for example GEOIP,CN,DIRECT, rather than the domain suffix.

When adding GEOIP to a configuration, place it before FINAL and check whether an earlier rule already matches.

When checking rule order, distinguish between a policy being selected and the destination service being reachable. For example, if the request is identified as lab.example.com, the first line matches DIRECT. Even if the service itself is unreachable, the request won't fall through to the second line and use PROXY. First confirm which rule matched, then check whether the service is reachable.

Host: Override DNS resolution for specific domains

[Host] maps a domain to a specified address in the configuration. The example below uses the documentation-only address 192.0.2.10. For a real test, use a test domain you control and an address reachable from your current network, and make sure the connection uses a resolution path affected by the configuration.

[Host]
lab.example.com = 192.0.2.10
  1. With the original configuration, visit the test domain and note whether it connects and where the server receives the request. Then enable a copy with the mapping and start a new connection to the same domain, so an existing connection or DNS cache doesn't affect the result.
  2. If the connection still reaches the original address each time, check that the copy is selected and whether the target app is reusing an existing connection or using its own DNS. Output from a system DNS lookup may not reflect how the domain resolves when the app connects through Shadowrocket.
  3. If the connection reaches the specified address but shows an HTTPS certificate error, check whether the destination service has a valid certificate for the original domain. [Host] changes the resolved address; it doesn't replace the domain in the URL or make a mismatched certificate valid.

If you want to visit the same domain but have a different server respond, check [Host]. If you want a request to one path to redirect to another, check [URL Rewrite]. Changing only the IP won't change the browser's address from /old to /new.

URL Rewrite: Redirect requests that match a URL pattern

The [URL Rewrite] example below lists a matching expression, target URL, and action code 302, separated by spaces. It matches only the complete HTTP URL http://lab.example.com/old. The dots in the domain are escaped with backslashes, and ^ and $ anchor the match, so /old/ and URLs with query parameters won't match this expression.

[URL Rewrite]
^http://lab\.example\.com/old$ http://lab.example.com/new 302
  • For testing, use a test domain you control that permits plain HTTP, and don't send account details or other sensitive information. Make sure the request is still http://: if the browser upgrades it to HTTPS first, it won't meet the example's match conditions.
  • The expected result is a 302 response to the original request, with Location pointing to the full URL ending in /new. A client that follows redirects then makes a new request. If the address bar shows /new but the page can't be found, first confirm that the target path exists on the server.
  • HTTPS paths and query parameters are encrypted. If Shadowrocket can't see the full URL in a request, changing http to https in the expression won't make path matching work. Verify the expression with a controlled HTTP example first; don't assume an HTTPS mismatch is caused by [Rule].

Troubleshooting: Where to look after editing a configuration

Why is a domain rule still using the previous policy?

In Config, check the file name, then confirm that Home → Global Routing is set to Config. In [Rule], check from top to bottom, especially for an earlier DOMAIN-SUFFIX rule. Move an exact match above the broader rule only when you have confirmed the intended exception.

Why do I get different results when visiting an IP directly versus entering a domain?

First, record the destination for each request separately. Entering a domain may match a domain rule, while entering an IP directly gives the domain rule nothing to match. Even if both requests reach the same address, the server may select a site based on the domain, and visiting an IP directly may cause a certificate mismatch.

After a rewrite, requests keep redirecting. Which line should I remove first?

Remove the rewrite added in this round from a copy, then test again. If the loop stops, check whether the target URL also matches the original expression or whether the target page redirects back to the original URL. Narrow the expression to the exact source path, then test the source and target URLs separately.

What if my local entries disappear after a configuration update?

In Config, first check whether the selected file is a remote configuration or a local copy. If the remote content has replaced your local changes, recover the entries from your saved copy and merge them section by section into a new copy. After merging, check rule order and duplicate domain mappings, then retest each change.

Download Shadowrocket