Skip to content

Commit

Permalink
Improve README and logging
Browse files Browse the repository at this point in the history
  • Loading branch information
@boronine
boronine committed Oct 15, 2024
1 parent 5d2a100 commit 7537f66
Show file tree
Hide file tree
Showing 5 changed files with 131 additions and 137 deletions.
45 changes: 23 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,66 +3,67 @@
![NPM Version](https://img.shields.io/npm/v/h2tunnel)
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/boronine/h2tunnel/node.js.yml)

A low level tool for a popular "tunneling" workflow, similar to the proprietary [ngrok](https://ngrok.com/)
A CLI tool and Node.js library for a popular "tunneling" workflow, similar to the proprietary [ngrok](https://ngrok.com/)
or the openssh-based `ssh -L` solution. All in [less than 600 LOC](https://github.com/boronine/h2tunnel/blob/main/src/h2tunnel.ts)
with no dependencies.

![Diagram](https://raw.githubusercontent.com/boronine/h2tunnel/main/diagram.drawio.svg)]
![Diagram](https://raw.githubusercontent.com/boronine/h2tunnel/main/diagram.drawio.svg)

## The "tunneling" workflow

This workflow allows exposing your localhost development server to the internet. This requires a server component
hosted on a public IP address, and a client component running on your local machine. The client establishes a tunnel
to the server, and the server acts as a reverse proxy, tunneling requests back to your local machine.
to the server, and the server proxies requests through this tunnel to your local machine.

## How does h2tunnel work?

1. The client initiates a TLS connection (tunnel) to the server
2. The server takes the newly created TLS socket and tunnels an HTTP2 session through it back to the client
3. The client listens for an HTTP2 connection on the socket from which it initiated the TLS tunnel
4. The server starts accepting HTTP1 requests and converts them into HTTP2 requests before sending them to the client
5. The client receives these HTTP2 requests and converts them back into HTTP1 requests to feed them into the local server
1. The client initiates a TLS connection to the server and starts listening for HTTP2 sessions on it
2. The server takes the newly created TLS socket and initiates an HTTP2 session through it
3. The server starts accepting HTTP1 requests, converting them into HTTP2 requests, and fowarding them to the client
4. The client receives these HTTP2 requests and converts them back into HTTP1 requests to feed them into the local server

The reason for using HTTP2 is that it allows multiplexing: processing simultaneous HTTP requests over a single connection.
By using HTTP2 we avoid having to reinvent this wheel.
Converting between HTTP1 and HTTP2 is necessary to take advantage of HTTP2's multiplexing capabilities. This feature of
the protocol allows simultaneous requests to be processed on a single TCP connection.

Similarly we avoid having to reinvent authentication by using a self-signed TLS certificate + private key pair. This
pair is used by both the client and the server, and both are configured to reject any other certificate. This way, the
pair effectively becomes a shared password.
For authentication we use a self-signed TLS certificate + private key pair. This pair is used by both the client and
the server, and both are configured to reject anything else. This way, the pair effectively becomes a shared password.

## Usage

### Forward localhost:8000 to http://example.com

Generate `.key` and `.crt` files. These will be used by both client and server to authenticate each other.
Generate `h2tunnel.key` and `h2tunnel.crt` files using `openssl` command:

```bash
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -days 3650 -nodes -keyout h2tunnel.key -out h2tunnel.crt -subj "/CN=example.com"
```

### Forward localhost:8000 to http://example.com

On your server (example.com), we will be listening for tunnel connections on port 15001, and providing an HTTP proxy
on port 80. Make sure these are open in your firewall. `--mux-listen-port` can be any available port, it is necessary
to run a local HTTP2 multiplexer (always bound to 127.0.0.1).
on port 80. Make sure these are open in your firewall.

Use any port for `--mux-listen-port`, h2tunnel will run an HTTP2 multiplexer on this port bound to 127.0.0.1,
it will not be exposed to the internet even if your firewall allows it.

```bash
sudo h2tunnel server \
--crt h2tunnel.crt \
--key h2tunnel.key \
--tunnel-listen-ip 0.0.0.0 \
--tunnel-listen-port 15001 \
--proxy-listen-port 80 \
--proxy-listen-ip 0.0.0.0 \
--proxy-listen-port 80 \
--mux-listen-port=15002
````

On your local machine, we will connect to the tunnel and forward a local HTTP server on port 8000. `--demux-listen-port`
can be any available port, it is necessary to run a local HTTP2 demultiplexer (always bound to 127.0.0.1).
On your local machine, we will connect to the tunnel and forward a local HTTP server on port 8000.

Use any port for `--demux-listen-port`, h2tunnel will run an HTTP2 demultiplexer on it.

```bash
python3 -m http.server # runs on port 8000
h2tunnel client \
--key h2tunnel.key \
--crt h2tunnel.crt \
--key h2tunnel.key \
--tunnel-host=example.com \
--tunnel-port=15001 \
--local-http-port=8000 \
Expand Down
57 changes: 27 additions & 30 deletions diagram.drawio
View file
Original file line number Diff line number Diff line change
@@ -1,50 +1,47 @@
<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36" version="24.7.17">
<diagram name="Page-1" id="Whb8RC3Au8cvX3wrGirA">
<mxGraphModel dx="931" dy="605" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<mxGraphModel dx="894" dy="581" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-29" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;remote&lt;/span&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="480" y="30" width="260" height="300" as="geometry" />
<mxCell id="vVhd3XwVl_YpVuTGVh2o-1" value="" style="rounded=0;whiteSpace=wrap;html=1;strokeColor=none;" vertex="1" parent="1">
<mxGeometry x="160" y="10" width="540" height="340" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-25" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP1 Server&lt;/span&gt;&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;+ HTTP2 Client&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="610" y="80" width="120" height="240" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-29" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;remote&lt;/span&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;fillColor=#B3B3B3;strokeColor=none;" parent="1" vertex="1">
<mxGeometry x="460" y="30" width="220" height="300" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-27" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;localhost&lt;/span&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="70" y="30" width="390" height="300" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-25" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP1 Server&lt;/span&gt;&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP2 Client&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;fillColor=#FFB366;strokeColor=none;" parent="1" vertex="1">
<mxGeometry x="570" y="80" width="100" height="240" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-28" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP1 Server&lt;/span&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="80" y="140" width="120" height="160" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-27" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;local&lt;/span&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;fillColor=#CCCCCC;strokeColor=none;" parent="1" vertex="1">
<mxGeometry x="180" y="30" width="280" height="300" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-21" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP2 Server&lt;/span&gt;&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;+ HTTP1 Client&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="210" y="80" width="120" height="240" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-28" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP1&lt;/span&gt;&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;Server&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;fillColor=#A9C4EB;strokeColor=default;" parent="1" vertex="1">
<mxGeometry x="190" y="160" width="60" height="160" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-16" value="&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;TLS&lt;/span&gt;&lt;span style=&quot;text-wrap: nowrap; background-color: initial;&quot;&gt;&amp;nbsp;Client&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="330" y="80" width="120" height="240" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-21" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP2 Server&lt;/span&gt;&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap; background-color: initial;&quot;&gt;HTTP1 Client&lt;/span&gt;&lt;br&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;fillColor=#FFB366;strokeColor=none;" parent="1" vertex="1">
<mxGeometry x="260" y="80" width="90" height="240" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-5" value="" style="ellipse;whiteSpace=wrap;html=1;align=center;aspect=fixed;fillColor=none;strokeColor=none;resizable=0;perimeter=centerPerimeter;rotatable=0;allowArrows=0;points=[];outlineConnect=1;" vertex="1" parent="1">
<mxGeometry x="470" y="130" width="10" height="10" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-16" value="&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;TLS&lt;/span&gt;&lt;span style=&quot;text-wrap: nowrap; background-color: initial;&quot;&gt;&amp;nbsp;Client&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;fillColor=#D5E8D4;strokeColor=none;" parent="1" vertex="1">
<mxGeometry x="350" y="80" width="100" height="240" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-13" value="&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;TLS Server&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="490" y="80" width="120" height="240" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-5" value="" style="ellipse;whiteSpace=wrap;html=1;align=center;aspect=fixed;fillColor=none;strokeColor=none;resizable=0;perimeter=centerPerimeter;rotatable=0;allowArrows=0;points=[];outlineConnect=1;" parent="1" vertex="1">
<mxGeometry x="460" y="130" width="10" height="10" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-2" value="initiation + authentication + encryption" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=top;shape=mxgraph.arrows2.arrow;dy=0;dx=23.08;notch=20.25;rotation=0;fillColor=#fff2cc;strokeColor=#d6b656;horizontal=1;" vertex="1" parent="1">
<mxGeometry x="340" y="110" width="260" height="190" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-13" value="&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;TLS Server&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;strokeColor=none;fillColor=#D5E8D4;" parent="1" vertex="1">
<mxGeometry x="470" y="80" width="100" height="240" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-19" value="multiplexing&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=top;shape=mxgraph.arrows2.arrow;dy=0;dx=12.75;notch=19.75;flipH=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
<mxGeometry x="220" y="140" width="500" height="150" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-2" value="TLS&lt;div&gt;initiation&amp;nbsp;&lt;div&gt;authentication&amp;nbsp;&lt;/div&gt;&lt;div&gt;encryption&lt;/div&gt;&lt;/div&gt;" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=top;shape=mxgraph.arrows2.arrow;dy=0.02;dx=19.2;notch=17.2;rotation=0;fillColor=#D5E8D4;strokeColor=default;horizontal=1;" parent="1" vertex="1">
<mxGeometry x="370" y="120" width="190" height="190" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-26" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
<mxGeometry x="90" y="170" width="680" height="20" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-19" value="HTTP2&lt;div&gt;multiplexing&lt;div&gt;&lt;br&gt;&lt;/div&gt;&lt;/div&gt;" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=top;shape=mxgraph.arrows2.arrow;dy=0;dx=40.4;notch=35.2;flipH=1;fillColor=#FFB366;strokeColor=default;" parent="1" vertex="1">
<mxGeometry x="290" y="195" width="350" height="105" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-31" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
<mxGeometry x="90" y="200" width="680" height="20" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-26" value="HTTP1" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#A9C4EB;strokeColor=default;" parent="1" vertex="1">
<mxGeometry x="220" y="240" width="470" height="20" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-32" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
<mxGeometry x="90" y="230" width="680" height="20" as="geometry" />
</mxCell>
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-33" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
<mxGeometry x="90" y="260" width="680" height="20" as="geometry" />
<mxCell id="e_OSxrDLTewV0Rg9lFOJ-31" value="HTTP1" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#A9C4EB;strokeColor=default;" parent="1" vertex="1">
<mxGeometry x="220" y="270" width="470" height="20" as="geometry" />
</mxCell>
</root>
</mxGraphModel>
Expand Down
2 changes: 1 addition & 1 deletion diagram.drawio.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 0 additions & 2 deletions docker-compose.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,6 @@ services:
h2tunnel:
build: .
restart: unless-stopped
cap_add:
- NET_ADMIN
secrets:
- crt
- key
Expand Down
Loading

0 comments on commit 7537f66

Please sign in to comment.