183 lines
4.8 KiB
Markdown
183 lines
4.8 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```text
|
||
http://<qbit-debian-IP>:8080
|
||
```
|
||
|
||
Example in this setup:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
/data/Downloads
|
||
```
|
||
|
||
- **Keep incomplete torrents in:** optional subfolder, e.g.:
|
||
|
||
```text
|
||
/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](https://www.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
|
||
|
||
```bash
|
||
ps aux | grep qbittorrent
|
||
```
|
||
|
||
- Healthy process should show state `S` or similar, **not** `T` (stopped).
|
||
|
||
### Check Web UI port
|
||
|
||
```bash
|
||
ss -tlnp | grep 8080
|
||
```
|
||
|
||
Expected output (example):
|
||
|
||
```text
|
||
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
|
||
|
||
```bash
|
||
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.
|
||
|
||
--- |