mvpg/docs/TROUBLESHOOTING.md

# Troubleshooting Guide

## Common Issues and Solutions

### Installation Issues

#### Problem: Installation fails with dependency errors
```bash
E: Unable to locate package wireguard
```

**Solution:**
```bash
# 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
```bash
modprobe: FATAL: Module wireguard not found
```

**Solution:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Edit WireGuard config
sudo nano /etc/wireguard/wg0.conf

# Reduce keepalive interval
PersistentKeepalive = 10  # Instead of 25
```

2. **Check MTU:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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):**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Force enable
sudo /usr/local/bin/vpn-killswitch.sh enable

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

2. **Check for rule conflicts:**
```bash
# List all rules
sudo iptables-save

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

3. **Restart security monitor:**
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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
```bash
#!/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
```bash
# 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:**
```bash
sudo journalctl -xe
sudo dmesg | tail -50
```

2. **Run health check:**
```bash
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:**
```bash
# 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
```