{"id":21831391,"url":"https://github.com/nodef/extra-tunnel","last_synced_at":"2025-04-14T07:07:12.782Z","repository":{"id":90491455,"uuid":"107592476","full_name":"nodef/extra-tunnel","owner":"nodef","description":"Tunnel web server from private IP.","archived":false,"fork":false,"pushed_at":"2025-04-08T16:36:07.000Z","size":244,"stargazers_count":28,"open_issues_count":0,"forks_count":46,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-14T07:07:04.670Z","etag":null,"topics":["extra","host","ip","private","remote","server","tunnel","web"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/extra-tunnel","language":"JavaScript","has_issues":false,"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/nodef.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}},"created_at":"2017-10-19T20:00:54.000Z","updated_at":"2025-04-08T16:36:11.000Z","dependencies_parsed_at":"2023-10-11T12:52:04.847Z","dependency_job_id":"4bd30dcd-de5e-4aa1-bf2c-52099743c870","html_url":"https://github.com/nodef/extra-tunnel","commit_stats":{"total_commits":449,"total_committers":2,"mean_commits":224.5,"dds":0.06681514476614703,"last_synced_commit":"d143266b3466034d788219713c553ee55aa47908"},"previous_names":["nodef/rhost"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodef%2Fextra-tunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodef%2Fextra-tunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodef%2Fextra-tunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodef%2Fextra-tunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodef","download_url":"https://codeload.github.com/nodef/extra-tunnel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837278,"owners_count":21169374,"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":["extra","host","ip","private","remote","server","tunnel","web"],"created_at":"2024-11-27T19:10:12.223Z","updated_at":"2025-04-14T07:07:12.766Z","avatar_url":"https://github.com/nodef.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Tunnel web server from private IP.**\n\nA tunneling system, where the *tunnel* acts both as a *middle-man* and an\n*HTTP server*. This enables *users* to access an HTTP server running\n**locally**, through a *public-ip tunnel server*, which can be hosted on a\n*cloud server*, like *[Heroku]*. The tunnel also supports **channels**, other\nthan HTTP which enables users to access *TCP servers*, like *SSH/FTP*,\nrunning locally.\n\nThe system has 3 parts:\n- **Tunnel**: acts as the tunnel server\n- **Server**: enables local server to be hosted through *Tunnel*\n- **Client**: enables local clients to request through *Tunnel*\n\nThink of *Tunnel* like a *school*. It has multiple *channels*, like a school has\nmultiple *classrooms*. Each *channel* has a *Server*, like each classroom has a\n*class teacher*.. Any number of *Clients* can connect to a *channel* and send\nrequests to the *Server*, and so can any number of *students* in a *classroom*\nask questions to their *class teacher*.\n\u003cbr\u003e\u003cbr\u003e\n\n\n## Setup\n\n### Tunnel\n\nIn order to start, we need a *Tunnel* first. Let's set it up:\n1. Get *Tunnel* to your [GitHub].\n    1. Create an account on [GitHub].\n    2. Goto [extra-tunnel] repository, and fork it.\n2. Create *Tunnel* application in cloud.\n    1. Create an account on [Heroku].\n    2. On [Heroku dashboard], create a new app, like `tunnelwebapp`.\n    3. Select the *Deploy* tab, and the choose *GitHub* as deployment method.\n    4. In *Connect to GitHub*, type in *extra-tunnel* and *Connect*.\n    5. In *Manual Deploy*, *Deploy Branch* when *master* is selected.\n\n### Server/Client\n\nWe need to install [extra-tunnel] locally in order to use it as *Server* or *Client*\n(a private-ip *Tunnel* would only be useful in testing).\n\n```bash\n# to use from command line\nnpm install -g extra-tunnel\n\n# to use from node.js\nnpm install extra-tunnel\n```\n\u003cbr\u003e\u003cbr\u003e\n\n\n## Usage\n\n### Host local HTTP server\n\nAssuming your [Heroku] app name is `tunnelwebapp`, and your local HTTP server is\nrunning on port 80. The following command starts up a *Server*, which acts as a\nbridge between your local server `localhost:80` and the *Tunnel* `tunnelwebapp`.\nTry opening `https://tunnelwebapp.herokuapp.com` in your browser, after running\nthis command.\n\n```bash\netunnel server --tunnel tunnelwebapp.herokuapp.com --server 80\n```\n\n### Host local SSH server\n\nAll *channels* other than default `/` for HTTP are disabled by default. Lets\nenable it first by going to *Tunnel* setting on [Heroku]:\n1. Goto [Heroku dashboard], and then choose *Settings* tab.\n2. In *Config Variables*, we need to add one, so select *Reveal Config Vars*.\n3. Set *Key* as `KEYS_SSH`, and *Value* as `admin` (or whatever you want).\n4. Select *Add*, this restarts the app with new config.\n5. You can see app logs at *More -\u003e View Logs*.\n\nNow that we have setup the key for `/ssh` *channel*, it is enabled and we are\nready to setup the server. Assuming your [Heroku] app name is `tunnelwebapp`,\nand your local SSH server is running on port 22. The following command starts\nup a *Server*, which acts as a bridge between your local server `localhost:22`\nand the *Tunnel* `tunnelwebapp`, on *channel* `/ssh`.\n\n```bash\netunnel server -t tunnelwebapp.herokuapp.com -s 22 --channel /ssh --key admin\n```\n\nThe common use of SSH is to access the terminal of a remote computer. In our\ncase, since we are using *Tunnel*, we would now be able to access it, not just\nfrom LAN, but from anywhere in the world (with an internet connection). Unlike\nHTTP however, *Tunnel* is unable to act as an SSH server and hence you cannot\nconnect directly to it with your SSH client.\n\nTo solve this problem, we have a *Client*. Any number of *Clients* can connect\nto a *channel* on the *Tunnel*. So, on a separate machine, install [extra-tunnel] using\nthe command `npm install -g extra-tunnel`, and then start *Client* using the following\ncommand:\n\n```bash\netunnel client -t tunnelwebapp.herokuapp.com -c 22 -n /ssh\n```\n\u003cbr\u003e\u003cbr\u003e\n\n\n## Concept\n\n### Tunnel\n\nIt acts as a server on a single port, and manages communication between\n*Clients* and *Servers* through *channels*. Each *Server* registers to a unique\n*channel* (like `/` or `/ssh`), and any number of *Clients* can then connect to\nthe *Tunnel* on that *channel*. The *Tunnel* also itself acts as a client on\n*channel* `/` forwarding any HTTP requests it receives on its port to the\n*Server* registered to *channel* `/`.\n\n### Server\n\nIt connects to the *Tunnel*, and registers to a unique *channel* using a *key*\nand a *token*. The *key* must match the one stored on the *Tunnel* for that\n*channel*. Once registered, the *token* is used to accept *Clients*. *Server*\nthen acts a multiple local clients for forwarding requests to local server from\nspecified *channel*, thus making you **feel** as if the *Clients* are running\nlocally (even if its not). A *Server* registered to *channel* `/` will also\nreceive *HTTP requests* from *Tunnel*, becuase *Tunnel* also acts as a *Client*\nto *channel* `/`.\n\n### Client\n\nIt connects to the *Tunnel*, and subscribes to a *channel* using a *token*. This\n*token* must match the one provided by the *Server* registered to this\n*channel*. *Client* then acts as a local server for forwarding requests of\nlocal clients to specified *channel*, thus making you **feel** as if the\n*Server* is running locally (even if its not). Any *Client* can also register\nto *channel* `/`, but this is **unnecessary** since you can directly request\nthe *Tunnel* server instead.\n\u003cbr\u003e\u003cbr\u003e\n\n[GitHub]: https://github.com\n[Heroku]: https://www.heroku.com\n[extra-tunnel]: https://github.com/nodef/extra-tunnel\n[Heroku dashboard]: https://dashboard.heroku.com/apps\n\n\n## Reference\n\n### Command Line\n\n```bash\n$ etunnel [\u003cmode\u003e] [options]\n\n# mode: this is 'tunnel', 'server', or 'client'\n# -t | --tunnel: address of tunnel\n# -s | --server: address of server\n# -c | --client: address of client\n# -n | --channel: channel to register/subscribe\n# -k | --key: key for registering server\n# -o | --token: token for subscribing client\n# -i | --ping: ping period to Tunnel\n# -e | --keys: JSON object with keys of channels\n# --keys_ch1: key for channel /ch1\n# --keys_ch1_ch2: key for channel /ch1/ch2\n# --version: get version\n# --help: get this help\n# environment variables are also accepted\n# PORT: port number for tunnel\n# TUNNEL: address of tunnel\n# SERVER: address of server\n# CLIENT: address of client\n# CHANNEL: channel to register/subscribe\n# KEY: key for registering server\n# TOKEN: token for subscribing client\n# PING: ping period to Tunnel in ms\n# KEYS: JSON object with keys of channels\n# KEYS_CH1: key for channel /ch1\n# KEYS_CH1_CH2: key for channel /ch1/ch2\n```\n\n### Node.js\n\n```javascript\nconst Tunnel = require('extra-tunnel');\n\nTunnel([\u003cprefix\u003e], [\u003coptions\u003e]);\nTunnel.\u003cServer/Client\u003e([\u003cprefix\u003e], [\u003coptions\u003e]);\n// prefix: name of object in logs\n// the following options are accepted (object)\n// tunnel: address of tunnel ('localhost:7000')\n// server: address of server ('localhost:7001')\n// client: address of client ('localhost:7002')\n// channel: channel to register/subscribe ('/')\n// key: key for registering server ('')\n// token: token for subscribing client ('')\n// ping: ping period to Tunnel in ms (8000)\n// keys: keys for each allowed channel ({'/': ''})\n```\n\u003cbr\u003e\u003cbr\u003e\n\n\n![](https://i.imgur.com/2u9XcjX.jpg)\n[![](https://i.imgur.com/wOgtZvg.jpg)](https://merferry.github.io)\n\n\u003e Listen: [Epic Mountain]; Inspiration: [Samy Kamkar]; Docs: [Net Node.js]; Play: [Scrap Mechanic];\u003cbr\u003e\n\u003e ASCII art: [Taag]; Reference: [Markdown Cheatsheet]; Prof. icons: [Icon Experience]\u003cbr\u003e\n\n[Epic Mountain]:https://soundcloud.com/epicmountain\n[Samy Kamkar]: https://samy.pl\n[Net Node.js]: https://nodejs.org/api/net.html\n[Scrap Mechanic]: http://scrapmechanic.com\n[Taag]: http://patorjk.com/software/taag\n[Markdown Cheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet\n[Icon Experience]: https://www.iconexperience.com\n\n![](https://ga-beacon.deno.dev/G-RC63DPBH3P:SH3Eq-NoQ9mwgYeHWxu7cw/github.com/nodef/extra-tunnel)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodef%2Fextra-tunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodef%2Fextra-tunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodef%2Fextra-tunnel/lists"}