Settings Reference

01 · Settings and checking current values

Troubleshooting starts with a repeatable baseline, not a full reset to defaults. In Home, check the selected server, then review the Global Routing mode and the configuration enabled in Config. A Settings change only makes sense in this context: the same DNS value can behave differently across networks, rules, and servers. Record these three details before opening the setting you want to change. Note its original value, why you changed it, and the test result.

Default, current, and recommended values are not the same

A default is the value an app uses under specific initial conditions. The current value may instead reflect a manual change, an imported configuration, or previously restored data. On a device that has been used before, a switch's position alone cannot tell you what the factory default was. This guide does not present values as universal defaults when they cannot be checked on every device. Read the value shown on your device before assessing switches, ports, or test methods. A recommended value suits a particular use case; it is not necessarily faster on every network.

To check default behavior, start with the relevant in-app explanation, then see whether the enabled configuration contains related directives. Do not delete every configuration just to get a “clean slate.” That could also remove server records, rules, and groups you need to roll back. A safer approach is to back up what you have, duplicate a configuration for testing, and note how it differs from your everyday setup.

Understand the three Global Routing modes

Config routes requests according to the rules in the current configuration. Proxy sends traffic through the proxy path for that mode. Direct connects without using the proxy path. These are different traffic-handling modes, not speed settings. If you use rules for everyday routing, start with Config. To isolate the effect of rules, you can temporarily switch modes and compare the same destination, then restore the original mode when you're done. Changing modes will not fix incorrect server parameters.

Change one variable at a time

Choose a page you can revisit reliably and record the network type, connection status, and failure behavior. After changing one setting, reconnect if needed and make a new request. If you change the server, DNS, and rules at the same time, even restored access won't tell you which change helped. To roll back, undo changes one by one in reverse order instead of layering on more settings. Record the step that succeeded, not just that things “seem fine.”

Also distinguish app-wide settings from configuration-specific settings. A global option in Settings, a directive in a Config file, and a parameter on an individual server may apply at different levels. If a change has no expected effect, first make sure you edited the object currently in use, then check the scope described in the in-app help. Don't assume identically named settings simply override one another, or treat content in an inactive configuration as the current runtime state.

If a menu label differs slightly from this guide, check its function and the in-app explanation rather than changing an option based on a similar name. See the tutorial for the complete first-time setup sequence, or visit Troubleshooting to find a path by symptom. The sections below follow the same steps: check the current state, make the smallest change, test it, and roll back if it fails.

02 · DNS: Resolution paths and rule checks

DNS resolves domain names to addresses used to make connections. A successful lookup does not guarantee the connection will work, and a successful connection alone does not prove that the expected resolution path was used. When troubleshooting DNS, check the domain, the resolved address, and the policy applied to the request. First see whether the current Config contains DNS directives, then review the DNS options actually available in Settings and their explanations. Don't replace all DNS settings based on a single browser error.

Start with a working configuration; don't replace it outright

The value currently shown on your device is a troubleshooting baseline, not automatically the default. Different configurations may specify different DNS servers, query methods, or domain-handling conditions. If your existing setup works, leave it as is. Make a targeted change only when you can reproduce a lookup failure, get an unexpected address, or need to meet a specific network requirement. Adding more manually entered addresses does not necessarily make DNS more reliable.

On campus, at work, or on other managed networks, internal domains may rely on DNS information provided by that network. Sending every request to a different resolver could make internal sites unavailable. Conversely, a resolver that cannot be reached on the current network may slow requests. First distinguish an unreachable DNS server from a server returning an unexpected result; they require different fixes. Waiting longer alone won't tell you which is happening.

Domain rules and IP rules solve different problems

DOMAIN-SUFFIX matches domain suffixes; GEOIP makes decisions using geographic information associated with an address. They rely on different criteria and are not interchangeable. Rules are generally evaluated in order, so place more specific domain rules appropriately and use FINAL as the last-resort policy at the end. This snippet illustrates rule order; it is not a complete replacement for your configuration. PROXY must refer to a policy recognized by the current configuration.

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

This example handles example.com and its subdomains first, checks the address condition next, and sends remaining requests to the final policy. Choose DIRECT or PROXY based on your own needs and existing configuration. Copying a snippet cannot guarantee access to a particular site, and routing every domain through the same policy won't fix an underlying DNS problem. To proxy only selected sites, see DOMAIN-SUFFIX setup and verification.

Test in stages to reduce cache interference

First reproduce the problem with the same domain. Then check the request record for a resolved address, the matched rule, and the stage where the connection failed. After changing DNS, make a new request. Existing connections may keep using an earlier result, and the browser or system may cache DNS. If needed, close and reopen the relevant page and reconnect using the method provided by the app. A single page refresh does not prove that every cache has been cleared.

If one domain fails, check its spelling, domain rules, and the destination itself first. If most domains fail to resolve, check resolver reachability and network status. If an address was returned but the connection failed, investigate the server, TLS, routing, or destination service instead of repeatedly changing DNS. Directly accessing an IP is not always a valid comparison: HTTPS sites may require the correct domain for certificate validation.

Save a working and a failing comparison: use the same network, server, and domain, and change only the DNS setting under review. If you have to test across networks, note the network change separately. If an internal domain stops working, restore the original DNS conditions first and retest. For widespread failures, roll back the most recent change. Matching the result to the timestamp in Log is more useful than cycling through multiple addresses.

03 · On Demand: Conditional connections and manual control

On Demand manages VPN connection behavior based on conditions supported by the system. It controls when a connection is attempted; it does not choose a routing rule for a particular site or make an unavailable server work. Before using it, establish a stable manual connection: import your own configuration, confirm the selected server works, check Global Routing, and verify access. If a manual connection still fails, enabling automatic triggers only adds another variable.

Check the current state and conditions before enabling

Open the relevant settings and record the master switch and any existing conditions, then check what each condition applies to. The current state may carry over from earlier changes; reopening the app does not restore defaults. If the interface offers options by network or condition, review them individually. Don't infer features that aren't shown from screenshots of other devices. Start with the fewest conditions needed to cover the situations where you actually want an automatic connection.

Several steps separate a trigger condition from a successful connection: the system must recognize the condition and allow the connection, a network path must be established, and the client must connect to the server. An automatic attempt may fail temporarily if the network has not obtained a usable address or requires a sign-in first. An enabled On Demand setting does not mean the connection will always succeed, and it cannot guarantee that a request will work as expected.

What to check when switching networks

Start by testing on a known working Wi-Fi network, then switch to another working network and check whether the VPN and in-app connection states match the conditions. After each switch, give the network time to come online and make a new request. Existing connections may drop and reconnect, and background apps may retain an old state. Judge the result by a new request and current records, not by whether a page opened before the switch is still visible.

If a condition uses a Wi-Fi name, check for an exact match, including capitalization, spaces, and similar-looking characters. The same name does not guarantee a trusted network, so a network-name condition is only one part of connection logic, not authentication. Other VPN configurations or device management policies may also affect the result. If connections keep switching, first find out which configuration is currently controlling the connection.

Distinguish manual disconnection from automatic triggers

With On Demand enabled, a manual disconnect and a later condition being met are separate events. If the connection comes back after you disconnect, check the On Demand conditions before deciding the switch is broken. For a controlled offline test, turn off the relevant On Demand behavior first, disconnect manually, and then check the system and app states. When you're done, restore the settings from your notes so temporary changes to automatic connection behavior aren't forgotten.

System permissions, device management restrictions, and network conditions can all affect On Demand behavior. If a prompt asks you to manage a VPN configuration, read it before proceeding; don't repeatedly confirm prompts when you're unsure where they came from. Initial authorization is separate from automatic connection later, and an existing configuration does not mean every condition will work. If you're unsure of the current state, return to the manual connection steps and verify the network and server details first.

The right setting depends on whether you need automatic triggers; On Demand does not need to be enabled for everyone. If you frequently test rules manually, keep control manual for now to reduce interference. Enable On Demand only when you have a stable configuration and a clear need for conditional connections, then verify each condition. Don't add many conditions at once just to reduce taps. For each one, know which situation it covers and how to remove it if it causes an unexpected connection.

If connections are intermittent, note whether the device was locked, switched networks, or completed a network sign-in just before the issue, then compare with Log diagnostics. Repeatedly tapping Connect adds noise. Disable automatic triggers and reproduce the issue with one manual connection first; this often separates network, server, and trigger-condition problems more clearly.

04 · Ping and Connectivity Test: what the results can tell you

Ping and Connectivity Test show connectivity at different layers; neither guarantees that every real-world request will work. First check the selected test method, target, and timeout, then interpret the result. Similar-sounding tests may check different stages: some focus on host or port reachability, while others send a request through the proxy path. Read the option's explanation on your device; don't assume every displayed value in milliseconds measures the same latency.

Identify what is being measured before comparing results

A measurement reflects specific network and target conditions. A test to a server address and a test that uses the server to reach a webpage cover different parts of the path. The first can show that some stages along that route are reachable; the second may also depend on DNS, protocol handshakes, and the destination service. Don't rank results from different methods or targets as if they were comparable, and don't assume a lower number means every app will be faster.

This guide does not prescribe a universal timeout or test target: current values may have been changed, and available options depend on what the app shows. Keep a working method and run it repeatedly to establish a baseline. If you need to adjust something, change one condition at a time—for example, keep the target and change the network, or keep the network and compare test methods. A timeout that's too short can mark a slow but successful connection as a failure; one that's too long delays detection of an unreachable target.

How to run a useful test

First confirm that the server details belong to a configuration you're authorized to use, then check the address, port, and protocol. Run a small number of tests on the same network and note the distribution of successes and failures, not just the best result. If results vary widely, rule out network changes, signal fluctuations, and heavy device activity. Don't run several tests at once; competing for network resources makes the results harder to compare.

Then connect and visit a repeatable test destination to see whether the real request completes. After the page opens, test the next action relevant to your use case, such as loading additional resources or completing a normal interaction. A fast first response does not guarantee a stable transfer, and one download does not represent the latency of small requests. Use measurements to investigate a specific symptom, not just to chase a better-looking number.

A timeout does not always mean the server is unavailable

Some networks restrict particular probe methods, and a server may not respond to a given type of probe. A Ping timeout is therefore not the same as a failed proxy request. If access works but a probe fails, keep the working configuration and check whether another test method suits the environment better. Conversely, an open port does not prove authentication is correct; an incorrect password, UUID, or TLS parameter may only show up later in the handshake.

If all your existing servers show similar failures at the same time, first check that the device is online, then review shared DNS or test-target conditions. If only one entry has a problem, check its parameters and service status first. Failed tests across multiple entries do not prove every server failed at once, especially when the tests use the same target, which may itself be the common cause.

For TLS connections, keep certificate validation enabled; don't change security-related options just to make a test pass. If a test fails, check the server address, port, domain, and device time, then review the server requirements. Extending the timeout won't fix incorrect protocol parameters. For help with specific fields, see Trojan parameter reference, but always follow your actual configuration.

Choose settings that reliably complete the requests you need, rather than chasing the lowest test result. Save the test time, network type, and result, then look for failures at the same time in Log. This helps distinguish an unsuitable test method from a failed connection or destination request, and prevents repeated changes at the wrong layer.

05 · Log and Data: identify where a request failed

Use Log to understand what happened during a real request, not to diagnose a problem based on a familiar-looking English term alone. Before troubleshooting, note the time, destination domain, network type, Global Routing mode, and selected server. Then make a repeatable request and look for records around that time. Multiple apps may connect in the background, so judging the issue from the topmost row can easily lead you to an unrelated request.

Read the record in stages: resolution, rules, connection, response

First check whether the domain was resolved and an address was returned. Next, check which rule matched and which policy was applied. Then see whether a connection to the destination or server was established, followed by any handshake and data transfer. Fields vary with what the app actually displays, and not every request includes the same detail. A missing record doesn't necessarily mean a step did not happen; consider the recording scope and current settings too.

For example, if the domain and address appear but the request later times out, investigate the connection path rather than changing DNS alone. If the request consistently matches an unexpected rule, check Config and rule order first. If the policy is right but authentication fails, focus on server parameters. Looking at the full sequence helps you avoid skipping the actual failure point because one error term looks familiar.

Choosing log detail and retention

Review the current log options and in-app explanations; don't present the value on your device as a universal default. For everyday use, keep enough detail to see what you need. Temporarily increase logging when you need to reproduce a problem. More detailed records can use additional storage and processing and may reveal more about your activity. Restore your usual settings after diagnosis; you don't need to keep every test record indefinitely.

Don't clear the records before saving anything useful. First note the symptom and time, save the necessary excerpts, and make sure you have a rollback reference; then clear records if needed. Reconnecting can change the timeline, so note when each connection and disconnection occurs. For intermittent failures, recording when they started, how long they lasted, and whether the network changed is usually more useful than accumulating logs without context.

Data statistics are not a bill

Data shows traffic information the app can measure. Before interpreting it, check the measurement scope, direction, time period, and whether the counter was reset. The app, system, network provider, and connectivity service may count traffic differently. Protocol overhead, measurement start and end points, and refresh timing may also vary. Data can help tell you whether a test transferred anything, but it should not be treated as the basis for another system's billing.

If the count keeps rising, check foreground downloads, media loading, and background tasks before assuming a setting is wrong. A connection can be established without a visible increase if no new requests have been made. Try a short, repeatable visit and observe the change; don't transfer large amounts of data just to test the counter. For longer-term comparisons, use the same measurement window and reset point.

Remove sensitive context before sharing

Subscription links, authentication details, destination addresses, and server identifiers may appear in diagnostic context. Before posting publicly, review the full text—not just the password in the middle of a screenshot. Keep the error type, sequence, and necessary field names, but replace values that identify your account or connection resources. If you're discussing rules, you usually don't need to share a full subscription or configuration.

Separate observations from assumptions: an observation is which request failed and when, and which policy it matched; an assumption is which setting might have caused it. Use this minimal record with Troubleshooting to find the right path faster. When you're done, turn off temporary detailed logging and confirm that your everyday configuration is still the one you intended to use.

06 · Widget: quick access and status checks

Use a Widget as a shortcut to check status or open an action, not as a replacement for a full check in Home. The system controls when Widgets refresh and how they respond, so displayed information may not reflect the latest connection state. If the Widget disagrees with the app, open Shadowrocket and check the selected server, Global Routing, and connection status before making a real request. Don't assume an old status label means the connection is still working.

Distinguish what the Widget shows from what it controls

Widget styles and available interactions may vary by device. Use the options shown when adding a Widget and the in-app explanation as your reference. Some actions may open the app or require system confirmation; a lack of immediate visual change does not necessarily mean the feature failed. After adding a Widget, test it explicitly: connect from a disconnected state, then disconnect, and observe the app status and when the Widget refreshes each time.

Before changing a Widget-related option in Settings, check its current value. This guide does not specify a universal default layout; the displayed result depends on the Widget layout and system support. Keep only the information that helps with everyday checks, so similar shortcuts don't invite mistakes. For server changes, protocol parameters, or complex rules, return to the relevant screen in the app and review them there.

Troubleshooting stale Widget information

First check whether the state has changed in the app, then wait for the system to refresh and check the Widget again. If the app is still connecting, troubleshoot the connection rather than rebuilding the Widget. If the app and actual access work but the Widget is out of date, reconfigure or add it again using the system's options. Don't also reset Config, DNS, and server records; they are rarely the first things to check for a display issue.

Network changes, screen lock, and background activity can all affect what you see. Note what happened just before the issue, and distinguish among “Widget hasn't refreshed,” “tap didn't complete the action,” and “connection failed.” The first two concern the display or interaction path; the third calls for network checks using Ping and Log. Treating them as the same problem can lead you to repeatedly change connection settings that were working.

Check the action sequence when using On Demand

If On Demand is enabled, a condition may trigger a new connection attempt after a manual disconnect from the Widget. That doesn't necessarily mean the Widget button failed. To test, temporarily turn off On Demand and check the shortcut on its own. Once it works, restore On Demand and test how the two behave together. Use the actual state in the app as your reference, not just the icon's appearance.

A shortcut may use the server and configuration last selected in the app, so check what was active before you use it. If you don't restore your everyday setup after testing, the next connection from the Widget may use test settings. At the end of each rules check, follow the same wrap-up: restore the configuration and Global Routing mode, confirm the server, then check the shortcut.

Limit the information shown

A Widget may appear somewhere other people can see it. If you can choose what it displays, consider whether server names and status details should be visible. Avoid putting full account details, subscription URLs, or other credentials in the names of personal entries. Names are for identification; keep detailed parameters in their settings. This also makes everyday selection easier and reduces the risk of exposing sensitive context in screenshots or screen sharing.

If the traffic shown in a Widget comes from app statistics, interpret it within Data's measurement limits. A number in the Widget does not represent all device traffic. System refresh timing and the app's measurement window can both affect what's displayed. To compare traffic before and after a visit, check the measurement scope in the app and run a controlled test instead of subtracting two Widget readings taken at different times.

Keep the Widget as a simple shortcut and make complex changes in the app. If the Widget remains out of date while the app and actual access work, treat it as a display issue. If all three show a problem, return to basic connection troubleshooting. This preserves the convenience of quick access without using repeated connection resets to fix a display delay.

07 · iCloud: sync, backups, and moving to a new device

iCloud sync and an exported backup serve different purposes. Sync propagates changes across supported content; a backup preserves a copy from a specific point in time. Sync is not an archive you can use to return to any historical state. Before reorganizing or moving to a new device, check which iCloud options the app actually provides, their current states, and what you can export, then save an independent copy. Don't change settings on multiple devices before checking the data.

Check what sync covers instead of assuming everything is copied

Check separately how server records, Config files, and app settings are saved or synced. Different types of content may be handled differently. The appearance of one configuration does not prove that passwords, selection states, and usage statistics have all migrated. Check the in-app explanation and actual results to confirm coverage. Test with an easy-to-identify item that contains no sensitive information before reorganizing a large set of data.

In system settings, check the current iCloud account and relevant permissions, as well as available storage and network status. Enabling a switch in the app is only one sync condition; it does not confirm that data has been saved remotely. If content hasn't updated, check these basics and see whether the other device can read it. Repeatedly toggling the switch or importing the same file won't necessarily speed things up and may create duplicates that are hard to distinguish.

Move in stages: install, check, restore, verify

First get Shadowrocket from the App Store. See how to restore a previous purchase. Purchase history and personal connection settings are different kinds of data; restoring the app does not restore server details. After installation, check your iCloud settings and restore the content you need from an existing backup. Finally, review the selected server, Config, Global Routing, and any required system permissions.

After the first restore, test a manual connection before enabling complex On Demand conditions. Visit a familiar destination and check that DNS and rules behave as expected. If the content is restored but the connection fails, check server parameters and the current network instead of assuming sync caused the problem. The old device can provide a useful comparison, but don't make conflicting changes on both devices at once.

Keep two reference copies while resolving conflicts

If the same content was edited on two devices, don't assume the system will keep the version you want. Save a local copy from each device first, decide which one will be your baseline, and then use the app's available options to resolve the difference. Compare at least the rule order, final policy, server references, and relevant parameters. Matching filenames do not prove matching content, and a more recent timestamp is no substitute for checking the files.

If you find duplicate entries, check whether they contain different data or are duplicate imports before deleting anything. Don't bulk-delete by name alone; servers with the same name may have different ports or transport parameters. After cleanup, verify the result on one device before checking the other. Take particular care when deletions sync: until you know what's affected, an independently restorable copy is more valuable than a tidy list.

Backups also need access controls

An exported configuration may contain addresses, passwords, UUIDs, or subscription links. A plain-looking filename does not make it safe to share. Store the file somewhere you can control access to, and review it before sharing. If you only need to discuss rules, make a separate minimal example with personal parameters removed. A backup is useful only if you can read it and identify what it contains—not simply because a file exists.

Keep a known-working copy before important changes, and note what it is for; there is no need to keep every inconsequential test as a long-term backup. See configuration backup and iCloud migration for the full device-migration and restore checks. Once migration is complete, re-enable automatic connections and shortcuts, then make sure you won't accidentally select an old test copy as your everyday configuration.

08 · Proxy ports: local listeners and access scope

First distinguish a local listening port from a remote server port. The port in Add Server is used to connect to your server. A local proxy listener port lets compatible requests connect to a listening service on your device. They serve different purposes, appear in different places, and follow different paths. Changing a local port won't change the remote server's port, fix incorrect credentials, or replace a connection service that is no longer available.

Check the protocol, address, and port together

If the app offers listener settings, read the displayed protocol type, listening address, and port details. HTTP and SOCKS5 are different proxy access methods; the client making the request must use the matching type. The address tells it where to connect, and the port identifies the listener. A correct number alone won't help if the address or protocol is wrong. Don't assume a familiar number shown on another device is the default on yours.

Enable a listener only when you have a specific use for it, and note the original value. If you only use Shadowrocket for a regular VPN connection and rules-based routing, verify that workflow first; you don't need to change listener settings just to make the setup feel complete. Different entry points may have different requirements, so check the in-app explanation. Don't assume an unsupported listener or access-control feature exists by guessing configuration fields.

A loopback address is not a LAN address

A loopback address refers to the device making the request. If another device uses a loopback address, it points to itself—not to the device running Shadowrocket. If you need access from another device, first confirm that the app supports the access method, then check the listening scope, network, and any required access controls. Widening the listening scope alone does not guarantee that requests can reach the service from another device.

A wider listening scope lets more network sources attempt to access the entry point. Use the narrowest scope that meets your needs. If the interface offers authentication or access restrictions, check that they fit your use case. If you can't confirm the access boundary, don't expose the listener to an untrusted network. A network change may also change the device's address, making the old address unusable. Remove access settings you no longer need.

Troubleshoot refused connections, timeouts, and authentication failures separately

If a connection is refused, first check that the relevant listener is enabled, the app is in the right state, and the port is correct. For a timeout, also check the address, network reachability, and access scope. If a connection is established but authentication or protocol errors follow, check the protocol selected by the client and the requirements at both ends. Don't keep changing ports before identifying the failure stage; otherwise, it becomes harder to match the client and listener records.

Keep the regular VPN path as a baseline, then test the listener separately. If the client supports proxy settings, change only the required fields in that client and restore them after testing. Otherwise, problems in other apps may simply mean they're still pointing to a listener you've turned off. One app being able to use a proxy does not mean every app on the device will use the same settings; check the scope of each request.

Include port checks in your final review

Once the local entry point works, check which policy and server the request ultimately uses. A successful listener test only confirms that the request reached the entry point; it does not verify resolution, rules, or the rest of the connection. Find the request at the same time in Log and confirm the destination response. If there's no corresponding record, first check whether the client actually used the proxy settings you entered instead of changing remote server parameters.

Finish in a consistent order: restore your everyday Config and Global Routing mode, confirm the selected server, roll back temporary DNS and Log settings, check On Demand, and then review the Widget. Update your backup notes before keeping any changes. If the issue remains, continue with Troubleshooting or return to the tutorial and repeat the basic connection steps. Don't cover an unexplained symptom with more unrelated switches.