Share
Embed
FOSDEM 2026: STUNMESH-go: Building P2P WireGuard Mesh Without Self-Hosted Infrastructure
Video Recording: https://fosdem.org/2026/schedule/event/YQWEDC-stunmesh-go_building_p2p_wireguard_mesh_without_self-hosted_infrastructure/
Date Huang
February 02, 2026
Transcript
24 slides
-
STUNMESH-go: Building P2P WireGuard Mesh Without Self-Hosted Infrastructure Date (Yu-Chiang)
Huang <tjjh89017 [at] hotmail.com> @ FOSDEM 2026 Network DevRoom 1 -
Who am I: Date (Yu-Chiang) Huang • Cloud and Network
Solution Architect with 6 years of experience • Creator of STUNMESH-go and EZIO Project • Expertise in major public cloud networking services and on-prem datacenter networking design • Specialized in Cloud Network, OpenStack, Kubernetes, SD-WAN, and open-source • Extensive speaking experience at international conferences 2 -
Agenda • What is STUNMESH-go? What does STUNMESH-go try to
solve? • STUN implementation in different platform (Linux, MacOS, FreeBSD) • Compatibility with WireGuard kernel module • Plugin system without self-hosted service • Minimizing binary size for embedded systems • Next Step for STUNMESH-go 3 -
Before we start: Prerequisite Knowledge • Basic WireGuard concept and
usage • Stateful Firewall concept • Different NAT/CG-NAT types (e.g. Cone vs. Symmetric, EIF, EIM) • Basic STUN RFC5389 concept and usage • UDP Hole Punching concept 4 -
What is STUNMESH-go? • It’s a WireGuard helper for devices
behind Firewall and NAT • Make true Peer-to-Peer WireGuard connection • No self-hosted server needed • Cross-Platform and Cross-Architecture support • Inspired by FOSDEM 2018 - BulletinBoard DHT and wireguard-p2p by Manuel Schoelling ◦ Thanks to Manuel & FOSDEM • GPL v2 or Later • https://github.com/tjjh89017/stunmesh-go/ Github Link 5 -
What does STUNMESH-go try to solve? • wireguard-p2p still needs
to proxy the traffic and do the STUN separately • Other solutions still need Self-hosted server for connection exchange • Without forking and embedding Wireguard-go ◦ to share the same port socket for STUN implementation (what Tailscale did) 6 -
STUN with Proxy wg port A port C Proxy Send/Recv
STUN STUN Server Listen on / send&recv packet Remote Peer Proxy connect to remote peer It might be another Proxy Config wg remote endpoint with 127.0.0.1:<port B> thru Proxy Proxy does the “Port Translation” for WG for easy STUN procedure Forward packet port B Info Exchange 7 -
What does STUNMESH-go try to solve? • wireguard-p2p still need
to proxy the traffic and do the STUN separately ◦ Remove the Proxy by re-using the same port as WireGuard used for STUN ◦ WireGuard connect to the remote peer directly • Self-hosted server for connection exchange ◦ Implement Plugin to re-use the existing public service as Key-Value storage • Without forking and embedding Wireguard-go ◦ Different STUN implementation details will be covered later. 8 -
STUN implementation • Re-use the WireGuard port for STUN •
We ensure that the <Public IP:Port> discovered by STUN is precisely the same one of WireGuard. 9 -
STUN without Proxy wg port A STUNMESH-go Send/Recv STUN STUN
Server Listen on / send&recv packet directly to remote peer Remote Peer Config wg remote endpoint with true remote peer endpoint Info Exchange Get remote peer endpoint from plugin system 10 -
STUN (Linux-based) • Utilize Raw Sockets combined with a cBPF
with self-construct STUN request • Raw Sockets ◦ Send and Receive STUN packets. • cBPF (SO_ATTACH_FILTER) ◦ Capture only STUN packets (using the STUN magic cookie/header). • All other non-STUN packets flow to the WireGuard as normal, ensuring zero disruption to the VPN traffic while we correctly discover the public endpoint. 11 -
STUN (MacOS, FreeBSD, BSD-based) • Unlike Linux, FreeBSD and macOS
would not receive any packets from Raw Sockets, need to rely on BPF /dev/bpf for low-level packet capture. • Raw Sockets ◦ Allow the STUNMESH-go to send and receive raw packets directly on the network interface. • BPF (/dev/bpf) ◦ Monitor all interfaces and capture only STUN packets for a short period (using the STUN magic cookie/header) 12 -
Compatibility with WireGuard kernel module • Sidecar STUN: ◦ STUNMESH-go
relies on OS feature to hijack the same UDP port as WireGuard • Control Plane Only: ◦ Only need to configure remote endpoint on demand, without proxying the data plane ◦ The highly optimized WireGuard kernel module still handles all the high-speed VPN traffic • Compatible with WireGuard Kernel Module and WireGuard-go userspace implementation • Without proxies or embedded WireGuard-go to implement complex feature set 13 -
How Peer Info Exchange? • STUN is One-Way: ◦ The
STUN server only tells your device its public IP and Port • The Missing Link: ◦ You still do not know the remote peer's public endpoint. • Why not self-hosted exchange platform? ◦ If I have a self-hosted exchange platform, why not just make it as a VPN hub? • Exchange Platform without self-hosted: ◦ This should be a secure, external mechanism for both peers to Upload and Retrieve each others public endpoints. 14 -
Plugin System without self-hosted service • Flexible Generic Backend Storage:
◦ The system utilizes existing Public Key-Value services (like Cloudflare DNS or custom APIs) • Secure Exchange ◦ Encrypted by Curve25519 Sealedbox before being stored; This process reuses the WireGuard peer key pair, simplifying key management. • Concise and Direct ◦ Any Key-Value storage can fit this model. ◦ Implement a custom plugin to define your own serialization, enabling integration with any custom storage solution. 15 -
Plugin System API (Key) KEY = hex( sha1( concat( <LOCAL
PUBLIC KEY>, <REMOTE PUBLIC KEY> ) ) ) // Local sends Local’s endpoint info to Remote 16 -
Plugin System API (Value) VALUE = hex( encrypt( stringify( {
"ipv4": "1.2.3.4:1234", "ipv6": "[2001:db8::1]:1234" } ) ) ) 17 -
Plugin System API KEY = HEX_STRING VALUE = HEX_STRING PLUGIN.set(KEY,
VALUE) VALUE2 = PLUGIN.get(KEY2) 18 -
Plugin Example (Cloudflare DNS) • DNS TXT Record as Key-Value
Store ◦ Cloudflare's DNS TXT records can act as the simple key-value storage backend. • Key Mapping ◦ The unique identifier is mapped to the subdomain name(e.g. [key].<subdomain>.<zone>) • Value Mapping ◦ The Encrypted Public Endpoint (IP:Port) is stored in the TXT record field value. • This uses existing, highly available public infrastructure for secure peer exchange. 19 -
Minimizing binary size for embedded systems • STUNMESH-go is very
small, just 2.5MB with UPX compression • The memory footprint is low, using under 20MB of RAM • Good for use in embedded systems and tiny devices 20 -
Next Steps for STUNMESH-go • Full IPv6 Support (Under testing,
after v1.5.1) • Ping module detection, Smart Re-connect (Under testing) • In-Band Heartbeat (Under planning) • Testing with Satellite Network (StarLink, under planning, seeking for support) 21 -
We are COSCUP from Taiwan • Biggest Open Source Conference
in Asia • Co-hosted with UbuCon Asia • 8th~9th August 2026 • With Wordwide Speakers and Attendees • https://coscup.org • QR Code or Search “COSCUP” 22 -
Q&A • For Further Question, Discussion, Anything • You can
open an issue in GitHub, or contact me at Linkedin My Linkedin Page 23