qBittorrent Self-Hosted BitTorrent Client on AWS 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 data volume mounted at /var/lib/qbittorrent, and a unique admin password is generated on the first boot of every instance so no shared or default 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 well known admin/adminadmin default login is never reachable
• A unique admin password generated on first boot and recorded in a root-only file
• A dedicated data volume 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 load-balancer health checks
• 24/7 cloudimg support

Prerequisites

An AWS account, an EC2 key pair in the target region, and a VPC with a public subnet. m5.large (2 vCPU / 8 GiB RAM) is the recommended instance type. Security group inbound: allow 22/tcp from your management network for SSH, 80/tcp for the Web UI, and 6881/tcp and 6881/udp for BitTorrent peer connections.

Step 1 - Launch the AMI

Subscribe to the listing in AWS Marketplace, choose Continue to Launch, and launch through the EC2 console or the AWS CLI. Select the m5.large instance type, your key pair, and a security group that opens ports 22, 80 and 6881.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <security-group-id> \
  --subnet-id <subnet-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=qbittorrent}]'

Step 2 - Connect to your instance

Connect over SSH as the default login user for the OS variant you launched. This listing may ship more than one OS variant; use the matching login user below.

Step 3 - Confirm the services are running

qBittorrent runs behind nginx, with a one-shot first-boot service that mints the per-instance admin password. Confirm the two long-running services are healthy:

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

Both report active.

Step 4 - Verify the stack and endpoints

Confirm the running qBittorrent version, that the Web UI is bound to the loopback interface only, that the BitTorrent session is listening on port 6881, that the unauthenticated health probe answers, and that the Web UI refuses anonymous API access:

qbittorrent-nox --version
ss -tln | grep 127.0.0.1:8080
ss -tln | grep 6881
curl -s -o /dev/null -w 'healthz: HTTP %{http_code}\n' http://127.0.0.1/healthz
curl -s -o /dev/null -w 'unauthenticated API: HTTP %{http_code}\n' http://127.0.0.1:8080/api/v2/app/version

The Web UI is bound to 127.0.0.1:8080 only, port 6881 is listening for peers, /healthz returns 200, and the unauthenticated API returns 403 because authentication is enforced on every request.

Step 5 - Read your per-instance admin credential

The image ships no shared or default login. On first boot a unique admin password is generated for this instance and written to a root-only file. Read it, confirming the file permissions and the resolved URL:

sudo stat -c '%a %U:%G' /root/qbittorrent-credentials.txt
sudo grep -E '^QBITTORRENT_(USERNAME|URL)=' /root/qbittorrent-credentials.txt

The file is 600 root:root, QBITTORRENT_USERNAME is your admin username (admin), and QBITTORRENT_URL is the address to open in your browser. Run sudo cat /root/qbittorrent-credentials.txt to also see the password.

Step 6 - Prove the login round-trip from the command line

Confirm the per-instance password authenticates against the Web UI API and returns a valid session, exactly as your browser will:

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 login returns Ok. and sets a session cookie, and the authenticated version call reports the running qBittorrent version (for example v4.6.3).

Step 7 - Sign in to the Web UI

Browse to http://<instance-public-ip>/ (the value of QBITTORRENT_URL) and sign in with the admin username and password from the credentials file. Authentication is enforced on every request, so there is no anonymous access.

Step 8 - Add a torrent and watch it transfer

Click the Add Torrent Link icon (top left) to paste a magnet link or a .torrent URL, or Add Torrent File to upload a .torrent. The transfers view lists every torrent with its progress, status, seeds, peers and speeds, and the sidebar filters by status, category and tag. Downloads are saved to the dedicated data volume at /var/lib/qbittorrent/downloads.

Step 9 - Review the secure Web UI settings

Open Tools -> Options -> Web UI to review the security posture. The Web UI is bound to 127.0.0.1:8080, authentication is enforced (the Bypass authentication for clients on localhost option is left off), clickjacking and CSRF protection are enabled, and you can change the admin password here at any time.

Step 10 - Tune preferences

The Options dialog exposes qBittorrent's full configuration - download locations and behaviour, connection and port settings, global and per-torrent speed limits, BitTorrent privacy options, and RSS automation - all applied instantly from the browser with no configuration files to edit.

Maintenance

• Downloads and profile: the qBittorrent profile and the download library live on the dedicated data volume at /var/lib/qbittorrent (config at /var/lib/qbittorrent/qBittorrent/config/qBittorrent.conf, downloads under /var/lib/qbittorrent/downloads). Resize the volume independently of the OS disk as your library grows.
• Credential: the per-instance admin password is in /root/qbittorrent-credentials.txt. To rotate it, change it from Tools -> Options -> Web UI in the browser.
• Ports: the Web UI is served on port 80 (nginx). BitTorrent peer traffic uses port 6881 (TCP and UDP); open it in the security group for the best connectivity.
• Restart: sudo systemctl restart qbittorrent-nox.service nginx.service if you need to bounce the stack.
• 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.

This image packages the open source qBittorrent software (GNU General Public License v2) for convenient deployment on AWS. cloudimg is not affiliated with, endorsed by, or sponsored by the qBittorrent project.