Shadowrocket Protocol Guide

01 / Connection Model

How connections work: identify the four layers

Choose a protocol to match the server, not based on assumptions about performance. A Shadowrocket connection entry typically specifies the server address, authentication, transport, and security settings; rules determine which requests use that entry. A mismatch in any layer can cause a connection timeout. Before making changes, keep a copy of the working configuration and confirm the details come from a service you already use or a server you manage. Don't fill in missing fields from memory.

Protocol, transport, and TLS are different things

Shadowsocks, VMess, VLESS, and Trojan use different protocol mechanisms. TCP, UDP, and WebSocket describe ways to carry data, while TLS provides encryption and authentication for a specific connection layer. An entry can use a protocol together with WebSocket and TLS; these are not mutually exclusive choices. Match each layer to the connection details you were given. Enabling TLS does not remove the need for protocol authentication, and entering a UUID does not mean the transport is configured correctly.

Server address and connection names also serve different purposes. Server usually specifies where the client connects; Port identifies the server port; SNI is the server name sent during the TLS handshake. WebSocket Host is part of the HTTP request, while Path identifies the server-defined route. These values may happen to match, or they may intentionally differ. They are not interchangeable fields. Keep imported or default values for fields not specified in your connection details rather than filling everything with the server address.

Global Routing determines whether traffic uses the entry

In Global Routing, Config applies the rules in the selected configuration. Proxy sends traffic handled by the client to the proxy policy, while Direct connects without a proxy. These modes change routing, not the server protocol. If switching to Proxy restores access but switching back to Config does not, check the rules and the policy actually matched before rebuilding the server entry. Likewise, successful access in Direct mode does not prove that a proxy connection was established.

DNS is a prerequisite across these layers. The client may need to resolve the server's domain first, while the destination website may require a separate lookup. If the server domain cannot be resolved, authentication has not started. If the destination domain resolves incorrectly, the connection entry itself may still work. Distinguish “can't find the server” from “can't reach a destination through the server.” Note the domain and the stage where the error occurs; not every DNS issue means the protocol is incompatible.

On iPhone and iPad, real-world performance also depends on wireless signal, network changes, background activity, and server load. Low latency means a particular test had a short round-trip time; it does not guarantee faster large-file transfers. A page loading quickly once does not prove lower battery use in standby. Compare protocols on the same device and network, at similar times, using the same destination. Record whether extra transport layers are enabled so the results can be reproduced.

This guide explains what settings do and the order in which to check them; it does not replace server configuration instructions. If an imported entry includes an option not covered here, first confirm whether the server requires it. Available fields vary by transport combination, so refer to what the app actually shows. Change one related group of settings at a time and record the original values so you can identify which layer caused any change in the next test.

02 / Shadowsocks

Shadowsocks: match the encryption method and password

Shadowsocks is designed to forward traffic with relatively little protocol overhead, combining encryption with data transfer. It is not a full device-networking protocol and does not identify users by certificate name. At a minimum, the address, port, encryption method, and password must all match the server. Entries with the same name do not necessarily share these settings. This is especially important after a server changes its port or authentication details: an old entry may remain but no longer work.

Method determines how the password is used

Method is not a performance setting you can change at will. Each method defines key derivation, data encapsulation, and integrity checks, so the client and server must support the same one. Modern authenticated encryption can protect data and detect tampering, but no method works with every server. Check the method against the details you were given. Don't substitute another method just because it belongs to the same algorithm family or has a longer-sounding name.

Use Password exactly as provided. Copying can introduce spaces, line breaks, or lookalike characters. Some protocol variants require a key with a specific encoding and length, so it cannot be re-entered as an ordinary text password. If an imported link shows a long password, preserve its structure; don't change its case or remove trailing symbols. If you need to confirm it, use the appropriate account or service management page. Never include the full password in a screenshot or public discussion.

Common AEAD methods include AES-GCM and the ChaCha20-Poly1305 family. Their performance depends on device hardware instructions, implementation, and traffic patterns, so the algorithm name alone cannot tell you which will always use less battery on iPhone. Processor efficiency can affect throughput during sustained transfers; for intermittent use, wake-ups and radio activity may matter more. Comparing methods is useful only when the server offers compatible options.

TCP working does not mean UDP is available

Shadowsocks can carry different types of destination traffic, but UDP forwarding requires support from the server, client settings, and current network. Websites can usually connect over TCP, while some real-time apps depend on UDP. So “the website loads, but another app still fails” is not a contradiction. First check whether that app needs UDP, then confirm the existing service allows it. A successful page load is not a substitute for testing UDP separately.

If your connection details include an extra plugin or transport setting, it is part of the complete connection. A matching base protocol name does not mean you can remove those settings and expect the entry to work. At the same time, don't add TLS, Host, or Path to a basic entry unless instructed. More fields add more conditions to match; they do not fix an incorrect address, expired password, or unreachable port.

When is a Shadowsocks entry worth keeping on iPhone?

If your existing Shadowsocks entry reliably handles everyday tasks, switching to a protocol with a more complex name does not guarantee a benefit. Record three kinds of experience: access after a fresh start, sustained transfers, and recovery after the screen locks. The first tests connection setup, the second sustained throughput, and the third reconnection after a network change. Each answers a different question; they should not be collapsed into a single “speed score.”

When a connection fails, first check whether the server domain resolves and the port is correct. Then verify Method and Password, followed by UDP or any extra transport requirements. If every destination fails through the same entry on the same network, check the endpoint and authentication first. If only a specific destination has a problem, check the rules, destination DNS, and the path from the server to that destination. Narrowing down the layers is more useful than repeatedly changing encryption methods.

When maintaining imported subscription entries, distinguish subscription updates from manual edits. An update may overwrite provider-managed settings or add similarly named entries. Before testing, make sure the selected entry is the one you just checked; otherwise, you may edit one entry and test another. If you need to keep custom settings, first understand how updates affect that type of entry and keep the original connection details for recovery.

03 / VMess · VLESS

VMess and VLESS: check authentication and transport separately

VMess and VLESS are often paired with different transport options, but they are not interchangeable names. VMess has its own authentication and data-protection mechanisms; VLESS keeps the protocol itself simpler and relies on a complementary security layer. These are different design choices, not a straightforward speed upgrade. Use the protocol configured on the existing server. Changing the protocol name while keeping only the UUID is not enough.

A UUID identifies a connection; it is not a complete configuration

A UUID often identifies the connection, but a valid UUID is only one part of authentication. Server, Port, transport, and related security settings must also match. If importing fails, re-entering the UUID while leaving an incorrect WebSocket Path unchanged will not help. Don't borrow a UUID from another entry to test: different identities may have different permissions, validity, or server endpoints.

VMess authentication involves time, so a significant device clock error can cause failures. Check that automatic date and time are enabled in system settings, and look for a time zone or manual clock error. A different displayed time zone does not necessarily mean the system clock is wrong; the actual time must be correct. Don't try to compensate by repeatedly changing old authentication settings. First make sure the device and server have a reliable time reference.

VLESS does not provide transport encryption equivalent to TLS on its own, so successful authentication does not mean the connection is adequately protected. Use a security combination specified by the existing service and supported by the client. If the details require TLS, check name validation and the certificate chain. Set any other security parameters exactly as specified. The fact that the app lets you save a blank field does not mean that configuration is suitable for the network.

Keep the meaning of WebSocket Host and Path intact

WebSocket can carry data over a defined connection path, sometimes through an HTTP request, TLS, or a reverse proxy. Host helps the endpoint identify the request; Path selects the server-side route. Neither is decorative. Paths are often case-sensitive, and the leading slash or query string may matter. Preserve the exact value from your connection details. If you receive a webpage or ordinary HTTP error, check the endpoint routing before the UUID.

Some connection details also specify flow control or multiplexing behavior. These settings are usually tied to the server implementation, protocol, and transport combination, so don't copy them from another entry. Adding a setting found online to an unrelated combination may break an otherwise working entry. Set an option only when the app exposes it and the server explicitly requires it—not because the field sounds advanced.

How to assess the cost of extra encapsulation

On mobile networks, extra handshakes can affect the first request, but their cost is spread across subsequent traffic once a persistent connection is established. The endpoint, path length, and server load may matter more than protocol overhead. When comparing VMess and VLESS, keep the server endpoint and transport combination as similar as possible. If the server locations also differ, the measured result cannot be attributed to the protocol, let alone generalized to other users.

Review settings in this order: protocol and identity, transport, security, then device time. Repeat the test with the same destination. If settings changed after a subscription update, confirm that the update caused the change before restoring old values. For a step-by-step timeout and clock check, see Three steps to troubleshoot connection failures. Don't change several layers at once before identifying the cause.

04 / Trojan · TLS

Trojan and TLS: verify the server's identity first

Trojan places proxy authentication and data transfer inside a TLS connection, using an established secure transport. Configuration must satisfy two sets of conditions: the TLS connection must be established correctly, and then the server must accept the protocol password. A correct password cannot fix a certificate name mismatch, and a successful TLS handshake does not prove Trojan authentication succeeded. Treating these as separate stages is key to understanding connection errors.

How Server, SNI, and the certificate name relate

Server is the network endpoint; SNI is the name sent by the client during the handshake; and the certificate verifies the server's identity. In some deployments, the endpoint address differs from the domain covered by the certificate, so the connection details specify SNI separately. Preserve that relationship rather than changing every name to the endpoint address for consistency. Certificate verification checks the expected identity and should not be skipped just because an address is reachable.

Name verification needs particular care when the endpoint is an IP address. A certificate issued for a domain does not automatically cover that IP. Use the name specified by the service rather than guessing. Conversely, don't enter a familiar domain as SNI unless the endpoint is configured to serve it. A name mismatch can terminate the connection before authentication, so changing Password at that point is unlikely to help.

Certificate verification also depends on the certificate chain, validity period, and device trust settings. A badly incorrect system clock can make a valid certificate appear not yet valid or expired. A server that fails to provide an intermediate certificate may also behave differently across devices. Record the name and verification stage shown in the error, then ask the server administrator to check the certificate deployment. Don't routinely bypass certificate validation; doing so weakens server identity checks.

What Password and ALPN each do

Password is protocol authentication data and must match the current server exactly. It is not the TLS certificate's private key and should not be entered as SNI, Host, or Path. Preserve every character when copying, but never include the actual value in public notes. If you need help, say whether the field has been checked and at what stage the error occurs; redact the full authentication details.

ALPN negotiates the application-layer protocol within TLS. Some deployments require a specific result; others use the default behavior. It is not a universal acceleration switch, and adding an arbitrary protocol name does not improve compatibility. If the connection details specify ALPN, preserve the value and order. If they do not and the imported field is blank, leave it unchanged until you confirm the server's requirements.

Handshakes, battery use, and connection reuse

The first TLS handshake requires network round trips and encryption, but that alone does not mean Trojan always uses more battery on iPhone. Persistent connections spread the handshake cost over time, and device support for encryption algorithms affects processing efficiency. Battery use also depends on retransmissions over weak signals, frequent network changes, and repeated reconnections. Separate occasional requests from sustained transfers when comparing, rather than using one startup delay to predict a full day's battery life.

If small requests work but large files often stall, check link quality, timeouts, and possible MTU issues. If every request fails during setup, check the endpoint and TLS first. If only certain domains fail, check Global Routing, rules, and destination DNS. A protocol's security layer does not make every subsequent issue a certificate problem; narrow it down based on where the error occurs.

Keep the original imported entry and test on a copy. If the server's certificate or endpoint changes, first check whether your existing details have been updated instead of accumulating entries that bypass validation. Once the connection works again, delete test copies you no longer need to avoid selecting a similarly named entry by mistake. Check purchase and system compatibility through the relevant App Store purchase verification guide; these are not determined by protocol settings.

05 / HTTP · SOCKS5

HTTP and SOCKS5: proxy support does not mean encryption

HTTP proxy and SOCKS5 are designed to let an app access a destination through an intermediary; they differ significantly from device-wide network tunnels. An HTTP proxy handles HTTP requests and connection tunnels, while SOCKS5 provides a more general way to request a connection to a destination. Choose based on the service your existing server actually provides, then check whether it includes secure transport. “Supports a proxy” does not mean the client-to-proxy connection is encrypted.

CONNECT with an HTTP proxy

An HTTP proxy can handle ordinary HTTP requests and use CONNECT to create a byte tunnel to a destination. When the destination uses HTTPS, TLS typically protects the website content between the client and destination. That is separate from whether the client-to-proxy connection also uses TLS. The proxy still needs information such as the destination, so seeing HTTPS in the browser does not tell you how the proxy endpoint handles authentication or metadata.

If the server provides an HTTP proxy endpoint secured with TLS, configure the client accordingly. Pointing a regular HTTP proxy entry at a port that expects TLS—or the other way around—can cause negotiation to fail. Port numbers are not standardized guarantees: different services can use the same number. Follow the server details rather than guessing the protocol from a commonly used port.

Whether Username and Password are required depends on the proxy service's authentication requirements. Blank fields may mean authentication is not required, or that the imported details are incomplete; don't assume either. If you get an authentication error, confirm that the account belongs to this endpoint, the characters are intact, and the authentication method is supported by the current setup. Don't enter a website login password as proxy credentials; they authenticate different things.

SOCKS5 connections and UDP limitations

SOCKS5 can specify a destination by domain name or IP address and supports different commands, including UDP ASSOCIATE for UDP forwarding. The protocol's support for UDP does not mean every server enables it or every network can carry it. For a real test, confirm that the server allows UDP, the client settings support the intended use, and the firewall and return path are working. The SOCKS5 label alone does not guarantee real-time apps will work.

Common SOCKS5 authentication methods are not encryption methods. Even if a server requires a username and password, assess client-to-endpoint transport protection separately. TLS in the destination app can protect that service's traffic, but it does not replace trust in the proxy endpoint. If an existing service is intended for a trusted internal network, follow that boundary; don't use its internal proxy address in an environment it was not designed for.

Check which side resolves domain names in the actual setup

A proxy request may carry a domain name or use an address the client has already resolved. The behavior depends on the app, rules, and DNS settings. So if internal domains or split DNS are failing, simply switching between HTTP and SOCKS5 may not help. First check which network should resolve the domain and whether the result is valid for the server, then trace the actual request path. If the endpoint is reachable but an internal site is not, the cause may be DNS or access permissions, not authentication.

There is no speed verdict for these protocols that applies to every iPhone or iPad. A simple handshake may reduce the cost of some short connections, but destination distance, proxy server capacity, and network quality still drive much of the experience. They are suitable when you already have a known working proxy service, understand its authentication and security requirements, and have a use case the service supports. Fewer settings alone do not make them replacements for every connection type.

For testing, choose a fixed destination you are authorized to access. Check authentication and TCP forwarding before testing other required services. If only internal resources fail, ask the service administrator to verify permissions, DNS, and access scope. Record the status and destination type for diagnostics, but do not include full account details or lists of internal addresses. Protocol choice determines how the client communicates with the endpoint; it does not grant access to resources you were not already allowed to use.

06 / WireGuard

WireGuard: understand keys, addresses, and routes together

WireGuard is designed for encrypted IP tunnels, using a compact cryptographic suite and a peer-based model. Unlike protocols that create a proxy connection for each destination, its configuration includes a local tunnel address, keys, and routing ranges as well as the server endpoint. Choosing WireGuard is not a matter of replacing a Password with a different field; it requires a complete set of matching tunnel settings provided by the server.

The roles of Private Key and Public Key

The client's Private Key proves its identity; the server's peer configuration stores the corresponding client Public Key. The Public Key in the client entry identifies the server peer. Swap these public keys and the expected handshake will fail, even if the address and port are correct. A Private Key is sensitive authentication data. Never include it in public screenshots, log attachments, or support requests. Before replacing it, check whether the server configuration must also be updated.

Some configurations also include a Preshared Key, adding a shared secret to the existing key exchange. Enter it only if the server requires and uses the same value; generating one yourself will not make the server accept it. If the server does not require it, keep the original setting. Key length, encoding, and characters are significant. Don't edit them manually or treat a similar-looking key as an interchangeable password.

Address, Endpoint, and Allowed IPs

Address is the tunnel address assigned to the local device; Endpoint is the network address and port used to reach the peer. The first is internal to the tunnel, the second is for the external connection. Don't put one in the other's field. Each device usually needs its own identity and address allocation. Copying the same client keys to multiple devices may cause the server to see endpoints switching between them, so they interfere with one another. Use the details assigned to each device by the existing service.

In WireGuard, Allowed IPs helps select a peer for routing and limits which source addresses that peer can accept. It is not a list of website domains and cannot use DOMAIN-SUFFIX syntax. Shadowrocket's Global Routing and configuration rules operate at another layer. A broad tunnel route does not guarantee that all traffic will use it. Verify separately how the app sends a request to the entry and how the tunnel handles IP packets.

The DNS option specifies DNS behavior, but whether it applies to a particular query also depends on the client's overall DNS settings. If the tunnel connects but you can reach IP addresses and not names, check DNS reachability and rules before rebuilding keys. If the tunnel includes private address ranges, check for overlap with the current Wi-Fi network. Overlapping addresses can send requests to the wrong interface, making it look like the destination server is not responding.

The trade-offs of MTU and Persistent Keepalive

WireGuard typically carries tunnel traffic over UDP. Additional encapsulation takes up packet space; an MTU that does not suit the actual path can allow small requests while stalling larger transfers. A larger MTU is not always faster, and a smaller one is not always more stable. Adjust it only in response to a reproducible symptom. Prefer a value provided by the server or already tested, record the original, and change it in small steps. Don't also change DNS and routing at the same time.

Persistent Keepalive can maintain a network address translation mapping when needed. It may improve reachability after idle periods, but periodic traffic also increases network activity on mobile devices. It is not required for every client setup, and a shorter interval is not necessarily more reliable. Set it according to the existing service's requirements and observed idle disconnects; it is not a universal battery-saving or speed setting.

WireGuard's compact design can reduce some processing overhead, but mobile battery use still depends on traffic volume, retransmissions, and keepalives. After switching between Wi-Fi and cellular, endpoint changes may also depend on network policy. Check key direction, Endpoint, tunnel address, routing range, and DNS in order. Focus on MTU testing only when you see packet-size-related symptoms. If your main need is access to an existing private network, first confirm which ranges the server allows rather than aiming for the broadest possible coverage.

07 / Hysteria2

Hysteria2: UDP paths and bandwidth settings

Hysteria2 uses mechanisms including QUIC to shape transport behavior for networks with variable latency, packet loss, and bandwidth. It makes different trade-offs from connections that rely mainly on TCP, but that does not mean it is faster on every network. First, the current network must reach the server's UDP endpoint. Then authentication, security, and bandwidth settings must match. If the endpoint is unreachable, there is no point adjusting speed expectations in the app.

Check the UDP endpoint before authentication

Server and Port should point to the actual endpoint in your existing connection details. Some networks allow common web traffic but restrict other UDP traffic, so being able to browse directly does not prove the Hysteria2 endpoint is reachable. If the same entry works on Wi-Fi but not cellular, keep the authentication settings unchanged and compare the network path first. Don't regenerate passwords every time you change networks; that confuses a network issue with an authentication issue.

Enter authentication details as required by the current server. If extra obfuscation settings are provided, they are separate from login authentication. Match the obfuscation type, related password, and enabled state as a set; turning on an option in the client alone is not enough. A missing required setting can cause the connection to fail at an earlier stage. If the imported entry has two secret fields for different purposes, don't set them to the same value just to simplify management.

The same TLS name and certificate verification principles described earlier apply here. An address used as the server endpoint is not automatically covered by its certificate; preserve the SNI specified by the service. QUIC uses UDP, but that does not make TLS identity checks optional or mean every handshake failure is caused by packet loss. Check clock, name, certificate chain, and authentication separately. The stage where the error occurs is more useful than a vague “timeout.”

A bandwidth setting is not a measured guarantee

Hysteria2 bandwidth settings can affect sending behavior and congestion-control choices, depending on the server and options exposed by the app. Distinguish upload from download and check the units. Entering an advertised ISP speed, wireless link rate, or one speed-test peak does not describe the path's sustainable capacity. A value far above the actual connection may cause more packet loss, retransmissions, and jitter, hurting interactive requests.

Upload bandwidth is particularly easy to overlook. Downloads still require acknowledgments and control traffic; if background tasks saturate the upload, performance can suffer even when download capacity is ample. Test when the network is relatively idle and check whether background syncing is running. If the service provides automatic handling or a recommended value, follow its guidance. Manually setting bandwidth is not a required optimization for every situation.

Measure throughput, latency, and battery use separately

A more aggressive transport strategy may help maintain throughput on some degraded links, but continuous packet activity, loss recovery, and user-space processing also consume resources. On iPhone, finishing a download sooner may shorten radio activity; repeated packet loss and retransmissions may instead increase heat and battery use. These effects pull in different directions, so the protocol name alone cannot tell you the outcome. Record task completion time, interactive responsiveness, and device behavior together.

When testing a large file, don't judge by the peak from the first few seconds. First confirm the transfer can finish, then check whether ordinary browsing or other interactions are affected while it runs. Higher throughput alongside slower short requests may indicate queue buildup or a saturated link; adjust the test conditions and bandwidth expectations. On mobile networks, signal changes cause available capacity to fluctuate, so one fixed value may not work everywhere.

If small requests work but larger transfers stall, check packet size, network loss, bandwidth settings, and server resources. If no connection can be established, check the endpoint and security layer first. If the entry fails only on one network, testing the same settings on another network is more informative than repeatedly changing parameters. Keep the combination that reliably handles the actual task, has a clear source for its settings, and produces reproducible results—not the one with the highest momentary reading.

08 / Selection · Diagnostics

Choosing and troubleshooting: test under consistent conditions

Start with combinations supported by the service you already have. If only one endpoint is available, configure it accurately. You can compare protocols only when your existing service offers multiple options. First meet the needs of your use case—TCP, UDP, private network ranges, and security—then compare reliability and ease of use. Don't drop required authentication to remove a setting, or add unsupported encapsulation just to use a particular protocol.

Narrow down options based on the task

For everyday browsing and app access, check initial connection time, ongoing reliability, and recovery after network changes. For sustained transfers, watch throughput and responsiveness under concurrent use. For an existing private network, check address allocation, destination ranges, and DNS. Test UDP-dependent services separately. Different tasks may suit different combinations, but only if the server already provides and permits them; the client cannot supply missing capabilities.

Use rules to confirm where test requests go

Before testing, set Global Routing to Config and confirm that the configuration you intend to edit is active. The snippet below demonstrates rule matching only; it contains no server details. PROXY must map to a valid proxy policy in the current configuration. Put specific domains before broader rules and use FINAL for all remaining traffic. If you want other requests to connect directly, adjust the final policy for your needs instead of copying it as-is.

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

Rules are evaluated from top to bottom, and the first match determines what happens next. GEOIP checks the address range; it does not infer location from a website's display language. The domains above are retained to illustrate syntax, not as speed-test targets. For verification, use a real resource you are authorized to access and can test consistently, then check the matched policy in the connection log. See rule keywords and matching scope for more syntax details, or how to route selected websites to proxy only certain sites.

Troubleshoot by the stage where the error occurs

Stage one is endpoint resolution and reachability: check Server, Port, and the current network, then confirm the server domain resolves to the expected address. Stage two is security and authentication: check the certificate name, device clock, password, UUID, or keys as required by the protocol. Stage three is routing and service access: check rules, DNS, UDP, destination permissions, and large transfers. If authentication has not started, don't rebuild identity details. If the endpoint is already established, don't keep changing the port.

Interpret Connectivity Test results according to what the test actually measures. It may show the time for a particular connection or request, but may not cover every path used by your real tasks, and does not measure sustained throughput. If a test passes but an app fails, check the domain, protocol, and policy used by the actual request. If a test fails while some tasks work, check whether the test destination itself is reachable. Use several related observations rather than treating one result as conclusive.

When comparing speed, change one variable per round. Use the same device and network, and keep test durations similar. Avoid background syncing, system updates, or other devices using bandwidth; note whether the test starts fresh, whether a connection is already established, and whether the signal is weak. Battery comparisons require a longer, repeatable fixed task. System battery statistics can offer clues, but they cannot attribute all network power use to a particular protocol. Interpret short-term heat in the context of how much data was transferred.

After testing, restore the Global Routing mode and rules you need for everyday use, remove test copies you no longer need, and keep a clear record of which original details match the working settings. See the setup guide for first-time connections and quick answers to common beginner questions. This guide explains protocol choices and settings; it does not manage servers or change what the App Store purchase includes. Check the App Store listing for system requirements.