Shadowsocks

A Shadowsocks server is described by a cipher and a password, and optionally a plugin that disguises the connection. Potatso connects to a server when it supports the cipher and, if there is one, the plugin. Use the tables below to check your server's settings, as shown by your provider or in its ss:// link.

You can add a Shadowsocks server by hand, with an ss:// link, or by importing:

• a Clash or Mihomo subscription,
• a SIP008 online configuration, from a file or a link,
• a shadowsocks-rust or shadowsocks-libev config.json,
• a Surge configuration, or an Xray or V2Ray configuration.

Ciphers

Prefer a 2022 cipher if your server offers one, then an AEAD cipher. Stream ciphers have known weaknesses: use them only with servers that offer nothing else.

Names aren't case-sensitive, so AES-256-GCM works the same as aes-256-gcm.

none sends your traffic unencrypted. Use it only with a plugin that encrypts the connection itself, such as v2ray-plugin with TLS.

Every supported cipher is tested against at least one real Shadowsocks server: shadowsocks-rust, sing-box or the original Python server. Of the AEAD ciphers above, only shadowsocks-rust servers offer aes-*-ccm, aes-*-gcm-siv and sm4-*, and few providers use them.

2022 keys

The 2022 ciphers (SIP022) don't use a password. They use a key: random bytes, Base64-encoded, of the length the cipher needs. 2022-blake3-aes-128-gcm needs a 16-byte key and the other 2022 ciphers a 32-byte key. Use the key exactly as your server has it.

Potatso doesn't connect with a key of the wrong length, or with a password that isn't Base64. To make a new key for your server, run openssl rand -base64 16 for 2022-blake3-aes-128-gcm, or openssl rand -base64 32 for the other 2022 ciphers.

Multi-user servers

A 2022 server can share one port between several users (SIP023). Each user has their own key. For these servers, set the password to the server key and your user key, separated by a colon:

server-key:user-key

Only 2022-blake3-aes-128-gcm and 2022-blake3-aes-256-gcm support multi-user servers.

Plugins

A plugin wraps the Shadowsocks connection to make it harder to detect. Potatso has these plugins built in, so there's nothing else to install.

Potatso doesn't import a server that needs another plugin:

• Cloak, xray-plugin and other plugins are programs your device would have to run next to Potatso, which iOS doesn't allow.
• kcptun and ech-tls-tunnel aren't available in Potatso yet.

Setting a plugin

In the server's settings, choose the plugin under Plugin, then enter its options in Plugin Parameter. Options are key=value pairs separated by semicolons, as in this Simple Obfs example:

obfs=tls;obfs-host=cdn.example.com

A key on its own, such as tls, turns that option on. Leave out any option you don't need; the tables below give each default.

When you import a server, Potatso sets the plugin and its options for you:

• An ss:// link carries them in its plugin parameter, after the plugin name: simple-obfs;obfs=tls;obfs-host=cdn.example.com.
• A Clash or Mihomo subscription carries them in plugin and plugin-opts.
• A SIP008 configuration or a shadowsocks-rust or shadowsocks-libev config.json carries them in plugin and plugin_opts.

These are the same options in every form. If your provider lists them one per line, as in a Clash plugin-opts, write each as key=value and join them with semicolons.

Plugin options

Simple Obfs

v2ray-plugin

gost-plugin

ShadowTLS

Restls

JLS

Potatso doesn't connect to a server when a required option is missing or a value isn't valid.

UDP

UDP is on by default for Shadowsocks servers and works with every supported cipher. Turn it off in the server's settings if your server doesn't relay UDP.

UDP isn't sent through a plugin, so with a plugin other than Simple Obfs the server only carries TCP. Potatso doesn't support UDP-over-TCP (udp-over-tcp or uot in a link or subscription) and doesn't import a server that requires it.

Feature support

Some shadowsocks-rust features are settings of its own client program, sslocal, and Potatso does the same job its own way:

• Local SOCKS5, HTTP, tunnel, redir, DNS and TUN servers: Potatso captures your device's traffic itself.
• Access control lists (ACL): use rules in your profile.
• Picking the fastest of several servers: use a proxy group in your profile.

ss:// links

An ss:// link holds a whole server in one line (SIP002):

ss://userinfo@host:port/?plugin=…#name

Potatso also imports the older form, where everything before the # is Base64-encoded:

ss://base64(cipher:password@host:port)#name

Potatso accepts standard and URL-safe Base64, with or without = padding. When Potatso shares a server, it offers the Base64 and percent-encoded forms of SIP002 and the older form.

Examples

Each example shows the link to import. The password in the AEAD examples is secret.

A basic server with aes-256-gcm:

ss://YWVzLTI1Ni1nY206c2VjcmV0@ss.example.com:8388#Basic

A 2022 server with the 16-byte key MTIzNDU2Nzg5MDEyMzQ1Ng==:

ss://2022-blake3-aes-128-gcm:MTIzNDU2Nzg5MDEyMzQ1Ng%3D%3D@ss.example.com:8388#2022

A multi-user 2022 server, with the server key and user key separated by a colon (%3A):

ss://2022-blake3-aes-256-gcm:MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI%3D%3AYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU%3D@ss.example.com:8388#Multi-user

Simple Obfs with TLS, using cdn.example.com as the server name:

ss://YWVzLTI1Ni1nY206c2VjcmV0@ss.example.com:443/?plugin=simple-obfs%3Bobfs%3Dtls%3Bobfs-host%3Dcdn.example.com#Obfs

The older form of the basic server:

ss://YWVzLTI1Ni1nY206c2VjcmV0QHNzLmV4YW1wbGUuY29tOjgzODg#Legacy

A server with an IPv6 address:

ss://YWVzLTI1Ni1nY206c2VjcmV0@[2001:db8::1]:8388#IPv6