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