Shadowsocks quick guide for restricted internet environments

on under developer
5 minute read

Shadowsocks is a Proxy/VPN protocol and collection of of compatible OpenSource client and server software programs. It was first conceived by Github user clowwindy, who had to take parts of the software down because he got visited by the local police. Fortunately, this software is available again and was continued by the community. It works similar like SOCKS5 but uses (better) encryption and (optional) session passphrases to avoid Known Plaintext Attack.

In comparison to commercial VPN/Proxy offers, you or someone you trust need command line access to a server outside the restricted area. To forward the traffic into the Free Internet™ you need to run one of the server software on your machine.

If you are already in the restricted area you might be unable to access the Shadowsocks website (and/or Google Play store). Fortunately, Github access as possible for me at this point. This is why I've included some direct download URLs below.

Table of Contents

Installation on Server (Go binary)

I used the Go server program, as it doesn't need any other prerequisites or libraries on the machine and can run standalone. Besides, it offers the unique feature of running on multiple ports at the same time with different passwords, making it easier to share access with other people.

You can find prebuild binaries for direct download here: Other option would be compiling by using Go get and written in the README. I show here the direct download, as it is the easiest and don't require any change on the server machine.

(current version as of 2016/05 is 1.1.4)

gunzip shadowsocks-server-linux64-1.1.4.gz

# Create config.json
vim config.json

# Run programm in foreground - use tmux or screen if you want to keep it running
# only needs sudo if you choose a port < 1000
sudo ./shadowsocks-server-linux64-1.1.4

Simplest way of configuring the server is adding a config.json file in the same folder as the binary. Here is an example:

  "server":       "",
  "server_port":  443,
  "local_port":   1080,
  "password":     "yoursecretpassword",
  "timeout":      600,
  "method":       "aes-128-cfb",
  "auth":         true
  • Server port: choose an unused port. The more common the port, the less likely it will be blocked. If possible, use HTTPs port 443, another option would be numbers like 995 (POP3s, if you don't use POP mail server) or 990 (FTPs). You could also use a port number greater than 1000 to avoid using sudo, try 8443 or 8080 first. The port 8388 is kind of default port for Shadowsocks.
  • method: Default recommendation by Shadowsocks website is AES-256-CFB.
    But the Go-server README suggests: aes-128-cfb is recommended as it is faster and secure enough – I also use 128 to save a little battery on the mobile clients.
  • auth: Use One Time Authentication (generate a session password to avoid known plaintext attack). Should always be enabled. You could disable it on the client if you experience problems.
  • password: generate a passphrase that you provide to all clients later on

Unused by the server AFAIK, but can fill in if you want to share the config file with client software:

  • Local port: The default is 1080 for all apps.
  • IP: Enter the public IP of the server.

The Go server will run in the shell foreground and don't daemonize. Use Screen or Tmux to keep it running without to much hassle. Otherwise you could create a system job (like Upstart) to wrap it. Here a gist for some ideas (using the -local instead of -server tool):

Installation on clients (Android, OSX)

I describe shortly installation and operation specifics of the Android and OSX clients. You can find a multitude of other clients on the Shadowsocks website.


Shadowsocks profile manager For Android there is a Shadowsocks App in the Play store. If you can't access that store from your location, you have to sideload. Fortunately, they provide the APKs on Github which is not blocked (at the moment):

Shadowsocks android interface If works great with recent versions of Android, as there is no Root required to enable a global Proxy service for the whole device. (There is only a bug with the profile manager, make sure to choose the Default profile and rename it, otherwise you might lose the settings later).


OSX background service options For Mac laptops there is a GUI tool which you also can download directly from Github.

After installing, configuring and starting the service, I run into some specifics:

  • Chrome worked out of the box using the system Proxy configuration (= doing nothing)
  • Firefox and Thunderbird somehow didn't pick up this settings, so you have to manually configure a SOCKS5 proxy in the respective network settings. Other programs might be configured similary.
  • The GUI tool has two modes: Auto proxy and Global mode. With Auto proxy only requests that matches an internal PAC list are forwarded with to the Proxy, otherwise it uses the native system connection. Good, if you want to maintain a more "normal" profile and increase speed to websites that are available anyway

Settings for Thunderbird

SOCKS to HTTP proxy

Some applications ignore our newly configured SOCKS proxy and require a HTTP proxy, such as Google Cloud SDK (gcloud) or Google Drive. To achieve that, we need another piece of OpenSource software, Polipo. Installation should be straight forward with a package manager like apt or brew.

For a quick run, just start the server in a terminal:

polipo socksParentProxy=localhost:1080

Keep that terminal open. To run gcloud, set an environment variable first:

export HTTP_PROXY=

For GoogleDrive, I also needed to configure a "Web-Proxy" in the OSX Network settings Proxies tab. (localhost:8123)

Happy hacking!