{"id":13425079,"url":"https://github.com/skx/tunneller","last_synced_at":"2025-04-13T02:16:40.628Z","repository":{"id":53052207,"uuid":"182522521","full_name":"skx/tunneller","owner":"skx","description":"Allow internal services, running on localhost, to be accessed over the internet..","archived":false,"fork":false,"pushed_at":"2024-08-13T07:36:22.000Z","size":131,"stargazers_count":485,"open_issues_count":2,"forks_count":41,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-13T02:16:31.410Z","etag":null,"topics":["go","golang","ngrok","proxy","selfhosted","websockets"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"skx","custom":"https://steve.fi/donate/"}},"created_at":"2019-04-21T11:05:11.000Z","updated_at":"2025-04-09T11:21:36.000Z","dependencies_parsed_at":"2024-01-07T22:49:08.262Z","dependency_job_id":"3219e052-a04f-40cd-82bb-ae9172e17489","html_url":"https://github.com/skx/tunneller","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Ftunneller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Ftunneller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Ftunneller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Ftunneller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skx","download_url":"https://codeload.github.com/skx/tunneller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654104,"owners_count":21140237,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","ngrok","proxy","selfhosted","websockets"],"created_at":"2024-07-31T00:01:04.103Z","updated_at":"2025-04-13T02:16:40.606Z","avatar_url":"https://github.com/skx.png","language":"Go","funding_links":["https://github.com/sponsors/skx","https://steve.fi/donate/"],"categories":["Go","\u003ca id=\"01e6651181d405ecdcd92a452989e7e0\"\u003e\u003c/a\u003e工具","golang"],"sub_categories":["\u003ca id=\"9d6789f22a280f5bb6491d1353b02384\"\u003e\u003c/a\u003e隧道\u0026\u0026穿透"],"readme":"[![Go Report Card](https://goreportcard.com/badge/github.com/skx/tunneller)](https://goreportcard.com/report/github.com/skx/tunneller)\n[![license](https://img.shields.io/github/license/skx/tunneller.svg)](https://github.com/skx/tunneller/blob/master/LICENSE)\n[![Release](https://img.shields.io/github/release/skx/tunneller.svg)](https://github.com/skx/tunneller/releases/latest)\n\nTable of Contents\n=================\n\n* [tunneller](#tunneller)\n* [Overview](#overview)\n* [How it works](#how-it-works)\n* [Installation](#installation)\n  * [Source Installation go \u0026lt;=  1.11](#source-installation-go---111)\n  * [Source installation go  \u0026gt;= 1.12](#source-installation-go---112)\n  * [Installation of your self-hosted Server](#installation-of-your-self-hosted-server)\n* [Github Setup](#github-setup)\n\n\n# tunneller\n\nTunneller allows you to expose services which are running on `localhost`, or on your local network, to the public internet.\n\nThis is very useful for testing webhooks, the generation of static-site compilers, and similar things.\n\n\u003e**NOTE**: There is a public end-point I host, you __SHOULD NOT__ rely upon it.  It might come and go.  It is not secure.\n\nThere is a _basic_ GUI present to allow you to view status-codes, and the most recent few requests:\n\n![Screenshot](_media/gui1.png)\n\n\n## Overview\n\nAssuming 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:\n\n    $ tunneller client -expose localhost:8080\n\nThis will show you initial page of the GUI, letting you know how you can access your resource externally:\n\n![Screenshot](_media/gui0.png)\n\nAs 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.\n\nIn short this project is designed to be a __self-hosted__ alternative to software such as `ngrok`.\n\nSo remember:\n\n\u003e**NOTE**: There is a public end-point I host, you __SHOULD NOT__ rely upon it.  You should configure your own server, and use it.\n\n\n\n## How it works\n\nWhen 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.\n\nWhen 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).\n\nIn short:\n\n* The server sends a \"Fetch this URL\" request to the client.\n* The client makes the request to fetch the URL\n  * This will succeed, because the client is running inside your network and can access localhost, and any other \"internal\" resources.\n* The response is sent back to the server.\n  * And from there it is routed back to the requested web-browser.\n\nBecause 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.\n\n\n## Installation\n\nThere are two ways to install this project from source, which depend on the version of the [go](https://golang.org/) version you're using.\n\n\u003e **NOTE**: If you prefer you can find binary releases upon our [release page](https://github.com/skx/tunneller/releases/)\n\n\n### Source Installation go \u003c=  1.11\n\nIf you're using `go` before 1.11 then the following command should fetch/update `tunneller`, and install it upon your system:\n\n     $ go get -u github.com/skx/tunneller\n\n### Source installation go  \u003e= 1.12\n\nIf 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`:\n\n    git clone https://github.com/skx/tunneller\n    cd tunneller\n    go install\n\n\nIf 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).\n\n\n\n\n## Installation of your self-hosted Server\n\nIf you wish to host your own central-server this is how to do it:\n\n* Create a DNS-entry `tunnel.example.com`, pointing to your host.\n* Create a __wildcard__ DNS entry for `*.tunnel.example.com` to point to the same host.\n* Setup and configure [mosquitto queue](https://mosquitto.org/) running on that same host.\n  * See [mq/](mq/) for details there.\n  * Don't forget to ensure that the MQ-service is publicly visible, by opening a firewall hole for port `1883` if required.\n\nOf 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).)\n\n\n\n## Github Setup\n\nThis repository is configured to run tests upon every commit, and when\npull-requests are created/updated.  The testing is carried out via\n[.github/run-tests.sh](.github/run-tests.sh) which is used by the\n[github-action-tester](https://github.com/skx/github-action-tester) action.\n\nReleases are automated in a similar fashion via [.github/build](.github/build),\nand the [github-action-publish-binaries](https://github.com/skx/github-action-publish-binaries) action.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Ftunneller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskx%2Ftunneller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Ftunneller/lists"}