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
2. General Configuration
3. Provider-Specific Configurations
4. Testing Your VPN Connection
5. Troubleshooting
6. 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:

# =============================================================================
# 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:

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:

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:

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:

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:

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:

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:

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):

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:

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

ansible-playbook -i inventory/hosts site.yml

Step 2: Check Gluetun Connection

# 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

# 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:

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:

# 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:

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

# 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:

# 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):

# 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

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

Multiple VPN Servers

# 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:

# 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 - Comprehensive provider list
• r/VPN - General VPN discussions
• 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.