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
Install Webmesh
- GUI Application
- On Linux, the GUI application relies on the
webmeshdservice from the CLI installations below.
- On Linux, the GUI application relies on the
- CLI and Docker Packages
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.
Developers
Integrating your project with Webmesh networks is easy.
All APIs are written in protobuf in the API repository.
Applications can integrate either via the webmeshd process or by embedding this package directly.
Libraries and other integrations are available for the following languages and environments:
- Go
- JS/Typescript
- Kubernetes
- Webmesh CNI
- Webmesh Operator (Work in Progress)
More documentation on direct embedding will be provided later. For now, you can find examples in the examples/embedded directory. The godoc for the embed package is also a good place to start.
Building
The Makefile contains several targets for building the project.
You can run make help to see all the available targets.
Roadmap
- More storage provider implementations.
- 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. |
|
webmeshd
Entrypoint for the webmesh daemon process.
|
Entrypoint for the webmesh daemon process. |
|
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/cmdutil
Package cmdutil provides utilities for working with the command-line entrypoints.
|
Package cmdutil provides utilities for working with the command-line entrypoints. |
|
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/daemoncmd
Package daemoncmd contains the entrypoint for webmesh nodes running as an application daemon.
|
Package daemoncmd contains the entrypoint for webmesh nodes running as an application daemon. |
|
cmd/nodecmd
Package nodecmd contains the entrypoint for webmesh nodes.
|
Package nodecmd contains the entrypoint for webmesh nodes. |
|
common
Package common contains common utility functions.
|
Package common contains common utility functions. |
|
config
Package config contains configuration options and parsing for the webmesh node CLI and daemon server.
|
Package config contains configuration options and parsing for the webmesh node CLI and daemon server. |
|
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. |
|
logging
Package logging contains logging utilities and adapters for various logging libraries.
|
Package logging contains logging utilities and adapters for various logging libraries. |
|
meshnet
Package meshnet provides the core networking functionality for WebMesh.
|
Package meshnet provides the core networking functionality for WebMesh. |
|
meshnet/nat64
Package nat64 provides a stateless bi-directional NAT64 implementation.
|
Package nat64 provides a stateless bi-directional NAT64 implementation. |
|
meshnet/netutil
package netutil provides common utility functions for networking.
|
package netutil provides common utility functions for networking. |
|
meshnet/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. |
|
meshnet/system
Package system contains utilities for managing network interfaces on the system.
|
Package system contains utilities for managing network interfaces on the system. |
|
meshnet/system/buffers
Package buffers contains facilities for changing system buffer sizes.
|
Package buffers contains facilities for changing system buffer sizes. |
|
meshnet/system/dns
Package dns contains utility functions for DNS.
|
Package dns contains utility functions for DNS. |
|
meshnet/system/firewall
Package firewall contains an interface for interacting with the system firewall.
|
Package firewall contains an interface for interacting with the system firewall. |
|
meshnet/testutil
Package testutil contains testing utilities for networking and meshnet.
|
Package testutil contains testing utilities for networking and meshnet. |
|
meshnet/transport
Package transport defines the interfaces needed for various mesh operations.
|
Package transport defines the interfaces needed for various mesh operations. |
|
meshnet/transport/datachannels
Package datachannels provides a WebRTC data channel API for port forwarding.
|
Package datachannels provides a WebRTC data channel API for port forwarding. |
|
meshnet/transport/libp2p
Package libp2p provides webmesh integration with libp2p.
|
Package libp2p provides webmesh integration with libp2p. |
|
meshnet/transport/libp2p/embedded/protocol
Package protocol defines the libp2p webmesh protocol.
|
Package protocol defines the libp2p webmesh protocol. |
|
meshnet/transport/libp2p/embedded/transport
Package transport defines the libp2p webmesh transport.
|
Package transport defines the libp2p webmesh transport. |
|
meshnet/transport/libp2p/embedded/util
Package util provides utility functions for the webmesh libp2p integrations.
|
Package util provides utility functions for the webmesh libp2p integrations. |
|
meshnet/transport/libp2p/embedded/wgtransport
Package wgtransport implements a Webmesh WireGuard transport for libp2p.
|
Package wgtransport implements a Webmesh WireGuard transport for libp2p. |
|
meshnet/transport/tcp
Package tcp provides TCP based transports.
|
Package tcp provides TCP based transports. |
|
meshnet/transport/webrtc
Package webrtc contains transports for WebRTC.
|
Package webrtc contains transports for WebRTC. |
|
meshnet/wireguard
Package wireguard contains utilities for working with wireguard interfaces.
|
Package wireguard contains utilities for working with wireguard interfaces. |
|
meshnode
Package meshnode contains the mesh node and related interfaces.
|
Package meshnode contains the mesh node and related interfaces. |
|
plugins
Package plugins contains the plugin manager.
|
Package plugins contains the plugin manager. |
|
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/idauth
Package idauth is an authentication plugin based on libp2p peer IDs.
|
Package idauth is an authentication plugin based on libp2p peer IDs. |
|
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. |
|
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 defines the interfaces for the storage provider.
|
Package storage defines the interfaces for the storage provider. |
|
storage/errors
Package errors contains error definitions for storage providers.
|
Package errors contains error definitions for storage providers. |
|
storage/meshdb
Package meshdb implements a storage.Database using any storage.MeshStorage instance.
|
Package meshdb implements a storage.Database using any storage.MeshStorage instance. |
|
storage/meshdb/graphstore
Package graph implements a graph data structure for the mesh network.
|
Package graph implements a graph data structure for the mesh network. |
|
storage/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. |
|
storage/meshdb/rbac
Package rbac contains interfaces to the database models for RBAC.
|
Package rbac contains interfaces to the database models for RBAC. |
|
storage/meshdb/state
Package state provides an interface for querying mesh state.
|
Package state provides an interface for querying mesh state. |
|
storage/providers
Package providers contains the built-in storage providers.
|
Package providers contains the built-in storage providers. |
|
storage/providers/backends/badgerdb
Package badgerdb implements the storage backends using BadgerDB.
|
Package badgerdb implements the storage backends using BadgerDB. |
|
storage/providers/external
Package external provides a storage provider that uses a storage plugin to manage mesh storage and consensus.
|
Package external provides a storage provider that uses a storage plugin to manage mesh storage and consensus. |
|
storage/providers/passthrough
Package passthrough provides a passthrough storage provider.
|
Package passthrough provides a passthrough storage provider. |
|
storage/providers/raftstorage
Package raftstorage implements a Raft-backed storage provider.
|
Package raftstorage implements a Raft-backed storage provider. |
|
storage/providers/raftstorage/fsm
Package fsm implements the Raft FSM.
|
Package fsm implements the Raft FSM. |
|
storage/providers/raftstorage/raftlogs
Package raftlogs provides facilities for applying raft logs to a database.
|
Package raftlogs provides facilities for applying raft logs to a database. |
|
storage/providers/raftstorage/snapshots
Package snapshots provides an interface for managing raft snapshots.
|
Package snapshots provides an interface for managing raft snapshots. |
|
storage/rpcdb
Package rpcdb provides a meshdb that operates over RPC.
|
Package rpcdb provides a meshdb that operates over RPC. |
|
storage/rpcsrv
Package rpcsrv contains utilities for serving mesh databases over RPC.
|
Package rpcsrv contains utilities for serving mesh databases over RPC. |
|
storage/testutil
Package testutil contains testing utilities for storage providers and backends.
|
Package testutil contains testing utilities for storage providers and backends. |
|
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.