Wireguard Mesh Tool

This is a small project designed to experiment with distribution and maintenance of Wireguard Meshes for private networks using Protocol Routing.

Of necessity, the Routing Daemons are running against the wireguard interfaces.

If there are local Routing Requirements, they are beyond the scope of this mesh development. This is intended to produce a routing mesh - care and feeding of the mesh is your responsibility.

Requirements

• Fedora prolly any modern linux will work
• Wireguard included with Fedora (wireguard-tools)
• Python included with almost all modern linux
• BIRD modular protocol routing daemon
• Shorewall local linux firewall configuration, with the simple two-interface setup

See INSTALL.md - for installation details about Virtual Machines and other details.

See SITESETUP.md - for bootstrapping the wgmesh config

TODO

• Build init workflow
• init route53 workflow
• add hooks for other DNS model

Serious Bugs

• lack of coherent documentation about how to configure the meshes

• the key names are arbitrary and poorly handled

• the instructions suck for setting up the nodes/site/etc.

• The wgmesh.yaml needs to be properly defined

• the wgconfig needs to be clearer

• the wgsite needs to be clearer.

• the wgpub

• build node removal workflow.

• wgconfig should perform the initial wghost configuration.

• Local Site-specific configurations integration?

  • 1/2 done, calls -local scripts.

• Rename netns "private" to a mesh-specific locus.

• startup script should prolly be written in python.

• Non-dns method of transmitting deploy_messages.

• Warning command:

  • check default and private for forwarding
  • check for addresses on WG interfaces
  • Check for wg up
  • Check for veth device presence
  • Check veth addressed
  • Monitor/Warn on UDP port conflicts on startup.

• Examine ifaddr dependency.

• Simplify wgconfig, remove wgdeploy redundant code blocks.

• Fix deploy template args structure so that wg/table/ifdetails are portable throughout the templates

Getting Started

Example config: wgmesh.yaml Example Domain: mesh.example.com

Site Config

• Copy wgmesh-example.yaml to wgmesh.yaml
• Edit the file and set the primitives.
  • The ipv6 segment should be a 48bit ULA subnet.
• Execute site publisher: wgsite wgmesh.yaml
• Publish the DNS Information. (TXT record 'mesh.example.com')

Endpoint Config

• Connect to mesh endpoints, setup python virtualenv if desired.

• Install wgmesh package; pip install wgmesh

• Setup host registration the mesh (run as root or sudo):

   wgconfig mesh.example.com
  

• Configure the local host:

   wgconfig -i ens3 -T ens4 -I 172.22.15.243/24  mesh.example.com
  

• Publish Site import data:

  wghost mesh.example.com
  

Site Config

• Import the host by copying the output into the site controller. wgsite -i <hash> wgmesh.yaml
• Once host(s) are ready, publish Host-base DNS records: wgpub wgmesh.yaml
• Publish output to the [uuid].wgmesh.example.com TXT records.

Endpoint Config

• Deploy on the local hosts: wgdeploy mesh.example.com

Publish and deploy processes can be automated.

Warnings:

wghost setup, and wgsite -i must be a human-approved process, because this adds nodes (e.g. trusted keys) to the mesh.

Route53 Integration

If you are using Route53 for DNS hosting, you may setup automated DNS posting from the site configurator. This causes wgsite, and wgpub to automatically update records in DNS.

Add the aws_access_key_id and aws_secret_access_key to the Site Mesh file in the global section.

global:
  aws_access_key_id: XXXXXXXXXXXXXXXXXX
  aws_secret_access_key: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Mesh Endpoints

The Mesh endpoints expect a VM (or machine) with two attached interfaces. One interface should be configured for Internet access. The other interface must connect to the local LAN.

Mesh BGP Configuration is setup for exchanging routes between Mesh Endpoints across the wireguard links. Local routing configuration can be attached using BIRD's modular configuration capability.

Process Flow

Troubleshooting

UDP Ports

Check for UDP Port conflicts. Other elements on the system may conflict with the UDP ports. UDP Ports are assigned from the base port in an ascending fashion. Reliable reports have come in and high-end (49900+) ports have caused OS-related interference.

Lowering the ports resolved the issue.

BIRD Status

BFD Is enabled to make troubleshooting easier. The endpoints are all known at wgdeploy time, and this neatly describes the config when monitoring. Use this script to watch bird on an endpoint, and to see changes in status as nodes are up'd and down'd.

util/birdwatch.sh

watch -n1 "birdc -s /var/run/bird-private.sock show prot;echo '';birdc -s /var/run/bird-private.sock show bfd session;echo '';birdc -s /var/run/bird-private.sock show route count"

Testing Subnet

If you're experimenting with the MESH, and just want to send packets racing around, start the tester namespace:

sudo systemctl start systemd-netns-access@tester systemd-netns@tester

From within the namespace, you can ping the other nodes. (Taken from a 3-node test setup.)

[root@vpn-nodea eis]# ip netns exec tester fping 192.168.101.1 192.168.102.100 192.168.103.10
192.168.101.1 is alive
192.168.102.100 is alive
192.168.103.10 is alive

Contributing

Pull requests and feature requests gladly accepted.

wgmesh is licensed under the MIT/Expat license.

Changelog

• 2020-12-04: Joshua Schmidlkofer - project setup
• 2021-03-03: 0.5 - functional test release.
• 2021-03-03: 0.5.1 - packaging test release.