WireGuard from Scratch

There was a period in my career when “set up a VPN” meant three days of reading OpenVPN docs, debugging certificate chains, and eventually getting something working that nobody could explain to their manager. WireGuard did not invent the VPN, but it did something more valuable: it made the VPN auditable, fast, and boring in the best possible sense. This post covers WireGuard from the cryptographic primitives up through production deployment patterns — road warrior access, site-to-site routing, diagnostics, and an honest look at where it fits and where it does not.

The VPN Landscape Before WireGuard

To appreciate what WireGuard does, you need to remember what came before it.

OpenVPN shipped in 2001 and became the de facto standard for open-source VPN over the following decade. It runs in userspace over TLS, supports TCP and UDP transports, and has an enormous feature surface. The codebase ballooned to roughly 70,000 lines of C. The certificate management story is a mess unless you have deployed a full PKI with Easy-RSA or something similar. Configuration files are verbose and easy to get subtly wrong. Performance is bounded by the fact that the TLS state machine runs on a single thread — on a modern server you might get 200-400 Mbps before you hit CPU limits, and every new connection burns through a TLS negotiation that takes hundreds of milliseconds.

IPsec predates even OpenVPN. The protocol suite itself is a collection of RFCs — AH, ESP, IKEv1, IKEv2, XAUTH, EAP, mode configs — and implementations like strongSwan and Libreswan expose every dial and lever that those RFCs describe. IPsec has strong kernel-level implementations and can hit genuinely impressive throughput numbers, especially with AES-NI hardware. But the configuration surface is brutal. IKEv2 connection profiles, proposal sets, transform sets, traffic selectors, leftid/rightid, reauthentication timers — it is entirely possible to deploy a functional IPsec tunnel and have no confident understanding of what security parameters you actually negotiated. Interoperability with Cisco, Palo Alto, and Juniper gear adds another layer of vendor-specific quirks.

Cisco AnyConnect and its open-source cousin OpenConnect serve the enterprise remote access market well but are proprietary or tightly coupled to Cisco infrastructure.

Jason Donenfeld started WireGuard around 2015 with a different premise: what if you constrained the design so aggressively that the entire VPN implementation could be read and understood by a security engineer in an afternoon? The kernel module shipped with approximately 4,000 lines of code — two orders of magnitude less than OpenVPN. One cipher suite, no negotiation, no X.509 certificates, no CA infrastructure. The protocol is published as a technical paper and the cryptographic construction is built on well-studied primitives with a clean composition story.

WireGuard was merged into the Linux kernel mainline in version 5.6, released March 2020. This was the first VPN implementation ever accepted into the mainline kernel — a strong signal from the kernel security community about the quality of the code. On any modern Linux distribution running kernel 5.6 or later, WireGuard is simply there. No DKMS modules, no kernel header packages, no out-of-tree compilation. The wireguard-tools package — which provides wg and wg-quick — is at version 1.0.20250521 as of mid-2025.

The use cases have expanded well beyond remote access. Tailscale built its entire product on top of WireGuard primitives. Cilium uses WireGuard for pod-to-pod transparent encryption in Kubernetes. Flannel supports a WireGuard native backend. K3s bundles WireGuard for its built-in Flannel networking. Azure Kubernetes Service ships WireGuard-based container network security as a first-class feature. The protocol is load-bearing infrastructure across a significant fraction of the cloud-native stack today.

What WireGuard deliberately does not do is equally important to understand before committing to it: it has no key distribution mechanism, no dynamic routing, no user authentication system, no built-in NAT traversal for symmetric NAT scenarios, and no management plane. It is a tunnel primitive, not a complete VPN solution. If you need those things, you either build them around WireGuard or you use something else.

Cryptographic Foundation

The Noise Protocol Framework

WireGuard’s handshake is built on the Noise Protocol Framework, a system designed by Trevor Perrin for constructing secure channel protocols from well-defined patterns and cryptographic primitives. Noise defines a small vocabulary of handshake patterns with specific security properties, and WireGuard uses one specific instantiation:

Noise_IKpsk2_25519_ChaChaPoly_BLAKE2s

Breaking this name apart:

• Noise: the framework itself
• IK: the handshake pattern. “I” means the initiator transmits their static public key in the first message — immediately, not after a discovery round trip. “K” means the responder’s static public key is already known to the initiator before the handshake begins. This is what enables WireGuard’s one-RTT handshake: no certificate exchange, no “here is my identity, please authenticate it” back-and-forth.
• psk2: a pre-shared symmetric key is mixed in at the second message position. This provides an additional layer of symmetric encryption on top of the asymmetric key exchange, and is explicitly motivated by post-quantum threat modeling — a future quantum computer that could break Curve25519 DH still cannot decrypt a session protected by a secret 256-bit pre-shared key.
• 25519: Curve25519 is used for all Diffie-Hellman operations
• ChaChaPoly: ChaCha20-Poly1305 is the AEAD cipher
• BLAKE2s: the hash function and HMAC construction

Curve25519

Every WireGuard identity is a Curve25519 keypair. The private key is 32 bytes (256 bits) of random data with a few bits clamped per the Curve25519 specification. The public key is derived by scalar multiplication of the private key against the Curve25519 base point. The DH operation — computing a shared secret from your private key and another party’s public key — is exceptionally fast. On modern x86 CPUs you can perform tens of thousands of DH operations per second. The 32-byte key size means key management is trivially simple: a WireGuard public key is a base64-encoded 44-character string you can copy-paste or store in a text file.

Curve25519 does not provide authentication on its own. Knowing someone’s public key tells you only that whoever holds the corresponding private key can participate in the exchange. Authentication in WireGuard comes from the fact that peers are explicitly configured with expected public keys. If a packet decrypts and its MAC verifies against a specific public key, you have cryptographic proof of who sent it — assuming the private key has not been compromised.

ChaCha20-Poly1305

ChaCha20-Poly1305 is the only AEAD cipher WireGuard uses. There is no negotiation, no cipher suite list, no option to downgrade to a weaker cipher. ChaCha20 is a 256-bit stream cipher designed by Daniel Bernstein. Poly1305 is a one-time MAC. Together they provide authenticated encryption with associated data — you cannot decrypt a packet without also verifying its integrity, and you cannot forge a valid packet without knowing the symmetric key.

ChaCha20 was designed specifically to be fast on CPUs lacking AES hardware acceleration: embedded systems, older ARM cores, microcontrollers. On modern x86 processors with AES-NI, AES-GCM can be faster in raw throughput, which is one reason IPsec with AES-GCM can match or beat WireGuard on server hardware. But ChaCha20-Poly1305 is competitive on AES-NI CPUs and substantially faster on mobile and embedded hardware, which is why WireGuard’s battery story on phones is compelling.

The lack of cipher agility is a principled design choice. Every cipher-negotiation protocol creates a downgrade attack surface — an attacker who can interfere with the handshake might steer both sides toward a weaker cipher. WireGuard’s position is that ChaCha20-Poly1305 is strong enough that there is no legitimate reason to use anything weaker, and the cost of cryptographic agility — code complexity, testing surface, downgrade vectors — is not worth paying.

BLAKE2s

BLAKE2s is used as the hash function for key derivation (HKDF-style constructions inside the Noise state machine) and for computing MACs over handshake messages. BLAKE2s is faster than SHA-256 in software and has a clean security analysis. It has received significant cryptanalytic attention since publication and the design margins are comfortable.

The Handshake

Initiator                                      Responder
    |                                               |
    |-- msg1: e, es, s, ss, TAI64N timestamp ------>|
    |         (encrypted to responder's static key) |
    |                                               | validates timestamp,
    |                                               | checks public key in
    |                                               | peer table
    |<-- msg2: e, ee, se, psk2 --------------------|
    |                                               |
    |============= encrypted data packets =========>|
    |<============ encrypted data packets ==========|

The initiator generates an ephemeral keypair, performs Diffie-Hellman operations with the responder’s known static public key, constructs the first handshake message, and includes a TAI64N timestamp. The timestamp is critical: the responder stores the most recent valid timestamp received from each initiator and rejects any handshake message with an older or equal value. This prevents replay attacks — an attacker who captures handshake message 1 cannot replay it hours later to impersonate the initiator.

The responder generates its own ephemeral key, completes the DH key derivation chain, mixes in the PSK if configured, and sends the second message. After those two messages — one round trip — both sides have independently derived identical session keys using the chained derivation defined by the Noise framework. No third message, no session token, no session ID exchange.

Session Key Lifecycle

WireGuard’s key management is governed by constants from the protocol specification:

• REKEY_AFTER_TIME = 120 seconds: If the session is active and the current session key is older than 120 seconds, the initiating side triggers a new handshake.
• REJECT_AFTER_TIME = 180 seconds: Any session key older than 180 seconds is hard-expired. Packets using it are dropped unconditionally.
• REKEY_AFTER_MESSAGES = 2^60 packets: A rekey is also triggered after this many packets, regardless of elapsed time.

The practical effect is that session keys rotate roughly every two minutes under active traffic, providing continuous forward secrecy. After a key rotation, ciphertext captured from the previous session cannot be decrypted with the new key. All ephemeral private keys and session keys are zeroed from memory after they expire.

Key Generation and the Cryptokey Routing Model

Generating Keys

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Generate a private key and derive the public key in one pipeline
wg genkey | tee /etc/wireguard/private.key | wg pubkey > /etc/wireguard/public.key

# Secure the private key file immediately
chmod 600 /etc/wireguard/private.key

# Generate a pre-shared key (optional, recommended for post-quantum margin)
wg genpsk > /etc/wireguard/preshared.key
chmod 600 /etc/wireguard/preshared.key

# View the keys
cat /etc/wireguard/private.key   # keep secret, never share
cat /etc/wireguard/public.key    # share freely with peers

The private key file contains a single base64-encoded 32-byte value. The public key file contains its derived counterpart. These are the only credential materials WireGuard uses. There are no certificates, no CA chains, no CRLs, no renewal deadlines. Revoking a peer means removing their [Peer] block from the server config and running wg set wg0 peer PUBKEY remove or reloading the interface.

The Cryptokey Routing Table

WireGuard’s routing model is called “cryptokey routing” and it is one of the most elegant aspects of the design. Every WireGuard interface maintains an internal table that maps:

PublicKey  ->  AllowedIPs (set of CIDR prefixes)

This table simultaneously performs two jobs:

Inbound (decryption and acceptance): When an encrypted UDP packet arrives on the WireGuard listen port, WireGuard identifies the session key to use via a session index in the packet header, decrypts the inner packet, and inspects its source IP. It then checks whether that source IP falls within the AllowedIPs of the peer whose key was used. If the source IP is not in the permitted range for that peer, the packet is silently dropped. A peer can inject only traffic with source addresses they are explicitly authorized to use.

Outbound (encryption and routing): When the kernel wants to send a packet out the wg0 interface, WireGuard looks up the destination IP in the cryptokey routing table, finds the peer whose AllowedIPs most specifically matches that destination via longest-prefix matching, and encrypts the packet to that peer’s public key before sending the UDP datagram.

This design enforces a tight coupling between cryptographic identity and network address. There is no separate firewall rule needed to prevent a peer from injecting traffic as if it originated from another peer — the routing table and the access control list are the same object.

The 0.0.0.0/0 entry is the full-tunnel flag. If a peer has AllowedIPs = 0.0.0.0/0, all outbound traffic that matches no more-specific route is encrypted to that peer. Combined with a NAT masquerade rule on the server, this routes all of the client’s internet traffic through the VPN.

Manual wg-quick Configuration

Configuration File Structure

WireGuard configuration lives in /etc/wireguard/wg0.conf (or any INI-style file under /etc/wireguard/; the interface name derives from the filename). The format has two section types: [Interface] describes the local peer, and [Peer] describes each remote peer.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

[Interface]
# The private key of THIS machine's WireGuard interface
PrivateKey = <base64-encoded-private-key>

# The IP address of this interface on the tunnel network (with prefix length)
Address = 10.0.0.1/24

# UDP port to listen on (server-side; omit on pure clients that only initiate)
ListenPort = 51820

# DNS server pushed to the system resolver when the interface comes up
DNS = 10.0.0.1

# Shell commands run after the interface is created
PostUp = iptables -A FORWARD -i %i -j ACCEPT; \
         iptables -A FORWARD -o %i -j ACCEPT; \
         iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

# Shell commands run before the interface is destroyed
PreDown = iptables -D FORWARD -i %i -j ACCEPT; \
          iptables -D FORWARD -o %i -j ACCEPT; \
          iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
# The public key of the remote peer
PublicKey = <base64-encoded-peer-public-key>

# What traffic to encrypt to this peer (outbound) and accept from it (inbound)
AllowedIPs = 10.0.0.2/32

# Where to send encrypted packets (public IP:port of the remote peer)
Endpoint = 203.0.113.50:51820

# Send a keepalive packet every 25 seconds to maintain NAT state
PersistentKeepalive = 25

# Optional: pre-shared key for additional symmetric protection layer
PresharedKey = <base64-encoded-psk>

Several distinctions that trip up new users regularly:

Address on [Interface] is the IP address of this WireGuard interface on the tunnel network. wg-quick uses the prefix length to add a kernel route for the tunnel subnet — a server at 10.0.0.1/24 gets the route 10.0.0.0/24 dev wg0 added automatically.

AllowedIPs on a [Peer] block is the cryptokey routing table entry for that peer. It has nothing to do with the peer’s own Address field — it declares what traffic should be encrypted to that peer (outbound) and what source IPs that peer is permitted to use on packets it injects (inbound).

Endpoint is required only if this machine needs to initiate the connection. A server on a static public IP does not set Endpoint for its clients — the clients connect to the server, and the server learns each client’s real UDP source address from incoming handshakes. If both sides are behind NAT, one must have a known, reachable Endpoint.

Managing the Interface

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Start the interface (reads /etc/wireguard/wg0.conf)
wg-quick up wg0

# Stop the interface (runs PreDown hooks, removes interface)
wg-quick down wg0

# Enable at boot via systemd
systemctl enable wg-quick@wg0
systemctl start wg-quick@wg0

# Check service status
systemctl status wg-quick@wg0

# Reload config without full restart (add/change peers without dropping sessions)
wg syncconf wg0 <(wg-quick strip wg0)

wg-quick is a shell script wrapper around wg, ip, and optionally resolvconf or systemd-resolved. Its sequence: create the network interface, call wg setconf to load the cryptographic configuration, assign addresses, bring the link up, add routes based on AllowedIPs, and run PostUp hooks. The lower-level wg tool handles only the WireGuard-specific parameters and leaves interface and routing management to you.

IP Forwarding

If the WireGuard host routes traffic for clients — as a VPN server or site-to-site gateway — IP forwarding must be enabled at the kernel level:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Temporary (reset at reboot)
sysctl -w net.ipv4.ip_forward=1
sysctl -w net.ipv6.conf.all.forwarding=1

# Permanent
cat > /etc/sysctl.d/99-wireguard.conf <<'EOF'
net.ipv4.ip_forward=1
net.ipv6.conf.all.forwarding=1
EOF
sysctl -p /etc/sysctl.d/99-wireguard.conf

Forgetting ip_forward is the most common cause of “tunnel connects but traffic does not flow” reports. The WireGuard handshake will complete successfully and wg show will display a recent handshake timestamp, but the kernel silently drops forwarded packets.

Full Tunnel vs Split Tunnel

The choice between full tunnel and split tunnel controls where packets go, and it is driven entirely by what you put in AllowedIPs.

Full Tunnel

1
2

[Peer]
AllowedIPs = 0.0.0.0/0, ::/0

Including 0.0.0.0/0 routes all IPv4 traffic through the WireGuard peer. Including ::/0 covers IPv6. You must include both or IPv6 traffic leaks around the tunnel in plaintext. With full tunnel, the WireGuard server must masquerade the clients’ traffic as it exits to the internet.

Client (10.0.0.2)                    WireGuard Server                  Internet
       |                             (10.0.0.1 / 198.51.100.10)            |
       |                                        |                           |
All traffic ---encrypted over UDP 51820-----> NAT masquerade ----------> destination
                                            appears as
                                          198.51.100.10

The masquerade rule in PostUp:

1

iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

Replace eth0 with the actual external interface name — ens3, enp3s0, whatever ip link shows on your system. Getting this interface name wrong is one of the most common full-tunnel failures: the tunnel connects, the handshake succeeds, but internet traffic dies because masquerade is applied to the wrong interface.

Full tunnel is appropriate for untrusted networks (hotel, conference, coffee shop), for preventing DNS interception, or when you want your internet traffic to appear to originate from the server’s IP address.

Split Tunnel

1
2

[Peer]
AllowedIPs = 10.0.0.0/8, 192.168.1.0/24

Only traffic destined for the listed subnets traverses the WireGuard tunnel. All other internet traffic goes directly from the client to the internet without touching the VPN server. This is the correct setup for homelab access where you want to reach your NAS, Proxmox host, and Pi-hole from anywhere, but you do not want your video streaming traffic routing through your home connection.

The DNS leak problem with split tunnel: If your VPN server runs a DNS resolver (Pi-hole, AdGuard Home, Unbound), DNS queries still go to your ISP’s resolver by default unless the DNS server IP falls within AllowedIPs. Either include the DNS server IP in the allowed routes, or set DNS = 10.0.0.1 in the client [Interface] block — wg-quick uses resolvconf or systemd-resolved to configure the resolver when the tunnel comes up.

Excluding specific IPs from a full tunnel: WireGuard’s AllowedIPs has no exclusion syntax. You cannot write 0.0.0.0/0 except 203.0.113.50/32. Instead, you enumerate all CIDRs that cover the desired range minus the exceptions — standard CIDR arithmetic. The official WireGuard documentation links to an AllowedIPs calculator for this; the calculation is straightforward but tedious by hand.

IPv6 in full tunnel: Always include ::/0 alongside 0.0.0.0/0. A client with native IPv6 connectivity will bypass the tunnel entirely for IPv6 destinations if ::/0 is absent, potentially exposing the client’s real IPv6 address and routing traffic outside the VPN.

Road Warrior Setup: Server and Multiple Clients

This is the most common WireGuard deployment: a server with a public IP, multiple roaming clients connecting from dynamic addresses.

Network Topology

                                Internet
                                   |
                +------------------+------------------+
                |                  |                  |
        Laptop (10.0.0.2)   Phone (10.0.0.3)   Work PC (10.0.0.4)
                |                  |                  |
                +------------------+------------------+
                                   |
                         +---------+---------+
                         |  WireGuard Server  |
                         |  Public IP:        |
                         |  198.51.100.10     |
                         |  Tunnel: 10.0.0.1  |
                         |  Port: 51820/UDP   |
                         +---------+---------+
                                   |
                         Home LAN (192.168.1.0/24)
                         NAS, Proxmox, Pi-hole, etc.

Server Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# /etc/wireguard/wg0.conf  (server)

[Interface]
PrivateKey = SERVER_PRIVATE_KEY_HERE
Address = 10.0.0.1/24
ListenPort = 51820

PostUp  = sysctl -w net.ipv4.ip_forward=1; \
          iptables -A FORWARD -i %i -j ACCEPT; \
          iptables -A FORWARD -o %i -j ACCEPT; \
          iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PreDown = iptables -D FORWARD -i %i -j ACCEPT; \
          iptables -D FORWARD -o %i -j ACCEPT; \
          iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

# --- Laptop ---
[Peer]
PublicKey = LAPTOP_PUBLIC_KEY_HERE
PresharedKey = LAPTOP_PSK_HERE
AllowedIPs = 10.0.0.2/32

# --- Phone ---
[Peer]
PublicKey = PHONE_PUBLIC_KEY_HERE
PresharedKey = PHONE_PSK_HERE
AllowedIPs = 10.0.0.3/32

# --- Work PC ---
[Peer]
PublicKey = WORKPC_PUBLIC_KEY_HERE
PresharedKey = WORKPC_PSK_HERE
AllowedIPs = 10.0.0.4/32

The server does not set Endpoint for clients — it learns their addresses from the UDP source of incoming handshakes. Each client’s AllowedIPs is a /32 because the server expects traffic only from that specific tunnel IP.

Client Configuration: Laptop (Full Tunnel)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# /etc/wireguard/wg0.conf  (laptop, full tunnel)

[Interface]
PrivateKey = LAPTOP_PRIVATE_KEY_HERE
Address = 10.0.0.2/32
DNS = 10.0.0.1

[Peer]
PublicKey = SERVER_PUBLIC_KEY_HERE
PresharedKey = LAPTOP_PSK_HERE
Endpoint = 198.51.100.10:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

Client Configuration: Phone (Split Tunnel for Homelab)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# WireGuard mobile client  (split tunnel, homelab access only)

[Interface]
PrivateKey = PHONE_PRIVATE_KEY_HERE
Address = 10.0.0.3/32
DNS = 10.0.0.1

[Peer]
PublicKey = SERVER_PUBLIC_KEY_HERE
PresharedKey = PHONE_PSK_HERE
Endpoint = 198.51.100.10:51820
AllowedIPs = 10.0.0.0/24, 192.168.1.0/24
PersistentKeepalive = 25

Adding a New Peer Without Downtime

On a running WireGuard interface, you can add a peer atomically without interrupting existing sessions:

1
2
3
4
5
6
7
8

# Add peer live (no restart needed)
wg set wg0 \
  peer NEW_CLIENT_PUBLIC_KEY \
  preshared-key /etc/wireguard/new-client.psk \
  allowed-ips 10.0.0.5/32

# Write current running config (including the new peer) back to disk
wg showconf wg0 > /etc/wireguard/wg0.conf

QR Codes for Mobile Import

The WireGuard iOS and Android apps can scan a QR code to import a full configuration:

1
2
3
4
5

# Print QR code to terminal for phone scanning
qrencode -t ansiutf8 < /etc/wireguard/phone-client.conf

# Save to PNG if the terminal rendering is unreadable
qrencode -t png -o phone-client.png < /etc/wireguard/phone-client.conf

Delete the QR image after scanning. The config contains the client’s private key in plaintext.

Site-to-Site VPN

Road warrior access is the simplest WireGuard topology. Site-to-site — connecting two entire networks so hosts on each side can reach hosts on the other — requires more careful attention to routing.

Network Topology

Home Network                              Cloud VPS / VPC
192.168.1.0/24                            10.2.0.0/24

+----------------------+                +----------------------+
|  Router / Gateway    |                |  VPS                 |
|  192.168.1.1         |                |  10.2.0.1            |
|  10.1.0.1 (wg0)      +---WireGuard----+  10.1.0.2 (wg0)      |
|                      |  10.1.0.0/30   |                      |
|  NAS: 192.168.1.5    |  tunnel subnet |  App:  10.2.0.10     |
|  PVE: 192.168.1.6    |                |  DB:   10.2.0.11     |
+----------------------+                +----------------------+

Home peer AllowedIPs for VPS:  10.1.0.2/32, 10.2.0.0/24
VPS  peer AllowedIPs for Home: 10.1.0.1/32, 192.168.1.0/24

Home Gateway Configuration (Initiator)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# /etc/wireguard/wg0.conf  (home router/gateway)

[Interface]
PrivateKey = HOME_PRIVATE_KEY_HERE
Address = 10.1.0.1/30
ListenPort = 51820
PostUp  = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT
PreDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT

[Peer]
PublicKey = VPS_PUBLIC_KEY_HERE
Endpoint = 203.0.113.100:51820
AllowedIPs = 10.1.0.2/32, 10.2.0.0/24
PersistentKeepalive = 25

VPS Configuration (Listener)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# /etc/wireguard/wg0.conf  (VPS)

[Interface]
PrivateKey = VPS_PRIVATE_KEY_HERE
Address = 10.1.0.2/30
ListenPort = 51820
PostUp  = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT
PreDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT

[Peer]
PublicKey = HOME_PUBLIC_KEY_HERE
# No Endpoint here — home side initiates, VPS learns source address from handshake
AllowedIPs = 10.1.0.1/32, 192.168.1.0/24
PersistentKeepalive = 25

Routing for Non-WireGuard Hosts

This is the step most guides omit. Your NAS at 192.168.1.5 has a default gateway of 192.168.1.1 — the home router. When it wants to reach 10.2.0.10 on the VPS, it sends the packet to that gateway. This works transparently if the home router is also the WireGuard gateway, as in the topology above.

If WireGuard runs on a dedicated Linux box at 192.168.1.2 rather than the primary router, you have two options. First, add a static route for 10.2.0.0/24 via 192.168.1.2 on every host that needs VPS access — workable for a few static machines, not for a DHCP network. Second, configure the primary router to add a static route for 10.2.0.0/24 via 192.168.1.2, which pushes the route to all hosts automatically. On the VPS side, cloud instances are typically the sole host in their subnet. In multi-host VPCs, application servers needing home LAN access require a route: ip route add 192.168.1.0/24 via 10.2.0.1.

Hub-and-Spoke Multi-Site

For three or more sites, a central hub simplifies the topology. Each spoke peer block on the hub contains only that spoke’s LAN in AllowedIPs. The hub’s kernel routes traffic between spokes because it holds routes for all of them. Spokes set AllowedIPs to include all other spoke subnets they need to reach, routing them via the hub.

               Hub (10.1.0.1)
              /       |       \
             /        |        \
     Site A        Site B        Site C
  (10.2.0.0/24) (10.3.0.0/24) (10.4.0.0/24)

The hub must allow inter-peer forwarding — traffic arriving on wg0 from one spoke destined for another spoke’s subnet:

1
2

# On the hub: allow wg0-to-wg0 forwarding (spoke-to-spoke traffic)
iptables -A FORWARD -i wg0 -o wg0 -j ACCEPT

Without this rule, the FORWARD chain drops packets arriving on wg0 that need to exit on wg0 to reach a different spoke, and the hub becomes a connectivity dead end.

wg show and Diagnostics

Annotated Output

# wg show

interface: wg0
  public key: xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
  private key: (hidden)
  listening port: 51820

peer: RGD3zPWbVVJKBvaCw6KrAdKL8tdQnVBsiSKJ/UvM8kU=
  preshared key: (hidden)
  endpoint: 203.0.113.50:42817       <-- client real IP:port learned from handshake
  allowed ips: 10.0.0.2/32
  latest handshake: 1 minute, 43 seconds ago    <-- session is live and healthy
  transfer: 48.32 MiB received, 183.16 MiB sent
  persistent keepalive: every 25 seconds

peer: YPjqNODYFTRFN9BVPYQ0Gh3CGg4R/ykqEJWRJxFD+gA=
  preshared key: (hidden)
  endpoint: (none)                    <-- peer has never connected to this server
  allowed ips: 10.0.0.3/32
  latest handshake: 2 days, 4 hours, 11 minutes ago    <-- session expired long ago
  transfer: 0 B received, 0 B sent

Key things to read from this output:

latest handshake age: Under active use, this should be under three minutes (the REJECT_AFTER_TIME boundary). If it is stuck at an old timestamp while you are actively sending traffic, the handshake is failing. Common causes: a firewall blocking UDP 51820, a wrong public key on either side, or an incorrect Endpoint address. If there is no latest handshake line at all, no handshake has ever succeeded for this peer.

Transfer counters: If the received counter increments but sent does not — or vice versa — you have a unidirectional problem. Common causes: ip_forward not enabled on the server, masquerade rule absent, or a routing problem where traffic enters the tunnel but responses take a different path.

Endpoint showing (none): The peer has not yet connected. WireGuard does not initiate connections to peers without a configured Endpoint — the peer must connect first. Once the first handshake arrives, the endpoint populates and persists.

Parseable Output for Scripting

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Tab-separated dump: interface, public-key, private-key, listen-port, fwmark
wg show wg0 dump

# All interfaces at once
wg show all dump

# Only latest handshake timestamps (good for monitoring freshness)
wg show wg0 latest-handshakes

# Only transfer counters (bytes RX/TX per peer)
wg show wg0 transfer

A practical shell one-liner to alert on stale sessions:

1
2
3

wg show wg0 latest-handshakes | awk -v now="$(date +%s)" \
  '{ age = now - $2
     if (age > 300) printf "STALE: peer %s, last handshake %d seconds ago\n", $1, age }'

Packet-Level Debugging

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Sniff the decrypted tunnel interface (inner packets are plaintext here)
tcpdump -i wg0 -n

# Sniff encrypted WireGuard UDP datagrams on the physical interface
tcpdump -i eth0 -n udp port 51820

# Force traffic out the WireGuard interface specifically
ping -I wg0 10.0.0.1

# Trace the path through the tunnel
traceroute -i wg0 10.0.0.1

# Verify DNS resolves via the tunnel's resolver
dig @10.0.0.1 example.com

The distinction between sniffing wg0 versus eth0 port 51820 matters. On wg0 you see decrypted inner packets — ICMP, TCP, DNS — which tells you whether routing works inside the tunnel. On eth0 port 51820 you see only encrypted UDP datagrams, which tells you whether WireGuard is sending and receiving at the wire level at all.

Common Failure Modes and Fixes

Performance Benchmarks vs OpenVPN and IPsec

Benchmarks in this space carry significant variance depending on hardware, kernel version, CPU capabilities (especially AES-NI), MTU settings, and whether the test is throughput-dominated or latency-sensitive. The numbers below reflect representative ranges from published 2024-2025 benchmarks across commodity hardware and server-grade x86.

Comparison Table

*IPsec with AES-GCM assumes AES-NI hardware acceleration. Without it, throughput drops substantially. **Tailscale latency depends heavily on whether a direct WireGuard path is available or traffic routes through a DERP relay server.

Reading the Numbers

WireGuard vs OpenVPN is not a close competition on any metric except raw feature count. WireGuard runs in the kernel; OpenVPN runs in userspace and crosses the kernel boundary on every packet. WireGuard’s handshake is one round trip; OpenVPN’s TLS setup involves multiple messages and certificate verification. OpenVPN’s TLS state machine is fundamentally single-threaded — on a 32-core server you still get one core’s worth of crypto throughput. In virtualized cloud environments, recent benchmarks show WireGuard achieving roughly 2x OpenVPN TCP throughput with a third the CPU load. On bare metal with AES-NI the gap widens further. The practical throughput difference is 10-20x on server hardware.

WireGuard vs IPsec is more nuanced and hardware-dependent. A well-configured IPsec deployment running esp=aes256gcm128-sha256-x25519 with kernel-level crypto offload and AES-NI can match or exceed WireGuard’s throughput ceiling because AES-GCM with hardware acceleration is extremely fast — faster per byte than ChaCha20-Poly1305 on AES-NI processors. The trade-off is configuration complexity and the risk of misconfiguration. IPsec has many knobs, and a mistaken proposal or transform set can produce a tunnel that works but silently negotiated weak parameters. WireGuard constrains you to one cipher suite that cannot be misconfigured into weakness.

Latency is where WireGuard’s design pays the most visible dividend in day-to-day use. A WireGuard session that has expired resumes in under a millisecond on the next outgoing packet — one round trip and data flows. An OpenVPN connection resuming from scratch initiates a full TLS handshake. On a mobile device moving between WiFi and cellular, WireGuard reconnects imperceptibly. OpenVPN produces a noticeable multi-second delay.

Battery life on mobile reflects two factors: CPU overhead and the absence of TCP-over-UDP pathology. WireGuard’s ChaCha20-Poly1305 is efficient on mobile ARM cores. There is no TCP state machine layered over UDP, no retransmission overhead, no head-of-line blocking. OpenVPN on TCP 443 — sometimes required to traverse restrictive firewalls — is significantly more CPU-intensive and consumes noticeably more battery over an 8-hour work day.

Limitations and When to Use Something Else

WireGuard’s simplicity is real, but it is achieved by deliberately not solving certain problems. Understanding these limitations determines whether WireGuard is the right tool for a given deployment.

No key distribution or management plane. Adding or removing a peer requires editing the configuration file on every affected host and reloading the interface. A hundred-node mesh requires updating a hundred config files. WireGuard provides no mechanism for centralized peer management. Tools like Netmaker, Headscale, defguard, and WireGuard Portal add management layers on top, but they are third-party additions — the core protocol has no management API.

No dynamic routing protocol support. WireGuard does not speak OSPF, BGP, or IS-IS. You can run BIRD or FRR over a WireGuard tunnel, but WireGuard provides no routing protocol integration at all. In complex multi-site topologies where routes change dynamically based on link state, you need either a static route management layer or a different VPN technology.

No built-in NAT traversal for symmetric NAT. WireGuard peers with static endpoints or typical port-restricted NAT — the majority of consumer routers — work fine. Symmetric NAT, where the external port changes per destination, breaks direct connectivity because neither side can predict the other’s external port. Tailscale solves this with DERP relay servers. If a significant fraction of your users sit behind corporate symmetric NAT, WireGuard alone will not reliably establish direct tunnels for all of them.

No user authentication. WireGuard authenticates cryptographic identities (key pairs), not people. There is no username/password, no TOTP challenge, no LDAP or Active Directory integration, no SAML. A device with a valid WireGuard private key has unconditional VPN access until that key is manually revoked from every peer’s configuration. In environments with compliance requirements for user-level MFA, WireGuard requires a wrapper — Headscale with OIDC, a separate authentication gateway, or similar.

Kernel version floor. The in-kernel implementation requires Linux 5.6. Current long-term-support kernels on all major distributions are well above this. Organizations running RHEL 7, CentOS 7, Debian Stretch, or other older enterprise distributions need wireguard-dkms or the wireguard-go userspace implementation. The userspace version works but is meaningfully slower and loses the kernel-integration performance benefits.

Identity is bound to the key, not the person. In a team, each member has a private key. If they have three devices, they typically have three keys — or one shared key, which is a security problem. If someone leaves, you remove their keys, but only if you tracked which keys belong to which person. WireGuard has no concept of a user identity that spans multiple devices.

Decision Guidance

Closing Thoughts

WireGuard is not the right tool for every situation, but it occupies an unusually large portion of the VPN problem space with unusual elegance. The protocol paper is readable in an afternoon. The kernel implementation can be audited in a day. The configuration is close to the theoretical minimum necessary to express a secure tunnel.

The practical workflow for almost any deployment is the same: generate a keypair per host, write a configuration file with [Peer] blocks, set AllowedIPs carefully (this is where all the logic lives), enable ip_forward if routing for others, add masquerade rules for full-tunnel setups, and use wg show when something does not work. There are no certificates to rotate, no cipher suites to choose, no TLS version flags to set.

Where WireGuard falls short — NAT traversal, key management at scale, user authentication — the ecosystem has responded. Tailscale and Headscale sit on top of WireGuard primitives. Cilium’s transparent pod encryption uses it. The Kubernetes and cloud-native communities have adopted it broadly. The protocol is sound, and the building-block design is proving to be the right abstraction level.

After running WireGuard tunnels across a homelab, several production VPSes, and two site-to-site links over multiple years, the number of times the interface needed a restart for reasons other than a deliberate configuration change is approximately zero. When something does go wrong, wg show almost always tells you exactly what the problem is in three lines of output. That kind of operational transparency is not accidental — it is the direct product of the same design discipline that produced 4,000 lines of kernel code instead of 70,000.