{"id":13509181,"url":"https://github.com/norouter/norouter","last_synced_at":"2025-03-30T13:31:43.795Z","repository":{"id":39617653,"uuid":"298272233","full_name":"norouter/norouter","owner":"norouter","description":"NoRouter: IP-over-Stdio. The easiest multi-host \u0026 multi-cloud networking ever. No root privilege is required. ","archived":false,"fork":false,"pushed_at":"2023-07-03T20:39:53.000Z","size":1187,"stargazers_count":349,"open_issues_count":14,"forks_count":21,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-01T09:34:18.233Z","etag":null,"topics":["multi-cloud","netstack","usermode-networking","vpn"],"latest_commit_sha":null,"homepage":"https://norouter.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/norouter.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-24T12:29:48.000Z","updated_at":"2024-10-08T15:25:45.000Z","dependencies_parsed_at":"2024-06-18T14:02:55.578Z","dependency_job_id":null,"html_url":"https://github.com/norouter/norouter","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norouter%2Fnorouter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norouter%2Fnorouter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norouter%2Fnorouter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norouter%2Fnorouter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/norouter","download_url":"https://codeload.github.com/norouter/norouter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246323932,"owners_count":20759051,"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":["multi-cloud","netstack","usermode-networking","vpn"],"created_at":"2024-08-01T02:01:04.168Z","updated_at":"2025-03-30T13:31:43.080Z","avatar_url":"https://github.com/norouter.png","language":"Go","funding_links":[],"categories":["Go","vpn"],"sub_categories":[],"readme":"![NoRouter banner](./docs.source/static/images/norouter_h.svg)\n\n[NoRouter](https://norouter.io/) (IP-over-Stdio) is the easiest multi-host \u0026 multi-cloud networking ever:\n- Works with any container, any VM, and any baremetal machine, on anywhere, as long as the shell access is available (e.g. `docker exec`, `kubectl exec`, `ssh`)\n- Omnidirectional port forwarding: Local-to-Remote, Remote-to-Local, and Remote-to-Remote\n- No routing configuration is required\n- No root privilege is required (e.g. `sudo`, `docker run --privileged`)\n- No public IP is required\n- Provides several network modes\n  - Loopback IP mode (e.g. 127.0.42.101, 127.0.42.102, ...)\n  - HTTP proxy mode with built-in name resolver\n  - SOCKS4a and SOCKS5 proxy mode with built-in name resolver\n- Easily installable with a single binary, available for Linux, macOS, BSDs, and Windows\n\nWeb site: https://norouter.io/\n\n- - -\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [What is NoRouter?](#what-is-norouter)\n- [Download](#download)\n- [Quick usage](#quick-usage)\n  - [Example 1: Port forwarding across localhost + Docker + Kubernetes + LXD + SSH](#example-1-port-forwarding-across-localhost--docker--kubernetes--lxd--ssh)\n  - [Example 2: Virtual VPN connection into `docker network create` networks](#example-2-virtual-vpn-connection-into-docker-network-create-networks)\n  - [Example 3: Virtual VPN connection into Kubernetes networks](#example-3-virtual-vpn-connection-into-kubernetes-networks)\n  - [Example 4: Aggregate VPCs of AWS, Azure, and GCP](#example-4-aggregate-vpcs-of-aws-azure-and-gcp)\n- [Documentation](#documentation)\n- [Installing NoRouter from source](#installing-norouter-from-source)\n- [Contributing to NoRouter](#contributing-to-norouter)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## What is NoRouter?\n\nNoRouter implements unprivileged networking by using multiple loopback addresses such as 127.0.42.101 and 127.0.42.102.\nThe hosts in the network are connected by forwarding packets over stdio streams like `docker exec`, `kubectl exec`, `ssh`, and whatever.\n\nUnlike traditional port forwarders such as `docker run -p`, `kubectl port-forward`, `ssh -L`, and `ssh -R`,\nNoRouter provides mutual interconnectivity across multiple remote hosts.\n\n![overview](./docs.source/static/images/norouter-overview.png)\n\nNoRouter is mostly expected to be used in a dev environment for running heterogeneous multi-cloud apps.\n\ne.g. An environment that is composed of:\n- A laptop in the living room, for writing codes\n- A baremetal workstation with GPU/FPGA in the office, for running machine-learning workloads\n- ACI (Azure Container Instances) containers, for running other workloads that do not require a complete Kubernetes cluster\n- EKS (Amazon Elastic Kubernetes Service) pods, for workloads that heavily access Amazon S3 buckets\n- GKE (Google Kubernetes Engine) pods, for running gVisor-armored workloads\n\nFor production environments, setting up VPNs rather than NoRouter would be the right choice.\n\n## Download\n\nThe binaries are available at https://github.com/norouter/norouter/releases .\n\nSee also [Getting Started](https://norouter.io/docs/getting-started/).\n\n## Quick usage\n\n- Install the `norouter` binary to all the hosts. Run `norouter show-installer` to show an installation script.\n- Create a manifest YAML file. Run `norouter show-example` to show an example manifest.\n- Run `norouter \u003cFILE\u003e` to start NoRouter with the specified manifest YAML file.\n\n### Example 1: Port forwarding across localhost + Docker + Kubernetes + LXD + SSH\n\nRun `norouter \u003cFILE\u003e` with the following YAML file:\n\n```yaml\nhosts:\n# localhost\n  local:\n    vip: \"127.0.42.100\"\n# Docker \u0026 Podman container (docker exec, podman exec)\n  docker:\n    cmd: \"docker exec -i some-container norouter\"\n    vip: \"127.0.42.101\"\n    ports: [\"8080:127.0.0.1:80\"]\n# Writing /etc/hosts is possible on most Docker and Kubernetes containers\n    writeEtcHosts: true\n# Kubernetes Pod (kubectl exec)\n  kube:\n    cmd: \"kubectl --context=some-context exec -i some-pod -- norouter\"\n    vip: \"127.0.42.102\"\n    ports: [\"8080:127.0.0.1:80\"]\n# Writing /etc/hosts is possible on most Docker and Kubernetes containers\n    writeEtcHosts: true\n# LXD container (lxc exec)\n  lxd:\n    cmd: \"lxc exec some-container -- norouter\"\n    vip: \"127.0.42.103\"\n    ports: [\"8080:127.0.0.1:80\"]\n# SSH\n# If your key has a passphrase, make sure to configure ssh-agent so that NoRouter can login to the remote host automatically.\n  ssh:\n    cmd: \"ssh some-user@some-ssh-host.example.com -- norouter\"\n    vip: \"127.0.42.104\"\n    ports: [\"8080:127.0.0.1:80\"]\n```\n\nIn this example, 127.0.42.101:8080 on each hosts is forwarded to the port 80 of the Docker container.\n\nTry:\n\n```console\n$ curl http://127.0.42.101:8080\n$ docker exec some-container curl http://127.0.42.101:8080\n$ kubectl --context=some-context exec some-pod -- curl http://127.0.42.101:8080\n$ lxc exec some-container -- curl http://127.0.42.101:8080\n$ ssh some-user@some-ssh-host.example.com -- curl http://127.0.42.101:8080\n```\n\nSimilarly, 127.0.42.102:8080 is forwarded to the port 80 of the Kubernetes Pod,\n127.0.42.103:8080 is forwarderd to the port 80 of the LXD container,\nand 127.0.42.104:8080 is forwarded to the port 80 of `some-ssh-host.example.com`.\n\n### Example 2: Virtual VPN connection into `docker network create` networks\nThis example shows steps to use NoRouter for creating an HTTP proxy that works like a VPN router\nthat connects clients into `docker network create` networks.\n\nThis technique also works with remote Docker, rootless Docker, Docker for Mac, and even with Podman.\nRead `docker` as `podman` for the usage with Podman.\n\nFirst, create a Docker network named \"foo\", and create an nginx container named \"nginx\" there:\n```console\n$ docker network create foo\n$ docker run -d --name nginx --hostname nginx --network foo nginx:alpine\n```\n\nThen, create a \"bastion\" container in the same network, and install NoRouter into it:\n```console\n$ docker run -d --name bastion --network foo alpine sleep infinity\n$ norouter show-installer | docker exec -i bastion sh\n```\n\nLaunch `norouter example2.yaml` with the following YAML:\n```yaml\nhosts:\n  local:\n    vip: \"127.0.42.100\"\n    http:\n      listen: \"127.0.0.1:18080\"\n    loopback:\n      disable: true\n  bastion:\n    cmd: \"docker exec -i bastion /root/bin/norouter\"\n    vip: \"127.0.42.101\"\nroutes:\n  - via: bastion\n    to: [\"0.0.0.0/0\", \"*\"]\n```\n\nThe \"nginx\" container can be connected from the host as follows:\n```console\n$ export http_proxy=http://127.0.0.1:18080\n$ curl http://nginx\n```\n\nIf you are using Podman, try `curl http://nginx.dns.podman` rather than `curl http://nginx` .\n\n### Example 3: Virtual VPN connection into Kubernetes networks\n\nExample 2 can be also applied to Kubernetes clusters, just by replacing `docker exec` with `kubectl exec`.\n\n```console\n$ export http_proxy=http://127.0.0.1:18080\n$ curl http://nginx.default.svc.cluster.local\n```\n\n### Example 4: Aggregate VPCs of AWS, Azure, and GCP\n\nThe following example provides an HTTP proxy that virtually aggregates VPCs of AWS, Azure, and GCP:\n\n```yaml\nhosts:\n  local:\n    vip: \"127.0.42.100\"\n    http:\n      listen: \"127.0.0.1:18080\"\n  aws_bastion:\n    cmd: \"ssh aws_bastion -- ~/bin/norouter\"\n    vip: \"127.0.42.101\"\n  azure_bastion:\n    cmd: \"ssh azure_bastion -- ~/bin/norouter\"\n    vip: \"127.0.42.102\"\n  gcp_bastion:\n    cmd: \"ssh gcp_bastion -- ~/bin/norouter\"\n    vip: \"127.0.42.103\"\nroutes:\n  - via: aws_bastion\n    to:\n      - \"*.compute.internal\"\n  - via: azure_bastion\n    to:\n      - \"*.internal.cloudapp.net\"\n  - via: gcp_bastion\n    to:\n# Substitute \"example-123456\" with your own GCP project ID\n      - \"*.example-123456.internal\"\n```\n\nThe localhost can access all remote hosts in these networks:\n\n```console\n$ export http_proxy=http://127.0.0.1:18080\n$ curl http://ip-XXX-XXX-XX-XXX.ap-northeast-1.compute.internal\n$ curl http://some-azure-host.internal.cloudapp.net\n$ curl http://some-gcp-host.asia-northeast1-b.c.example-123456.internal\n```\n\n## Documentation\n\n- [Top](https://norouter.io/docs/)\n- [Getting Started](https://norouter.io/docs/getting-started/)\n  - [Download](https://norouter.io/docs/getting-started/download/)\n  - [First example](https://norouter.io/docs/getting-started/first-example/)\n  - [Name resolution](https://norouter.io/docs/getting-started/name-resolution/)\n  - [VPN-ish mode](https://norouter.io/docs/getting-started/vpn/)\n- [Examples](https://norouter.io/docs/examples/)\n  - [Docker](https://norouter.io/docs/examples/docker/)\n  - [Podman](https://norouter.io/docs/examples/podman/)\n  - [Kubernetes](https://norouter.io/docs/examples/kubernetes/)\n  - [LXD](https://norouter.io/docs/examples/lxd/)\n  - [SSH](https://norouter.io/docs/examples/ssh/)\n  - [Azure Container Instances](https://norouter.io/docs/examples/azure-container-instances/)\n  - [AWS/Azure/GCP VPCs](https://norouter.io/docs/examples/vpc/)\n- [Troubleshooting](https://norouter.io/docs/troubleshooting/)\n- [Command reference](https://norouter.io/docs/command-reference/)\n  - [`norouter`](https://norouter.io/docs/command-reference/norouter/)\n  - [`norouter manager`](https://norouter.io/docs/command-reference/norouter-manager/)\n  - [`norouter agent`](https://norouter.io/docs/command-reference/norouter-agent/)\n  - [`norouter show-example`](https://norouter.io/docs/command-reference/norouter-show-example/)\n  - [`norouter show-installer`](https://norouter.io/docs/command-reference/norouter-show-installer/)\n- [YAML reference](https://norouter.io/docs/yaml-reference/)\n- [How it works](https://norouter.io/docs/how-it-works/)\n- [Roadmap](https://norouter.io/docs/roadmap/)\n- [Similar projects](https://norouter.io/docs/similar-projects/)\n- [Artwork](https://norouter.io/docs/artwork/)\n\n## Installing NoRouter from source\n\n```console\n$ make\n$ sudo make install\n```\n\n## Contributing to NoRouter\n\n- Please certify your [Developer Certificate of Origin (DCO)](https://developercertificate.org/), by signing off your commit with `git commit -s` and with your real name.\n- Please add documents and tests whenever possible.\n\n- - -\n\nNoRouter is licensed under the terms of [Apache License, Version 2.0](./LICENSE).\n\nCopyright (C) NoRouter authors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorouter%2Fnorouter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorouter%2Fnorouter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorouter%2Fnorouter/lists"}