Manage qBittorrent as PMSS-controlled install — version pinning and security control

[MagnaCapax]

Summary

Transition qBittorrent from an apt-installed package to a fully PMSS-managed install with version pinning and security control, following the same model used for rtorrent (compiled from source with version targets per Debian release).

Current State

Installation: qBittorrent is installed as qbittorrent-nox via apt-get install -y as part of the media/network package set in scripts/lib/update/apps/packages/system.php (line 47). There is no dedicated qBittorrent installer script -- it is bundled with ~50 other packages in the media/network package installer function.

No version control. PMSS installs whatever version Debian's apt repos provide:

• Debian 10 (buster): qBittorrent 4.1.5
• Debian 11 (bullseye): qBittorrent 4.3.2
• Debian 12 (bookworm): qBittorrent 4.5.2

Latest stable qBittorrent is 5.x series. The gap between Debian-shipped versions and upstream is significant and growing.

No upgrade path. The package set installer is idempotent at the package level (apt skips already-installed packages) but never upgrades. A Debian 10 server installed two years ago will still run qBittorrent 4.1.5 with no path to update without a full OS upgrade.

User management: Per-user config provisioned by scripts/lib/user/qbittorrent.php (random port, template-based config). Watchdog cron scripts/cron/checkQbittorrentInstances.php keeps instances running. Password hashing uses PBKDF2-HMAC-SHA512 (properly implemented in scripts/lib/user/passwords.php).

Systemd hardening: The system-wide qbittorrent-nox unit is stopped, disabled, and masked by scripts/lib/update/services/systemd.php (line 130). Only per-user instances run.

Motivation

Security Control

qBittorrent has had security-relevant changes across versions:

• WebUI authentication improvements
• CSRF protections
• API access control changes
• TLS/certificate handling fixes

With apt-installed packages, PMSS cannot patch or upgrade qBittorrent independently of the OS release cycle. A critical CVE in qBittorrent would require waiting for Debian to package the fix or performing manual intervention on every server.

Feature Parity with rtorrent

rtorrent is fully managed by PMSS (scripts/lib/update/apps/rtorrent.php):

• Version-pinned per Debian release (0.9.6 for Debian 9, 0.9.8-udns for Debian 10+)
• Compiled from source with custom patches (udns, posix-fallocate)
• SHA256-verified tarballs from Pulsed Media mirrors
• Idempotent version check (only rebuilds if running version differs from target)
• Template reload and instance restart after upgrade

Deluge is being moved to the same model (see related issue for Deluge managed install). qBittorrent should follow for consistency and security control across all torrent clients.

Version Freshness

Users expect current software. The gap between Debian repo versions and upstream stable is:

Debian	Ships	Current Stable	Gap
10	4.1.5	5.x	~3 major versions behind
11	4.3.2	5.x	~2 major versions behind
12	4.5.2	5.x	~1 major version behind

The qBittorrent 5.x series includes significant improvements: better memory management, Qt6 support, improved Web UI, and protocol enhancements.

Proposed Approach

Option A: Compile from Source (Recommended)

Follow the rtorrent pattern exactly:

1. Fetch pinned source tarballs from upstream or Pulsed Media mirrors
2. Verify SHA256 checksums
3. Compile with cmake (qBittorrent 4.4+ uses CMake)
4. Install to /usr/local/bin/qbittorrent-nox
5. Version check: compare running version against target, only rebuild when needed

Build dependencies:

• cmake (>= 3.16)
• libboost-dev (>= 1.71)
• libtorrent-rasterbar-dev (>= 2.0 for qBittorrent 5.x; >= 1.2 for 4.x)
• qt6-base-dev (for qBittorrent 5.x) or qtbase5-dev (for 4.x)
• libssl-dev, zlib1g-dev, pkg-config

Compile time concern: qBittorrent + Qt + libtorrent-rasterbar compilation is significantly heavier than rtorrent. Could take 20-60 minutes on typical seedbox hardware. This is manageable for initial install but affects update.php runtime.

Option B: Static Binary Distribution

Build once on a build server, distribute pre-compiled static binary:

1. Build qBittorrent-nox with static linking on a build server
2. Publish to Pulsed Media package mirror (like rtorrent tarballs)
3. Download + SHA256 verify + install to /usr/local/bin/
4. Much faster deployment (download vs compile)

This is cleaner but requires maintaining a build pipeline.

Option C: PPA or Third-Party Repo

Use the qBittorrent PPA or nightly builds repo:

• Faster to implement than source compilation
• But: trusts a third-party package source
• And: still depends on someone else's release schedule

Not recommended -- defeats the purpose of managed installs.

Dependencies to Investigate

• libtorrent-rasterbar version: qBittorrent 5.x requires libtorrent-rasterbar >= 2.0. Debian 10 ships 1.1.x. May need to compile libtorrent-rasterbar from source as well (increasing complexity)
• Qt version: qBittorrent 5.x prefers Qt6; fallback to Qt5 possible but may drop Qt5 support in future. Debian 10 ships Qt 5.11, Debian 12 ships Qt 6.4
• CMake version: Debian 10 ships CMake 3.13 which may be too old for qBittorrent 5.x
• Realistic version targets per Debian release:
  • Debian 10: qBittorrent 4.6.x (last 4.x series, Qt5 compatible)
  • Debian 11: qBittorrent 4.6.x or 5.x (investigate Qt availability)
  • Debian 12: qBittorrent 5.x (Qt6 available)

Files Affected

• New: scripts/lib/update/apps/qbittorrent.php -- dedicated installer (does not exist yet)
• scripts/lib/update/apps/packages/system.php -- remove qbittorrent-nox from apt package list (line 47)
• scripts/cron/checkQbittorrentInstances.php -- verify binary path compatibility
• scripts/lib/user/qbittorrent.php -- config provisioning (template changes for new version?)
• scripts/lib/user/passwords.php -- password hashing (PBKDF2 format may change in 5.x)
• etc/skel/www/qbittorrent.php -- user control panel (references qbittorrent-nox binary)
• etc/skel/www/welcome.php -- checks /usr/bin/qbittorrent-nox existence (line 176, path will change to /usr/local/bin/)

Risks and Mitigations

Risk	Mitigation
Long compile times on seedbox hardware	Option B (pre-compiled binaries) or compile in screen/background
libtorrent-rasterbar version conflict with Deluge	Deluge uses Python bindings, qBittorrent uses C++ -- separate library instances possible
Qt6 not available on Debian 10/11	Pin older qBittorrent version for older Debian releases
Config format changes between major versions	Test upgrade path with existing user configs
Binary path change (/usr/bin -> /usr/local/bin)	Update welcome.php check, symlink for backward compat

Acceptance Criteria

• Dedicated scripts/lib/update/apps/qbittorrent.php installer created
• qbittorrent-nox removed from apt package list in system.php
• Version-pinned per Debian release with explicit targets
• SHA256 verification on all downloaded source/binaries
• Idempotent: running update.php twice does not reinstall if already at target version
• Existing user configs preserved and functional after upgrade
• Watchdog cron works with new binary paths
• qbittorrent-nox --version reports expected version after install
• Password hashing (PBKDF2) still works correctly with new version
• welcome.php binary detection updated for new path

---

— Sampsa Pellervoinen 🌱

[MagnaCapax]

QA Verification: PASS

Commit verified: 3b7f654

Layers Tested

L1 Structural: php -l clean on welcome.php.

L2 Happy Path: Added /usr/local/bin/qbittorrent-nox as alternative detection path alongside existing /usr/bin/qbittorrent-nox. The qBittorrent section on the welcome page now appears regardless of installation method (apt vs source-compiled).

L3 Adversarial: Change is strictly additive — || condition cannot break existing detection. Brings qBittorrent to parity with Deluge, which already had dual-path detection.

L4 Red Team: No custom path support (only two hardcoded paths), but this matches PMSS conventions. No version detection added (not in scope).

Caveat

This commit fixes welcome page detection only. The broader #214 scope (qBittorrent managed install, source compilation, version pinning) is not yet implemented.

• Test: PASS