New branch
This commit is contained in:
commit
58d70409b5
31 changed files with 9093 additions and 0 deletions
425
docs/TROUBLESHOOTING.md
Normal file
425
docs/TROUBLESHOOTING.md
Normal file
|
|
@ -0,0 +1,425 @@
|
|||
# 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
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue