75 lines
3.1 KiB
Markdown
75 lines
3.1 KiB
Markdown
# wesher
|
|
|
|
Mesh overlay network manager, using [wireguard](https://www.wireguard.com/).
|
|
|
|
**⚠ 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](https://www.wireguard.com/) 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](github.com/hashicorp/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.
|
|
|