Shadowrocket Official Guide · Glossary

Shadowrocket Glossary

Use the categories to distinguish interface terms, protocol names, and rule syntax. First check where a term appears, then review what it does and where its limits are; similar English names may refer to different settings.

Interface option Config / Proxy / Direct

Sets the overall mode for Global Routing.

Matching condition DOMAIN-SUFFIX

Determines whether a connection matches a rule.

Rule action PROXY / DIRECT / REJECT

Specifies what happens when a rule matches.

Use this page to look up terms, not as a step-by-step guide. For your first setup, read the setup guide. For updating, sorting, and backing up an existing subscription, see the server management guide.

Interface & toggles

Connection screen and modes

A name may refer to both a screen and a mode option. The explanations below depend on where the term appears; screen layouts may vary by platform and app state.

Home: The screen for viewing the server list, choosing a connection, and toggling it on or off. Selecting a server only sets the connection target; you still need to enable the connection and check that it works. An enabled toggle does not guarantee that a destination is reachable.

Global Routing: Sets the overall connection mode. The interface terms for configuration, proxy, and direct connection are Config, Proxy, and Direct. Use Config to route traffic by rules. If you temporarily switch modes for troubleshooting, note the original setting and restore it after testing.

Config: As a screen name, Config opens configuration file import, selection, and management. In Global Routing, it means connections are handled according to the active configuration’s rules. Saving a file does not enable it; check the selected configuration and current mode as well.

Proxy / Direct: In Global Routing, Proxy uses the proxy mode, while Direct uses a direct connection. These set the overall operating mode, not the protocol of a specific server. They are also distinct from the uppercase PROXY and DIRECT actions in rule entries.

On Demand: Requests an automatic connection from the system when specified conditions are met, reducing the need to connect manually in those situations. It does not choose routing rules or fix an incorrect password or address. After disconnecting manually, check whether a trigger is still active before reconnecting.

DNS: The mechanism that resolves domain names to IP addresses. It can affect domain access and some rule matching. If a domain fails to open but its IP address responds, check DNS separately. Changing DNS settings will not fix protocol authentication failures or an unreachable server.

Connectivity Test: The test screen checks server reachability using the selected method. Results depend on the local network, test target, and connection protocol. Use the same test conditions when comparing results. A successful test only confirms a response to that probe; it does not prove that every app and destination will work.

Protocols

Server types and connection settings

The protocol determines how the two ends authenticate and transmit data, not how rules match. When adding a server, use the details provided for that server; do not reuse fields from a different protocol.

Shadowsocks: A proxy protocol that uses an encryption method and password to establish a connection. The address, port, encryption method, and password must match the server. Similar-looking encryption method names are not interchangeable; check each setting against the details from your service provider.

VMess: A proxy protocol that authenticates with a user ID. Transport and related security options may also need to match the server. A correct user ID is only one requirement; a mismatched transport path, Host, or TLS setting can still prevent the connection.

VLESS: A proxy protocol authenticated with a user ID. Its transport and security settings must match the server. It is a different protocol from VMess; changing the protocol name alone does not make all the existing settings compatible. Check the supplied details to determine whether TLS and other options are required.

Trojan: A proxy protocol commonly used with TLS. Common settings to check include the address, port, password, and SNI. SNI identifies the service name during the TLS handshake and may differ from the connection address. For certificate errors, first check the domain, system time, and server settings.

Hysteria2: A QUIC-based proxy protocol that uses UDP and requires matching authentication and TLS settings. If the network blocks UDP, the connection may fail even with the correct address and password. Set bandwidth-related options to suit actual conditions; increasing values is not a substitute for checking connectivity.

WireGuard: A protocol that creates an encrypted tunnel using public and private keys and peer details. Settings usually include the tunnel address, endpoint, and allowed IP ranges. Keep private keys confidential and out of help screenshots. If the handshake succeeds but access does not work, check routing and DNS.

HTTP / SOCKS5: Two proxy protocol names. Check the server configuration to confirm the authentication method and supported traffic types. The protocol name alone does not indicate whether a connection is encrypted, and not every SOCKS5 service supports UDP forwarding. Verify the specific service requirements.

Rule keywords

Matching conditions and actions

A typical rule consists of a match type, a match value, and an action. Rules are usually evaluated in list order. Before reviewing a rule, check that Global Routing is in Config mode and whether an earlier, broader rule already matches.

DOMAIN: Matches the exact domain specified. For example, DOMAIN,example.com,DIRECT applies to example.com. It does not automatically include all subdomains. To handle names such as www.example.com too, add another rule or use an appropriate suffix match.

DOMAIN-SUFFIX: Matches the specified domain and its subdomains, making it suitable for applying the same action to a whole domain family. DOMAIN-SUFFIX,example.com,PROXY can match example.com and its subdomains, but not any domain that merely contains the string example.

DOMAIN-KEYWORD: Matches domains that contain a given string, usually more broadly than a suffix match. A short keyword may match domains you did not intend to include. Check the scope first and put more precise exception rules earlier in the list.

GEOIP: Classifies destination addresses using an IP geolocation database. For example, GEOIP,CN,DIRECT runs DIRECT for addresses in the matching category. This database result does not prove a user's location or a server's identity; changes to address geolocation and DNS results can also affect matching.

IP-CIDR / IP-CIDR6: Match IPv4 and IPv6 address ranges separately. The prefix length after the slash determines the range covered. Check which address family the destination actually uses; an IPv4 rule does not automatically cover the corresponding IPv6 address.

FINAL: Sets a fallback action for connections that did not match earlier rules, such as FINAL,PROXY. It usually belongs at the end of the rule list. If placed too early, it may prevent later, more specific rules from being evaluated.

PROXY / DIRECT / REJECT: Rule actions that route traffic through a proxy, connect directly, or reject the connection. The final exit for PROXY also depends on the active server or related policy settings. DIRECT bypasses that proxy path but does not guarantee the destination is reachable.

URL Rewrite: Matches request URLs using an expression and applies a rewrite or other configured handling. This is different from routing rules that select a connection path based on the destination. It depends on whether the request can be handled by the relevant mechanism; an expression will not necessarily apply to every encrypted request.

Subscriptions & servers

Import, testing, and data recovery

The entries below assume you already have your own subscription or server details. Get subscription URLs from your service provider. Treat authentication parameters in URLs, server passwords, and private keys as sensitive information.

Add Server: The screen for adding a server manually. Select a protocol first, then enter the corresponding details. Address, port, authentication, transport, and TLS are separate settings; do not guess values for fields that do not apply. Test the connection after saving.

SERVER: May refer to a server entry or an address field; check its position in the interface. A server address is usually a domain or IP, not a subscription URL. Pasting a full subscription URL into an address field does not import it through Subscribe.

Scan QR Code: The QR code scanner imports the information it recognizes. A QR code may contain a link to a single server or a subscription URL. Check the detected type and fields before saving. Do not share QR codes that contain authentication details publicly.

Latency: The response time measured under specified test conditions, often used to compare entries in the same test. A lower value does not mean consistently faster downloads or quicker responses from every website. Use the same test method before sorting; if a test times out, investigate network and authentication issues separately.

iCloud Sync: Syncs app-supported data when Apple device, account, and system permission requirements are met. It does not migrate every connection state or external service. After moving to a new device, check your subscription, active Config, and connection permissions, and keep a separate backup where needed.

Installation & system permissions

Purchase records, architecture, and permissions

Shadowrocket is available for iPhone, iPad, Mac, Windows, Android, and Linux. Get the iPhone and iPad versions from the App Store; see the App Store listing for system requirements. For other platforms, download installers from this site’s /dl/ directory. See the download page for links and installation steps.

Purchased: The App Store account section for viewing and redownloading purchased apps. When switching or reinstalling a device, check the purchase record using the original account. An app purchase does not restore a service provider subscription. To verify the app, check for developer Shadow Launch Technology Limited and app ID 932747118.

Apple Silicon / Intel: The two Mac processor architectures, each with a separate Shadowrocket DMG installer. Check the chip or processor in About This Mac before choosing. Architecture determines compatibility; follow the system permission steps if you see a prompt the first time you open the app.

SmartScreen: Windows app reputation warning. Seeing the prompt does not mean the installer has been checked. After confirming that the file came from this site’s download page, select More info → Run anyway in the prompt. If device management policies block this action, follow your organization’s requirements.

Privacy & Security: The macOS settings section for handling restrictions on opening an app for the first time. If you see an “unverified developer” warning, verify that the installer came from this site, then look for “Open Anyway.” If the app is reported as damaged, confirm it is in Applications, then follow the download page instructions to run xattr -cr /Applications/Shadowrocket.app. Do not run commands on files from unknown sources.

Allow unknown apps: Android grants installation permission separately to each source app, such as the browser used to download an apk or the file manager used to open it. Enable it only for the source you are using, and turn it off afterward if appropriate. If downloads do not work inside WeChat, open the download page in your system browser instead.

deb / rpm / AppImage: Linux offers several package formats. Choose deb or rpm based on your distribution’s package management system. AppImage files need execute permission before they can run. When using chmod +x, specify the AppImage file you actually downloaded. To install a deb file, you can use sudo apt install with the local file; see the download page for details.

For installation links, see the downloads for all platforms. To put these terms into practice, continue with the setup guide or the subscription and server management guide.