homelab-notes/qBit/qBit-notes.md

qbit-debian / qBittorrent + WireGuard Notes

Last updated: 2025-12-28

Debian VM dedicated to qBittorrent (qbittorrent-nox) with Web UI and local-only access, plus groundwork for self-hosted WireGuard.

---

Host Overview

• VM name: qbit-debian
• OS: Debian 12 (bookworm)
• Role: Headless BitTorrent client with Web UI
• Primary services:
  • qbittorrent-nox (Web UI on port 8080) [web:146]
  • WireGuard tooling installed (wireguard, wireguard-tools) [web:145][web:154]

---

qBittorrent Installation & Launch

Install qbittorrent-nox

apt update
apt install -y qbittorrent-nox

• qbittorrent-nox is the headless/server variant with a Web UI only. [web:153]

First run & legal notice workaround

Problem: first launch blocks on an interactive legal notice prompt, which leaves the process in T (stopped) state.

Workaround using screen:

apt install -y screen
pkill -9 qbittorrent-nox
screen -S qbit -d -m bash
screen -S qbit -X stuff "qbittorrent-nox\n"
sleep 2
screen -S qbit -X stuff "y\n"

After acceptance, qbittorrent-nox runs normally in the background and can later be daemonized with qbittorrent-nox -d once the legal notice has been accepted at least once. [web:153][web:150]

---

Web UI Access

Port and address

• Default Web UI port: 8080. [web:143][web:146]
• Default bind address: all interfaces (0.0.0.0), so it is reachable at:

http://<qbit-debian-IP>:8080

Example in this setup:

http://10.0.10.91:8080

Login

• Default credentials on first run:
  • Username: admin
  • Password: adminadmin [web:142]
• Change these immediately in Tools → Options → Web UI once logged in.

---

Core qBittorrent Configuration

1. Web UI security

Inside the Web UI:

• Go to Tools → Options → Web UI.
• Change:
  • Username: set custom admin user.
  • Password: set strong password.
• Keep protocol as HTTP and listen only on LAN IP; HTTPS termination can be handled later via Caddy if ever exposed externally. [web:143]

Current design choice:

• Web UI is LAN-only, accessed via private address (10.0.10.91:8080), not exposed to the public internet.
• No reverse proxy / TLS used yet; avoids CSRF and exposure concerns mentioned in containerized setups. [web:142][web:149]

2. Download locations

Within Tools → Options → Downloads:

• Default save path: pointed to VM-mounted storage (e.g. TrueNAS share), such as:

/data/Downloads

• Keep incomplete torrents in: optional subfolder, e.g.:

/data/Downloads/incomplete

• Ensure the mount has appropriate permissions for the qbittorrent-nox user to read/write; issues in other setups often stem from permission mismatches. [web:147]

3. Testing with legal Linux ISOs

Use official torrents for testing:

• Debian images and torrents: debian.org/download [web:150]
• ArchWiki and other docs confirm Web UI default at http://HOST_IP:8080 for verification. [web:146]

Add a magnet link or .torrent via Add Torrent in the Web UI and confirm files appear under /data/Downloads.

---

Process & Port Verification

Check process

ps aux | grep qbittorrent

• Healthy process should show state S or similar, not T (stopped).

Check Web UI port

ss -tlnp | grep 8080

Expected output (example):

LISTEN 0 50 *:8080 : users:(("qbittorrent-nox",pid=XXXX,fd=YY))

Confirms qbittorrent-nox is listening on port 8080 on all interfaces. [web:143][web:146]

---

WireGuard (On This VM Only – Current Status)

WireGuard is installed but not yet fully configured for production use.

Install commands used

apt update
apt install -y wireguard wireguard-tools

This pulls kernel module support and user-space tools on Debian 12. [web:145][web:154]

Planned role:

• Eventually act as self-hosted VPN endpoint for:
  • Mobile access into the home lab / TrueNAS.
  • Potential routing of qBittorrent traffic through a VPN tunnel.

Current state:

• No persistent /etc/wireguard/wg0.conf finalized yet.
• No peers configured; service not yet enabled with systemctl enable wg-quick@wg0. [web:145][web:154]

---

Design Decisions & Notes

• qBittorrent is intentionally not reverse-proxied yet; all access is via LAN IP and HTTP on port 8080 for simplicity during initial setup. [web:143][web:142]
• Legal notice for qbittorrent-nox required an interactive acceptance once; screen was used to handle this on a headless VM. [web:153][web:150]
• WireGuard is colocated on qbit-debian for now; may later be moved to a dedicated container/VM as a centralized VPN gateway.
• When/if exposing the Web UI externally, plan is to:
  • Put it behind Caddy with HTTPS and access controls.
  • Restrict exposure to VPN subnets rather than the open internet.

---