Official Guide / Features
Shadowrocket
Features and Common Settings
First choose how traffic should be handled, then check servers, rules, and connection conditions. Change one type of setting at a time to pinpoint what made a difference.
This guide follows in-app navigation on iPhone and iPad. Options may vary by version; check the App Store page for system requirements.
01 / Traffic handling
Global Routing：Config、Proxy、Direct
Global Routing determines how traffic handled by the client is routed. This is separate from whether a server is available and whether the system connection is enabled.
What it does: Config mode applies the rules in the active configuration; Proxy mode sends traffic handled by the client through the proxy policy; Direct mode uses the direct policy. “All” means traffic handled by the client, not necessarily every type of system communication on the device.
Where to find it: Open Home, tap Global Routing, then choose a mode. Before troubleshooting, note the current mode and check which server is selected on Home. Switching to Proxy does not fill in server details or confirm that the server is reachable.
| Mode | How it works | When to use it | What to check |
|---|---|---|---|
| Config | Applies the rules and policies in the active Config. | For everyday rule-based routing when you have specific traffic-routing needs. | Active configuration, rule order, and policy targets. |
| Proxy | Uses the proxy policy instead of routing traffic rule by rule. | To temporarily test the proxy connection and narrow down rule-related issues. | Selected server, authentication fields, and actual access results. |
| Direct | Uses the direct policy. | To temporarily check direct access on the current network. | Whether the local network is working, and whether you restore the previous mode after testing. |
How to set it: If you already have a working configuration, select Config and test a destination that should match an expected rule. If it fails in Config, temporarily select Proxy and try the same destination with the same network and server. If Proxy works but Config does not, check which rule matched. If both fail, check the server details and network conditions before adding more rules.
What to keep in mind: Direct does not turn off the system VPN connection. Check the selected mode and connection switch separately. When you finish troubleshooting, restore your usual mode so you do not leave a temporary setting in place. For step-by-step connection instructions, see the Setup Tutorial; this page focuses on how the features work together.
02 / Config and policies
Rule-based routing: match first, then apply a policy
A rule answers “What conditions does this connection match?” A policy answers “How should a matching connection be handled?” Knowing the rule keywords alone is not enough to determine the actual route.
What it does: Rules are usually checked in order. When a rule matches, its assigned policy is used. Common policies include DIRECT, PROXY, and REJECT, for direct access, proxying, and blocking. A configuration can also reference policy groups, so if you see PROXY or a group name, check which server it ultimately points to.
Where to find it: Open Config, confirm which configuration is active, then review or edit its rules. Saving another file does not make it active. To test the configuration’s routing logic as expected, also confirm that Global Routing is set to Config.
How to configure it: Back up the current configuration first, then add rules with clearly defined scopes. Place specific targets before broader matching conditions, and check the final FINAL rule. During testing, note the destination, matching rule, and policy used; do not infer the routing result only from whether a page opens.
| Keyword | Matches | What to consider |
|---|---|---|
| DOMAIN | Exact domain name. | Use for a single domain. It does not include all of its subdomains. |
| DOMAIN-SUFFIX | Domain suffix. | Applies to the domain and its subdomains; check the scope carefully. |
| DOMAIN-KEYWORD | Keyword in a domain name. | Can match broadly; avoid short keywords that may cause unintended matches. |
| IP-CIDR / IP-CIDR6 | IPv4 or IPv6 address range. | Check the address type and prefix length. Domain requests may also involve DNS resolution. |
| GEOIP | Geographic IP data. | Matching depends on the IP address and database, not the page language. |
| FINAL | Fallback for connections not matched by earlier rules. | Check the fallback policy so unmatched connections do not take an unexpected route. |
What to keep in mind: A single page may request resources from multiple domains, so a page loading successfully does not mean every resource used the same policy. DNS results, configuration content, and connection reuse can all affect rule matching. Do not assume a setting is complete just because you added one example rule; check whether an earlier rule already matches. For keyword definitions, see the Glossary.
03 / Home and importing
Managing subscriptions and servers
This section assumes you already have subscription or server details. A one-time purchase of the client is not a connectivity plan; get subscription links from your service provider.
What they do: An individual server stores the protocol, address, port, and authentication details needed to connect. Subscribe imports and updates a set of server details. Config handles rules and related settings; the two serve different purposes. Updating a subscription refreshes the content associated with it and should not be treated as a universal fix for configuration issues.
Where to find them: From Home, open the add menu and select Add Server, then choose the appropriate type. For an existing subscription link, use Subscribe. For individual server details, choose the matching protocol and fill in the fields. Use Scan QR Code to read a QR code; clipboard import works with share content supported by the current client.
How to set it up: First identify whether your import data is a subscription link, an individual server share link, or a configuration file, then choose the matching option. When entering details manually, make sure Address, Port, and protocol match the information from your service provider. Fill in Password, UUID, TLS, SNI, and other fields only as required by that protocol; do not mix parameters from different protocols. After importing, add a recognizable label to each server or subscription, then select a server to test.
If you use multiple subscriptions, label them by source and purpose, and confirm which one you are updating. An unavailable server does not necessarily mean you need to delete the entire set; first check the update result and whether the service is still active with your provider. Save any information you need before deleting, especially manually edited fields that a later update could overwrite.
What to keep in mind: Subscription links may contain access credentials. Do not include them in public logs, screenshots, or feedback. A QR code being readable only means its content can be recognized; it does not mean the server is reachable. A latency test is not the same as verifying full webpage access. For updating, sorting, deleting, and backing up, see the Subscription and Server Management Guide.
04 / Connection conditions
On Demand: connect automatically under specified conditions
On Demand controls when a connection is established. It does not replace Global Routing or determine whether a subscription is valid.
What it does: On Demand uses the system’s on-demand connection mechanism to handle connections according to configured network conditions. It is useful when you want to connect automatically on particular networks. Check the current interface for the available conditions and how they can be combined.
Where to find it: Open Settings and look for the On Demand options. Check the current toggle and existing conditions. If you have configured On Demand before, note those conditions first and decide whether to add or change anything to avoid conflicting duplicates.
How to configure it: First confirm that the server and Config work while connected manually, then set up On Demand. Change one network condition at a time. After saving, check the system VPN status on the relevant network and test access to a known destination. Verify Wi-Fi and cellular connections separately; do not just toggle the setting repeatedly on the same network.
What to keep in mind: With On Demand configured, manually disconnecting may still trigger a reconnection when the conditions are met. To temporarily stop automatic connections, check the On Demand conditions instead of repeatedly tapping the Home switch. An On Demand connection being established does not mean traffic is routed correctly; Global Routing and the active configuration determine the path.
05 / Usage records
Data: view traffic, not billing
Data helps you observe traffic recorded by the client. It can help determine whether data was transferred, but it cannot by itself confirm speed, connection quality, or billing.
What it shows: Data displays traffic statistics visible to the client. Upload and download refer to data transferred in different directions. Check the page for the exact metrics and recording scope. Client statistics, system-level device statistics, and provider usage measurements may use different methods, so their values do not have to match exactly.
Where to find it: Open Data and check the statistic’s scope and time range. If the page offers categories by server or connection, confirm which one you are viewing before comparing values. Do not treat a figure for one category as the device’s total traffic.
How to check it: Choose a well-defined test, such as visiting a single destination, then compare traffic before and after. If the interface has a reset option, save any records you need before deciding whether to use it. Resetting client statistics does not reset usage recorded by your service provider. For longer observations, keep the measurement scope consistent.
What to keep in mind: A small amount of traffic does not mean the destination loaded successfully; connection negotiation, retries, and background requests can also generate traffic. Data cannot tell you how much usage remains and does not replace your provider’s billing records. To investigate a failed request, review Data alongside connection details in Diagnostics.
06 / Common settings
Settings: DNS, testing, shortcuts, and sync
Keep your current working settings before making changes, and adjust them to address a specific issue. A setting with the right-sounding name will not fix every connection problem.
DNS: distinguish resolution failures from connection failures
What it does and where to find it: DNS resolves domain names to addresses. When checking DNS options in Settings, also look for DNS settings in the active Config so you do not change one location while overlooking the configuration in use.
How to configure it: Note the current DNS settings, make a change only for a clear reason, then test the same domain again. If only some destinations fail, first determine whether DNS returned no result or whether the connection failed after an address was returned. If you need to specify a resolver, check its address format, reachability, and compatibility with the current network; do not replace it just because that address is commonly used.
What to keep in mind: DNS results may be cached, so they may not change immediately after an update. Changing DNS will not fix an incorrect server password, port, or TLS setting. For configuration overrides and precedence, use the active configuration and diagnostic results as your guide; changing DNS should not be an automatic first step.
Test Method: keep test conditions consistent
What it is and where to find it: Test Method is a Settings option related to connection testing. Interpret Connectivity Test results on Home in the context of the selected method. Different methods may test different stages, so their results are not directly comparable.
How to configure it: Choose a method supported by the current interface that fits your troubleshooting goal, then test the same set of servers. Keep the network, test method, and destination consistent when comparing results. If the test method includes a target address or timeout option, record those too.
What to keep in mind: A successful test usually confirms only that the test conditions were met; it does not guarantee that all real-world requests will work. A failure may also be related to the test target or timeout. Do not sort servers based on a single latency result; verify the selected server with an actual request.
Today Widget: quick access and system support
What it is and where to find it: Today Widget is a setting for system-level quick access. Check the related options in Settings, then see whether it can be added from the relevant system widget management screen. Availability and appearance depend on the current system and app interface.
How to configure it: Add it using the method provided by the system, then check the displayed connection status and available actions. The first time you use it, return to Home to confirm that the shortcut affected the intended connection instead of relying only on the text shown in the widget.
What to keep in mind: The widget provides a shortcut; it does not change server details or rules. If it does not appear, first check system support and widget settings. Do not change DNS, subscriptions, and Config just to make the widget show up.
iCloud: handle sync and backups separately
What it is and where to find it: iCloud options sync content supported by the app when your system account and cloud services are available. Check the related switch in Settings, along with iCloud permissions and available storage in the system settings. See the app for the exact sync scope.
How to configure it: Before changing devices, confirm the sync status on your old device and separately save important Config files and existing subscription details. After restoring the app from the App Store on the new device, check that the synced content is complete and verify servers, configurations, and rules one by one. Do not delete data from the old device just because items appear in a list.
What to keep in mind: Sync is not a standalone historical snapshot; changes or deletions on one device may affect others. Purchase records, system VPN configuration permissions, and in-app settings are different kinds of data. You may still need to confirm system permissions on the new device after syncing.
07 / Diagnostics and retesting
Diagnostics: narrow down issues using evidence
Reproduce the issue once, then review the records from that time. Check the connection, DNS resolution, rules, and server details separately; changing several things at once makes the cause harder to identify.
What it is and where to find it: Diagnostics is an entry point for checking connection status and related records. Look for it in Settings. Available logs and tools may vary; check the current interface. Diagnostic records are supporting evidence and should be interpreted alongside the network, Global Routing mode, and active configuration at the time of the issue.
How to use it: Note the failed destination, time, and error message, then repeat the smallest possible action. Check the relevant records to identify whether the issue occurred during DNS resolution, connection setup, authentication, or a later request. If only Config mode fails, focus on rules and policies. If the same server also fails in Proxy mode, check the server fields and test conditions first.
What to keep in mind: Logs may contain subscription links, server addresses, visited domains, and authentication details. Before sharing records, remove credentials and personal information; keep only the time, error type, and checks needed to diagnose the issue. Do not lower TLS verification requirements just to troubleshoot an ordinary connection error.
Complete settings checklist
- Confirm the current network is working, then note the server and connection status shown on Home.
- Check Global Routing and reproduce the issue with the same destination.
- In Config, check rule order and policy targets. For the server, verify the protocol and authentication fields.
- Review DNS, Test Method, and Diagnostics. Do not compare results from different test methods as if they were equivalent.
- Change one setting at a time. Retest, keep changes that work, and restore any temporary mode afterward.
For more troubleshooting by symptom, see Troubleshooting. To repeat the import and connection steps, see the Setup Tutorial.