From ArchWiki
Jump to navigation Jump to search

Shadowsocks is a lightweight socks5 proxy, originally written in Python.


Install the package shadowsocks-libev(c) or shadowsocks(python). shadowsocks-libev is recommended.


Shadowsocks configuration may be done with a JSON formatted file. Example configuration:

    "server": "my_server_ip",
    "server_port": 8388,
    "local_address": "",
    "local_port": 1080,
    "password": "mypassword",
    "timeout": 300,
    "method": "chacha20-ietf-poly1305",
    "fast_open": false,
    "workers": 1
Tip: To specify multiple server IPs, the following syntax can be used "server":["",""],
Tip: To find out the fastest method running on your machine, you can benchmark with the script
Name Explanation
server the address your server listens
server_port server port
local_address the address your local listens
local_port local port
password password used for encryption
timeout in seconds
method see Stream Ciphers and AEAD Ciphers
fast_open use TCP-Fast-Open, true / false
workers number of workers
Tip: refer to CONFIG FILE section of shadowsocks-libev(8) for JSON syntax


Warning: The udns package is used as a stub resolver for DNS. In order to prevent DNS request leaking of client applications (like browsers), further applications must be employed. For example, privoxy or a full DNS resolver on the client.[1] [2]

From the command line

The client is started with the ss-local command. To start it using the configuration file /etc/shadowsocks/config.json:

$ ss-local -c /etc/shadowsocks/config.json

Alternatively, the configuration may be specified directly on the command:

$ ss-local -s server_address -p server_port -l local_port -k password -m encryption_method

To use verbose log, add -v to the command:

$ ss-local -s server_address -p server_port -l local_port -k password -m encryption_method -v

Using systemd

Make sure that the configuration file is in /etc/shadowsocks. For example, the configuration file is /etc/shadowsocks/foo.json.

The Shadowsocks client can be controlled with an instance of shadowsocks@.service or shadowsocks-libev@.service through systemctl. You may also be interested in running an instance of shadowsocks-libev@ after the network is up.

Tip: Run journalctl -u shadowsocks@foo as root to see the logs.

GUI client

Install shadowsocks-qt5.


From the command line

The server is started with the ss-server(shadowsocks-libev) or ssserver(shadowsocks) command.

To start it in the foreground using the configuration file /etc/shadowsocks/config.json:


$ ss-server -c /etc/shadowsocks/config.json


$ ssserver -c /etc/shadowsocks/config.json

To run in the background:


$ ss-server -c /etc/shadowsocks/config.json -d start
$ ss-server -c /etc/shadowsocks/config.json -d stop


$ ssserver -c /etc/shadowsocks/config.json -d start
$ ssserver -c /etc/shadowsocks/config.json -d stop

Using systemd

The Shadowsocks server can be controlled with an instance of shadowsocks-server@.service.

For example, to start and enable the service using the configuration file /etc/shadowsocks/config.json, use the service shadowsocks-libev-server@config.service(shadowsocks-libev) or shadowsocks-server@config.service(shadowsocks).

To bind Shadowsocks to a privileged port (less than 1024), the server should be started as user root:



Installing the python-m2crypto package will make encryption a little faster.

To use Salsa20 or ChaCha20 ciphers, install the libsodium package.

See also