Zoltan Papp
8bf8fa968f
The keepalive deadlock fixed in #20 was one instance of a class the kernel module rules out by construction. This commit adopts the same two rules instead of working around the symptom. 1. Nothing reached from a timer callback may wait. In the kernel the callback runs in softirq: alloc_skb is GFP_ATOMIC and gives up, and wg_queue_enqueue_per_device_and_peer fails with -ENOSPC/-EPIPE and the packet is dropped or marked PACKET_STATE_DEAD. #20 made the keepalive allocation non-blocking but left the rest of the path waiting: a container allocation on the nonce-overflow branch and the two bounded queue sends in SendStagedPackets. Any of them, parked while holding the timer's runningLock, wedges Timer.DelSync and with it Peer.Stop, RemovePeer and Device.Close. SendKeepalive now runs sendStagedPackets(wait=false): a full pool or queue drops the batch; if the sequential sender already holds the batch it is emptied and unlocked so the sender passes over it. The public SendStagedPackets keeps waiting, so the TUN reader keeps its backpressure. 2. A peer holds at most MAX_STAGED_PACKETS (128) packets while waiting for a handshake; wg_xmit drops the oldest before adding a batch. Our staged queue was bounded in batches, not packets, and a GSO batch can carry 128 packets, so one peer that never completes its handshake could pin thousands of buffers and drain a capped pool for every other peer. StagePackets now enforces the packet bound with a per-peer counter, dropping the oldest batches first. That, not the handshake retry policy, is how the kernel keeps a dead peer from hurting the rest of the device. With the bound in place the handshakeAttempts change from #20 is not needed and is reverted: outbound traffic resets the counter again, as it does upstream and in wg_packet_send_queued_handshake_initiation, and SendHandshakeInitiation goes back to the upstream isRetry signature so these lines no longer diverge on merges. The revert also removes a problem that change introduced. It relied on the give-up branch of expiredRetransmitHandshake to release a dead peer's buffers, and that branch only runs after MaxTimerHandshakes failed retries - about 90 seconds. Until then the pool stayed drained, the TUN reader stayed parked and no peer on the device could send. And once the branch had run, nothing reset the counter again while traffic kept flowing: the next packet sent one initiation and re-armed the retransmit timer, which found the counter already past the limit and gave up after a single try, flushing the staged queue, deleting the keepalive timer and logging "giving up" every five seconds for as long as the peer was down and had traffic. Upstream and the kernel give each burst of new traffic a full 90-second budget instead, and now so do we. Tests: TestStagedSendKeepsHandshakeAttempts is replaced by TestStagedSendResetsHandshakeAttempts; TestStagePacketsBoundedPerPeer checks the packet bound and that dropped buffers return to the pool; TestSendKeepaliveWithFullOutboundQueue wedges the sequential sender and checks the keepalive still returns.
Go Implementation of WireGuard
This is an implementation of WireGuard in Go.
Usage
Most Linux kernel WireGuard users are used to adding an interface with ip link add wg0 type wireguard. With wireguard-go, instead simply run:
$ wireguard-go wg0
This will create an interface and fork into the background. To remove the interface, use the usual ip link del wg0, or if your system does not support removing interfaces directly, you may instead remove the control socket via rm -f /var/run/wireguard/wg0.sock, which will result in wireguard-go shutting down.
To run wireguard-go without forking to the background, pass -f or --foreground:
$ wireguard-go -f wg0
When an interface is running, you may use wg(8) to configure it, as well as the usual ip(8) and ifconfig(8) commands.
To run with more logging you may set the environment variable LOG_LEVEL=debug.
Platforms
Linux
This will run on Linux; however you should instead use the kernel module, which is faster and better integrated into the OS. See the installation page for instructions.
macOS
This runs on macOS using the utun driver. It does not yet support sticky sockets, and won't support fwmarks because of Darwin limitations. Since the utun driver cannot have arbitrary interface names, you must either use utun[0-9]+ for an explicit interface name or utun to have the kernel select one for you. If you choose utun as the interface name, and the environment variable WG_TUN_NAME_FILE is defined, then the actual name of the interface chosen by the kernel is written to the file specified by that variable.
Windows
This runs on Windows, but you should instead use it from the more fully featured Windows app, which uses this as a module.
FreeBSD
This will run on FreeBSD. It does not yet support sticky sockets. Fwmark is mapped to SO_USER_COOKIE.
OpenBSD
This will run on OpenBSD. It does not yet support sticky sockets. Fwmark is mapped to SO_RTABLE. Since the tun driver cannot have arbitrary interface names, you must either use tun[0-9]+ for an explicit interface name or tun to have the program select one for you. If you choose tun as the interface name, and the environment variable WG_TUN_NAME_FILE is defined, then the actual name of the interface chosen by the kernel is written to the file specified by that variable.
Building
This requires an installation of the latest version of Go.
$ git clone https://git.zx2c4.com/wireguard-go
$ cd wireguard-go
$ make
License
Copyright (C) 2017-2025 WireGuard LLC. All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.