# 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: 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.

---