¶ What is qBittorrent?
qBittorrent is a free and open-source software that aims to provide the same features as µTorrent, such as polished user interface, no ads, search engine, torrent creation tool and more. It runs on all major platforms (Windows, Linux, macOS, FreeBSD, OS/2) and supports many Bittorrent extensions.
¶ Installation
services:
qbittorrent:
container_name: qbittorrent
image: ghcr.io/hotio/qbittorrent
restart: unless-stopped
ports:
- 8080:8080
environment:
- PUID=568
- PGID=568
- UMASK=002
- TZ=America/New_York
- WEBUI_PORTS=8080/tcp,8080/udp
- VPN_ENABLED=true
- VPN_CONF=wg0
- VPN_PROVIDER=generic
- VPN_LAN_NETWORK=10.99.0.0/24
- VPN_LAN_LEAK_ENABLED=false
- VPN_EXPOSE_PORTS_ON_LAN=
- VPN_AUTO_PORT_FORWARD=true
- VPN_AUTO_PORT_FORWARD_TO_PORTS=
- VPN_FIREWALL_TYPE=auto
- VPN_HEALTHCHECK_ENABLED=false
- VPN_NAMESERVERS=
- PRIVOXY_ENABLED=false
cap_add:
- NET_ADMIN
sysctls:
- net.ipv4.conf.all.src_valid_mark=1
- net.ipv6.conf.all.disable_ipv6=1
volumes:
- /mnt/tank/configs/qbittorrent:/config
- /mnt/tank/media:/media
This qBittorrent container is from hotio and uses a Wireguard VPN to protect traffic.
| Variable | Value |
|---|---|
VPN_CONF |
With VPN_CONF you can set the name used for your WireGuard config. There needs to be a file wg0.conf located in /config/wireguard for the VPN to start. |
VPN_LAN_NETWORK |
The environment variable VPN_LAN_NETWORK can be set to for example 192.168.1.0/24, 192.168.1.0/24,192.168.44.0/24, so you can get access to the webui or other additional ports. If for example you were to pick 192.168.0.0/24, every device with an ip in the range 192.168.0.0 - 192.168.0.255 on your LAN is allowed access to the webui. |
VPN_EXPOSE_PORTS_ON_LAN |
If you need to expose ports on your LAN you can use VPN_EXPOSE_PORTS_ON_LAN. For example VPN_EXPOSE_PORTS_ON_LAN=7878/tcp,9117/tcp, will block those ports on the vpn interface, so that there’s no risk that they might be exposed to the world and allow access to them from your LAN. Some images also have a WEBUI_PORTS environment variable that does basically the same for the vpn part. For those apps that support it, it’ll also change the port on which the app runs. |
VPN_AUTO_PORT_FORWARD |
Auto retrieve a forwarded port and configure the supported app if set to true or if you can manually request/set a forwarded port in the VPN provider’s web interface, fill in the port number (just the number). |
VPN_AUTO_PORT_FORWARD_TO_PORTS |
Adds a redirect for the forwarded port from your vpn provider to the internal port on which the app runs, ports in this list are also not blocked on the wireguard interface, so this var is also useful if you want to expose a port on both your LAN and VPN. Values like 32400/tcp will use the port from VPN_AUTO_PORT_FORWARD to create the redirect or if set to true the forwarded port from pia/proton. Use 3000@3001/tcp,3002@3003/tcp syntax for extra static redirects. The only known usecase as of right now is Plex and exposing it on the VPN with a non configurable forwarded port, because it’s not possible to run Plex on anything else but 32400. |
VPN_FIREWALL_TYPE |
Possible values are auto, legacy or nftables. The default is auto, this will try to use the most modern method available. If this doesn’t work, you can try forcing it to legacy or nftables. |
VPN_HEALTHCHECK_ENABLED |
This is almost never needed, only in very rare cases (mostly when using PIA). |
VPN_NAMESERVERS |
Possible values are wg, 8.8.8.8 or 1.1.1.1@853#cloudflare-dns.com seperated by a ,. The value wg will use the nameservers from the wg0.conf file. The value 8.8.8.8 is to use a plain old nameserver. The value 1.1.1.1@853#cloudflare-dns.com will add a DNS over TLS nameserver, this will override all other regular nameservers. Leaving the variable empty will allow Unbound to work in recursive mode. |
For more info on these values, look here
When you start this container it will fail until you add the VPN config file. See the Example Wireguard section below
There have been widespread reports of issues with this container. The main one being it will work for awhile then go down, or the port will be open then close on its own after 10 minutes or less. As such, I am not recommending this for the time being. Use at your own risk - no support will be answered for issues with this container
In Discord many people have said this container fixes the Gluetun issue. I have not tested it, but if you are using Gluetun and you get randomly discconnected every so often, try this method: qSticky.
services:
gluetun:
cap_add:
- NET_ADMIN
container_name: gluetun
devices:
- /dev/net/tun:/dev/net/tun
environment:
- TZ=America/New_York
- VPN_SERVICE_PROVIDER=custom
- VPN_TYPE=wireguard
- WIREGUARD_ENDPOINT_IP=
- WIREGUARD_ENDPOINT_PORT=
- WIREGUARD_PUBLIC_KEY=
- WIREGUARD_PRIVATE_KEY=
- WIREGUARD_PRESHARED_KEY=
- WIREGUARD_ADDRESSES=
- FIREWALL_VPN_INPUT_PORTS=6881
- SERVER_COUNTRIES= #optional
- DNS_ADDRESS= #optional
image: qmcgaw/gluetun:latest
ports:
- '8080:8080'
- 6881:6881/udp
- 6881:6881/tcp
restart: unless-stopped
qbittorrent:
container_name: qbittorrent
depends_on:
- gluetun
environment:
- PUID=568
- PGID=568
- TZ=America/New_York
- WEBUI_PORT=8080
image: linuxserver/qbittorrent:latest
network_mode: service:gluetun
restart: unless-stopped
volumes:
- /mnt/tank/configs/qbittorrent:/config
- /mnt/tank/media:/media
| Variable | Value |
|---|---|
VPN_SERVICE_PROVIDER |
This is setup as custom to accommodate any provider but there are many more providers. |
FIREWALL_VPN_INPUT_PORTS |
Comma separated list of ports |
SERVER_COUNTRIES |
Comma separated list of countries |
To add port forwarding, on the FIREWALL_VPN_INPUT_PORTS add a comma with no space and then the port which you want to forward. Make sure to make the change in the qbittorrent connection settings as well as shown below.
For more info on this container, look here
The qBittorrent container in the default Apps catalog on TrueNAS does not include a VPN, therefore we won’t use it. Instead, create a Custom App by clicking the 3 dot menu next to the blue Custom App button and click Deploy via YAML or follow the steps below to launch an LXC.
¶ Prerequisites
- Use TrueNAS Fangtooth 25.04 or higher
- Have a bridge built and configured (Instances → Configuration → Global Settings)
- Have a wireguard file from your VPN provider
- Make sure your folder structure follows the guide (your
mediafolder must have adownloadsfolder within it)
¶ Launch the Container
- Navigate to Instances and launch a container named
qbitwith the Ubuntu Noble image (leave all other settings default) - Run this command as
rootin the TrueNAS shell:
sudo su -c "wget https://raw.githubusercontent.com/serversathome/ServersatHome/refs/heads/main/qbit-lxc.sh && chmod +x qbit-lxc.sh && bash qbit-lxc.sh"
- Enter your
mediadataset path when prompted - Enter the contents of your wireguard config file when prompted then hit CTRL+D
Once the script has finished, it will print out the IP of the web interface as well as the username and password
¶ Example Wireguard wg0.conf File
This is an example of how your wg0.conf file should look like. If there’s a lot of extra stuff, remove it unless you know what it’s there for.
[Interface]
Address = 10.171.142.169
PrivateKey = supersecretkey
MTU = 1320
DNS = 10.128.0.1
[Peer]
PublicKey = supersecretkey
PresharedKey = supersecretkey
Endpoint = 1.2.3.4:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 15
For more clarification on these values, look here
If you are using the hotio container for qBit with a VPN this file needs to be added to
/config/wireguard(in the folder holding the qBit configuration files) before the container can run
¶ Testing Open Ports
To test if your port forward is working correctly, shell into qBit and execute:
curl ip.me
to get the IP address you are using. Then plug that IP + your port into this tool.
¶ YouTube Walkthrough
https://www.youtube.com/watch?v=WVM3Wgb290g
¶ qBittorrent Configuration
¶ Logging In
To login to the webUI, navigate to http://{serverIP}:8080. If when you first try to open the app and you receive a blank page which just says “Unauthorized”, don’t worry, you did everything correctly. Click the URL bar and hit Enter and you should be forwarded to the login screen. The default username is admin and the password is set randomly. To see it, go into the logs and look for this line:
If you are having an issue where qBit is running but you cannot reach the webUI and you are coming into your network over VPN, be sure to add the VPNs IPv4 range to the
VPN_LAN_NETWORKline in a comma separated list, no spaces
¶ Configuration Options
Click on the cog icon 
in the bar or select Tools > Options in the tool bar. I will tell you what to change tab by tab. If it is not mentioned, it is left as the default value
The Default Save Path needs to be modified to be /media/downloads if you followed the Folder Structure guide.
In the Listenting Port section, add the port given to you by AirVPN (see the AirVPN page for instructions).
Uncheck all the boxes under Connection Limits.
If you are using private trackers only, uncheck all the boxes in the Privacy grouping. If you are using public trackers, leave this section default.
Uncheck the box for Torrent Queuing.
This part is completely optional, but I highly suggest using a skin for the Web UI called VueTorrent
To get VueTorrent (I put mine in /mnt/tank/media/downloads/VueTorrent) run this command in the TrueNAS shell:
git clone --single-branch --branch latest-release https://github.com/VueTorrent/VueTorrent.git /mnt/tank/media/downloads/
In the Web UI tab, check the box for Use Alternative WebUI and enter the path of the VueTorrent folder (/media/downloads/VueTorrent).
I keep mine up to date (assuming I save it in /mnt/tank/media/downloads) by adding this command to TrueNAS in System → Advanced Settings → Cron Jobs running as root:
git -C /mnt/tank/media/downloads/VueTorrent pull
Change the Network Interface to VPN (yours might also say wg0 or tun0).
