{"id":13456592,"url":"https://github.com/anderspitman/SirTunnel","last_synced_at":"2025-03-24T11:30:40.759Z","repository":{"id":37528069,"uuid":"297804419","full_name":"anderspitman/SirTunnel","owner":"anderspitman","description":"Minimal, self-hosted, 0-config alternative to ngrok. Caddy+OpenSSH+50 lines of Python.","archived":false,"fork":false,"pushed_at":"2024-03-24T20:15:50.000Z","size":20,"stargazers_count":1419,"open_issues_count":2,"forks_count":118,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-18T10:36:27.008Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anderspitman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2020-09-23T00:15:26.000Z","updated_at":"2025-03-17T18:28:24.000Z","dependencies_parsed_at":"2022-07-12T16:21:49.208Z","dependency_job_id":"19230bd4-bd55-40be-a355-bb27f065349e","html_url":"https://github.com/anderspitman/SirTunnel","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderspitman%2FSirTunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderspitman%2FSirTunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderspitman%2FSirTunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderspitman%2FSirTunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anderspitman","download_url":"https://codeload.github.com/anderspitman/SirTunnel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245260653,"owners_count":20586436,"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":[],"created_at":"2024-07-31T08:01:24.586Z","updated_at":"2025-03-24T11:30:40.492Z","avatar_url":"https://github.com/anderspitman.png","language":"Python","funding_links":[],"categories":["Python","others"],"sub_categories":[],"readme":"# What is it?\n\nIf you have a webserver running on one computer (say your development laptop),\nand you want to expose it securely (ie HTTPS) via a public URL, SirTunnel\nallows you to easily do that.\n\n# How do you use it?\n\nIf you have:\n\n* A SirTunnel [server instance](#running-the-server) listening on port 443 of\n  `example.com`.\n* A copy of the sirtunnel.py script available on the PATH of the server.\n* An SSH server running on port 22 of `example.com`.\n* A webserver running on port 8080 of your laptop.\n\nAnd you run the following command on your laptop:\n\n```bash\nssh -tR 9001:localhost:8080 example.com sirtunnel.py sub1.example.com 9001\n```\n\nNow any requests to `https://sub1.example.com` will be proxied to your local\nwebserver.\n\n\n# How does it work?\n\nThe command above does 2 things:\n\n1. It starts a standard [remote SSH tunnel][2] from the server port 9001 to\n   local port 8080.\n2. It runs the command `sirtunnel.py sub1.example.com 9001` on the server.\n   The python script parses `sub1.example.com 9001` and uses the Caddy API to\n   reverse proxy `sub1.example.com` to port 9001 on the server. Caddy\n   automatically retrieves an HTTPS cert for `sub1.example.com`.\n\n**Note:** The `-t` is necessary so that doing CTRL-C on your laptop stops the\n`sirtunnel.py` command on the server, which allows it to clean up the tunnel\non Caddy. Otherwise it would leave `sirtunnel.py` running and just kill your\nSSH tunnel locally.\n\n\n# How is it different?\n\nThere are a lot of solutions to this problem. In fact, I've made something of\na hobby of maintaining [a list][0] of the ones I've found so far.\n\nThe main advantages of SirTunnel are:\n\n* Minimal. It leverages [Caddy][1] and whatever SSH server you already have\n  running on your server. Other than that, it consists of a 50-line Python\n  script on the server.  That's it. Any time you spend learning to customize\n  and configure it will be time well spent because you're learning Caddy and\n  your SSH server.\n* 0-configuration. There is no configuration on the server side.  Not even CLI\n  arguments.\n* Essentially stateless. The only state is the certs (which is handled entirely\n  by Caddy) and the tunnel mappings, which are ephemeral and controlled by the\n  clients.\n* Automatic HTTPS certificate management. Some other solutions do this as well,\n  so it's important but not unique.\n* No special client is required. You can use any standard SSH client that\n  supports remote tunnels. Again, this is not a unique feature.\n\n\n# Running the server\n\nAssuming you already have an ssh server running, getting the SirTunnel server\ngoing consists of simply downloading a copy of Caddy and running it with the\nprovided config. Take a look at [`install.sh`](./install.sh) and\n[`run_server.sh`](./run_server.sh) for details.\n\n**Note:** Caddy needs to bind to port 443, either by running as root (not\nrecommended), setting the `CAP_NET_BIND_SERVICE` capability on the Caddy binary\n(what the `install.sh` script does), or changing `caddy_config.json` to bind\nto a different port (say 9000) and using something like iptables to forward\nto that port.\n\n# Future Features\n\nSirTunnel is intended to be a minimal tool. As such, I'm unlikely to add many\nfeatures moving forward. However, the simplicity makes it easier to modify\nfor your needs. If you find a feature missing, maybe one of the forks below\nhas what you need or gives you some ideas:\n\n* https://github.com/matiboy/SirTunnel adds functionality to help multiple\n  users avoid overwriting each others' tunnels.\n* https://github.com/daps94/SirTunnel implements tunnel checking and auto\n  cleanup to address issue with stale tunnels.\n\n\n[0]: https://github.com/anderspitman/awesome-tunneling\n\n[1]: https://caddyserver.com/\n\n[2]: https://www.ssh.com/ssh/tunneling/example#remote-forwarding\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanderspitman%2FSirTunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanderspitman%2FSirTunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanderspitman%2FSirTunnel/lists"}