Shadowrocket Rules Guide
Look up syntax by configuration section and trace match results through the request flow. This page is for users who already have their own subscription or server details and need to maintain a rules file. Example domains and addresses illustrate syntax only; they do not represent available services.
For adding a server, importing a subscription, and connecting for the first time, follow the setup guide. This page explains how those steps relate to the configuration and how to verify changes. Use the setup guide to get started, then refer to this rules guide for details—or consult both as needed.
- Config file: .conf
- Rule: evaluated top to bottom
- Keep the original file before editing
First, distinguish the app purchase, servers, and configurationShadowrocket is a paid client for Apple platforms. Buying the app once does not include a server plan. This site does not provide, sell, or recommend nodes or subscriptions. The App Store is the only place to get the app. See purchase and download information for steps to verify the official listing.
On this page
Confirm the file and routing mode before looking up specific keywords. If something goes wrong, work backward from the final chapter using the evidence you have; there’s no need to replace the entire configuration at once.
Configuration structure and scope
A Shadowrocket configuration file is not another name for a server list. Server details describe connection targets, authentication parameters, and transport settings. A configuration file describes how traffic is handled, how names are resolved, and which requests need special treatment. Updating an existing subscription may update its servers without changing the active rules file. Likewise, importing a rules file does not provide a server to connect to. Separate these two layers before troubleshooting to avoid repeatedly changing the wrong one.
Identify sections and line formats
Common sections include [General], [Rule], [Host], and [URL Rewrite]. A section header in square brackets identifies the section for the following lines, up to the next header. Each section has its own syntax: General commonly uses key-value pairs, Rule uses comma-separated fields, and Host maps names to addresses. A line that looks valid on its own may still fail or behave unexpectedly in the wrong section.
[General]
dns-server = system
[Rule]
DOMAIN,portal.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
[Host]
printer.example.com = 192.0.2.20This snippet illustrates section layout; it is not a complete configuration that can connect to a service. example.com is a documentation example domain, and 192.0.2.20 is a documentation example address. Replace them with targets you are authorized to manage. PROXY in the example does not create a server; it refers to an existing proxy selection. Confirm that your existing server works before deciding whether a domain should use PROXY. That gives you a clear basis for testing.
Check the active file in Config
In Config, check which configuration is selected, then open its contents for editing. Saving a file and selecting a file are separate actions: a file saved in the list may not be the one currently used for connections. To test a new draft, keep the original, save a clearly named copy, and select that copy as the active configuration. Then return to Home and check Global Routing to confirm it is set to Config, not Proxy or Direct.
Treat remote configurations and local copies as separate things. When remote content is updated again, local edits may not be retained; this depends on the file and update method. Before maintaining personal rules over time, establish whether you are editing a local version of a remote file or an independent copy. A successful save now does not guarantee that edits will survive future updates. Recheck key rules after each update rather than guessing how changes are merged.
Read the structure before editing
When taking over a long configuration file, start by searching for section headers. Note where Rule begins and ends and which line contains FINAL, then check for external rule references or additional policy definitions. Don’t judge a rule from one search result alone; a broader condition above it may already match first. Configurations from different sources may use the same keywords but depend on different policy names. Before combining them, check that every reference has a corresponding target in the current file or runtime environment.
Chinese commas, full-width square brackets, and curly quotes inserted by an editor are not part of the syntax shown here. Enter English punctuation in the configuration editor and avoid inserting explanatory Chinese text between fields. Put comments on separate lines so they are easier to read and less likely to be mistaken for part of a policy name. Blank lines can separate groups, but they do not end rule matching; the order of rules in Rule still determines what happens.
Keep one clear final fallback in each configurationWhen maintaining a file, put FINAL at the end of Rule, after exceptions and domain and address rules. Ordinary rules after FINAL cannot participate in the same match.
A maintainable file should let readers answer three questions: where the active file is selected, which existing policies the rules depend on, and how to recover if an edit fails. Record these first; it’s more useful than piling on unverified sections. For exporting files and keeping them when changing devices, see configuration backup and device migration. After restoring a file, check the active configuration and server selection again.
General, DNS & Global Routing
Settings in General provide the basis for connections and name resolution; Rule then chooses a policy under those conditions. If a rule looks correct but access fails, don’t check Rule alone. Name resolution, server reachability, and whether the system has routed the connection through Shadowrocket can all affect the result before the target rule does. Understanding these prerequisites helps separate rule issues from network issues instead of masking the cause with more rules.
What to check in each routing mode
Config, Proxy, and Direct in Global Routing are operating modes, not three rule sections that can be enabled at once. Config applies routing from the active configuration; Proxy sends ordinary forwarded traffic through the proxy path; Direct uses a direct path. System routing, exclusions, and connection-specific restrictions may still affect actual traffic, so a mode label alone cannot confirm what happened. To test Rule, select Config and inspect how the target request was handled.
| Interface label | Meaning | What to check |
|---|---|---|
| Config | Config mode | Verify the routing result from the active Rule |
| Proxy | Proxy mode | Check whether the existing proxy path works |
| Direct | Direct mode | Check direct access on the current network |
For example, if the same target works in Proxy but fails in Config, focus on the matched policy, the server associated with that policy, and differences in name resolution. If both modes fail, check your existing server details and basic connectivity before assuming DOMAIN-SUFFIX is wrong. Success in Direct only shows that the direct path worked at that time; it doesn’t prove a proxy rule is working or that all related resources use the same path.
DNS settings are not a substitute for policies
[General]
dns-server = system
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTdns-server = system means using the system-provided DNS settings. It’s a simple starting point for understanding configuration structure, not a universal recommendation for every network. Actual resolution also depends on other DNS options, request types, and the current connection environment. When maintaining an existing configuration, don’t remove its DNS settings just to copy this snippet. Record the current value, change one thing at a time, compare results, and restore it if needed. Changing DNS, rules, and servers all at once leaves no clear basis for diagnosis.
Domain rules match names; address rules match addresses, and resolution can link the two. If a log shows only an address, don’t assume the client always has the original domain name. If it shows a domain, don’t assume the connection will succeed. Record resolution and connection results separately. If a domain cannot be resolved, check the resolution path first. If it resolves but the connection times out, check the policy route and reachability of the target.
Limits of exclusions and On Demand
Bypass or exclusion settings in an existing file may keep some traffic out of the expected rule path. They are not exactly the same as DIRECT in Rule: DIRECT is a policy applied after a rule matches, while an exclusion may take effect before rule processing. Before changing these settings, read their in-app descriptions and confirm whether they control system routing, proxy exceptions, or something else. Don’t treat two options as interchangeable just because their names sound similar.
On Demand mainly controls when a connection is established or restored; it does not replace Rule when deciding which policy a domain uses. A connection may open automatically while a request still goes direct. In that case, check Global Routing and the match record instead of repeatedly changing On Demand. Conversely, a complete rules file cannot establish a connection by itself. Connection timing and traffic routing after connection are separate concerns.
When adjusting General, keep a concise record of the smallest changes that explain the result: the original value, what you changed it to, the request used to test it, and what changed. After the connection is restored, retest targets that depend on the local network or other name resolution, not just one website. General settings often have a wider scope than a single domain rule, so verify both ordinary use and exceptions rather than checking only whether the home page loads.
Confirm the mode before judging rulesRule examples in this guide assume Config is selected for testing. If you’re using Proxy or Direct, switch back to that prerequisite before comparing rule results.
DOMAIN, DOMAIN-SUFFIX & DOMAIN-KEYWORD
Domain rules express routing intent using names rather than server addresses that may change frequently. First decide whether you need to match one exact hostname, a domain and its subdomains, or a name containing a particular string, then choose the keyword. The broader the match, the greater the chance of unintended matches. For a personal configuration, start with exact matches and combine them into a suffix rule only after request records confirm they serve a shared purpose.
DOMAIN: match one exact hostname
[Rule]
DOMAIN,login.example.com,PROXY
DOMAIN,static.example.com,DIRECT
FINAL,DIRECTDOMAIN matches an exact hostname. The first rule handles login.example.com; it should not be read as matching api.login.example.com or all of example.com. Enter a hostname in the rule field, not a scheme, port, or URL path. For a full address in the browser bar, extract the hostname first. DOMAIN alone cannot express a condition that applies only to a particular path.
A page may contact separate hosts for sign-in, images, APIs, analytics, and other resources. An exact rule for the page’s address covers only one hostname. If text appears but images are missing, check the host used by the failed request rather than immediately broadening the rule to cover every host. Inspect connections from the same page load individually to find any missing resource domains without changing the policy for unrelated traffic.
DOMAIN-SUFFIX: match a domain and its subdomains
[Rule]
DOMAIN,local.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTDOMAIN-SUFFIX matches the specified domain and its subdomains. The example first keeps local.example.com as a direct exception, then sends other names under example.com through PROXY. Enter example.com without an asterisk prefix; *.example.com is not the same notation. Domain boundaries matter: a suffix match does not mean that the same string can appear anywhere in a name.
Put exceptions before broader rules. If you swap the first two lines in the example, the suffix rule matches first and the exact direct rule below it cannot change the result. This is not because DOMAIN has lower priority; Rule is evaluated in order. More precise conditions don’t automatically receive higher priority—the author expresses intent through placement. When adding an exception, find all broader rules that could match first, then choose where to insert it.
DOMAIN-KEYWORD: broad matching requires careful checks
[Rule]
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECTDOMAIN-KEYWORD checks whether a domain name contains a specified keyword, regardless of whether it belongs to a particular domain family. The example illustrates syntax, but isn’t suitable as an everyday rule without review: names containing example don’t necessarily belong to the same organization or serve the same purpose. Short, common keywords are especially likely to match unintended domains. If an exact domain or suffix expresses the need, prefer that clearer scope.
| Keyword | Scope | Common mistake |
|---|---|---|
DOMAIN | Exact hostname | Entering a full URL in the name field |
DOMAIN-SUFFIX | Domain and its subdomains | Adding an unnecessary asterisk prefix |
DOMAIN-KEYWORD | Keyword contained in the name | Treating a keyword as an organization boundary |
When testing domain rules, prepare at least one name that should match and one that should not. For suffix rules, include both the root domain and a subdomain. For keyword rules, also check a name containing the same text that is outside the intended scope. These negative test cases can reveal rules that are too broad. Confirming only that the target opens doesn’t show whether other requests that should go direct are also being sent through the proxy.
For domains with international characters, check the name as it appears in request records, then enter it in a format accepted by the client. Don’t copy a display title that contains spaces or assume the readable text shown by a browser is the final match value. Another common mistake is repeatedly refreshing the same page after editing a rule: the app may reuse an existing connection. Generate a new request and confirm that the new connection uses the updated policy.
As the number of rules grows, group exact exceptions, business-related suffixes, and carefully used keywords into small blocks, but don’t sort mechanically by keyword. Order should reflect exceptions and their relationships, not the alphabet. To route only selected websites through a proxy, see rules for routing selected websites. Start with a short list and add resource hosts as needed; there’s no need to cover a large number of unrelated names at once.
GEOIP, IP-CIDR, IP-CIDR6 & USER-AGENT
Address rules answer “which address range does this target belong to?”, not “which app is the user running?” They’re useful when a request connects directly to an address, domain information is unavailable, or a clearly defined internal network needs an exception. But different services may share addresses, and resolution results can change, so don’t permanently assign a large address range to a policy based on one observation. Confirm where the address came from and who maintains it before adding it to the configuration.
IP-CIDR: the address and prefix length define the range
[Rule]
IP-CIDR,192.0.2.20/32,DIRECT,no-resolve
IP-CIDR,198.51.100.0/24,PROXY,no-resolve
FINAL,DIRECTAn IPv4 IP-CIDR field consists of a network address and prefix length. /32 represents one address; /24 represents a range. The number is neither a port nor a priority. The example uses an address reserved for documentation and cannot tell you whether a real network is reachable. When maintaining a configuration, confirm the intended network boundary. Adding a short prefix to a single target address at random may include many unrelated targets.
no-resolve is an optional parameter for address rules that avoids triggering domain resolution just to check that rule. It does not disable all DNS or guarantee a match. Address matching can still take place when the request already has an address to compare; if only a domain name is available and there is no corresponding address, don’t expect the rule to resolve it first. When troubleshooting, record whether the request provides a name or an address.
IP-CIDR6: check the IPv6 path separately
[Rule]
IP-CIDR6,2001:db8::20/128,DIRECT,no-resolve
IP-CIDR6,2001:db8:1::/48,PROXY,no-resolve
FINAL,DIRECTIP-CIDR6 uses an IPv6 network prefix; /128 can represent a single IPv6 address. 2001:db8:: in the example is reserved for documentation. An IPv4 address rule alone does not mean a connection to the same domain over IPv6 will match. If both address families are available on the network and target, test the address family actually in use. One successful IPv4 test doesn’t confirm that routing for the target is complete.
If the same target uses different policies on different networks, first check the resolution results and the address actually used for the connection. Then see whether the configuration has a rule for only one address family. Disabling a type of address may temporarily change the behavior, but it doesn’t prove the rule scope is right. If the need is really about a stable domain family, prefer domain rules. Use address rules for clearly defined ranges you manage; they’re usually easier to maintain that way.
GEOIP: classify by address database
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXYGEOIP classifies a target address using an address database. GEOIP,CN,DIRECT means that an address classified as CN by the database uses DIRECT. It does not classify by page language, domain suffix, or the user’s location. Database classification may not reflect business ownership, especially for targets using distributed infrastructure. Put specific business exceptions before GEOIP rather than using address classification to guess which route a domain should take.
GEOIP also depends on having usable address information. If a request doesn’t match the expected region, check the actual target address, its database classification, and any earlier rules instead of changing the country or region code alone. When combining GEOIP and FINAL, make sure you know where unmatched requests go: the example sends them to PROXY, the opposite of the default in FINAL,DIRECT. Read the last line before copying a snippet.
USER-AGENT: request attributes are not app identity
[Rule]
USER-AGENT,ExampleClient*,DIRECT
FINAL,PROXYUSER-AGENT matches available User-Agent information. The example uses ExampleClient* to illustrate a value that starts with that text. This is not a general way to route by app name: multiple apps may use the same identifier, and one app may use different identifiers for different requests. If the request headers aren’t readable for an encrypted request, don’t expect this rule to identify its internal User-Agent.
Before using USER-AGENT, confirm that the relevant attribute is visible in the records, then test it with a specific request. Don’t broaden decryption settings just to make this rule work, and don’t mistake a failed header match for a proxy server problem. Names, addresses, and request headers are different kinds of evidence. Choose the corresponding keyword only when you know which information the current request provides.
PROXY, DIRECT, REJECT & match priority
A rule combines a condition with an action: the preceding fields say what to match, and the policy field says what to do when it matches. PROXY, DIRECT, and REJECT are common policy keywords. Distinguish them from Proxy and Direct in the Global Routing interface by their capitalization and where they appear. Read the condition and action together; the presence of a domain alone doesn’t tell you how it will be handled. The same domain can behave very differently under different policies.
What each policy does
PROXY sends matching traffic to the selected proxy and requires an existing, working server with valid connection settings. A PROXY match chooses an outbound route; it does not guarantee that the server is reachable or the target will accept the request. DIRECT connects to the target directly and still depends on successful resolution and network access. REJECT denies matching requests. Use it only for clearly scoped targets you know can be blocked; it is not an instruction to try another route if a request fails.
| Policy | What it does | What to verify |
|---|---|---|
PROXY | Send through the proxy path | Match result and reachability of the existing server |
DIRECT | Use a direct path | Resolution result and reachability on the current network |
REJECT | Reject the request | Whether only the intended target is affected |
DIRECT doesn’t exit Shadowrocket or turn off the connection. It can be the result of one rule under Config while other requests continue to use PROXY. Similarly, REJECT doesn’t disconnect the entire device; it applies only to requests matching that condition. But blocking a shared API, authentication service, or resources used by multiple pages can have a broad impact. Use precise conditions and keep a way to revert them.
The first matching rule determines the policy for that request
[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,office.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,DIRECTThe example first rejects one exact host, preserves a direct exception for another, sends other names under the suffix through PROXY, checks GEOIP, then uses FINAL for anything unmatched. Priority comes from position, not a ranking of keywords by precision. Move the suffix rule to the top and it will override both exact rules. Put FINAL first and the remaining ordinary rules won’t participate in the match.
“Stop at the first match” means Rule stops looking for another ordinary rule to choose a policy for that request. It doesn’t mean the entire request lifecycle uses just one configuration feature. DNS, connection setup, and other processing mechanisms still have their own stages. Nor does a failed connection automatically proceed to the next rule: if a PROXY match fails to connect, a DIRECT rule below it usually won’t become a fallback. Fix the path required by the matched policy rather than expecting a later rule to take over.
FINAL: define where unmatched requests go
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTFINAL needs no domain or address parameter. It provides a policy for requests not matched earlier. The example means “use the proxy for the listed domains and connect directly to everything else.” Change it to FINAL,PROXY and the default direction changes; all unlisted requests may then use the proxy path. Many apparently local issues actually come from overlooking FINAL when copying a configuration. Before changing the fallback policy, list exceptions that need to remain, such as sign-in, local network access, and frequently used services.
For easier maintenance, keep just one FINAL at the end. Multiple FINAL rules don’t create a fallback chain to try in turn: the first one already handles the remaining requests, leaving later rules of the same kind with no opportunity to match. If an editing tool creates duplicate ending rules, first check which section belongs to the active Rule, then remove redundant lines. Don’t delete lines just because they look duplicated without checking whether two configuration sections from different sources were combined.
Custom policy references must resolve
More complex files may use custom names in the policy field instead of PROXY. Confirm that each name is defined in the current configuration and supported by the app, and that it points to an available target. Copying a rule that refers to an external policy without copying or creating its definition leaves an unexplained dependency. This guide uses built-in policies to explain the core syntax and avoid presenting naming conventions from one configuration as fixed keywords.
Check the rules above, not just the neighboring linesTo find what overrides a rule, trace Rule from the first line down to the first match. An earlier keyword, address rule, or external rule reference may determine the result before the exact rule you’re looking at.
The goal of ordering is to make exceptions easy to understand, not simply to make the file look tidy. Add a separate comment explaining each rule and why it needs to come before the group below it. Before making future changes, check whether that reason still applies. You can combine rules safely only when you can explain their placement. Isolate and test rules with unclear purposes instead of adding them straight to a long-term configuration.
What Host and URL Rewrite are for
Host and URL Rewrite can both affect the result users see, but they solve different problems. Host maps names to addresses; URL Rewrite matches and processes visible URLs. Host is not a proxy policy, and URL Rewrite is not a replacement for domain-based routing. To decide which feature you need, describe the goal in one sentence: specify a resolution address, choose a connection route, or change one form of address into another.
Host: a fixed mapping does not fix the route
[Host]
printer.example.com = 192.0.2.20
[Rule]
DOMAIN,printer.example.com,DIRECT
FINAL,PROXYThe example maps a name to a documentation-only address and uses Rule to select DIRECT for that name. These lines handle resolution and routing separately; neither replaces the other. In actual use, the address must be a target you’re authorized to use and that your current network can reach. Pointing a domain at an address won’t make an unreachable network accessible or create authentication, port forwarding, or virtual-host configuration on the server.
A fixed mapping can also override dynamic resolution. If a target relies on changing addresses, location-based routing, or failover, an outdated mapping may cause connection timeouts. Before adding one, confirm that a fixed address is really needed and record how to remove it. During testing, check not only that the name resolves to the expected address, but also that the service, port, and certificate identity are correct. An address responding doesn’t prove the service is working.
Host does not change the hostname the browser is visiting. When connecting to an HTTPS hostname, the server certificate must still pass validation for that name. Mapping a name to an address that doesn’t serve it may lead to a certificate error or the wrong site; don’t handle this by ignoring validation. Check that the target service supports the hostname and that the mapping is for an authorized test environment. After restoring normal resolution, make sure the relevant cache has updated.
URL Rewrite: regular expressions, targets & actions
[URL Rewrite]
^http://legacy\.example\.com/(.*)$ https://www.example.com/$1 302This example uses a regular expression to match an old URL, carries the captured path to a new address, and returns a 302 redirect. The backslash before each dot makes it match a literal dot. The anchors at the start and end limit the match, and $1 refers to the captured text inside the parentheses. Both domains are examples. Before using this in your own configuration, replace them with targets you’re authorized to test, and check whether query parameters and encoding are preserved as needed.
A dot in a regular expression has a special meaning by default. If you forget to escape it, the expression may match unintended names; omitting hostname boundaries can also affect similar-looking addresses. When maintaining URL Rewrite, prepare a matching example, a similar address that should not match, and examples with paths and query parameters. Don’t test only the home page: a successful redirect with no path doesn’t prove that longer URLs are handled correctly.
Limits of encrypted visibility and processing stages
The path in a full HTTPS URL is encrypted; ordinary traffic routing cannot simply read every field in it. Whether a URL Rewrite rule applies depends on which request details are visible and the relevant processing conditions. Writing a regular expression doesn’t automatically make the URL path readable. Don’t broaden decryption settings just to test a redirect. Evaluate settings that affect certificates and encrypted traffic separately, including authorization, privacy, and app compatibility.
Don’t extend Rule’s top-to-bottom matching principle to mean that the entire configuration file runs once from top to bottom. Sections have different functions; Host appearing before Rule in the file doesn’t mean it necessarily runs first in the order shown. To troubleshoot a rewrite, follow the request: what was the original URL, did a redirect occur, what was its destination, and which policy handled the next connection? This helps distinguish a rewrite that didn’t trigger from a failed redirect target or an error in subsequent routing.
If redirects repeat, disable the newly added rule firstA loop may occur if the new destination matches the old rule again or the site sends the request back to its original address. Restore the original configuration and confirm normal behavior, then narrow the regular expression. Don’t keep adding redirects in the opposite direction.
Browsers may cache redirect results, and apps may cache resolution and connections. If old behavior continues after removing a rule, that doesn’t necessarily mean the file wasn’t saved. Confirm the active configuration, then check again with a new request or a separate test session. For long-term rewrites, record the purpose, applicable hosts, expected action, and removal criteria. Otherwise, a site may change its URL structure while a local rule keeps forcing an outdated flow.
Host and URL Rewrite work best for narrowly scoped, explainable needs; they aren’t the right starting point for every access problem. If you simply want a site to use PROXY, go back to domain rules. If resolution is wrong, check DNS and existing mappings first. If a site rejects a request, check authentication and the service response as well. Identify the layer where the problem occurs before choosing a configuration section. The file will be shorter and the issue easier to reproduce.
Common routing patterns and how to edit them
Start with the requirement, not the number of rules. First choose the default policy, list the targets that need exceptions, then decide whether to match exact domains, suffixes, or addresses. Each snippet below illustrates a separate approach; don’t paste them all consecutively into the same Rule section. When combining approaches, revisit FINAL, exception order, and duplicate conditions, or later snippets may never be evaluated.
Route selected websites through the proxy; connect directly to everything else
[Rule]
DOMAIN,account.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-SUFFIX,example.net,PROXY
FINAL,DIRECTThis pattern suits a clearly bounded need to proxy only targets on a list. Put account hosts that need a direct connection first, then add the two example domain families, and send the remaining requests to DIRECT. When adapting it, first test one target to confirm that both the server and rule work, then add other hosts the service depends on as needed. Don’t change FINAL to PROXY just because one resource is missing; that changes the route for every unlisted request and turns a narrow setup into something else.
When maintaining a list, record the page address separately from the actual resource requests. A service may host static files, APIs, and sign-in flows on other domains; suffix rules can’t infer those relationships. Add only targets you’ve observed and actually need, then verify that a commonly used site outside the list still connects directly. For details, see how to route only selected websites through a proxy.
Connect directly to specific exceptions and proxy everything else
[Rule]
DOMAIN,portal.example.com,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
FINAL,PROXYThis pattern does the opposite: it sets exact hosts and common private IPv4 ranges as direct exceptions, then sends everything else through the proxy. Private address rules cover only their specified address conditions; they don’t guarantee that all local network discovery, broadcasts, or special network features will work as expected. If your network uses different ranges or IPv6, assess those separately. A few private address rules are not a complete replacement for system network configuration.
Before using FINAL,PROXY, confirm that your existing proxy path handles your day-to-day needs, and check authentication, local network services, and any required direct exceptions. If a service needs a direct connection, add a clearly scoped rule and test whether it affects other requests on shared infrastructure. If a service uses many changing domains, maintain the rules from observed records instead of guessing a broad keyword and expecting it to stay accurate.
Reject one exact host while keeping other requests in the same domain
[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN-SUFFIX,example.com,DIRECT
FINAL,DIRECTThis pattern rejects one exact host without blocking the entire suffix. For your first REJECT test, choose a target with a clear purpose that won’t disrupt a critical workflow. Then check whether the page, sign-in, and APIs still work. A failed request may be the intended result, but users may not be able to tell what caused it, so keep a clear comment. If the rule affects something it shouldn’t, removing it is easier than layering on more patches.
If a blocked host also serves other essential functions, a domain rule can’t distinguish between its uses. Reassess the requirement instead of broadening the block as a workaround. After REJECT blocks a request, the app may retry or use another target. A new request in the records doesn’t mean the original rule failed. Compare each request’s actual name and policy to determine whether it’s a retry to the same target or a separate connection initiated by the service.
Safely add a rule to an existing file
Copy the original configuration first, then find the existing Rule section and its final FINAL. Place new exceptions before any broader rule that could match first; don’t add a second Rule section and guess how it will merge. If the existing file contains rule references, understand their scope before deciding whether to insert the new rule before or after them. Save and select the copy, confirm Global Routing is set to Config, then generate a new request and check the match. If verification fails, return to the original copy rather than continuing to edit an uncertain version.
- Write down the goal, default policy, and exceptions to preserve.
- Record the active configuration, server selection, and Global Routing mode.
- Add only the rules needed for this change; check the fields, policy names, and FINAL position.
- Test requests that should match, should be excluded, and are part of everyday use.
- Once verified, save a note. If the result is unexpected, restore the original file and continue troubleshooting.
A subscription update may change the server list, but it doesn’t replace rule verification. If a server used by the current policy changes, check the proxy path again. A change to the displayed server name alone doesn’t mean the rules have changed. If you manage multiple subscriptions, see how to group and organize multiple subscriptions. Keep source management separate from rule maintenance so a duplicate server issue isn’t mistaken for a rule exception.
Verify matches, troubleshoot, and restore configuration
The goal of rule testing isn’t to get lucky with one successful visit. It’s to confirm that a specific request uses the intended policy under the intended conditions without breaking behavior you need to keep. A complete record should include the test time, active configuration name, Global Routing mode, target name or address, actual match result, and connection behavior. The time is for comparing this test with others, not application update information. Specific evidence makes it possible to compare results when the network changes.
Troubleshoot layer by layer instead of guessing from rule count
First confirm that a connection is established and the intended file is selected, then check whether the request enters the expected processing path. Next, verify name resolution and the actual target, check which rule matches first, and finally confirm that the policy route is available. If an earlier layer has already failed, changing a later one usually won’t help. For example, adding more domain suffixes won’t necessarily fix a resolution failure; moving FINAL won’t fix a failed server connection after a PROXY match.
| What you see | Check first | Next step |
|---|---|---|
| None of the new rules have an effect | Active configuration and Config mode | Select the file and generate a new connection |
| An earlier rule matched the target | Rules that match above it | Move necessary exceptions ahead of broader rules |
| PROXY matches, but the connection fails | Existing server and target reachability | Compare the Proxy mode result and the specific error |
| Only some resources fail | The actual host used by the failed resource | Check each relevant request, not just the page title |
| Old behavior remains after reverting | Cache, persistent connections, and active file | Generate a new test request before comparing |
Connectivity Test can help assess how existing servers respond to a test, but it doesn’t prove that every site, protocol, or service request will work. A successful test may still be followed by a real request that fails due to name resolution, a target rejection, or service authentication. Treat the result as one piece of evidence, not a final answer. Likewise, a page loading successfully doesn’t prove it used PROXY; check the policy recorded for the relevant request.
Build positive, negative, and regression test cases
A positive test shows that a target should match; a negative test shows the scope hasn’t widened; a regression test confirms that existing behavior still works. For example, after adding DOMAIN-SUFFIX, test the root domain and a subdomain, then a name outside that suffix, and finally sign-in and local network access. Don’t test against targets you don’t understand; use services you’re authorized to access and whose purpose is clear. Example domains are for illustrating syntax only.
Change one variable at a time where possible. Keep the server, network, and routing mode the same; change one rule, compare results, then move on. If you must switch networks, record that separately so a network-related resolution difference isn’t attributed to the rule change. When a page reuses connections, close the relevant test session and make a new request. New rules are best checked with new connections; the behavior of an existing connection is not enough on its own.
Sharing logs and protecting sensitive information
If you need to share records for troubleshooting, include only the target, rule, policy, and error details needed to reproduce the issue. Remove authentication parameters from subscription URLs, server passwords, private request paths, account identifiers, and credentials from the full configuration. Screenshots may contain the same information, so check them too. Replace sensitive values with clear examples and note which fields were changed. This preserves useful diagnostic detail while protecting private information.
To narrow down a problem, create a minimal test configuration with the necessary General settings, one rule for the target, and one FINAL. Continue to use your existing server. If the minimal configuration works, restore the original rules group by group until you find what changed the result. Keep the existing order within each group; don’t reorganize the whole file at the same time. This helps identify whether the issue comes from a condition, an external reference, or the order of multiple exceptions.
After restoring, check the runtime state again
Rolling back means more than changing the text back. Select the original configuration, confirm Global Routing and the existing server selection, reconnect if needed, then compare against a previously successful test case. If the original file still behaves differently, consider whether the network, server, or service has changed rather than attributing every issue to your edit. Keeping both versions and a short record helps avoid introducing new differences when restoring from memory.
How to know a change is completeThe target matches correctly, exceptions aren’t catching unrelated traffic, everyday requests pass regression tests, and you can restore the previous state. Once all four are confirmed, use the tested copy as your long-term configuration.
When restoring on a new device, first confirm that the app came from the App Store. Then restore your saved server details and configuration file, and check the active configuration and system connection permissions. For system requirements, refer to the App Store listing. For purchases and redownloading the app, see restore a previous purchase and the purchase FAQ. For first-time connection steps, return to the setup guide; use this page’s contents to review each rule.
For ongoing maintenance, keep a stable version and a test version: put only verified changes in the stable file, and use the test file for new conditions and experiments. Periodically remove obsolete exceptions, check that fixed addresses are still valid, and review personal rules after updating a remote configuration. A rules file is valuable not for its length, but when every condition has a clear purpose, every result can be checked, and every change can be rolled back.