wg-easy Overview

wg-easy.md

wg-easy

wg-easy is a client-server model WireGuard configuration management system designed to automate the provisioning of WireGuard based VPN networks.

Example usage

$ wg-easy|wg-easy-set

Design overview

• Simple Python3 implementation with a single external dependency (pyYAML)
• SSH for communication between clients and servers
• YAML based flat-file peer database

Components

Hub (Server)

SSH accessible host responsible for (optionally) issuing IP addresses and keeping track of the set of connected Peers. Must itself be or have knowledge of an addressible WireGuard peer.

Peer (Client)

Any Linux host with WireGuard and wg-easy installed interested in joining a WireGuard network. Peers register with one or many Hubs.

Implementation overview

• wg-easy Shell script - Ran on the Peer to generate its WireGuard private key and invoke hub.py on a remote Hub ($HUB_HOST) via SSH, passing as arugments a WireGuard public key, its name ($PEER_NAME) and either its desired IP address or the string dynamic if it wishes for the Hub to assign it an IP address.
• hub.py Python3 script - writes the arguments passed to it out as YAML file (1 file per registered Peer) and returns YAML to be consumed by wg-easy-set. Only returns reachable Peers selected to act as Hubs in its responding YAML.
• wg-easy-set Python3 script - Consumes the YAML output of hub.py and executes the appropriate ip and wg set commands to configure the local WireGuard interface.
• wg.py - Python3 library - Wraps the ip and wg command-line utilities. Used by hub.py and wg-easy-set to handle WireGuard interface configuration.