README
¶
Webmesh
Webmesh is a simple, distributed, and zero-configuration WireGuard™ mesh solution for Linux, FreeBSD, macOS, and Windows. It is designed to be easy to use, and to work well with existing network infrastructure. For a more detailed introduction and extended documentation, please see the project website.
This repository contains the core functionality of the Webmesh Project. It implements the Webmesh API in Go.
This project is not yet ready for production use, but I hope to rapidly get there. For now, expect backwards-incompatible changes.
Getting Started
If you'd like to play with the project on Kubernetes, there is a work-in-progress Operator in the operator repository. It works fine on most clusters, including ephemeral docker-based ones, but is not yet ready for production use.
Detailed instructions can be found in the Getting Started guide on the project website.
The below instructions are a quick-start guide for running a simple mesh on a single host using docker.
# You can remove the --global.no-ipv6 flag if you have IPv6 connectivity on your docker network.
docker run --rm --privileged --name=bootstrap-node ghcr.io/webmeshproj/node:latest \
--global.insecure \
--global.no-ipv6 \
--global.detect-endpoints \
--global.detect-private-endpoints \
--bootstrap.enabled
Once the node is ready, to join another node to the network you can run the following:
docker run --rm --privileged ghcr.io/webmeshproj/node:latest \
--global.insecure \
--global.no-ipv6 \
--mesh.join-address=bootstrap-node:8443
The two containers should now be connected to each other over WireGuard and you can exec into them to test connectivity.
The wmctl utility included in this repository can also be used to connect and/or query the APIs.
More documentation on the CLI utility will be added soon.
wmctl connect --insecure --no-ipv6 --join-server=<container_ip>:8443
Configuration can be provided as CLI flags (as shown above) or via a configuration file and environment variables. Full details can be found on the configuration section of the project website. Administration of the network can be done via the API using the CLI or custom tooling.
Building
The Makefile contains several targets for building the project.
Since the project uses CGO, it is recommended to build the project in a container with static libraries.
The helpers in the Makefile will do this for you when building for distribution.
You can run make help to see all the available targets.It looks very interesting, but I'm still on the fence about it. It doesn't look so bad in practice without all the theoretical type parameters laid around.
Roadmap
- GUI Application. In the works over here.
- Potential SaaS offering for those who don't want to run their own controllers or have a simple off-site backup of the mesh state.
- Ability to peer with other meshes. This would allow for a mesh to be split into multiple smaller meshes that can still communicate with each other.
Most other functionality that is provided by other similar projects already exists in the kernel or in other projects. For example, NAT64 and DNS64 have several ways of being configured, but could still be seen as a potential common use-case. There is a question as to how many of those things should be "auto-configured" by a node and how much should be left up to the user.
Contributing
Contributions are welcome and encouraged. Please see the contributing docs for more information.
Special Thanks
The developers of rqlite for inspiration on managing a distributed database.
The incredible work done by the pion team for WebRTC in Go.
Legal
WireGuard is a registered trademark of Jason A. Donenfeld.
Support
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gendocs
command
|
|
|
node
command
Entrypoint for webmesh nodes.
|
Entrypoint for webmesh nodes. |
|
wmctl
command
Entrypoint for wmctl command.
|
Entrypoint for wmctl command. |
|
examples
|
|
|
remote-server-plugin
command
This is an example plugin that runs as a remote server.
|
This is an example plugin that runs as a remote server. |
|
pkg
|
|
|
context
Package context provides facilities for storing and retrieving values from context objects.
|
Package context provides facilities for storing and retrieving values from context objects. |
|
ctlcmd
Package ctlcmd contains the wmctl CLI tool.
|
Package ctlcmd contains the wmctl CLI tool. |
|
ctlcmd/config
Package config contains the wmctl CLI tool configuration.
|
Package config contains the wmctl CLI tool configuration. |
|
ctlcmd/connect
Package connect contains an implementation of the connect subcommand.
|
Package connect contains an implementation of the connect subcommand. |
|
ctlcmd/pki
Package pki contains an interface for managing the PKI for a cluster using mTLS.
|
Package pki contains an interface for managing the PKI for a cluster using mTLS. |
|
meshdb
Package meshdb contains the schemas, generated code, and interfaces for interacting with the mesh database.
|
Package meshdb contains the schemas, generated code, and interfaces for interacting with the mesh database. |
|
meshdb/networking
Package networking contains interfaces to the database models for Network ACLs and Routes.
|
Package networking contains interfaces to the database models for Network ACLs and Routes. |
|
meshdb/peers
Package peers contains an interface for managing nodes in the mesh.
|
Package peers contains an interface for managing nodes in the mesh. |
|
meshdb/raftlogs
Package raftlogs provides facilities for applying raft logs to a database.
|
Package raftlogs provides facilities for applying raft logs to a database. |
|
meshdb/rbac
Package rbac contains interfaces to the database models for RBAC.
|
Package rbac contains interfaces to the database models for RBAC. |
|
meshdb/snapshots
Package snapshots provides an interface for managing raft snapshots.
|
Package snapshots provides an interface for managing raft snapshots. |
|
meshdb/state
Package state provides an interface for querying mesh state.
|
Package state provides an interface for querying mesh state. |
|
net/datachannels
Package datachannels provides a WebRTC data channel API for port forwarding.
|
Package datachannels provides a WebRTC data channel API for port forwarding. |
|
net/inspect
Package inspect contains facilities for tapping into the network stack.
|
Package inspect contains facilities for tapping into the network stack. |
|
net/mesh
Package mesh contains helpers for computing networking information from the mesh.
|
Package mesh contains helpers for computing networking information from the mesh. |
|
net/system
Package system contains utilities for managing network interfaces on the system.
|
Package system contains utilities for managing network interfaces on the system. |
|
net/system/firewall
Package firewall contains an interface for interacting with the system firewall.
|
Package firewall contains an interface for interacting with the system firewall. |
|
net/wireguard
Package wireguard contains utilities for working with wireguard interfaces.
|
Package wireguard contains utilities for working with wireguard interfaces. |
|
nodecmd
Package nodecmd contains the entrypoint for webmesh nodes.
|
Package nodecmd contains the entrypoint for webmesh nodes. |
|
nodecmd/global
Package global provides global configurations that can override others.
|
Package global provides global configurations that can override others. |
|
plugins
Package plugins contains the interface for using plugins to extend the functionality of the node.
|
Package plugins contains the interface for using plugins to extend the functionality of the node. |
|
plugins/basicauth
Package basicauth is an authentication plugin that uses basic auth.
|
Package basicauth is an authentication plugin that uses basic auth. |
|
plugins/clients
Package clients contains the interface for using plugin clients.
|
Package clients contains the interface for using plugin clients. |
|
plugins/ipam
Package ipam provides a plugin for simple mesh IPAM.
|
Package ipam provides a plugin for simple mesh IPAM. |
|
plugins/ldap
Package ldap implements a basic LDAP authentication plugin.
|
Package ldap implements a basic LDAP authentication plugin. |
|
plugins/mtls
Package mtls is an authentication plugin that uses mTLS.
|
Package mtls is an authentication plugin that uses mTLS. |
|
plugins/plugindb
Package plugindb contains a SQL driver for running data queries over a Plugin Query stream.
|
Package plugindb contains a SQL driver for running data queries over a Plugin Query stream. |
|
services
Package services contains the gRPC server for inter-node communication.
|
Package services contains the gRPC server for inter-node communication. |
|
services/admin
Package admin provides the admin gRPC server.
|
Package admin provides the admin gRPC server. |
|
services/dashboard
Package dashboard contains a service that serves a web dashboard.
|
Package dashboard contains a service that serves a web dashboard. |
|
services/leaderproxy
Package leaderproxy provides a gRPC interceptor that proxies requests to the leader node.
|
Package leaderproxy provides a gRPC interceptor that proxies requests to the leader node. |
|
services/meshapi
Package meshapi contains the webmesh Mesh API service.
|
Package meshapi contains the webmesh Mesh API service. |
|
services/meshdns
Package meshdns contains the Mesh DNS server.
|
Package meshdns contains the Mesh DNS server. |
|
services/node
Package node contains the webmesh node service.
|
Package node contains the webmesh node service. |
|
services/peerdiscovery
Package peerdiscovery contains the webmesh PeerDiscovery API service.
|
Package peerdiscovery contains the webmesh PeerDiscovery API service. |
|
services/rbac
Package rbac contains utilities for evaluating requests against roles.
|
Package rbac contains utilities for evaluating requests against roles. |
|
services/turn
Package turn contains the STUN/TURN server.
|
Package turn contains the STUN/TURN server. |
|
services/webrtc
Package webrtc contains the webmesh WebRTC service.
|
Package webrtc contains the webmesh WebRTC service. |
|
storage
Package storage contains the interface for storing and retrieving data about the state of the mesh.
|
Package storage contains the interface for storing and retrieving data about the state of the mesh. |
|
store
Package store provides raft consensus and data storage for webmesh nodes.
|
Package store provides raft consensus and data storage for webmesh nodes. |
|
store/streamlayer
Package streamlayer contains the Raft stream layer implementation.
|
Package streamlayer contains the Raft stream layer implementation. |
|
version
Package version contains compile-time version information.
|
Package version contains compile-time version information. |