README.md
1[](https://goreportcard.com/report/github.com/skx/tunneller)
2[](https://github.com/skx/tunneller/blob/master/LICENSE)
3[](https://github.com/skx/tunneller/releases/latest)
4
5Table of Contents
6=================
7
8* [tunneller](#tunneller)
9* [Overview](#overview)
10* [How it works](#how-it-works)
11* [Installation](#installation)
12 * [Source Installation go <= 1.11](#source-installation-go---111)
13 * [Source installation go >= 1.12](#source-installation-go---112)
14 * [Installation of your self-hosted Server](#installation-of-your-self-hosted-server)
15* [Github Setup](#github-setup)
16
17
18# tunneller
19
20Tunneller allows you to expose services which are running on `localhost`, or on your local network, to the public internet.
21
22This is very useful for testing webhooks, the generation of static-site compilers, and similar things.
23
24>**NOTE**: There is a public end-point I host, you __SHOULD NOT__ rely upon it. It might come and go. It is not secure.
25
26There is a _basic_ GUI present to allow you to view status-codes, and the most recent few requests:
27
28
29
30
31## Overview
32
33Assuming you have a service running within your local network, perhaps a HTTP server you could access via http://localhost:8080/, you can expose that to the public-internet by running:
34
35 $ tunneller client -expose localhost:8080
36
37This will show you initial page of the GUI, letting you know how you can access your resource externally:
38
39
40
41As the name implies there is a central-host involved which is in charge of routing/proxying to your local network - in this case that central host is `tunnel.steve.fi` - the reason this project exists is not to host a general-purpose end-point, but instead to allow you to host your own.
42
43In short this project is designed to be a __self-hosted__ alternative to software such as `ngrok`.
44
45So remember:
46
47>**NOTE**: There is a public end-point I host, you __SHOULD NOT__ rely upon it. You should configure your own server, and use it.
48
49
50
51## How it works
52
53When a client is launched it creates a connection to a message-bus running on the default remote end-point, `tunnel.steve.fi`, it keeps that connection alive waiting for instructions.
54
55When a request comes in for `foo.tunnel.steve.fi` the server will submit a command for the client to make the appropriate request by publishing a message upon the topic the client is listening to. (Each client has a name, and listens to its own topic).
56
57In short:
58
59* The server sends a "Fetch this URL" request to the client.
60* The client makes the request to fetch the URL
61 * This will succeed, because the client is running inside your network and can access localhost, and any other "internal" resources.
62* The response is sent back to the server.
63 * And from there it is routed back to the requested web-browser.
64
65Because the client connects directly to a message-bus there is always the risk that malicious actors will inject fake requests, attempting to scan, probe, and otherwise abuse your local network.
66
67
68## Installation
69
70There are two ways to install this project from source, which depend on the version of the [go](https://golang.org/) version you're using.
71
72> **NOTE**: If you prefer you can find binary releases upon our [release page](https://github.com/skx/tunneller/releases/)
73
74
75### Source Installation go <= 1.11
76
77If you're using `go` before 1.11 then the following command should fetch/update `tunneller`, and install it upon your system:
78
79 $ go get -u github.com/skx/tunneller
80
81### Source installation go >= 1.12
82
83If you're using a more recent version of `go` (which is _highly_ recommended), you need to clone to a directory which is not present upon your `GOPATH`:
84
85 git clone https://github.com/skx/tunneller
86 cd tunneller
87 go install
88
89
90If you don't have a golang environment setup you should be able to download a binary for GNU/Linux from [our release page](https://github.com/skx/tunneller/releases).
91
92
93
94
95## Installation of your self-hosted Server
96
97If you wish to host your own central-server this is how to do it:
98
99* Create a DNS-entry `tunnel.example.com`, pointing to your host.
100* Create a __wildcard__ DNS entry for `*.tunnel.example.com` to point to the same host.
101* Setup and configure [mosquitto queue](https://mosquitto.org/) running on that same host.
102 * See [mq/](mq/) for details there.
103 * Don't forget to ensure that the MQ-service is publicly visible, by opening a firewall hole for port `1883` if required.
104
105Of course security is important, so you should ensure that your message-bus is only reachable by clients you trust to expose their services. (i.e. Your VPN and office range(s).)
106
107
108
109## Github Setup
110
111This repository is configured to run tests upon every commit, and when
112pull-requests are created/updated. The testing is carried out via
113[.github/run-tests.sh](.github/run-tests.sh) which is used by the
114[github-action-tester](https://github.com/skx/github-action-tester) action.
115
116Releases are automated in a similar fashion via [.github/build](.github/build),
117and the [github-action-publish-binaries](https://github.com/skx/github-action-publish-binaries) action.
118
){kind=link}
){kind=link}
