FOSDEM 2026: STUNMESH-go: Building P2P WireGuard Mesh Without Self-Hosted Infrastructure

https://fosdem.org/2026/schedule/event/YQWEDC-stunmesh-go_building_p2p_wireguard_mesh_without_self-hosted_infrastructure/

Transcript

1. STUNMESH-go: Building P2P WireGuard Mesh Without Self-Hosted Infrastructure Date (Yu-Chiang) Huang <tjjh89017 [at] hotmail.com> @ FOSDEM 2026 Network DevRoom 1
2. 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
3. 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
4. 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
5. 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
6. 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
7. 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
8. 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
9. 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
10. 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
11. 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
12. 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
13. 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
14. 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
15. 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
16. Plugin System API (Key) KEY = hex( sha1( concat( <LOCAL PUBLIC KEY>, <REMOTE PUBLIC KEY> ) ) ) // Local sends Local’s endpoint info to Remote 16
17. Plugin System API (Value) VALUE = hex( encrypt( stringify( { "ipv4": "1.2.3.4:1234", "ipv6": "[2001:db8::1]:1234" } ) ) ) 17
18. Plugin System API KEY = HEX_STRING VALUE = HEX_STRING PLUGIN.set(KEY, VALUE) VALUE2 = PLUGIN.get(KEY2) 18
19. 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
20. 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
21. 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
22. 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
23. Q&A • For Further Question, Discussion, Anything • You can open an issue in GitHub, or contact me at Linkedin My Linkedin Page 23
24. Reference • https://archive.fosdem.org/2018/schedule/event/bulletinboard_dht/ • https://tailscale.com/kb/1035/wireguard 24