Shadowrocket
Rules & Configuration Reference

Configuration Structure and What Makes It Take Effect

A Configuration File Is Not a Server List

A configuration file describes how the client handles requests; server details describe how to establish a connection. Check them separately. After importing a subscription, seeing entries in Home only confirms that server data has been added to the client—it does not mean a particular rules file is active. Likewise, saving a configuration successfully does not mean its PROXY policy has a working connection. Keep these two objects separate when troubleshooting; replacing rules will not fix a problem with server credentials.

In Config, confirm which configuration is selected, then check whether Global Routing is set to Config. This mode handles traffic according to the active configuration and is required to interpret the Rule examples on this page. Switching to Proxy or Direct changes how requests are handled, so the same rule-match expectations no longer apply. A file name is only an identifier; matching names do not guarantee matching contents. When several files are present, confirm both the selected file and the text actually saved in it.

Use Section Names to Identify Each Section's Role

Section names in square brackets determine how the following lines are interpreted. General typically uses key-value pairs, Rule uses comma-separated rule fields, and Host maps hostnames to addresses. Pasting domain rules under Host or general settings under Rule will not produce the intended result, even if the text looks complete. Locate the section name before editing; this is more reliable than searching for a keyword alone.

[General]
dns-server = system

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

[Host]
router.example.com = 192.168.1.1

The file above contains three sections with different roles. A domain-suffix rule selects a connection policy, while a Host entry specifies the resolution address for a hostname; they do not override each other in the same way. The example uses DIRECT as a fallback to make the matching scope easy to see, not because it is the right default for every situation. Before changing the fallback, decide how unmatched requests should be handled and confirm the chosen connection works. Do not infer a file's purpose from its name.

Use an Editing Workflow You Can Roll Back

Before making changes, export or keep a copy of the current configuration, and give test files descriptive names. Open a copy and change just one section or one closely related group of rules at a time. After saving, confirm the selected item in Config again; saving a different file does not automatically make it the active configuration. Record the purpose of each change. Keep it if it works; otherwise, return to the verified copy instead of layering on more uncertain fields.

Punctuation in configuration text is part of the syntax. Rules use English commas, key-value settings use English equals signs, and address ranges use slashes. When copying from rich text, check for non-English punctuation, invisible spaces, or fields split by line breaks. A long rule may wrap visually in the editor without actually containing a line break; check the real file lines. Comments can explain a rule's purpose, but they cannot replace policy fields. Do not put connection passwords in comments.

Remote configuration updates can also overwrite manual edits. If you edit a file that is updated from a remote source, a later update may change its local contents. Confirm the file's source and how in-app updates work before deciding whether to maintain your rules in a local copy. Subscription updates generally apply to server data, while configuration updates apply to configuration text; the fact that both use addresses does not make them the same operation. For saving and migration, see configuration backup and device migration notes.

General Settings and DNS Resolution Boundaries

Keep General Settings Separate from Rule Selection

General describes shared configuration behavior; it does not work like Rule's line-by-line matching. These settings can affect DNS resolution, address handling, and the connection environment, but they are not another routing list. When checking an unfamiliar field, verify that the app supports it using the relevant in-app configuration editor or setting guidance before deciding whether its value is valid. A key appearing in another text file does not mean the current app recognizes it. Do not add a field with an unclear purpose to an active configuration.

DNS resolves hostnames to addresses; Rule selects a policy based on request information. Successful resolution does not mean a proxy connection will work, and choosing the right policy does not guarantee a correct resolution result. For example, if a domain rule matches PROXY but the server connection fails, the issue may still be in the connection settings. If a request uses DIRECT but resolves to an unreachable address, check the resolution source and destination service. Testing these steps separately helps narrow down what to change.

Start with a Simple DNS Baseline

[General]
dns-server = system

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

dns-server = system uses system DNS as the resolution source for this setting. The example provides an easy-to-roll-back baseline; it does not guarantee the same result on every network. With system resolution, the current network's DNS configuration affects the result. Switching networks may change both the resolved address and whether it is reachable. When comparing tests, record whether the network environment was the same, or you may mistake a network difference for the effect of a rule change.

Before changing DNS servers, confirm your network requirements and the value format accepted by the current app, then change one setting at a time. Do not change the resolution source, add Host mappings, and reorder rules all at once; it will be hard to tell what caused the result. A DNS server address and a proxy server address are different fields. Putting an existing subscription address in DNS settings will not import a server. After changing the setting, make a new request and check the logs to see whether the resolved address is expected.

Domains, Addresses, and no-resolve

Domain rules can match when the request hostname is available; address rules require destination address information. For a request that has a hostname but no address yet, some address matches may require resolution, so rule order can affect whether an additional lookup occurs. When troubleshooting slow resolution, do not check DNS settings alone. Also check whether an earlier address rule triggers resolution to determine a match, and whether a domain rule that could have matched first was placed too far down the list.

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

no-resolve is an optional modifier for address rules that prevents the rule from initiating a lookup solely for its match. It does not disable DNS for the entire configuration, nor does it mean the request will not need resolution later to connect. If the client already has the destination address, it can still check that address against the rule. If no address is available, do not expect this rule to resolve the hostname and match it to a range. Do not append it to every rule; it does not change the meaning of domain rules or FINAL.

Differences Caused by Address Families and Caching

A hostname can resolve to multiple addresses, including addresses from different families. An IPv4 range rule does not automatically cover an IPv6 destination; adding an IPv6 address rule does not guarantee that the network can reach it either. Check the actual destination address before deciding whether a rule covers it. Disabling an address family to fix one failed request may hide an issue with the destination network or connection settings. Check the relevant switches against the in-app guidance.

After changing resolution settings, existing connections, app caches, and system caches may still affect what you see. Refreshing a page does not always create a new connection, and existing connections do not necessarily run through the full matching process again just because the text changed. Close or end the relevant request, then make a new, identifiable request; if needed, use the in-app control to refresh resolution state. Recording the hostname, resolved address, matched policy, and connection result is more useful for comparison than noting only whether a page loads.

DOMAIN Rule Types: Scope and Syntax

Exact Match vs. Suffix Match

DOMAIN matches an exact hostname, while DOMAIN-SUFFIX matches the specified domain and its subdomains. Their main difference is scope, not inherent priority. Use an exact match to limit a rule to one host; use a suffix match to cover a domain tree more easily. List the hosts you want to include and exclude before choosing a type. This helps avoid broadening the routing scope just because one form is shorter to write.

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

This example sends api.example.com through PROXY and uses DIRECT for other hosts under example.com. The exception must come before the broader rule because that host also matches the suffix. If you swap the first two lines, the suffix rule matches first and the exact rule below it no longer determines the outcome for that request. An exact-match rule does not automatically outrank earlier rules. Its position in the file determines when it is checked.

The domain field should contain a hostname, not a scheme, path, query parameter, or port. A page path in a URL is not part of a DOMAIN match value, so pasting a full page URL usually will not match the hostname as intended. To change the destination based on a path, check URL Rewrite rather than adding a slash to a domain rule. After editing, check the three parts separately: rule type, match value, and policy.

Keep Keyword Matches Narrow

DOMAIN-KEYWORD checks for a keyword in the hostname, so its scope is usually less obvious than a suffix rule's. The same string can appear in unrelated hostnames, so this type is not a good substitute for a clear domain ownership boundary. A keyword is not a regular expression: entering dots, asterisks, or parentheses as if they were regex syntax will not make them work as regex patterns. When you have a clear list of domains, prefer conditions that precisely describe the intended scope.

[Rule]
DOMAIN,keep.example.com,DIRECT
DOMAIN,ads.example.com,REJECT
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECT

The first two lines in this example keep a DIRECT exception and reject one exact hostname before the keyword rule handles other matching domains. ads.example.com is only a syntax example; it does not represent any real content category. Rejecting a host may also affect resources a page depends on, so confirm its purpose first. If a page goes blank after a request is rejected, use the request logs to find its dependencies instead of immediately adding a broader allow rule.

Subdomains, Aliases, and Request Visibility

A page may make requests to several hosts for APIs, images, authentication, and static resources. A rule for the hostname in the browser's address bar will not automatically apply the same policy to those other hosts. If some content fails to load, list the hosts used by the failed requests and check whether each falls within the active suffix rule. Do not group unrelated domains into one domain-rule scope just because they resolve to the same address.

Distinguish aliases and resolution chains from the hostname in the original request. A DNS result pointing to another name does not mean all matching will necessarily use that name; rely on the information shown for the current request. When a destination is accessed by address, the client may not have enough hostname information for DOMAIN rules to match, so check address rules and the fallback. Do not infer the request hostname from a page title or app name alone.

When validating a suffix rule, test at least the root domain, one subdomain, and one hostname outside the rule's scope. Then make a separate request for any earlier exception and confirm that the log shows a different policy. If you add an exact rule for a temporary test, note why and decide whether to keep or remove it afterward. As exceptions accumulate, periodically merge duplicates and remove outdated hosts; this is easier to maintain and roll back than adding rules to the top of the file indefinitely.

Address Rules and USER-AGENT Conditions

IP-CIDR and Address Ranges

IP-CIDR describes an IPv4 address range. The number after the slash is the prefix length, not a port or a count of addresses to match. A longer prefix means a smaller range. Before checking a rule, determine which network the destination belongs to instead of comparing only the first few characters. When ranges overlap, policy selection still follows rule order, so an exception for a smaller range must come before the larger range that contains it.

[Rule]
IP-CIDR,192.168.1.10/32,REJECT,no-resolve
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
FINAL,PROXY

The first line in the example matches a single IPv4 address; the next two match common private address ranges. The first line comes before the larger ranges, so that address is rejected first. If it were placed below them, an existing DIRECT rule would take effect instead. A private address does not identify the same device on every network; the same address may point to a different host after switching networks. Consider the current LAN and your own connection environment when using these ranges.

IP-CIDR6 is for IPv6 address ranges; IPv4 syntax is not a substitute. The example range is not a one-to-one counterpart to private IPv4 ranges; it simply shows that the two address families must be expressed separately. A service may have both kinds of address, and the rule that matches depends on the actual destination. During troubleshooting, record the full address. Do not overlook the address family actually used just because the interface shows a hostname.

GEOIP Is Not Domain Categorization

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

GEOIP matches using geographic information from an address database; a domain suffix, page language, or website name cannot replace that check. If a domain uses different delivery addresses, the match may vary with the actual address. GEOIP is suited to address-based classification, not to guaranteeing that an entire service will always use one policy. If you have a specific requirement for a domain, put a domain rule before the geographic rule to express the exception explicitly.

An address database may not reflect a service's actual deployment, and a geographic match does not identify where the service operator is based. When a result differs from expectations, check the destination address and request logs before adding an exact domain rule. Changing the policy for all geographic matches to fix one domain usually broadens the impact. If the request needs resolution to obtain an address, also consider the DNS and no-resolve boundaries covered in the previous section.

When to Use USER-AGENT

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

USER-AGENT matches available request-header information. ExampleClient* is a sample pattern illustrating wildcard syntax, not a real app identifier. This condition does not match by app name or select policies by device process. It can only be evaluated when the relevant request information is visible. Do not assume that every app connection includes the same header, or treat this as a reliable way to classify all traffic from one app.

Headers inside encrypted requests are not automatically visible. Do not add certificates or change HTTPS handling settings just to make a USER-AGENT rule match; those steps involve separate trust and access boundaries and require a clear purpose and authorization. For ordinary domain-based routing, start with DOMAIN rules. Seeing a request header in one test does not prove that background connections, other APIs, or later requests will expose the same information.

When combining rules, put explicit host exceptions first, followed by address ranges and geographic conditions as needed. If you use a header condition, verify its visibility and matching scope separately. When a rule fails to match, distinguish among three cases: the field is missing, the field is present but its value differs, or an earlier rule already matched. Each calls for a different fix; changing a wildcard will not solve all three. Document the information each rule depends on to avoid repeating the same guesswork later.

Policies, Global Routing, and Rule Order

Check the Mode Before the Policy

Global Routing determines the overall handling mode in use. Config routes according to the configuration, Proxy uses proxy mode, and Direct uses direct mode; the exact behavior also depends on the app's current settings and the type of request. You can explain the Rule examples in this section only after confirming that Config is active. Switching modes can help isolate an issue, but it does not fix a rule. When testing is done, restore the intended mode explicitly.

Proxy in the interface and PROXY in a rule are at different levels. Similar names do not make them interchangeable: the former selects an overall mode, while the latter is a policy applied when a rule matches. DIRECT bypasses the selected proxy to connect to the destination, but the destination and local network must still be reachable. REJECT explicitly denies a request; it is not an automatic fallback after a connection failure. A rejected request does not continue down the list looking for an allow rule.

First Match Wins; Put Exceptions First

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

This example checks rules from top to bottom. The API host uses PROXY, the specified host is rejected, and other hosts in the domain tree use DIRECT. An address condition later in the list can decide the policy only if earlier domain conditions have not already done so. Rule types are not automatically sorted, and there is no implicit priority that makes the most specific rule always win. Position in the text is a key part of priority. When adding an exception, check every rule that could match earlier, not just the line directly above it.

The commonly used order of “domains first, addresses as fallback” is arranged by the configuration maintainer; it is not automatic behavior. Putting address rules earlier may decide requests that you intended to handle by domain, and may also affect resolution. The outcome depends on the available request information and the specific conditions. When reading an unfamiliar file, follow its actual order instead of inferring priority from grouping comments. A comment may label a line as an exception, but if the line comes after a broader rule, it still may not take effect.

Where to Put FINAL and What It Means

FINAL is a fallback rule with no additional match value. Common forms include FINAL,PROXY and FINAL,DIRECT. Put it at the end of the rule list so explicit conditions can be evaluated first. Placing FINAL in the middle prevents later rules from getting their expected chance to match. Adding multiple FINAL rules does not create a rotating fallback chain. Before choosing a default policy, decide how requests not listed in the file should be handled.

If a PROXY match fails to connect, the client does not automatically fall back to DIRECT or continue to the next Rule. The rule selects a policy; connection success is a separate step. Only a separately configured mechanism can change what happens afterward. To check whether a proxy works, test your own connection separately and verify its authentication and transport settings. Hiding a proxy failure behind a broad DIRECT rule makes a successful page load meaningless as a test of the proxy.

Organize Rule Order by Purpose

A useful order is exact exceptions, domain scopes, LAN addresses, other address classifications, then FINAL, with each group labeled by purpose. This is not a fixed template; the key is being able to explain why each exception is where it is. When you find duplicate rules, check not only whether the hostnames look identical, but also whether their policies differ or an override is intentional. An exact exception before a broad rule can be useful; a duplicate line with the same scope and policy after it usually adds maintenance work without changing the result.

When comparing Config and Proxy test results, record both the matched rule and the selected connection. If Proxy connects but Config fails, first check conditions that route the request to DIRECT or REJECT. If both fail, check the connection and network. A successful Direct test does not prove that proxy settings are correct. For more on the modes, see notes on the three Global Routing modes. When making changes, rely on what the app actually records.

Host Mappings and LAN Boundaries

Maps an Address; Does Not Select a Policy

Host maps a specified hostname to an address. It answers “which address does this name resolve to?”, not “which connection should handle this request?” After adding a mapping, you still need to check the applicable rules and current mode. A hostname mapped to a LAN address does not guarantee a direct connection; an earlier domain rule may still select PROXY. When reading a configuration, check Host and Rule together while keeping their roles distinct.

[Host]
router.example.com = 192.168.1.1
service.example.com = 192.168.1.20

[Rule]
DOMAIN,router.example.com,DIRECT
DOMAIN,service.example.com,DIRECT
FINAL,PROXY

The example assigns addresses to two hosts and uses exact domain rules to specify an intention to connect directly. It applies only to devices you are authorized to access that are actually present on the current network. These example addresses are not public entry points that work on every network; copying them will not provide a service if your LAN uses a different range. Before adding a mapping, confirm the target device's address, port, and service are working, then use the hostname as an easier-to-recognize name for access.

Handle Hostnames, Ports, and Paths Separately

Put a hostname on the left side of a Host entry and its corresponding address on the right. Do not include a page path, scheme prefix, or port. A mapping does not change the port requested by an app or turn a regular web request into another protocol. If the target service listens on a specific port, the client still needs to use the correct access method. If the mapping works but the service is unreachable, check the connection target and service status instead of appending a path to the Host value.

Host is not a suffix rule. Do not assume a mapping for one specific host will also apply to all its subdomains. If you need to map multiple hosts, verify the supported syntax and target for each, starting with explicit hostnames you can test. Most routing tasks do not need Host. To route a domain through a proxy, use Rule to select the policy and leave normal resolution in place; hard-coding an address adds maintenance without a routing benefit.

HTTPS Hostname Checks Still Apply

Mapping a hostname to an address does not change the hostname in the request or make the target certificate valid for that name. An HTTPS connection may still check the certificate name and trust chain, and the target service may select a site based on the hostname. If a certificate error occurs after mapping, check whether the service actually supports that hostname; disabling verification is not a routine fix. Address reachability, hostname mapping, and certificate validity are separate requirements.

For a service you manage, configure the hostname and certificate correctly on the server, then test on the current network. For a service you do not manage, pinning an arbitrary address may send requests to the wrong endpoint or keep failing after the address changes. Distributed services often return different addresses through DNS; keeping an address observed once may interfere with normal routing. If there is no clear need for a mapping, remove the test entry and restore normal resolution.

Maintaining and Rolling Back Mappings After a Network Change

Network changes are the most common limitation of LAN mappings. The same private address may not exist on another network or may belong to a different device. After leaving the original network, a mapping will not automatically change to a public address just because it is no longer relevant. After a successful test, note which network and service it applies to and consider whether to disable the configuration on other networks. One successful test does not prove that the mapping works on cellular data or another LAN.

When troubleshooting, confirm the current network first. Then test whether the target address is reachable and check whether a request to the mapped hostname uses the expected address and policy. If the address itself fails, investigate the network or target service first. If the address works but the hostname fails, check the name, certificate, and how the app makes the request. If both work but the policy is wrong, check earlier Rule entries. Testing in layers avoids repeatedly changing Host addresses while missing the rule that actually controls the result.

After deleting or changing a mapping, make a new request; existing connections and resolution caches may still contain the old result. In a maintained copy, document the purpose and rollback method for each mapping, but do not record device credentials. If a mapping was added only for diagnosis, remove it from the active configuration when testing is done. If you keep it long term, periodically confirm that the target address has not changed. Clearly limited use makes it easier to decide later whether each entry is still needed.

URL Rewrite Syntax and Scope

Rewrites URLs; Does Not Route Domains

URL Rewrite uses regular expressions to identify request URLs and apply the configured change. Its purpose differs from Rule: Rule selects a handling policy, while a rewrite changes the behavior of matching URLs. To route a host through DIRECT or PROXY, do not add a rewrite section. Add one only when you explicitly need to send one URL to another and understand how the app handles that kind of request.

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

This example matches an HTTP URL for a specified host and uses captured content to build an HTTPS target. The final 302 is the redirect status code. The match, target, and status code are separated by spaces; this syntax does not use Rule's comma format. The example explains the structure only. It does not mean that the domain provides the stated service, and it is not a general-purpose rewrite for arbitrary sites. Any real configuration must target an object you are authorized to access and can verify.

Anchors, Escaping, and Capture Groups

The leading ^ anchors a regex to the start of the URL, and the trailing $ anchors it to the end. Escape dots in a hostname with a backslash so they are not treated as wildcard characters. Parentheses create a capture group, and $1 in the target refers to the first group. Check what each symbol does rather than copying the whole expression as if it were a fixed string. A missing escape or anchor can broaden the match beyond its intended scope.

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

The second example handles only paths under the specified host that begin with /old/; other paths do not match. Captured content is used to build the target, so check exactly what the input contains. Query parameters, encoded characters, and trailing slashes can all affect the match. One short test URL is not enough to conclude that every request will work. If the target has an extra slash, loses parameters, or becomes invalid, adjust the expression rather than changing the proxy policy.

A Redirect Creates a New Request

A redirect response generally causes the client to request the target URL, and that new request may use a different host, scheme, or path. Recheck its policy and service behavior. The original request using DIRECT does not guarantee that the new target will also use DIRECT. If the target host changes, check the rules matched by both requests separately. Seeing multiple requests in the debug log is not necessarily an error; the important question is whether they form the expected, finite redirect sequence.

Avoid rewriting a target to a URL that matches the same condition again, which can create a redirect loop. At minimum, list the original URL, the rewritten target, and whether the target still matches. A broad regex near the top may also catch requests intended for more specific conditions below it, so put narrow exceptions first and follow with general rules you have tested. When a regex becomes too complex, splitting it into a few explainable conditions is usually easier to troubleshoot than adding more nesting.

HTTPS Visibility and Access Boundaries

Ordinary connection forwarding cannot directly read the full path and headers inside an encrypted request, so do not assume that a rewrite rule for an HTTPS path will automatically be visible. Handling HTTPS content requires separate understanding of relevant in-app settings, certificate trust, and target scope; the simple examples on this page do not require enabling those capabilities. Adding content-handling settings to fix an ordinary connection problem expands the issue from rule routing to trust and compatibility. Avoid mixing those troubleshooting steps.

Even when you manage the target service, handle only the specific hosts and paths that need rewriting, and keep the original configuration as a rollback baseline. Rewrites may affect authentication redirects, cross-host requests, form submissions, and server-side URL validation. First verify the URL change with a simple read request, then check the actual workflow; one successful page load is not complete validation. For URLs containing sensitive parameters, keep only the necessary redacted structure in test notes and do not export complete request data.

For each rewrite, record its purpose, match scope, and rollback method. If it stops working, disable that line first and check whether the original URL works before deciding whether the issue is a service change or an expression error. Changing Rule and rewrites together makes it difficult to tell which layer affected the result, so test them in separate rounds. If you only need domain routing, use domain rules instead. Configurations with no rewrite requirement can omit the section entirely; there is no need to add an empty section just for completeness.

Configuration Validation, Layered Troubleshooting, and Rollback

Build a Test Configuration You Can Explain

Start validation from a known working state, not a complex file that has accumulated fields. First confirm that your own server can establish a basic connection. Then keep only the necessary general settings, a few explicit rules, and one FINAL in a copy. Temporarily remove Host and rewrite rules that are unrelated to the test; this does not mean they are wrong, only that you are reducing variables. Once the baseline is stable, restore rules one group at a time and repeat the same test after each group.

[General]
dns-server = system

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

This example tests four outcomes: an exact proxy exception, an explicit rejection, a suffix rule using DIRECT, and a default proxy. It is still only a syntax sample. For real validation, use targets you are authorized to access and whose status you know; do not judge whether the client works by whether an example domain serves a webpage. Give each test target one purpose and avoid depending on several unknown interfaces at once. This makes it easier to identify the condition responsible for a difference rather than blaming the entire file.

Saving Does Not Mean You Have Retested

After saving, confirm the active Config, Global Routing mode, and current connection, then end existing test requests and make new ones. Long-lived connections may continue along their previous path, and app caches may display old content. A page that looks unchanged does not immediately prove that a new rule failed. When checking in-app connection details or logs, verify the request hostname, destination address, matching condition, and actual outcome. Make sure the record was generated after the change.

Separate syntax, matching, and connection failures

Syntax problems may prevent a configuration from loading, cause a line to be ignored, or leave a setting unrecognized. Check English punctuation, section placement, extra fields, and actual line breaks. Then remove the most recently added content from a copy and compare. A matching problem means the request used a different policy; scan from the top for the first rule that meets its conditions. If the request lacks a hostname or address, consider insufficient matching information as a separate cause instead of assuming the field is misspelled.

When the policy is correct but the connection fails, check the server, resolution, destination service, and local network. Connectivity Test can help show connection status, but one test does not validate every protocol or application request. Check your own server details against the information you have, including address, port, authentication, and transport settings. A latency result does not prove that every destination is reachable, and one failed destination is not a reason to change the default policy for the whole configuration.

Identify failures caused by rejection separately. When REJECT matches, the destination is inaccessible by design; that is not a proxy connection quality issue. If rejection blocks something it should not, narrow the match or adjust earlier exceptions, then test the page's dependencies again. DOMAIN-KEYWORD rules especially need checks for unintended matches. Prefer changing the rule to target an explicit hostname rather than countering an overly broad rejection with an allow rule for an entire domain tree.

Rollback and Change Notes

For each change, record three things: what happened before, which lines changed, and which requests verified the result. Notes should make it possible to reproduce the test without storing real subscription URLs, authentication details, or complete request logs. Before exporting a configuration, check whether it contains your sensitive data. If sharing a troubleshooting snippet, include only the relevant section and redacted request conditions. Keep obvious example values separate from real credentials.

After updating a remote configuration or subscription, first check which objects changed, then reuse the original test checklist. Changes to server data may affect PROXY connections; changes to rules may affect matching. Do not combine both updates into one conclusion. If the new state does not work, switch back to a verified local copy and confirm it is selected; leaving the old file in the list is not a rollback. Once restored, isolate the differences one at a time instead of accumulating temporary fixes in the broken file.

This page explains how configuration works. For your first import, connecting, and basic validation, return to the quick-start guide. For brief definitions of field names, see the glossary. For purchases, restoring a purchase to the original account, or App Store compatibility, see purchase restoration instructions; these are not handled by editing the configuration. Keeping a problem at the right layer and testing with the smallest possible change helps maintain a configuration that remains easy to read.