net/shadowsocks-libev/README.md

   1 ## components
   2
   3 `ss-local` provides SOCKS5 proxy with UDP associate support.
   4
   5          socks5                                     ss              plain
   6         --------> tcp: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         ifnames                 only apply rules on packets from these ifnames
  43
  44         --- for incoming packets having source address in
  45
  46         src_ips_bypass          will bypass the redir chain
  47         src_ips_forward         will always go through the redir chain
  48         src_ips_checkdst        will continue to have their destination addresses checked
  49
  50         --- otherwise, the default action can be specified with
  51
  52         src_default             bypass, forward, [checkdst]
  53
  54         --- if the previous check result is checkdst,
  55         --- then packets having destination address in
  56
  57         dst_ips_bypass_file
  58         dst_ips_bypass          will bypass the redir chain
  59         dst_ips_forward_file
  60         dst_ips_forward         will go through the redir chain
  61
  62         --- otherwise, the default action can be specified with
  63
  64         dst_default             [bypass], forward
  65
  66         --- for local out tcp packets, the default action can be specified with
  67
  68         local_default           [bypass], forward, checkdst
  69
  70 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.
  71
  72 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`
  73
  74 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
  75
  76 ## notes and faq
  77
  78 Useful paths and commands for debugging
  79
  80         # check current running status
  81         ubus call service list '{"name": "shadowsocks-libev"}'
  82         ubus call service list '{"name": "shadowsocks-libev", "verbose": true}'
  83
  84         # dump validate definition
  85         ubus call service validate '{"package": "shadowsocks-libev"}'
  86         ubus call service validate '{"package": "shadowsocks-libev"}' \
  87                 | jsonfilter -e '$["shadowsocks-libev"]["ss_tunnel"]'
  88
  89         # check json config
  90         ls -l /var/etc/shadowsocks-libev/
  91
  92         # set uci config option verbose to 1, restart the service and follow the log
  93         logread -f
  94
  95 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`
  96
  97 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