Shadowrocket
Protocol Reference and Configuration Guide

Start with the server’s requirements

A protocol defines how the client and server establish a connection, authenticate, and exchange data. It is not a cosmetic setting you can swap on its own. If a server accepts Shadowsocks and the client is set to Trojan, the connection will fail even if the address, port, and password look the same. Start by getting the complete server details and confirming the protocol, authentication fields, transport, and whether TLS is enabled. Subscriptions usually include this information; keep an original copy before making manual edits.

Speed here means the outcome of a complete visit, shaped by the path between your device and server, server load, the destination’s response, and client processing. A protocol can affect handshake count, encapsulation overhead, and recovery from packet loss, but it cannot provide a usable network path. Don’t treat a single Connectivity Test result as a measure of webpage load speed: the test target may differ from the site you visit, and a brief connection test won’t show congestion or fluctuations during sustained transfers.

Understand protocols, transports, and encryption

A protocol defines data formats and authentication. A transport carries bytes or packets, while an encryption layer protects the data in transit. Some combinations use TCP, others UDP; WebSocket is an optional transport method, and TLS is a security layer. A server configuration may include a protocol name, transport, and certificate domain—each describes a different layer. Knowing that a configuration uses VLESS or VMess isn’t enough to recreate it; check the corresponding transport and security settings too.

Rules belong to a separate chain of logic: first decide which policy a request should use, then send it through the selected server using its protocol. DOMAIN-SUFFIX does not change server authentication, and FINAL will not fix an incorrect TLS name. When something fails, check whether the request followed the expected policy, then verify the protocol connection. Mixing up these steps can lead to changing passwords when the request is actually going DIRECT, or repeatedly editing rules while authentication continues to fail.

On mobile, consider sustained power use—not just peak speed

On iPhone and iPad, battery use comes from more than encryption and decryption. Repeated wireless wakeups, retransmissions on weak signals, frequent handshakes, and maintaining background connections can all increase power use. The same protocol may behave differently on stable Wi-Fi and cellular networks with changing signal strength. For a fair comparison, keep the device, network, task, and test duration consistent, and note heat, loading delays, and reconnects. Don’t assign a fixed battery-efficiency ranking based on protocol names.

The fields shown in Shadowrocket depend on the selected type and related options. This guide explains what each field does; optional settings for one protocol aren’t automatically required for all the others. Match your configuration to the app’s current interface and the server details you have. If an extension isn’t available on the edit screen, don’t put it in the name or password field. If you’re new to the app, follow the setup guide to connect first, then add only the transport settings you need, changing one variable at a time.

Use the same sequence throughout the following sections: identify what the server actually supports, check the authentication details, review the transport and security layers, and then test a real task. If you only have an address and port but no protocol details, get the missing information first. Guessing the protocol or switching security options at random usually produces new failure symptoms rather than a diagnosis you can reproduce.

Design trade-off: handling proxy traffic with minimal overhead

Shadowsocks is designed to carry proxy traffic using a relatively simple format, placing the destination address and application data in an encrypted structure agreed on by both ends. Unlike a full network tunnel, it doesn’t require users to work with virtual subnets and routing addresses. Manual setup typically involves the server address, port, encryption method, and password. This simplicity makes basic configuration easier to understand, but different encryption methods, protocol generations, and extensions are not necessarily compatible.

A key difference between early stream ciphers and authenticated encryption is whether the recipient can verify data integrity as well as decrypt the content. AEAD combines encryption and authentication, so the client and server must agree on the specific method and key material. Check similar-looking names character by character; don’t infer compatibility from key length or algorithm family. If a configuration requires a particular key format, an arbitrary text password from another setup won’t work.

How address, method, and password fit together

The server address—a domain name or IP—is where the outer connection begins. The port identifies the service at that address. The encryption method determines how data is processed; the password or correctly formatted key supplies the material needed for encryption and authentication. Check these fields together. If the method is wrong, the underlying connection may still succeed, but the peer won’t accept the data. Reaching a port and passing protocol authentication are two different things.

After importing through Subscribe, check the server edit screen to confirm the type is Shadowsocks, then verify the method and password are complete. Some shared configurations are encoded; missing trailing characters, added line breaks, or extra decoding can change their contents. If reimporting the subscription fixes the issue but a manually edited entry still fails, compare the fields. Don’t overwrite other servers in the subscription with your manual edits.

Use extensions only when the server explicitly supports them. Some configurations include a plugin or additional encapsulation settings, but these are not required for every Shadowsocks connection. A working base protocol does not mean any extra transport will work; conversely, if the server requires an extension, the four basic fields won’t be enough. For an unfamiliar extension, confirm its name, options, and required settings. Don’t try to substitute TLS or a commonly used port.

Test TCP and UDP separately

Browsing a webpage tests the relevant app access path; it doesn’t prove UDP forwarding works. UDP can be affected by client options, server configuration, and intermediate networks. If your existing service supports UDP, test it with a task that actually uses UDP and check the policy applied to that request in the logs. If webpages work but a real-time app doesn’t, first confirm the app’s traffic type and forwarding support before changing protocols.

On mobile devices, Shadowsocks processing costs depend on the encryption implementation, data volume, and network conditions. Less encapsulation can reduce overhead, but on a weak signal, delays from retransmissions can far outweigh differences in encryption costs. Compare two configurations using the same task and observe sustained throughput and response consistency. A single small-packet test can’t prove that one setup is faster over time or uses less power in the background.

Choose Shadowsocks when your existing service provides complete Shadowsocks details and supports the forwarding your tasks need. If you need certificate identity checks, a specific transport, or network-layer address management, review the relevant sections based on what your server supports. Don’t add unrelated fields to a Shadowsocks entry. Once connected, keep the original details and, if problems return, first compare the network conditions and any changes to the entry.

Similar fields don’t make protocols interchangeable

VMess organizes user authentication and proxy data transfer within its own protocol structure. Configurations commonly use a UUID to identify the user and include related security settings. VLESS reduces some processing within the protocol itself and relies more on the outer layer for transport security. The two may use similar server addresses, UUIDs, and transport fields, but their message formats and server-side handling differ. Changing the type from VMess to VLESS in the edit screen does not convert a configuration.

This distinction helps explain why a connection can fail even when the fields look identical. A UUID is only part of the authentication material; it is not a universal login credential for every protocol. The server must be configured for the matching type and accept the corresponding transport and security combination. If your subscription lists entries of different types, treat them as separate connection details. Don’t combine a password, port, or transport field from one entry with another.

Keep the server address separate from the service name

The server address tells the client where to connect. The TLS service name is used for identity checks and the handshake, while the WebSocket Host and Path are part of the corresponding application-layer request. These values may match or differ, depending on the server deployment. When connecting to an IP address, for example, the certificate may still be issued to a domain name. Use the name specified by the server—not the IP as a substitute—and don’t treat the Path as part of the domain name.

A WebSocket Path usually begins with a slash and must match the path accepted by the server. Letter case, a trailing slash, or extra spaces can affect whether the request is accepted. Host is not a label for your own reference; a descriptive name won’t work in its place. When entering settings manually, make a checklist with the address, port, UUID, transport, TLS name, Host, and Path on separate lines, then match each item to the options available in the app.

VMess configurations may also include security settings; some fields in older documentation might not apply to the current service. VLESS extensions and transport combinations likewise require support from both client and server. Don’t copy defaults from an old guide into an existing configuration, or guess a substitute when an option isn’t visible. Keep the complete subscription entry where possible, and ask your own service provider which fields to use if needed.

More handshake layers can affect short tasks

A combination of TCP, TLS, and WebSocket usually requires each layer to be established in turn. For short tasks with little data, connection setup can take longer than the transfer itself; an already-established connection may feel different. So a combination that performs steadily during continuous use may not work as well on a cellular network with frequent reconnects. Compare the first page load, continued browsing, and recovery after a network change separately.

VMess authentication involves time, so a significant difference between the device clock and actual time can cause authentication errors. Check the system date and time before reviewing protocol fields; don’t assume the same explanation applies to a failed VLESS entry. Whether an existing connection survives a network change also depends on the underlying transport. TCP connections generally need to be reestablished when the path changes. Similar protocol names don’t guarantee the same recovery behavior.

Choose between these protocols based on the complete configuration your service provides, not just the names VMess and VLESS. If a connection fails without a clear error, check reachability, the TLS handshake, transport request, and authentication in order. Keep a reason for each conclusion. Otherwise, changing several fields at once might restore the connection by chance without revealing the cause.

The security layer is part of the connection

Trojan carries proxy requests and password authentication inside a TLS connection, using established TLS mechanisms to protect communication between the client and server. To understand a Trojan connection, check more than the password: the server certificate, service name, and handshake all matter. Until the outer secure connection is established, application-level authentication usually can’t proceed. Repeatedly changing the password won’t fix an expired certificate, name mismatch, or failed handshake negotiation.

This TLS connection protects the leg between your device and the proxy server. If the destination website uses HTTPS, it has a separate secure connection between the app and that site. These connections use different certificates and shouldn’t be confused. If the server connection succeeds but a website reports a certificate error, identify which layer produced the error. Changing the Trojan server name just because an error mentions TLS could break a configuration that was already correct.

The endpoint, SNI, and certificate each have a role

The address tells the client where to connect. SNI identifies the requested service during the handshake, and the certificate provides evidence of that service’s identity. In a simple deployment, they may all use the same domain; in other setups, they may differ. Match each field to the server details and make sure the certificate covers the expected service name. If the endpoint is an IP address, don’t assume the certificate must include that IP. Confirm the required TLS name first.

The password must match the server configuration exactly; leading or trailing spaces, line breaks, or substituted characters can cause authentication to fail. A port identifies a service endpoint, but a commonly used port doesn’t prove that Trojan is running there or that its certificate is configured correctly. If the server supports additional transport encapsulation, check the relevant fields. Don’t add a Path or Host from another transport to a standard Trojan entry unless the server explicitly requires it.

Some advanced fields, such as ALPN, affect application protocol negotiation or handshake details. They help the client and server agree on how to proceed; they are not universal speed switches. If your server details don’t specify them, keep the settings from the imported entry. Copying a value from elsewhere might establish the outer connection but reach the wrong service, or cause the server to reject the request. Start troubleshooting from a known-good combination and check differences one at a time.

Troubleshoot certificate errors by cause

For a certificate name mismatch, check whether the address and TLS name have been confused, and confirm that the server presents the expected certificate. If the certificate appears expired or not yet valid, check the device’s date and time, then confirm whether the server certificate needs updating. For a trust chain issue, the server should provide the required chain or use its established trust configuration. Disabling certificate verification removes the basis for checking identity and shouldn’t be a routine way to restore a connection.

On iOS, TLS processing and handshake costs are only part of the overall experience. With a stable connection carrying many requests, setup overhead is shared across them. On a mobile network with frequent disconnects, repeated handshakes add waiting and wireless activity. That doesn’t justify labeling Trojan as inherently faster or more power-hungry. Compare real tasks on the same network, distinguishing the initial connection time from data transfer after the connection is established.

Trojan is suitable when your existing service explicitly provides it along with complete certificate and authentication details. If the service offers multiple endpoints, start with an entry whose certificate details are clear and that’s reachable on your current network. If only one destination fails, check the rules and DNS before rebuilding the TLS configuration. If every destination fails and the logs point to the handshake, follow the checks in this section. For name resolution issues, see DNS settings and troubleshooting.

How the two general-purpose proxy types forward requests

HTTP proxies were designed to forward web requests and accept proxy requests over HTTP. For connections that need a tunnel, the common mechanism is CONNECT. SOCKS5 centers on generic destination addresses and connection requests instead of a particular type of web resource. The two protocols have different origins and uses, but the server must support the one you select. An address and port alone aren’t enough to choose between them.

An HTTP proxy, an HTTP proxy connection secured with TLS, and accessing an HTTPS website through an HTTP proxy are three different things. In the last case, the destination website’s HTTPS does not automatically protect all communication between the client and the proxy endpoint. SOCKS5 is not an encrypted tunnel either. To understand the security boundary, check whether the outer connection is protected and whether the application data itself uses end-to-end security.

Check authentication and transport security separately

Both types commonly use address, port, username, and password fields, but the server determines whether authentication is enabled and which methods it supports. A blank username doesn’t necessarily mean the service is anonymous, and entering arbitrary characters won’t make the server accept the request. If your details specify an authenticated proxy, split the fields according to its protocol. Don’t leave the username in the address field or mistake part of the port for the password.

SOCKS5 username and password authentication does not provide full data encryption. If the outer connection needs protection, confirm that the service actually provides the required security mechanism rather than looking for a similarly named toggle. The same applies to HTTP proxies: a valid certificate for the destination site only confirms the relevant checks for that connection; it doesn’t replace identity and transport checks for the proxy endpoint.

Where a destination domain is resolved—on the device or by the proxy—can affect results and troubleshooting. The client may pass a domain name to the proxy, or obtain an IP first, depending on the configuration and request. If access by domain fails but a test to a known address works, check the DNS path and how the destination appears in the logs before blaming authentication. These tests may use different resolution paths.

Don’t infer UDP support from the protocol name

The SOCKS5 standard includes mechanisms related to UDP, but actual use depends on the client implementation, server support, and network reachability. HTTP CONNECT is commonly used for TCP tunnels; don’t assume every UDP task can use the same endpoint. If your main tasks involve real-time audio or video, or other UDP requests, test the capabilities of that specific entry. Opening a webpage in a browser is not a complete test.

On iPhone and iPad, performance still depends on the connection path. A simple endpoint may perform directly on a particular network, or cause delays due to remote processing, connection limits, or authentication policies. A protocol’s age doesn’t mean it’s necessarily slower, and fewer fields don’t guarantee lower battery use. Frequent retries can create extra wireless activity and make even a simple configuration noticeably more demanding.

These protocols are suitable when you already have details for an HTTP or SOCKS5 service, or need to connect to a proxy endpoint on an established network. First confirm the trust boundary, then test the tasks and name resolution you need. Choosing either protocol alone does not protect data between your device and the remote endpoint. If the endpoint’s security layer is unclear, get the full service details instead of inferring end-to-end security from the browser’s address bar.

From proxy requests to network packets

WireGuard is designed to create network-layer tunnels with a compact protocol. It uses public keys to identify peers and UDP to carry encrypted packets. Unlike the proxy types above, which organize requests by destination, its configuration needs more than a server address: you must also specify the local tunnel address, peer key, and address ranges allowed through the route. Treating it as just another server type that needs a password can leave out essential fields.

WireGuard uses a fixed set of modern cryptographic algorithms, so there’s less need to choose from an algorithm menu. This reduces configuration complexity around algorithms but makes correct keys, addresses, and routing relationships especially important. A compact protocol doesn’t eliminate network setup. Even with correct keys, a mismatched tunnel address or allowed range can result in a successful handshake but no working traffic.

The local private key and peer public key are not interchangeable

The private key proves the local device’s identity and should be kept secure. The public key identifies the peer. The peer public key in the client entry must correspond to the private key actually used by the server, and the server must recognize the public key associated with this client. Both ends can’t simply generate unrelated values and expect a connection to work. If the configuration also uses a preshared key, it must match at both ends and be stored separately from the public and private keys.

Endpoint specifies the outer server address and port; tunnel Address specifies the local address inside the tunnel. They belong to different network layers. The endpoint might be a publicly reachable domain, while the tunnel address might come from a designated private subnet. Putting the endpoint IP in the tunnel address field generally won’t work. When importing existing details, keep the address prefix length and distinguish IPv4 from IPv6. Don’t keep only the part that looks like an IP address.

AllowedIPs associates address ranges with a peer and, in the full configuration, affects both routing and which source ranges are accepted. Shadowrocket also has its own rule policies, so server-side tunnel configuration and client-side traffic routing are separate constraints. Don’t broaden the address ranges just to send all traffic through the tunnel. When accessing a LAN or multiple private subnets, check the original network plan to determine which destinations need to be covered.

Keepalive and MTU are parameters with trade-offs

PersistentKeepalive can maintain mappings on intermediate devices when needed, which helps in some cases where a peer needs to reach the device after a period of inactivity. It isn’t a universal setting that becomes more reliable at shorter intervals: frequent keepalives send more packets and can increase wireless activity on mobile networks. Whether to use it and which value to set depend on the network and existing configuration. If reconnections only happen occasionally during active use, first check whether idle time and mapping expiry are actually involved.

MTU sets the size limit for a packet carried over the connection. Encapsulation adds overhead and changes the available space. If the path can’t handle larger packets, small requests may work while large pages or files stall. That symptom alone doesn’t prove an MTU issue; also check for packet loss and destination response problems. If you need to adjust MTU, keep the original value and test step by step on the same network and destination. Don’t change DNS, rules, and keys at the same time.

On iOS, WireGuard’s UDP transport and endpoint update mechanism can handle some network changes, but they can’t guarantee a seamless transition every time. UDP restrictions, mapping issues, routing, or the return path can still affect the connection. WireGuard is suitable when you already have complete, working tunnel details, especially if you need access to specific private subnets. Don’t infer a guaranteed speed or battery advantage from its compact design.

Designed with fluctuating network paths in mind

Hysteria2 uses QUIC over UDP to carry proxy traffic, with corresponding authentication and congestion control mechanisms. Its design takes high latency, packet loss, and fluctuating throughput into account, but that does not guarantee better performance on every network. First confirm that your current network allows the required UDP traffic. If the outer packets can’t reach the server, changing bandwidth or authentication settings won’t help.

QUIC can carry multiple streams over a single connection, reducing delivery delays caused by packet loss between streams in some cases. But all streams still share the available capacity of the path; congestion and weak wireless signals don’t go away. Hysteria2 also encapsulates app traffic in its own protocol, so a QUIC feature alone doesn’t mean every task will be faster. Evaluate how long real tasks take, not just peak throughput.

Enter authentication, TLS, and extra settings separately

Basic settings include the server address, port, authentication details, and any TLS settings required by the service. Match authentication details to your existing information; don’t reuse a password from another protocol just because it’s also a text string. The same TLS name guidance applies: the endpoint address and TLS service name may differ. Confirm that the server certificate covers the expected identity and keep verification enabled.

Some services also offer additional obfuscation settings, whose type and password must match at both ends. These are separate from user authentication. Don’t combine the two passwords or enable an option only on the client and expect the server to recognize it. If the subscription doesn’t include this setting, don’t treat it as a required performance option. For an unfamiliar extension, first check whether the current app supports it, then decide whether to use that connection entry.

Bandwidth settings are easy to mistake for a way to remove speed limits. In relevant modes, they may affect sending behavior or congestion control. Values should reflect the path’s reasonable capacity, not the speed you hope to reach. Setting them too high may exceed what the path can carry, causing queues, packet loss, or slower responses for other tasks. Setting them too low may limit throughput. Check whether a value is needed and what units it uses against the app interface and server details.

Consider speed and responsiveness together

On the same device, high throughput during a large download can make other pages respond more slowly due to queuing and competition for bandwidth. When evaluating Hysteria2, observe both sustained downloads and lightweight requests instead of keeping only the fastest result. If a setting increases peak throughput but makes pages stall more often, revert it and compare whether a more moderate value suits the current network better.

Changing mobile signal strength affects available throughput, so a fixed bandwidth estimate may not stay accurate. Don’t copy values from Wi-Fi directly to cellular or treat an idle-time test as representative of the whole day. Frequent retries, sustained high throughput, and wireless activity can all increase heat and battery use. If you need a long-running background connection, observe it over a typical usage period instead of relying on one fast test.

Use Hysteria2 when your existing service explicitly supports it and the current network can reliably carry its UDP traffic. If that condition isn’t met, test another working entry provided by your service rather than repeatedly increasing the bandwidth values. Frame the conclusion as “better for this network and task,” not as a universal protocol ranking based on one test.

Filter by required capabilities, not by protocol rankings

Start by listing the constraints of your task: which types your existing service supports, whether the current network allows TCP and UDP, whether you need access to private subnets, and whether the main task involves short page loads, sustained transfers, or real-time interaction. Complete details and reliable reachability matter more than a protocol’s reputation. If you have one working configuration, verify it first. If you have several entries, compare them under consistent conditions instead of piecing together settings to pursue a particular protocol name.

For everyday browsing, start with an existing entry that has complete fields and a reliable handshake. Focus on the first page load and how subsequent pages respond. For access to specific private networks, check the addresses and routes in your existing tunnel details, such as WireGuard. For UDP tasks, confirm that the protocol, server, and path all support them. During sustained transfers, watch throughput, delays to other requests, and device temperature; don’t judge by one peak result.

Check Global Routing before changing protocols

Global Routing has three modes: Config, Proxy, and Direct. Config applies policies from the current configuration; Proxy handles relevant traffic using a proxy policy; Direct connects without a proxy. Proxy can help you compare the effects of some rules, but it isn’t a complete diagnosis. Check the logs to confirm how each request was handled. When testing is done, restore the mode you normally use so a temporary troubleshooting setting doesn’t become a permanent policy.

This snippet illustrates rule syntax and order only; it isn’t a complete configuration and contains no server details. Rules are evaluated from top to bottom, with FINAL at the end to handle requests that didn’t match earlier rules. In an actual configuration, PROXY must correspond to an available policy. For configuration sections, see .conf file structure; for matching order, see custom rules and FINAL.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

Test one failing layer at a time

If nothing connects, first check whether the current network is usable, then verify the server address, port, and protocol type. Next, check whether the error points to TLS, authentication, or a timeout. If the connection succeeds but webpages don’t load, check DNS and the policy applied to the request. If only some tasks fail, check whether they need UDP, use a different destination, or expose issues with large packets or concurrent traffic. Don’t change DNS, disable verification, edit rules, and rebuild the server entry all at once.

Keep a brief test log with the network type, selected entry, Global Routing mode, task, and stage where the error occurred. When switching between Wi-Fi and cellular, leave all other settings unchanged. When comparing protocols, keep the destination and task as consistent as possible. Observe battery use over a reasonable period and note screen brightness, background tasks, and signal strength. A short-term percentage change can’t prove that a protocol inherently uses more power.

Before sharing logs or screenshots, remove subscription URLs, authentication passwords, private keys, and anything that could reproduce the configuration. Share only the relevant time range, destination type, and error description; don’t send the full configuration. If something changes after a subscription update, compare the type, address, transport, and authentication fields before changing local settings. Purchase restoration is a separate process; see restore a previous purchase. Rebuilding a protocol entry won’t restore a purchase.

Make the conclusion repeatable: confirm a working entry, keep the original details, restore your usual rules, and test a real task. If problems continue, see what to check when connected but offline or the FAQ. To repeat the import steps, return to the Quick Start Guide. That completes the protocol check: accurate details, a reachable path, the expected policy, and a successful test of the task.