gluetun_wireguard_proxy/README.md

# WireGuard Server Setup with Gluetun (Docker)

A comprehensive bash script for setting up a WireGuard VPN server using Gluetun in a Docker container on Debian systems. This setup provides HTTP and SOCKS5 proxy functionality with automatic failsafe mechanisms.

## 🚀 Features

- **Automated Installation**: Complete Docker and dependency setup
- **WireGuard Integration**: Custom WireGuard configuration support
- **Proxy Services**: HTTP proxy (port 8888) and SOCKS5 proxy (port 8388)
- **Kill Switch**: Built-in VPN kill switch prevents traffic leaks
- **Firewall Configuration**: Automated UFW setup with secure defaults
- **Systemd Integration**: Auto-start containers on boot
- **Static IP Support**: Optional static IP configuration
- **Package Validation**: Checks and installs only missing components

## 📋 Requirements

### System Requirements
- **OS**: Debian 10+ (Buster or newer)
- **Architecture**: x86_64 (amd64)
- **RAM**: 512MB minimum (1GB recommended)
- **Storage**: 8GB minimum
- **Root Access**: Required for installation

### WireGuard Requirements
- Valid WireGuard configuration from your VPN provider
- Private Key
- Public Key
- Server Endpoint (IP:Port)
- Interface IP address (IPv4 only)

## ⚠️ Important: Proxmox Considerations

### LXC Containers (Not Recommended)
LXC containers have limitations with TUN/TAP devices required for VPN functionality. While workarounds exist, they require host-level modifications.

### VM (Recommended)
Use a **VM instead of LXC** for best compatibility:
- **OS**: Debian netinst minimal
- **RAM**: 512MB
- **Disk**: 8GB
- **CPU**: 1 vCore

## 🛠️ Installation

### 1. Download and Prepare
```bash
# Download the script
wget https://raw.githubusercontent.com/your-repo/wireguard-gluetun-setup.sh
# OR
curl -O https://raw.githubusercontent.com/your-repo/wireguard-gluetun-setup.sh

# Make executable
chmod +x wireguard-gluetun-setup.sh
```

### 2. Run Installation
```bash
sudo ./wireguard-gluetun-setup.sh
```

### 3. Follow Interactive Setup
The script will prompt for:
- Static IP configuration (optional)
- WireGuard configuration details
- Confirmation of installation steps

## 🔧 Configuration

### Required WireGuard Parameters
During installation, you'll be prompted for:

```
WireGuard Private Key: [Your private key]
WireGuard Public Key: [Your public key]
WireGuard Preshared Key: [Optional - press Enter to skip]
WireGuard Endpoint: [e.g., vpn.example.com:51820]
WireGuard Allowed IPs: [e.g., 0.0.0.0/0]
WireGuard Interface IP: [e.g., 10.66.66.2/32] ⚠️ IPv4 ONLY
```

### ⚠️ Critical: IPv6 Limitation
**Gluetun currently has issues with IPv6 addresses in WireGuard interface configuration.**

❌ **Don't use**: `10.66.66.2/32,fd42:42:42::2/128`  
✅ **Use instead**: `10.66.66.2/32`

The script automatically filters IPv6 addresses to prevent connection issues.

### Generated Configuration
The script creates:
- Docker Compose file: `/opt/gluetun/docker-compose.yml`
- Systemd service: `/etc/systemd/system/gluetun.service`
- UFW firewall rules
- Network interface configuration (if static IP chosen)

## 🔗 Proxy Usage

After successful installation, you can use these proxy settings:

### HTTP/HTTPS Proxy
```
Proxy: http://[SERVER-IP]:8888
Port: 8888
```

### SOCKS5 Proxy  
```
Host: [SERVER-IP]
Port: 8388
```

### Example Configuration

**Browser Settings:**
- HTTP Proxy: `192.168.1.100:8888`
- HTTPS Proxy: `192.168.1.100:8888`
- SOCKS5 Proxy: `192.168.1.100:8388`

**Command Line Usage:**
```bash
# Using HTTP proxy
curl --proxy http://192.168.1.100:8888 https://ipinfo.io/ip

# Using SOCKS5 proxy
curl --socks5 192.168.1.100:8388 https://ipinfo.io/ip
```

## 🎛️ Management Commands

### Container Management
```bash
# Check container status
docker ps

# View container logs
docker logs gluetun-wireguard

# Follow logs in real-time
docker logs -f gluetun-wireguard
```

### Service Management
```bash
# Start service
systemctl start gluetun

# Stop service
systemctl stop gluetun

# Restart service
systemctl restart gluetun

# Check service status
systemctl status gluetun
```

### Docker Compose Commands
```bash
# Navigate to configuration directory
cd /opt/gluetun

# Start container
docker-compose up -d

# Stop container
docker-compose down

# Update container image
docker-compose pull && docker-compose up -d
```

## 🔒 Security Features

### Built-in Kill Switch
Gluetun includes an automatic kill switch that:
- Blocks all traffic if VPN connection drops
- Only allows traffic through the VPN tunnel
- Prevents DNS leaks

### Firewall Configuration
The script configures UFW with:
- Default deny incoming policy
- Allow SSH access
- Allow proxy ports (8888, 8388)
- Allow Docker subnet communication
- Block all other incoming connections

### Network Isolation
- Container traffic is isolated to Docker networks
- Only specified subnets can communicate with container
- VPN traffic is routed through encrypted tunnel

## 🔍 Troubleshooting

### Common Issues

#### 1. Container Won't Start (Proxmox LXC)
**Problem**: `/dev/net/tun: no such file or directory`

**Solution**: Use a VM instead of LXC container, or modify LXC configuration on Proxmox host:
```bash
# On Proxmox host
pct stop [CONTAINER_ID]
echo "lxc.cgroup2.devices.allow: c 10:200 rwm" >> /etc/pve/lxc/[CONTAINER_ID].conf
echo "lxc.mount.entry: /dev/net dev/net none bind,create=dir" >> /etc/pve/lxc/[CONTAINER_ID].conf
pct start [CONTAINER_ID]
```

#### 2. VPN Not Connecting
**Check logs**:
```bash
docker logs gluetun-wireguard | grep -E "(ERROR|WARN|wireguard)"
```

**Common causes**:
- Incorrect WireGuard keys
- IPv6 addresses in interface configuration
- Firewall blocking VPN endpoint
- VPN server issues

#### 3. Can't Access Proxy
**Verify container is running**:
```bash
docker ps | grep gluetun
```

**Test proxy connectivity**:
```bash
curl --proxy http://localhost:8888 https://ipinfo.io/ip
```

**Check firewall**:
```bash
ufw status
```

#### 4. DNS Issues
If experiencing DNS resolution problems, modify `/opt/gluetun/docker-compose.yml`:
```yaml
environment:
  - DNS_ADDRESS=1.1.1.1
  # or
  - DNS_ADDRESS=8.8.8.8
```

### Diagnostic Commands

```bash
# Check VPN connection inside container
docker exec gluetun-wireguard wget -qO- https://ipinfo.io/ip

# Test WireGuard interface
docker exec gluetun-wireguard wg show

# Check container networking
docker exec gluetun-wireguard ip route

# Test external connectivity
docker exec gluetun-wireguard ping -c 3 8.8.8.8
```

## 📁 File Locations

| File | Location | Purpose |
|------|----------|---------|
| Docker Compose | `/opt/gluetun/docker-compose.yml` | Container configuration |
| Systemd Service | `/etc/systemd/system/gluetun.service` | Auto-start service |
| Network Config | `/etc/network/interfaces` | Static IP settings |
| UFW Rules | `/etc/ufw/user.rules` | Firewall configuration |

## 🔄 Updates

### Updating Gluetun
```bash
cd /opt/gluetun
docker-compose pull
docker-compose up -d
```

### Updating Configuration
1. Edit `/opt/gluetun/docker-compose.yml`
2. Restart container: `docker-compose up -d`

## 🆘 Support

### Getting Help
- Check container logs: `docker logs gluetun-wireguard`
- Review Gluetun documentation: [Gluetun Wiki](https://github.com/qdm12/gluetun/wiki)
- Verify WireGuard configuration with your provider

### Reporting Issues
When reporting issues, please include:
- Operating system version (`lsb_release -a`)
- Container logs (`docker logs gluetun-wireguard`)
- Docker Compose configuration (sanitized)
- Error messages and symptoms

## 📄 License

This script is provided as-is for educational and practical purposes. Use at your own risk and ensure compliance with your local laws and VPN provider's terms of service.

## 🙏 Acknowledgments

- [Gluetun](https://github.com/qdm12/gluetun) - Lightweight VPN client in a thin Docker container
- [WireGuard](https://www.wireguard.com/) - Fast, modern, secure VPN tunnel
- [Docker](https://www.docker.com/) - Containerization platform

---

**⚠️ Important Security Notice**: Always use reputable VPN providers and keep your systems updated. This setup is for legitimate privacy and networking purposes only.