qBittorrent on Ubuntu 24.04 on Azure User Guide

Overview

qBittorrent is a free, open source BitTorrent client that offers the features power users expect without the bloat of heavier clients. This cloudimg image runs the headless daemon, qbittorrent-nox, and exposes its full functionality through a browser based Web UI: add torrents by file, URL or magnet link, organise them into categories, control bandwidth and scheduling, use the integrated search, subscribe to RSS feeds with automatic downloading, and watch transfer progress in real time. The daemon runs as a dedicated unprivileged qbittorrent system user under a hardened systemd unit, with the Web UI bound to the loopback address 127.0.0.1:8080 behind an nginx reverse proxy on port 80. BitTorrent peer traffic uses port 6881 (TCP and UDP). The qBittorrent profile and the download library live on a dedicated Azure data disk mounted at /var/lib/qbittorrent, and a unique admin password is generated on the first boot of every VM so no shared credential ships in the image. Backed by 24/7 cloudimg support.

What is included:

• qBittorrent 4.6.3 (qbittorrent-nox) managed by systemd, serving a full Web UI
• nginx on port 80 fronting the Web UI, which is bound to the loopback address 127.0.0.1:8080
• Authentication forced for every client, including localhost, so the Web UI is never open
• A unique admin password generated on first boot and recorded in a root only file
• A dedicated Azure data disk at /var/lib/qbittorrent holding the profile and downloads
• BitTorrent peer connectivity on port 6881 (TCP and UDP)
• qbittorrent-nox.service and nginx.service as systemd units, enabled and active
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point. NSG inbound rules: allow 22/tcp from your management network for SSH, 80/tcp for the Web UI, and 6881/tcp and 6881/udp so the client can accept incoming BitTorrent peer connections. qBittorrent serves the Web UI over plain HTTP on port 80; for production, terminate TLS in front of it with your own domain (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for qBittorrent by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). After deployment, add inbound rules for the BitTorrent peer port on TCP 6881 and UDP 6881 so the client can accept incoming connections. Review the dedicated data disk on the Disks tab, then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name qbittorrent \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name qbittorrent --port 80 --priority 1010
az network nsg rule create --resource-group <your-rg> --nsg-name <your-nsg> \
  --name allow-bt-tcp --priority 1020 --protocol Tcp --destination-port-ranges 6881 --access Allow
az network nsg rule create --resource-group <your-rg> --nsg-name <your-nsg> \
  --name allow-bt-udp --priority 1030 --protocol Udp --destination-port-ranges 6881 --access Allow

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active qbittorrent-nox.service nginx.service

Both report active. qbittorrent-nox serves the Web UI on the loopback address 127.0.0.1:8080, nginx fronts it on port 80, and the BitTorrent session listens on port 6881. The profile and downloads live on the dedicated Azure data disk mounted at /var/lib/qbittorrent.

Step 5 - Retrieve your admin login

The qBittorrent Web UI admin password is generated uniquely on the first boot of your VM and written to a root only file:

sudo cat /root/qbittorrent-credentials.txt

This file contains QBITTORRENT_USERNAME, QBITTORRENT_PASSWORD and the URL to open. The username is admin. Store them somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/healthz

It returns ok. This endpoint never requires authentication, so it is safe for an Azure Load Balancer health probe.

Step 7 - Verify authentication from the command line

The Web UI forces authentication for every client, including localhost, so an unauthenticated API request is rejected. Confirm this, then log in with the per VM password and read the version back through the API:

# Secure by default: an unauthenticated API request is rejected
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/api/v2/app/version

# Log in with the per-VM password (read from the root-only file) and read the version
PW=$(sudo grep '^QBITTORRENT_PASSWORD=' /root/qbittorrent-credentials.txt | cut -d= -f2-)
JAR=$(mktemp)
curl -s -c "$JAR" -H 'Referer: http://127.0.0.1:8080' \
  --data-urlencode username=admin --data-urlencode "password=$PW" \
  http://127.0.0.1:8080/api/v2/auth/login; echo
curl -s -b "$JAR" http://127.0.0.1:8080/api/v2/app/version; echo
rm -f "$JAR"

The unauthenticated request returns 403. The login returns Ok. and sets a session cookie, and the authenticated request returns the qBittorrent version (for example v4.6.3).

Step 8 - Sign in to the Web UI

Browse to http://<vm-public-ip>/. qBittorrent shows a sign in page; enter the username admin and the password from Step 5.

Once signed in, the transfer list is the main view. A toolbar across the top adds and controls torrents, the left sidebar filters by status, category, tag and tracker, and the bottom panel shows details for the selected torrent. The status bar reports free space, the number of DHT nodes and the current transfer rates.

Step 9 - Add a torrent

Use the toolbar Add Torrent Link button (or File -> Add Torrent Link) to paste a magnet link or a torrent URL. You can set the save location, a category, the content layout and per torrent rate limits before adding. To add a .torrent file instead, use Add Torrent File. Downloads are saved to /var/lib/qbittorrent/downloads on the dedicated data disk by default.

Step 10 - Tune preferences

Open Tools -> Options to configure the client. The Connection tab sets the listening port (6881 by default), the Speed tab applies global and scheduled rate limits, the BitTorrent tab controls seeding limits and DHT, and the Web UI tab manages the interface and its credentials. Change the admin password here under Web UI -> Authentication.

Step 11 - Confirm downloads live on the dedicated disk

The qBittorrent profile, configuration and download library are stored under /var/lib/qbittorrent on the dedicated Azure data disk, so they survive OS changes and can be resized independently:

findmnt /var/lib/qbittorrent

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Maintenance

• Admin login: the per VM credentials live in /root/qbittorrent-credentials.txt. To change the password, sign in to the Web UI and use Tools -> Options -> Web UI -> Authentication.
• Listening port: the BitTorrent peer port is 6881 (TCP and UDP); open it in the NSG for incoming connections, or change it under Options -> Connection.
• Storage: all runtime state lives under /var/lib/qbittorrent on the data disk; back up that volume to protect your configuration and downloads.
• Service: the unit is qbittorrent-nox.service; after any change run sudo systemctl restart qbittorrent-nox.
• TLS: the Web UI is served over plain HTTP on port 80; front it with TLS (for example certbot with your own domain) before production use, or enable HTTPS directly under Options -> Web UI.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.