Fields that make up a Shadowsocks node
The client uses cipher and password to create the Shadowsocks cipher, then connects to server:port the configured server. The address, port, encryption method, and password must all come from the same server configuration.
Base Shadowsocks can carry TCP and UDP separately. A plugin wraps the Shadowsocks connection to change its transport or traffic profile; it does not replace the base encryption fields.
nameRequired- The node name, used by policy groups and rules.
typeRequired- Set this to
ss。 serverRequired- The domain name or IP address of the Shadowsocks server.
portRequired- The server's listening port.
cipherRequired- The encryption method, which must match the server exactly.
passwordRequired- The Shadowsocks password for the selected encryption method.
Choose the Cipher actually used by the server
The current core supports several groups of Shadowsocks encryption methods. Do not replace a cipher simply because another name looks newer; the encrypted handshake fails when client and server differ.
| Category | Official field examples | Description |
|---|---|---|
| AES | aes-128-gcm、aes-256-gcm、CTR、CFB、CCM、GCM-SIV | Includes AEAD and some stream ciphers retained for compatibility |
| ChaCha | chacha20-ietf-poly1305、xchacha20-ietf-poly1305 | Also supports the ChaCha20 and ChaCha8 variants in the official list |
| 2022 Blake3 | 2022-blake3-aes-128-gcm、2022-blake3-chacha20-poly1305 | The password or key format must follow the corresponding server implementation |
| LEA | lea-128-gcm、lea-192-gcm、lea-256-gcm | Choose only when the server uses the same implementation |
| Other compatible options | aegis-128l、aegis-256、rc4-md5、none and others | Use only with an existing server configuration; do not downgrade casually for compatibility |
UDP and UDP over TCP
udp Controls whether the node may handle UDP. By default, UDP uses native Shadowsocks UDP. When UOT is enabled, UDP data is encapsulated in a TCP connection, and the server must support the same mechanism and version.
udpOptional- Allows the node to handle UDP. Disabled by default.
udp-over-tcpOptional- Enables UDP over TCP. The default is
false。 udp-over-tcp-versionVersion- Only UOT versions 1 and 2 are supported. Version 1 is used when omitted.
smuxAdvanced- Generic TCP multiplexing configuration. It is not the same as UOT and cannot replace server-side protocol support.
Plugins and Plugin Options
A node can use only the plugin selected on the server, and the structure ofplugin-opts is defined by that plugin. Shadowsocks has no generic top-level tls switch; configure TLS within the options of a plugin that supports it.
| plugin | Primary modes | Configuration boundary |
|---|---|---|
obfs | http or tls | Common mode and host; it must match the simple-obfs server |
v2ray-plugin | websocket | Can enable TLS within the plugin; QUIC mode is not currently supported |
gost-plugin | websocket | Supports Host, Path, request headers, Mux, and in-plugin TLS |
shadow-tls | Shadow TLS | Configure host, password, version, and optional ALPN; supported versions are 1, 2, and 3 |
restls | Restls | Configure host, password, version-hint, and an optional traffic script |
kcptun | KCP | Parameters must match the kcptun server; the current implementation enables UOT |
jls | JLS | Configure host, username, password, and optional ALPN |
pluginOptional- The plugin name. Use only a type supported by the current core and actually enabled on the server.
plugin-optsOptional- Plugin-specific options that cannot be reused directly across different plugins.
client-fingerprintOptional- Allows the corresponding Shadow TLS, Restls, or JLS plugin to emulate a TLS client profile.
Base node example and troubleshooting
The following is a base node without a plugin. If the subscription provides a plugin, keep the six base fields unchanged and append plugin and the corresponding plugin-opts。
- If initialization reports a cipher error, verify the encryption-method spelling and the current core's supported list.
- If TCP works but UDP does not, verify server-side UDP, the client
udpsetting, and the firewall. - If the plugin connection fails, verify the plugin name, mode, host, path, TLS, and password one by one rather than checking only the SS password.
proxies:
- name: ss-node
type: ss
server: server.example.com
port: 443
cipher: chacha20-ietf-poly1305
password: your-password
udp: true