ss-local

shadowsocks client as socks5 proxy, C implementation

SYNOPSIS

ss-local [options]

DESCRIPTION

shadowsocks-c is a lightweight and secure socks5 proxy. It is a port of the original shadowsocks created by clowwindy. shadowsocks-c is written in pure C and takes advantage of libuv to achieve both high performance and low resource consumption.

shadowsocks-c consists of five components. ss-local(1) works as a standard socks5 proxy on local machines to proxy TCP traffic. For more information, check out shadowsocks-libev(8).

OPTIONS

Options include all supported platform variants; restrictions are noted below.

-f <pid_file>

Start shadowsocks as a daemon with specific pid file.

-s <server_host>

For clients, set a server endpoint as HOST:PORT or [IPv6]:PORT; host-only values use the legacy -p or configured fallback. Bare IPv6 is never split at its last colon. For server and manager, set the listening address.

-p <server_port>

For clients, set the legacy fallback port for server values without an embedded port. For ss-server, set the listening port.

-l <local_port>

Set the local port number.

-k <password>

Set the password. The server and the client should use the same password.

-t <timeout>

Set the socket timeout in seconds. The default value is 60.

-m <encrypt_method>

Set the cipher. The default is chacha20-ietf-poly1305.

AEAD cipher names from the source (availability depends on the build):

constexpr AeadSpec kSpecs[] = {
    { "aes-128-gcm", AeadKind::aes_128_gcm, 16, 12, 16 },
    { "aes-192-gcm", AeadKind::aes_192_gcm, 24, 12, 16 },
    { "aes-256-gcm", AeadKind::aes_256_gcm, 32, 12, 16 },
    { "chacha20-ietf-poly1305", AeadKind::chacha20_poly1305, 32, 12, 16 },
#ifdef crypto_aead_xchacha20poly1305_ietf_ABYTES
    { "xchacha20-ietf-poly1305", AeadKind::xchacha20_poly1305, 32, 24, 16 },
#endif
};

The unauthenticated stream ciphers (aes-256-cfb, chacha20-ietf, rc4-md5 and the like) are no longer supported.The 2022-blake3-* ciphers implement Shadowsocks 2022 (SIP022). They require a base64-encoded pre-shared key supplied with --key or --password (-k): 16 bytes for 2022-blake3-aes-128-gcm and 32 bytes for the other 2022 ciphers. Generate a 32-byte key with openssl rand -base64 32. Passwords are not stretched into keys for these ciphers.

-i <interface>

Send outbound traffic through the specified network interface where supported by the platform.

-c <config_file>

Use a configuration file.

Refer to shadowsocks-c(8) CONFIG FILE section for more details.

-b <local_address>

Set the local address to bind for the client listener.

-a <user_name>

Run as a specific user.

-n <number>

Specify the maximum number of open files. Requires a platform with setrlimit support.

-S <path>

Android only: UNIX socket path for traffic statistics.

-h

Print help message.

-u

Enable UDP relay.

-U

Enable UDP relay and disable TCP relay.

-v

Enable verbose mode.

-V

Android only: enable VPN socket protection.

-6

Resolve hostname to IPv6 address first.

-A

Deprecated one-time authentication option. Exits with an error; use AEAD ciphers instead.

--config <config_file>

Read JSON configuration. See the CLI conventions for precedence and default-value behavior. Short alias: -c.

--cipher <encrypt_method>

Select the encryption cipher. See -m for supported cipher names and key requirements. Short alias: -m.

--timeout <timeout>

Same behavior as -t; see that option for details. Short alias: -t.

--user <user_name>

Same behavior as -a; see that option for details. Short alias: -a.

--pid-file <pid_file>

Same behavior as -f; see that option for details. Short alias: -f.

--nofile <number>

Same behavior as -n; see that option for details. Short alias: -n.

--udp

Enable both TCP and UDP relay, overriding the configured mode. Short alias: -u.

--udp-only

Enable UDP relay only, overriding the configured mode. Short alias: -U.

--ipv6-first

Prefer IPv6 DNS results; overrides configuration. This does not restrict connections to IPv6. Short alias: -6.

--verbose

Same behavior as -v; see that option for details. Short alias: -v.

--server <HOST:PORT>

Set a remote server endpoint; may be repeated with different ports. Use HOST:PORT for a hostname or IPv4, and [IPv6]:PORT for IPv6 (including scope when needed). Bare IPv6 is always a host, never split into a port. Host-only values require the legacy --server-port fallback or a configured port. An endpoint port takes priority over the fallback regardless of option order. SIP003 plugins require the same port for all endpoints. Short alias: -s.

--server-port <server_port>

Legacy fallback port for server values without an embedded port. Prefer --server HOST:PORT. Short alias: -p.

--listen-address <local_address>

Set the listening address. Server and manager addresses may be repeated. Short alias: -b.

--listen-port <local_port>

Set the listening port. Short alias: -l.

--interface <interface>

Same behavior as -i; see that option for details. Short alias: -i.

--version

Print the program name and version to standard output and exit successfully.

--tcp-only

Enable TCP relay only, overriding the configuration file's mode. The last of --tcp-only, --udp, and --udp-only wins.

--ipv4-first

Prefer IPv4 DNS results, overriding ipv6_first in the configuration file. This is an address preference, not a restriction to IPv4. The last of --ipv4-first and --ipv6-first wins.

--vpn

Same behavior as -V; see that option for details. Short alias: -V.

--stat-path <path>

Same behavior as -S; see that option for details. Short alias: -S.

--reuse-port

Enable port reuse where supported by the operating system.

--tcp-incoming-sndbuf <size>

Set TCP send buffer size for incoming connections.

--tcp-incoming-rcvbuf <size>

Set TCP receive buffer size for incoming connections.

--tcp-outgoing-sndbuf <size>

Set TCP send buffer size for outgoing connections.

--tcp-outgoing-rcvbuf <size>

Set TCP receive buffer size for outgoing connections.

--fast-open

Enable TCP Fast Open where supported by the operating system.

--no-delay

Enable TCP_NODELAY.

--max-connections <number>

Serve at most this many TCP connections at once (default: 1024). Their memory is reserved at startup; a connection beyond the limit is refused until another one closes.

--max-udp-sessions <number>

Keep at most this many UDP associations (default: 256 for clients, 512 for ss-server). When the table is full, the least recently used one is dropped.

--max-dns-queries <number>

Run at most this many DNS lookups at once (default: the connection limit; ss-server adds 64). Beyond the limit ss-server closes the connection that needed the lookup, and ss-local applies its ACL without the address.

--acl <acl_config>

Enable ACL (Access Control List) and specify config file.

--mtu <MTU>

Specify the MTU of your network interface.

--mptcp

Enable Multipath TCP.

Only available with MPTCP enabled Linux kernel.

--plugin <plugin_name>

Enable SIP003 plugin. (Experimental)

--plugin-opts <plugin_options>

Set SIP003 plugin options. (Experimental)

--password <password>

Set the password. The server and the client should use the same password.

--key <key_in_base64>

Set the key directly. The key should be encoded with URL-safe Base64.

--server-url <ss_url>

Take the server address, port, cipher, password and any SIP003 plugin from a single ss:// URL, as produced by most clients and by shadowsocks-rust's ssurl. Both the SIP002 form (ss://base64(method:password)@host:port/?plugin=...#tag) and the older ss://base64(method:password@host:port) form are accepted. Options given later on the command line override the values taken from the URL.

--printable-salt

Experimental client TCP salt camouflage, disabled by default. Config key: "printable_salt": true (ss-local only). Randomly choose 6-12 leading salt bytes and sample each as printable ASCII (0x20-0x7e). Requires chacha20-ietf-poly1305 or aes-256-gcm. Adds no framing bytes; leaves UDP and server responses unchanged. The 32-byte salt retains at least 238 bits of entropy. Salt uniqueness remains essential. This is not TLS impersonation or proven censorship resistance.

--help

Print help message.

EXAMPLE

ss-local(1) can be started from command line and run in foreground. Here is an example:

# Start ss-local with given parameters
ss-local --server example.com:12345 --listen-port 1080 --password foobar --cipher aes-256-gcm

SEE ALSO

ss-server(1), ss-tunnel(1), ss-redir(1), ss-manager(1), shadowsocks-libev(8), iptables(8), /etc/shadowsocks-libev/config.json