EZ-Homelab/config-templates/dokuwiki/data/pages/services/media/qbittorrent.txt

====== qBittorrent ======

qBittorrent is a free and open-source BitTorrent client that provides a web-based interface for downloading and managing torrent files. In the AI-Homelab, it's configured to route all traffic through Gluetun VPN for enhanced privacy and security.

===== Overview =====

**Purpose:** Torrent downloading with VPN protection
**URL:** https://qbit.yourdomain.duckdns.org
**Authentication:** Built-in web UI authentication
**Deployment:** Media stack (VPN-routed through Gluetun)
**VPN Integration:** Routes through Gluetun container

===== Key Features =====

**Torrent Management:**
  * **Web Interface**: Clean, responsive web UI
  * **Torrent Creation**: Create torrents from files/folders
  * **Magnet Links**: Support for magnet link downloads
  * **Batch Downloads**: Download multiple torrents
  * **RSS Feeds**: Automatic RSS feed monitoring

**Download Control:**
  * **Speed Limits**: Set download/upload speed limits
  * **Bandwidth Management**: Per-torrent bandwidth allocation
  * **Queue Management**: Priority-based download queuing
  * **Auto-Management**: Automatic torrent management

**Privacy & Security:**
  * **VPN Routing**: All traffic through Gluetun VPN
  * **IP Binding**: Bind to VPN interface only
  * **Encryption**: Protocol encryption support
  * **Proxy Support**: SOCKS5/HTTP proxy support

===== Configuration =====

**Container Configuration:**
```yaml
services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: "service:gluetun"  # Route through VPN
    depends_on:
      - gluetun
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=${TZ}
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent/config:/config
      - /mnt/downloads:/downloads
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 256M
```

**Gluetun Configuration (Update):**
```yaml
# In gluetun service, add port mapping
gluetun:
  ports:
    - 8080:8080  # qBittorrent WebUI
    - 6881:6881  # Torrent ports (TCP)
    - 6881:6881/udp  # Torrent ports (UDP)
```

**Environment Variables:**
```bash
# User permissions
PUID=1000
PGID=1000

# Timezone
TZ=America/New_York

# Web UI port
WEBUI_PORT=8080
```

===== VPN Integration =====

**Network Mode:**
```yaml
network_mode: "service:gluetun"
```

**Benefits:**
  * **IP Protection**: All torrent traffic through VPN
  * **ISP Protection**: Hide torrenting from ISP
  * **Geographic Access**: Access geo-restricted content
  * **Privacy**: Enhanced download privacy

**Port Mapping:**
  * **WebUI**: 8080 (internal to Gluetun)
  * **Torrent TCP**: 6881
  * **Torrent UDP**: 6881

**VPN Verification:**
```bash
# Check if qBittorrent is using VPN IP
docker exec gluetun curl -s ifconfig.me

# Verify qBittorrent is accessible through VPN
curl -k https://qbit.yourdomain.duckdns.org
```

===== Initial Setup =====

**First Access:**
  1. **Navigate**: Visit qBittorrent URL
  2. **Default Credentials**: admin/adminadmin
  3. **Change Password**: Immediately change default password
  4. **Configure Settings**: Set up download preferences

**Basic Configuration:**
  * **Download Location**: Set to `/downloads`
  * **Temporary Files**: Configure temp directory
  * **Auto-Management**: Enable automatic torrent management
  * **WebUI Settings**: Configure interface preferences

===== Download Management =====

**Adding Torrents:**
  * **Torrent Files**: Upload .torrent files
  * **Magnet Links**: Paste magnet links
  * **URLs**: Add torrent URLs
  * **Batch Operations**: Add multiple torrents

**Download Categories:**
  * **Category Creation**: Create download categories
  * **Path Assignment**: Assign paths per category
  * **Automatic Sorting**: Auto-assign categories
  * **Category Management**: Organize downloads

**Queue Management:**
  * **Priority Setting**: Set download priorities
  * **Queue Limits**: Limit concurrent downloads
  * **Speed Allocation**: Allocate bandwidth per torrent
  * **Sequential Downloads**: Download files in order

===== Advanced Features =====

**RSS Integration:**
  * **RSS Feeds**: Add RSS torrent feeds
  * **Automatic Downloads**: Auto-download matching torrents
  * **Filters**: Set download filters and rules
  * **Smart Filtering**: Advanced filtering options

**Search Integration:**
  * **Built-in Search**: Search torrent sites
  * **Search Plugins**: Install additional search plugins
  * **Plugin Management**: Manage search engines
  * **Search History**: Track search history

**Automation:**
  * **Watch Folders**: Monitor folders for new torrents
  * **Auto-Tagging**: Automatic torrent tagging
  * **Script Integration**: Execute scripts on completion
  * **API Integration**: REST API for automation

===== Performance Optimization =====

**Speed Settings:**
```yaml
# Recommended settings for VPN
Global maximum number of upload slots: 20
Global maximum number of half-open connections: 500
Maximum number of upload slots per torrent: 4
Maximum number of connections per torrent: 100
```

**Disk Settings:**
  * **Disk Cache**: Set to 64-128 MB
  * **Disk Cache Expiry**: 60 seconds
  * **OS Cache**: Enable OS cache
  * **Coalesce Reads**: Enable for SSDs

**Connection Settings:**
  * **Global Max Connections**: 500
  * **Max Per Torrent**: 100
  * **Max Upload Slots**: 20
  * **Max Half-Open**: 500

===== Security Configuration =====

**WebUI Security:**
  * **Authentication**: Enable username/password
  * **HTTPS**: Force HTTPS connections
  * **IP Filtering**: Restrict access by IP
  * **Session Timeout**: Configure session limits

**Network Security:**
  * **Encryption**: Enable protocol encryption
  * **DHT**: Enable DHT for peer discovery
  * **PEX**: Enable peer exchange
  * **LSD**: Enable local service discovery

**VPN Security:**
  * **Kill Switch**: Gluetun provides kill switch
  * **DNS Leak Protection**: VPN DNS protection
  * **IPv6 Blocking**: Block IPv6 leaks
  * **Port Forwarding**: VPN port forwarding

===== Integration with Media Stack =====

**Sonarr/Radarr Integration:**
```yaml
# In Sonarr/Radarr settings
Download Client: qBittorrent
Host: qbittorrent  # Container name
Port: 8080
Username: your-username
Password: your-password
Category: sonarr  # Use categories for organization
```

**Category Setup:**
  * **sonarr**: For TV show downloads
  * **radarr**: For movie downloads
  * **manual**: For manual downloads
  * **books**: For book downloads

**Path Mapping:**
  * **/downloads/complete/sonarr**: TV shows
  * **/downloads/complete/radarr**: Movies
  * **/downloads/complete/manual**: Manual downloads

===== Monitoring & Maintenance =====

**Health Checks:**
```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080"]
  interval: 30s
  timeout: 10s
  retries: 3
```

**Log Monitoring:**
```bash
# View qBittorrent logs
docker logs qbittorrent

# View Gluetun logs (VPN)
docker logs gluetun
```

**Performance Monitoring:**
  * **Download Speed**: Monitor download/upload speeds
  * **Connection Count**: Track peer connections
  * **Disk I/O**: Monitor disk usage
  * **Memory Usage**: Track memory consumption

===== Troubleshooting =====

**VPN Connection Issues:**
```bash
# Check VPN status
docker exec gluetun sh -c "curl -s ifconfig.me"

# Verify Gluetun is running
docker ps | grep gluetun

# Check Gluetun logs
docker logs gluetun | grep -i wireguard
```

**WebUI Access Issues:**
  * **Port Mapping**: Verify port 8080 is mapped in Gluetun
  * **Network Mode**: Confirm `network_mode: "service:gluetun"`
  * **Firewall**: Check firewall rules
  * **Traefik**: Verify Traefik routing

**Download Problems:**
  * **Port Forwarding**: Check if VPN supports port forwarding
  * **Speed Limits**: Remove artificial speed limits
  * **Tracker Issues**: Check tracker status
  * **Peer Connections**: Verify peer connectivity

**Common Issues:**
  * **No Downloads**: Check VPN connection and port forwarding
  * **Slow Speeds**: Verify VPN server selection and speed
  * **Connection Errors**: Check firewall and network settings
  * **Authentication**: Verify username/password credentials

**Troubleshooting Steps:**
  1. **Check VPN**: Verify Gluetun is connected
  2. **Test Access**: Access WebUI directly
  3. **Check Logs**: Review container logs
  4. **Verify Ports**: Confirm port mappings
  5. **Test Downloads**: Try a known working torrent

===== Backup & Recovery =====

**Configuration Backup:**
```bash
# Backup qBittorrent configuration
docker run --rm \
  -v qbittorrent-config:/config \
  -v $(pwd)/backup:/backup \
  busybox tar czf /backup/qbittorrent-config.tar.gz /config
```

**Download Recovery:**
  * **Resume Downloads**: qBittorrent auto-resumes
  * **Torrent Files**: Backup .torrent files
  * **Fast Resume**: Use fast resume data
  * **Re-add Torrents**: Re-add from backup

**Migration:**
  1. **Stop Container**: Stop qBittorrent
  2. **Backup Config**: Backup configuration directory
  3. **Restore Config**: Restore to new location
  4. **Update Paths**: Update download paths if changed
  5. **Start Container**: Restart qBittorrent

===== Best Practices =====

**VPN Usage:**
  * **Dedicated Server**: Use VPN server optimized for P2P
  * **Port Forwarding**: Enable port forwarding when available
  * **Kill Switch**: Always use VPN kill switch
  * **IP Rotation**: Rotate VPN servers periodically

**Download Management:**
  * **Category Organization**: Use categories for organization
  * **Speed Limits**: Set reasonable speed limits
  * **Queue Management**: Limit concurrent downloads
  * **Disk Space**: Monitor available disk space

**Security:**
  * **Strong Passwords**: Use strong WebUI passwords
  * **IP Restrictions**: Limit WebUI access
  * **Regular Updates**: Keep qBittorrent updated
  * **VPN Always**: Never disable VPN routing

**Performance:**
  * **Resource Allocation**: Appropriate CPU/memory limits
  * **Disk I/O**: Use fast storage for downloads
  * **Network Optimization**: Optimize VPN server selection
  * **Cache Settings**: Optimize disk cache settings

===== Advanced Configuration =====

**qBittorrent.conf Settings:**
```ini
[Preferences]
WebUI\Username=your-username
WebUI\Password_PBKDF2="encrypted-password"
WebUI\Port=8080
Downloads\SavePath=/downloads
Downloads\TempPath=/downloads/temp
```

**API Usage:**
```bash
# Get torrent list
curl -u username:password "http://localhost:8080/api/v2/torrents/info"

# Add magnet link
curl -X POST \
  -u username:password \
  -d "urls=magnet:?..." \
  http://localhost:8080/api/v2/torrents/add
```

**Integration Scripts:**
```bash
#!/bin/bash
# Auto-organize completed downloads
QB_HOST="http://localhost:8080"
QB_USER="username"
QB_PASS="password"

# Get completed torrents
completed=$(curl -s -u $QB_USER:$QB_PASS "$QB_HOST/api/v2/torrents/info?filter=completed")

# Process completed torrents
# Add your organization logic here
```

qBittorrent provides a powerful, privacy-focused torrent downloading solution that integrates seamlessly with your media automation stack while maintaining security through VPN routing.

**Next:** Explore [[services:media-management:start|Media Management Services]] or return to [[services:media:start|Media Services Overview]].