net/shadowsocks-libev/README.md

   1 ## components
   2
   3 `ss-local` provides SOCKS5 proxy.
   4
   5          socks5                                     ss              plain
   6         --------> tcp:udp:local_address:local_port ----> ss server -------> dest
   7
   8 `ss-redir`.  The REDIRECT and TPROXY part are to be provided by `ss-rules` script.  REDIRECT only works for tcp traffic (see also darkk/redsocks).  TPROXY is used to proxy udp messages, but it's only available in the PREROUTING chain and as such cannot proxy local out traffic.
   9
  10           plain             plain                                 ss              plain
  11         ---------> REDIRECT ------> tcp:local_address:local_port ----> ss server -----> original dest
  12
  13           plain            plain                                 ss              plain
  14         ---------> TPROXY -------> udp:local_address:local_port -----> ss server -----> original dest
  15
  16 `ss-tunnel` provides ssh `-L` local-forwarding-like tunnel.  Typically it's used to tunnel DNS traffic to the remote.
  17
  18           plain                                       ss               plain
  19         ---------> tcp|udp:local_address:local_port ------> ss server -------> tunnel_address
  20
  21 `ss-server`, the "ss server" in the above diagram
  22
  23 ## uci
  24
  25 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.
  26
  27 Every section have a `disabled` option to temporarily turn off the component instance or component instances referring to it.
  28
  29 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).
  30
  31 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.
  32
  33 We can have multiple instances of component and `server` sections.  The relationship between them is many-to-one.  This will have the following implications
  34
  35  - It's possible to have both `ss_local` and `ss_redir` referring to the same `server` definition
  36  - 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
  37
  38 `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`
  39
  40         redir_tcp               name of ss_redir section with mode tcp_only or tcp_and_udp
  41         redir_udp               name of ss_redir section with mode udp_only or tcp_and_udp
  42
  43         --- incoming packets having source address in
  44
  45         src_ips_bypass          will bypass the redir chain
  46         src_ips_forward         will always go through the redir chain
  47         src_ips_checkdst        will continue to have their destination addresses checked
  48
  49         --- otherwise, the default action can be specified with
  50
  51         src_default             bypass, forward, [checkdst]
  52
  53         --- for local out tcp packets, the default action can be specified with
  54
  55         local_default           [bypass], forward, checkdst
  56
  57         --- if the previous check result is checkdst,
  58         --- then packets having destination address in
  59
  60         dst_ips_bypass_file
  61         dst_ips_bypass          will bypass the redir chain
  62         dst_ips_forward_file
  63         dst_ips_forward         will go through the redir chain
  64
  65 ## notes and faq
  66
  67 Useful paths and commands for debugging
  68
  69         # check current running status
  70         ubus call service list '{"name": "shadowsocks-libev"}'
  71         ubus call service list '{"name": "shadowsocks-libev", "verbose": true}'
  72
  73         # dump validate definition
  74         ubus call service validate '{"package": "shadowsocks-libev"}'
  75         ubus call service validate '{"package": "shadowsocks-libev"}' \
  76                 | jsonfilter -e '$["shadowsocks-libev"]["ss_tunnel"]'
  77
  78         # check json config
  79         ls -l /var/etc/shadowsocks-libev/
  80
  81         # set uci config option verbose to 1, restart the service and follow the log
  82         logread -f
  83
  84 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`
  85
  86 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