{"id":13581526,"url":"https://github.com/pojntfx/gon2n","last_synced_at":"2025-04-06T10:32:33.797Z","repository":{"id":57516676,"uuid":"230541031","full_name":"pojntfx/gon2n","owner":"pojntfx","description":"Go bindings, management daemons and CLIs for n2n edges and supernodes.","archived":true,"fork":false,"pushed_at":"2023-02-26T03:22:14.000Z","size":312,"stargazers_count":83,"open_issues_count":2,"forks_count":19,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-11-05T21:44:44.581Z","etag":null,"topics":["daemon","go","golang","n2n","p2p","peer-to-peer","vpn"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pojntfx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-12-28T01:16:27.000Z","updated_at":"2024-05-30T06:23:34.000Z","dependencies_parsed_at":"2024-01-16T20:54:06.980Z","dependency_job_id":"33823c46-57c2-4024-8dfe-a89b2a7658f6","html_url":"https://github.com/pojntfx/gon2n","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fgon2n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fgon2n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fgon2n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fgon2n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pojntfx","download_url":"https://codeload.github.com/pojntfx/gon2n/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247470358,"owners_count":20944146,"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":["daemon","go","golang","n2n","p2p","peer-to-peer","vpn"],"created_at":"2024-08-01T15:02:04.434Z","updated_at":"2025-04-06T10:32:33.139Z","avatar_url":"https://github.com/pojntfx.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# gon2n\n\nGo bindings, management daemons and CLIs for n2n edges and supernodes.\n\n[![hydrun CI](https://github.com/pojntfx/gon2n/actions/workflows/hydrun.yaml/badge.svg)](https://github.com/pojntfx/gon2n/actions/workflows/hydrun.yaml)\n[![Matrix](https://img.shields.io/matrix/gon2n:matrix.org)](https://matrix.to/#/#gon2n:matrix.org?via=matrix.org)\n[![Binary Downloads](https://img.shields.io/github/downloads/pojntfx/gon2n/total?label=binary%20downloads)](https://github.com/pojntfx/gon2n/releases)\n\n## Overview\n\n`gon2n` is a collection of Go bindings, management daemons and CLIs for the n2n peer-to-peer VPN. n2n is built of two main components:\n\n- `edge`s, which are the \"VPN clients\" that manage the TUN/TAP interfaces on every device that is part of a community (a overlay network)\n- `supernode`s, which are responsible for both keeping track of the `edge`s of a community as well routing traffic to `edge`s which can't communicate to each other with a peer-to-peer connection\n\nIn a similar way, `gon2n` is built of multiple components. The components are:\n\n- `edged`, a n2n edge management daemon with a gRPC interface\n- `supernoded`, a n2n supernode management daemon with a gRPC interface\n- `edgectl`, a CLI for `edged`\n- `supernodectl`, a CLI for `supernoded`\n\n## Installation\n\nStatic binaries are available on [GitHub releases](https://github.com/pojntfx/gon2n/releases).\n\nOn Linux, you can install them like so:\n\n```shell\n$ curl -L -o /tmp/supernoded \"https://github.com/pojntfx/gon2n/releases/latest/download/supernoded.linux-$(uname -m)\"\n$ curl -L -o /tmp/edged \"https://github.com/pojntfx/gon2n/releases/latest/download/edged.linux-$(uname -m)\"\n$ curl -L -o /tmp/supernodectl \"https://github.com/pojntfx/gon2n/releases/latest/download/supernodectl.linux-$(uname -m)\"\n$ curl -L -o /tmp/edgectl \"https://github.com/pojntfx/gon2n/releases/latest/download/edgectl.linux-$(uname -m)\"\n$ sudo install /tmp/{supernoded,edged,supernodectl,edgectl} /usr/local/bin\n$ sudo setcap cap_net_admin+ep /usr/local/bin/edged # This allows rootless execution\n```\n\nOn macOS, you can use the following (macOS does not support TAP devices, so only the client CLIs work):\n\n```shell\n$ curl -L -o /tmp/supernodectl \"https://github.com/pojntfx/gon2n/releases/latest/download/supernodectl.linux-$(uname -m)\"\n$ curl -L -o /tmp/edgectl \"https://github.com/pojntfx/gon2n/releases/latest/download/edgectl.linux-$(uname -m)\"\n$ sudo install /tmp/{supernodectl,edgectl} /usr/local/bin\n```\n\nOn Windows, the following should work (using PowerShell as administrator; Windows does not support TAP devices, so only the client CLIs work):\n\n```shell\nPS\u003e Invoke-WebRequest https://github.com/pojntfx/gon2n/releases/latest/download/supernodectl.windows-x86_64.exe -OutFile \\Windows\\System32\\supernodectl.exe\nPS\u003e Invoke-WebRequest https://github.com/pojntfx/gon2n/releases/latest/download/edgectl.windows-x86_64.exe -OutFile \\Windows\\System32\\edgectl.exe\n```\n\nYou can find binaries for more operating systems and architectures on [GitHub releases](https://github.com/pojntfx/gon2n/releases).\n\n## Usage\n\n### 1. Setting up the Supernode\n\nFirst, start the supernode management daemon:\n\n```shell\n$ supernoded -f examples/supernoded.yaml\n{\"level\":\"info\",\"timestamp\":\"2021-10-24T20:32:21Z\",\"message\":\"Starting server\"}\n```\n\nNow, in a new terminal, create a supernode:\n\n```shell\n$ supernodectl apply -f examples/supernode.yaml\nsupernode \"69b92323-9384-46fb-8814-663ea3ff98fe\" created\n```\n\nYou can retrieve the running supernodes with `supernodectl get`:\n\n```shell\n$ supernodectl get\nID                                      LISTEN PORT\n69b92323-9384-46fb-8814-663ea3ff98fe    1234\n```\n\n### 2. Setting up the Edges\n\nIn this example, we'll be creating two edges, which will both run on the same host - in a real-world scenario, you probably want to run an edge management daemon per host. First, start the edge management daemon:\n\n```shell\n$ edged examples/edged.yaml\n{\"level\":\"info\",\"timestamp\":\"2021-10-24T20:38:34Z\",\"message\":\"Starting server\"}\n```\n\nNow, in a new terminal, create the edges:\n\n```shell\n$ edgectl apply -f examples/edge-1.yaml\nedge \"74125834-6ad7-4c90-8c28-f22edda10dad\" created\n$ edgectl apply -f examples/edge-2.yaml\nedge \"7f1c60ed-e298-47a1-abe7-cefa61e4d886\" created\n```\n\nYou can retrieve the running edges with `edgectl get`:\n\n```shell\n$ edgectl get\nID                                      COMMUNITY NAME  LOCAL PORT      SUPERNODE HOST:PORT ENCRYPTION METHOD       DEVICE NAME\n74125834-6ad7-4c90-8c28-f22edda10dad    mynetwork       0               localhost:1234      2                       edge0\n7f1c60ed-e298-47a1-abe7-cefa61e4d886    mynetwork       0               localhost:1234      2                       edge1\n```\n\nThe log of the edge management daemon started earlier also shows the changes:\n\n```shell\n24/Oct/2021 22:41:07 [edge_utils.c:2578] Adding supernode[0] = localhost:1234\n{\"level\":\"info\",\"timestamp\":\"2021-10-24T20:41:07Z\",\"message\":\"Starting edge\"}\n24/Oct/2021 22:41:07 [edge_utils.c:211] supernode 0 =\u003e localhost:1234\n24/Oct/2021 22:41:07 [edge_utils.c:2104] TOS set to 0x10\n24/Oct/2021 22:41:07 [edge_utils.c:727] Successfully joined multicast group 224.0.0.68:1968\n24/Oct/2021 22:41:07 [edge_utils.c:1803] [OK] Edge Peer \u003c\u003c\u003c ================ \u003e\u003e\u003e Super Node\n24/Oct/2021 22:41:12 [edge_utils.c:2578] Adding supernode[0] = localhost:1234\n{\"level\":\"info\",\"timestamp\":\"2021-10-24T20:41:12Z\",\"message\":\"Starting edge\"}\n24/Oct/2021 22:41:12 [edge_utils.c:211] supernode 0 =\u003e localhost:1234\n24/Oct/2021 22:41:12 [edge_utils.c:2104] TOS set to 0x10\n24/Oct/2021 22:41:12 [edge_utils.c:727] Successfully joined multicast group 224.0.0.68:1968\n24/Oct/2021 22:41:12 [edge_utils.c:1756] [P2P] Rx REGISTER from 100.64.154.252:53854\n24/Oct/2021 22:41:12 [edge_utils.c:1756] [P2P] Rx REGISTER from 100.64.154.252:34474\n24/Oct/2021 22:41:12 [edge_utils.c:1756] [P2P] Rx REGISTER from 100.64.154.252:34474\n# ...\n```\n\nIf we check with `ip a`, we can also see the created `edge0` and `edge1` interfaces:\n\n```shell\n$ ip a\n# ...\n553: edge0: \u003cBROADCAST,MULTICAST,UP,LOWER_UP\u003e mtu 1500 qdisc fq_codel state UNKNOWN group default qlen 1000\n    link/ether de:ad:be:ef:01:10 brd ff:ff:ff:ff:ff:ff\n    inet 192.168.1.1/24 brd 192.168.1.255 scope global edge0\n       valid_lft forever preferred_lft forever\n    inet6 fe80::dcad:beff:feef:110/64 scope link\n       valid_lft forever preferred_lft forever\n554: edge1: \u003cBROADCAST,MULTICAST,UP,LOWER_UP\u003e mtu 1500 qdisc fq_codel state UNKNOWN group default qlen 1000\n    link/ether de:a0:be:ef:01:10 brd ff:ff:ff:ff:ff:ff\n    inet 192.168.1.2/24 brd 192.168.1.255 scope global edge1\n       valid_lft forever preferred_lft forever\n    inet6 fe80::dca0:beff:feef:110/64 scope link\n       valid_lft forever preferred_lft forever\n# ...\n```\n\n🚀 **That's it!** We've successfully created a layer 2 overlay network.\n\nBe sure to check out the [reference](#reference) for more information.\n\n## Reference\n\n### Daemons\n\nThere are two daemons, `supernoded` and `edged`; the latter requires `CAP_NET_ADMIN` capabilities to manage the TUN/TAP interfaces.\n\n#### `supernoded`\n\nYou may also set the flags by setting env variables in the format `SUPERNODED_[FLAG]` (i.e. `SUPERNODED_SUPERNODED_CONFIGFILE=examples/supernoded.yaml`) or by using a [configuration file](examples/supernoded.yaml).\n\n```bash\n$ supernoded --help\nsupernoded is the n2n supernode management daemon.\n\nFind more information at:\nhttps://github.com/pojntfx/gon2n\n\nUsage:\n  supernoded [flags]\n\nFlags:\n  -h, --help                               help for supernoded\n  -f, --supernoded.configFile string       Configuration file to use.\n  -l, --supernoded.listenHostPort string   TCP listen host:port. (default \"localhost:1050\")\n```\n\n#### `edged`\n\nYou may also set the flags by setting env variables in the format `EDGED_[FLAG]` (i.e. `EDGED_EDGED_CONFIGFILE=examples/edged.yaml`) or by using a [configuration file](examples/edged.yaml).\n\n```bash\n$ edged --help\nedged is the n2n edge management daemon.\n\nFind more information at:\nhttps://github.com/pojntfx/gon2n\n\nUsage:\n  edged [flags]\n\nFlags:\n  -f, --edged.configFile string       Configuration file to use.\n  -l, --edged.listenHostPort string   TCP listen host:port. (default \"localhost:1060\")\n  -h, --help                          help for edged\n```\n\n### Client CLIs\n\nThere are two client CLIs, `supernodectl` and `edgectl`.\n\n#### `supernodectl`\n\nYou may also set the flags by setting env variables in the format `SUPERNODE_[FLAG]` (i.e. `SUPERNODE_SUPERNODE_CONFIGFILE=examples/supernode.yaml`) or by using a [configuration file](examples/supernode.yaml).\n\n```bash\n$ supernodectl --help\nsupernodectl manages supernoded, the n2n supernode management daemon.\n\nFind more information at:\nhttps://github.com/pojntfx/gon2n\n\nUsage:\n  supernodectl [command]\n\nAvailable Commands:\n  apply       Apply a supernode\n  completion  generate the autocompletion script for the specified shell\n  delete      Delete one or more supernode(s)\n  get         Get one or all supernode(s)\n  help        Help about any command\n\nFlags:\n  -h, --help   help for supernodectl\n\nUse \"supernodectl [command] --help\" for more information about a command.\n```\n\n#### `edgectl`\n\nYou may also set the flags by setting env variables in the format `EDGE_[FLAG]` (i.e. `EDGE_EDGE_CONFIGFILE=examples/edge-1.yaml`) or by using a [configuration file](examples/edge-1.yaml) ([alternative with DHCP instead of static IPs](examples/edge-dhcp.yaml)).\n\n```bash\n$ edgectl --help\nedgectl manages edged, the n2n edge management daemon.\n\nFind more information at:\nhttps://github.com/pojntfx/gon2n\n\nUsage:\n  edgectl [command]\n\nAvailable Commands:\n  apply       Apply an edge\n  completion  generate the autocompletion script for the specified shell\n  delete      Delete one or more edge(s)\n  get         Get one or all edge(s)\n  help        Help about any command\n\nFlags:\n  -h, --help   help for edgectl\n\nUse \"edgectl [command] --help\" for more information about a command.\n```\n\n## Acknowledgements\n\n- This project would not have been possible were it not for [@ntop](https://github.com/ntop)'s [n2n](https://github.com/ntop/n2n) VPN; be sure to check it out too!\n- All the rest of the authors who worked on the dependencies used! Thanks a lot!\n\n## Contributing\n\nTo contribute, please use the [GitHub flow](https://guides.github.com/introduction/flow/) and follow our [Code of Conduct](./CODE_OF_CONDUCT.md).\n\nTo build gon2n locally, run:\n\n```shell\n$ git clone https://github.com/pojntfx/gon2n.git\n$ cd gon2n\n$ make depend\n$ make\n$ sudo make run/edged # Or run/supernoded etc.\n```\n\nHave any questions or need help? Chat with us [on Matrix](https://matrix.to/#/#gon2n:matrix.org?via=matrix.org)!\n\n## License\n\ngon2n (c) 2021 Felicitas Pojtinger and contributors\n\nSPDX-License-Identifier: AGPL-3.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpojntfx%2Fgon2n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpojntfx%2Fgon2n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpojntfx%2Fgon2n/lists"}