Official Guide · Glossary

Shadowrocket Terms & Concepts

Use the interface location to understand settings and the match conditions to understand rules. English names stay as written; explanations cover their purpose, scope and common points of confusion.

First, distinguish modes, rules and servers

Global Routing determines how traffic is handled overall, Rule determines which connections match which policies, and SERVER provides the parameters for an actual connection. These are separate layers. When troubleshooting, check the current mode first, then the matching rule, and finally the server details. This avoids changing settings at the wrong level.

Interface instructions on this page use iPhone and iPad as examples; option locations may differ on other platforms. Shadowrocket is a closed-source commercial app available across platforms: the iPhone/iPad version costs $2.99 as a one-time App Store purchase, while versions for Mac (Apple silicon and Intel), Windows, Android and Linux are free. See the download page for acquisition options and installers from /dl/. Check the App Store listing for the iPhone/iPad system requirements.

Interface & Controls

First, identify where a setting is located. Similar English terms may refer to an overall mode, a page name or a rule policy.

Global Routing

This is where you choose how traffic is handled overall. The three modes are Config, Proxy and Direct. The mode determines whether traffic is routed according to rules in the configuration, so check that Config is selected before changing a Rule. Switching modes does not change the server or fill in missing authentication details.

Config

In Global Routing, Config means connections are handled according to the rules in the current configuration. As a page name, Config is where you manage and select configuration files. First determine whether the term refers to a mode or the configuration management page. Importing a configuration file does not make it active automatically; check that it is selected before use.

Proxy

This is the proxy mode in Global Routing. Connections use the currently selected proxy instead of being evaluated against Config rules one by one. You can compare it with other modes as a controlled diagnostic test, but restore the intended mode afterward. Capitalized Proxy is an interface mode, not the all-caps PROXY policy in a rule.

Direct

This is the direct mode in Global Routing. Connections reach their destinations without using a proxy server. It can help you check whether the local network can reach the same destination, but it cannot fix DNS, destination service or routing problems. DIRECT in a rule applies only to connections that match that policy; its scope differs from this overall mode.

On Demand

This feature triggers VPN connection behavior based on preset network conditions, which should reflect the actual device environment. It determines when to start a connection; Rule determines how to handle traffic after the connection is established. If the connection repeatedly disconnects and reconnects after enabling it, check the relevant conditions first, then investigate whether the connection itself is failing.

Settings

This is the central entry point for client settings, separate from selecting a server in Home. Options and their locations vary; refer to the interface on your device rather than looking for buttons in another platform’s menus. During troubleshooting, change one setting at a time and note its original value so you can tell whether it affected the problem.

Protocols

A protocol defines how the client and server work together; it is not a speed tier. When importing, use the type and parameters supplied with your existing server.

Shadowsocks

This is a proxy protocol that requires the server address, port, password and encryption method to match. An address and port alone are usually not enough to establish a working connection, and encryption methods should not be swapped just because their names look similar. If your existing configuration includes additional transport parameters, check them against the original details instead of omitting them.

VMess

This proxy protocol uses parameters such as an identity for authentication. The protocol type, identity, transport method and TLS settings are separate fields; identifying a connection as VMess does not mean the other parameters are correct. When entering details manually, check the device time and server information too, so an authentication failure is not mistaken for a network outage.

VLESS

This is a proxy protocol. Authentication and transport security are separate considerations: the protocol name alone does not say whether TLS is enabled. The transport method, server name and other settings must still match the server. Don’t try to fix an existing entry by repeatedly switching protocol types; compare each field with the original configuration instead.

Trojan

This proxy protocol is commonly used with TLS. Check the authentication password, port and server name. TLS verification depends on factors such as the certificate and name; an IP address responding does not mean authentication and certificate checks will pass. If you see a certificate error, check the domain, device time and original parameters first rather than disabling verification to hide the cause.

Hysteria2

This QUIC-based proxy protocol depends on UDP network conditions. Authentication, TLS and other transport parameters must match the server; entering only a server address is not enough. If it fails on one network, keep the parameters unchanged and test on another network to help distinguish a network issue from a configuration problem.

WireGuard

This key-based tunneling protocol typically involves interface addresses, keys, peer endpoints and routing ranges. A private key is sensitive; remove it before sharing a configuration or troubleshooting screenshot. Establishing a tunnel does not guarantee access to the destination network; check address ranges, DNS and peer routing too.

HTTP / SOCKS5

These are two different proxy protocols; the same address does not make them interchangeable. Use the server’s information to determine whether authentication is required and which types of traffic are supported. The protocol name alone does not mean transport encryption is enabled, so HTTP or SOCKS5 labels are not enough to determine how the entire connection is protected.

Rule Keywords & Policies

Keywords describe what to match; policies describe what to do when a match is found. The examples below illustrate syntax only and are not a complete rule set you can use to replace an existing configuration.

Rule

A Rule usually includes a match type, match value and handling policy. Rules are generally checked from top to bottom, so a broad entry near the top may prevent a more specific one below from taking effect. When troubleshooting, check which rule matches first rather than just confirming that a domain appears in the list.

DOMAIN

This keyword matches an exact domain, for example DOMAIN,example.com,DIRECT. It does not automatically include all subdomains or treat a URL path as part of the domain. To match both a root domain and its subdomains, understand the scope of DOMAIN-SUFFIX before choosing the rule.

DOMAIN-SUFFIX

This keyword matches a specified domain and its subdomains, for example DOMAIN-SUFFIX,example.com,PROXY. It matches at domain suffix boundaries; it does not match any occurrence of the same text. Do not include https:// or a page path in the match value.

GEOIP

This keyword matches according to how the destination IP is classified in a geolocation database, for example GEOIP,CN,DIRECT. The match is based on the destination address used for the connection and the database, not the website’s language or registration details. Content delivery networks and changing IP allocations can affect classification, so this is not a definitive judgment of a website’s identity.

IP-CIDR / IP-CIDR6

These two keywords match 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 matches this IPv4 range. These rules match IP addresses; they do not automatically track every future address associated with a domain.

FINAL

This is a fallback entry used when none of the preceding rules match, for example FINAL,PROXY. It usually belongs at the end of the rule list; otherwise, it may catch connections before later rules can handle them. Changing it affects every destination not covered by an earlier rule, so check the intended routing behavior before editing.

PROXY

This is a proxy policy marker in a rule. Matching connections use the proxy route, but the result still depends on the current selection and whether the relevant server is available. A PROXY match does not guarantee the destination can be reached. This is a rule outcome, not the overall Proxy mode in Global Routing.

DIRECT

This is a direct policy marker in a rule. Matching connections reach their destinations without using a proxy server. The device still needs a working local network and suitable name resolution. A connection using DIRECT does not mean the client as a whole is in Direct mode; other connections may match different policies.

REJECT

This is a reject policy marker in a rule. It blocks matching connections. An overly broad match may also affect resources that normal pages depend on, so do not add a broad rule based on an ambiguous name. If some content disappears afterward, check the match records and rule order before deciding whether to narrow the scope.

Subscriptions & Configuration

Subscriptions update server entries; configurations describe how traffic is handled. Backups and sync address data storage. These serve different purposes and cannot replace one another.

Subscribe

This method retrieves and updates server entries using a subscription URL you already have; it is not a connection service. An update may change the list of entries, but it cannot fix an expired subscription, invalid authentication or server-side outage. Subscription URLs may contain access credentials, so don’t post them in comments, screenshots or shared documents.

SERVER

A server entry contains more than an address: it may include a port, protocol, authentication details and transport parameters. Names in the list are usually just labels for identification; they do not tell you the actual location or connection performance. Use the original details for your existing server when correcting parameters.

Add Server

This is the entry point for creating a server entry manually, for cases where you already have complete server details. Select the correct protocol type first, then enter the address, port and authentication parameters in their respective fields. Don’t reuse fields across different protocols. After saving, select the entry and test the connection; saving alone does not mean the server is available.

iCloud Sync

This syncs app-supported data across eligible devices using iCloud, subject to account and system requirements. Sync is not a separate backup; an accidental deletion or incorrect change may propagate to other devices. Before changing devices, save any configurations you need separately. After restoring, check the current Config, server entries and subscription status one by one.

Connections & Diagnostics

Identify what you’re testing before interpreting the result. Connection status, DNS resolution, response time and actual page access each answer a different question.

DNS

This is the process of resolving a domain name to an IP address, usually before connecting to the destination. A successful lookup does not guarantee a successful connection, and a failed connection does not necessarily point to DNS. Check the resolution result, current routing policy and destination service separately; don’t keep changing DNS settings just because a page won’t load.

Connectivity Test

This tool checks how an entry connects, with results depending on the selected test method, destination and network conditions. A response shows only that the test path returned a result at that time; it does not replace checking access to the actual service. Keep test conditions consistent when comparing entries, then try the destination you actually need after making your choice.

Latency

Latency is the response time measured under a particular set of test conditions—not download speed or throughput. A lower number does not mean every website will load faster; destination location, packet loss, congestion and server load also matter. One timeout is not enough to draw a conclusion. Test again under the same conditions and consider actual access as well.

Data

This page displays traffic logs or connection statistics; the specific details depend on the current interface. Client-side records and a service provider’s billing scope or reporting period may differ, so one total cannot be used to infer the other bill. For troubleshooting, focus on the relevant destination, time and policy. Remove private addresses and authentication details before sharing logs.

URL Rewrite

This configuration feature rewrites matching URLs. It is different from selecting a PROXY or DIRECT route: domain rules handle traffic routing, while URL Rewrite matches and processes request URLs. What can be handled over HTTPS depends on encryption and related configuration conditions; don’t assume one rewrite rule will apply to every request.

From terms to practical steps

For your first setup, follow the getting started tutorial to import your existing details, choose Global Routing and test the connection. For a step-by-step guide to permissions, configuration, traffic and ongoing maintenance, see the complete guide. If you’re dealing with a specific error, use the FAQ to narrow down the cause.

Suggested reading order: Global Routing → Config → Rule → PROXY / DIRECT / REJECT → DNS. Understand how these layers fit together before looking into protocol parameters to avoid mistaking a routing problem for an authentication issue.

Back to term categories ↑
Download Shadowrocket for all platforms