Differences

This shows you the differences between two versions of the page.

--- automation:qbit [2025/12/20 17:25] – created - external edit 127.0.0.1
+++ automation:qbit [2025/12/20 18:02] (current) – privacyl0st
@@ Line 1: / Line 1: @@
+====== qBittorrent Configuration Guide ======
+qBittorrent is the **acquisition workhorse** of the Trash Panda automation ecosystem. While any reputable torrent client can function in this role, qBittorrent is recommended due to its stability, predictable behavior, strong API support, and mature feature set that integrates cleanly with the ARR suite.
+This page covers **conceptual configuration and performance-sensitive settings** for qBittorrent running natively on Ubuntu within the Automation / Acquisition VM. Naming conventions, category mapping, and ARR-side configuration are covered in their respective guides.
+===== Why qBittorrent =====
+qBittorrent is recommended for several pragmatic reasons:
+  * Fully open-source and actively maintained
+  * No ads, bundled junk, or opaque behaviors
+  * Strong Web UI with full API support
+  * Predictable disk I/O under automation
+  * Explicit VPN interface binding support
+  * Excellent compatibility with Sonarr, Radarr, and Prowlarr
+Most importantly, qBittorrent behaves **consistently under unattended operation**, which is mandatory for a set-it-and-forget-it system.
+===== Role in the Automation Ecosystem =====
+qBittorrent’s responsibilities are intentionally narrow:
+  * Receive approved torrents from Sonarr/Radarr
+  * Download content efficiently and safely
+  * Hand off completed data cleanly
+  * Remain invisible the rest of the time
+It should never:
+  * Rename media
+  * Decide where final media lives
+  * Compete for system resources unnecessarily
+===== Installation Model =====
+  * Installed natively on Ubuntu (no Docker)
+  * Runs on the Automation / Acquisition VM
+  * All internet-bound traffic traverses the VPN
+  * Local resources remain reachable via LAN routing
+This guide assumes qBittorrent is already installed and reachable via its Web UI.
+===== VPN Binding (CRITICAL) =====
+qBittorrent **must be bound to the VPN interface**.
+Relevant configuration variables:
+  * ''Session\\InterfaceName=NordLynx''
+  * ''Session\\InterfaceAddress=0.0.0.0''
+  * ''Session\\ReannounceWhenAddressChanged=true''
+Why this matters:
+  * Prevents traffic leaks if the VPN drops
+  * Ensures torrents never exit via a physical NIC
+  * Forces qBittorrent offline if the tunnel disappears
+Binding to ''Any'' or a physical interface defeats the purpose of the VPN. If the VPN goes down, qBittorrent should stop transferring immediately — that is **intentional behavior**.
+===== Network & Connection Performance =====
+Your configuration emphasizes **high download concurrency with controlled upload pressure**.
+Key performance-impacting settings:
+  * ''Session\\MaxConnections=500''
+  * ''Session\\MaxConnectionsPerTorrent=200''
+  * ''Session\\ConnectionSpeed=50''
+  * ''Session\\MaxActiveDownloads=10''
+  * ''Session\\MaxActiveUploads=1''
+  * ''Session\\MaxUploads=1''
+  * ''Session\\MaxUploadsPerTorrent=1''
+Design intent:
+  * Allow many peers for fast swarm convergence
+  * Aggressively limit upload to preserve bandwidth
+  * Favor completion over long-lived seeding
+  * Reduce contention with other services
+This configuration prioritizes **fast acquisition without saturating upstream bandwidth**.
+===== Queueing & Torrent Lifecycle =====
+Queueing is enabled and aggressively tuned.
+Relevant settings:
+  * ''Session\\QueueingSystemEnabled=true''
+  * ''Session\\IgnoreSlowTorrentsForQueueing=true''
+  * ''Session\\SlowTorrentsDownloadRate=512''
+  * ''Session\\SlowTorrentsUploadRate=10''
+  * ''Session\\SlowTorrentsInactivityTimer=180''
+Effect:
+  * Slow or stalled torrents are deprioritized
+  * Active slots are reused efficiently
+  * The system avoids getting “stuck” on bad releases
+This is essential for automation where human intervention is rare.
+===== Disk I/O & Cache Optimization =====
+Disk behavior is one of the largest performance differentiators in automated systems.
+Key disk-related settings:
+  * ''Session\\DiskCacheSize=1024''
+  * ''Session\\DiskIOReadMode=DisableOSCache''
+  * ''Session\\DiskIOWriteMode=DisableOSCache''
+  * ''Session\\AsyncIOThreadsCount=8''
+  * ''Session\\PieceExtentAffinity=true''
+Why these matter:
+  * Large internal cache reduces disk thrashing
+  * Disabling OS cache avoids double-buffering
+  * Async I/O threads increase parallelism
+  * Piece extent affinity improves sequential writes
+Combined, these settings produce **predictable, sustained throughput** rather than bursty I/O that can disrupt other services.
+===== Filesystem Layout & Hygiene =====
+qBittorrent uses separate directories for incomplete and completed data.
+Relevant settings:
+  * ''Session\\TempPathEnabled=true''
+  * ''Session\\TempPath=/mnt/w/Incomplete''
+  * ''Session\\DefaultSavePath=/mnt/w/Complete''
+Benefits:
+  * Clear separation of transient and stable data
+  * Easier troubleshooting
+  * Cleaner handoff to ARRs
+Excluded file patterns:
+  * ''Session\\ExcludedFileNamesEnabled=true''
+  * ''Session\\ExcludedFileNames=*.torrent, *.url, *.html, *.txt, *sample*, *.nfo, *.zip, *.rar, *.7z, *.iso''
+This prevents junk files from polluting downstream imports.
+===== Bandwidth Control =====
+Upload limits are deliberately conservative.
+Key values:
+  * ''Session\\GlobalUPSpeedLimit=25600''
+  * ''Session\\AlternativeGlobalUPSpeedLimit=1''
+  * ''Session\\UseAlternativeGlobalSpeedLimit=false''
+Rationale:
+  * Protects upstream bandwidth
+  * Avoids saturating VPN tunnels
+  * Keeps API communication responsive
+Downloads are intentionally less restricted, as acquisition speed is prioritized.
+===== Web UI Access (SECURITY) =====
+Web UI is enabled for internal management only.
+Relevant settings:
+  * ''WebUI\\Enabled=true''
+  * ''WebUI\\LocalHostAuth=true''
+Security posture:
+  * Web UI must remain LAN-only
+  * Never expose via reverse proxy
+  * Never expose to WAN
+  * Use firewall rules to enforce access
+Automation nodes should not be externally interactive.
+===== Integration with the ARR Suite =====
+ARRs interact with qBittorrent via API:
+  * Categories control routing
+  * Pause/resume is ARR-driven
+  * Completion triggers import workflows
+qBittorrent should remain **policy-free** and let the ARRs orchestrate behavior.
+===== Logging & Stability =====
+Logging is enabled but constrained.
+Relevant settings:
+  * ''FileLogger\\Enabled=true''
+  * ''FileLogger\\Backup=true''
+  * ''FileLogger\\DeleteOld=true''
+  * ''FileLogger\\MaxSizeBytes=66560''
+  * ''FileLogger\\Age=3''
+This ensures:
+  * Sufficient forensic data when debugging
+  * No unbounded log growth
+  * Minimal disk overhead
+===== Design Philosophy Recap =====
+qBittorrent in this ecosystem is:
+  * VPN-bound
+  * Disk-efficient
+  * Upload-conservative
+  * Automation-driven
+  * Operationally boring
+If you notice it running, something else is broken.
+When it’s tuned correctly, it quietly feeds the system and disappears into the background — exactly as intended.