mvpg/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common Issues and Solutions

Installation Issues

Problem: Installation fails with dependency errors

E: Unable to locate package wireguard

Solution:

# Update package lists
sudo apt update

# Enable backports (Debian)
echo "deb http://deb.debian.org/debian $(lsb_release -cs)-backports main" | \
  sudo tee /etc/apt/sources.list.d/backports.list
sudo apt update

# Install kernel headers
sudo apt install linux-headers-$(uname -r)

# Retry installation
sudo ./install.sh

Problem: WireGuard module not loading

modprobe: FATAL: Module wireguard not found

Solution:

# Install WireGuard kernel module
sudo apt install wireguard-dkms

# Load module manually
sudo modprobe wireguard

# Verify module loaded
lsmod | grep wireguard

Connection Issues

Problem: VPN won't connect

Symptoms: Connection timeout, no handshake

Solutions:

1. Check server reachability:

# Ping server (if ICMP allowed)
ping -c 3 <server-ip>

# Check port connectivity
nc -zv <server-ip> 51820

# Trace route
traceroute <server-ip>

2. Verify credentials:

# Check keys format
wg show wg0 private-key
wg show wg0 public-key

# Verify key length (should be 44 characters)
echo "<key>" | wc -c

3. Check firewall:

# Ensure UDP 51820 outbound is allowed
sudo iptables -L OUTPUT -n -v | grep 51820

# Temporarily allow all outbound (testing only!)
sudo iptables -I OUTPUT 1 -j ACCEPT

4. Review logs:

# Check WebUI logs
sudo journalctl -u vpn-webui -n 100

# Check WireGuard logs
sudo dmesg | grep wireguard

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

Problem: Connection drops frequently

Symptoms: Intermittent connectivity, handshake failures

Solutions:

1. Adjust keepalive:

# Edit WireGuard config
sudo nano /etc/wireguard/wg0.conf

# Reduce keepalive interval
PersistentKeepalive = 10  # Instead of 25

2. Check MTU:

# Test different MTU values
sudo ip link set dev wg0 mtu 1380

# Find optimal MTU
ping -M do -s 1372 <vpn-server-ip>
# Increase/decrease -s value until it works

3. Monitor connection:

# Watch handshakes
watch -n 1 'wg show wg0 latest-handshakes'

# Check for packet loss
mtr <vpn-server-ip>

Network Issues

Problem: No internet after connecting

Symptoms: VPN connected but can't browse

Solutions:

1. Check routing:

# Show routing table
ip route show

# Verify default route through VPN
ip route | grep default

# Add route manually if missing
sudo ip route add default dev wg0

2. Check DNS:

# Test DNS resolution
nslookup google.com
dig google.com

# Check DNS config
cat /etc/resolv.conf

# Force DNS update
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf

3. Check NAT:

# Verify NAT rules
sudo iptables -t nat -L POSTROUTING -n -v

# Add NAT manually if missing
sudo iptables -t nat -A POSTROUTING -o wg0 -j MASQUERADE

Problem: Local network not accessible

Symptoms: Can't reach LAN devices when VPN connected

Solution:

# Add LAN route exception
sudo ip route add 192.168.1.0/24 dev eth0

# Or modify WireGuard AllowedIPs
# Change from: 0.0.0.0/0
# To: 0.0.0.0/1, 128.0.0.0/1

WebUI Issues

Problem: WebUI not loading

Symptoms: Connection refused, timeout

Solutions:

1. Check service status:

# Service status
sudo systemctl status vpn-webui

# Restart service
sudo systemctl restart vpn-webui

# Check if running
ps aux | grep gunicorn

2. Check port binding:

# Verify port is listening
sudo netstat -tlnp | grep 5000
sudo ss -tlnp | grep 5000

# Check for port conflicts
sudo lsof -i :5000

3. Check Nginx (if used):

# Test Nginx config
sudo nginx -t

# Restart Nginx
sudo systemctl restart nginx

# Check Nginx logs
sudo tail -f /var/log/nginx/error.log

Problem: Can't change settings

Symptoms: Changes don't save, errors on submit

Solutions:

1. Check permissions:

# Fix ownership
sudo chown -R root:root /opt/vpn-gateway

# Fix permissions
sudo chmod 755 /opt/vpn-gateway
sudo chmod 644 /opt/vpn-gateway/app.py

2. Check disk space:

# Check available space
df -h /opt/vpn-gateway

# Clean up if needed
sudo journalctl --vacuum-time=7d
sudo apt clean

Security Issues

Problem: Killswitch not working

Symptoms: Internet accessible without VPN

CRITICAL - Fix immediately:

1. Re-enable killswitch:

# Force enable
sudo /usr/local/bin/vpn-killswitch.sh enable

# Verify rules
sudo iptables -L -n -v | grep DROP

2. Check for rule conflicts:

# List all rules
sudo iptables-save

# Remove conflicting rules
sudo iptables -F OUTPUT
sudo iptables -P OUTPUT DROP

3. Restart security monitor:

sudo systemctl restart vpn-security-monitor
sudo systemctl status vpn-security-monitor

Problem: DNS leaks detected

Symptoms: DNS queries not going through VPN

Solutions:

1. Force VPN DNS:

# Lock resolv.conf
sudo chattr +i /etc/resolv.conf

# Disable systemd-resolved
sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved

2. Check firewall rules:

# Block DNS except through VPN
sudo iptables -A OUTPUT -p udp --dport 53 ! -o wg0 -j DROP
sudo iptables -A OUTPUT -p tcp --dport 53 ! -o wg0 -j DROP

Performance Issues

Problem: Slow speeds

Symptoms: Poor throughput, high latency

Solutions:

1. Optimize MTU:

# Test optimal MTU
for mtu in 1420 1400 1380 1360; do
  sudo ip link set dev wg0 mtu $mtu
  echo "Testing MTU $mtu"
  iperf3 -c <server-ip> -t 5
done

2. Check CPU usage:

# Monitor CPU
top -n 1 | grep -E "wireguard|python"

# Check interrupts
watch -n 1 'cat /proc/interrupts | grep -E "eth|wg"'

3. Tune kernel parameters:

# Optimize network stack
cat >> /etc/sysctl.conf << EOF
net.core.rmem_max = 134217728
net.core.wmem_max = 134217728
net.ipv4.tcp_rmem = 4096 87380 134217728
net.ipv4.tcp_wmem = 4096 65536 134217728
net.core.netdev_max_backlog = 30000
net.ipv4.tcp_congestion_control = bbr
EOF

sudo sysctl -p

Diagnostic Commands

Complete System Check

#!/bin/bash
echo "=== VPN Gateway Diagnostics ==="
echo ""
echo "1. Services Status:"
systemctl status vpn-webui --no-pager | head -n 10
systemctl status vpn-killswitch --no-pager | head -n 10
systemctl status vpn-security-monitor --no-pager | head -n 10
echo ""
echo "2. VPN Status:"
wg show
echo ""
echo "3. Firewall Rules:"
iptables -L -n | head -n 20
echo ""
echo "4. Network Configuration:"
ip addr show
ip route show
echo ""
echo "5. DNS Configuration:"
cat /etc/resolv.conf
echo ""
echo "6. Recent Logs:"
journalctl -u vpn-webui -n 20 --no-pager
echo ""
echo "7. Disk Usage:"
df -h /opt/vpn-gateway
echo ""
echo "8. Memory Usage:"
free -h

Export Debug Info

# Create debug archive
sudo tar czf vpn-debug-$(date +%s).tar.gz \
  /var/log/vpn-*.log \
  /var/log/syslog \
  /etc/wireguard/ \
  /opt/vpn-gateway/logs/ \
  <(iptables-save) \
  <(wg show) \
  <(ip addr) \
  <(ip route) \
  <(systemctl status vpn-*)

Getting Help

If problems persist:

1. Check logs thoroughly:

sudo journalctl -xe
sudo dmesg | tail -50

2. Run health check:

sudo /usr/local/bin/vpn-health-check.sh

3. Create issue on GitHub with:

• System info: uname -a
• Service status: systemctl status vpn-*
• Error messages
• Debug archive

4. Emergency recovery:

# Disable killswitch (TEMPORARY!)
sudo iptables -P INPUT ACCEPT
sudo iptables -P OUTPUT ACCEPT
sudo iptables -P FORWARD ACCEPT
sudo iptables -F

# Reinstall
curl -sSL https://raw.githubusercontent.com/yourusername/vpn-gateway/main/install.sh | bash