Shadowrocket Settings Guide

1. How Settings, Config, and Connection State Differ

Before changing anything, identify which layer is involved. App preferences in Settings, the selected configuration file in Config, and the selected server and connection switch in Home are separate states. The server determines the destination and protocol parameters; the configuration file determines rules and related handling; Global Routing determines the current routing mode. Changing one setting does not automatically change the others. Keep track of each separately while troubleshooting.

The three Global Routing modes

For everyday rule-based traffic handling, use Config and check which file is selected on the Config screen. Proxy is useful for temporarily checking the proxy route; Direct is useful for comparison with a direct connection. Neither fixes an incorrect configuration. If a webpage opens after switching to Proxy, that does not prove DNS and all rules are correct. It only shows that the selected proxy route worked for that request under those test conditions.

Default, current, and recommended values

A default is the initial state before the relevant setting has been changed. The current value may have been altered by the user, an imported configuration, or a restore. An enabled switch confirms only that it is enabled now; it does not show what the original state was. As a baseline, leave unfamiliar options unchanged. Change a setting only when you can describe the problem and know how to verify the result. Use the service details you already have for server protocol fields; do not replace them with supposedly universal values.

You do not need to erase data to establish a baseline. Record Global Routing, the current Config filename, the selected server, and relevant switches. Keep a local copy before editing a configuration. Then choose a stable destination you can access repeatedly and note the results on the current network. Change just one factor per test—for example, DNS, the selected server, or On Demand—so you can identify what caused any difference.

How configuration settings factor into troubleshooting

A configuration file can contain global parameters, rules, and local mappings. The snippets below illustrate the structure; they are not instructions to overwrite your existing file. Example domains are for demonstration only. Make sure PROXY refers to an available proxy policy in your current setup; preserve valid policy names used by your existing file. After importing, confirm that the file is selected and check request records to see which rules matched. A successful save alone is not enough.

[General]
dns-server = system

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

[Host]
localhost = 127.0.0.1

Verify three things after a change: whether the target request succeeds, whether it uses the expected policy, and whether other commonly used destinations still work. If it fails, revert the one change and compare the result. If the issue persists after reverting, check whether the network changed, a subscription was updated, or the server changed during testing. For configuration section details, see Configuration File Structure Explained. For the initial import steps, use the setup guide.

2. DNS: Resolution Sources, Configuration Overrides, and Caching

DNS resolves domain names to addresses that can be reached, but successful resolution does not guarantee a successful connection. A webpage may fail during name resolution, connection to the proxy server, connection to the destination, or subsequent encrypted communication. Before changing DNS, identify where the failure occurs: check whether the records show a resolution error, whether a destination address was returned, and whether the server is available. A browser's generic connection error is not enough to conclude that the resolver is at fault.

What dns-server and system mean

In a configuration file, dns-server = system means to use the DNS resolution source provided by the system. This is a useful baseline for comparison with the current network, not a claim about the factory default on every device. System DNS conditions can change with the network, so the same configuration may behave differently on Wi-Fi and cellular. If an existing configuration specifies another resolver, find out why before reverting it.

If you need to specify a resolver, use an address and format you can verify and that meet the requirements of your current network. Standard DNS and encrypted DNS have different connection requirements; encrypted DNS also depends on the service hostname, certificates, and network access to the resolver. Entering an address does not guarantee that the method will work. After saving, check that the app accepts the format, then verify it with a new request. Do not enter a DNS address as a proxy server address.

Check the configuration and Host entries before changing resolvers

If only one domain has a problem, first check whether the current configuration's [Host] section contains a mapping for it. An explicit mapping may keep requests using a fixed address, so changing the resolver may not affect the result. Then check whether a rule routes the domain through an unexpected policy. Rule matching and DNS queries are separate processes. A failed request through a proxy does not prove that the domain resolved to the wrong address.

Caching can make the first check after a change hard to interpret. The system, app, and destination site's connections may all retain existing state; connections already established may not resolve again after you change the resolver. Close the page under test and make a new request. If needed, use the app's available cache-clearing option, then reconnect. Do not make clearing all website data a routine step, as it may remove login states unrelated to troubleshooting.

IPv6, network access, and the limits of DNS troubleshooting

Some destinations have both IPv4 and IPv6 addresses, while the current network may not provide equal reachability for both. Consider testing the relevant setting individually only when records show successful resolution but connections through a particular address family consistently fail. Disabling related functionality may temporarily change what you observe without fixing the underlying cause. Record the original state and check whether other services that rely on that address family are affected.

A recommended troubleshooting order is: confirm the current Config file, check dns-server and Host entries, review the records, then change one DNS condition for comparison. Keep the server and Global Routing mode unchanged during testing. If the issue occurs only on one network, first record that network's system DNS and authentication state. If it persists after switching networks, inspect the configuration itself. Revert any change that did not help so temporary tests do not remain in the configuration.

3. On Demand: Automatic Connection Triggers and Stop Conditions

On Demand starts a connection when configured conditions are met. It does not select the right rules or fill in server details. Before enabling it, verify that a manual connection works: an existing server can connect, the current Config file works, and system VPN authorization is complete. If a manual connection fails, troubleshoot the server, DNS, or rules first; automatic triggers will otherwise encounter the same problem repeatedly.

When to enable it

Configure On Demand when your use case has clear conditions, such as automatically connecting on a specific network. For initial setup, leave it disabled until you have verified a manual connection, then enable it separately. This is a troubleshooting baseline, not a claim about a universal app default. If it is already enabled, record the current rules and conditions before changing anything; they may include exceptions you need for specific networks.

Find On Demand in Settings and review the conditions actually shown in the current interface. Conditions may interact or depend on their order, so check each rule's action and scope. If you use a network name as a condition, remember that a name is only a matching value, not proof that the network is trusted. Multiple access points can share a name, and a name change can make an existing condition stop matching.

System VPN authorization versus the app switch

When first establishing a connection, the system may ask to add a VPN configuration. This authorization allows the system to establish the connection; it does not import a server or complete every app setting. If authorization is interrupted, return to the app and check the connection state, then follow the system prompts. Do not repeatedly create configurations in the hope that one will work. First confirm that the existing configuration belongs to the app, then check for management policies or other connection configurations that may affect it.

With On Demand enabled, manually disconnecting and stopping automatic triggers are two different actions. After you turn off the connection, new network activity may meet a condition and cause the system to reconnect, making it seem as if the switch turned itself back on. If this happens, temporarily disable On Demand and disconnect again to compare. If the connection no longer restarts, check the trigger conditions rather than assuming the app is malfunctioning.

How to run a complete trigger test

Test three stages: meeting the trigger condition, maintaining the connection, and leaving the condition. First record the network and current connection state. Enable On Demand, switch networks as required by the condition, and make a normal request. Check the system connection state and app records to confirm that the expected condition triggered the connection. Then leave that condition and verify the resulting behavior; do not stop after confirming that the initial trigger worked.

Test public Wi-Fi that requires sign-in separately. Before authentication is complete, DNS resolution and server connections may be restricted; automatic connection cannot replace network sign-in. If the sign-in page does not appear, you can temporarily disable automatic triggering if you understand the change, complete network authentication, and then restore the original settings. Do not compare failures during sign-in with results after normal network access is available.

On managed devices, system policies may restrict some VPN behavior, and personal-device instructions cannot override those restrictions. To restore the previous state, disable On Demand first, restore the original conditions and connection selection, then verify a manual connection. For questions such as “reconnects after disconnecting” or “triggers only on one network,” see the FAQ and include the network conditions at the time; a description of the switch alone is not enough.

4. Ping and Connectivity Test: Understanding Test Results

Ping and Connectivity Test help assess connection conditions; they are not a complete measure of real-world service quality. A successful test shows that the test method completed the relevant interaction at that moment. Websites, video, and other requests may still fail because of differences in DNS, rules, destination services, or protocol requirements. Before testing, check the method, destination, and timeout so you do not compare numbers that measure different things.

The test method determines what the result means

Find the Ping-related settings in Settings and review the test method currently selected. If a TCP-based test is available, it mainly indicates whether a connection to the destination port can be made. An HTTP-based test through a proxy also depends on proxy negotiation, the test URL, and the response. These methods measure different stages. Even if they use the same units, a smaller number does not necessarily mean better performance for every kind of access.

Use the current app display as the reference for the default test method, test address, and timeout; this guide does not prescribe a fixed number. Start with the existing settings to establish a repeatable baseline. Change them only if the test destination is unreachable or the method does not suit your troubleshooting goal. Before using a custom test address, confirm it is stable and that you are authorized to access it. Avoid pages that require sign-in, redirect frequently, or restrict automated requests as general connectivity targets.

A timeout does not mean every request has failed

A timeout means the test did not finish within the specified period; by itself, it does not prove the server is completely unavailable. Possible causes include an unreachable port, mismatched protocol parameters, a restricted test destination, or a network change during the test. Conversely, a quick response does not prove that large transfers will be stable. If a test times out, repeat it under the same conditions, then verify with a normal request and record the results separately.

How to compare existing servers

Keep the network, test method, destination, and other settings the same when comparing. Wait for the network connection to stabilize, then run a small number of repeat tests on servers you already have. Look for consistent results rather than selecting an occasional lowest value. Tests generate network requests; there is no need to run them continuously to rank servers, and a one-time order is not a long-term reliability ranking.

Incorrect protocol fields can also make an address reachable but unusable. A successful port connection only shows that the port responded; it does not verify authentication details, encryption method, server name, or other parameters. Go back to Add Server and check the service details you already have, paying particular attention to spaces, ports, and field placement when copying. Do not disable certificate verification or change protocol security settings just to make a test pass.

Relate test results to real-world access

After Connectivity Test, explicitly select the server you want to verify, then check Global Routing and the current Config file. A successful entry in the test list does not mean the active connection has switched to it. A change in list order does not confirm a successful switch either. Make a repeatable request and check the records to confirm the route actually used. Only then can you relate the test result to real-world access.

If the connection switch is on but sites are inaccessible, check the network, server, mode, DNS, and rules in that order; this is more useful than testing every entry repeatedly. For a detailed workflow, see the Connected but No Internet Troubleshooting Checklist. When describing the issue, include the test method and stage of failure rather than only a timeout screenshot. This helps distinguish a problem with the test destination from a server issue.

5. Log and Data: Request Records, Usage Statistics, and Privacy

Log helps reconstruct what happened; Data shows changes within the app's statistics. They serve different purposes. An enabled connection switch shows only that a connection was attempted; it does not prove that every request was handled as expected. When troubleshooting, start with one reproducible request and connect its time, destination domain, matched policy, and error message. Do not browse large amounts of history at once looking for lines that merely seem relevant.

Choosing a log detail level

Check the Log-related options in Settings and the current logging level. If the interface offers different levels of detail, use one that is sufficient for routine checks and increase detail temporarily when investigating a specific issue. The selected option is the actual state on that device; this guide does not designate a fixed default level. Detailed logs may increase storage and processing load. Restore the original setting after troubleshooting and clear records as needed.

Before reproducing the issue, note the time. If needed, clear old records that are unrelated to this investigation, then access just one destination. Check the sequence: did resolution occur, was an address returned, was a policy selected, did a connection start, and where did it fail? Adjacent log entries may belong to concurrent requests. Do not assume they are part of the same connection just because they appear next to each other; use the destination, timestamps, and any correlation details shown by the app.

Check whether settings took effect by reviewing rule matches

If you expect a domain to use PROXY but the records show DIRECT, first check whether Global Routing is set to Config, then review the rule order and current file. The snippet below means “proxy the specified domain and connect directly to everything else.” Rules are evaluated in order, with FINAL at the end. This example illustrates matching logic; it is not a replacement for your existing configuration. After editing, make a new request; existing connections may not be matched again immediately.

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

If an earlier, broader rule already matches the destination, a later rule does not automatically take priority just because it is more specific. Check the full list, not only the two new lines. DOMAIN, DOMAIN-SUFFIX, and IP-CIDR match different kinds of values, and an address returned by DNS is not the same as the original domain. For the basics, see Rule Keywords and Matching Order.

Why Data values are not a bill

When viewing Data, first check whether the interface shows the current session, an individual entry, or a cumulative total, and whether it has ever been reset. App statistics and service-provider billing may use different periods and measurement methods. Protocol overhead, measurement boundaries, and time ranges may also differ. A discrepancy does not automatically indicate a problem. Align the periods first, then review the usage calculation details provided by your existing service.

Small changes in Data after connecting may come from normal connection maintenance, DNS resolution, or requests from other apps. A rising count alone does not prove that a particular destination is continually transferring data. Use request records to help identify the source. Before resetting statistics, record the current value and time. A reset establishes a new point of reference; it does not change usage already recorded by a service or fix a connection problem.

Before exporting or sharing

Logs may contain visited domains, server addresses, request paths, or authentication details. Subscription information may also include personal identifiers. Before sharing, copy only the necessary excerpts and remove passwords, complete subscription URLs, tokens, and personally identifiable information. Do not redact only the most obvious line while leaving similar information elsewhere. If the issue can be described with the failure stage and a little context, there is no need to share the full log.

A useful record should answer: when was it tested, on which network, in which mode, and what happened? After locating the issue, turn off temporary detailed logging, clear exported copies as needed, and restore the statistics view you use. If the issue happens again, collect a new, minimal reproduction using the same method. That is easier to assess than keeping extensive history containing sensitive information.

6. Widget: Shortcuts, Status Refresh, and System Limitations

A Widget provides shortcuts or status information within the limits allowed by the system; it does not replace the full settings in the app. How quickly it updates and which actions it offers depend on the components provided by the current app and system behavior. Verify a manual connection in Shadowrocket before adding a system Widget. The Widget appearing does not mean that a server has been imported, a configuration selected, or system authorization completed.

Check the app's basic state before adding a Widget

Open Home and confirm the selected server and connection state, then check that the correct file is active in Config. If you need rule-based routing, also confirm that Global Routing is set to Config. Then review the Widget options currently available in Settings and change only options you can actually see on the device. This guide does not prescribe a number of Widgets, their size, or a fixed button layout, and does not treat any display as a universal default.

In the system's Widget gallery, find Shadowrocket and choose a style currently available. If it does not appear, first make sure you have opened the app at least once, then follow the system's current steps for adding Widgets. Check the App Store listing for system requirements. Do not reset all app data to look for a style that is not shown in the current interface; first return to the app and confirm that its basic functions work.

Compare the displayed status with the actual connection

A Widget may show the status from its last refresh, which may not match the app's live display. If the status does not change immediately, open the app and verify with an actual request. The system connection indicator is only one point of reference: it cannot show which rule a particular destination used or prove that the server can reach every destination. Assess the Widget, app, and request records separately.

How shortcuts interact with On Demand

If the connection restarts after you disconnect using a shortcut, check On Demand first. A shortcut action and an automatic connection rule may run one after the other, so the final state cannot be explained by that one tap alone. To stop automatic connections temporarily, handle the trigger conditions in the app before disconnecting. Repeated taps can cause overlapping actions and make results harder to interpret; wait for the status to settle after each action.

When the device is locked, background activity is restricted, or additional confirmation is needed, a shortcut may complete differently from an action performed directly in the app. Follow the system prompts. Do not treat background permissions, Low Power Mode, or refresh settings as a fixed checklist that must all be disabled. Compare one setting at a time only when you can reproduce its effect on the feature, and restore unnecessary changes after testing.

Displayed information and device privacy

If a Widget is visible to others, its displayed names may reveal what a server is used for or something about your habits. Give your existing entries recognizable names that do not include excessive personal information to reduce selection and disclosure risks. Do not include passwords, subscription tokens, or complete service addresses in a name. Names are for identification; they do not change server authentication details or prove that protocol settings are correct.

A good baseline is to make sure the in-app workflow is stable, then keep only the shortcuts you actually need. Removing a system Widget usually does not remove servers or configurations from the app, but distinguish what you are removing before you proceed. If the issue occurs only in the Widget, repeat the same action in the app. If it fails there too, troubleshoot the connection instead of continuing to rearrange Widgets. This separates system display issues from network handling issues.

7. iCloud Sync: Data Scope, Conflicts, and Recovery Order

iCloud features save or sync app data within the scope currently supported; they should not be assumed to copy every aspect of the app's running state. Server entries, configuration files, app preferences, and system VPN authorization are separate items. Check the current app's options and documentation to see what is supported. Before using sync for the first time, keep a usable local copy so you do not overwrite your only working configuration before you understand the sync direction.

Distinguish sync, import, and purchase restoration

App Store purchase restoration verifies your eligibility to get the app; it does not restore your servers or configurations. After getting the app again with the original Apple Account, check whether your local data is present before deciding how to restore anything. For purchase steps, see Device Transfer and Purchased App Restoration. Check the App Store listing for purchase compatibility. Having the app installed on one device does not mean all your devices contain the same data.

Sync concerns updates between copies of data; importing usually adds selected content to the current app. They are not interchangeable. If you see Import from Cloud JSON, follow that option's requirements for the file format; do not treat ordinary configuration text or a subscription URL as the same kind of file. Before importing, check the source, content type, and destination. Afterwards, look for duplicate entries and confirm that the intended item is still selected.

Current state and when to enable sync

The current iCloud switch may be affected by system settings, app preferences, and restore history; this guide does not claim a universal default. First verify your data on one device, then enable sync if you need it. If you use only one device and have no syncing needs, your existing setup is fine. Before enabling sync, check that the system allows Shadowrocket to use the relevant iCloud features and that your account and storage are working.

After syncing, do not immediately delete the local copy to test whether it was saved to the cloud. A safer approach is to check the data on another device that is ready to use, confirming the file contents, item count, and necessary fields. A sync-complete message does not replace an actual connection test. Check system authorization, the selected server, and the network separately on that device.

When edits conflict across devices

Do not edit the same important configuration on two devices at once and expect the system to merge the changes correctly. Network delays or offline edits can cause different copies to arrive in either order; a newer modification time does not necessarily mean the content is more appropriate. Choose one device for each editing session. Save a copy, make and verify your changes, then check the other device. If the contents differ, compare them before deciding whether to replace anything.

Subscription updates are not iCloud sync

A subscription update retrieves content from a subscription source you already use; iCloud sync concerns the data objects supported by the app. Syncing a local configuration does not mean a subscription has been updated. A successful subscription update does not mean another device received the latest copy. Record these operations separately while troubleshooting so you do not attribute changes after an update to a cloud overwrite. If you need to keep local notes or edits, first check whether an update could affect them.

Exported data may contain server authentication details; treat it as sensitive when saving or sharing. Before deleting anything, confirm whether the action affects a local copy or a synced item; do not assume it applies only to the current device. Follow this recovery order: get the app, restore the data, check fields, select a configuration, handle system authorization, verify a manual connection, and only then restore On Demand. This makes issues easier to isolate and prevents automatic connections from masking incomplete recovery.

8. Proxy Ports: Local Listeners, Access Scope, and Reverting Changes

First distinguish the two types of address involved in Proxy port settings: the remote port in a server entry and the listening port used to provide a local proxy endpoint. The former is part of the service details you already have; the latter is an access setting on the current device. Changing the local listening port does not fix an incorrect remote server port or alter remote authentication parameters. Before troubleshooting, confirm which type of field you are editing. Do not enter the same number in every port field.

When to change a local port

Do not casually change the local Proxy port just to “optimize” a normal system VPN connection. Check the relevant settings only if you specifically need to connect through a local proxy endpoint provided by the app or have confirmed a listening-port conflict. The protocol type, listening address, and port shown in the current app are the source of truth; this guide does not specify a fixed default port. If the interface does not offer a feature, do not invent a settings option based on other materials.

A port must be a valid number and match the value entered by the connecting device. HTTP and SOCKS5 are different access methods; do not treat them as interchangeable just because both are proxies. If a connection is refused, check that the listener is running, the address and port are correct, and the selected protocol matches before checking the remote route. Do not start by changing DNS; the request may not have reached the local proxy endpoint at all.

The difference between loopback and local network addresses

127.0.0.1 refers to the device making the connection. Entering this address on another device will not point to the device running Shadowrocket. For access across devices, confirm that the app currently provides and has enabled the relevant access feature, use the correct local network address, and check that the devices can communicate. Access point isolation, different subnets, or a sleeping device can prevent a port connection.

Allowing access from a wider range changes who can use this endpoint; do not leave it enabled just for a one-time test. If the app offers access restrictions or authentication options, configure them for your needs. If you do not need to share the endpoint, restrict access to the local device and leave extended access disabled. This is a security baseline, not a claim about the factory default. Do not expose a local proxy endpoint to a network you cannot control.

Preventing forwarding loops and duplicate routing

Do not use a local proxy endpoint as the remote server for the same active route. This can create duplicate forwarding or a connection loop. If a change causes repeated connections, persistent timeouts, or unusual traffic, stop the test immediately, restore the previous server selection and listener settings, then check the references. It is more useful to map where the request enters, which policy it passes through, and where it ultimately connects than to keep changing ports.

Rule files still need to be verified independently. To route only selected domains through a proxy, check Config mode and rules such as DOMAIN-SUFFIX rather than trying to achieve destination selection through port settings. See Rules for Proxying Only Selected Websites for an example. Whether the local endpoint accepts connections and whether a destination matches PROXY are separate layers; record them separately when testing.

Consistent change verification and rollback

After adjusting any setting, first verify the feature it directly affects, then check that common destinations still behave as expected. Record the old and new values, network conditions, and results. Revert any change that did not clearly help. If sync and automatic connections are both involved, stabilize the local configuration first, confirm the synced data next, and enable On Demand last. This prevents results from automatic triggers from being mistaken for final verification while the configuration is still changing.

To continue troubleshooting, follow this page's sections on scope, DNS, testing, and logs in order, and use the Quick Start Guide to rebuild a minimal working setup. For purchase, restore, or device requirement questions, see the App Store guide rather than changing network settings to solve an account issue. Use the recommendations here alongside the interface shown in your current app. A settings change is complete only when you can explain its purpose, reproduce the verification result, and retain a way to revert it.