net/shadowsocks-libev/README.md

   1 Skip to [recipes](#recipes) for quick setup instructions
   2
   3 # components
   4
   5 `ss-local` provides SOCKS5 proxy with UDP associate support.
   6
   7          socks5                                     ss              plain
   8         --------> tcp:local_address:local_port ----> ss server -------> dest
   9
  10 `ss-redir`.  The REDIRECT and TPROXY part are to be provided by `ss-rules` script.  REDIRECT is for tcp traffic (`SO_ORIGINAL_DST` only supports TCP).  TPROXY is for udp messages, but it's only available in the PREROUTING chain and as such cannot proxy local out traffic.
  11
  12           plain             plain                                 ss              plain
  13         ---------> REDIRECT ------> tcp:local_address:local_port ----> ss server -----> original dest
  14
  15           plain            plain                                 ss              plain
  16         ---------> TPROXY -------> udp:local_address:local_port -----> ss server -----> original dest
  17
  18 `ss-tunnel` provides ssh `-L` local-forwarding-like tunnel.  Typically it's used to tunnel DNS traffic to the remote.
  19
  20           plain                                       ss               plain
  21         ---------> tcp|udp:local_address:local_port ------> ss server -------> tunnel_address
  22
  23 `ss-server`, the "ss server" in the above diagram
  24
  25 # uci
  26
  27 Option names are the same as those used in json config files.  Check `validate_xxx` func definition of the [service script](files/shadowsocks-libev.init) and shadowsocks-libev's own documentation for supported options and expected value types.  A [sample config file](files/shadowsocks-libev.config) is also provided for reference.
  28
  29 Every section have a `disabled` option to temporarily turn off the component instance or component instances referring to it.
  30
  31 Section type `server` is for definition of remote shadowsocks servers.  They will be referred to from other component sections and as such should be named (as compared to anonymous section).
  32
  33 Section type `ss_local`, `ss_redir`, `ss_tunnel` are for specification of shadowsocks-libev components.  They share mostly a common set of options like `local_port`, `verbose`, `fast_open`, `timeout`, etc.
  34
  35 Plugin options should be specified in `server` section and will be inherited by other compoenents referring to it.
  36
  37 We can have multiple instances of component and `server` sections.  The relationship between them is many-to-one.  This will have the following implications
  38
  39  - It's possible to have both `ss_local` and `ss_redir` referring to the same `server` definition
  40  - It's possible to have multiple instances of `ss_redir` listening on the same address:port with `reuse_port` enabled referring to the same or different `server` sections
  41
  42 `ss_rules` section is for configuring the behaviour of `ss-rules` script.  There can only exist at most one such section with the name also being `ss_rules`
  43
  44         redir_tcp               name of ss_redir section with mode tcp_only or tcp_and_udp
  45         redir_udp               name of ss_redir section with mode udp_only or tcp_and_udp
  46         ifnames                 only apply rules on packets from these ifnames
  47
  48         --- for incoming packets having source address in
  49
  50         src_ips_bypass          will bypass the redir chain
  51         src_ips_forward         will always go through the redir chain
  52         src_ips_checkdst        will continue to have their destination addresses checked
  53
  54         --- otherwise, the default action can be specified with
  55
  56         src_default             bypass, forward, [checkdst]
  57
  58         --- if the previous check result is checkdst,
  59         --- then packets having destination address in
  60
  61         dst_ips_bypass_file
  62         dst_ips_bypass          will bypass the redir chain
  63         dst_ips_forward_file
  64         dst_ips_forward         will go through the redir chain
  65
  66         --- otherwise, the default action can be specified with
  67
  68         dst_default             [bypass], forward
  69
  70         --- for local out tcp packets, the default action can be specified with
  71
  72         local_default           [bypass], forward, checkdst
  73
  74 Bool option `dst_forward_recentrst` requires iptables/netfilter `recent` match module (`opkg install iptables-mod-conntrack-extra`).  When enabled, `ss-rules` will setup iptables rules to forward through `ss-redir` those packets whose destination have recently sent to us multiple tcp-rst.
  75
  76 ss-rules uses kernel ipset mechanism for storing addresses/networks.  Those ipsets are also part of the API and can be populated by other programs, e.g. dnsmasq with builtin ipset support.  For more details please read output of `ss-rules --help`
  77
  78 Note also that `src_ips_xx` and `dst_ips_xx` actually also accepts cidr network representation.  Option names are retained in its current form for backward compatibility coniderations
  79
  80 # incompatible changes
  81
  82 | Commit date | Commit ID | Subject | Comment |
  83 | ----------- | --------- | ------- | ------- |
  84 | 2019-05-09  | afe7d3424 | shadowsocks-libev: move plugin options to server section | This is a revision against c19e949 committed 2019-05-06 |
  85 | 2017-07-02  | b61af9703 | shadowsocks-libev: rewrite | Packaging of shadowsocks-libev was rewritten from scratch |
  86
  87 # notes and faq
  88
  89 Useful paths and commands for debugging
  90
  91         # check current running status
  92         ubus call service list '{"name": "shadowsocks-libev"}'
  93         ubus call service list '{"name": "shadowsocks-libev", "verbose": true}'
  94
  95         # dump validate definition
  96         ubus call service validate '{"package": "shadowsocks-libev"}'
  97         ubus call service validate '{"package": "shadowsocks-libev"}' \
  98                 | jsonfilter -e '$["shadowsocks-libev"]["ss_tunnel"]'
  99
 100         # check json config
 101         ls -l /var/etc/shadowsocks-libev/
 102
 103         # set uci config option verbose to 1, restart the service and follow the log
 104         logread -f
 105
 106 ss-redir needs to open a new socket and setsockopt IP_TRANSPARENT when sending udp reply to client.  This requires `CAP_NET_ADMIN` and as such the process cannot run as `nobody`
 107
 108 ss-local, ss-redir, etc. supports specifying an array of remote ss server, but supporting this in uci seems to be overkill.  The workaround can be defining multiple `server` sections and multiple `ss-redir` instances with `reuse_port` enabled
 109
 110 # recipes
 111
 112 ## forward all
 113
 114 This will setup firewall rules to forward almost all incoming tcp/udp and locally generated tcp traffic (excluding those to private addresses like 192.168.0.0/16 etc.) through remote shadowsocks server
 115
 116 Install components.
 117 Retry each command till it succeed
 118
 119         opkg install shadowsocks-libev-ss-redir
 120         opkg install shadowsocks-libev-ss-rules
 121         opkg install shadowsocks-libev-ss-tunnel
 122
 123 Edit uci config `/etc/config/shadowsocks-libev`.
 124 Replace `config server 'sss0'` section with parameters of your own remote shadowsocks server.
 125 As for other options, change them only when you know the effect.
 126
 127         config server 'sss0'
 128                 option disabled 0
 129                 option server '_sss_addr_'
 130                 option server_port '_sss_port_'
 131                 option password '********'
 132                 option method 'aes-256-cfb'
 133
 134         config ss_tunnel
 135                 option disabled 0
 136                 option server 'sss0'
 137                 option local_address '0.0.0.0'
 138                 option local_port '8053'
 139                 option tunnel_address '8.8.8.8:53'
 140                 option mode 'tcp_and_udp'
 141
 142         config ss_redir ssr0
 143                 option disabled 0
 144                 option server 'sss0'
 145                 option local_address '0.0.0.0'
 146                 option local_port '1100'
 147                 option mode 'tcp_and_udp'
 148                 option reuse_port 1
 149
 150         config ss_rules 'ss_rules'
 151                 option disabled 0
 152                 option redir_tcp 'ssr0'
 153                 option redir_udp 'ssr0'
 154                 option src_default 'checkdst'
 155                 option dst_default 'forward'
 156                 option local_default 'forward'
 157
 158 Restart shadowsocks-libev components
 159
 160         /etc/init.d/shadowsocks-libev restart
 161
 162 Check if things are in place
 163
 164         iptables-save | grep ss_rules
 165         netstat -lntp | grep -E '8053|1100'
 166         ps ww | grep ss-
 167
 168 Edit `/etc/config/dhcp`, making sure options are present in the first dnsmasq section like the following to let it use local tunnel endpoint for upstream dns query.
 169 Option `noresolv` instructs dnsmasq to not use other dns servers like advertised by local isp.
 170 Option `localuse` intends to make sure the device you are configuring also uses this dnsmasq instance as the resolver, not the ones from other sources.
 171
 172         config dnsmasq
 173                 ...
 174                 list server '127.0.0.1#8053'
 175                 option noresolv 1
 176                 option localuse 1
 177
 178 Restart dnsmasq
 179
 180         /etc/init.d/dnsmasq restart
 181
 182 Check network on your computer
 183
 184         nslookup www.google.com
 185         curl -vv https://www.google.com