ss-local

Run a Shadowsocks proxy by specifying the host, server port, local port, password, and encryption method

$ ss-local -s [host] -p [server_port] -l [local port] -k [password] -m [encrypt_method]

$ ss-local -c [path/to/config/file.json]

$ ss-local --plugin [plugin_name] --plugin-opts [plugin_options]

$ ss-local --fast-open

ss-local [-s server_addr] [-p server_port] [-l local_port] [-k password] [-m method] [-t timeout] [-u] [-c config_file] [--fast-open] [--mtu mtu_value] [--socks5-hostname] [-v] [-h]

-s server_addr
    Specifies the remote Shadowsocks server's IP address or hostname.

-p server_port
    Specifies the remote Shadowsocks server's port.

-l local_port
    Specifies the local SOCKS5 proxy port (default: 1080).

-k password
    Sets the password for encryption/decryption with the server.

-m method
    Defines the encryption method (e.g., aes-256-gcm, chacha20-ietf-poly1305). Must match server's method.

-t timeout
    Sets the timeout in seconds for connections.

-u
    Enables UDP relay for protocols like DNS or games.

-c config_file
    Specifies a path to a JSON configuration file for settings. Highly recommended for complex setups.

--fast-open
    Enables TCP Fast Open for reduced latency.

--mtu mtu_value
    Sets the Maximum Transmission Unit for UDP packets.

--socks5-hostname
    Enables SOCKS5 hostname resolution on the server side instead of locally.

-v
    Enables verbose output for debugging.

-h
    Displays the help message and exits.

ss-local is the client-side component of the Shadowsocks proxy, designed to forward local traffic through a secure, encrypted tunnel to an ss-server running on a remote host. It operates as a local SOCKS5 proxy (defaulting to 127.0.0.1:1080), allowing applications on your machine to route their network traffic through it. This effectively bypasses network censorship, provides a degree of privacy by encrypting data between the client and server, and can mask your real IP address from target websites. Unlike a traditional VPN, Shadowsocks is designed to be lightweight and more difficult to detect and block, making it popular in regions with strict internet controls. Users configure ss-local with the remote server's address, port, password, and encryption method to establish the secure connection.

ss-local requires a corresponding ss-server running on a remote machine to function. It primarily proxies application-level traffic (SOCKS5) and does not automatically route all system traffic like a full VPN. Applications must be explicitly configured to use the local SOCKS5 proxy. Security relies heavily on the chosen encryption method and the strength of your password. Misconfiguration can lead to traffic leaks or connection failures.

While ss-local can be configured via command-line arguments, it is highly recommended to use a JSON configuration file specified with the -c option. This allows for more organized, complex, and persistent settings, including multiple servers, specific routing rules, and the integration of obfuscation plugins (e.g., simple-obfs, v2ray-plugin).

ss-local acts as a local SOCKS5 proxy server. Applications (web browsers, download managers, chat clients, etc.) need to be explicitly configured to use 127.0.0.1 and the specified local port (default 1080) as their SOCKS5 proxy to route traffic through Shadowsocks. This provides flexibility but also requires per-application setup.

Shadowsocks was initially created by a Chinese programmer named clowwindy in 2012 as a lightweight and obfuscated proxy specifically designed to circumvent the Great Firewall of China. Its design focuses on being less detectable than traditional VPN protocols. The ss-local command represents the fundamental client-side component of this project, evolving alongside the server to adapt to new censorship techniques and incorporate better encryption methods.

ss-server(8), proxychains(1), curl(1), ssh(1), openvpn(8)