Troubleshooting WireGuard VPN

Overview

WireGuard is intentionally lightweight and produces very little logging by default, which can make troubleshooting more challenging than with traditional VPN solutions such as OpenVPN.

This article describes the most useful commands for diagnosing WireGuard connectivity issues on Ubuntu Server.

1. Verify the WireGuard Interface

First, confirm that the WireGuard interface is running.

sudo wg show

Verify that:

  • The interface (for example wg0) exists.
  • Peers are listed.
  • A Latest Handshake timestamp appears after a successful connection.
  • Traffic counters (transfer) increase when data is exchanged.

For continuous monitoring, run:

watch -n2 wg show

This is one of the quickest ways to determine whether handshakes are occurring.

2. Check the WireGuard Service

If you are using wg-quick, verify that the service started successfully.

sudo systemctl status wg-quick@wg0

If the service failed to start, inspect the system journal:

sudo journalctl -u wg-quick@wg0 -b

To follow new log entries in real time:

sudo journalctl -fu wg-quick@wg0

3. Verify Network Configuration

Confirm that the interface has the expected IP address:

ip addr show wg0

Verify that routes have been installed correctly:

ip route

If policy routing is used:

ip rule

Incorrect routes or missing policy rules are among the most common causes of connectivity problems.

4. Enable WireGuard Kernel Debug Logging

WireGuard operates primarily inside the Linux kernel and therefore does not generate verbose application logs by default.

For deeper troubleshooting, Ubuntu allows enabling dynamic kernel debugging.

Step 4.1 – Enable debug logging

echo "module wireguard +p" | sudo tee /sys/kernel/debug/dynamic_debug/control

Step 4.2 – Watch kernel messages in real time

Open another terminal and run:

sudo dmesg -wT

or

sudo journalctl -kf

You should now see WireGuard kernel events, including handshake attempts, peer activity, and packet processing.

Step 4.3 – View historical kernel debug logs

To display previously recorded kernel messages:

sudo journalctl -k

To show only messages related to WireGuard:

sudo journalctl -k | grep -i wireguard

To display kernel messages from the current boot only:

sudo journalctl -k -b

Note

Historical debug messages are only available if WireGuard dynamic debug was enabled when the events occurred and the system journal has retained the logs. Logs from previous boots are available only if persistent journaling is enabled.

Step 4.4 – Disable debug logging

Once troubleshooting is complete, disable verbose logging:

echo "module wireguard -p" | sudo tee /sys/kernel/debug/dynamic_debug/control

Note

On systems with Secure Boot enabled, Linux Kernel Lockdown may prevent dynamic debug from working. In that case, you may need to disable Secure Boot or boot the kernel with the wireguard.dyndbg=+p kernel parameter.

5. Capture WireGuard Traffic

If no handshakes are visible, verify that UDP packets are reaching the server.

Replace 51820 with your WireGuard listening port if different.

sudo tcpdump -ni any udp port 51820

You should observe incoming and outgoing UDP packets when a client attempts to connect.

If no packets are captured, investigate:

  • Firewall rules
  • NAT configuration
  • Cloud security groups
  • Internet connectivity
  • Client endpoint configuration

6. Common Checks

Before investigating more complex issues, verify the following:

  • Public and private keys match the correct peers.
  • AllowedIPs are configured correctly on every peer.
  • The endpoint address and port are correct.
  • IP forwarding is enabled when routing traffic.
  • Firewall rules allow UDP traffic on the WireGuard port.
  • NAT (MASQUERADE/SNAT) rules are configured if clients require Internet access through the tunnel.

Useful Commands

# Show WireGuard status
sudo wg show

# Monitor WireGuard status
watch -n2 wg show

# Show interface configuration
ip addr show wg0

# Show routing table
ip route

# Show policy routing
ip rule

# Service status
sudo systemctl status wg-quick@wg0

# Service logs
sudo journalctl -u wg-quick@wg0 -b

# Follow service logs
sudo journalctl -fu wg-quick@wg0

# Enable WireGuard kernel debug logging
echo "module wireguard +p" | sudo tee /sys/kernel/debug/dynamic_debug/control

# Watch kernel logs (live)
sudo dmesg -wT

# Alternative live kernel logs
sudo journalctl -kf

# View historical kernel logs
sudo journalctl -k

# View WireGuard kernel logs only
sudo journalctl -k | grep -i wireguard

# View kernel logs from current boot
sudo journalctl -k -b

# Disable WireGuard kernel debug logging
echo "module wireguard -p" | sudo tee /sys/kernel/debug/dynamic_debug/control

# Capture WireGuard UDP traffic
sudo tcpdump -ni any udp port 51820

References