README_EN.md

nysocks

使用简介

Nysocks binds kcp and libuv to provide a tcp tunnel in nodejs.

• Features
  • Aggresive ARQ makes it works better than TCP in environments where packets loss always happens.
  • Support both SOCKS5 and SS protocols.
  • Encrypt transmission.

Proxy tests from a Linode instance(Tokyo 2, JP) where 10% packet loss always happens when trasmitting data from to China mainland:

tcp proxy:

nysocks fast2 mode:

How it works

for SOCKS client

for SS client

protocol(unstable):

NOTE: The protocol of nysocks has been changed from v2.0.0 so that you have to install nysocks v2.0.x in both of your client and server.

+-------+-----+-----+---------+---------+--------+------------+
|  kcp  | ver | cmd |  nonce  | mux.cmd | mux.id | mux.length |
+-------+-----+-----+---------+---------+--------+------------+
|  24   |  1  |  1  |    8    |    1    |    2   |     4      |
+-------+-----+-----+---------+---------+--------+------------+

TODO: Pass error code.

About the Tunnel Implementation

The tunnel connections in nysocks is implemented as a node-addon(C/CPP) mainly because:

0. Node don't support setting send/recv buffer size of udp connections before v8.7.0.
1. In large data transmissions, udp message callback is too frequently and manipulating buffers in js(or any other script languages) is relatively expensive which would make the total performace unacceptable. You can check my pure js implementation here.

Installation

node >= 6.x

Make sure you have node-gyp installed successfully as nysocks will build C/CPP code, then:

npm i nysocks -g

Or check the executable here.

Usage

1. Create server service

In your server, start nysocks with server command:

nysocks server -p 20000 -k YOUR_PASSWORD -m fast

2. Create client service

In your client, start nysocks with client command to create a tunnel client that will connect to your server and provide proxy service:

nysocks client -a YOUR_SERVER_HOST -p 20000 -k YOUR_PASSWORD -m fast

Nysocks will start a SOCKS5 service to tunnel your tcp connections. Now you can utilize the SOCKS5 service (default port 1080). A PAC file server will also be served(default port 8090) for convenience.

Use SS Protocol

Nysocks supports using shadowsocks protocol to replace SOCKS5 protocol in your client:

nysocks client -a YOUR_SERVER_HOST -p 20000 -k YOUR_PASSWORD -m fast --client_protocol SS --ss_password YOUR_SS_PASSWORD --ss_method aes-128-cfb

Check the ssServer from encryptsocks for more details.

3. Use config.json

You can create a config.json file like this that containing your configs to avoid verbose cli options:

nysocks client -c config.json

4. Use daemons

Add -d options if you want to run under daemons(pm2):

nysocks client -d restart -c config.json

5. Check other options

Modify your options in the CLI. See other options here:

nysocks -h

Configs

CLI:

nysocks <command>

Commands:
  nysocks server  Start a tunnel server.
  nysocks client  Start a tunnel client.

Options:
  --version                Show version number                         [boolean]
  --config, -c             The path of a json file that describe your
                           configuration.
  --daemon, -d             Run with a daemon(pm2): start, stop, restart.
  --daemon_status, -s      Show daemoned(pm2) processes status
  --mode, -m               Like kcptun: normal, fast, fast2, fast3.
  --password, -k           The passowrd/key for the encryption of transmissio.
  --socket_amount          The amount of connections to be created for each
                           client (default: 10)
  --server_addr, -a        The host of your server.
  --server_port, -p        The port of your server.
  --client_protocol, --cp  The protocol that will be used by clients: SS, SOCKS
                           (default: SOCKS)
  --socks_port             Specify the local port for SOCKS service (default:
                           1080)
  --ss_port                Specify the local port for ssServer service (default:
                           8083)
  --ss_password            Specify the key for the encryption of ss
  --ss_method              Specify the method of the encryption for ss (default:
                           aes-128-cfb)
  --log_path               The file path for logging. If not set, will log to
                           the console.
  --log_memory             Log memory info.
  --log_conn               Log connections info.
  --help                   Show help                                   [boolean]

config.json example:

{
  "serverAddr": "YOUR_SERVER_HOST",
  "serverPort": 20000,
  "socketAmount": 20,
  "password": "YOUR_PASSWORD",
  "kcp": {
    "sndwnd": 1024,
    "rcvwnd": 1024,
    "nodelay": 0,
    "interval": 30,
    "resend": 2,
    "nc": 1
  },
  "pac": {
    "pacServerPort": 8090
  },
  "clientProtocol": "SOCKS",
  "SOCKS": {
    "port": 1080
  },
  "SS": {
    "password": "YOUR_SS_PASSWORD",
    "method": "aes-128-cfb",
    "serverPort": 8083,
  }
}

How to utilize the SOCKS5 service

Most OSes support SOCKS5 proxy by default:

Use chrome extensions like SwitchyOmega to help browse web pages by proxy.

How to utilize the SS service

Install clients in your devices and connecting to the ssServer set up by nysocks.

Encryption

aes_256_cbc

Known Issues

• Do not support ipv6 currently.
• Changing the ip of the client will disconnect all the connections temporary.

References

• kcptun - A Secure Tunnel Based On KCP with N:M Multiplexing
• kcp - A Fast and Reliable ARQ Protocol
• C++ and Node.js Integration

LICENSE

BSD