Troubleshooting¶
Fixes for the problems you are most likely to hit with WireGuard Private Access. Each entry gives the symptom, the usual cause, and what to do.
A remote peer never completes a handshake¶
Cause: the port is still closed, or the keys do not match. The usual reasons are:
- the localhost allowlist is still in place,
- the security group does not allow UDP 51820 from the peer,
- the
PublicKeyon either side is wrong.
Fix: check each one:
If the first command lists the table, open the port as described in
Open the port to remote peers.
Compare the peer's public key with the one in wg0.conf, and this
instance's key, in /usr/local/share/sushi/wireguard/wg0.public, with the
one in the peer's configuration.
The port closes again after a reboot¶
Cause: first boot restores the localhost allowlist on every boot unless
/etc/wireguard/allow-non-localhost exists.
Fix: create the marker file:
wg-quick@wg0 fails to start¶
Cause: usually a mistake in wg0.conf, a peer Endpoint hostname that
does not resolve, or a first boot failure.
Fix: read the logs:
systemctl status sushi-wireguard-firstboot wg-quick@wg0 --no-pager
sudo journalctl -b -u sushi-wireguard-firstboot -u wg-quick@wg0 --no-pager
Fix the configuration, then restart the tunnel with
sudo systemctl restart wg-quick@wg0. If first boot failed, retry it with
sudo systemctl restart sushi-wireguard-firstboot.
First boot reports an identity mismatch¶
Cause: /etc/wireguard/ was restored incompletely: wg0.conf without
wg0.private, a private key that does not match the one in wg0.conf, or
a file replaced with a link.
Fix: restore the whole directory from the same backup, as regular files, then retry first boot. First boot never invents a new identity over a partial restore.
Peers connect, but other VPC hosts cannot reach them¶
Cause: forwarding through the instance needs AWS changes the image does not make.