README.md

Cactus Tunnel

🌵 A charming TCP tunnel over WebSocket and Browser.

_{Built with ❤︎ by jeffreytse and contributors}

Hey, nice to meet you, you found this charming tool. Here the Cactus Tunnel is a TCP tunnel tool over WebSocket and Browser. It can help you open a TCP tunnel to another side of the world through the browser in an extremely restricted environment, just like a cactus under the scorching sun to absorb nutrients in the endless desert. If you are a thirsty and honey geek and focus on finding new hydration, don't miss it.

Like this charming tool? You can give it a star or sponsor me!
I will respect your crucial support and say THANK YOU!

Installation

Install the tool from NPM:

npm install -g cactus-tunnel

Usages

The help instructions of this tool:

$ cactus-tunnel help

Usage: cactus-tunnel help [command]

TCP tunnel over websocket and browser

Options:
  -V, --version                       output the version number
  -h, --help                          display help for command

Commands:
  client [options] <server> <target>  runs cactus-tunnel in client mode
  server [options]                    runs cactus-tunnel in server mode
  help [command]                      display help for command

Tunnel Server

The help instructions of tunnel server:

$ cactus-tunnel help server

Usage: cactus-tunnel server [options]

runs cactus-tunnel in server mode

Options:
  -p, --port <port>         tunnel server listening port (default: 7800)
  -h, --hostname <address>  tunnel server listening hostname (default: "0.0.0.0")
  -v, --verbose             enable verbose output
  --help                    display help for command

Start a tunnel server:

cactus-tunnel server

Tunnel Client

The help instructions of tunnel client:

$ cactus-tunnel help client

Usage: cactus-tunnel client [options] <server> <target>

runs cactus-tunnel in client mode

Arguments:
  server                            tunnel server url, empty is bridge mode, e.g.
                                    ws://your-tunnel-server:7800
  target                            tunnel target url, e.g. your-linux-ssh-server:22

Options:
  -p, --port <port>                 tunnel client listening port (default: 7700)
  -h, --hostname <address>          tunnel client listening hostname (default: "127.0.0.1")
  -b, --bridge-mode                 enable tunnel bridge mode
  -nb, --no-browser                 disable auto open browser when in bridge mode
  -bp, --bridge-port <port>         tunnel bridge listening port (default: 7900)
  -bh, --bridge-hostname <address>  tunnel bridge listening hostname (default: "0.0.0.0")
  -v, --verbose                     enable verbose output
  --help                            display help for command

Request External API Services

Start a tunnel client:

cactus-tunnel client -b ws://<your-tunnel-server>:7800 ip-api.com:80

This command will start a server at address localhost:7700 in bridge mode, and open the tunnel bridge on the web browser.

curl http://localhost:7700/json/8.8.8.8

When you connect to the port 7700, it will auto connect to the specified tunnel server <your-tunnel-server>:7800 and connect to target host ip-api.com:80, you will get your server ip address through the IP API lookup service, the response content is similar as below:

$ curl http://localhost:7700/json/8.8.8.8 | jq
{
  "status": "success",
  "country": "United States",
  "countryCode": "US",
  "region": "VA",
  "regionName": "Virginia",
  "city": "Ashburn",
  "zip": "20149",
  "lat": 39.03,
  "lon": -77.5,
  "timezone": "America/New_York",
  "isp": "Google LLC",
  "org": "Google Public DNS",
  "as": "AS15169 Google LLC",
  "query": "8.8.8.8"
}

SSH SOCKS5 Proxy

Start a tunnel client:

cactus-tunnel client -b ws://<your-tunnel-server>:7800 <your-ssh-server>:22

This command will start a server at address localhost:7700 in bridge mode, and open the tunnel bridge on the web browser.

ssh -p 7700 -D 3128 -C -N <your-username>@localhost

• -D 3128: open a SOCKS5 proxy on local port 3128
• -C: compress data in the tunnel, save bandwidth
• -N: do not execute remote commands, useful for just forwarding ports

When you connect to the port 7700, it will auto connect to the specified tunnel server localhost:7800 and connect to target host <your-ssh-server>:22 Now you have an SSH tunnel between your computer and the remote host, in this example <your-ssh-server>:22.

Import the package

A simple example:

import cactusTunnel from "cactus-tunnel";

const options = {
  port: 1234,
  hostname: localhost,
};

const server = new cactusTunnel.Server({
  listen: {
    port: options.port,
    hostname: options.hostname,
  },
  logger: {
    silent: options.verbose ? false : true,
  },
});

console.info(`server listening at: http://${options.hostname}:${options.port}`);

Development

To set up your environment to develop this tool, run npm install.

Your environment is setup just like a normal node project! To test your project, run npm start:cli help. This shows help instructions of CLI tool. You can edit the source code under src, bin, test, etc. like normal to test NodeJS project. As you make modifications to the source code and configuration files, you need to rerun the command and you should see the changes, just like normal.

Contributing

Issues and Pull Requests are greatly appreciated. If you've never contributed to an open source project before I'm more than happy to walk you through how to create a pull request.

You can start by opening an issue describing the problem that you're looking to resolve and we'll go from there.

Credits

• express - Fast, unopinionated, minimalist web framework for node.
• websocket-stream - WebSockets with the node stream API.
• pump - Pipe streams together and close all of them if one of them closes.
• winston - A logger for just about everything.

License

This theme is licensed under the MIT license © JeffreyTse.