cactus-tunnel
v0.3.0
Published
TCP tunnel over WebSocket and Browser
Downloads
23
Maintainers
Readme
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.
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 api.ipify.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/\?format\=json
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
api.ipify: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/\?format\=json
{"ip":"201.xxx.xxx.138"}%
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 port3128
-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.