Shadowrocket Protocol Guide
and Settings Reference

1. Choosing a Protocol and Understanding Connection Layers

Choose a protocol based on how the server actually accepts connections, not on its name. In Shadowrocket, the protocol type must match your existing subscription or server details. Changing the type for the same address does not give the server new capabilities. You can compare options only when the server offers multiple connection methods and provides complete authentication and transport settings for each. After importing a configuration, check the type, address, and port first. Then decide whether any additional settings need adjustment; don't start by guessing based on speed.

Break a Connection into Four Layers

The first layer is the local network: the device connects over Wi-Fi or cellular and must be able to reach the server. The second is transport and security, which determine whether the connection uses TCP or UDP, whether it establishes TLS, and whether it uses an additional transport such as WebSocket. The third layer handles protocol authentication and data formats, such as a password, UUID, or public-key identity. The fourth is client routing and destination access: it determines whether requests use the selected server or connect directly. If an earlier layer fails, changing a later one usually won't help.

This is why getting a response in a test is not the same as being able to load a website. A test may check only whether an address is reachable, a handshake succeeds, or a specified target responds. It may not cover all destinations, DNS, UDP, or app behavior. Conversely, a single failed test may be caused by the test target itself being unreachable. When comparing results, note the test method, current network, selected server, and routing mode. Don't compare figures gathered under different conditions.

Compare Speed and Battery Use Under the Same Conditions

Protocol overhead is only one factor in speed. Server distance, available bandwidth, congestion, packet loss, destination limits, and the device's wireless signal can all matter more than differences between encryption algorithms. To distinguish handshake time from sustained throughput, test the same destination on the same network at roughly the same time, checking the initial load, sustained transfer, and recovery after idle. A brief speed test doesn't represent sustained performance, and when several tasks run at once, don't attribute the overall experience to a single protocol.

On iPhone and iPad, battery use is also affected by wireless radio activity, background reconnections, signal quality, screen brightness, and foreground tasks. Fewer handshakes don't automatically mean better battery life, and more persistent connections don't necessarily use more power. The impact depends on how often you connect and how often the network changes. For a useful comparison, keep usage time similar, note whether the device gets warm or connections drop frequently, and distinguish app traffic from system background activity. This guide doesn't rank protocols by speed or battery use.

When organizing configurations, keep a verified working baseline, change one setting at a time, and record why you changed it. Authentication details, subscription URLs, and private keys are sensitive; don't include them in public screenshots or diagnostic text. Use the fields shown in the current app and the server's documentation. If an option isn't available, don't substitute a similarly named field. System requirements are as listed on the App Store page; device compatibility and protocol performance are separate considerations.

2. Shadowsocks: Shared Keys and Encryption Methods

Shadowsocks was designed as a relatively lightweight proxy relay, using a pre-shared password and encryption method to protect communications. It isn't a TLS protocol that verifies server identity through a certificate chain, so the password and encryption method must both match for the connection to work. Its trade-off is a compact proxy protocol, leaving server deployment, account management, and transport extensions to supporting implementations. Treat the server-provided settings as a complete set, not just an address and password.

Address, Port, Password, and Method

The address can be a domain name or IP address; the domain must resolve correctly before a connection can be made. The port identifies a specific server entry, and different ports on the same address may use different passwords or encryption methods. Enter the Password exactly as provided, watching for leading or trailing spaces, line breaks, and full-width characters. Method determines how data is encrypted; it isn't a performance setting to switch at will. Methods with similar names aren't interchangeable.

Earlier stream-cipher designs and later AEAD designs differ in integrity protection, packet handling, replay protection, and other respects. AEAD handles confidentiality and authentication together, but an algorithm name alone doesn't tell you whether a method is right for your server. Methods may also have different key-format requirements; some require key material that shouldn't be treated like an ordinary password. If an imported configuration contains a long string, first confirm whether it's a key in the required format. Don't shorten it, re-encode it, or replace it with an easy-to-remember phrase.

Import links often include the type, encryption method, password, address, and port, but a compact link doesn't mean any of those details are optional. Start with the original configuration as your baseline. If you need to check it manually, compare each field shown in the app. The remark is just a local label; it doesn't prove anything about the protocol or server capabilities. A subscription name that mentions a network method isn't a reason to enable extra transport options. Use the configuration fields and server documentation to confirm the actual connection method.

UDP and Additional Transports Aren't Automatically Compatible

For real-time audio or video, or other UDP traffic, check the client settings, server forwarding capabilities, and intervening network. Being able to load TCP websites doesn't prove that the UDP path works. If the configuration includes additional transport or obfuscation settings, those are part of the agreement between client and server. Matching only the main protocol while missing those settings can result in a connection with no useful data. Set additional options only as supported by the current app; don't combine settings from a different server entry.

Shadowsocks resource use depends on the method implementation, device hardware, data volume, and number of connections. A lightweight transport may reduce some processing, but over a weak or lossy signal, wireless transmission and retries may still dominate. To tell whether performance is protocol-related, compare available entries on the same server. Don't attribute a difference between servers on different routes or under different loads to the algorithm. If the device warms up after a brief download, wireless and storage activity may be the main cause.

Use a consistent troubleshooting order: check the address and port, confirm Method and Password, check any additional transport settings, then test UDP and routing. If a previously working subscription stops working, check whether an update changed its fields and whether the server details are still valid. Don't change several options at once. Record manual changes before refreshing a subscription, since a refresh may overwrite entries. If you need to repeat the setup process, see Getting Started. This chapter explains the fields rather than repeating the full setup.

3. VMess and VLESS: Authentication, Transport, and Security

VMess and VLESS often use a UUID as user identity material, but they aren't two modes of the same protocol. VMess handles authentication and data protection within its own design, while VLESS has a more streamlined protocol structure and is typically paired with a separate secure transport layer. Their design trade-offs differ: one handles more within the protocol, while the other delegates some responsibilities to an outer layer. Having a UUID doesn't mean you can switch between the two types.

A Valid UUID Only Confirms the Format

Keep every UUID character and separator intact. When copying, don't include quotation marks, spaces, or explanatory text. Even a correctly formatted UUID may be rejected if the account is disabled, the identity doesn't match, or the connection entry is configured differently. For VMess, also check that the device clock is accurate; a significant time difference can affect authentication. Automatic date and time can help rule this out. If the connection still fails once the clock is correct, check the server settings instead of repeatedly resetting the time.

Set VMess encryption options according to the server's requirements. Don't assume that using TLS externally determines the internal settings. Older configurations may include different additional fields, so after importing, check what the current app actually parsed. If an older field is missing or has a default value, refer to the original configuration and server documentation rather than combining settings from different eras based on online examples. Protocol evolution and server-specific differences can't be identified by field names alone.

Transport Determines How the Connection Reaches the Protocol Entry

The same protocol can use different transports. Direct TCP, WebSocket, and other supported transports have different requirements for the path, host name, and server handling. With WebSocket, settings such as Path and Host may affect request routing, so preserve the exact slashes, capitalization, and characters in the path. If the server uses an intermediate proxy to route connections, connecting to the same address and port doesn't guarantee that you'll reach the right service.

The TLS Server Name is used for Server Name Indication during the handshake and related identity checks. The transport-layer Host may be used for routing an upper-layer request. They may be the same in some configurations, but they serve different purposes; don't mechanically copy one value into the other when a field is missing. Certificate verification isn't something to turn off as a first troubleshooting step. Check for a name mismatch, an invalid certificate chain, or an incorrect system clock first; disabling verification can turn a clear error into a hidden risk.

VLESS's Simpler Design Doesn't Mean You Can Skip Outer-Layer Security

VLESS doesn't handle data encryption in the same way as VMess; actual protection depends on the complete security setup. If your existing configuration specifies TLS or other supported security settings, keep them together. Some servers also require a specific Flow or related security fields. These affect protocol behavior on both sides; they're not ordinary notes. Check the current Shadowrocket interface and existing configuration to see which fields and combinations are supported. Don't clear a field just to make an error disappear.

On iOS, the wait before the first request may include DNS lookup, an outer connection, and a security handshake. Sustained transfers are more affected by path quality and congestion. Additional encapsulation can add processing overhead, but may be required for the server entry to work. If connections are slow after idle but transfers are otherwise normal, look at reconnections and network changes. If they're slow throughout, compare the network path and server load. Choose between VMess and VLESS based on whether your existing server entry can be matched completely, not on a single label such as “streamlined” or “encrypted.”

4. Trojan, HTTP, and SOCKS5: Different Security Boundaries

Trojan relies on TLS as an important outer layer and combines it with its own authentication and forwarding format. HTTP and SOCKS5 address more general proxy needs, telling a proxy server which destination to connect to. Comparing them helps distinguish proxy functionality from a secure channel: forwarding a connection doesn't automatically encrypt the link between the client and proxy server. Check both the proxy type and whether the existing server entry provides the required security layer.

Trojan: Check TLS First, Then Password

A Trojan configuration typically needs a server address, port, Password, and TLS name details. The connection address reaches the server; the Server Name is used for the TLS handshake and certificate identity check. They may be the same or differ depending on the deployment. If you connect using an IP address, don't assume the certificate should match that IP. Keep the name settings from your existing configuration. Successful authentication doesn't guarantee that forwarding will work; check destination reachability separately.

Check certificate-related failures against the system clock, name match, certificate chain, and server deployment, one by one. Skipping certificate verification weakens server identity checks and shouldn't be left in place as a permanent fix. If the local network requires a sign-in page before granting access, complete that first, then test the proxy. TLS, authentication, and destination errors occur at different stages. Keep the original error text so that a summary doesn't obscure the difference.

HTTP: CONNECT Creates a Tunnel; It Doesn't Replace TLS

An HTTP proxy can handle proxy requests and often uses CONNECT to establish a byte tunnel to a destination. When the destination website uses HTTPS, the website's own TLS connection is usually established between the app and the destination. That doesn't mean the proxy handshake, authentication details, or destination metadata are automatically protected between the client and proxy. Whether the proxy entry itself is encrypted depends on the server's offering and the corresponding app settings. Don't judge by whether the destination URL starts with HTTPS.

HTTP proxy credentials may be completely different from server login credentials. Use the proxy authentication details explicitly provided by the server. If authentication fails, check whether a username is required, whether it contains special characters, and whether importing preserved it correctly. Some proxies restrict destination ports, request methods, or account usage. You may be able to connect while some destinations are rejected. Changing DNS or rules repeatedly may not help; first check the proxy's access limits.

SOCKS5: Destination Negotiation, Authentication, and UDP Requirements

SOCKS5 negotiates destination connections, supports different authentication methods, and defines a mechanism for UDP forwarding, but doesn't guarantee data encryption. Client support for a feature doesn't mean the current server has enabled it. Where a domain name is resolved depends on how the request is sent through the proxy and how the client handles it. Check the DNS settings as well; the name SOCKS5 alone doesn't mean all lookups happen remotely.

SOCKS5 UDP forwarding often requires an additional association step and depends on both endpoints and the intervening network allowing the traffic. If websites work but real-time services fail, check TCP and UDP separately instead of repeatedly changing the username. If your existing proxy is for a local or managed network, also consider whether its address remains reachable outside that network. Saving an entry in the client doesn't extend the network range where its address can be reached.

When comparing these types of connection, rule out configuration differences first, then consider handshake time, connection reuse, and path quality. Trojan's TLS handshake may affect the initial wait for short connections. A plain proxy has less overhead, but that doesn't automatically make it faster or a better fit overall. For intermittent use on iOS, the ability to recover reliably also matters. If only one destination fails, check the destination and server access limits first. If all destinations fail, recheck the address, authentication, and security layer.

5. WireGuard: Key Identity and a Layer 3 Tunnel

WireGuard is designed for network-layer tunneling, unlike proxy protocols that negotiate destinations request by request. It identifies peers by public key, carries IP packets, and uses UDP for transport. Its configuration ties together identity, tunnel addresses, and the IP ranges that can be sent. You can't set it up with just a server address and password: you need the complete details provided by the server and must know which fields belong to your device and which to the remote peer.

PrivateKey and PublicKey: Which Key Goes Where

PrivateKey is the secret material for your local identity. Don't share it, submit it to an unfamiliar diagnostics page, or include it in screenshots. The PublicKey in the peer configuration identifies the remote side; the server usually also needs the public key corresponding to your private key. If you replace your local private key without updating the identity recognized by the server, a complete-looking configuration still won't communicate. Copy the full key encoding without including notes or line breaks.

If the configuration includes a PresharedKey, it's additional shared material for both sides. It doesn't replace the public/private key relationship, and you shouldn't enter an arbitrary string. Key fields may look alike while serving different purposes. The app accepting an input doesn't prove the value is correct: format validation can't verify that the remote side has matching settings. You can check key correspondence when troubleshooting, but don't include the full private key in feedback.

Address, Endpoint, and AllowedIPs

Address usually means the local interface address inside the tunnel. Endpoint is the public address and port the device uses to contact the remote peer. They aren't interchangeable: a tunnel address isn't a server entry you can connect to directly, and a remote public address isn't your local tunnel address. If the server provides a specific address, enter it as given and preserve the prefix length. Substituting another address that looks unused may break server routing or access controls.

In WireGuard, AllowedIPs maps IP ranges to a peer and is also involved in choosing outgoing traffic and validating incoming sources. It's not simply a list of website domains, nor is it the same as Shadowrocket's domain-routing rules. How traffic ultimately enters this entry also depends on client routing. Don't assume that global routing works the same way in every setup. Check the tunnel's allowed ranges, the server's forwarding capabilities, and the current Global Routing setting together.

Adjust MTU and Keepalive Only with a Clear Reason

MTU affects the size of individual packets inside the tunnel. Outer encapsulation requires extra space, and the path may have its own packet-size limits. An unsuitable value can cause small requests to work while larger transfers stall. But lowering MTU isn't a universal fix for connection problems. First rule out address, key, and routing errors. Then compare before and after under the same repeatable task. Avoid changing several parameters at once, or you won't know what made the difference.

Keepalive can maintain a mapping or help preserve reachability on certain networks, but an overly frequent interval increases idle traffic and wireless activity. Whether to set it, and how, should depend on the server configuration and actual network behavior; don't copy a fixed value without a reason. On iOS, foreground use, the locked screen, and changes between wireless networks can behave differently. A visible handshake doesn't prove that destinations inside the tunnel are reachable; check server forwarding, return routes, and DNS too. For a more detailed guide to reading the fields, see WireGuard Settings Explained.

6. Hysteria2: QUIC, UDP, and Congestion

Hysteria2 uses QUIC over UDP to carry proxy traffic, with a focus on data transfer under challenging network conditions. QUIC implements secure connections, reliable transport, and multiplexing over UDP, so “UDP-based” doesn't mean all traffic is unreliable. Its transport behavior differs from TCP-based entries, but results still depend on whether the network allows UDP, path congestion, server resources, and appropriate settings. The protocol name alone can't guarantee speed.

Check the UDP Path Before Evaluating Performance

Being able to browse the web on a local network doesn't guarantee that the UDP port on a particular server is reachable. Some networks restrict UDP or handle long-lasting or high-volume UDP traffic differently. If the connection never establishes, first check the address, port, and network conditions. If possible, compare on another trusted network. A clear difference after switching networks points to the path, not to an authentication string or certificate name that should be changed first.

QUIC's connection and retransmission mechanisms can handle some packet loss and path changes, but can't overcome physical bandwidth limits, remote congestion, or sustained packet loss. More retries on a lossy network can increase wireless traffic and device processing. Even if a foreground task finishes faster, battery use must be considered alongside transfer time and idle activity. For short, message-like requests, the initial handshake and wake-up costs may matter more. For long transfers, assess the sustained phase rather than a single peak at the start.

Authentication, TLS Names, and Additional Settings

Hysteria2 authentication must match the server's requirements and may use a password or another specified form of credential. Don't remove separators just because a field looks like an ordinary password. TLS-related names still need to match, and the connection address serves a different purpose from the certificate name. If the original configuration includes specific security or additional settings, confirm the current app supports them and import them intact. Don't try to convert entries from different protocol generations just by changing their names.

Some deployments require additional obfuscation settings or other agreed parameters. These aren't universal speed boosts or decorative fields that can be omitted at will. If the server requires a setting that's missing from the client, effective communication may fail before authentication. After importing, compare each value with the original details, paying particular attention to special characters, encoding, and field names. If manual entry differs from the subscription import, first find out why before deciding which set to keep.

Bandwidth Settings Don't Guarantee Speed

If the current configuration offers upload, download, or congestion-related settings, their values may affect sending behavior or bandwidth negotiation. They don't represent fixed capacity assigned to your account by the server. Check the upload and download directions, units, and server limits. Increasing the values won't expand the physical capacity of your local wireless connection and may make congestion, packet loss, and latency worse. Without a reliable basis for changing them, keep the existing working settings rather than entering a momentary peak from a speed test.

To assess battery use on iPhone, start with a real task over a fixed period, then observe an idle connection for the same length of time. Note signal conditions and any network changes. Background activity, frequent retries, and heavy transfers all affect results. Comparing different servers also introduces differences in network routes. If the device gets warm, stop repeated high-volume tests and let conditions return to normal; heat and system scheduling can skew the next results.

Base your decision on the resources you already have: you need a server that explicitly supports Hysteria2, a working UDP path, and complete authentication and TLS settings before testing. If the same server offers other types, keep another verified entry as a comparison, but don't conclude from one failed attempt that the protocol can never work. If only some destinations fail, check DNS, rules, and the destination itself. A successful connection at the entry layer doesn't verify every layer that follows.

7. How Global Routing, Rules, and DNS Work Together

A protocol entry describes how to connect to a server; Global Routing determines whether requests use that entry. These are separate layers. Config / Proxy / Direct in the interface correspond to configuration / proxy / direct routing: Config applies the active configuration's rules, Proxy uses the selected proxy for typical requests, and Direct connects without a proxy. Actual access can also depend on configuration details, system behavior, and app behavior. When testing, check the request records, not just the status shown on Home.

Use Three Routing Modes to Narrow Down the Problem

If a destination works under Direct but fails under Proxy, first check the selected server, protocol authentication, and the server's route to the destination. If Proxy works but Config fails, focus on the active configuration and rule matches, especially whether the request is being sent to another policy or matched by REJECT. If all three modes fail, check the local network, destination service, and DNS first. This comparison is a troubleshooting tool, not a reason to use one mode permanently for every need.

When multiple configuration files are present, first confirm which one is active. Changes to an inactive file won't automatically affect the rules in use. Updating servers in a subscription doesn't mean the rule file has been updated. Before troubleshooting, note the selected server, Global Routing mode, and configuration name so you don't confuse three separate changes. When you're done, switch back from any temporary test mode to the setting you normally need.

Rule Order and the Fallback Rule

Rules are generally evaluated in order, and an earlier matching rule can prevent later rules from handling the same request. DOMAIN matches an exact domain; DOMAIN-SUFFIX covers a domain and its subdomains; IP-CIDR and IP-CIDR6 apply to address ranges; GEOIP checks an IP database; and FINAL provides a fallback. Before choosing a rule keyword, decide whether you're matching a domain or an IP address. Don't broaden the scope arbitrarily just to cover more requests.

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

This example shows rule structure and order; it isn't a complete file you can use as a replacement for your existing configuration. example.com is an illustrative domain. PROXY and DIRECT specify how traffic is handled and shouldn't be replaced with translated text. GEOIP results depend on the IP database and the destination's actual address; they don't necessarily match the region where a website is based. Choose FINAL to suit your needs and keep it in the fallback position. Changing it affects requests that haven't matched earlier rules, not just one test destination.

DNS Isn't a Standalone “Speed Boost”

DNS resolves domain names to addresses. The resolver, the path used for DNS requests, and the returned address can all affect subsequent access. System DNS, custom resolvers, and DNS over HTTPS each have their own deployment requirements. DoH wraps DNS traffic in HTTPS, but you still need to check whether it uses a proxy, whether the resolver is reachable, and whether connecting to it creates a dependency before other connections can start. When changing DNS, confirm that the new path works rather than changing every resolver setting at once.

Domain rules and IP rules may depend on information available at different stages. If only domain-based access fails, testing an address directly verifies only part of the path; the certificate name, upper-layer host name, and destination service may still require the domain. Different IPv4 and IPv6 results can also cause the same destination to behave differently across networks. Don't assume a problem is resolved just because one lookup returned an address. Check the address family actually used by the failed request and how the rules handled it.

After changing DNS, existing connections and caches may temporarily keep using previous results. Start a new request under controlled conditions before comparing records. Don't refresh a subscription while also changing the resolver and rules, or you won't know which change affected the result. For more on resolver trade-offs, see System DNS, Custom DNS, and DoH Explained. For definitions, see Glossary.

8. Choosing by Use Case and Troubleshooting by Layer

Choose based on the configurations available and the task at hand. If you have only one complete set of server details, get that working correctly rather than switching protocol types. If you have multiple working entries, compare short requests, sustained transfers, recovery after idle, and network changes under the same conditions. Keep a stable baseline. The best result may vary by use case: for foreground large-file transfers, focus on sustained throughput; for intermittent browsing, focus on initial response time; for real-time traffic, check UDP, jitter, and sustained reachability too.

Start with the Constraints

If UDP reachability on the local network is uncertain, test the path before evaluating Hysteria2 or WireGuard. If the test fails, increasing bandwidth settings or shortening keepalive intervals isn't a substitute for checking the network. If your existing configuration depends on specific domains, paths, and TLS names, first ensure that all VMess, VLESS, or Trojan settings match. If you already have an HTTP or SOCKS5 entry, clarify its reachability, security layer, and access limits as well.

If your device frequently switches between Wi-Fi and cellular, test both networks separately and observe how the connection recovers after a switch. A brief interruption doesn't automatically mean authentication has failed; DNS resolution, mappings, and existing connections may all need to be re-established. If a connection fails after the screen locks but works in the foreground, note how long the screen was locked, how the connection recovered, and whether On Demand conditions were involved. Don't mistake an On Demand trigger for proof that a protocol can't work in the background.

Connection Failure: Work from the Entry Point Toward the Destination

First, confirm that the local network provides normal access. If needed, complete any sign-in page required by the network. Next, check the server address, port, and protocol type. Confirm that the subscription has been updated and the entry is still valid. Then check authentication, security, and transport settings, including the password, UUID, public-key pairing, Server Name, Host, Path, and any additional parameters. Address one verifiable issue at a time; don't switch several settings just to make the status change.

Next, distinguish handshake, authentication, and destination-access failures. Keep the exact error shown by the app, and use the available logs or diagnostics to identify the stage where the failure occurs. Then check Global Routing, rules, and DNS, and compare more than one destination. If only one destination fails, consider the server's route to it, destination restrictions, and DNS results. If all destinations fail, revisit the shared connection layers instead of changing website rules one by one.

Slow Speeds: Make Tests Repeatable

Before testing, stop other high-volume tasks. Use the same destination and a similar task length, and record the network and server. Compare direct access with the proxy access you need, then compare available entries on the same server. Connectivity Test results apply only to that test method and the conditions at the time; they aren't equivalent to download speeds. Repeated maximum-load tests can introduce heat, congestion, and background activity. Allowing time between tests makes the results easier to interpret.

If only the first load is slow, check DNS, the handshake, and connection recovery. If the connection starts normally but slows over time, check congestion, server load, device temperature, and path changes. If small requests work but large transfers stall, then investigate MTU or fragmentation. Retest every finding with the same task. For a layered approach to speed problems and how to interpret results, see How to Troubleshoot Slow Speeds by Layer. Don't delete your entire configuration based on a single result.

Restore a Baseline and Prepare a Useful Report

If you've made many changes, restore a verified copy of the configuration first, then add necessary changes one at a time. Before updating a subscription, check whether local manual changes will be overwritten; don't mistake changed fields after an update for a random client failure. To report a problem, include the protocol type, network conditions, stage of failure, exact error text, and steps to reproduce. Remove the full subscription URL, Password, UUID, PrivateKey, and any identifying account details. Never publish authentication material to make a report easier to reproduce.

This manual doesn't replace server configuration documentation, and a protocol name isn't a guarantee of quality. For app purchases, restoring purchases, and purchase verification, see Purchase Verification. For first-time system permissions, see First Launch and VPN Configuration Permissions. For known symptoms, browse the Troubleshooting section. After troubleshooting, record the configuration that actually works rather than simply noting that switching protocols fixed it. That gives you a reliable way to check things again after an update or network change.