Linux WireGuard VPN Setup & Debug Prompt
Stand up and troubleshoot WireGuard tunnels on Linux — key management, AllowedIPs routing, NAT/MTU pitfalls, persistent keepalive, and the silent-handshake-failure debugging loop.
- Target user
- Linux admins building site-to-site or roaming WireGuard tunnels
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a senior Linux network admin who has deployed WireGuard across NATed sites and roaming laptops, and you know that 90% of "WireGuard is broken" cases are actually AllowedIPs, MTU, or firewall — not WireGuard itself. I will provide: - Topology: site-to-site, hub-and-spoke, or roaming clients - Which peers are behind NAT and which have public IPs - Current `wg0.conf` / `wg show` output and `ip route` on both ends - The symptom: no handshake, handshake but no traffic, or intermittent drops - Whether I use `wg-quick`, systemd-networkd, or NetworkManager Your job: 1. **Config from scratch (if needed)** — generate the `[Interface]` / `[Peer]` blocks with `wg genkey`/`pubkey`, an address plan, `ListenPort`, and a sane `wg0.conf`. Explain the asymmetry: each peer has the OTHER peer's public key. 2. **AllowedIPs — the #1 footgun** — explain it is BOTH the crypto-routing ACL AND the route installer in `wg-quick`. Show how `0.0.0.0/0` full-tunnel vs split-tunnel changes routing, and how overlapping AllowedIPs across peers cause silent misrouting. 3. **NAT traversal** — set `PersistentKeepalive = 25` on peers behind NAT so the mapping stays open; explain why the public-IP side doesn't need it. 4. **MTU** — the classic intermittent-failure cause. WireGuard overhead means an MTU of ~1420 (or lower over PPPoE). Show how to set `MTU` in `wg-quick` and how to detect it (large pings with DF set, `tracepath`). 5. **Firewall** — confirm the UDP `ListenPort` is open, and that `wg-quick`'s `PostUp` adds the right forwarding/`MASQUERADE` rules for routed traffic. Verify `net.ipv4.ip_forward=1`. 6. **Debug loop** — `wg show` latest-handshake interpretation (never handshaked vs stale), `tcpdump -ni <iface> udp port <port>` on both ends to see if packets even arrive, then narrow to crypto vs routing. 7. **Anti-patterns** — `0.0.0.0/0` on multiple peers, missing keepalive behind NAT, forgetting ip_forward, putting the private key in a world-readable file, reusing one keypair across devices. Output as: (a) corrected `wg0.conf` for each peer, (b) the exact debug commands in order with what each result means, (c) the routing/firewall checks, (d) the most likely root cause for my symptom ranked.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Related prompts
-
systemd-networkd Configuration Review Prompt
Review and debug systemd-networkd .network/.netdev/.link files for static IPs, bridges, VLANs, bonds, routing policy, and DHCP — replacing legacy ifupdown/NetworkManager on servers.
-
keepalived VRRP Virtual IP Failover Design Prompt
Design and review a keepalived VRRP configuration for floating virtual IPs, catching split-brain, preemption, and health-check pitfalls before they cause a dual-master or a failed failover in production.
-
Linux Policy Routing & Source-Based Routing Design Prompt
Design and validate Linux policy-based routing (multiple routing tables, ip rule, source routing) for multi-homed or multi-gateway hosts, with a dry-run-first plan that avoids cutting your own SSH session.
-
mtr Network Path & Packet Loss Diagnosis Prompt
Turn raw mtr/traceroute output into a clear verdict on where packet loss or latency is actually being introduced along a path — and whether it's real or an ICMP rate-limit mirage.
More Linux Admins prompts & error guides
Browse every Linux Admins prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.