Skip to content

Commit d08a366

Browse files
mmatczukmmatczuk
authored
Merge pull request #13 from mmatczuk/mmt/readme_update
Readme update
2 parents 3d073a2 + d78f983 commit d08a366

4 files changed

Lines changed: 129 additions & 35 deletions

File tree

‎README.md‎

Lines changed: 122 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,127 @@
11
# Tunnel [![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](http://godoc.org/github.com/mmatczuk/go-http-tunnel) [![Go Report Card](https://goreportcard.com/badge/github.com/mmatczuk/go-http-tunnel)](https://goreportcard.com/report/github.com/mmatczuk/go-http-tunnel) [![Build Status](http://img.shields.io/travis/mmatczuk/go-http-tunnel.svg?style=flat-square)](https://travis-ci.org/mmatczuk/go-http-tunnel)
22

3-
Tunnel is fast and secure server/client package that enables proxying public connections to your local machine over a tunnel connection from the local machine to the public server. In other words you can share your localhost even if it doesn't have a public IP or if it's not reachable from outside.
3+
Tunnel is fast and secure client/server package that enables proxying public connections to your local machine over a tunnel connection from the local machine to the public server. **It enables you to share your localhost when you dont't have a public IP or you are hidden by a firewall**.
44

5-
It uses HTTP/2 protocol for data transport and connection multiplexing.
5+
It can help you:
66

7-
With tunnel you can proxy:
7+
* Demo without deploying
8+
* Simplify mobile device testing
9+
* Build webhook integrations with ease
10+
* Run personal cloud services from your own private network
811

9-
* HTTP
10-
* TCP
11-
* UNIX sockets
12+
It is based on HTTP/2 for speed and security. Server accepts TLS connection from known clients, client is recognised by it's TLS certificate id. Server can protect HTTP tunnels with [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
13+
14+
## Installation
15+
16+
Download latest release from [here](https://github.com/mmatczuk/go-http-tunnel/releases/latest). The release contains two executables:
17+
18+
* `tunneld` - the tunnel server, to be run on publicly available host like AWS or GCE
19+
* `tunnel` - the tunnel client, to be run on your local machine or in your private network
20+
21+
To get help on the command parameters run `tunneld -h` or `tunnel -h`.
22+
23+
## Configuration
24+
25+
The tunnel client `tunnel` requires configuration file, by default it will try reading `tunnel.yml` in your current working directory. If you want to specify other file use `-config` flag.
26+
27+
Sample configuration that exposes:
28+
29+
* `localhost:8080` as `webui.my-tunnel-host.com`
30+
* host in private network for ssh connections
31+
32+
looks like this
33+
34+
```yaml
35+
server_addr: SERVER_IP:4443
36+
insecure_skip_verify: true
37+
tunnels:
38+
webui:
39+
proto: http
40+
addr: localhost:8080
41+
auth: user:password
42+
host: webui.my-tunnel-host.com
43+
ssh:
44+
proto: tcp
45+
addr: 192.168.0.5:22
46+
remote_addr: 0.0.0.0:22
47+
```
48+
49+
Configuration options:
50+
51+
* `server_addr`: server TCP address, i.e. `54.12.12.45:4443`
52+
* `insecure_skip_verify`: controls whether a client verifies the server's certificate chain and host name, if using self signed certificates must be set to `true`, *default:* `false`
53+
* `tls_crt`: path to client TLS certificate, *default:* `client.crt` *in the config file directory*
54+
* `tls_key`: path to client TLS certificate key, *default:* `client.key` *in the config file directory*
55+
* `tunnels / [name]`
56+
* `proto`: tunnel protocol, `http` or `tcp`
57+
* `addr`: forward traffic to this local port number or network address, for `proto=http` this can be full URL i.e. `https://machine/sub/path/?plus=params`, supports URL schemes `http` and `https`
58+
* `auth`: (`proto=http`) (optional) basic authentication credentials to enforce on tunneled requests, format `user:password`
59+
* `host`: (`proto=http`) hostname to request (requires reserved name and DNS CNAME)
60+
* `remote_addr`: (`proto=tcp`) bind the remote TCP address
61+
* `backoff`
62+
* `interval`: how long client would wait before redialing the server if connection was lost, exponential backoff initial interval, *default:* `500ms`
63+
* `multiplier`: interval multiplier if reconnect failed, *default:* `1.5`
64+
* `max_interval`: maximal time client would wait before redialing the server, *default:* `1m`
65+
* `max_time`: maximal time client would try to reconnect to the server if connection was lost, set `0` to never stop trying, *default:* `15m`
66+
67+
## Running
68+
69+
Tunnel requires TLS certificates for both client and server.
70+
71+
```bash
72+
$ openssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout client.key -out client.crt
73+
$ openssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout server.key -out server.crt
74+
```
75+
76+
Run client:
77+
78+
* Install `tunnel` binary
79+
* Make `.tunnel` directory in your project directory
80+
* Copy `client.key`, `client.crt` to `.tunnel`
81+
* Create configuration file `tunnel.yml` in `.tunnel`
82+
* Start all tunnels
83+
84+
```bash
85+
$ tunnel -config ./tunnel/tunnel.yml start-all
86+
```
87+
88+
Run server:
89+
90+
* Install `tunneld` binary
91+
* Make `.tunneld` directory
92+
* Copy `server.key`, `server.crt` to `.tunneld`
93+
* Get client identifier (`tunnel -config ./tunnel/tunnel.yml id`), identifier should look like this `YMBKT3V-ESUTZ2Z-7MRILIJ-T35FHGO-D2DHO7D-FXMGSSR-V4LBSZX-BNDONQ4`
94+
* Start tunnel server
95+
96+
```bash
97+
$ tunneld -tlsCrt .tunneld/server.crt -tlsKey .tunneld/server.key -clients YMBKT3V-ESUTZ2Z-7MRILIJ-T35FHGO-D2DHO7D-FXMGSSR-V4LBSZX-BNDONQ4
98+
```
99+
100+
This will run HTTP server on port `80` and HTTPS (HTTP/2) server on port `443`. If you want to use HTTPS it's recommended to get a properly signed certificate to avoid security warnings.
101+
102+
## Using as library
103+
104+
Install the package:
105+
106+
```bash
107+
$ go get -u github.com/mmatczuk/go-http-tunnel
108+
```
109+
110+
The `tunnel` package is designed to be simple, extensible, with little dependencies. It is based on HTTP/2 for client server connectivity, this avoids usage of third party tools for multiplexing tunneled connections. HTTP/2 is faster, more stable and much more tested then any other multiplexing technology. You may see [benchmark](benchmark) comparing the `tunnel` package to a koding tunnel.
111+
112+
The `tunnel` package:
113+
114+
* custom dialer and listener for `Client` and `Server`
115+
* easy modifications of HTTP proxy (based on [ReverseProxy](https://golang.org/pkg/net/http/httputil/#ReverseProxy))
116+
* proxy anything, [ProxyFunc](https://godoc.org/github.com/mmatczuk/go-http-tunnel#ProxyFunc) architecture
117+
* structured logs with go-kit compatible minimal logger interface
118+
119+
See:
120+
121+
* [ClientConfig](https://godoc.org/github.com/mmatczuk/go-http-tunnel#ClientConfig)
122+
* [ServerConfig](https://godoc.org/github.com/mmatczuk/go-http-tunnel#ServerConfig)
123+
* [ControlMessage](https://godoc.org/github.com/mmatczuk/go-http-tunnel/proto#ControlMessage)
124+
125+
## License
126+
127+
The BSD 3-Clause License

‎TODO.md‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
Release 1.0
2-
3-
1. docs: new README
4-
51
Backlog
62

73
1. monitoring: client connection state machine
@@ -13,21 +9,3 @@ Backlog
139
1. proxy: host_header modifier
1410
1. security: certificate signature checks
1511
1. cli: integrated certificate generation
16-
17-
Notes for README
18-
19-
1. HTTP/2
20-
1. Server http.RoundTriper
21-
1. Extensible Proxy architecture
22-
1. Configurable HTTP proxy httputil.ReverseProxy
23-
1. Custom listener and dialer
24-
1. Connection back off
25-
1. Dynamic tunnel management
26-
1. Structured logs, go kit logger compatible
27-
28-
Log levels:
29-
30-
* 0 - Critical, error something went really wrong
31-
* 1 - Info, something important happened
32-
* 2 - Debug
33-
* 3 - Trace, reserved for data transfer logs

‎cmd/tunnel/options.go‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,15 +26,15 @@ config.yaml:
2626
server_addr: SERVER_IP:4443
2727
insecure_skip_verify: true
2828
tunnels:
29-
www:
29+
webui:
3030
proto: http
31-
addr: http://IP:8080/ui/
31+
addr: localhost:8080
3232
auth: user:password
33-
host: ui.mytunnel.com
33+
host: webui.my-tunnel-host.com
3434
ssh:
3535
proto: tcp
36-
addr: IP:22
37-
remote_addr: 0.0.0.0:2222
36+
addr: 192.168.0.5:22
37+
remote_addr: 0.0.0.0:22
3838
3939
Author:
4040
Written by M. Matczuk (mmatczuk@gmail.com)
@@ -63,7 +63,7 @@ type options struct {
6363

6464
func parseArgs() (*options, error) {
6565
debug := flag.Bool("debug", false, "Starts gops agent")
66-
config := flag.String("config", "tunnel.yaml", "Path to tunnel configuration file")
66+
config := flag.String("config", "tunnel.yml", "Path to tunnel configuration file")
6767
logTo := flag.String("log", "stdout", "Write log messages to this file, file name or 'stdout', 'stderr', 'none'")
6868
logLevel := flag.Int("log-level", 1, "Level of messages to log, 0-3")
6969
version := flag.Bool("version", false, "Prints tunnel version")

‎doc.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Package tunnel is fast and secure server/client package that enables proxying
1+
// Package tunnel is fast and secure client/server package that enables proxying
22
// public connections to your local machine over a tunnel connection from the
33
// local machine to the public server.
44
package tunnel

0 commit comments

Comments
 (0)