table of contents
other versions
- jessie-backports 2.6.3+ds-3+deb9u1~bpo8+1
- stretch 2.6.3+ds-3+deb9u1
- testing 3.2.4+ds-1
- stretch-backports 3.2.3+ds-1~bpo9+1
- unstable 3.2.5+ds-1
SHADOWSOCKS-LIBEV(8) | Shadowsocks-libev Manual | SHADOWSOCKS-LIBEV(8) |
NAME¶
shadowsocks-libev - a lightweight and secure socks5 proxySYNOPSIS¶
ss-local|ss-redir|ss-server|ss-tunnel|ss-manager [-s <server_host>] [-p <server_port>] [-l <local_port>] [-k <password>] [-m <encrypt_method>] [-f <pid_file>] [-t <timeout>] [-c <config_file>]DESCRIPTION¶
Shadowsocks-libev is a lightweight and secure socks5 proxy. It is a port of the original shadowsocks created by clowwindy. Shadowsocks-libev is written in pure C and takes advantage of libev to achieve both high performance and low resource consumption. Shadowsocks-libev consists of five components. One is ss-server(1) that runs on a remote server to provide secured tunnel service. ss-local(1) and ss-redir(1) are clients on your local machines to proxy traffic(TCP/UDP or both). ss-tunnel(1) is a tool for local port forwarding. While ss-local(1) works as a standard socks5 proxy, ss-redir(1) works as a transparent proxy and requires netfilter’s NAT module. For more information, check out the EXAMPLE section. ss-manager(1) is a controller for multi-user management and traffic statistics, using UNIX domain socket to talk with ss-server(1). Also, it provides a UNIX domain socket or IP based API for other software. About the details of this API, please refer to the PROTOCOL section.OPTIONS¶
-s <server_host>Set the server’s hostname or IP.
-l <local_port>
Set the local port number.
Not available in server nor manager mode.
-k <password>
Set the password. The server and the client should use
the same password.
-m <encrypt_method>
Set the cipher.
Shadowsocks-libev accepts 21 different ciphers:
table, rc4, rc4-md5, aes-128-cfb, aes-192-cfb, aes-256-cfb, aes-128-ctr,
aes-192-ctr, aes-256-ctr, bf-cfb, camellia-128-cfb, camellia-192-cfb,
camellia-256-cfb, cast5-cfb, des-cfb, idea-cfb, rc2-cfb, seed-cfb, salsa20,
chacha20 and chacha20-ietf.
The default cipher is rc4-md5.
If built with PolarSSL or custom OpenSSL libraries, some of these ciphers may
not work.
-a <user_name>
Run as a specific user.
-f <pid_file>
Start shadowsocks as a daemon with specific pid
file.
-t <timeout>
Set the socket timeout in seconds. The default value is
60.
-c <config_file>
Use a configuration file.
-n <number>
Specify max number of open files.
Not available in manager mode.
Only available on Linux.
-i <interface>
Send traffic through specific network interface.
For example, there are three interfaces in your device, which is lo (127.0.0.1),
eth0 (192.168.0.1) and eth1 (192.168.0.2). Meanwhile, you configure
shadowsocks-libev to listen on 0.0.0.0:8388 and bind to eth1. That
results the traffic go out through eth1, but not lo nor eth0. This option is
useful to control traffic in multi-interface environment.
Not available in redir mode.
-b <local_address>
Specify local address to bind.
Not available in server nor manager mode.
-u
Enable UDP relay.
TPROXY is required in redir mode. You may need root permission.
-U
Enable UDP relay and disable TCP relay.
Not available in local mode.
-A
Enable onetime authentication.
-L <addr:port>
Specify destination server address and port for local
port forwarding.
Only available in tunnel mode.
-d <addr>
Setup name servers for internal DNS resolver (libudns).
The default server is fetched from /etc/resolv.conf.
Only available in server and manager mode.
--fast-open
Enable TCP fast open.
Not available in redir nor tunnel mode, with Linux kernel > 3.7.0.
--acl <acl_config>
Enable ACL (Access Control List) and specify config file.
Not available in redir nor tunnel mode.
--manager-address <path_to_unix_domain>
Specify UNIX domain socket address.
Only available in server and manager mode.
--executable <path_to_server_executable>
Specify the executable path of ss-server.
Only available in manager mode.
-v
Enable verbose mode.
-h|--help
Print help message.
CONFIG FILE¶
The config file is written in JSON and easy to edit. The config file equivalent of command line options is listed as example below.Command line | JSON |
-s some.server.net | "server": "some.server.net" |
-s some.server.net -p 1234 (client) | "server": "some.server.net:1234" |
-p 1234 -k "PasSworD" (server) | "port_password": {"1234":"PasSworD"} |
-p 1234 | "server_port": "1234" |
-b 0.0.0.0 | "local_address": "0.0.0.0" |
-l 4321 | "local_port": "4321" |
-k "PasSworD" | "password": "PasSworD" |
-m "aes-256-cfb" | "method": "aes-256-cfb" |
-t 60 | "timeout": 60 |
-a nobody | "user": "nobody" |
--fast-open | "fast_open": true |
--plugin "obfs-server" | "plugin": "obfs-server" |
--plugin-opts "obfs=http" | "plugin_opts": "obfs=http" |
-6 | "ipv6_first": true |
-A | "auth": true |
-n "/etc/nofile" | "nofile": "/etc/nofile" |
-d "8.8.8.8" | "nameserver": "8.8.8.8" |
-L "somedns.net:53" | "tunnel_address": "somedns.net:53" |
-u | "mode": "tcp_and_udp" |
-U | "mode": "udp_only" |
no "-u" nor "-U" options (default) | "mode": "tcp_only" |
EXAMPLE¶
ss-redir requires netfilter’s NAT function. Here is an example:# 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 # Ignore LANs and any other addresses you'd like to bypass the proxy # See Wikipedia and RFC5735 for full list of reserved networks. # See ashi009/bestroutetb for a highly optimized CHN route list. root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 0.0.0.0/8 -j RETURN root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 10.0.0.0/8 -j RETURN root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 127.0.0.0/8 -j RETURN root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 169.254.0.0/16 -j RETURN root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 172.16.0.0/12 -j RETURN root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 192.168.0.0/16 -j RETURN root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 224.0.0.0/4 -j RETURN root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 240.0.0.0/4 -j RETURN # Anything else should be redirected to shadowsocks's local port root@Wrt:~# iptables -t nat -A SHADOWSOCKS -p tcp -j REDIRECT --to-ports 12345 # Add any UDP rules 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 # Start the shadowsocks-redir root@Wrt:~# ss-redir -u -c /etc/config/shadowsocks.json -f /var/run/shadowsocks.pid
PROTOCOL¶
ss-manager(1) provides several APIs through UDP protocol
Send UDP commands in the following format to the manager-address provided to
ss-manager(1):
command: [JSON data]
To add a port:
add: {"server_port": 8001,
"password":"7cd308cc059"}
To remove a port:
remove: {"server_port": 8001}
To receive a pong:
ping
Then ss-manager(1) will send back the traffic statistics:
stat: {"8001":11370}
SEE ALSO¶
ss-local(1), ss-server(1), ss-tunnel(1), ss-redir(1), ss-manager(1), iptables(8), /etc/shadowsocks-libev/config.json12/04/2017 | Shadowsocks-libev 2.6.3 |