425 lines
7.8 KiB
Markdown
425 lines
7.8 KiB
Markdown
# 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
|
|
```
|