Official Manual Defined Terms

Shadowrocket Glossary

Look up terms by interface label or rule keyword. The terms below remain in English; the explanations distinguish choosing how traffic is handled, entering connection details, and defining matching rules.

This guide assumes you already have your own subscription or server details. Get connection parameters from your service provider. This site does not provide, sell, or recommend servers or subscriptions.

First, distinguish the client from network services

The iPhone / iPad version costs $2.99 as a one-time App Store purchase. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. Buying the client does not buy a network service or create a subscription or server credentials.

See downloads for all platforms. For iPhone / iPad, check the App Store listing for system requirements. Get desktop and Android installers from this site at /dl/. See installation instructions for steps to allow the app to open the first time.

Interface and Controls

Global Routing

Overall traffic handling

Global Routing is where you choose how traffic is handled overall: Config, Proxy, or Direct. It determines whether traffic follows the configuration’s rules and is not the same as the PROXY or DIRECT policy on an individual rule. When troubleshooting, note the current mode before checking the rules. This helps avoid repeatedly changing rules that are not being used as expected in Proxy mode.

Config

Config mode

Selecting Config in Global Routing applies the rules in the active configuration. Rules are generally evaluated from top to bottom, and the first match determines the policy, so put specific conditions before broader ones. Config does not mean that all requests use a proxy; the route depends on the rules and the active configuration.

Proxy

Proxy mode

Selecting Proxy in Global Routing routes traffic handled by the client through the proxy. Use it to compare behavior with Config mode. If a request works in Proxy but fails in Config, check the rule that matches the request and its policy. This mode cannot correct a wrong password, port, or TLS setting, and it does not guarantee that every app’s traffic is handled.

Direct

Direct mode

Selecting Direct in Global Routing sends traffic handled by the client directly over the local network instead of through the selected proxy server. Use it to check whether the local network can reach a test target. Direct is a routing mode; it does not turn off the connection switch or delete subscriptions or configuration.

On Demand

Request a connection based on conditions

On Demand requests a connection when configured triggers, such as network conditions, are met. Available conditions depend on the settings shown in the current interface. It works with the manual connection switch but does not check whether a subscription is valid or fix server authentication failures. If the client connects unexpectedly, check both the On Demand conditions and the system’s VPN settings.

Add Server

Add a server manually

Add Server lets you enter server details field by field. First select the correct protocol, then enter the address, port, and authentication details. Required fields vary by protocol; passwords, UUIDs, and keys are not interchangeable. Check each field against the information from your service provider before saving. See the Add Server manual setup guide for the full steps.

Connectivity Test

Connectivity testing

Connectivity Test checks connection behavior under specified test conditions. Confirm the test target and method before interpreting the result. A response does not mean every website is reachable, and a failed test does not necessarily mean the server is entirely unavailable. Consider the actual request, current Global Routing mode, and logs together rather than relying on a single test.

Protocols

A protocol defines how both sides establish a connection, authenticate, and transmit data. A matching protocol name is only the starting point; transport, security, and authentication settings must also match the server.

Shadowsocks

Password and encryption method

A Shadowsocks connection typically requires the server address, port, password, and encryption method. The method must match the server. A password alone is not enough to connect, and changing the encryption method cannot fix an unknown configuration. If your service provider supplies additional transport parameters, use the original details and do not add options that were not requested.

VMess

Authentication and transport parameters

VMess uses details such as a UUID for authentication; connections may also require a transport type, path, Host, and TLS settings. A valid UUID does not mean the other fields can be left blank. In particular, distinguish the server address from the hostname used at the transport layer. An incorrect device clock can also affect authentication, so check that the system time is accurate when troubleshooting.

VLESS

User identity and security settings

VLESS is a proxy protocol that identifies users with a UUID. The required security and transport parameters depend on the server configuration. Do not assume the full set of VMess settings also applies to VLESS. After importing, check the protocol, address, port, and additional fields. Confirm any unknown fields against the original information from your service provider.

Trojan

Password authentication and TLS

Trojan commonly uses TLS and password authentication. Check the server address, port, password, and SNI. A resolvable address does not guarantee a successful TLS handshake; the certificate name must also match. If you see a certificate error, check the name, system time, and server certificate rather than routinely bypassing certificate verification.

Hysteria2

QUIC-based transport

Hysteria2 is based on QUIC and requires the local network and server to allow the corresponding UDP traffic. Depending on the configuration, you may also need TLS or obfuscation parameters in addition to the address, port, and authentication details. The protocol name does not guarantee a particular speed; performance also depends on packet loss, bandwidth, and server load.

WireGuard

Key pairs and tunnel addresses

WireGuard uses a key pair to establish a tunnel. PrivateKey, PublicKey, Endpoint, and address settings each serve a different purpose. PrivateKey is private authentication material; do not enter it as the server’s public key or share it publicly. Endpoint is the peer’s address and port. DNS, routing ranges, and MTU affect communication after the tunnel is established.

HTTP / SOCKS5

Proxy protocol types

HTTP and SOCKS5 are different proxy protocols. Select the type actually provided by the server; the same address and port do not make them interchangeable. The server determines whether a username and password are required. The protocol name alone does not guarantee encryption between the client and proxy server. Also distinguish the security of the proxy connection from HTTPS between the client and destination website.

Rule Keywords

A rule generally includes a match type, match value, and policy. The example below illustrates syntax only; example.com is not a usable server.

DOMAIN

Exact domain match

DOMAIN matches an exact domain. For example, DOMAIN,example.com,DIRECT applies to that domain itself. It does not automatically cover subdomains such as www.example.com; use DOMAIN-SUFFIX when you need to match subdomains. Enter a domain here, not a URL path or query string.

DOMAIN-SUFFIX

Match a domain and its subdomains

DOMAIN-SUFFIX matches a specified domain and its subdomains. For example, DOMAIN-SUFFIX,example.com,PROXY can match both example.com and www.example.com. It matches domain boundaries, not arbitrary strings. Put more specific rules first if a subdomain needs different handling.

DOMAIN-KEYWORD

Match a string in a domain

DOMAIN-KEYWORD checks whether a domain contains a specified string. It often matches more broadly than exact-domain and suffix rules. Short strings can catch unrelated domains, so avoid using a site abbreviation without checking its scope. If traffic is routed unexpectedly, check whether a broad keyword rule appears before a more precise rule.

GEOIP

Geolocation label for a destination IP

GEOIP matches labels in an IP geolocation database. For example, GEOIP,CN,DIRECT sends matching addresses to DIRECT. It checks the database’s classification of the destination IP, not the page language, company registration location, or content ownership. Database updates and a site’s content delivery network can change the result; add exact domain rules if needed.

IP-CIDR / IP-CIDR6

IPv4 and IPv6 address ranges

IP-CIDR is for IPv4 ranges, and IP-CIDR6 is for IPv6 ranges. The prefix length after the address determines the range. For example, IP-CIDR,192.0.2.0/24,DIRECT is a documentation example, not a single server address. Check which address family the destination uses to avoid handling IPv4 while missing IPv6.

FINAL

Fallback policy for unmatched requests

FINAL handles requests that did not match any earlier rule. For example, FINAL,PROXY sends the remaining requests through the proxy. It is usually placed at the end of the rule list; placing it too early prevents later rules from matching. Whether the fallback should be PROXY or DIRECT depends on the configuration’s purpose—there is no single answer for every network.

PROXY / DIRECT / REJECT

Policy applied when a rule matches

PROXY sends a request through a proxy, DIRECT connects directly, and REJECT denies the request. These values belong in a rule’s policy field. The uppercase policies are at a different level from the Proxy and Direct modes in Global Routing. REJECT can block requests based on conditions the rules can identify; it cannot distinguish every part of a page on the basis of a domain alone.

See keywords in a complete rule

In Config mode, check specific matches first, then geolocation rules, and FINAL last. The snippet below demonstrates rule order; do not replace your existing configuration with it without adapting it.

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

Subscriptions and Configuration

Subscribe

Import and update a server list

Subscribe imports and updates server entries from a subscription link. Get the link from your service provider. A subscription URL may contain account-identifying credentials; do not post it publicly or share an uncensored screenshot. An update can add, remove, or rename entries. A successful update only means the content was retrieved; it does not mean every entry can connect.

SERVER

A server entry

SERVER represents a server entry, typically containing an address, port, protocol, and authentication parameters. It is also commonly called a node in Chinese-language documentation. The display name is only a label: identical names do not mean the settings are identical, and different names do not necessarily mean the addresses differ. When organizing entries, distinguish subscription-generated records from manually added ones so you do not assume manual changes will persist after an update.

Config / [Rule]

Configuration files and rule sections

A configuration file can contain rules, DNS, and other settings. [Rule] marks the rule section; this is not the same as a subscription that only provides a server list. Having server entries does not mean you already have routing rules suited to your needs, and an imported configuration may not include server credentials. Before switching configurations, keep a copy of the current working setup and confirm that Global Routing is in the mode you need.

DNS

DNS resolution

DNS resolves domain names to IP addresses as part of the connection process; it is not proxy authentication. If a domain resolves but the site will not open, also check routing, TLS, the port, and server status. Before changing DNS, note the current settings and distinguish a failure to resolve the server address from a failure to resolve the destination website; these occur at different stages.

Latency

Measure response time

Latency is the time taken to receive a response under a particular test method. It depends on the test target, network conditions, and protocol handshake. Lower latency does not necessarily mean faster downloads, and a timeout may mean only that the test target is unreachable. For a meaningful comparison, use the same method and target under similar network conditions, then consider actual browsing performance.

App Store · Purchased

Redownload a purchased app

Use Purchased in the App Store to find apps bought with the same Apple ID. You can redownload the app on iPhone and iPad using the same purchase account. The iPhone / iPad version costs $2.99 as a one-time App Store purchase; the Mac, Windows, Android, and Linux versions are free and are not obtained through Purchased. If you cannot find the purchase, check the Apple ID and store region first. See the redownload guide.

To put these concepts into practice, continue with the user guide. For subscription updates, server entry management, and backups, see the server management manual.