Shadowrocket Official Manual

ShadowrocketGlossary

Look up terms by interface label, protocol, or rule syntax. English labels retain their in-app spelling, with explanations of their purpose and limitations. For step-by-step instructions, see the setup guide; for connection issues, see the troubleshooting guide.

INTERFACE & SWITCHES

Interface & Toggles

Start by checking where each setting appears. Similar English terms can refer to a page, an operating mode, or the result of a rule.

Home: The interface for viewing server entries and subscription groups, choosing a connection, and controlling the connection toggle. After importing, first confirm that the entry appears here, then check which one is selected. A successful import only means the parameters were saved; it does not confirm that the server is reachable. Once the connection toggle is on, use actual requests to verify that the network behaves as expected.

Global Routing: Settings that control the overall traffic mode, with Config, Proxy, and Direct as the available options. If rules do not seem to take effect, check this setting before rewriting them. The same configuration can produce different request paths in different modes. Global Routing and the connection toggle are separate controls: choosing a mode does not establish a connection.

Config / Proxy / Direct: The three modes mean following the configuration, routing all traffic through a proxy, or connecting directly. The interface labels remain Config, Proxy, and Direct. Use Config for rule-based routing. Temporarily switching to Proxy or Direct can help compare paths, but restore the original selection after testing. These capitalized interface labels are distinct from the all-caps policy keywords used in rules.

On Demand: Settings that trigger VPN connection behavior based on configuration conditions, controlling when a connection starts or resumes. They govern connection triggers, not which rule a domain matches. If a connection resumes after you turn it off manually, check the On Demand conditions instead of repeatedly toggling the connection.

Add Server: The entry point for creating a connection from existing server details. Select the protocol used by the server, then fill in its corresponding fields. Address, port, and authentication details are separate parameters; the display name alone cannot confirm that they are correct. Check the transport method, TLS, and other optional fields against the server information you already have rather than trying combinations at random.

Connectivity Test: Checks connectivity for an entry using the current network and selected test method. The result only reflects the path covered by that test; it does not prove that every website or transport method works. If the test passes but actual requests fail, check Global Routing, DNS, and the destination's rules. A timeout alone does not prove that the authentication details are wrong.

PROTOCOLS

Protocols

A protocol defines how a client communicates with a server. The same protocol name does not mean the parameters are identical; compare each field with the information you already have.

Shadowsocks: A protocol for carrying proxy traffic between a client and server. The server address, port, encryption method, and password must match. The encryption method is a protocol parameter; do not substitute one just because its name looks similar. If your existing details include additional transport settings, check those too. Changing the display name will not fix mismatched parameters.

VMess: A proxy protocol with an authentication mechanism. Connection details commonly include a user identifier, transport method, and security settings. A reachable server address only confirms part of the network path; mismatched authentication or transport parameters can still prevent a connection. An inaccurate device clock can also affect authentication, so make sure the system time is correct before checking other fields.

VLESS: A lightweight proxy protocol whose transport protection depends on the security layer configured. The protocol name alone does not tell you how the connection is protected. The user identifier, transport method, and related security parameters must match the server. If an imported entry still cannot connect, check these fields against the original server details instead of changing it to another protocol type.

Trojan: A proxy protocol commonly used with TLS. Authentication details and certificate settings both affect whether the connection succeeds. The server address, TLS name, and domain covered by the certificate may serve different purposes, so check them separately. If you see a certificate error, check the name, device time, and server certificate. Disabling verification should not be treated as a routine fix.

Hysteria2: A QUIC-based proxy protocol that relies on UDP for its underlying communication, so the network must allow the relevant UDP traffic. Its performance also depends on congestion, packet loss, server resources, and configuration; the protocol name alone cannot predict speed. If ordinary webpages load but this entry repeatedly times out, include UDP reachability in your checks.

WireGuard: A VPN protocol that creates an encrypted tunnel using keys. Configuration typically includes a local address, peer public key, endpoint, and allowed IP ranges. Establishing a tunnel does not automatically provide correct routes to every destination; check the routing ranges and DNS as well. A private key is sensitive: remove it and any other authentication material before sharing troubleshooting details.

RULE KEYWORDS

Rule Keywords

Rules are usually checked in order, and the first match determines the outcome. The keyword specifies the match condition; the policy at the end of the line specifies what happens when it matches.

DOMAIN: Matches an exact, fully qualified domain name and is useful when you want to target a single hostname. For example, DOMAIN,example.com,DIRECT applies to example.com and does not automatically cover its subdomains. If the destination also uses separate API or static asset domains, account for them separately; a match for the main page does not mean all of its requests take the same path.

DOMAIN-SUFFIX: Matches a domain suffix, covering the specified domain and its subdomains. For example, DOMAIN-SUFFIX,example.com,PROXY can match example.com and its subdomains, but not any hostname that merely contains the string example.com. Before adding a broad suffix rule, check whether more specific exceptions appear earlier.

DOMAIN-KEYWORD: Matches a specified string contained in a domain name, usually with a broader scope than an exact-domain or suffix match. It may match several unrelated domains, so short strings are not suitable as precise conditions. If traffic is routed unexpectedly, check for overly broad keyword rules and whether they appear before more specific rules.

GEOIP: Matches destination addresses based on location data in an IP geolocation database. Results depend on the database and the IP address returned by DNS. This is not the device's live location and does not guarantee the server's physical location. For distributed services, the resolved address may vary with the network, so do not rely on assumptions based on the domain name alone to determine whether a GEOIP rule should match.

IP-CIDR / IP-CIDR6: Matches IPv4 and IPv6 address ranges, respectively. The prefix length after the slash determines the range. For example, IP-CIDR,192.168.0.0/16,DIRECT describes an IPv4 private address range, not a single address. When writing address-range rules, consider IPv6 traffic too; checking IPv4 alone does not mean all requests are covered.

FINAL: A fallback rule used when none of the preceding rules match, usually placed at the end of the rule list. FINAL,DIRECT sends remaining requests directly, while FINAL,PROXY routes them through a proxy. Changing this rule can affect many requests not covered by specific rules, so understand the existing rules before adjusting the fallback policy.

PROXY / DIRECT / REJECT: Common rule policy keywords for routing through a proxy, connecting directly, or rejecting a request. PROXY at the end of a rule does not name a specific server; the connection used depends on the current selection and configuration. DIRECT does not mean all client processing stops. It describes the request's connection path, while DNS and other behavior still depend on the configuration.

DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,DIRECT

If an example request matches another rule first, a later rule of the same type will not determine its policy. For the full troubleshooting workflow, see rule routing and connection troubleshooting.

SUBSCRIPTION & CONFIGURATION

Subscriptions & Configuration

Subscriptions manage connection entries; configuration manages how traffic is handled. Importing, updating, selecting, and connecting are separate actions, and each result should be verified.

Server entry: A set of connection parameters saved in the client, typically including the server address, port, protocol, and authentication details, and sometimes transport and TLS settings. The display name is just a label for identification; it does not guarantee the server's location, speed, or availability. Before editing an entry created from a subscription, keep a record of the original, as a later subscription update may replace its parameters.

Config: As an interface label, Config is the configuration file used to manage rules and related network settings. As a Global Routing option, it means processing requests according to the current configuration. Configuration files and server subscriptions serve different purposes; updating one does not update the other. Importing a file does not mean it is in use, so confirm which one is currently selected when troubleshooting.

Subscription Update: Requests the subscription URL again and updates the corresponding entries based on the response. This is separate from updating Shadowrocket through the App Store. An update can fail while accessing the URL, receiving a server response, or recognizing the content; identify the stage rather than deleting the existing group. After updating, check the current selection again, especially if an entry was removed or its parameters changed.

See the subscription import and first connection guide →

DNS & NETWORK

DNS & Networking

Check domain resolution, server connectivity, and destination access separately. Success at one stage does not prove the others are working.

DNS: A system that resolves domain names to records such as IP addresses, often before a network request can connect. If resolution fails, the request may not have reached the destination connection stage. Even when resolution succeeds, the port may be unreachable, authentication may fail, or the destination service may return an error. Distinguish “no DNS result” from “a result is returned, but the connection fails”; each calls for different checks.

System DNS / Custom DNS: System DNS usually comes from the current network's resolver settings; Custom DNS is a resolver explicitly configured by the user. The configuration file, domain rules, and network environment can also affect the resolution path, so the address entered is not the whole story. After changing resolvers, retest the same destination and consider whether cached results are still being used.

DNS over HTTPS: A method for sending DNS queries over HTTPS, commonly abbreviated DoH. It changes how DNS queries are transported, not the proxy protocol. The resolver endpoint itself must be reachable, and its domain resolution and connection path must also work. Switching to DNS over HTTPS will not fix server authentication, rule selection, or destination website issues.

Latency / Timeout: Latency is the time taken to receive a response in a particular test, and its meaning depends on the test method. A timeout means the expected response was not received within the allotted time. Low latency does not imply high sustained throughput or prove that every destination is accessible. For meaningful comparisons, keep the test method, network, and destination the same; otherwise, the results are generally not directly comparable.

TCP / UDP: Two common transport-layer protocols: TCP provides an ordered, reliable byte stream; UDP sends datagrams, with reliability mechanisms potentially handled by higher-level protocols. A successful TCP test does not mean UDP also works on the same network; this distinction matters especially for transports such as QUIC. First identify which underlying protocol the current connection relies on, then choose what to test.

Open the troubleshooting guide → View frequently asked questions → Back to categories ↑