Checklist and troubleshooting
Checklist
- A key pair per router; private keys never leave it, and never get published.
- On each side: tunnel address, listen port, the peer's public key and endpoint, and AllowedIPs covering everything that should reach you through that peer.
- A route for the far site's networks into the tunnel (or a routing protocol over it).
- Persistent keepalive if either side is behind NAT.
- MSS clamping on the tunnel, and ICMP "fragmentation needed" allowed through firewalls.
- A firewall policy for the tunnel interface.
When it doesn't work
| Symptom | Look at | Usual cause |
|---|---|---|
| No handshake | show interfaces wireguard wg0 summary (latest handshake) | Wrong public key or endpoint, or UDP 51820 blocked |
Handshake OK, Required key not available | AllowedIPs on the sending side | Destination missing from the peer's AllowedIPs |
| Handshake OK, replies never arrive | AllowedIPs on the receiving side | Source missing from the peer's AllowedIPs, so it's dropped |
| Small packets work, large ones hang | DF pings at increasing sizes | Path MTU discovery blocked; clamp MSS |
| Tunnel drops after a while behind NAT | latest handshake age | No persistent keepalive |
vyos@R1:~$ show interfaces wireguard wg0 summary
interface: wg0
description: TUNNEL-TO-SITE-B
address: 10.255.0.1/30
public key: OConCRYmjmBfDgES1tEaOWlemFABGnHdedxblLTPmXo=
private key: (hidden)
listening port: 51820
peer: SITE-B
public key: XQamVv310EgscbB6CVqvJHwnfCQXczieqVA5KiWMKjg=
latest handshake: 0:01:03
status: active
endpoint: 198.51.100.2:51820
allowed ips: 10.255.0.0/30, 10.2.0.0/24
transfer: 3 KB received, 4 KB sent
persistent keepalive: every 25 seconds- Line 11: Recent handshake.
- Line 14: Both subnets allowed.
- Line 15: Traffic flowing.
vyos@R1:~$ show configuration commands | match "wireguard|static"
set interfaces wireguard wg0 address '10.255.0.1/30'
set interfaces wireguard wg0 description 'TUNNEL-TO-SITE-B'
set interfaces wireguard wg0 peer SITE-B address '198.51.100.2'
set interfaces wireguard wg0 peer SITE-B allowed-ips '10.255.0.0/30'
set interfaces wireguard wg0 peer SITE-B allowed-ips '10.2.0.0/24'
set interfaces wireguard wg0 peer SITE-B persistent-keepalive '25'
set interfaces wireguard wg0 peer SITE-B port '51820'
set interfaces wireguard wg0 peer SITE-B public-key 'XQamVv310EgscbB6CVqvJHwnfCQXczieqVA5KiWMKjg='
set interfaces wireguard wg0 port '51820'
set interfaces wireguard wg0 private-key '4D/X9DgG5DxTgUujH2p1/Bt4xx1Cv+puImElA4pY0E4='
set protocols static route 0.0.0.0/0 next-hop 203.0.113.1
set protocols static route 10.2.0.0/24 interface wg0- Lines 2–11: The tunnel and its peer.
- Line 13: Site B into the tunnel.