arr-suite-template-bootstrap/docs/VPN_CONFIGURATION.md

# VPN Configuration Guide

This guide provides detailed configuration examples for popular VPN providers with the Arrs media stack. The VPN integration uses Gluetun to route qBittorrent traffic through your VPN provider for enhanced privacy and security.

## Table of Contents

1. [Overview](#overview)
2. [General Configuration](#general-configuration)
3. [Provider-Specific Configurations](#provider-specific-configurations)
4. [Testing Your VPN Connection](#testing-your-vpn-connection)
5. [Troubleshooting](#troubleshooting)
6. [Advanced Configuration](#advanced-configuration)

## Overview

### What Gets Protected

When VPN is enabled:
- ✅ **qBittorrent**: All torrent traffic routed through VPN
- ✅ **SABnzbd**: Optionally routed through VPN (configurable)
- ❌ **Other services**: Sonarr, Radarr, Plex, etc. use direct connection

### VPN Technologies Supported

- **OpenVPN**: Most common, works with most providers
- **WireGuard**: Faster, more modern protocol (where supported)

## General Configuration

### Basic VPN Settings

Edit `group_vars/all.yml`:

```yaml
# =============================================================================
# VPN CONFIGURATION (for qBittorrent)
# =============================================================================

# Enable VPN for download clients
vpn_enabled: true

# Optionally route SABnzbd through VPN as well (some prefer Usenet through VPN)
sabnzbd_vpn_enabled: false  # Set to true if you want SABnzbd through VPN

# VPN Provider (see provider list below)
vpn_provider: "nordvpn"  # Change to your provider

# VPN Type: openvpn or wireguard
vpn_type: "openvpn"

# OpenVPN credentials (if using OpenVPN)
openvpn_user: "your_username"
openvpn_password: "your_password"

# WireGuard configuration (if using WireGuard)
wireguard_private_key: ""
wireguard_addresses: ""

# VPN server countries (comma-separated)
vpn_countries: "Netherlands,Germany"
```

## Provider-Specific Configurations

### NordVPN

**Requirements:**
- NordVPN subscription
- Service credentials (not your regular login)

**Configuration:**

```yaml
vpn_enabled: true
vpn_provider: "nordvpn"
vpn_type: "openvpn"
openvpn_user: "your_service_username"
openvpn_password: "your_service_password"
vpn_countries: "Netherlands,Germany,Switzerland"
```

**Getting Service Credentials:**
1. Log into your NordVPN account
2. Go to Services → NordVPN → Manual Setup
3. Generate service credentials
4. Use these credentials (not your regular login)

**Recommended Countries:**
- Netherlands, Germany, Switzerland (good for privacy)
- Romania, Moldova (good speeds)

### ExpressVPN

**Requirements:**
- ExpressVPN subscription
- Manual configuration credentials

**Configuration:**

```yaml
vpn_enabled: true
vpn_provider: "expressvpn"
vpn_type: "openvpn"
openvpn_user: "your_username"
openvpn_password: "your_password"
vpn_countries: "Netherlands,Germany"
```

**Getting Credentials:**
1. Log into ExpressVPN account
2. Go to Set Up ExpressVPN → Manual Config
3. Select OpenVPN
4. Download credentials or note username/password

### Surfshark

**Requirements:**
- Surfshark subscription
- Service credentials

**Configuration:**

```yaml
vpn_enabled: true
vpn_provider: "surfshark"
vpn_type: "openvpn"
openvpn_user: "your_service_username"
openvpn_password: "your_service_password"
vpn_countries: "Netherlands,Germany"
```

**Getting Service Credentials:**
1. Log into Surfshark account
2. Go to VPN → Manual setup → OpenVPN
3. Generate or view service credentials

### Private Internet Access (PIA)

**Requirements:**
- PIA subscription
- Username and password

**Configuration:**

```yaml
vpn_enabled: true
vpn_provider: "private internet access"
vpn_type: "openvpn"
openvpn_user: "your_pia_username"
openvpn_password: "your_pia_password"
vpn_countries: "Netherlands,Germany,Switzerland"
```

**Note:** Use your regular PIA login credentials.

### CyberGhost

**Requirements:**
- CyberGhost subscription
- OpenVPN credentials

**Configuration:**

```yaml
vpn_enabled: true
vpn_provider: "cyberghost"
vpn_type: "openvpn"
openvpn_user: "your_username"
openvpn_password: "your_password"
vpn_countries: "Netherlands,Germany"
```

**Getting Credentials:**
1. Log into CyberGhost account
2. Go to My Account → VPN → Configure new device
3. Select OpenVPN and download configuration

### ProtonVPN

**Requirements:**
- ProtonVPN subscription (Plus or higher for P2P)
- OpenVPN credentials

**Configuration:**

```yaml
vpn_enabled: true
vpn_provider: "protonvpn"
vpn_type: "openvpn"
openvpn_user: "your_openvpn_username"
openvpn_password: "your_openvpn_password"
vpn_countries: "Netherlands,Germany,Switzerland"
```

**Getting Credentials:**
1. Log into ProtonVPN account
2. Go to Account → OpenVPN/IKEv2 username
3. Generate OpenVPN credentials

**Important:** Only Plus and Visionary plans support P2P traffic.

### Mullvad

**Requirements:**
- Mullvad subscription
- Account number

**OpenVPN Configuration:**

```yaml
vpn_enabled: true
vpn_provider: "mullvad"
vpn_type: "openvpn"
openvpn_user: "your_account_number"
openvpn_password: "m"  # Always "m" for Mullvad
vpn_countries: "Netherlands,Germany,Switzerland"
```

**WireGuard Configuration (Recommended):**

```yaml
vpn_enabled: true
vpn_provider: "mullvad"
vpn_type: "wireguard"
wireguard_private_key: "your_private_key"
wireguard_addresses: "10.x.x.x/32"
vpn_countries: "Netherlands,Germany,Switzerland"
```

**Getting WireGuard Keys:**
1. Log into Mullvad account
2. Go to WireGuard configuration
3. Generate a key pair
4. Note the private key and IP address

### Windscribe

**Requirements:**
- Windscribe Pro subscription
- OpenVPN credentials

**Configuration:**

```yaml
vpn_enabled: true
vpn_provider: "windscribe"
vpn_type: "openvpn"
openvpn_user: "your_username"
openvpn_password: "your_password"
vpn_countries: "Netherlands,Germany"
```

**Getting Credentials:**
1. Log into Windscribe account
2. Go to Setup → Config Generators → OpenVPN
3. Generate configuration with credentials

## Testing Your VPN Connection

### Step 1: Deploy with VPN Enabled

```bash
ansible-playbook -i inventory/hosts site.yml
```

### Step 2: Check Gluetun Connection

```bash
# Check Gluetun logs
docker logs gluetun

# Look for successful connection messages
docker logs gluetun | grep -i "connected"
```

### Step 3: Verify qBittorrent IP

1. Go to qBittorrent web interface: `http://YOUR_VPS_IP:8080`
2. Check the connection status
3. Use a torrent IP checker to verify your IP has changed

### Step 4: Test IP Leak Protection

```bash
# Check what IP qBittorrent sees
docker exec qbittorrent curl -s https://ipinfo.io/ip
```

This should show your VPN server's IP, not your VPS IP.

## Troubleshooting

### Common Issues

#### Gluetun Won't Connect

**Check logs:**
```bash
docker logs gluetun
```

**Common causes:**
- Wrong credentials
- Unsupported server location
- Provider API issues

**Solutions:**
1. Verify credentials are correct
2. Try different server countries
3. Check provider status page

#### qBittorrent Can't Access Internet

**Symptoms:**
- Can't download torrents
- Can't access trackers

**Check:**
```bash
# Test internet connectivity through Gluetun
docker exec qbittorrent curl -s https://google.com
```

**Solutions:**
1. Restart Gluetun: `docker restart gluetun`
2. Check VPN server status
3. Try different server location

#### Services Start But No VPN Protection

**Check network mode:**
```bash
docker inspect qbittorrent | grep -i network
```

Should show: `"NetworkMode": "service:gluetun"`

**Fix:**
1. Ensure `vpn_enabled: true` in configuration
2. Redeploy: `ansible-playbook -i inventory/hosts site.yml`

### Debug Commands

```bash
# Check all container status
docker ps

# Check Gluetun detailed logs
docker logs gluetun --tail 50

# Check qBittorrent logs
docker logs qbittorrent --tail 50

# Test VPN connection
docker exec gluetun wget -qO- https://ipinfo.io/ip

# Check qBittorrent network
docker exec qbittorrent ip route
```

## Advanced Configuration

### Custom VPN Servers

Some providers allow specifying exact servers:

```yaml
# For providers that support server selection
vpn_server_hostnames: "nl123.nordvpn.com,de456.nordvpn.com"
```

### Port Forwarding

For providers that support port forwarding (like PIA):

```yaml
# Enable port forwarding (if supported by provider)
vpn_port_forwarding: true
```

### Kill Switch

Gluetun includes a built-in kill switch that blocks all traffic if VPN disconnects. This is enabled by default.

### Custom DNS

```yaml
# Use custom DNS servers through VPN
vpn_dns_servers: "1.1.1.1,1.0.0.1"
```

### Multiple VPN Servers

```yaml
# Connect to multiple countries (load balanced)
vpn_countries: "Netherlands,Germany,Switzerland,Romania"
```

## Security Best Practices

### 1. Use Strong Credentials

- Generate unique passwords for VPN services
- Store credentials securely
- Rotate credentials periodically

### 2. Choose Privacy-Friendly Locations

**Good choices:**
- Netherlands, Germany, Switzerland (strong privacy laws)
- Romania, Moldova (good for torrenting)

**Avoid:**
- Countries with data retention laws
- Your home country (for maximum privacy)

### 3. Monitor Connection Status

Set up monitoring to alert if VPN disconnects:

```bash
# Add to crontab for monitoring
*/5 * * * * docker exec gluetun wget -qO- https://ipinfo.io/ip | grep -v "YOUR_VPS_IP" || echo "VPN DOWN" | mail -s "VPN Alert" your@email.com
```

### 4. Regular Testing

- Test IP changes monthly
- Verify no DNS leaks
- Check for WebRTC leaks

### 5. Enhanced Security Features

The VPN configuration includes several security enhancements:

**Kill Switch Protection:**
- Firewall automatically blocks traffic if VPN disconnects
- No data leaks even during VPN reconnection
- Configured automatically with `FIREWALL=on`

**DNS Leak Prevention:**
- Custom DNS servers prevent ISP DNS leaks
- DNS over TLS disabled to avoid conflicts
- Malicious domain blocking enabled

**Network Isolation:**
- Download clients isolated from other services
- Only necessary ports exposed through VPN
- Outbound traffic restricted to Docker subnet

**Port Configuration:**
- qBittorrent: Port 8080 (through VPN)
- SABnzbd: Port 8081 (through VPN, if enabled)
- Automatic port conflict resolution

## Provider Comparison

| Provider | OpenVPN | WireGuard | Port Forward | P2P Friendly | Notes |
|----------|---------|-----------|--------------|--------------|-------|
| NordVPN | ✅ | ❌ | ❌ | ✅ | Good speeds, many servers |
| ExpressVPN | ✅ | ❌ | ❌ | ✅ | Premium service, fast |
| Surfshark | ✅ | ✅ | ❌ | ✅ | Good value, unlimited devices |
| PIA | ✅ | ✅ | ✅ | ✅ | Port forwarding support |
| CyberGhost | ✅ | ❌ | ❌ | ✅ | Dedicated P2P servers |
| ProtonVPN | ✅ | ✅ | ❌ | ✅* | *Plus plan required for P2P |
| Mullvad | ✅ | ✅ | ✅ | ✅ | Privacy-focused, anonymous |
| Windscribe | ✅ | ❌ | ❌ | ✅ | Good free tier |

## Getting Help

### Provider Support

Most VPN providers have specific guides for Docker/Gluetun:
- Check your provider's knowledge base
- Search for "Docker" or "Gluetun" setup guides
- Contact provider support for OpenVPN credentials

### Community Resources

- [Gluetun Wiki](https://github.com/qdm12/gluetun-wiki) - Comprehensive provider list
- [r/VPN](https://reddit.com/r/VPN) - General VPN discussions
- [r/selfhosted](https://reddit.com/r/selfhosted) - Self-hosting community

### Troubleshooting Checklist

1. ✅ VPN subscription active?
2. ✅ Correct provider name in config?
3. ✅ Valid credentials?
4. ✅ Supported server location?
5. ✅ Provider allows P2P traffic?
6. ✅ Gluetun container running?
7. ✅ qBittorrent using Gluetun network?
8. ✅ No firewall blocking VPN?

Remember: VPN configuration can be tricky. Start with a simple setup and gradually add complexity as needed.