wireguard

Identity

• Kernel module: wireguard (built into kernel 5.6+; backported to 5.4 via DKMS)
• Config: /etc/wireguard/wg0.conf (interface name matches filename: wg0)
• Manage via: wg-quick up wg0 / wg-quick down wg0 / wg (status and stats)
• Unit: wg-quick@wg0.service (systemd unit for persistent operation)
• Install: apt install wireguard / dnf install wireguard-tools (kernel module usually pre-included on modern distros)

Key Generation

# Generate server keys
wg genkey | tee server_private.key | wg pubkey > server_public.key

# Generate client keys
wg genkey | tee client_private.key | wg pubkey > client_public.key

# Optional: pre-shared key (adds post-quantum resistance layer)
wg genpsk > preshared.key

chmod 600 server_private.key client_private.key preshared.key

Private keys never leave the host they were generated on. Public keys are shared freely. Pre-shared keys (PSKs) are symmetric secrets shared between exactly two peers — one PSK per peer pair, stored in both configs.

Key Operations

Goal	Command
Bring interface up	sudo wg-quick up wg0
Bring interface down	sudo wg-quick down wg0
Enable on boot	sudo systemctl enable wg-quick@wg0
Start now + on boot	sudo systemctl enable --now wg-quick@wg0
Show all interface status	sudo wg show
Show specific interface	sudo wg show wg0
Show current running config	sudo wg showconf wg0
Check handshake timestamps	sudo wg show wg0 latest-handshakes
Show transfer stats	sudo wg show wg0 transfer
Add peer at runtime	sudo wg set wg0 peer <pubkey> allowed-ips 10.0.0.3/32
Save runtime changes to file	sudo wg-quick save wg0
Reload config without down/up	sudo wg syncconf wg0 <(wg-quick strip wg0)

Expected Ports

• 51820/udp — default; set via ListenPort in [Interface]
• WireGuard is UDP-only. TCP is not supported.
• Verify listening: ss -ulnp | grep wireguard
• Allow through firewall: ufw allow 51820/udp or firewall-cmd --add-port=51820/udp --permanent

Health Checks

1. sudo wg show — lists all interfaces and peers; confirms the interface is up
2. sudo wg show wg0 latest-handshakes — epoch timestamps; any value > 0 means the peer has connected; values more than ~3 minutes in the past mean the connection is idle or broken
3. Ping across the tunnel (e.g., ping 10.0.0.2 from the server to the first client's tunnel IP)
4. journalctl -u wg-quick@wg0 -n 50 — startup errors, PostUp script failures
5. sudo wg show wg0 transfer — bytes sent/received; zero RX means no traffic is returning

Common Failures

Symptom	Likely cause	Fix
wg show shows peer but no handshake	Firewall blocking UDP 51820 on server, or wrong public key pasted	Open UDP port on server; verify keys match exactly
Handshake occurs but no traffic flows	ip_forward disabled on server; PostUp NAT rule missing	sysctl -w net.ipv4.ip_forward=1; verify PostUp iptables rule
Handshake times out repeatedly	Client endpoint wrong (wrong IP or port)	Confirm server's public IP and ListenPort; check Endpoint line
DNS leaks outside the tunnel	DNS server not set in client [Interface], or DNS not reachable via tunnel	Set DNS = <server-tunnel-ip> in client config; run DNS server on server
Mobile client drops after idle	NAT table on router expires UDP mapping	Add PersistentKeepalive = 25 to client's [Peer] (server entry)
Split tunnel routes wrong traffic	AllowedIPs too broad or overlapping between peers	AllowedIPs is a routing table — each IP range can appear in only one peer
wg-quick: Permission denied on startup	wg0.conf permissions are not 600	chmod 600 /etc/wireguard/wg0.conf
RTNETLINK answers: Operation not supported	WireGuard kernel module not loaded	modprobe wireguard; on older kernels install wireguard-dkms

Pain Points

• AllowedIPs is a routing table: Each peer's AllowedIPs determines which destination IPs get routed through that peer's tunnel. 0.0.0.0/0, ::/0 = all traffic (full VPN). Specific subnets = split tunnel. Common mistake: overlapping AllowedIPs between two peers — WireGuard will accept the config but routing becomes undefined.

• No auto-discovery: Every peer must be explicitly added to every other peer's config. There is no central auth server or certificate authority. Adding a new client means editing the server config and reloading it.

• UDP only: WireGuard strictly uses UDP. If a network blocks all UDP (restrictive hotel/corporate firewall), WireGuard will not work. Unlike OpenVPN, there is no TCP fallback.

• Handshake timeout = dead connection: wg show shows latest handshake as a Unix timestamp. If it is more than 3 minutes ago, the tunnel is likely broken. PersistentKeepalive = 25 sends a keepalive every 25 seconds to maintain NAT mappings and detect dead connections faster.

• ip_forward required on server: For the server to route traffic between peers (or to the internet), net.ipv4.ip_forward = 1 must be active. Set persistently in /etc/sysctl.d/99-wireguard.conf with net.ipv4.ip_forward = 1; activate with sysctl -p.

• File permissions: /etc/wireguard/wg0.conf must be mode 600 (owner-read-only). wg-quick warns and may refuse to start if permissions are too open. The file contains the private key in plaintext.

• Runtime changes vs. file changes: wg set modifies the running interface immediately but does not persist to wg0.conf. Use wg-quick save wg0 to write runtime state back to the file, or use wg syncconf wg0 <(wg-quick strip wg0) to apply file changes without taking the interface down.

References

See references/ for:

• wg0.conf.annotated — fully annotated server and client config examples
• setup-patterns.md — step-by-step guides for common deployment scenarios
• docs.md — official documentation and community resources