From 3d487d51571b1d22d8b93f6304f044fbece942f2 Mon Sep 17 00:00:00 2001 From: Boyuan Yang <073plan@gmail.com> Date: Mon, 21 Dec 2015 22:59:50 +0800 Subject: [PATCH] readme: refine structure; add info about mbedTLS. --- README.md | 93 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 74 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 6e0580c8..b99894ea 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ ## Intro -[Shadowsocks-libev](http://shadowsocks.org) is a lightweight secured SOCKS5 +[Shadowsocks-libev](http://shadowsocks.org) is a lightweight secured SOCKS5 proxy for embedded devices and low-end boxes. -It is a port of [Shadowsocks](https://github.com/shadowsocks/shadowsocks) -created by [@clowwindy](https://github.com/clowwindy), which is maintained by +It is a port of [Shadowsocks](https://github.com/shadowsocks/shadowsocks) +created by [@clowwindy](https://github.com/clowwindy), which is maintained by [@madeye](https://github.com/madeye) and [@linusyang](https://github.com/linusyang). Current version: 2.4.3 | [Changelog](debian/changelog) @@ -16,24 +16,76 @@ Travis CI: [![Travis CI](https://travis-ci.org/shadowsocks/shadowsocks-libev.svg ## Features Shadowsocks-libev is written in pure C and only depends on -[libev](http://software.schmorp.de/pkg/libev.html) and +[libev](http://software.schmorp.de/pkg/libev.html) and [OpenSSL](http://www.openssl.org/) or [PolarSSL](https://polarssl.org/). +The use of [mbedTLS](https://tls.mbed.org/) is added but still for testing, and +it is not officially supported yet. -In normal usage, the memory footprint is about 600KB and the CPU utilization is -no more than 5% on a low-end router (Buffalo WHR-G300N V2 with a 400MHz MIPS CPU, +In normal usage, the memory footprint is about 600KB and the CPU utilization is +no more than 5% on a low-end router (Buffalo WHR-G300N V2 with a 400MHz MIPS CPU, 32MB memory and 4MB flash). +For a full list of feature comparison between different versions of shadowsocks, +refer to the [Wiki page](https://github.com/shadowsocks/shadowsocks/wiki/Feature-Comparison-across-Different-Versions). + + ## Installation -**Notes about PolarSSL** +### Distribution-specific guide + +- [Debian & Ubuntu](#debian--ubuntu) + + [Install from repository](#install-from-repository) + + [Build deb package from source](#build-deb-package-from-source) + + [Configure and start the service](#configure-and-start-the-service) +- [Fedora & RHEL](#fedora--rhel) + + [Install from repository](#install-from-repository-1) +- [Archlinux](#archlinux) +- [Directly build and install on UNIX-like system](#linux) +- [FreeBSD](#freebsd) +- [OpenWRT](#openwrt) +- [OS X](#os-x) +- [Windows](#windows) + +* * * + +### Pre-build configure guide + +For a complete list of avaliable configure-time option, +try `configure --help`. + +#### Using alternative crypto library + +There are three crypto libraries available: + +- OpenSSL (**default**) +- PolarSSL +- mbedTLS (__NOT__ officially supported) + +##### PolarSSL -* The default crypto library is OpenSSL. To build against PolarSSL, -specify `--with-crypto-library=polarssl` and `--with-polarssl=/path/to/polarssl` -when running `./configure`. -* PolarSSL __1.2.5 or newer__ is required. Currently, PolarSSL does __NOT__ support +To build against PolarSSL, specify `--with-crypto-library=polarssl` +and `--with-polarssl=/path/to/polarssl` when running `./configure`. + +* PolarSSL __1.2.5 or newer__ is required. Currently, PolarSSL does __NOT__ support CAST5-CFB, DES-CFB, IDEA-CFB, RC2-CFB and SEED-CFB. * RC4 is only support by PolarSSL __1.3.0 or above__. +##### mbedTLS +To build against mbedTLS, specify `--with-crypto-library=mbedtls` +and `--with-mbedtls=/path/to/mbedtls` when running `./configure`. + +Please not that we do **NOT** officially support mbedTLS right now, +and you should use it at your own risk. + +Windows users will need extra work when compiling mbedTLS library, +see [this issue](https://github.com/shadowsocks/shadowsocks-libev/issues/422) for detail info. + +#### Using shared library from system + +Please specify `--enable-system-shared-lib`. This will replace the bundled +`libev`, `libsodium` and `libudns` with the corresponding libraries installed +in the system during compilation and linking. + ### Debian & Ubuntu #### Install from repository @@ -82,7 +134,7 @@ Please follow the instructions on [Debian Backports](http://backports.debian.org This also means that you can only install those built packages on systems that have `init-system-helpers` installed. -Otherwise, try to build and install directly from source. See the **Linux** +Otherwise, try to build and install directly from source. See the [Linux](#linux) section below. ``` bash @@ -145,11 +197,11 @@ sudo pacman -S shadowsocks-libev ``` Please refer to downstream [PKGBUILD](https://projects.archlinux.org/svntogit/community.git/tree/trunk?h=packages/shadowsocks-libev) -script for extra modifications. +script for extra modifications and distribution-specific bugs. ### Linux -For Unix-like systems, especially Debian-based systems, +For Unix-like systems, especially Debian-based systems, e.g. Ubuntu, Debian or Linux Mint, you can build the binary like this: ```bash @@ -182,13 +234,16 @@ service shadowsocks_libev start ### OpenWRT +**Note**: You may want to use [openwrt-shadowsocks](https://github.com/shadowsocks/openwrt-shadowsocks) +, which is developed specifically for OpenWRT. + ```bash # At OpenWRT build root pushd package git clone https://github.com/shadowsocks/shadowsocks-libev.git popd -# Enable shadowsocks-libev in network category +# Enable shadowsocks-libev in network category make menuconfig # Optional @@ -238,7 +293,7 @@ make lib WINDOWS=1 make install DESTDIR="$HOME/prebuilt" ``` -Then, build the binary using the commands below, and all `.exe` files +Then, build the binary using the commands below, and all `.exe` files will be built at `$HOME/ss/bin`: #### OpenSSL @@ -322,7 +377,7 @@ man pages of the applications, respectively. notes: - ss-redir provides a transparent proxy function and only works on the + ss-redir provides a transparent proxy function and only works on the Linux platform with iptables. ``` @@ -334,7 +389,7 @@ The latest shadowsocks-libev has provided a *redir* mode. You can configure your # Create new chain root@Wrt:~# iptables -t nat -N SHADOWSOCKS root@Wrt:~# iptables -t mangle -N SHADOWSOCKS - + # Ignore your shadowsocks server's addresses # It's very IMPORTANT, just be careful. root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 123.123.123.123 -j RETURN @@ -358,7 +413,7 @@ The latest shadowsocks-libev has provided a *redir* mode. You can configure your root@Wrt:~# ip rule add fwmark 0x01/0x01 table 100 root@Wrt:~# ip route add local 0.0.0.0/0 dev lo table 100 root@Wrt:~# iptables -t mangle -A SHADOWSOCKS -p udp --dport 53 -j TPROXY --on-port 12345 --tproxy-mark 0x01/0x01 - + # Apply the rules root@Wrt:~# iptables -t nat -A PREROUTING -p tcp -j SHADOWSOCKS root@Wrt:~# iptables -t mangle -A PREROUTING -j SHADOWSOCKS