At a glance

Before editing, check the active configuration in Config, then verify Global Routing in Home. This guide uses the iPhone / iPad interface and is for readers who can already connect and want to adjust traffic routing or troubleshoot rules that do not match. Edit one section at a time and keep the original configuration so you can test outbound policies, DNS resolution, and URL redirects separately.

Check the .conf file and routing mode first

A .conf file is organized into sections. The name in square brackets determines which section reads the entries that follow: [General] and [Host] use equals signs for assignments, [Rule] uses commas to separate fields, and the redirect example in [URL Rewrite] uses spaces. Do not move a line to another section without checking its syntax there.

Active configurationRouting modeTarget matchOutbound policyConnection log

In Config, confirm that the file you intend to test is active—not just open in the editor. Save a copy, return to Home, and set Global Routing to Config before testing traffic routing. Proxy and Direct are separate global routing options; neither is suitable for checking whether a particular [Rule] matched. On Demand in Settings controls when connections are established automatically and does not replace this step.

4 sections
This guide covers General, Rule, Host, and URL Rewrite
2 commas
A basic DOMAIN-SUFFIX rule has fields for the rule type, domain, and policy
302
The HTTP redirect status code used in this URL Rewrite example

Check the match before diagnosing the route

A page loading successfully does not prove that traffic used the intended outbound route. Start a new connection to a known target and check its policy in the app's connection log. If the policy is correct but the request still fails, check DNS results or whether the selected outbound route is available.

General: Configure global DNS settings

[General] contains settings shared across the configuration. For example, setting dns-server to system uses the system DNS rather than specifying a fixed DNS server on that line. The system's DNS environment may change when switching between Wi-Fi and cellular networks, so keep the network connection unchanged when comparing results before and after an edit.

[General]
dns-server = system
  • Edit the relevant key in the existing [General] section. Do not add a second section with the same name just to test a setting, and do not leave two conflicting dns-server entries.
  • Compare results before and after the change using the same domain that was previously reachable, and make sure the test sends a new request. Refreshing a page may not trigger a fresh DNS lookup if an existing connection is reused or a cached result is used.
  • Diagnose DNS resolution and outbound routing separately. Resolving a destination address does not mean that the current policy can reach it; likewise, an existing connection can continue transferring data even if a new DNS lookup fails.

Rule: Order specific rules before the FINAL fallback

Rules in [Rule] are evaluated in order, and the first match determines the policy. Put exceptions for individual domains before broader suffix rules, and place FINAL at the end. The documentation domains and addresses below are only examples for illustrating rule matching; they do not represent real services. Before using PROXY in your own configuration, confirm in Home that a working proxy server is available.

[Rule]
DOMAIN,docs.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT
FINAL,DIRECT

Assuming the app has the requested domain, docs.example.com matches the first line, while img.example.com matches the second. If you swap the first two lines, the suffix rule will match docs.example.com first. The third line matches the specified IPv4 range; a request made with an IP literal will not match a domain rule. Requests that do not match any earlier line fall through to FINAL.

Match by domain

DOMAIN
Matches an exact domain, such as docs.example.com.
DOMAIN-SUFFIX
Matches example.com and its subdomains, but not notexample.com.
Common mistakes
Do not include https://, a port, or a path in the domain field.

If a suffix has an exception, put the exact domain above the suffix rule.

Match by IP address and set a fallback

IP-CIDR
Matches an IPv4 address range, such as 192.0.2.0/24.
GEOIP
Matches based on the destination IP's geographic classification, for example GEOIP,CN,DIRECT.
FINAL
Sets the policy for requests that match no earlier rules, for example FINAL,DIRECT.

IP-based rules use the destination address; they do not match by domain suffix or the device's location.

Do not replace the existing FINAL rule just to test a domain rule. That changes the outbound route for all traffic that matches no other rule, making the result harder to diagnose. Keep the existing fallback, add one specific exception, then compare a domain that should match with one that should not.

Host: Map a domain to a specific IP address

In [Host], the left side is the domain to resolve and the right side is its mapped address. Use it to direct requests to a specific address when Shadowrocket resolves that domain. It does not replace [Rule], choose between DIRECT and PROXY, or change the domain shown in the address bar.

[Host]
staging.example.com = 192.0.2.10

192.0.2.10 is a documentation example address and should not be used to test whether a service is reachable. For a real test, use a domain you manage and a service address reachable on your current network. Make the request using the domain; entering the IP directly bypasses the domain mapping and may cause the server to handle the request as a different site.

  1. First confirm that the request uses a DNS resolution path handled by Shadowrocket. App caches, existing connections, or DNS resolution performed remotely can make a local mapping appear to have no effect.
  2. Check that the target service is listening on the port in use. http:// defaults to port 80, and https:// defaults to port 443; the mapping line does not change the port.
  3. For HTTPS, the server must still present a certificate that matches the original domain. If using the mapped IP results in a certificate error, check the server certificate and site configuration first; do not mistake a certificate error for a mapping failure.

URL Rewrite: Match a URL and return a redirect

The 302 syntax in [URL Rewrite] applies to recognizable HTTP request URLs. When a rule matches, it returns a redirect response, and the requesting client decides whether to follow it. This is not a DNS mapping and does not rewrite a destination IP to the value on the right side of the rule. The example below uses plain HTTP and matches one exact old URL:

[URL Rewrite]
^http://docs\.example\.com/old$ http://docs.example.com/new 302
  • The first field is a regular expression. \. matches a literal period, while the leading ^ and trailing $ anchor the match to the entire URL and prevent the rule from matching other hosts or similar paths.
  • The second field is the redirect target. In this example, /old/ and /old?ref=test with a query parameter do not match. /new does not match the original rule either, so this line will not redirect it again.
  • The third field is the action, 302. To verify it, check whether the original request receives 302, whether Location points to the expected target, and whether the new request succeeds. An error at the new address does not mean the original redirect failed.

Test with a site you control. If the client upgrades HTTP to HTTPS before sending the request, this regular expression beginning with http:// will not match. HTTPS paths and query parameters are protected by TLS, so knowing the hostname alone is not enough for path-based rewriting. Changing the regular expression or adding [Host] will not solve this.

Configuration not taking effect? Check the file, policy, and request

I changed the configuration in Config. Why are requests still using the old policy?

First confirm that the changes were saved and that this is the active file. Then check that Global Routing in Home is set to Config. Make the test app establish a new connection, then check the outbound policy for that request; do not use a log entry from before the change.

The rule says DIRECT. Why is traffic still going through PROXY?

Look for an earlier suffix rule or another rule that also matches the destination. Move the exact-domain DOMAIN exception ahead of the broader rule, then test both the exception domain and another domain with the same suffix.

Host points to a test server. Why does the original site still open?

First confirm that the request is still made using the test domain, then check whether the test service received a new request. If it did not, rule out an existing connection, cached data, and remote DNS resolution. If it did receive the request but returned the original site's content, check that the test server is configured to serve the correct site for that domain.

I added a 302 rule. Why doesn't the browser redirect?

Compare the actual request URL with the regular expression, especially the scheme, trailing slash, and query parameters. If the response is already 302, check Location and the follow-up request instead of repeatedly changing the original pattern. Temporarily remove the rule and test again to distinguish a configuration redirect from a redirect already returned by the server.