{"id":13564814,"url":"https://github.com/aschmidt75/wgmesh","last_synced_at":"2025-09-13T07:14:47.399Z","repository":{"id":53453609,"uuid":"334189925","full_name":"aschmidt75/wgmesh","owner":"aschmidt75","description":"Automatically build private mesh networks using wireguard and serf.io","archived":false,"fork":false,"pushed_at":"2021-04-11T15:37:41.000Z","size":755,"stargazers_count":34,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T21:36:29.022Z","etag":null,"topics":["decentralized","golang","serf","wireguard"],"latest_commit_sha":null,"homepage":"","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/aschmidt75.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}},"created_at":"2021-01-29T15:47:21.000Z","updated_at":"2024-10-31T01:46:30.000Z","dependencies_parsed_at":"2022-09-11T23:02:55.619Z","dependency_job_id":null,"html_url":"https://github.com/aschmidt75/wgmesh","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschmidt75%2Fwgmesh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschmidt75%2Fwgmesh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschmidt75%2Fwgmesh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aschmidt75%2Fwgmesh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aschmidt75","download_url":"https://codeload.github.com/aschmidt75/wgmesh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312037,"owners_count":20918344,"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":["decentralized","golang","serf","wireguard"],"created_at":"2024-08-01T13:01:36.469Z","updated_at":"2025-04-05T09:17:54.698Z","avatar_url":"https://github.com/aschmidt75.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# wgmesh\n\nAutomatically build private wireguard mesh networks.\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/aschmidt75/wgmesh)](https://goreportcard.com/report/github.com/aschmidt75/wgmesh)\n[![Go](https://github.com/aschmidt75/wgmesh/actions/workflows/go.yml/badge.svg)](https://github.com/aschmidt75/wgmesh/actions/workflows/go.yml)\n\n![wgmesh Dashboard](docs/wgmesh-ui-sample.png)\n\n## How it works\n\n* A mesh consist of interconnected nodes. Each node has a [wireguard](https://www.wireguard.com/) interface with all other nodes registered as peers. The mesh is fully-connected through the wireguard-based overlay network. Each node can IP-reach all other nodes via direct host routes.\n* At least one of the mesh nodes is a bootstrap node. Besides the wireguard peerings it runs a gRPC-based mesh endpoint, where other nodes can issue join requests.\n* New nodes can enter the mesh by joining via a bootstrap node. The bootstrap node learns about the joining node and its wireguard endpoint and public key. It distributes this information to the other mesh nodes. It also fowards a list of mesh peers to the new joining node so it is able to configure its own wireguard interface.\n* Existing mesh nodes learn about the new joining node from the bootstrap node and update their wireguard peer configuration accordingly.\n* Mesh nodes integrate [serf.io](https://serf.io) to maintain state about the network topology, learn about new nodes joining and failing nodes or nodes leaving the mesh. This is done using serf's encrypted gossip-based cluster membership protocol.\n* The bootstrap node's gRPC endpoint runs TLS with requesting and validating client certificates. This way new nodes are required to authenticate themselves by x.509 certificates. \n\n## Build\n\nThe default targets of `Makefile` generate protobuf and grpc parts and build the binary in `dist/`. It also builds the web ui (and needs node/npm for this), and\nappends the web artifacts using [go.rice](https://github.com/GeertJohan/go.rice).\n\n```bash\n$ make all\n```\n\nThe binary can be built without web ui support:\n\n```bash\n$ make clean gen build\n```\n\nAdditionally, goreleaser can be used to create a snapshot release for different platforms (also in `dist/`)\n\n```bash\n$ make release\n```\n\nSo for a full, releaseable build one needs\n* go (tested w/ version go1.15.5 darwin/amd64)\n* [rice](https://github.com/GeertJohan/go.rice)\n* node (tested w/ v14.16.0)\n* npm (tested w/ 6.14.11)\n* [goreleaser](https://github.com/goreleaser/goreleaser) (tested w/ version 0.155.0)\n\n## Prerequisites\n\n* Linux\n* Wireguard module installed/enabled in kernel\n* Works best with a non-NATed setup. It can partially work with NAT, but there's no guarantee.\n\n## Usage\n\nThe fastest way to start a mesh is using the development mode, either with a bunch of local virtual machine or with available cloud instances.\n[This walkthrough](docs/multipass-demo-setup.md) shows how to use it with local multipass-based ubuntu lts instances.\n\nThe mesh is initiated with a first bootstrap node. It creates a wireguard interface and starts listening for join requests on a gRPC endpoint. Make sure that the bootstrap node is not behind a NAT. In development mode, no security/TLS/mesh encryption is enforced, so all other nodes can join with authentication. This simplifies testing but is not suitable for non-development purposes.\n\n```bash\n# wgmesh bootstrap -dev \n\n** Mesh name:                       xoJbYw07PM\n** Mesh CIDR range:                 10.232.0.0/16\n** gRPC Service listener endpoint:  0.0.0.0:5000\n** This node's name:                xoJbYw07PMAE80101\n** This node's mesh IP:             10.232.1.1\n**\n** This mesh is running in DEVELOPMENT MODE without encryption.\n** Do not use this in a production setup.\n**\n** To have another node join this mesh, use this command:\n** wgmesh join -v -dev -n xoJbYw07PM -bootstrap-addr \u003cPUBLIC_IP_OF_THIS_NODE\u003e:5000\n**\n** To inspect the wireguard interface and its peer data use:\n** wg show wgxoJbYw07PM\n**\n** To inspect the current mesh status use: wgmesh info\n**\n```\n\nFor other nodes to join, the (public or private) IP address of the bootstrap node is needed, so joining nodes are able to connect. Switch to a second instance and run the join command as stated above:\n\n```bash\n# wgmesh join -v -dev -n xoJbYw07PM -bootstrap-addr 10.0.0.0:5000\n\nINFO[2021/02/27 10:46:31] Fetching external IP from STUN server\nINFO[2021/02/27 10:46:31] Using external IP when connecting with mesh   ip=\nINFO[2021/02/27 10:46:31] Created and configured wireguard interface wgxoJbYw07PM as no-up\nWARN[2021/02/27 10:46:31] Using insecure connection to gRPC mesh service\nINFO[2021/02/27 10:46:32] Starting gRPC Agent Service at /var/run/wgmesh.sock\n**\n** Mesh 'xoJbYw07PM' has been joined.\n**\n** Mesh name:                       xoJbYw07PM\n** Mesh CIDR range:                 10.232.0.0/16\n** This node's name:                xoJbYw07PMAE8B8DB\n** This node's mesh IP:             10.232.184.219\n**\n** This mesh is running in DEVELOPMENT MODE without encryption.\n** Do not use this in a production setup.\n**\n** To inspect the wireguard interface and its peer data use:\n** wg show wgxoJbYw07PM\n**\n** To inspect the current mesh status use: wgmesh info\n**\nINFO[2021/02/27 10:46:33] Mesh has 2 nodes\n```\n\nAdditional nodes can join using the same `join` command.\n\nOn any node, the `info` command prints out connected nodes:\n\n```bash\n# wgmesh info\nMesh 'xoJbYw07PM' has 2 nodes, started 2021-02-27 10:45:31 +0100 CET\nThis node 'xoJbYw07PMAE8B8DB' joined 2021-02-27 10:46:31 +0100 CET\n\nName              |Address        |Status |RTT |Tags                                |\nxoJbYw07PMAE8B8DB |10.232.184.219 |alive  |7   | _addr=, _port=54540,  |\nxoJbYw07PMAE80101 |10.232.1.1     |alive  |38  | _addr=, _port=54540, |\n```\n\nThe `ui` command start an HTTP server, serving a simple, vue-based dashboard. By default it binds\nto port 9095 on the localhost interface only. It does not authenticate clients and does not (yet) support TLS.\n\n```bash\n# wgmesh ui \nServing files on 127.0.0.1:9095, press ctrl-C to exit\n```\n\n## License\n\n(C) 2020,2021 @aschmidt75 \nApache License, Version 2.0\n\nWireguard ist a registered trademark of Jason A. Donenfeld / [wireguard.com](https://wireguard.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faschmidt75%2Fwgmesh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faschmidt75%2Fwgmesh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faschmidt75%2Fwgmesh/lists"}