ilia/homelab-notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
homelab-notes/qBit/qBit-notes.md
ilia e6ab067641
All checks were successful
CI / skip-ci-check (push) Successful in 1m15s
Details
CI / markdown-lint (push) Successful in 1m18s
Details
CI / yaml-validate (push) Successful in 1m18s
Details
Add gpu, qbit and vikunja notes (#2) 
Reviewed-on: #2
2025-12-30 23:12:38 -05:00

4.8 KiB
Raw Permalink Blame History

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.