Shadowrocket
Configuration and Rule Reference

Configuration File Structure and Scope

First, distinguish server details from configuration files

Server details specify the address, port, protocol, and authentication fields needed to connect to a remote server. A configuration file defines how requests are handled, which rules apply, and how domains are resolved. Importing a subscription into Home does not replace the rule file in Config. Conversely, importing a file containing Rule entries does not add your server credentials. When troubleshooting, identify which of these two items is involved before making changes.

In Config, check which configuration is selected, then open it to review its contents. Importing, saving, and selecting are separate actions: seeing a file in the list only confirms it exists; seeing new content in the editor only confirms that file is open. To know whether it controls connections, verify that it is selected. Before editing, note the file name and selection state. After saving, check them again, then reconnect if needed so your next test uses the updated configuration.

What each of the four sections does

Section names appear in square brackets, with fields and rules listed under the relevant heading. General contains common settings, Rule matches requests and assigns policies, Host maps domain names to static addresses, and URL Rewrite matches and rewrites URLs. These sections aren’t interchangeable: adding a domain mapping under Rule won’t make it a Host entry, and putting a redirect expression under General won’t create an executable routing rule. Section names and rule keywords remain in English.

[General]
bypass-system = true
skip-proxy = 192.168.0.0/16, 10.0.0.0/8, localhost
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,DIRECT

[Host]
localhost = 127.0.0.1

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

This example sends unmatched requests to DIRECT and uses PROXY only for the example domain, so it is not a general-purpose proxy configuration. Understand the final policy before copying it. The bypass settings in General can also change the request path. If a request has already bypassed the proxy earlier, moving a Rule entry won’t bring it back into rule matching.

A basic editing, saving, and backup workflow

Keep a working file, then make a copy for experiments. Change one section or rule at a time, save, select the updated file, and test. If the file comes from a remote URL, check whether the next update will overwrite local changes. For changes you need to keep, use a local copy you can maintain independently rather than relying on differences that may disappear during an update. Choose a backup name that makes its purpose clear, but don’t include account details, server addresses, or credentials.

Separate rule parameters with commas, and use equals signs for general fields and Host key-value pairs. Don’t paste configuration with Chinese punctuation, explanatory text, or unusual spaces from a webpage. Line breaks in the examples are real line breaks, not visual wrapping. If a line is too long in the editor, scroll horizontally rather than splitting the rule across lines. Put comments on their own lines beginning with #; don’t append notes after policy parameters.

A file that saves successfully isn’t necessarily correct in every respect. A correctly spelled but overly broad DOMAIN-KEYWORD can match unrelated requests, while a valid FINAL can mask later rules if it appears too early. Verification should cover syntax, selection state, and actual request results—not just whether the editor reports an error.

General Fields and DNS Handling

General fields do more than introduce the rules

General determines how some requests enter the processing chain and where domain resolution gets its information. Review it before Rule: whether a connection enters proxy handling, whether an address has already been resolved, and whether the domain is still available for matching can all affect the result. Don’t treat General as a universal template. A bypass range that works on one local network may not suit another.

bypass-system = true lets relevant system traffic bypass proxy handling. It is not a switch that sends all requests direct, and it is not the same as Direct in Global Routing. If you keep this setting, be aware that some system requests may not follow the ordinary rule path. If a system feature doesn’t work, investigate the specific request and network environment; one webpage test can’t tell you how all system traffic behaves.

skip-proxy specifies destinations that bypass proxy handling, commonly local network addresses and local host names. This bypass happens at a different stage from choosing DIRECT in Rule. DIRECT is a policy selected after a request enters rule processing; a skipped request may not follow the usual proxy rule path at all. If the expected Rule match doesn’t appear in the log, check the skip list before copying the same rule to the top of the file.

[General]
bypass-system = true
skip-proxy = 192.168.0.0/16, 10.0.0.0/8, localhost
dns-server = system

What system means and how to establish a baseline

dns-server = system uses the DNS source provided by the system; it does not pin resolution to a specific DNS server. The system’s DNS settings can change when you switch Wi-Fi networks or use mobile data. Local network names may also be known only to the DNS service on that network. Starting with system DNS helps establish whether the current network can resolve the target before you decide whether to specify another source in your own setup.

DNS resolves names to addresses; rules determine which policy handles a request. The two are related but serve different purposes. DOMAIN rules can match a known domain, while GEOIP and IP-CIDR apply to addresses and may depend on a resolved address. If the log shows a resolution failure, the required address hasn’t been obtained yet. That doesn’t prove the PROXY server is unavailable, and adding FINAL can’t fix a missing DNS result.

It’s also important to distinguish app requests from DNS queries. A webpage using PROXY doesn’t prove that every DNS query follows the same path; resolution also depends on the app, system cache, and configuration options. For a precise diagnosis, check the actual logs and current configuration rather than inferring the DNS path from a rule’s policy name. If the server is identified by a domain, make sure that domain can be resolved too, so a failure at the connection entry point isn’t mistaken for a routing issue with the target site.

Checks before and after changing DNS

If external domains resolve but internal names don’t, first check whether you’ve left the network that provides internal DNS. If no names resolve but a known address is reachable directly, focus on the DNS source. Don’t change DNS, server settings, and Rule all at once; even if the connection recovers, you won’t know what fixed it. After each change, retest the same target on the same network with a new connection, and record the result.

DNS caching can make a change appear to take effect late. The system, client, and app may keep previous results, and a browser may reuse an existing connection. Refreshing a page after saving the configuration may not trigger a new DNS lookup. Disconnect and reconnect, then reopen the target app. Check the system’s network state only if the issue persists and there’s a clear reason to do so. A cache hit doesn’t verify that the new configuration works.

Check IPv4 and IPv6 separately. A domain may return both types of address, while one may be less reachable on the current network. The result can be successful resolution followed by a connection timeout. Check the address actually used and the rule that matched instead of changing the DNS source by default. Rather than adding fields from unclear sources, keep a working baseline and correlate four things: name, address, policy, and connection result.

Scope of DOMAIN Rules

Exact host names and domain suffixes

DOMAIN matches a specified domain name, making it suitable for a single, clearly identified host. For example, if only api.example.com should use PROXY while other names on the same site remain unchanged, start with an exact rule. Enter the domain itself—without a scheme, path, port, or query string. A full webpage URL may look more specific, but it isn’t the match target this rule expects.

DOMAIN-SUFFIX matches a domain suffix by label, so example.com can cover the domain itself and its subdomains, such as www.example.com and api.example.com. It doesn’t match arbitrary string endings without regard to boundaries; the dot-separated domain labels matter. Usually, enter the suffix as a domain—there’s no need to add an asterisk or append a webpage path.

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
FINAL,DIRECT

This order lets the exact api rule match first, then covers other requests to example.com. If DOMAIN-SUFFIX comes first, api requests will match the broader rule, and the later DOMAIN entry won’t get special priority for being more specific. Specificity guides how you arrange rules; the rule engine doesn’t automatically reorder them.

Why keyword rules need care

DOMAIN-KEYWORD matches a keyword found in a domain name, making it useful when a string-based scope is genuinely needed. It doesn’t know which site owns the name or what the word represents. The keyword example could appear at different levels and under different suffixes, so its scope is usually broader than DOMAIN-SUFFIX. When a specific domain or suffix will do, prefer the narrower, easier-to-review rule.

[Rule]
DOMAIN,login.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECT

The keyword rule here demonstrates the hierarchy; an actual configuration doesn’t need all three forms. The login host uses DIRECT first, the domain and its subdomains use PROXY next, and the third line handles other names containing the keyword. Remove broad rules that don’t meet a specific need to reduce accidental matches and troubleshooting work. More rules don’t make a configuration more accurate.

Information needed for domain rules to match

The request must have usable domain information for a domain rule to match by name. If an app connects directly to an IP, or the original domain is unavailable at the relevant stage, the rule engine may only be able to check address rules. Entering a domain in a browser doesn’t prove that every subsequent connection retains the same name. The page may also load images, APIs, fonts, or other resources from different domains.

If the homepage loads but some resources fail, find the actual failed request domain in the log rather than adding duplicate rules for the homepage. A page may depend on several domains; decide whether they should use the same policy based on the actual requests. Don’t broaden a short keyword to catch every similar name, or assume one successful visit proves all dependencies are covered.

For testing, choose one name that should match and one that shouldn’t, then observe the policy for each. The first checks that the rule works; the second checks that its scope isn’t too broad. With DOMAIN-SUFFIX, test both the root domain and a subdomain. With DOMAIN, confirm that a neighboring subdomain isn’t included by mistake. Testing both a positive and a negative case reveals scope errors better than checking one successful page.

Domain-name case is rarely the focus of troubleshooting, but consistent parameter formatting makes rules easier to review. For internationalized domains, unusual names, or normalized forms used by an app, rely on the match target shown in the log. Don’t infer rule parameters from the page title: the visible title, link text, and actual host connection can all differ. Keep a record of what you tested so you can tell whether a later issue came from a rule change or a different request.

IP-CIDR, IP-CIDR6, and GEOIP

Address ranges are not domain categories

IP-CIDR applies to IPv4 address ranges. Its parameter consists of a network address and prefix length. 192.168.0.0/16 describes a private address range, not a single host. To match one IPv4 address, use that address with /32. Before adding a rule, confirm the actual target address and mask. Don’t mistake a router address for an entire network or broaden a rule to every private range just to cover one device.

IP-CIDR6 applies to IPv6 address ranges, with the prefix length defining the scope. fc00::/7 covers IPv6 unique local addresses, while ::1/128 refers only to the loopback address. IPv4 and IPv6 rules don’t replace each other. If a domain resolves to both types, an IPv4-only range won’t automatically constrain IPv6 connections. Check the address family shown in the log when troubleshooting.

[Rule]
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
IP-CIDR6,fc00::/7,DIRECT,no-resolve
FINAL,PROXY

This snippet sends the listed local address ranges to DIRECT and other requests to PROXY. It doesn’t cover every special-purpose address or replace the bypass settings in General. “Local networks go direct” doesn’t mean every local network name will be reachable: the name still has to resolve to the correct address, the network must allow access to the device, and the target service must be available.

no-resolve controls whether resolution is triggered

no-resolve avoids triggering an additional domain lookup just to match that address rule. It isn’t an alias for DIRECT and doesn’t disable DNS for the whole configuration. If a request already includes a matchable address, the rule can still evaluate it. If there’s only a domain and the required address isn’t available, don’t expect the rule to resolve it proactively before matching. Add this option based on the kind of request you need to match.

For local devices accessed directly by IP, a network rule with no-resolve is relatively straightforward. For devices reached by an internal name, confirm that resolution returns a local address. Adding this option to every address rule just to “reduce lookups” may change paths that previously depended on DNS results. If behavior changes, check whether the request already had an address when it reached the rule instead of looking only at whether the final webpage loaded.

GEOIP uses an address database

GEOIP checks an IP address against a geolocation database. GEOIP,CN,DIRECT is a common syntax example. It doesn’t classify traffic by webpage language, domain suffix, account region, or the user’s location. A Chinese-language page may use addresses with different database locations, and a distributed service may return different addresses for the same domain. GEOIP is therefore a broad address classification layer, not proof that a particular service should always use DIRECT.

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

Putting a domain exception before GEOIP gives that name an explicit policy first. Address ranges and geolocation can then handle the remaining requests, with FINAL as the fallback. If GEOIP comes before a needed domain exception and the address condition is met, the request may match the address rule first. “Domain first” must be expressed through rule order; rule types don’t guarantee it automatically.

Database location doesn’t necessarily indicate whether a network can reach an address right now. If a connection fails after matching GEOIP, the target may be unreachable from the local network or its service may be down; that doesn’t mean the GEOIP syntax is invalid. For a stable exception, use a specific, verifiable domain rule. Don’t turn a temporary resolution result into a permanently broad address-range exception.

Address rules can also be affected by connection reuse. After changing a range policy, an app may continue using an existing connection, so the log may show no new match. Establish a new connection, then check the target IP, rule type, and final policy. If the same domain resolves to different addresses, keep track of the difference to determine whether the address pool changed or the rule scope is incomplete instead of repeatedly moving FINAL.

Policies, Global Routing, and Rule Order

Keep rule policies separate from the app’s routing mode

In rules, PROXY, DIRECT, and REJECT are request-handling policies. In Home, Config, Proxy, and Direct under Global Routing are overall routing modes. The terms are related but shouldn’t be mixed up. In Config mode, check the selected configuration’s Rule entries. In Proxy or Direct mode, don’t explain test results using expectations for normal rule-based routing. Always note the current mode in your troubleshooting record.

The overall routing mode doesn’t remove boundary settings such as system-level bypass or skip ranges. Comparing the three modes helps separate server-path issues from configuration matching; it doesn’t prove every system request follows the same processing path. After testing, restore the expected Config mode before verifying rules. Otherwise, even a correctly edited file may not produce the routing results you expect.

What the three common policies do

PROXY sends a matching request through the current proxy path, which requires server details you already have and can use. A PROXY rule only selects that policy; it doesn’t confirm server authentication or guarantee that the remote server can reach the target. DIRECT connects to the target through the current network, but the connection can still fail because of local routing, resolution, or the target service. REJECT blocks matching requests and is appropriate when blocking is intentional—not as a way to hide an unexplained connection failure.

If a configuration refers to an additional named policy, first confirm that the selected file defines and supports it. Don’t use a server remark as a policy keyword without checking. The examples here use only the three basic policies to avoid dependencies on objects outside the file. Server remarks, subscription names, and rule policies belong to different layers; similar names aren’t interchangeable.

Top to bottom: the first matching rule wins

Rule entries are checked in file order. The first matching rule determines the request’s policy; later ordinary rules don’t keep searching for a “better” match. A useful order is to put specific exceptions first, broader categories later, and FINAL at the end for anything that remains. The actual scope is what matters: a keyword rule that looks specific may still be broader than a later suffix rule.

[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

The blocked name is rejected first, the api name uses PROXY, and other example.com names use DIRECT. If the first line and suffix rule are swapped, the suffix rule can mask the blocking exception. If FINAL is placed first, it closes out matching early and prevents later rules from working as intended. To check rule order, trace a request through each condition rather than just searching the file for its domain.

FINAL has no match target and is usually written as FINAL,PROXY or FINAL,DIRECT at the end of Rule. It defines the default policy; it doesn’t mean every request must pass through it. To decide whether FINAL is appropriate, first ask how unmatched requests should be handled, then check whether your existing server is usable. Neither ending is universally right regardless of context.

For easier maintenance, group rules as “blocking exceptions, exact domains, domain suffixes, address categories, and final policy,” with comments before each group. Whenever you add a rule, check whether an existing rule already covers the target. Duplicate lines don’t usually improve reliability; they can mislead maintainers into thinking a later line can override an earlier decision. Before removing duplicates, confirm that their parameters are truly identical so you don’t delete an intentional difference in scope.

If Proxy mode works but Config doesn’t, start by checking the matched rule, DIRECT branches, REJECT, and DNS behavior. If both fail, check server details and network connectivity. Direct working doesn’t prove that every target should be accessed directly; it only shows that the tested target was reachable over that path at that time. Record the same target’s result in all three modes for a useful comparison.

Host Static Mapping and Address Boundaries

Maps names; doesn’t select a policy

Host maps a specified domain to a static address. It changes the address associated with a name; it doesn’t select PROXY or DIRECT and doesn’t replace Rule. To assign an address to an internal service and connect to it directly, handle the mapping and policy separately. Adding a Host entry doesn’t automatically make a request go direct, and adding a DOMAIN rule doesn’t make a name resolve to a specified address—those are separate functions.

[Host]
localhost = 127.0.0.1
intranet.example.com = 192.168.1.20

[Rule]
DOMAIN,intranet.example.com,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

The internal names and addresses here are teaching examples. They’re useful only if the corresponding service exists on your own network. Adding an example domain to a configuration doesn’t create a server, and a static mapping won’t start the target service. Before using a mapping, confirm the device address, service port, and current network so you don’t mistake an example for a ready-to-use service.

localhost points to the current device

localhost = 127.0.0.1 is the IPv4 loopback address. It points to the device making the request—not the router or a proxy server. On a phone, localhost won’t reach a service on another device. If a guide asks you to connect to a device on your local network, use its actual reachable address or the correct internal name, and confirm that the service accepts connections from other devices.

Private addresses are meaningful only within the relevant network routes. 192.168.1.20 may work on your home Wi-Fi but be unavailable on another network—or belong to a completely different device there. Before mapping an internal name to a private address, consider where the mapping will be used. If you use the file across multiple networks, a static mapping can keep sending the name to an obsolete address, causing a timeout instead of a DNS failure.

Host doesn’t bypass TLS identity checks

HTTPS connections still check whether the target certificate matches the requested host name. Pointing a domain to a different address doesn’t make an arbitrary certificate on that address valid; the server may also choose a site based on the host name. If a mapping causes a certificate error, check whether the address belongs to the service and whether the certificate covers the original name. Don’t take the error as proof that Host didn’t apply. Resolution and identity verification are separate checks.

One IP address can host multiple sites, with the domain name distinguishing each request. Being able to connect to an IP doesn’t mean every domain mapped to it will work. When checking an internal HTTPS service, verify the name, address, port, and certificate together. This guide doesn’t require changing certificate trust to use a static mapping; prefer the correct name and address already configured for your own service.

Static Mappings, Caching, and Dynamic Services

For a domain that uses dynamic addresses or a distributed service, pinning a static address may disrupt its normal routing. A reachable address from one lookup isn’t necessarily suitable for long-term use in Host. After a service changes, the old address may stop serving the same content while the static mapping continues to override normal resolution. Without a clear maintenance reason, don’t pin the address of a public service just to save time on one lookup.

An app may keep its own resolution results or existing connections, and not every request follows the same resolution path. After changing Host, establish a new connection and check the actual target address. If the log still shows the old address, rule out caching and connection reuse before concluding that the wrong configuration is selected. Seeing the new mapping in the editor doesn’t prove the target app is using it, and different apps may behave differently.

After removing a mapping, normal resolution may still be affected temporarily by an old cache. To roll back, keep the original file, remove just the mapping, save and select the file again, then retest the same target. If the name resolves again but one address remains unreachable, the original issue was likely a stale static address. If resolution still fails, return to the DNS section and check the system source and network environment.

Each Host entry should have a clear purpose. You can add a separate comment such as “local test service” or “fixed internal address,” but don’t include account credentials. Review mappings when devices get new addresses, network ranges change, or services move. Fewer, more specific entries are easier to audit and less likely to affect unrelated requests.

URL Rewrite and USER-AGENT Boundaries

Rewriting a URL is different from choosing a route

URL Rewrite matches and rewrites visible request URLs; Rule chooses a policy based on request conditions. Redirecting one address to another doesn’t mean the request uses PROXY. The request to the new address is still handled according to the current routing settings. This distinction helps when a rewrite succeeds but the target still won’t open: check the new target’s domain rules, resolution, and connection status instead of only changing the regular expression.

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

This line demonstrates redirecting a matching HTTP address to an HTTPS address. The first field is a regular expression, the next is the target URL, and the last is the redirect status code. ^ anchors the match to the start of the string, while \. represents a literal dot. The slash after the domain helps define the host boundary. Without escaping, a dot in a regular expression can match other characters and include names you didn’t intend to handle.

Specify whether to preserve the path and query parameters

The short example above doesn’t specify that the original path and query parameters should be preserved, so don’t apply it as-is to requests that need them. If the target URL contains an API path, search parameters, or authentication details, redirecting to a fixed homepage changes the meaning of the request. Before writing a rewrite, list the input and expected output, then decide whether you need capture groups. Don’t copy a broad expression first and judge it only by whether the page happens to load.

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

This example uses a capture group and $1 to preserve the content after the slash. It’s still only a syntax example: the target service must support HTTPS, and the client must continue the request after the redirect. For encoded characters, query parameters, or multiple redirects, check the actual result to confirm that the new address is what you expect. A redirect isn’t an internal server path rewrite and doesn’t change the content the remote service provides.

A 302 and a permanent redirect have different caching behavior. A temporary redirect is easier to observe during testing, but browser and app caches can still affect results. If a later rule sends the new target back to the original address, you may create a loop. If the browser reports too many redirects, inspect the source and destination of each hop rather than changing only the last rule. Validate one understandable rewrite at a time.

HTTPS Visibility and Processing Limits

In a standard HTTPS request, the path and request headers are inside the encrypted connection. Don’t assume every field is available for rewriting just because the client carries the connection. Processing HTTPS content involves additional MITM settings, domain scope, and certificate trust, and may also be limited by an app’s certificate validation. The minimal snippets in this guide don’t include those settings and shouldn’t be taken to mean that any HTTPS app can be rewritten directly.

Even when content processing is available, limit it to domains you understand and need to test. Don’t expand the scope to all requests just to make one rule match. Don’t copy URLs containing login parameters, session details, or personal data into public notes. If you’re troubleshooting a connection failure, start with Rule, DNS, and the server; there’s usually no reason to begin with content rewriting. Keep routing troubleshooting separate from content modification.

USER-AGENT doesn’t identify arbitrary apps

USER-AGENT is a Rule type that matches visible HTTP request headers; it doesn’t identify every connection by app name. If the relevant header isn’t visible inside encrypted traffic, it can’t match. An app may also use a different identifier, multiple networking components, or no usable USER-AGENT value. Use this rule when you have a specific request sample, not as a general substitute for routing all traffic from an app.

[Rule]
USER-AGENT,ExampleClient*,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

ExampleClient is a teaching label, and the asterisk represents a wildcard in the match pattern. The first line matters only when an actual visible field matches that pattern; otherwise, the request continues to later rules. Placing it first means matching requests use DIRECT, even if they would also match the domain suffix rule. Confirm that this priority is what you want before arranging the rules.

When testing USER-AGENT or URL Rewrite, first confirm that the match target is visible, then that the expression matches, and finally that the result is correct. Record each step separately. If there’s no match, don’t immediately broaden the wildcard. The field may be hidden, the request may not have been sent again, or the configuration may not be selected. Establish a routing baseline with ordinary domain rules, then add content-related conditions one at a time for a test process you can roll back.

Configuration Verification, Troubleshooting, and Maintenance

Start with a repeatable baseline

Before troubleshooting, record the current network, Global Routing mode, selected configuration, current server, and test target. Don’t combine results from different Wi-Fi networks, targets, or servers into one comparison. If a subscription you already have was recently updated, first confirm that Home still has the intended server selected. Even without changes to the configuration text, different subscription contents or a different selection can change the result.

Connectivity Test can help assess the server test result, but a single successful test doesn’t prove every target is reachable or that Rule matches as expected. The test tool and target app may use different request paths. Use the test as baseline information, then check the domain, address, and policy with a new connection to the actual target. An enabled connection switch only indicates that the client is in a connected state; it doesn’t verify that the target request succeeded.

Trace the processing chain step by step

First confirm that the file is selected. Second, confirm that Global Routing is set to Config. Third, check whether General bypasses the target from the usual processing path. Fourth, verify the actual domain or IP being matched. Fifth, check the matched rule and policy. Finally, inspect the connection result for the selected route. This order avoids analyzing downstream rules before their prerequisites are met and helps distinguish a request that never entered matching from one that matched but failed to connect.

When checking logs, look for a new request at the same time as your test. An older entry may reflect the configuration from before your changes. Connection reuse may also prevent a new, complete matching process. Reconnect and reopen the target to reduce this interference. If the expected entry still doesn’t appear, check whether the target actually sent a request, connected directly by IP, or was affected by a skip setting. Don’t immediately add a duplicate rule.

Use a minimal rule set to test one hypothesis

If you suspect a domain rule has the wrong scope, copy a working configuration and keep only the necessary General settings, an exact rule for the target, and FINAL. Temporarily remove the relevant keyword rules, Host entries, and URL Rewrite entries. This minimal file is for testing one hypothesis, not for long-term use. If the exact rule matches consistently, restore suffix rules, address categories, and other exceptions one group at a time to find which layer changed the result.

[General]
dns-server = system

[Rule]
DOMAIN,api.example.com,PROXY
FINAL,DIRECT

The example still requires a server you already have and can use. If it also fails in Proxy mode, expanding Rule has no clear purpose; return to checking the server and network. If the minimal rules work but the full configuration doesn’t, compare early matches, static mappings, and DNS settings between the files. Restore one group at a time and note the first point where the results differ. This is usually faster than adding everything at once.

Protect sensitive information and preserve a rollback path

Before sharing troubleshooting materials, remove subscription URLs, authentication fields, personal domains, sensitive paths, and query parameters that could identify an account. You can keep rule types, target categories, policies, and error symptoms while replacing real targets with example domains. Screenshots and logs can also contain credentials, so check them too. You don’t need to share your subscription to get an explanation of basic rule syntax from this manual.

For long-term maintenance, keep a recent working local copy and note the purpose and test result of each change. After a remote configuration update, recheck the selected file, FINAL, General, and important exceptions—not just the file name. If rules are easy to add but hard to remove, review their purpose by group. Test removing broad rules with no clear purpose in a copy instead of layering new exceptions on top of old problems.

For basic setup, follow the Quick Start guide. Look up interface and rule terminology in the Glossary. If the connection is on but webpages fail, work through the server, mode, DNS, and rule troubleshooting checklist. For system authorization issues, see the VPN configuration prompt guide. Each resource addresses a different issue; you don’t need to repeat purchasing, importing, and configuration steps for the same problem.