Shadowrocket Protocol Guide

01 · Protocol Selection & Connection Layers

Match the server's protocol type

Choosing a protocol is about compatibility, not ranking protocols by speed. A server address may listen on multiple ports, each using a different protocol. The same address does not mean authentication and transport settings are interchangeable. When selecting Type in Add Server, follow your existing server documentation or the details parsed from your subscription. Changing Shadowsocks to Trojan does not make the existing service support TLS; using VMess credentials with VLESS does not establish a connection. If subscription data conflicts with written instructions, first confirm that both refer to the same endpoint, then review the fields.

A connection can be understood in four layers. First, the current Wi-Fi or cellular network must be able to reach the server. Next comes the transport, such as TCP, UDP, or QUIC. Then come protocol authentication, encryption, and optional TLS. Finally, the request to its destination is handled according to routing rules. A timeout can occur at any layer, so it does not by itself mean the password is wrong. For example, an unreachable port prevents authentication from starting, while a certificate mismatch may occur before any destination request is sent. Breaking the process into layers narrows down what to check and helps avoid changing unrelated settings at the same time.

Compare speed and battery use under the same conditions

Connection speed includes three distinct measures: time to connect, time to the first response, and sustained throughput. DNS lookup, the handshake, and the first response are more noticeable when loading a short page. Large transfers depend more on link bandwidth, congestion control, and server load. A single Connectivity Test does not represent how every app will perform, nor can it be directly translated into download speed. When comparing existing endpoints, use the same device, network, test target, and roughly the same time. Record cold-start behavior separately from performance after the connection is established.

Battery use on iPhone and iPad cannot be judged by protocol name alone. Encryption uses processor resources, but an active wireless radio, packet loss and retransmissions, frequent handshakes, and overly frequent keepalives can also account for a significant share. On a weak signal, retransmitting data may affect battery life more than the algorithm itself. Keep screen brightness, foreground apps, and test duration similar, so screen use or background sync is not attributed to the protocol. Low latency and low battery use do not always go together; start by defining what matters for your use case.

If your existing server supports only one type, you don't need to enter a different protocol just to compare options. Choose the compatible type and check its required fields. Comparison is relevant only when your own server is configured with multiple endpoints. Transport and security options also depend on the server's specific setup and the app's current capabilities. If the interface does not offer a matching option, don't assume a similarly named setting is interchangeable. Keep the original instructions and confirm that the current client can represent all required settings.

02 · Shadowsocks Encryption & Forwarding

The trade-offs of a streamlined forwarding design

Shadowsocks was designed as a lightweight encrypted proxy that packages destination information and app data for processing by a remote server. Unlike a full network-layer tunnel, it handles proxy connections without assigning the device a complete set of tunnel addresses. Its simpler structure can make deployment and troubleshooting easier, but the phrase “encrypted proxy” alone does not establish every security property. Check the encryption method, authentication strength, UDP behavior, and any additional transport requirements against the server configuration.

To add a Shadowsocks server manually in Shadowrocket, select Shadowsocks, enter the server address and port, then check Method and Password. Method is a compatibility requirement, not a performance setting you can choose freely. If the two sides use different methods, the data cannot be interpreted correctly even when the password matches. When copying Password, check for leading or trailing spaces, line breaks, and capitalization. Don't use a subscription remark as the password or paste an entire encoded share string into the Password field. Import complete share details using the appropriate import method.

AEAD, compatibility, and additional settings

AEAD methods provide encryption and data integrity checks, allowing the recipient to detect altered or incorrectly authenticated data. This is different from simply making content unreadable, but similarly named algorithms are not necessarily compatible. Protocol variants may have additional requirements for keys, sessions, and user information. Keep the server's protocol type, algorithm name, and credentials together as a set. If a subscription includes extra fields, consult the original configuration instructions rather than deleting fields to make the form accept the entry.

Some existing configurations also include an additional transport component, hostname, or path. These are not universal Shadowsocks requirements; they need to match only when the server actually uses them. Additional components can change the outer data format and add handshake or configuration complexity, so don't enable them for a standard endpoint without a reason. If an import succeeds but the connection fails, check whether all required settings were preserved and whether the current client supports that combination. Seeing an entry only confirms that its data was parsed, not that the two sides completed protocol negotiation.

TCP, UDP, and behavior on iOS

If TCP requests work but an app that relies on UDP fails, investigate that separately. The server may not have UDP forwarding enabled, the network path may block UDP, or the current rules may not send that traffic to the expected policy. Repeatedly changing Password is unlikely to help. First confirm basic TCP forwarding with a regular webpage, then check the traffic type the app uses and the client logs. A successful webpage does not prove that every network function is available, and one failed test does not mean the entire protocol is unsuitable.

On iPhone and iPad, fewer additional layers usually mean simpler configuration, but actual throughput also depends on how efficiently the device handles the selected algorithm, server performance, and packet loss. Different devices can perform differently with the same algorithm, so results from another device may not apply. If sustained transfers are stable but the first page loads slowly, check DNS and connection setup first. If speeds fall only under heavy load, look at processor load and link limitations. Any algorithm change must also be supported by the server; changing it on the client alone is not enough.

Keep a working entry, then duplicate it to test one change at a time. Check Address, Port, Method, and Password first, then any additional settings that are actually in use, and finally verify UDP and routing. If a problem appears after a subscription update, compare the type and key fields before and after the update, but never share a complete entry containing credentials. For help importing and updating, see the Subscribe update guide. This section explains protocol fields and troubleshooting order; it does not provide the source of server settings.

03 · VMess & VLESS Authentication and Transport

Separate protocol identity from transport

VMess and VLESS commonly use a UUID as the user identifier, but they are not interchangeable formats that can be switched by changing Type alone. VMess incorporates authentication and data protection into its protocol design, and some authentication steps depend on a time window. A significantly incorrect system clock can therefore cause failures. VLESS has a more streamlined protocol structure; the base protocol does not encrypt the payload, so deployments typically rely on an accompanying security layer. These protocols differ in structure and responsibilities, not in a simple rule that one is always faster.

Get the UUID from your existing server configuration, preserving every character and separator. A randomly generated UUID in the correct format does not mean the server recognizes that user. Even with the right server address, port, and UUID, other settings still need checking: transport, TLS, Server Name, and path can all determine whether the connection works. If a subscription has several similar endpoints, don't combine the UUID from one entry with the path from another unless the server documentation explicitly says they belong to the same configuration.

TCP, WebSocket, and gRPC are different layers

The protocol determines how authentication and destination requests are represented; the transport determines how that data is carried. With WebSocket, the client must complete the required handshake, and settings such as Path and Host must match the server. With gRPC, check the service name and TLS settings. A standard TCP endpoint does not need a WebSocket Path. The same domain name does not prove that different transports use the same endpoint: a reverse proxy may route requests to different backends based on path, hostname, or service name.

Host, Server Name, and server address are not the same thing. The server address determines the connection target. The TLS Server Name is used for the name indication in the handshake and certificate matching. WebSocket Host is part of the application-layer request. Some deployments use the same value for all three, but that is a configuration choice, not a requirement for every setup. Enter each value as specified to distinguish between reaching the right server but the wrong backend and being unable to reach the server at all. Don't mask an error at one layer by arbitrarily changing a name.

Security settings and performance limits

VMess fields such as Security belong to its protocol configuration and are not equivalent to a TLS toggle. Some VLESS security or flow-control extensions apply only to specific deployment combinations. Don't enable an extension unless the server documentation says it is supported. If an imported entry contains an unfamiliar field, first check the corresponding setting in the current app and the server requirements, and keep the original entry intact. Deleting a field you don't recognize can make a complete configuration incompatible; replacing it with a “common value” is no more reliable than preserving the evidence.

Adding TLS or an application-layer transport usually adds handshakes and encapsulation, but that does not automatically mean lower overall speed. Persistent connections can spread handshake costs over time, and network intermediaries can affect how different transports perform. Frequent short connections are more likely to expose connection setup overhead; long transfers depend more on congestion and server load. On iOS, repeated failures and reconnects can use more battery than maintaining a stable connection. Fixing mismatched settings is more useful than starting by trying to remove an encapsulation layer.

For troubleshooting, first check that the device date and time are set automatically, then confirm the address and port are reachable. Next, check UUID, protocol security fields, transport, TLS, names, and paths layer by layer. If TLS succeeds but requests still fail, investigate authentication and backend routing rather than continuing to disable certificate checks. If the issue began after a subscription update, compare the transport fields. If every entry in the same group fails, first check the current network and shared DNS resolution. You can use this sequence alongside the connection timeout and failure notes.

04 · Trojan, HTTP, and SOCKS5: Key Differences

Trojan: authentication inside a TLS connection

Trojan handles proxy authentication and requests within a TLS connection, using established TLS mechanisms to protect the transport. Password and TLS settings have separate roles: the password identifies the user to the server, while certificate and name validation confirm the identity of the secure connection. A correct password does not mean certificate checks can be ignored, and a valid certificate does not guarantee that the account will authenticate. Treat these as two separate checks to distinguish handshake failures from authentication failures.

Server Name should match the server certificate and deployment requirements, not an arbitrary familiar domain. When the server address is an IP, the server may still require a domain name during the TLS handshake. This is a valid setup when specified by your existing server documentation: the connection target and validation name can differ. If a certificate error occurs, check the device time, spelling, certificate validity, and certificate chain. Ignoring validation to hide an error does not prove that you connected to the intended server and is not a good long-term fix.

HTTP: a proxy request does not mean the entire path is encrypted

HTTP proxies were designed to forward application-layer requests. For an HTTPS destination, CONNECT commonly establishes a byte tunnel to the destination. Distinguish between “the destination website uses HTTPS” and “the connection from the device to the proxy uses TLS”: the former protects the website session, while the latter protects the segment to the proxy. They are separate settings. If the proxy endpoint itself uses plain HTTP, an HTTPS destination URL does not mean the proxy credentials and endpoint metadata receive the same protection.

When configuring an HTTP proxy, check the server address, port, whether TLS is enabled, and whether Username and Password are required. Don't use a website login as proxy credentials, and don't enter the path portion of a URL as part of the address. If the server provides only a standard HTTP proxy, enabling TLS in the client will not upgrade it automatically. Conversely, a TLS-required endpoint will often fail early if contacted in plain text. Both sides must agree on how to interpret the first bytes sent.

SOCKS5: flexible forwarding without built-in payload encryption

SOCKS5 defines mechanisms for specifying destination addresses, negotiating authentication, and forwarding requests. It can handle domain names or IP addresses, and some deployments also support UDP. SOCKS5 does not provide general payload encryption, and Username and Password authentication is not the same as an encrypted channel. When using this type, understand what protections the existing network provides and whether the endpoint has another security layer. A password does not prove that data is encrypted, and a destination app's security does not protect every part of the connection.

SOCKS5 UDP support depends on the server, network path, and client working together. A server accepting TCP connections does not automatically mean it can forward UDP. Whether domains are resolved locally or remotely depends on the request format and client DNS settings. If a domain fails but a request to the same destination IP succeeds, check the resolution path first. If regular webpages work but a real-time app does not, check UDP and routing. Don't attribute every difference to authentication without enough evidence.

When comparing these three protocols on iPhone and iPad, start with the existing endpoints available to you. Trojan's TLS handshake, HTTP connection reuse, and SOCKS5 forwarding path can all affect the first response, but sustained speed depends mostly on the actual network path. If transport protection matters, check the endpoint's security layer rather than relying on the protocol label. For an app that needs UDP, verify end-to-end support first. If you have only one set of working settings, entering them correctly matters more than switching between incompatible types.

05 · WireGuard Keys, Addresses, and MTU

Network-layer tunnels versus proxy endpoints

WireGuard is designed as a streamlined network-layer tunnel. It identifies peers with public and private keys and carries protected data over UDP. Unlike proxy protocols that mainly forward app connections, WireGuard also involves tunnel addresses and routing ranges. Its configuration is more than “server plus password”: the device needs its own key identity, the peer must register the corresponding public key, and both sides need to know which addresses should use the tunnel. In addition to authentication and reachability, you must check address assignment and routing.

PrivateKey is the private key for the current endpoint and should remain in trusted local configuration. In the peer settings, PublicKey usually means the remote peer's public key, not a place to copy the local private key. The public key derived from the local private key must be authorized by the remote peer; the remote public key identifies the other end of the connection. If the keys are reversed or the server has not registered the local identity, a correct address and port won't establish a valid session. PresharedKey is optional additional shared material. Enter it only if both sides are configured to use it; don't invent a value for one side.

Address, Endpoint, and routing ranges

Address is the address assigned to the local endpoint inside the tunnel, usually with a prefix length. Endpoint is the reachable remote address and port on the outer network. They belong to different layers, so don't use a public server address as the tunnel address. If the existing configuration includes both IPv4 and IPv6 addresses, preserve both prefixes. Arbitrarily changing a tunnel address can cause conflicts with other endpoints or place it outside the range allowed by the remote peer, resulting in a handshake without the expected data returning.

In the WireGuard model, AllowedIPs relates both to permitted tunnel address ranges and peer selection; the exact presentation in the client depends on the interface. In Shadowrocket, also distinguish the endpoint's internal routing range from the app's overall rule policy. The former determines how the tunnel handles addresses; the latter determines which requests are assigned to that policy. A broad address range allowed by the remote peer does not mean every device request automatically goes through the tunnel. First confirm that the rules select the request, then check the return path and destination routing inside the tunnel.

How MTU, DNS, and keepalives interact

MTU is the maximum packet size an interface can carry. Tunnel encapsulation adds overhead, and if the path cannot handle larger packets correctly, small requests may work while larger responses stall. A modest MTU reduction can be a useful test, but no single value works for every network. Record the original value, change one step at a time, and retest the same destination. A value that is too low increases packet count and processing overhead. If the underlying issue is DNS or destination routing, changing MTU usually won't help.

DNS settings determine how domain names resolve to addresses; they do not automatically fix incorrect tunnel routing. If the DNS server is inside the tunnel, the route to it must be available first. Otherwise, you can end up with domains failing while some IP addresses remain reachable. Keepalives maintain a NAT mapping when needed; they do not increase bandwidth. Frequent keepalives can wake a mobile device's wireless radio more often, while infrequent ones may leave the first request waiting for the path to be re-established. Follow the network conditions and server recommendations.

When checking WireGuard, evaluate the handshake, traffic counters, and actual requests separately. A handshake shows that the peer identity and outer path worked together at that time; it does not prove that a destination inside the tunnel is reachable. If sent traffic increases but received traffic does not, continue checking remote routing, allowed addresses, and the return path. A brief recovery after switching from Wi-Fi to cellular does not immediately point to a key problem. For more detail on field relationships and configuration limits, see the WireGuard settings notes. Back up a working configuration before making changes.

06 · Hysteria2 QUIC and Bandwidth Settings

A connection carried over UDP

Hysteria2 builds proxy transport on QUIC. QUIC implements secure handshakes, connection management, and reliable data streams over UDP, so “the outer layer uses UDP” does not mean all inner data is sent unreliably. One design choice is to handle connection management and congestion control within this transport. It may behave differently from TCP-based transport under some packet-loss or latency conditions, but results still depend on network policies, server bandwidth, and implementation settings. The name alone cannot guarantee speed.

Use Hysteria2 only if your existing server actually provides that protocol. You can't reuse an address and password from another type or assume that similarly named protocol generations are interchangeable. First check Type, server address, and UDP port, then verify authentication and TLS settings. Some deployments also include additional obfuscation settings; use them only when the server has enabled them. Missing such a field can cause data to be dropped before a normal handshake begins, resulting in repeated timeouts without a clear authentication error.

UDP reachability matters more than webpage connectivity

Being able to load a regular webpage on the current Wi-Fi does not prove that UDP traffic can reach the target port. Some networks treat UDP differently from TCP, and some paths handle sustained UDP traffic differently. If Hysteria2 times out on one network but works with the same settings on another, check outer UDP reachability before changing the password. Test with the same entry so network changes and setting changes are not mixed together, making it impossible to tell what actually affected the result.

TLS still requires the correct name and certificate validation. Address determines where data is sent; Server Name is used for the handshake's name indication and identity check. If the server certificate covers only a domain, you may need to provide that name even when connecting by IP. Confirm the value in your existing configuration. An incorrect device date, a domain resolving to the wrong endpoint, or an incomplete certificate chain can all cause handshake problems. QUIC does not bypass these security requirements, and disabling validation does not prove that other settings are correct.

Bandwidth settings are not a speed boost

Interpret bandwidth fields according to the current implementation, server configuration, and your actual network connection. Some congestion-control modes use bandwidth information to determine how to send data. Entering a value well above the available capacity can increase queuing, packet loss, and retransmissions, making interactive requests slower. Don't treat a speed claim in a subscription note as an accurate setting or use your home connection's advertised speed for a cellular network. Units matter too: bits per second and bytes per second are not interchangeable. Check the field descriptions for upload and download direction.

If downloads are fast but webpage clicks feel sluggish, excessive queuing during congestion may be the cause, rather than slow DNS. Stop the large transfer and retest short requests to see whether the difference disappears, then check bandwidth and congestion settings against the server's recommendations. Higher throughput increases wireless and processor activity, while repeated retransmissions on a poor path also use more power. Compare the time and total energy needed to complete the same task rather than a momentary battery change or a single peak-speed figure.

After a switch in mobile networks, QUIC connection identifiers and path migration do not guarantee that every app session will continue uninterrupted. Recovery also depends on client behavior, remote state, NAT mappings, and the app's own timeout. Record connection results before and after switching networks; don't rely only on whether the connection icon remains visible. If only this protocol fails on one network while other existing endpoints work, keep that comparison as evidence. If all types fail, check the basic network, name resolution, and global routing before focusing further on QUIC settings.

07 · Configuration Fields & Layered Troubleshooting

Keep the original details, then check the imported entry

After importing a subscription or share link, check “parsed successfully” separately from “connection works.” Parsing only means the client recognized the data format. A working connection also depends on the network, authentication, security layer, and forwarding. First confirm that Type matches the source, then check the address, port, and key credentials, followed by transport extensions. If a field is missing, don't immediately fill it with a commonly used value; verify it against your existing configuration. Changing the display name or importing again cannot make an unsupported combination compatible.

A common source of confusion is treating several different “names” as one field. A remark is only for local identification; Address determines the connection target; Server Name is used for TLS; Host may affect the application-layer endpoint; and Path or service name selects a transport backend. These values may be the same or different for a given endpoint. In troubleshooting notes, record each value's role rather than just writing “domain is correct.” When a server uses multiple backends, a TCP connection to the same address can still reach the wrong service if the name or path is incorrect.

Narrow down the issue by where it fails

If only one entry fails, first check its specific address, credentials, and transport settings. If several entries in the same group fail, check their shared domain, credential source, and server status. If all entries fail on one network, compare with another known-working network. If they fail on every network, also check the current Config, device time, and system connection status. These decision points are more useful than repeatedly running tests because each step helps determine whether the issue is with one endpoint, shared settings, or the device environment.

A timeout means the expected result did not arrive within the allotted time; it does not directly indicate a wrong password. A connection refusal may mean no service is listening on the target port, or it may come from network-path handling. A certificate error points to TLS identity validation; an authentication error calls for checking protocol credentials. Interpret each message in context instead of treating every English-language error as the same issue. Keep details about the stage before the error for your own review, but when describing it to others, share only the type, network conditions, and a redacted error. Never publish complete credentials.

Separate a successful test from successful real-world use

A Connectivity Test result depends on the method and target used. It does not prove that every website, UDP app, or rule is working. If the test succeeds but browsing fails, check DNS for the actual domain, the matched policy, and the destination's response. If only one app fails, check whether it uses different domains or transport. Seeing the connection switch turned on only indicates the system tunnel state; it does not verify a request to its destination. Test a real request to at least one known destination before deciding that the configuration works.

DNS troubleshooting requires attention to dependencies. If the server address is a domain name, it usually needs to resolve before the connection can be established. Resolution of destination websites may depend on the current Config. If the DNS server is reachable only inside the tunnel and there is no working bootstrap resolution path, a dependency loop can occur. First confirm that the server domain resolves correctly, then check destination domains and request policies. Don't change every DNS setting at once. See the DNS setup guide for instructions.

Finish by creating a minimal retest record: current network, protocol type, actual test destination, failure stage, and the single field changed. After each change, retest the same destination and decide whether to keep or revert the change based on the result. A subscription retrieval failure and authentication failure on one endpoint are different issues. For the former, check whether the subscription URL is valid and whether it can be retrieved; see subscription troubleshooting. Once you've checked the settings, continue to the next section to investigate rules and connection triggers if only specific requests still fail.

08 · Global Routing, Rules & On Demand

After confirming the protocol works, check policy selection

The protocol determines how to connect to the remote server; Global Routing determines how requests are handled. These are separate functions. Config selects a policy according to the current configuration's rules. Proxy can temporarily narrow down rule-related variables once you understand what it means, while Direct sends traffic directly. During troubleshooting, note the current mode and check the actual route taken by a request. Otherwise, testing a remote protocol under Direct can lead to the wrong conclusion. Restore Config after testing; temporary changes affect later comparisons and may also change local network access.

Rules usually match in order, with more specific conditions placed appropriately and FINAL handling requests that matched no earlier rule. DOMAIN-SUFFIX matches a domain suffix; IP-CIDR matches an address range; GEOIP checks an address against the corresponding geographic data. They match different things and cannot be substituted just because a destination website name looks similar. PROXY, DIRECT, and REJECT specify different handling outcomes. The policy named in a rule must also resolve correctly in the current configuration. Confirm the actual result in the request log instead of guessing from the rule's position in the list.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

This .conf snippet illustrates rule syntax and ordering; it is not a complete configuration. example.com is an example domain, DIRECT for a private address range means direct access, GEOIP results depend on the relevant data, and FINAL handles anything not matched earlier. Before applying it to your own Config, confirm the existing policies, DNS, and local network ranges. Don't replace your entire configuration with the example. In particular, the example's geographic rule is not a recommendation for everyone, and changing rules will not fix an incorrect Password or TLS name.

On Demand controls when a connection is triggered

On Demand triggers system connection behavior based on the network and other configured conditions. It does not determine which protocol handles each request. Configure Wi-Fi, Cellular, and domain conditions according to the current interface and available rules; some conditions affect whether a connection starts, while others also depend on name resolution. First make sure a manual connection is stable, then add trigger conditions. If the manual connection already fails, automatic triggers will repeat the same problem and make it harder to diagnose.

For Wi-Fi conditions, check the exact SSID and make sure a similar-looking name is not a different network. For cellular conditions, test both switching from Wi-Fi to cellular and switching back. When multiple conditions are configured, check their order and fallback actions so a broad condition does not match before a more specific one. If the connection returns after you turn it off manually, a condition may have been met again; the switch may not be faulty. Check the On Demand rules before investigating the system connection state.

Test for your use case, not by protocol name

For everyday browsing, focus on time to the first response, reliable resolution, and recovery after idle periods. For sustained transfers, check effective throughput, queuing, and retransmissions. For apps that depend on UDP, first confirm end-to-end forwarding. For resources inside a tunnel, check WireGuard addresses and routing. If you have multiple compatible endpoints, testing each against these goals is more useful than declaring one protocol “faster overall.” Differences between servers using the same protocol may be greater than differences between protocol names. Note which variables you cannot control when comparing results.

Battery testing should reflect real tasks. Have two existing configurations handle similar amounts of data for similar lengths of time, and compare both sustained foreground use and idle periods. Record background sync, signal strength, and screen time, since they affect results. If idle battery use increases noticeably, check for repeated failed connections, overly frequent keepalives, or On Demand conditions that keep changing. If the increase occurs only during sustained transfers, consider throughput and processor load. Don't infer a fixed battery-use ranking for protocols from one system battery report.

Confirm three things: the entry's Type matches the server, real requests use the expected policy, and connection behavior after network changes follows the On Demand settings. Save a working configuration before adding automation conditions one at a time. For specific connection-trigger scenarios, see the Wi-Fi and Cellular trigger rules notes. To review the full process of adding, connecting, and verifying an entry, return to the setup guide. This protocol guide explains differences and troubleshooting boundaries; use your existing server details as the source for configuration values.