Official Manual · Protocols

Shadowrocket protocol types
and connection settings

Choose a protocol supported by your server, then check identity, transport, and routing settings. Test speed and battery use; neither can be inferred from a protocol name alone.

This page is for users who already have a subscription or server details. It explains protocol design, how settings relate to one another, and which layer to check first when a connection fails. New users should start with the quick-start guide to import a configuration, set Global Routing, and verify the connection. Use this page when you need to understand settings or compare trade-offs.

Shadowrocket is available for iPhone, iPad, Mac, Windows, Android, and Linux. This page focuses on behavior on iOS. The fields shown and supported combinations depend on the current client and server. See downloads for all platforms for ways to get the app.

01 · Choosing a protocol and understanding connection layers

The server determines which protocol to use

Selecting a type in Add Server does not switch operating modes on an existing server entry. It tells the client which handshake, authentication, and data encapsulation to use. If the server runs Shadowsocks, the client must use compatible Shadowsocks settings; changing the type to Trojan will not make the server accept a different protocol. Get subscriptions from your service provider. After importing one, keep the provider's protocol and transport settings unless the server explicitly offers multiple connection methods.

Think of a connection as four layers when reviewing settings. First, the server address and port determine where the connection goes. Second, credentials such as a Password, UUID, or key establish identity. Third, the transport carries the connection, for example TCP, UDP, WebSocket, or TLS. Fourth, client routing determines which requests use that connection. Protocols may combine some of these layers, but they should still be checked separately when troubleshooting. A resolvable address does not mean the port is reachable; a reachable port does not mean authentication succeeds; and successful authentication does not guarantee that a request to its destination will work.

Assess speed, battery use, and security separately

Speed includes connection setup time, how quickly short requests finish, sustained download throughput, and recovery after network interruptions. A transport that performs well during a long download may not make web pages load faster. Mobile performance also depends on wireless signal, cellular scheduling, device temperature, and background activity. Battery use comes not only from cryptographic processing but also from keeping the radio active, reconnecting, maintaining sessions, and transferring extra data. You cannot rank protocols by battery efficiency based only on UDP or fewer layers, nor draw conclusions about an entire protocol from a single latency test.

Security also has distinct aspects: whether data is encrypted, whether the server's identity is verified, and whether credentials could be exposed. When TLS is used, check that certificate validation is enabled and the server name is correct. A protocol without built-in encryption may still run inside a verified encrypted channel. Conversely, an encryption setting does not remove the need to verify identity. The goal here is to understand an existing configuration, not to make security guarantees about a server based on its protocol name.

TypePrimary credentialsCheck first
ShadowsocksMethod、PasswordEncryption method and implementation compatibility
VMess / VLESSUUIDTransport and security-layer combination
TrojanPasswordTLS name and certificate validation
WireGuardKey pairPeer identity, address, and routing
Hysteria2Authentication detailsUDP reachability and QUIC handshake

Set up a fair comparison

If the server allows a choice, keep the device, network, destination, test time, and Global Routing setting the same when comparing two verified configurations. Change one variable at a time and save the original configuration so you can revert. Servers in different locations or under different loads can perform very differently even when they use the same protocol; attributing those differences to the protocol alone can lead you in the wrong direction. Recording where a connection fails is more useful than recording a single speed figure—for example, “handshake timed out,” “certificate validation failed,” or “destination lookup failed after connection.”

02 · Shadowsocks: Encryption Methods and Forwarding Limits

Design and key trade-offs

Shadowsocks is designed to send an app's destination address and data through an encrypted proxy connection for forwarding by a remote server. Its core does not typically cover full device network addressing or complex user management, so the basic settings are focused: server, port, encryption method, and password. Fewer fields make configuration simpler, but users still need to distinguish the password, encryption method, and optional extensions. A shorter settings list does not mean the server can infer the client's choices or that similarly named implementations are fully compatible.

To understand how Shadowsocks has evolved, distinguish earlier stream-cipher designs from authenticated encryption with associated data (AEAD) methods and later protocol extensions with different key requirements. AEAD protects both confidentiality and integrity, allowing the receiver to detect modified data or failed authentication. Methods differ in key length, message format, and implementation support. Do not replace the method in a subscription just because another option appears in the client. The client and server must agree, and some newer formats require key material of a specific length and encoding.

Address, Port, Method, and Password

Enter the server hostname or address in Address, and the port the service listens on in Port. Method is the encryption method, not the connection mode; Password is the credential used with that method, not a website login. When entering settings manually, check for leading or trailing spaces, line breaks, and look-alike characters introduced when copying. If the credential is encoded text, keep it exactly as provided. Do not decode, re-encode, or replace it with an easier-to-remember phrase. Save the original entry before making changes so you can tell whether a problem came from data entry or a server-side change.

If the entry includes a plugin or additional transport settings, treat them as part of the server configuration. Correct basic Shadowsocks settings alone do not guarantee that a connection using extensions will work. If fields are missing after importing a subscription, first check whether the original subscription format and current client support that combination; do not fill in values by guesswork. Confirm UDP forwarding support with the server provider separately. A working TCP website only shows that the TCP path works; it says nothing about real-time voice, games, or other UDP applications.

Assessing speed and battery use on iOS

With a stable network and adequate server resources, the basic Shadowsocks forwarding design may require fewer additional transport settings. Actual throughput still depends on the encryption implementation, device performance, round-trip time, and server egress. Do not choose an algorithm just because its name sounds lightweight; first ensure server compatibility and meet current security requirements. On a phone, sustained downloads usually keep the wireless radio active far longer than a brief handshake. Heavy background syncing can also make small differences between protocols meaningless.

Start troubleshooting by checking whether the same entry fails on different networks. If authentication fails everywhere, check Method and Password first. If it times out only on one network, check address resolution, port, and reachability. If the connection works but UDP apps do not, check server-side UDP forwarding, client support, and network-path restrictions. Do not cycle through every encryption option at random: that turns a known configuration into multiple unknowns and may trigger server-side limits on failed connections.

Keep using Shadowsocks when an existing service provides compatible settings, everyday requests work reliably, and you do not need network addressing or transport features specific to another protocol. If something goes wrong, identify whether the issue is in identity, transport, or routing before considering a different connection method. A protocol name is not a service-quality guarantee. A configuration that repeatedly reconnects on a weak cellular signal may use more battery than a more complex setup with a stable connection.

03 · VMess and VLESS: Configure Identity and Transport Separately

The two protocols address different needs

VMess combines user authentication with proxy request encapsulation. It uses information such as a UUID to identify the client and defines its own data-protection mechanisms. Its historical configurations include different authentication formats and compatibility fields, so older guides found online may not apply to current services. VLESS has a more minimal core, focused on identity and destination information, and typically relies on an external security layer to protect data in transit. The two protocols may use similar transport settings, but they are not interchangeable protocols that can be swapped by changing the type name.

A comparison of VMess and VLESS cannot stop at “VLESS has fewer fields, so it must be faster.” Connections may use TCP, WebSocket, or another supported transport, with TLS layered on top. The effect of these combinations on handshake count, proxy compatibility, and connection reuse can outweigh the size of the core request headers. Intermediate forwarding, concurrency limits, and idle timeouts also affect the experience. Confirm the complete setup before comparing the overhead of one protocol; that is the only way to make the comparison repeatable.

UUID, Security, and legacy compatibility fields

A UUID identifies the client and must be entered as provided; do not substitute a server note or account name. In VMess, fields such as Security describe data protection and are separate from outer TLS. If the provider's configuration includes a legacy field such as Alter ID, check it against the current setup instructions rather than copying a fixed value from an old guide. Some authentication processes are sensitive to time differences, so check that the device date and time are correct before resetting other settings.

VLESS does not provide the same built-in content encryption layer as VMess, making external security settings particularly important. If an entry includes Flow, it specifies a particular data-handling mode that must be supported by the server, transport, and client. It is not a common label that can be added to improve speed. Leave unspecified fields at their defaults or follow the server instructions. When adding an entry manually, first confirm that the required options are available. If the current client does not support a feature, ask the provider for a compatible configuration rather than substituting a similar-looking option.

WebSocket Host, Path, and TLS server name

WebSocket carries proxy data over a bidirectional connection established with an HTTP handshake, and may fit a server's existing reverse-proxy setup. Path is the request path; its capitalization, leading slash, and any additional segments may affect matching. Host identifies the host at the HTTP request layer. The TLS server name is used during the handshake and certificate identity check, so it belongs to a different layer. These values may happen to be the same or may be deliberately different in a particular deployment. Do not copy them between fields just because they all look like domain names.

A common mistake is to replace Host or the TLS server name with the server address. The network connection may then reach the machine, but the reverse proxy can route the request to the wrong service or the TLS handshake can fail certificate validation. Narrow down the issue in order: address, TLS, HTTP handshake, then protocol authentication. An HTTP status error usually means a request reached an HTTP service, but it does not prove proxy authentication succeeded. Check Path, Host, and reverse-proxy rules before changing the UUID to explain every failure.

Keeping a sensible setup on mobile

On iOS, an extra layer can add handshake and packet overhead, but it may also better match the server's network setup and result in a more reliable connection. After switching between Wi-Fi and cellular, test real requests to see whether an existing connection needs to be re-established and how long that takes. Do not rely only on the connection button's status. For details on related routing in configuration files, see how Config files are structured. Keep configuration rules and protocol settings conceptually separate.

04 · Trojan: TLS Identity Verification and Password Authentication

Built on established secure transport

Trojan carries proxy requests and authentication details inside a TLS connection, using TLS for encryption, integrity protection, and server identity verification. Break the checks into two steps: did the client connect to a TLS service with a valid certificate for the right name, and did the server accept the proxy credentials over that connection? Completing the TLS handshake does not mean the password is correct, and a correct password cannot fix a certificate name mismatch. Checking each layer separately helps avoid treating every problem as a server outage.

This design reuses established secure transport, but its reliability depends on correctly configured certificates and domain names. The certificate chain, validity period, device time, and server name can all affect the handshake. If the server offers other transport methods, use the combination it specifies; not every protocol that uses TLS is interchangeable. The provider should also explain whether the connection passes through an additional forwarding layer. If you only have a subscription entry, keeping its original settings is generally safer than removing fields based on a generic guide.

Address, SNI, and certificate validation

Address determines the actual connection destination. The TLS server name is usually sent as SNI and is also used to check the server's certificate identity. A deployment may connect to an address while verifying a domain name, provided the provider specifies that domain and the certificate covers it. SNI is not a password or a field for entering an arbitrary destination website. Entering a familiar domain will not create a valid connection; it may instead cause the server to present the wrong certificate or select the wrong backend.

If you see a certificate error, first check the device time, verification name, and whether the original entry is complete. Then ask whether the server needs to renew or complete its certificate chain. Do not disable certificate validation as a permanent fix: it can hide a connection to the wrong server or a replaced transport path. If the provider specifies a dedicated certificate trust setup, get the necessary verification details and confirm that the client supports it. “It connects” is not enough to show that identity verification is working as intended; a vanished error does not mean the underlying cause is fixed.

Password, ALPN, and connection reuse

Password is Trojan's authentication credential and must match the server setting exactly. It cannot be replaced with a TLS certificate or domain name. ALPN negotiates the application-layer protocol during the TLS handshake; set it manually only if the server requires it. Adding more protocol names usually does not improve speed and may change the server's selection. Connection-reuse options also require compatible client and server implementations. Reuse can reduce repeated connection setup, but multiple requests may then be affected by congestion on the same transport connection.

On iOS, the first request may wait for DNS resolution, TCP setup, the TLS handshake, and the proxy's connection to the destination. Handshake costs mainly affect new connections; network conditions and server capacity have more influence on sustained throughput. That is why opening the same site several times in quick succession can produce different results from reopening it after a long idle period. Distinguish cold starts from reused connections during testing. Avoid changing TLS settings and the test destination at the same time, or you will not know which change mattered.

Use Trojan when an existing service provides a TLS domain, a valid certificate, and matching credentials. If problems start after a certificate renewal, ask the provider to check the certificate chain and name first. If authentication alone fails, check the password and account status. Keeping certificate and authentication issues separate is more effective than changing every field, and makes it easier to send the provider a diagnostic report without sensitive credentials.

05 · HTTP and SOCKS5: What General-Purpose Proxies Can Do

Understanding the two protocols as app proxy interfaces

HTTP proxies were designed to relay HTTP requests. They can handle web requests in proxy format and use CONNECT to establish a tunnel to a destination host and port. SOCKS5 provides a more general connection-proxy interface: the client specifies a destination and requests forwarding without interpreting the application data. Both are common in organizational networks and existing proxy setups, but “general-purpose” does not mean they provide encryption, anonymity, access to every port, or full UDP support. Their capabilities depend on the proxy mode, server policy, and client implementation.

After an HTTP CONNECT tunnel is established, it can carry TLS data for the destination site. This protects application data between the client and the destination, not the connection between the client and the proxy server. Do not confuse the two. If the proxy entry itself uses TLS, its certificate must be verified separately. SOCKS5 does not provide transport encryption. Even when username and password authentication is enabled, authentication is not encryption. For use over public networks, confirm how the connection to the proxy is protected instead of assuming that a Password field provides encryption.

Proxy authentication and destination authentication are separate

When setting up HTTP or SOCKS5, Server, Port, Username, and Password refer to the proxy service, not the destination website. A proxy may require authentication or grant access based on the source address; follow the provider's instructions to determine whether the fields should be blank. If HTTP returns a proxy-authentication status, check the proxy account. If the destination website shows a login page, that is the website's own process. Changing the proxy password will not resolve a website account or access-permission issue.

Port restrictions are another common limitation. An HTTP proxy that permits CONNECT to common secure web ports may still block other ports. A SOCKS5 service may also restrict destinations or concurrent connections. If ordinary browsing works but an app does not, check the app's transport and destination port, then review the server policy. A connection toggle in the client does not guarantee compatibility with every app. UDP handling and long-lived connections must each be verified separately.

CheckHTTPSOCKS5
Typical request methodsHTTP requests, CONNECTRequests to connect to a destination
Encryption built into the protocolDistinguish standard and TLS proxy endpointsNo built-in transport encryption
UDPCannot be inferred from standard CONNECT supportRequires compatible forwarding support from the server and client
Name resolutionDepends on the request method and configurationCan carry a domain name; verify how it is handled

Where name resolution occurs and what to expect on iOS

SOCKS5 can carry a domain name or an already-resolved address in a request. Whether the client preserves the domain name for remote resolution depends on its settings and the source of the request. HTTP CONNECT can also specify a hostname; check logs and settings to confirm where it is resolved. If a locally resolved address cannot be reached from the proxy's exit network, the handshake may succeed while the destination request fails. Check the DNS path and destination address before concluding that HTTP or SOCKS5 is inherently unsuitable for the site.

On iOS, speed and battery use with either proxy still depend on the underlying connection and request pattern. A single forwarding layer does not guarantee low latency; congestion at the proxy or repeated authentication attempts can outweigh its simplicity. Choose these protocols when an existing service explicitly provides the interface and supports the transports your apps need. If you need reliable UDP sessions, verify the full setup before relying on it. For common connection problems, you can also search the FAQ by symptom.

06 · WireGuard: Keys, Addresses, and Routes Work Together

It handles network packets

WireGuard is designed as a lean encrypted network tunnel, using a fixed set of modern cryptographic algorithms and peer public keys to identify each end of the connection. Unlike application proxy protocols that create connections for individual destinations, it organizes configuration around interface addresses, peers, and routable address ranges. This means a server address and password alone are not enough: the client also needs its own key, an address inside the tunnel, and the correct peer details. The server must know the client's public key and have the required address and forwarding permissions configured.

A fixed cryptographic suite reduces algorithm negotiation and ambiguity, but does not resolve address conflicts, DNS, server forwarding, or network-path issues. WireGuard uses UDP, so it can be affected by address-translation mappings. After a mobile network change, the peer can recognize a new source based on authenticated packets, but recovery still depends on reachability, system scheduling, and keepalive settings. Roaming support does not mean every network switch will be interruption-free.

Private Key, Public Key, and Endpoint

The Private Key identifies this device and must not be shared in public discussions or screenshots. The Public Key lets the peer identify this device. The peer Public Key in the client entry identifies the server; the two keys are not interchangeable. If the configuration includes a Preshared Key, both ends must use the same additional secret. It is not a regular password that replaces the public/private key pair. Changing the local private key also changes its corresponding public key. If the server still has the old public key, the client cannot establish the expected communication even if it can send packets.

Endpoint is the server address and port used for outer UDP packets; it is different from the tunnel's Address. Address is the local address assigned inside the tunnel, usually with a prefix length, and should not be set to the server's public address. Allowed IPs associates a peer with destination ranges and participates in routing decisions; its exact effect also depends on how the client integrates WireGuard. If those ranges overlap with an existing local network, requests intended for local devices may be routed into the tunnel. Check client routing and the actual network addresses together.

DNS, MTU, and Persistent Keepalive

DNS specifies which server resolves names, but that server must itself be reachable through the network path. If the tunnel connects but you can reach addresses and not domain names, first check whether DNS requests can reach the specified server. MTU sets the maximum packet size. If it is too large, extra encapsulation or packet-handling limits along the path can cause some connections to stall. If it is too small, it increases packet fragmentation and processing overhead. When large downloads stall, adjust MTU based on evidence rather than treating one fixed value as universal.

Persistent Keepalive periodically sends data to maintain certain address-translation mappings. It is useful when inbound reachability needs to be preserved, but it does not boost speed. Shorter intervals can wake the mobile radio more often. If the provider supplies a value, start with it. Consider changing it only after confirming that mappings expire during idle periods and that keeping the session reachable is necessary. A meaningful battery comparison needs a sufficiently long idle test; otherwise, it measures active traffic but misses the effect of keepalives.

During troubleshooting, first check whether there was a recent handshake, then inspect bidirectional traffic and routing. With no handshake, check Endpoint, keys, and UDP reachability. If there is a handshake but destinations are unreachable, check Address, Allowed IPs, server forwarding, and DNS. A successful handshake does not prove that every destination range is configured correctly. For field mapping and common setup errors, see WireGuard settings explained. Always hide private keys and other credentials when sharing a configuration.

07 · Hysteria2: QUIC, Congestion Control, and Bandwidth Settings

Designed for paths with packet loss

Hysteria2 uses QUIC to carry proxy traffic over an encrypted connection running on UDP. QUIC can manage multiple streams in one connection, reducing the waiting between streams that can result from a single ordered transport. This does not make bandwidth, congestion windows, or wireless resources independent. Hysteria2 focuses on transport efficiency under challenging network conditions, but its suitability depends on the actual path. If the network blocks UDP, its other features cannot overcome the basic reachability requirement.

It is inaccurate to interpret “runs over UDP” as “does not retransmit.” QUIC's reliable streams handle acknowledgments, loss detection, and retransmission; TCP simply does not provide those mechanisms. Separate stream delivery does not eliminate the cost of packet loss: missing data still needs recovery, and congestion control still limits sending. QUIC may use a path more efficiently in some conditions, but can also be affected by UDP traffic shaping, a small path MTU, or device processing overhead. Choose based on task completion time and stability, not the transport name alone.

Authentication, TLS, and server compatibility

When adding a server manually, first confirm that the type is Hysteria2. Do not reuse authentication or transport fields from another protocol just because the names look similar. Server, port, credentials, and TLS name should come from the same valid configuration. The connection runs over QUIC and TLS, so certificate validation still matters. As with other TLS connections, distinguish the server address from the verification domain. If the provider requires additional obfuscation settings, both ends must match; these settings are not performance labels to fill in yourself.

If the handshake fails completely, test the original entry on another network. If it works on Wi-Fi but consistently fails on cellular, check UDP reachability, network policy, and the server listener before assuming the credentials have expired. If it fails at the same stage on every network, then check credentials, TLS name, and server status. Keep the error details from each test. “It won't open” does not distinguish blocked UDP from certificate, authentication, or destination-access failures, making it much harder to troubleshoot.

A higher bandwidth setting is not always better

Some deployments use bandwidth estimates to influence sending behavior; others use different congestion-control methods. The exact behavior depends on both implementations and server policy. If the settings allow an upload or download bandwidth value, use a sustainable real-world estimate and follow the provider's guidance rather than copying the theoretical peak from your internet plan. An estimate that is too high can cause queue buildup, more packet loss, and higher latency; one that is too low can limit throughput. The server may ignore, restrict, or override the client's request, so the setting is not the same as the final transfer rate.

On iOS, sustained high throughput keeps the wireless radio and processor active. Heat can also affect later tests. More aggressive sending does not necessarily save battery. Even if a file finishes sooner, compare the total time and battery used to complete the same task rather than momentary power draw. Test idle background use, foreground browsing, and sustained downloads separately. Results are not useful for comparing protocols if screen brightness, signal strength, or background sync changes during the test.

Hysteria2 is worth considering when an existing service provides it and the UDP path has been verified, especially for comparison with a stable setup on a lossy or variable network. If large transfers work but small requests are slow, check DNS, connection reuse, and congestion queues. If only larger packets fail, investigate the path MTU. Keep a verified fallback entry. It is more reliable than changing bandwidth, certificates, obfuscation, and routing at the same time, and helps distinguish protocol differences from configuration errors.

08 · Test Protocols and Rules for Your Use Case

Understand the three Global Routing modes first

The protocol determines how requests communicate with the server; Global Routing determines whether a request uses the proxy path. Config mode follows rules in the currently enabled configuration file. Proxy mode sends supported requests to the proxy policy. Direct mode connects directly. The proxy mode in the interface cannot override every app's networking behavior; requests remain subject to what the system and client can handle. Before comparing protocols, confirm that the test request reaches the selected server rather than matching a DIRECT rule first.

The following Shadowrocket configuration snippet illustrates rule order. It is not a complete configuration and contains no server credentials. Rules are matched from top to bottom: the example domain suffix uses PROXY, private address ranges use DIRECT, and remaining requests use the policy set by FINAL. Before copying it, consider your local network and access needs; changing the rule order can change the result. PROXY refers to a proxy policy, not a protocol, so it does not tell you whether the underlying connection uses Trojan or Shadowsocks.

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

Choose tests that match your tasks, not a single overall ranking

For everyday browsing, check DNS resolution, how long the first page takes to load, and a series of short requests. For video or file transfers, observe sustained throughput, stalls, and heat. For real-time apps that need UDP, verify full UDP support and test performance under changing network conditions. For long-lived background connections, include tests after locking the screen, during idle periods, and after switching networks. If the same server offers multiple protocols, keep the option with the clearest settings, complete identity verification, and reliable everyday performance. Consider alternatives only if they solve a specific problem, not just to change protocols.

Connectivity Test can help check a test destination or connection step, but results depend on the test method and target. One response-time figure cannot represent video throughput or UDP behavior in a real app. Test server connectivity, a destination confirmed to use the proxy, name resolution, and the actual task in sequence, recording where a failure occurs. A test target may be under maintenance or rate-limited, so cross-check with another known-accessible target if needed. Do not change the protocol and routing at the same time, or you will lose a useful baseline.

Report diagnostic details by failure stage

For a complete timeout, check the server address, port, network permissions, and TCP or UDP reachability. For TLS errors, check the device time, server name, and certificate. For authentication errors, verify that the UUID, password, or key matches the server. If connected but unable to reach destinations, check DNS, routing, server forwarding, and destination restrictions. If only some websites fail, first check rule matching and the destination address family instead of resetting the entire subscription. IPv4 and IPv6 reachability can differ, creating seemingly random failures; use the actual resolution results to investigate.

When contacting your service provider, include the protocol type, network used, failure stage, whether the issue reproduces on other networks, and a redacted description of the error. Do not send a full subscription URL, QR code, password, UUID, or private key; these may be enough to access your service. If screenshots are needed, show only relevant field names and error details. If updating a subscription overwrites your changes, first confirm whether the server settings have changed, then restore personal adjustments. Comparing a modified entry with a newly imported subscription can make old settings look like current server requirements.

After reviewing this guide, return to the quick-start guide and follow the steps to import, select, connect, and verify. To troubleshoot by symptom, see the FAQ. Record the conditions that reproduce a problem and keep a verified configuration. The right protocol choice is a set of settings that works for your current service and network, not a speed or battery ranking divorced from real-world conditions.