github.com/database64128/shadowsocks-go@v1.10.2-0.20240315062903-143a773533f1/README.md (about)

     1  # shadowsocks-go
     2  
     3  [![Go Reference](https://pkg.go.dev/badge/github.com/database64128/shadowsocks-go.svg)](https://pkg.go.dev/github.com/database64128/shadowsocks-go)
     4  [![Test](https://github.com/database64128/shadowsocks-go/actions/workflows/test.yml/badge.svg)](https://github.com/database64128/shadowsocks-go/actions/workflows/test.yml)
     5  [![Release](https://github.com/database64128/shadowsocks-go/actions/workflows/release.yml/badge.svg)](https://github.com/database64128/shadowsocks-go/actions/workflows/release.yml)
     6  [![shadowsocks-go AUR package](https://img.shields.io/aur/version/shadowsocks-go?label=shadowsocks-go)](https://aur.archlinux.org/packages/shadowsocks-go)
     7  [![shadowsocks-go-git AUR package](https://img.shields.io/aur/version/shadowsocks-go-git?label=shadowsocks-go-git)](https://aur.archlinux.org/packages/shadowsocks-go-git)
     8  [![shadowsocks-go-domain-sets-git AUR package](https://img.shields.io/aur/version/shadowsocks-go-domain-sets-git?label=shadowsocks-go-domain-sets-git)](https://aur.archlinux.org/packages/shadowsocks-go-domain-sets-git)
     9  [![shadowsocks-go-geolite2-country-git AUR package](https://img.shields.io/aur/version/shadowsocks-go-geolite2-country-git?label=shadowsocks-go-geolite2-country-git)](https://aur.archlinux.org/packages/shadowsocks-go-geolite2-country-git)
    10  
    11  A versatile and efficient proxy platform for secure communications.
    12  
    13  ## Features
    14  
    15  - Reference Go implementation of Shadowsocks 2022 and later editions.
    16  - Client and server implementation of SOCKS5, HTTP proxy, and Shadowsocks "none" method.
    17  - Transparent proxy support for Linux.
    18  - Built-in router and DNS resolver with support for extensible routing rules.
    19  - RESTful API for server user management and traffic statistics.
    20  - TCP relay fast path on Linux with `splice(2)`.
    21  - UDP relay fast path on Linux with `recvmmsg(2)` and `sendmmsg(2)`.
    22  
    23  ## Configuration Examples
    24  
    25  All configuration examples and systemd unit files can be found in the [docs](docs) directory.
    26  
    27  ### 1. Shadowsocks 2022 Server
    28  
    29  The `clients` field can be omitted or left empty. A default "direct" client will be automatically added.
    30  
    31  On production servers, you may want to set `udpRelayBatchSize` to a lower value like 8 to reduce memory usage while still benefiting from `recvmmsg(2)` and `sendmmsg(2)`.
    32  
    33  UDP packets may be padded to up to the maximum packet size calculated from `mtu`. If the server may be used from a PPPoE connection, `mtu` should be reduced to 1492. If the client-to-server PMTU is unknown, padding can be completely disabled by setting `paddingPolicy` to `NoPadding`.
    34  
    35  For servers without any user PSKs (single-user mode), the `psk` field specifies the PSK, and the `uPSKStorePath` field can be omitted or left empty. When one or more user PSKs are specified in the uPSK store file, the `psk` field specifies the identity PSK.
    36  
    37  To add/update/remove users without restarting the server, modify the uPSK store file and send a `SIGUSR1` signal to the server process, or use the RESTful API. Updates from the RESTful API will be saved to the uPSK store file automatically.
    38  
    39  ```json
    40  {
    41      "servers": [
    42          {
    43              "name": "ss-2022",
    44              "listen": ":20220",
    45              "protocol": "2022-blake3-aes-128-gcm",
    46              "enableTCP": true,
    47              "listenerTFO": true,
    48              "enableUDP": true,
    49              "mtu": 1500,
    50              "psk": "qQln3GlVCZi5iJUObJVNCw==",
    51              "uPSKStorePath": "/etc/shadowsocks-go/upsks.json"
    52          }
    53      ]
    54  }
    55  ```
    56  
    57  ```json
    58  {
    59      "Steve": "oE/s2z9Q8EWORAB8B3UCxw==",
    60      "Alex": "hWXLOSW/r/LtNKynrA3S8Q=="
    61  }
    62  ```
    63  
    64  ### 2. Shadowsocks 2022 Client
    65  
    66  By default, the router uses the configured DNS server to resolve domain names and match IP rules. The resolved IP addresses are only used for matching IP rules. Requests are made using the original domain name. To disable IP rule matching for domain names, set `disableNameResolutionForIPRules` to true.
    67  
    68  ```json
    69  {
    70      "servers": [
    71          {
    72              "name": "socks5",
    73              "listen": ":1080",
    74              "protocol": "socks5",
    75              "enableTCP": true,
    76              "listenerTFO": true,
    77              "enableUDP": true,
    78              "mtu": 1500
    79          },
    80          {
    81              "name": "http",
    82              "listen": ":8080",
    83              "protocol": "http",
    84              "enableTCP": true,
    85              "listenerTFO": true
    86          }
    87      ],
    88      "clients": [
    89          {
    90              "name": "ss-2022",
    91              "protocol": "2022-blake3-aes-128-gcm",
    92              "endpoint": "[2001:db8:bd63:362c:2071:a0f6:827:ab6a]:20220",
    93              "enableTCP": true,
    94              "dialerTFO": true,
    95              "enableUDP": true,
    96              "mtu": 1500,
    97              "psk": "oE/s2z9Q8EWORAB8B3UCxw==",
    98              "iPSKs": [
    99                  "qQln3GlVCZi5iJUObJVNCw=="
   100              ]
   101          },
   102          {
   103              "name": "direct",
   104              "protocol": "direct",
   105              "enableTCP": true,
   106              "dialerTFO": true,
   107              "enableUDP": true,
   108              "mtu": 1500
   109          }
   110      ],
   111      "dns": [
   112          {
   113              "name": "cf-v6",
   114              "addrPort": "[2606:4700:4700::1111]:53",
   115              "tcpClientName": "ss-2022",
   116              "udpClientName": "ss-2022"
   117          },
   118          {
   119              "name": "system",
   120              "type": "system"
   121          }
   122      ],
   123      "router": {
   124          "defaultTCPClientName": "ss-2022",
   125          "defaultUDPClientName": "ss-2022",
   126          "geoLite2CountryDbPath": "/usr/share/shadowsocks-go/Country.mmdb",
   127          "domainSets": [
   128              {
   129                  "name": "category-ads-all",
   130                  "type": "gob",
   131                  "path": "/usr/share/shadowsocks-go/ss-go-gob-category-ads-all"
   132              },
   133              {
   134                  "name": "private",
   135                  "type": "gob",
   136                  "path": "/usr/share/shadowsocks-go/ss-go-gob-private"
   137              },
   138              {
   139                  "name": "cn",
   140                  "type": "gob",
   141                  "path": "/usr/share/shadowsocks-go/ss-go-gob-cn"
   142              },
   143              {
   144                  "name": "geolocation-!cn@cn",
   145                  "type": "gob",
   146                  "path": "/usr/share/shadowsocks-go/ss-go-gob-geolocation-!cn@cn"
   147              }
   148          ],
   149          "routes": [
   150              {
   151                  "name": "ads",
   152                  "client": "reject",
   153                  "toDomainSets": [
   154                      "category-ads-all"
   155                  ]
   156              },
   157              {
   158                  "name": "direct",
   159                  "client": "direct",
   160                  "resolver": "cf-v6",
   161                  "toDomainSets": [
   162                      "private",
   163                      "cn"
   164                  ],
   165                  "toPrefixes": [
   166                      "0.0.0.0/8",
   167                      "10.0.0.0/8",
   168                      "100.64.0.0/10",
   169                      "127.0.0.0/8",
   170                      "169.254.0.0/16",
   171                      "172.16.0.0/12",
   172                      "192.0.0.0/24",
   173                      "192.0.2.0/24",
   174                      "192.88.99.0/24",
   175                      "192.168.0.0/16",
   176                      "198.18.0.0/15",
   177                      "198.51.100.0/24",
   178                      "203.0.113.0/24",
   179                      "224.0.0.0/3",
   180                      "::1/128",
   181                      "fc00::/7",
   182                      "fe80::/10",
   183                      "ff00::/8"
   184                  ],
   185                  "toGeoIPCountries": [
   186                      "CN"
   187                  ]
   188              },
   189              {
   190                  "name": "cn-verify-ip",
   191                  "client": "direct",
   192                  "resolver": "system",
   193                  "toDomainSets": [
   194                      "geolocation-!cn@cn"
   195                  ],
   196                  "toMatchedDomainExpectedGeoIPCountries": [
   197                      "CN"
   198                  ]
   199              }
   200          ]
   201      }
   202  }
   203  ```
   204  
   205  ### 3. Feature Showcase
   206  
   207  See [docs/config.json](docs/config.json).
   208  
   209  ## Domain Sets and IP Geolocation Database
   210  
   211  shadowsocks-go has its own domain set file format, because other formats I've seen are all horrible!
   212  
   213  And don't worry, we have a simple conversion tool to convert between different formats: [shadowsocks-go-domain-set-converter](cmd/shadowsocks-go-domain-set-converter/main.go)
   214  
   215  A domain set text file optionally starts with a capacity hint comment. The conversion tool can automatically generate a capacity hint for you. There are 4 types of domain matching rules:
   216  
   217  - `domain:` Match the domain.
   218  - `suffix:` Match the domain and its subdomains.
   219  - `keyword:` Match if the domain contains the keyword.
   220  - `regexp:` Match if the domain matches the regular expression.
   221  
   222  Example of a domain set text file:
   223  
   224  ```
   225  # shadowsocks-go domain set capacity hint 1 6 1 1 DSKR
   226  domain:www.example.net
   227  suffix:example.com
   228  suffix:github.com
   229  suffix:cube64128.xyz
   230  suffix:api.ipify.org
   231  suffix:api6.ipify.org
   232  suffix:archlinux.org
   233  keyword:dev
   234  regexp:^adservice\.google\.([a-z]{2}|com?)(\.[a-z]{2})?$
   235  ```
   236  
   237  When loading a domain set text file, shadowsocks-go loads all suffixes as-is into a single map. This achieves the best balance between startup speed, memory usage and match speed. If you want better performance, you can use the conversion tool to convert the text file to the gob format.
   238  
   239  The gob format is basically the same thing, but has everything binary serialized and uses a trie to store and match suffixes. The conversion tool loads the suffixes to build a suffix trie, and then serializes the trie and the other rules to a gob file. Quite neat, isn't it?
   240  
   241  Of course, I'm not an algorithm guru, so the whole process still has a lot of inefficiencies. But it's good enough for me. If you have brilliant new ideas, please let me know!
   242  
   243  ### Commonly Used Domain Sets
   244  
   245  A set of commonly used domain sets are updated weekly at [shadowsocks-go-domain-sets](https://github.com/database64128/shadowsocks-go-domain-sets) in the release branch. Arch Linux users can install the [shadowsocks-go-domain-sets-git](https://aur.archlinux.org/packages/shadowsocks-go-domain-sets-git/) package from the AUR.
   246  
   247  ### Manually Generate Domain Sets
   248  
   249  To generate domain sets using https://github.com/v2fly/domain-list-community as the source, clone the repository and build the generator, then generate plaintext lists:
   250  
   251  ```bash
   252  ./domain-list-community -exportlists 'google,netflix'
   253  ```
   254  
   255  Use `shadowsocks-go-domain-set-converter` to convert the plaintext lists to domain set files:
   256  
   257  ```bash
   258  shadowsocks-go-domain-set-converter -inDlc google.txt -outGob ss-go-gob-google
   259  shadowsocks-go-domain-set-converter -inDlc netflix.txt -outGob ss-go-gob-netflix
   260  ```
   261  
   262  ### IP Geolocation Database
   263  
   264  shadowsocks-go uses the MaxMind GeoLite2 Country database for IP geolocation. The database can be downloaded from https://github.com/Dreamacro/maxmind-geoip. Arch Linux users can install the [shadowsocks-go-geolite2-country-git](https://aur.archlinux.org/packages/shadowsocks-go-geolite2-country-git/) package from the AUR.
   265  
   266  ## Security
   267  
   268  ### 1. Packet Padding Policy
   269  
   270  Packet padding policies are implemented for the Shadowsocks 2022 protocol. A packet padding policy controls whether to add padding to outgoing packets.
   271  
   272  When adding padding, the MTU is taken into account, so the size of the padded packet won't exceed the MTU. Therefore it is important to set the MTU correctly.
   273  
   274  The padding policy can be configured individually for each Shadowsocks 2022 client and server.
   275  
   276  - `PadPlainDNS`: Add padding if the destination port is 53. (Default)
   277  - `PadAll`: Pad all packets.
   278  - `NoPadding`: No padding.
   279  
   280  ### 2. TCP Reject Policy
   281  
   282  Reject policies are implemented for all TCP servers. A TCP server's reject policy is invoked when an accepted connection fails the protocol's handshake process. Each protocol has its own default reject policy. Custom reject policies can be useful for censorship circumvention servers to evade active probing.
   283  
   284  - `JustClose`: Just close the connection. (Default for cleartext protocols)
   285  - `ForceReset`: Forcibly reset the connection. Many protocols behave this way when invalid data is received. (Default for Shadowsocks 2022)
   286  - `CloseWriteDrain`: Send FIN and keep reading until EOF. This is typically how legacy Shadowsocks servers handle replay.
   287  - `ReplyWithGibberish`: Keep reading and send random garbage after each read returns. This emulates how a legacy Shadowsocks server without replay protection behaves, except it doesn't actually relay the replayed payload.
   288  
   289  ### 3. Unsafe Fallback
   290  
   291  A Shadowsocks 2022 server can be configured to forward TCP connections to a fallback address when the handshake fails. Add the `unsafeFallbackAddress` field to the server block to specify the fallback address. On startup a warning message will be printed to tell you that using this feature "taints" the server. Unsafe fallback only works for TCP connections.
   292  
   293  This feature might be useful when your threat model only includes off-path attackers, and you want to reuse the port or trick probes into thinking the server is something else. An on-path attacker (e.g. a typical censor) can easily tell that the regular traffic does not match the fallback traffic.
   294  
   295  ### 4. Unsafe Stream Prefix
   296  
   297  The unsafe stream prefix feature allows you to configure a pair of pre-shared cleartext prefixes for Shadowsocks 2022 streams. The prefixes are prepended to the request and response streams to trick simple firewalls.
   298  
   299  To use this feature, add `unsafeRequestStreamPrefix` and `unsafeResponseStreamPrefix` to both client and server blocks, and specify the prefixes in base64 encoding. The client and server must agree on the same pair of prefixes. On startup a warning message will be printed to tell you that using this feature "taints" the client and server.
   300  
   301  ## License
   302  
   303  [AGPLv3](LICENSE)