high riskservice affecting~45 min

Runbook: Troubleshoot WireGuard

1 · Prerequisites

Confirm every item is in place before any state change.

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

· The report is converted into a symptom before a command is run. "The tunnel is down" is what was said. "No handshake has ever happened", "the handshake is recent and nothing crosses", "traffic crosses and large transfers stall" and "it works, idles, and stops" are four different faults with four different owners.
· You have, or can get, show interfaces wireguard wg0 summary from BOTH routers. This is the single most important pre-check in the runbook: the router carrying the misconfiguration is usually the one that looks healthy, and the symptoms of a wrong key, a blocked port and a far-end allowed-ips gap are identical from one side.
· Whether this tunnel EVER worked is established, and if it did, when it stopped. A tunnel that has never come up is a two-ended agreement problem — keys, port, addresses. A tunnel that stopped is a change, an expiry, or a path, and the parameters are probably innocent.
· Out-of-band access to this router is confirmed by using it, BEFORE any remediation. If your session reaches this router across the tunnel, or across a prefix that appears in a peer allowed-ips, the thing you are about to change is your access path.
· Nobody has regenerated a key pair, deleted the peer, or bounced the interface "to see if that helps". If someone has, record it: a key regenerated on one side turns a diagnosable fault into a broken tunnel that now needs a coordinated two-ended change.
· The far end has an owner who is reachable now. Roughly half the evidence and a large share of the causes live on the other router, and there is no way to see either from here.
· The intended design is to hand for both ends: interface name and listen port, each router public key, the peer names, the full allowed-ips list on each side, the tunnel addresses, the static routes, and whether a preshared key is in use. Without the two allowed-ips lists written down you cannot tell a mismatch from a design.
· The change record for the last 72 hours covers both routers AND the path between them: firewall rules, WAN addressing, a failover onto a backup circuit, upstream provider work. A WAN failover onto a smaller-MTU circuit breaks large transfers on a tunnel whose configuration nobody touched.
· Anything you paste into a ticket or a chat has been through strip-private. The interface private key is a configuration value on 1.5, so a raw configuration dump is a disclosed secret and turns a tunnel fault into a key-rotation incident.

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1Capture the peer state on BOTH routers before changing anything: show interfaces wireguard wg0 summary. On 1.5 that subcommand runs sudo wg show wg0 and prints wg output verbatim, identifying peers by base64 public key rather than by the name you gave them.
2Read the peer block for what is NOT there. latest handshake is printed only once a handshake has happened, and transfer only once a byte has moved. A peer that has never come up prints its key, its endpoint and its allowed ips and then simply stops. There is no "never" string to grep for, so compare the block against a healthy peer rather than scanning for something alarming.
3Place the fault in one of three worlds. WORLD A: neither router prints a latest handshake line. WORLD B: the handshake is recent and the transfer counters are flat or one-sided. WORLD C: both counters advance and the application still fails. The three share no further diagnostic steps.
4WORLD A — split path from parameters with a capture pair, cheapest first: sudo tcpdump -ni eth0 "udp port 51820" -c 10 on the sending router and on the receiving one. Leaving and arriving with no reply is a key or preshared-key problem at the far end. Leaving and never arriving is the underlay: a firewall, a NAT, or a wrong peer address.
5WORLD A — check the underlay firewall on the RECEIVING side with show firewall ipv4 input filter. The encrypted UDP terminates on the router, so its rule belongs in the input chain; a listener rule written into forward filter never matches and its counter stays at zero while the input default-drop counter climbs at the handshake retry rate.
6WORLD A — compare the keys ACROSS the two routers, never within one. show interfaces wireguard wg0 public-key here must appear in show interfaces wireguard wg0 peers there, and the reverse. A public key that does not match produces no reply and no log line, exactly like a blocked port.
7WORLD A — confirm the preshared key is configured on both ends or on neither. A peer with none behaves as though it had one of all zeroes, so a half-applied preshared key derives different keys at each end and nothing ever completes.
8WORLD A — confirm at least one end has a peer address configured. Two ends that both wait to be contacted wait forever; the side that initiates is the side that knows where the other one is.
9WORLD B — read the counters in each direction, because they decide which router to investigate. Bytes out rising with bytes in flat puts the fault on the FAR router: its allowed-ips do not cover your source prefix, its forward rules drop the decrypted traffic, or it has no route back. Nothing moving in either direction means nothing is being sent into the tunnel at all.
10WORLD B — where nothing is moving, check the route before the crypto: show ip route for the destination prefix. allowed-ips is passed to wg set and installs no route on VyOS, so a tunnel with a correct peer and no static route looks healthy and carries nothing.
11WORLD B — capture the decrypted view on both ends: sudo tcpdump -ni wg0 -c 4. A packet visible on the sending router wg0 and absent on the receiving one was discarded between decryption and the interface, and there is exactly one thing that does that — the source address was not inside the allowed-ips of the peer it arrived from.
12WORLD B — check the firewall that governs the decrypted traffic on the far end: show firewall ipv4 forward filter, plus any named rule-set it jumps to. A named set whose counters are all zero, including its default action, is a set nothing jumps to.
13WORLD C — the tunnel carries traffic, so measure the MTU rather than theorising about it: ping DEST size 1392 do-not-fragment count 3 against ping DEST size 100 do-not-fragment count 3. Small succeeding while large fails is the encapsulation-overhead signature, and it is routinely reported as an application fault.
14WORLD C — bisect between a size that answers and one that does not, then set the interface MTU to the measured payload plus 28 and clamp beneath it with ip adjust-mss clamp-mss-to-pmtu. The MTU and the clamp are one change: a correct MTU with no clamp still black-holes TCP from the hosts behind the router, because those hosts never see the tunnel MTU.
15WORLD C — for a tunnel that works, idles and stops, check persistent-keepalive on the end behind NAT. The giveaway is the asymmetry: traffic initiated from the NAT side revives it immediately, traffic initiated from the public side does nothing. That is a path problem, not a crypto problem.
16Apply any configuration fix with commit-confirm 5 rather than a bare commit, one change at a time, then re-read the same show interfaces wireguard wg0 summary you captured in step 1 before running confirm and save.
17Write the diagnosis as a layer: underlay path, public key, preshared key, allowed-ips, route, firewall chain, MTU, or NAT binding. "Rebuilt the tunnel and it works now" is not a diagnosis and guarantees the same shift next quarter.

4 · Verification

Confirm the procedure actually fixed the problem.

✓show interfaces wireguard wg0 summary on BOTH routers prints a latest handshake line for the peer, and the age of that line is small and shrinking across two readings
✓The transfer line advances in BOTH directions across two readings a minute apart. One reading proves the peer exists; two readings prove it carries traffic, and a one-sided count is a far-end fault rather than a working tunnel
✓The public key printed by show interfaces wireguard wg0 public-key on each router appears in show interfaces wireguard wg0 peers on the other — checked across the pair, not within one router
✓show ip route on each router resolves the far-end prefix out of the tunnel interface, because allowed-ips installs no routes and the tunnel looks identical with or without them
✓show interfaces wireguard wg0 allowed-ips on each end covers the real source prefixes the other end uses, not only the tunnel subnet that was convenient to test with
✓The relevant firewall counters advance: the input-chain rule for the listen port on each router, and the forward-chain or named rule-set counters for the decrypted traffic
✓A do-not-fragment ping at the measured tunnel size crosses, not only a default-size ping. Small-packet success with large-packet failure is the defect this check exists to catch
✓One real application flow is tested host-to-host across the tunnel. Router-to-router proves the crypto; only host-to-host proves the routing, the firewall and the MSS clamp together
✓For a tunnel with an end behind NAT, it is still up after being deliberately left idle for longer than the binding it depends on — a tunnel verified immediately after traffic proves nothing about the failure being investigated
✓Any firewall rule widened during diagnosis has been narrowed again, any raised logging removed, and the running configuration saved on both routers

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶Diagnosis is read-only up to the first commit, so until then there is nothing to roll back. Everything below concerns undoing a fix or an emergency action.
↶A fix still inside its commit-confirm window that made things worse: do nothing and let the timer expire. This matters more here than usual, because the change you just made may have moved your own session into or out of the tunnel.
↶A committed and confirmed fix: delete the specific nodes you added, or load the pre-change configuration file and commit. Take the restore point with save /config/pre-change-wg-TICKET.conf from configuration mode before the first change, not after the second.
↶A route added to make the tunnel carry traffic is a routing change with its own blast radius. Confirm it did not overlap a prefix something else was using before you leave it in place.
↶Any firewall rule opened to test whether the firewall was the problem is temporary by definition. Narrow it to the peer address and the specific UDP port, or remove it, before the ticket closes — a WAN rule opened at 02:00 outlives everyone who remembers why.
↶A key pair regenerated during diagnosis cannot be rolled back by this router alone. The far end holds the old public key and will keep rejecting you until it is updated, so treat it as a coordinated two-ended change with a window rather than as an undo.
↶An allowed-ips entry added on one side only is half a change. Either complete the mirror on the far end or remove it; a one-sided list is the exact defect that produces no evidence on the router where the mistake was made.
↶If the interface was bounced or the peer deleted and recreated to restore service, that is a service restoration and not a diagnosis. Record that the evidence was lost and keep the ticket open until the cause is found or the next occurrence is instrumented.

6 · Escalation

When the runbook isn't enough, contact:

· Escalate to the far-end owner as soon as local evidence points outward, and send the evidence with it. A capture showing encrypted UDP leaving here and arriving there with no reply, or a transfer counter with bytes out and zero bytes in, is complete proof of a far-end condition — and further local reconfiguration only adds variables to a problem that is not yours.
· Ask the far-end owner for their show interfaces wireguard wg0 summary and their allowed-ips list specifically. Those two outputs settle the argument that comparing configurations by eye never does.
· Escalate to network engineering or the upstream provider when the capture shows outbound packets and nothing arriving, and the far end confirms they are listening. That is a path condition between two networks and neither router owner can fix it.
· Escalate to network engineering when a multi-WAN router sends the encrypted UDP out one uplink and the reply arrives on the other. Pinning the tunnel underlay path is a routing-policy change with its own review, not something to improvise during an incident.
· Escalate to the security owner immediately if a private key or a preshared key has been pasted into a ticket, a chat or an email during the investigation. Both are secrets that do not expire, and rotation is a coordinated two-ended change that has to be scheduled.
· Escalate to the platform team if this router stops answering on both the tunnel and the management path. Recover from the out-of-band session opened in the pre-checks rather than attempting further remediation across a path that may be the fault.
· Holding is a legitimate outcome. If the two ends have no agreed key and allowed-ips sheet and the tunnel has never worked, stop: trial-and-error across two change windows produces a tunnel nobody designed. Record the hold with an owner and an end time and hand the window back.

WireGuard is the easiest VPN on this platform to configure and the hardest to diagnose from one end, for the same reason: it says nothing.

There is no negotiation to watch fail. There is no proposal mismatch to read in a log. The kernel module does not log a rejected handshake, does not name the peer that sent it, and does not report an authentication failure — because answering an unauthenticated packet would tell an attacker that a key is valid. It never tears a session down either, so a tunnel that stopped working looks exactly like a tunnel that is simply idle.

An empty log is the expected state, not evidence of health. That leaves three sources of truth and nothing else: the handshake timestamp, the transfer counters in each direction, and a packet capture. Everything below is arranged around reaching those quickly and refusing substitutes.

When this runbook applies

A site-to-site WireGuard tunnel on VyOS 1.5 is reported down, or up and useless.
A tunnel that worked yesterday has stopped.
Traffic crosses the tunnel and something about it is wrong: one direction only, large transfers stalling, or a connection that dies after a quiet minute.

When it does not apply

The tunnel has never been built. Use the WireGuard configuration runbook. Diagnosing a tunnel that does not exist yet mostly produces a list of things you have not configured.
The complaint is throughput, not reachability. Encryption is CPU work and a single flow can be limited by one core. That is a router performance question, and MTU is not the first place to look when there are no stalls, just a ceiling.
The far end is not a peer you or a counterpart control. A managed service or a client device changes what half of this runbook can be acted on, though the reading of the evidence is the same.
The fault is a routing protocol running across the tunnel. If the handshake is healthy and counters advance, an adjacency that will not form is a routing problem that happens to be using a tunnel.

Blast radius, and the three things not to do first

The diagnosis itself is read-only. The remediation is not, and its blast radius has an unusual shape: a WireGuard peer’s allowed-ips is simultaneously the list of prefixes that get encrypted to that peer and the list of source addresses that peer is permitted to send from. Editing it is a routing change and an access-control change in the same commit.

Three actions feel like progress and are not:

Do not regenerate a key pair. It is the “start clean” instinct and it is the one action here that cannot be undone from this router. The far end holds your old public key; the moment you replace it, a diagnosable fault becomes a broken tunnel requiring a coordinated change at both ends.

Do not bounce the interface or delete the peer. The handshake age and the transfer counters are the entire evidence base, and both reset. On a peer that has never come up, a bounce also removes the only distinction you have — a peer block that has stopped printing latest handshake because it never had one looks the same as one that lost it.

Do not widen the firewall “just to check”. Widening it is a legitimate test, but only as a narrow, time-boxed rule you have already decided how to remove. A WAN rule opened during an incident and left behind is a permanent hole nobody remembers opening.

Step 1: read the peer state on both routers

Read-only / Safeon each router — this is the peer view

show interfaces wireguard wg0 summary
show interfaces wireguard wg0 peers
show interfaces wireguard wg0 endpoints
show interfaces wireguard wg0 allowed-ips
show interfaces wireguard wg0 public-key

The summary subcommand is the important one, and the distinction is worth being pedantic about. On 1.5 it runs sudo wg show wg0 and prints wg’s own output: the peer, its endpoint, its allowed ips, and — if they exist — a latest handshake line and a transfer line.

The bare form, show interfaces wireguard wg0 with nothing after it, is a different command. It runs the generic interface script and prints link state, addresses, MTU and aggregate counters. There is no peer, no handshake and no per-peer transfer in it. Reaching for the bare form and finding no handshake information is a common way to conclude, wrongly, that the peer is missing.

The evidence is an absence, and there is no string to grep for

wg show prints latest handshake only when the stored handshake timestamp is non-zero, and prints transfer only once a byte has moved in one direction or the other. A peer that has never completed a handshake prints its key, its endpoint and its allowed ips — and then the block simply ends.

There is no never. There is no DOWN. The two lines you are looking for are the two lines that are not there, and an operator scanning for something alarming will scan straight past it.

Make the comparison explicit: hold the peer block next to a healthy one and count the lines. Note also that the peer is identified by its base64 public key, not by the name you gave it in the configuration — this output is wg’s own and wg has never seen your peer names.

Step 2: the counters place the fault in one of three worlds

What both routers show	The fault is	Go to
No `latest handshake` line at either end	The handshake never happens: path, key, or address	World A
Handshake recent, transfer flat or one-sided	The tunnel is up and something drops the payload	World B
Both counters advancing, application still broken	Not the tunnel: MTU, routing beyond it, or a NAT binding	World C

Getting this right from one router is not possible, which is why step 1 insists on both. The symptoms of a wrong public key, a blocked UDP port and a far-end allowed-ips gap are indistinguishable from the near side, and an operator with access to only one router can reach a confident and entirely incorrect conclusion in under a minute.

World A — no handshake has ever happened

Six causes account for almost all of these, and one capture pair splits them into two groups before you check any of them.

Read-only / Saferun on the sending router and the receiving router at the same time

# Substitute your own values before running:
WAN_IF=eth0
WG_PORT=51820

sudo tcpdump -ni "$WAN_IF" "udp port $WG_PORT" -c 10

Packets leave here and arrive there, and nothing comes back. The far end received something it will not authenticate. That is a public key that does not match, or a preshared key configured on one side only. Nothing else produces this shape, because WireGuard replies to everything it can authenticate and to nothing it cannot.

Packets leave here and never arrive there. The underlay: a firewall on either end, a NAT in between, or a peer address that points somewhere that is not listening.

Packets never leave here at all. This router has no route to the far end’s outer address, or the peer has no address configured and this end is waiting to be contacted. If neither end has a peer address, both are waiting and neither will ever start.

Then check, in this order:

Read-only / Safethe underlay firewall, on the RECEIVING side

show firewall ipv4 input filter

The encrypted UDP terminates on the router, so its accept rule belongs in the input chain. A listener rule written into forward filter is one of the most common WireGuard firewall faults and it has a distinctive signature: the forward rule counter sits at zero while the input chain’s default-drop counter climbs at roughly the handshake retry rate. That is the fault naming itself, if anyone reads the counters.

Read-only / Safethe key check that needs both routers

show interfaces wireguard wg0 public-key
show interfaces wireguard wg0 peers

Run the first on one router and the second on the other, then swap. The key printed here must appear in the list there, and the reverse. Comparing keys within a single router proves nothing at all; this is a cross-router check and it is the reason the far-end owner is in the pre-checks.

World B — the handshake is fine and nothing crosses

The counters tell you which router to investigate, and that is the single most valuable piece of information available in this runbook.

Bytes out rising, bytes in flat. Your packets are being sent and the far end is not answering. The fault is on the far router: its allowed-ips do not cover your source prefix, its forward rules drop the decrypted traffic, or it has no route back. Stop reconfiguring this one.
Nothing moving in either direction. Nothing is being sent into the tunnel at all. Either the route to the destination does not point at the tunnel interface, or the destination is not inside any peer’s allowed-ips.
Both counters rising, application still broken. The tunnel carries traffic. That is World C.

The route check comes before the crypto check, because it is cheap and it is frequently the answer:

Read-only / Safedoes the destination route into the tunnel at all

show ip route 192.168.20.0/24
show interfaces wireguard wg0 allowed-ips

allowed-ips is passed straight to wg set and nothing more — the VyOS interface script installs no routes from it. The far-end prefix needs a static route out of the tunnel interface, and without one the packet never reaches the interface at all. The tunnel meanwhile reports a healthy handshake and carries nothing, which is a very convincing way to look fine. The tunnel’s own subnet is the exception: it is a connected route from the interface address and needs nothing added.

Why an allowed-ips gap is loud on one router and silent on the other

The two directions of an allowed-ips failure produce completely different symptoms, and knowing which one you are looking at saves an hour.

Locally, if a packet is routed to the tunnel interface and no peer claims its destination, the device has no key to encrypt it with. It cannot silently discard the packet without breaking the kernel’s contract, so it returns an ICMP destination unreachable to the sender. A local gap announces itself immediately.

Remotely, a decrypted packet whose source address is not inside the sending peer’s allowed-ips is simply discarded. No ICMP, no log, no counter that names it — answering would confirm to an attacker that the key was valid. A far-end gap produces silence.

Same misconfiguration, two symptoms, one loud and one silent, depending entirely on which router is carrying it. And the router carrying it is the one whose operator sees nothing wrong.

The decrypted capture is what proves it:

Read-only / Safeon both routers, on the tunnel interface

# Substitute your own values before running:
WG_IF=wg0

sudo tcpdump -ni "$WG_IF" -c 4

A packet visible on the sending router’s tunnel interface and absent on the receiving router’s was discarded between decryption and the interface. Exactly one thing does that, and it is the far end’s allowed-ips.

If the packet does appear on the far end’s tunnel interface and still goes nowhere, the firewall governing decrypted traffic is next:

Read-only / Safeon the far router

show firewall ipv4 forward filter

Read the counters, not the rules. A named rule-set whose counters are all zero — including its own default action — is a rule-set that nothing jumps to: the set exists, its rules are correct, and no rule in the forward chain selects traffic into it. A named set whose default-drop counter is advancing while later forward rules stay at zero is the opposite problem: the set is terminal and is swallowing traffic you expected to fall through. Both are configuration decisions rather than accidents, but only one of them is the one you made.

The other asymmetric case: traffic goes out and replies never return, with the far end’s named-set default-drop counter advancing at the same rate as your outbound flow. That is a missing or badly ordered state established and state related rule. Conntrack admits the reply only if a rule matches it.

World C — traffic crosses and the application still fails

Measure the MTU; do not reason about it

Read-only / Safethe small case and the large case, in that order

ping 192.168.20.10 size 100 do-not-fragment count 3
ping 192.168.20.10 size 1392 do-not-fragment count 3
ping 192.168.20.10 size 1400 do-not-fragment count 3

Run the small one first so that a failure on the large one means “too big” and not “no path”. The classic symptom set is a ping that works, an SSH session that connects and freezes on the first large output, and a web page that returns its headers and hangs — which is reported as an application fault and diagnosed as a network one.

The arithmetic: WireGuard adds 60 bytes to every packet over an IPv4 underlay — 20 of IP header, 8 of UDP, 16 of message header, 16 of authentication tag — and 80 bytes over IPv6, where the outer header is 40. The interface default MTU is 1420, which is 1500 minus 80: the value that fits a standard underlay even when the outer packet is IPv6. An ICMP payload of size N corresponds to an MTU of N plus 28.

So the default is already correct for a 1500-byte path, and MTU trouble comes from somewhere else:

The underlay is smaller than 1500. Left at 1420, the encrypted packets are too large for a constrained hop and are dropped or fragmented there.
TCP never learns the tunnel MTU. The hosts behind each router negotiate their MSS from their own local MTU. Their large segments reach the router, do not fit the tunnel, and the ICMP that would tell them so is filtered somewhere. That is a black hole, and it is the common case.

The MTU and the clamp are one change, not two

A tunnel with a correct MTU and no clamp still black-holes TCP from the hosts behind it, because those hosts never see the tunnel MTU. A clamp with a wrong MTU clamps to the wrong number.

clamp-mss-to-pmtu derives its value from the interface MTU, which is exactly why setting the MTU deliberately matters:

set interfaces wireguard wg0 mtu '1420'
set interfaces wireguard wg0 ip adjust-mss 'clamp-mss-to-pmtu'
set interfaces wireguard wg0 ipv6 adjust-mss 'clamp-mss-to-pmtu'

Note the spelling. tcp-mss was the 1.3 form and is not accepted on 1.5. Where the constraint is not this interface’s own MTU — an underlay that is itself a tunnel — use an explicit value from your measurement instead: the MTU minus 40 for IPv4 and minus 60 for IPv6, so 1380 and 1360 at an MTU of 1420.

An MTU fault that appears with no configuration change on either router is worth naming separately, because the instinct is to disbelieve it. The underlay path changed: a failover onto a backup circuit with a smaller MTU, or a tunnel inserted upstream. Small packets are unaffected, which is why monitoring that pings with 64 bytes reports everything as healthy throughout.

The tunnel that works, idles, and stops

The symptom is periodic and gets reported as intermittent. Traffic initiated from one side revives it immediately; traffic initiated from the other does nothing.

That asymmetry is the whole diagnosis. A consumer or carrier NAT device in front of one end drops its UDP binding after an idle period — commonly 30 to 120 seconds — so packets from the public side have nothing to traverse. WireGuard does not notice, because it has no session state to lose.

The fix belongs on the end behind the NAT, not on the hub:

Configuration changeon the router behind NAT

set interfaces wireguard wg0 peer HUB persistent-keepalive '25'
commit
save

Verifying this fix requires patience that an incident does not encourage: a tunnel checked immediately after traffic has crossed proves nothing about a binding that expires during idleness. Leave it alone for longer than the binding lifetime and check again.

What each action costs if it is wrong

Action	If it is right	If it is wrong
Regenerate a key pair	Nothing — this is not a fix for any fault here	The far end holds the old key; the tunnel is now definitively down until a two-ended change
Bounce the interface or recreate the peer	Service may return	The handshake age and both counters reset, and the cause becomes unknowable
Widen a firewall rule to test	The blocked port is confirmed	A permanent WAN hole nobody remembers opening, on the router terminating your VPN
Add or edit allowed-ips	The mirror is completed and traffic flows	On one side only, you have added a route without the matching permission, and the silent half of the fault moves rather than clearing
Add a static route into the tunnel	The destination becomes reachable	An overlapping prefix is pulled into the tunnel, and something unrelated stops working
Lower the interface MTU	Large transfers start crossing	Guessed rather than measured, throughput drops for no reason and the real ceiling is still unknown
Paste a configuration into the ticket	Nothing	The private key is a configuration value on 1.5, so this is a disclosed secret and a rotation incident

Holding is a first-class option

If the two ends have no agreed sheet of keys, ports and allowed-ips lists, and the tunnel has never worked, the correct action is to stop.

Trial-and-error across two change windows eventually produces a tunnel, and nobody will be able to say afterwards which of the twenty changes mattered or what the resulting configuration is supposed to be. Record a hold with an owner and an end time, ask for the two lists in writing, and hand the window back.

The same applies mid-incident when the evidence points at the far end and the far-end owner is not available. A capture showing your packets arriving and drawing no reply is a complete finding. Continuing to change this router after that point only adds variables.

Common patterns

Symptom	Likely cause	Where to look
No `latest handshake` line at either end	UDP blocked, wrong peer address, or wrong public key	Capture on both WANs, then the input-chain counters
Packets arrive at the far end and draw no reply	Public key mismatch, or a preshared key on one side only	Compare keys across the two routers
Neither end ever sends anything	Neither peer has an `address`, so both are waiting	`show interfaces wireguard wg0 endpoints`
Handshake fine, nothing moves either way	No route pointing into the tunnel	`show ip route` for the far prefix
Handshake fine, traffic one direction only	Allowed-ips gap on the RECEIVING end	The far router’s peer configuration
Decrypted packet leaves here, never appears there	Far-end allowed-ips does not cover your source prefix	`tcpdump` on the tunnel interface at both ends
Named rule-set counters all zero, including default	Nothing in the forward chain jumps to it	`show firewall ipv4 forward filter`
Outbound works, replies dropped at the far end	Missing or mis-ordered established and related rule	The far end’s named rule-set counters
Ping works, TLS and file transfers stall	MTU too high, or no MSS clamp	Sized do-not-fragment ping, then the clamp
Large packets stopped with no config change	The underlay path changed — WAN failover, upstream tunnel	Re-measure the ceiling and compare to yesterday
Works, then stops after a quiet minute or two	NAT binding expired, no `persistent-keepalive`	The peer configuration on the NATed end
Interface will not commit, port unavailable	Another WireGuard interface already holds that port	The listen ports of the other tunnels on this router
Tunnel gone after a reboot	Committed, never saved	`/config/config.boot`

Provenance

This runbook was written from the course’s own Part XLI lessons — vyos-xli-01-wireguard-concept, vyos-xli-02-wireguard-keys, vyos-xli-03-wireguard-peers, vyos-xli-04-wireguard-routing, vyos-xli-05-wireguard-firewall and vyos-xli-06-wireguard-troubleshoot — together with vyos-li-04-mss-clamping for the clamping material and vyos-lii-02-evidence-first for the capture-before-change discipline. It has not been executed against a live pair of routers, and no output is reproduced here as if it had been captured.

Why this matters

Every other VPN on this platform gives you intermediate signals to lean on: a phase that succeeded while another failed, a proposal list to compare, a daemon narrating a negotiation in a log. WireGuard removes all of them. It either has a handshake or it does not, and the configuration either matches at both ends or it silently does not.

That changes what competence looks like. It is not knowing more commands — there are barely a dozen. It is knowing that the evidence is an absent line, that a counter with bytes out and zero bytes in names the router you should be working on, and that the router carrying the mistake is usually the one whose operator sees nothing wrong.

The habit worth keeping past this incident is refusing one-ended diagnosis. A tunnel examined from one end has been half examined, and the half that was skipped is where the interesting failure lives — every single time, by construction, because the protocol is designed to say nothing to the side that is wrong.