How to Install, Configure, and Run Shadowsocks-Libev

Shadowsocks is an important tool for censorship circumvention.

The original Shadowsocks was written in Python. It was created by a Chinese developer named clowwindy. In 2015 clowwindy was contacted by the Chinese police and compelled to stop working on the project.

Shadowsocks-Libev is a rewrite in pure C. It aims to be a lightweight implementation of the Shadowsocks protocol in order to keep resource usage as low as possible.

Shadowsocks may not work in China itself, but it is still valuable in other countries. The procedures on this page were tested with CentOS 8 and Ubuntu 20.04.

1. Server

1.1. Open Firewall

If you have installed a firewall on your server, you need to open a port to allow Shadowsocks-Libev to receive client input. Choose the port on which Shadowsocks-Libev will listen. Open that port for TCP and, optionally, for UDP. In the rest of this article, we’ll use 8388 as our example of a Shadowsocks port.

If you’re using firewalld, your commands to open the port will look like this:

firewall-cmd --permanent --add-port=8388/tcp
firewall-cmd --permanent --add-port=8388/udp
firewall-cmd --reload

Here are the same command templates for nftables users, assuming you’re using the table inet filter and your port is 8388:

nft add rule inet filter input tcp dport 8388 counter accept
nft add rule inet filter input udp dport 8388 counter accept
nft list ruleset > /etc/sysconfig/nftables.conf

Similar rules can be created for iptables users. Again, we assume you have a policy of dropping input unless it’s explicitly accepted, and we assume you have previously installed and configured the iptables-persistent package.

iptables -A INPUT -p tcp --dport 8388 -j ACCEPT
iptables -A INPUT -p udp --dport 8388 -j ACCEPT
dpkg-reconfigure iptables-persistent

For users of the ufw frontend for iptables, the equivalent commands would be:

ufw allow 8388/tcp
ufw allow 8388/udp

1.2. Scripted Install, Configuration, and Run

The easiest way to install, configure and run Shadowsocks-Libev in a single step is to use the Teddysun script.

On a CentOS platform, you do that like this:

yum install wget -y
wget https://raw.githubusercontent.com/teddysun/shadowsocks_install/master/shadowsocks-libev.sh
chmod +x shadowsocks-libev.sh
./shadowsocks-libev.sh

Your run of the script will prompt you with some questions, like this:

#############################################################
# Install Shadowsocks-libev server for CentOS 6 or 7 #
# Intro: https://teddysun.com/357.html #
# Author: Teddysun #
# Github: https://github.com/shadowsocks/shadowsocks-libev #
#############################################################

[Info] Latest version: shadowsocks-libev-3.3.4

Please enter password for shadowsocks-libev:
(Default password: teddysun.com):barfoo!

---------------------------
password = barfoo!
---------------------------

Please enter a port for shadowsocks-libev [1-65535]
(Default port: 15441):8388

---------------------------
port = 8388
---------------------------

Please select stream cipher for shadowsocks-libev:
1) aes-256-gcm
2) aes-192-gcm
3) aes-128-gcm
4) aes-256-ctr
5) aes-192-ctr
6) aes-128-ctr
7) aes-256-cfb
8) aes-192-cfb
9) aes-128-cfb
10) camellia-128-cfb
11) camellia-192-cfb
12) camellia-256-cfb
13) xchacha20-ietf-poly1305
14) chacha20-ietf-poly1305
15) chacha20-ietf
16) chacha20
17) salsa20
18) rc4-md5
Which cipher you'd select(Default: aes-256-gcm):14

---------------------------
cipher = chacha20-ietf-poly1305
---------------------------

Press any key to start...or press Ctrl+C to cancel

The script downloads, compiles, configures, and runs the software. At the end of the script, it displays some confirmation messages:

Congratulations, Shadowsocks-libev server install completed!
Your Server IP : YY.YY.YY.YY
Your Server Port : 8388
Your Password : barfoo!

The script places the configuration in /etc/shadowsocks-libev/config.json. The Shadowsocks executables are in /usr/local/bin. The executable ss-server is running in the background and listening on the specified port (8388 in our example).

On a Debian or Ubuntu platform, the process is almost exactly the same:

wget https://raw.githubusercontent.com/teddysun/shadowsocks_install/master/shadowsocks-libev-debian.sh
chmod +x shadowsocks-libev-debian.sh
./shadowsocks-libev-debian.sh

Your run of the script will prompt you with some questions, like this:

#############################################################
# Install Shadowsocks-libev server for Debian or Ubuntu #
# Intro: https://teddysun.com/358.html #
# Author: Teddysun #
# Github: https://github.com/shadowsocks/shadowsocks-libev #
#############################################################

[Info] Latest version: shadowsocks-libev-3.3.4

Please input password for shadowsocks-libev:
(Default password: teddysun.com): barfoo!

Please enter a port for shadowsocks-libev [1-65535]
(Default port: 18122):8388

Please select stream cipher for shadowsocks-libev:
1) aes-256-gcm
2) aes-192-gcm
3) aes-128-gcm
4) aes-256-ctr
5) aes-192-ctr
6) aes-128-ctr
7) aes-256-cfb
8) aes-192-cfb
9) aes-128-cfb
10) camellia-128-cfb
11) camellia-192-cfb
12) camellia-256-cfb
13) xchacha20-ietf-poly1305
14) chacha20-ietf-poly1305
15) chacha20-ietf
16) chacha20
17) salsa20
18) rc4-md5
Which cipher you'd select(Default: aes-256-gcm):14

---------------------------
cipher = chacha20-ietf-poly1305
---------------------------

Press any key to start...or press Ctrl+C to cancel

The script downloads, compiles, configures, and runs the software. At the end of the script, it displays some confirmation messages:

Congratulations, Shadowsocks-libev server install completed!
Your Server IP : YY.YY.YY.YY
Your Server Port : 8388
Your Password : barfoo!
Your Encryption Method: chacha20-ietf-poly1305

The script places the configuration in /etc/shadowsocks-libev/config.json. The Shadowsocks executables are in /usr/local/bin. The executable ss-server is running in the background and listening on the specified port (8388 in our example).

1.3. Manually Compile Shadowsocks-Libev

If you do not want to use the automated script, you can alternatively manually compile Shadowsocks-Libev from source.

On CentOS, issue the following commands:

yum update -y
yum group install "Development Tools" -y
yum install asciidoc c-ares-devel libev-devel pcre-devel xmlto -y
yum install epel-release -y
yum install libsodium-devel mbedtls-devel -y
git clone https://github.com/shadowsocks/shadowsocks-libev.git
cd shadowsocks-libev
git submodule init && git submodule update
./autogen.sh
./configure
make
make install

On Debian or Ubuntu, issue the following commands:

apt update && apt upgrade -y
apt install build-essential autoconf automake libtool -y
apt install asciidoc libc-ares-dev libev-dev libpcre3-dev xmlto libsodium-dev libmbedtls-dev -y
git clone https://github.com/shadowsocks/shadowsocks-libev.git
cd shadowsocks-libev
git submodule init && git submodule update
./autogen.sh
./configure
make
make install

1.4. Manually Configure Defaults

Whether on CentOS or on Debian/Ubuntu, create a defaults file named /etc/default/shadowsocks-libev. Insert the contents:

START=yes
CONFFILE="/etc/shadowsocks-libev/config.json"
DAEMON_ARGS=
USER=nobody
GROUP=nogroup
MAXFD=32768

Save the file /etc/default/shadowsocks-libev.

1.5. Manually Configure Systemd Service File

Whether on CentOS or on Debian/Ubuntu, copy the example systemd service file into place:

cp debian/shadowsocks-libev.service /usr/lib/systemd/system

Now edit the file /usr/lib/systemd/system/shadowsocks-libev.service. The binaries are expected to be in /usr/bin, but we have installed them to /usr/local/bin. Therefore substitute this into the existing ExecStart line so that it reads:

ExecStart=/usr/local/bin/ss-server -c $CONFFILE $DAEMON_ARGS

Save the systemd service file /usr/lib/systemd/system/shadowsocks-libev.service.

Issue the command:

systemctl daemon-reload

1.6. Manually Configure Shadowsocks-Libev

Make a directory for your Shadowsocks-Libev configuration:

mkdir /etc/shadowsocks-libev

Create a file /etc/shadowsocks-libev/config.json. Here is a model you can adapt to your purposes. This configuration accepts both TCP and UDP, and listens on port 8388. Change the sample values to your own choices.

{
"server": ["::", "0.0.0.0"],
"mode": "tcp_and_udp",
"server_port": 8388,
"local_port": 1080,
"password": "barfoo!",
"timeout": 86400,
"method": "chacha20-ietf-poly1305",
"ipv6_first": true
}

Once you have finished editing, save the file /etc/shadowsocks-libev/config.json.

If you need more help understanding the available parameters, consult the manual pages for Shadowsocks-Libev by issuing the command:

man shadowsocks-libev

1.7. Manually Start Shadowsocks-Libev

Start Shadowsocks-Libev after every reboot, and also start it right now:

systemctl enable shadowsocks-libev
systemctl start shadowsocks-libev

Check that Shadowsocks-Libev is active and running:

systemctl status shadowsocks-libev

Check that Shadowsocks-Libev is listening on the expected port:

ss -tulpn | grep 8388

2. Clients

2.1. Client Availability

Shadowsocks clients are available for Windows, macOS, Linux, Android, iOS, and OpenWRT. The Shadowsocks clients page provides an overview. We will go into more details in the sections that follow.

2.2. Linux Client Compile Shadowsocks-Libev from Source

For CentOS clients, this process is very similar to the compile on the server. Issue the following commands in turn:

sudo yum update -y
sudo yum group install "Development Tools" -y
sudo yum install asciidoc c-ares-devel libev-devel pcre-devel xmlto -y
sudo yum install epel-release -y
sudo yum install libsodium-devel mbedtls-devel -y
git clone https://github.com/shadowsocks/shadowsocks-libev.git
cd shadowsocks-libev
git submodule init && git submodule update
./autogen.sh
./configure
make
sudo make install

For Debian or Ubuntu clients, issue the following commands in turn:

sudo apt update && sudo apt upgrade -y
sudo apt install build-essential autoconf automake libtool -y
sudo apt install asciidoc libc-ares-dev libev-dev libpcre3-dev xmlto libsodium-dev libmbedtls-dev -y
sudo apt install git
git clone https://github.com/shadowsocks/shadowsocks-libev.git
cd shadowsocks-libev
git submodule init && git submodule update
./autogen.sh
./configure
make
sudo make install

2.3. Linux Client Configure Shadowsocks-Libev

Create a new file ~/shadowsocks-libev.json.

Insert contents modeled on the following:

{
"server": "YY.YY.YY.YY",
"server_port": 8388,
"local_address": "127.0.0.1",
"local_port":1080,
"password": "barfoo!",
"method": "chacha20-ietf-poly1305",
"timeout": 300,
"fast_open": false,
"nameserver": "8.8.8.8",
"mode": "tcp_and_udp"
}

The parameters you choose on the client must match up with what you chose on the server.

2.4. Linux Client Run Shadowsocks-Libev

Start the Shadowsocks-Libev client running:

ss-local -c ~/shadowsocks-libev.json &

Check that it is running and listening on the expected port. Open a new Terminal window.

ps -aux | grep shadowsocks-libev
ss -tulpn | grep 1080

2.5. Linux Client Configure Firefox

Open Firefox. From the hamburger menu, select Preferences > General. Scroll down to Network Settings. Click the Settings button.

2.6. Verify Client Functionality

Check the end-to-end functionality to confirm that Shadowsocks-Libev and Firefox are configured correctly. With Shadowsocks-Libev still running, and Firefox proxied, visit one or more of these sites:

In all cases, you should see the IP address of the server, not your local client.

The IP Location site displays geolocation data from four databases (IP2Location, ipinfo.io, DB-IP, and ipdata.co). Note that the four may differ due to timing delays in updating databases.

2.7. End Run on Linux

Revert Firefox from Manual proxy configuration to Use system proxy settings.

In your Terminal window, do Ctrl+c to end the Shadowsocks-Libev process.

Alternatively, you can open a second Terminal window and identify the process id under which Shadowsocks-Libev is running:

ss -tulpn | grep 1080

Kill that process by process id. For example, if the process id is 38262:

kill 38262

2.8. Windows Client

Download and unzip the Windows client from GitHub.

Enter details which match those of the server. The screenshot below gives an example.

Shadowsocks system tray icon and server editing on Windows

Shadowsocks-Libev continues to run in the system tray. The is the area on the right side of the taskbar, toward the bottom right of your Windows desktop. Applications insert icons in the system tray to give you a quick entrance into the application. The Shadowsocks-Libev icon looks like a paper airplane. You can see it in the screenshot above. Right-click on the Shadowsocks-Libev icon to bring up the menu. The following options appear:

Under the System proxy option, you can either disable the system proxy or set it to global. If you disable the system proxy, you must configure your individual browser(s) to use a SOCKS5 proxy server on 127.0.0.1 port 1080. This is illustrated in the screenshot below.

Configure Firefox to use a proxy server

In global mode, the Windows system proxy is changed so that all applications that use the Windows system proxy will be affected. You can see the current value of the Windows system proxy in Settings > Network & Internet > Proxy.

Proxy Automatic Configuration (PAC) configures Shadowocks to use or not use the proxy server, depending on whether the destination URL is in your PAC file.

The Load balance and High availability options will automatically switch between proxy servers.

For UDP, please use SocksCap or ProxyCap to force the program to go through the proxy server.

2.9. macOS Client

The main macOS client is ShadowsocksX-NG. It is available from GitHub.

Download the latest release, e.g. ShadowsocksX-NG.1.9.4.zip.

Launch ShadowsocksX-NG from Finder. Click Open. Enter your macOS user password, and click OK. Click the button to allow notifications.

The ShadowsocksX-NG paper airplane icon appears in the menu bar across top of screen.

Select global mode. Set up your Server Preferences on the client to match your server.

ShadowsocksX-NG server editing on macOS

2.10. Android Client

You can get the Shadowocks for Android client from Google Play or GitHub.

On Android, Shadowsocks works more lika VPN. You don’t need to configure your browser to use a proxy server.

Note that we do not generally recommend mobile computing in environments where your security is threatened.

2.11. iOS Client

There are no free clients for iOS. Look in the iOS App Store for Shadowrocket.

Note that we do not generally recommend mobile computing in environments where your security is threatened.

3. Get Help and Report Issues

If you have informal questions about Shadowsocks, you can ask on social media platforms such as Reddit.

If you discover a legitimate issue with Shadowsocks, report it on the official GitHub issues page for the project: