README
¶
Webmesh
Webmesh is a simple, distributed, and zero-configuration WireGuard™ mesh solution for Linux, FreeBSD, macOS, and Windows. It allows for easily creating a mesh network between multiple hosts, and provides a simple API for managing the network. 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.
Webmesh is not a VPN, but rather a mesh network. It is designed to be used in conjunction with existing network infrastructure, and not as a replacement for it. It is also not a replacement for WireGuard™, but rather a way to manage a WireGuard™ mesh network. Connections are made into the network via direct links, over ICE (WebRTC) connections, or over LibP2P circuit relays. It differs from other WireGuard™ management solutions in that:
- It is designed to be distributed and extensible, relying on no single controller or database.
- The network is malleable and topology is governed by the user, not the controller.
- A plugin API is provided for adding additional functionality, such as a distributed database for storing the mesh state or additional authentication mechanisms.
- An application API is also provided for interacting with the mesh network, and is used by the CLI and GUI applications.
Getting Started
Detailed instructions can be found in the Getting Started guide on the project website. For examples of different topologies and the various features available, see the examples directory.
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.
Building
The Makefile contains several targets for building the project.
You can run make help to see all the available targets.
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.
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.
Community
Join me on Discord or in the webmesh channel on the Gophers Slack.
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
Become a Github Sponsor.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
webmesh-node
Entrypoint for webmesh nodes.
|
Entrypoint for webmesh nodes. |
|
webmesh-wasm
Entrypoint for webmesh nodes.
|
Entrypoint for webmesh nodes. |
|
wmctl
Entrypoint for wmctl command.
|
Entrypoint for wmctl command. |
|
examples
|
|
|
remote-server-plugin
This is an example plugin that runs as a remote server.
|
This is an example plugin that runs as a remote server. |
|
pkg
|
|
|
cmd/bridgecmd
Package bridgecmd contains the entrypoint for running a bridge between multiple clusters.
|
Package bridgecmd contains the entrypoint for running a bridge between multiple clusters. |
|
cmd/ctlcmd
Package ctlcmd contains the wmctl CLI tool.
|
Package ctlcmd contains the wmctl CLI tool. |
|
cmd/ctlcmd/config
Package config contains the wmctl CLI tool configuration.
|
Package config contains the wmctl CLI tool configuration. |
|
cmd/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. |
|
cmd/nodecmd
Package nodecmd contains the entrypoint for webmesh nodes.
|
Package nodecmd contains the entrypoint for webmesh nodes. |
|
cmd/nodedamon
Package nodedaemon contains the entrypoint for webmesh nodes running as an application daemon.
|
Package nodedaemon contains the entrypoint for webmesh nodes running as an application daemon. |
|
config
Package options contains configuration parsing for the nodecmd.
|
Package options contains configuration parsing for the nodecmd. |
|
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. |
|
crypto
Package crypto contains cryptographic utilities.
|
Package crypto contains cryptographic utilities. |
|
embed
Package embed provides a simplified way to run a webmesh node in-process.
|
Package embed provides a simplified way to run a webmesh node in-process. |
|
libp2p/protocol
Package protocol defines the libp2p webmesh protocol.
|
Package protocol defines the libp2p webmesh protocol. |
|
libp2p/transport
Package transport defines the libp2p webmesh transport.
|
Package transport defines the libp2p webmesh transport. |
|
libp2p/util
Package util provides utility functions for the webmesh libp2p integrations.
|
Package util provides utility functions for the webmesh libp2p integrations. |
|
libp2p/wgtransport
Package wgtransport implements a Webmesh WireGuard transport for libp2p.
|
Package wgtransport implements a Webmesh WireGuard transport for libp2p. |
|
mesh
Package mesh contains the mesh store and related interfaces.
|
Package mesh contains the mesh store and related interfaces. |
|
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/nat64
Package nat64 provides a stateless bi-directional NAT64 implementation.
|
Package nat64 provides a stateless bi-directional NAT64 implementation. |
|
net/relay
Package relay holds low-level primitives for proxying streams to a WireGuard interface.
|
Package relay holds low-level primitives for proxying streams to a WireGuard interface. |
|
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/buffers
Package buffers contains facilities for changing system buffer sizes.
|
Package buffers contains facilities for changing system buffer sizes. |
|
net/system/dns
Package dns contains utility functions for DNS.
|
Package dns contains utility functions for DNS. |
|
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/transport
Package transport defines the interfaces needed for various mesh operations.
|
Package transport defines the interfaces needed for various mesh operations. |
|
net/transport/datachannels
Package datachannels provides a WebRTC data channel API for port forwarding.
|
Package datachannels provides a WebRTC data channel API for port forwarding. |
|
net/transport/libp2p
Package libp2p provides webmesh integration with libp2p.
|
Package libp2p provides webmesh integration with libp2p. |
|
net/transport/tcp
Package tcp provides TCP based transports.
|
Package tcp provides TCP based transports. |
|
net/wireguard
Package wireguard contains utilities for working with wireguard interfaces.
|
Package wireguard contains utilities for working with wireguard interfaces. |
|
plugins/builtins
Package builtins contains the built-in plugin implementations.
|
Package builtins contains the built-in plugin implementations. |
|
plugins/builtins/basicauth
Package basicauth is an authentication plugin that uses basic auth.
|
Package basicauth is an authentication plugin that uses basic auth. |
|
plugins/builtins/debug
Package debug implements a plugin that exposes an HTTP server for debugging purposes.
|
Package debug implements a plugin that exposes an HTTP server for debugging purposes. |
|
plugins/builtins/ipam
Package ipam provides a plugin for simple mesh IPAM.
|
Package ipam provides a plugin for simple mesh IPAM. |
|
plugins/builtins/ldap
Package ldap implements a basic LDAP authentication plugin.
|
Package ldap implements a basic LDAP authentication plugin. |
|
plugins/builtins/mtls
Package mtls is an authentication plugin that uses mTLS.
|
Package mtls is an authentication plugin that uses mTLS. |
|
plugins/clients
Package clients contains the interface for using plugin clients.
|
Package clients contains the interface for using plugin clients. |
|
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. |
|
raft
Package raft contains Raft consensus for WebMesh.
|
Package raft contains Raft consensus for WebMesh. |
|
raft/fsm
Package fsm implements the Raft FSM.
|
Package fsm implements the Raft FSM. |
|
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/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/membership
Package membership contains the webmesh membership service.
|
Package membership contains the webmesh membership service. |
|
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/metrics
Package metrics contains the HTTP server for exposing Prometheus metrics.
|
Package metrics contains the HTTP server for exposing Prometheus metrics. |
|
services/node
Package node contains the webmesh node service.
|
Package node contains the webmesh node service. |
|
services/rbac
Package rbac contains utilities for evaluating requests against roles.
|
Package rbac contains utilities for evaluating requests against roles. |
|
services/storage
Package storage provides the storage server.
|
Package storage provides the storage server. |
|
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 and providing storage backends for raft.
|
Package storage contains the interface for storing and retrieving data about the state of the mesh and providing storage backends for raft. |
|
storage/badgerdb
Package badgerdb implements the storage backends using BadgerDB.
|
Package badgerdb implements the storage backends using BadgerDB. |
|
storage/memory
Package memory implements an in-memory storage backend suitable for testing.
|
Package memory implements an in-memory storage backend suitable for testing. |
|
util/meshutil
Package meshutil contains helpers for computing networking information from the mesh.
|
Package meshutil contains helpers for computing networking information from the mesh. |
|
util/netutil
package netutil provides common utility functions for networking.
|
package netutil provides common utility functions for networking. |
|
version
Package version contains compile-time version information.
|
Package version contains compile-time version information. |
Click to show internal directories.
Click to hide internal directories.