wesher/README.md

3.1 KiB

wesher

Mesh overlay network manager, using wireguard.

⚠ WARNING: since mesh membership is controlled by a mesh-wide pre-shared key, this effectively downgrades some of the security benefits from wireguard. See "security considerations" below for more info.

Quickstart

Before starting, make sure wireguard is installed on all nodes.

Install wesher on all nodes with:

$ go get github.com/costela/wesher

On the first node (assuming $GOPATH/bin is in the $PATH):

# wesher

Running the command above on a terminal will currently output a generated cluster key, like:

new cluster key generated: XXXXX

Then, on any further node:

# wesher --clusterkey XXXXX --joinaddrs x.x.x.x

Where XXXXX is the base64 encoded 32 bit key printed by the step above and x.x.x.x is the hostname or IP of any of the nodes already joined to the mesh cluster.

Note: wireguard, and therefore wesher, need root access.

Overview

Configuration options

All options can be passed either as command-line flags or environment variables:

Option Env Description Default
--cluster-key WESHER_CLUSTER_KEY shared key for cluster membership; must be 32 bytes base64 encoded; will be generated if not provided
--join WESHER_JOIN comma separated list of hostnames or IP addresses to existing cluster members; if not provided, will attempt resuming any known state or otherwise wait for further members
--bind-addr WESHER_BIND_ADDR IP address to bind to for cluster membership 0.0.0.0
--cluster-port WESHER_CLUSTER_PORT port used for membership gossip traffic (both TCP and UDP); must be the same across cluster 7946
--wireguard-port WESHER_WIREGUARD_PORT port used for wireguard traffic (UDP); must be the same across cluster 51820
--overlay-net WESHER_OVERLAY_NET the network in which to allocate addresses for the overlay mesh network (CIDR format); smaller networks increase the chance of IP collision 10.0.0.0/8
--interface WESHER_INTERFACE name of the wireguard interface to create and manage wgoverlay
--log-level WESHER_LOG_LEVEL set the verbosity (debug/info/warn/error) warn

Security considerations

The decision of whom to allow in the mesh is made by memberlist and is secured by a cluster-wide pre-shared key. Compromise of this key will allow an attacker to:

  • access services exposed on the overlay network
  • impersonate and/or disrupt traffic to/from other nodes It will not, however, allow the attacker access to decrypt the traffic between other nodes.

This pre-shared key is currently static, set up during cluster bootstrapping, but will - in a future version - be rotated.

Current known limitations

Overlay IP collisions

Since the assignment of IPs on the overlay network is currently decided by the individual node and implemented as a naive hashing of the hostname, there can be no guarantee two hosts will not generate the same overlay IPs. This limitation may be worked around in a future version.