tcp tunnel over websocket

npm install wstunnel
8 downloads in the last week
23 downloads in the last month


Establish tcp tunnel over web socket connection.


npm install wstunnel


Run the websocket tunnel server at port 8080:

wstunnel -s 8080

Run the websocket tunnel client:

wstunnel -tunnel 33: ws://host:8080

Note in above example, client picks the final tunnel destination, similar to ssh tunnel. Alternatively for security reason, you can lock tunnel destination on server end, example:

    wstunnel -s 8080 -t

    wstunnel -t 33 ws://server:8080

In both examples, connection to localhost:33 on client will be tunneled to on server via websocket connection in between.

Use case

For tunneling over strict firewall.

The tunnel server mode supports plain tcp socket only, for SSL support, use nginx.

Sample setup:

On server: wstunnel -s 8080

On server, run nginx (>=1.3.13) with sample configuration:

server {
    listen   443;

    ssl  on;
    ssl_certificate  /path/to/my.crt
    ssl_certificate_key  /path/to/my.key
    ssl_session_timeout  5m;
    ssl_protocols  SSLv2 SSLv3 TLSv1;
    ssl_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
    ssl_prefer_server_ciphers   on;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header        Host            $host;
        proxy_set_header        X-Real-IP       $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header        X-Forwarded-Proto $scheme;

On client: wstunnel -t 99:targethost:targetport wss://


If you are using self signed certificate on server end for ssl connection, add following line:

rejectUnauthorized : false

to ./node_modules/websocket/lib/WebSocketClient.js line 246. Then launch client again.

npm loves you