Skip to content

Latest commit

 

History

History
268 lines (169 loc) · 8.55 KB

readme.md

File metadata and controls

268 lines (169 loc) · 8.55 KB
Raw

✨ hypertunnel Build Status

When localtunnel/ngrok is not enough.

This free TCP relay/reverse proxy service can be used to expose any TCP/IP service running behind a NAT. It's using hypertunnel-tcp-relay under the hood, which itself is based on the excellent node-tcp-relay from tewarid, adding self-service multi-client support similar to localtunnel, a cool project name with "hyper" in it and a free public server.

Installation

# Use directly with no installation (npx is part of npm):
❯❯❯ npx hypertunnel --port 8080

# Or install globally:
❯❯❯ npm install -g hypertunnel

Usage

❯❯❯ hypertunnel --help

  Usage: hypertunnel --port 8080 [options]

  Expose any local TCP/IP service on the internet.

  Options:

    -v, --version                output the version number
    -p, --port [port]            local TCP/IP service port to tunnel
    -l, --localhost [localhost]  local server (default: localhost)
    -s, --server [server]        hypertunnel server to use (default: https://hypertunnel.ga)
    -t, --token [token]          token required by the server (default: free-server-please-be-nice)
    -i, --internet-port [port]   the desired internet port on the public server
    --ssl                        enable SSL termination (https://) on the public server    
    -h, --help                   output usage information

Examples (click to expand)

Example Local webserver

Example: Local webserver

Run a static web server in your current directory:

❯❯❯ npx http-server -p 7777

In another terminal window create a hypertunnel to make that server accessible from the internet:

❯❯❯ npx hypertunnel -p 7777

Et voila:

  ✨ Hypertunnel created.

  Tunneling hypertunnel.ga:19432 > localhost:7777

Bonus: Free SSL termination (https://)

Run hypertunnel with the --ssl flag, to let it know you wish for https support (with a valid certificate):

❯❯❯ npx hypertunnel@latest -p 7777 --ssl
  ✨ Hypertunnel created.

  Tunneling https://hypertunnel.ga:26949 > localhost:7777

SSL is not enabled by default as it makes mostly sense for HTTP servers, which is not the sole use-case for hypertunnel. :-)

Tip: Run commands in parallel

You can use bash niceties to run mutiple commands in parallel and stop all of them when hitting ctrl+c:

❯❯❯ (npx http-server -p 7777 & npx hypertunnel --port 7777 --ssl)
Example Remote SSH login

Example: Remote SSH login

As hypertunnel is a generic TCP/IP relay, why not use it for something different than a webserver.

Say you're running MacOS or Linux on your workstation and you want to quickly ssh into it from anywhere.

Note: Make sure your local SSH daemon is running (macOS instructions).

# Create a tunnel for the local SSH service running on port 22
❯❯❯ npx hypertunnel --port 22

Use the hypertunnel to SSH into that machine, from anywhere:

# Example, adjust the port based on the previous output:
❯❯❯ ssh hypertunnel.ga -p 21357
Warning: Permanently added 'hypertunnel.ga:21357' (ECDSA) to the list of known hosts.
Password:
Example Run and expose a local telnet chat server

Example: Run and expose a local telnet chat server

❯❯❯ npx netchat server -p 3000

In another terminal:

❯❯❯ npx hypertunnel -p 3000

From anywhere:

❯❯❯ telnet hypertunnel.ga 31967
Trying 159.69.23.189...
Connected to hypertunnel.ga.
Escape character is '^]'.
bob
Welcome, ::ffff:127.0.0.1:56252
Type "quit" to exit.

Enter username: You are now bob
> hello world
> _

Comparison to localtunnel/ngrok

Both are great services! If your use-case is to simply tunnel local http web server traffic I suggest using them. :-)

I ran into issues when trying to expose a local proxy server (to use the client as forwarding proxy). Both services need to inspect and rewrite HTTP headers for routing, so using the tunnel as a proxy in e.g. Chrome won't work. There are a couple other use-cases where raw TCP stream tunnelling is desired and hypertunnel is the only available option.

Technical differences

Instead of using hostnames to direct traffic to clients, hypertunnel is using a dedicated public port per tunnel. This greatly simplifies things as TCP/IP traffic can be routed based on the assigned port, without http header inspection and rewriting.

Free server: hypertunnel.ga

I really like the simplicity of services like localtunnel & ngrok as they're generously offering a free server. I'm doing the same for hypertunnel but beware of using this free server in mission critical settings. If you'd like to offer sponsorship for the public server feel cheered at and please raise a ticket. :-)

PS: You can also self-host a private hypertunnel-server and point the client to it.

Limits

There are currently no enforced usage limits, in the hopes that you will use the server in good faith. Tunnels are destroyed when you exit the client and latest after 24 hours of creation.

Status

It's doing what it says on the tin. Certain things could be improved and battle-hardened. It works for my current use-case so please raise an issue if you encounter problems.

The CLI interface is stable, but programmatic usage comes with no warranty as internals might change in the future (the internals are also not properly documented currently).

Have a look at the tests to get an idea of how to use hypertunnel programmatically.

Given that there is no alternative to hypertunnel I figured I'd rather release it early. :-)

Contributing

Contributions are welcome.

We use a monorepo powered by Lerna (and yarn workspaces), ava for testing and the standard style for linting.

Monorepo cheat sheet 
# Make sure you have a recent version of yarn & lerna installed:
npm install -g yarn lerna

# Bootstrap the packages in the current Lerna repo. 
# Installs all of their dependencies and links any cross-dependencies.
yarn bootstrap

# Install debug in all packages
lerna add debug

# Install debug in all packages as dev dependency
lerna add --dev debug

# Install fs-extra to hypertunnel-server
lerna add fs-extra --scope=hypertunnel-server

# Remove dependency
# https://github.com/lerna/lerna/issues/833
lerna exec -- yarn remove fs-extra

# Run test in all packages
yarn test

Todo

server & client

  • Hook into hypertunnel-tcp-relay events for better cleanup, error reporting and to show established connections
  • Support environment variables next to cli params

client

  • Support --basic-auth flag as a simple way to secure a local http server
  • Add --timeout flag, so a tunnel will self-destruct after a specified delay

server

  • Use e.g. redis or message passing for tunnel manager data to support clustering
  • Battle-hardening (e.g. rate-limits to keep bad actors out) - don't make this a necessity please ಠ_ಠ

Related

License

MIT