AsiaBSDCon 2026

The open-source tool STUNMESH-go helps devices create WireGuard connections when they all sit behind NAT or CGNAT networks. These network setups make it hard for devices to connect directly to each other. NAT and CGNAT are common in many situations: home networks, mobile networks, and enterprise networks. The tool uses STUN protocol to help devices find their public IP addresses and ports. It has a special feature: it can use the same port for both WireGuard and STUN traffic by working directly with the WireGuard kernel module. This approach is more efficient than solutions using embedded wireguard-go with a proxy setup, like Tailscale does. It means devices can connect directly without needing a central relay server. This saves bandwidth and reduces latency.
STUNMESH-go works well on Linux systems. This means it already supports popular network solutions like VyOS and OpenWrt. However, many network devices and firewalls use FreeBSD-based systems. pfSense and OPNsense are two popular firewall systems that run on FreeBSD. To support these important platforms, we needed to add proper FreeBSD support. Also, macOS support is valuable for developers and network engineers who want to test and develop P2P VPN solutions on their computers. In this work, we added full support for FreeBSD and macOS. This helps developers and network engineers who use BSD or Apple systems to build P2P WireGuard networks, even when they are behind NAT or CGNAT.
We explain the technical problems we met during this work. On Linux, STUNMESH-go uses raw sockets with BPF filtering. This lets it watch all network interfaces at the same time. But FreeBSD and macOS work differently. They use BPF with interface-specific packet capture. We had to write code that listens on all network interfaces for STUN messages, but not on the WireGuard interface itself. This design works better when systems have multiple network connections or backup routes. We tested this with OPNsense virtual machines to check that it works correctly in real firewall situations.
We also added the health monitoring system to both platforms. This system checks if the tunnel is working by sending ping messages to each peer. If a connection fails, it tries to reconnect automatically. It uses smart retry logic with exponential backoff. This means it waits longer between each retry attempt to avoid overloading the network. Each peer can have its own ping settings with different timeout and interval values. This feature is very useful for mobile networks and changing network situations common on BSD and macOS. In ideal conditions, when network changes happen, the system can detect the connection problem and reconnect quickly.
The tool has a plugin system that we also ported to these platforms. STUNMESH-go supports different key-value storage backends through plugins. Users can even write custom plugins using the exec plugin interface. We made sure this plugin system works on all platforms. Users can connect to various DNS providers or key-value storage services like Cloudflare. This helps with automatic peer discovery and configuration sharing. When a peer's IP address changes, it updates the DNS record automatically. Other peers can then find the new address and reconnect. This works well with WireGuard's built-in roaming capability. As the WireGuard documentation describes, the server finds peer endpoints by checking where authenticated data comes from. If endpoints change, both client and server update their settings by learning from where they receive correctly authenticated data. This means there is full IP roaming on both ends. STUNMESH-go uses this feature by helping peers discover their new public addresses quickly through STUN and updating the shared configuration storage.
We successfully built and ran STUNMESH-go on FreeBSD and modern macOS versions. We set up full-mesh P2P networks with nodes behind NAT or CGNAT. We tested that direct P2P connections work reliably on these platforms. Our tests included VyOS routers with LTE modems, OPNsense firewalls running on FreeBSD, and mixed environments with BSD, macOS, and Linux nodes. We did not measure detailed performance like latency or speed. Our main goal was to check that connections work in real network conditions. The results show that BSD and macOS platforms can run direct P2P WireGuard networks using STUNMESH-go reliably.
We share our experience and future directions. Important insights include how to handle networking across different platforms in Go, best ways to prepare build environments on Unix-like systems, and why good documentation matters for platform-specific setup. We also worked with BSD and macOS communities to get feedback and support. This helped us find unusual problems and platform-specific issues. Future work includes making the build process easier, improving documentation for BSD and macOS users, and helping more people in these communities use P2P network tools. We also plan to add support for more BSD variants and improve the testing framework for firewall platforms like pfSense and OPNsense.