qBittorrent with GlueTUN VPN in Container Manager on a Synology NAS

Last updated on 15 January 2025

What are qBittorrent and GlueTUN?

qBittorrent is a torrent downloader and GlueTUN is the Docker container that has pre-configured VPN connections for numerous VPN providers.

Before you start check the GlueTUN Wiki to see if your provider is on the supported list.

Also, if you are yet to choose a provider have a look at the Reddit list of recommended suppliers as could save you a headache when trying to seed. I currently use AirVPN which has nice easy port forwarding and is P2P friendly. This is my affiliate link if you fancy signing up.

Let’s Begin

In this guide I will take you through the steps to get qBittorrent up and running in Docker and a separate GlueTUN VPN container. By having a separate container for the VPN connection we can use it in the future for other applications.

In order for you to successfully use this guide please complete the three preceding guides

• Docker Package, SSD and Memory Recommendations
  
• Step 1: Directory Setup Guide
• Step 2: Setting up a restricted Docker user
• Step 3: Setting up a Docker Bridge Network (synobridge)

Folder Setup

Let’s start by getting some folders set up for the containers to use. Open up File Station create the following.

/docker/projects/vpnproject-compose
/docker/gluetun
/docker/qbittorrent

Setting up the TUN start up script

In order for the VPN connection to work we need to make sure the TUN Interface is available to make the connection to a VPN provider. In order to ensure it is available even after a reboot we will set up a small script.

Open up Control Panel and then click on Task Scheduler

Next click on Create, Triggered Task then User Defined Script.

Enter the following:

On the Task Settings tab copy and paste the code below in the ‘User-Defined script’ section. It will look like screenshot.

#!/bin/sh -e

insmod /lib/modules/tun.ko

You can now press OK and agree to the warning message. Next run the script which will enable the TUN device.

You can now move on to the next step.

Wireguard Kernel Module (not required for OpenVPN)

The default Gluetun Wireguard setup uses the ‘Userspace’ implementation of Wireguard which requires higher CPU resources. For example a 40MiB/s download via qBittorrent uses up to 176% in CPU (1.7 Cores) on my 1821+.

By installing the appropriate Kernel Module this reduces down to 1 or 2% which frees up the CPU for other tasks.

BlackVoid.club have put together a Kernel Module for Synology which allows Gluetun to use the lower level Kernel to perform Wireguard duties make sure you drop them a thanks as this would not be possible without them!

https://www.blackvoid.club/wireguard-spk-for-your-synology-nas/

While on first glances it looks like a long installation process the page details a number of methods. I recommend having a read taking note of warnings and also if you want to build your own module it tells you how.

The TLDR is below.

1. Find your model of NAS under the correct DSM version section (If you are following this guide it will be 7.2 or above) and download the pre compiled .spk file
2. Head into Package Center and click ‘Manual Install’ on the top right and install the .spk file and untick the box to run after install
3. Reboot
4. SSH Into your NAS (Just like in the User Setup guide) and elevate yourself to root by typing sudo -i and entering your password
5. Enter this command and press enter to start up the module /var/packages/WireGuard/scripts/start

You should now be able to see the WireGuard package running in Package Center. Please note while I will try my best to support in relation to this module I may have to refer you on if it is a specific technical issue.

On to the next part.

Container Manager Project (aka Docker Compose)

Next we are going to set up a ‘Project’ in Container Manager, a project is used when you want multiple containers to all be loaded together and often rely on each other to function. In our case we want qBittorrent to load and talk to the GlueTUN VPN container.

Open up Container Manager and click on Project then on the right-hand side click ‘Create’

In the next screen we will set up our General Settings, enter the following:

OK we are now going to drop in our Docker Compose configuration (YAML) – You will find some presets below – A basic WireGuard or OpenVPN setup which covers the majority of providers, but I have also provided some standard WireGuard presets for AirVPN and ProtonVPN, select the one that is appropriate for you.

Docker Compose Presets

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8888:8888/tcp # HTTP proxy
      - 8388:8388/tcp # Shadowsocks
      - 8388:8388/udp # Shadowsocks
      - 8090:8090/tcp # port for qbittorrent
    volumes:
      - /volume1/docker/gluetun:/gluetun
    environment:
      - PUID=1234 #CHANGE_TO_YOUR_UID
      - PGID=65432 #CHANGE_TO_YOUR_GID
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - VPN_SERVICE_PROVIDER=NAMEOFYOURPROVIDER
      - VPN_TYPE=openvpn
      - OPENVPN_USER=abc
      - OPENVPN_PASSWORD=abc
      - SERVER_COUNTRIES=VPNSERVERCOUNTRY #Change based on the Wiki
      - HTTPPROXY=off #change to on if you wish to enable
      - SHADOWSOCKS=off #change to on if you wish to enable
      - FIREWALL_OUTBOUND_SUBNETS=172.20.0.0/16,192.168.0.0/24
#      - FIREWALL_VPN_INPUT_PORTS=12345
      - UPDATER_PERIOD=24h
    network_mode: synobridge
    labels:
      - com.centurylinklabs.watchtower.enable=false
    security_opt:
      - no-new-privileges:true
    restart: always
    
  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1234 #CHANGE_TO_YOUR_UID
      - PGID=65432 #CHANGE_TO_YOUR_GID
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - WEBUI_PORT=8090
      - UMASK=022
    volumes:
      - /volume1/docker/qbittorrent:/config
      - /volume1/data/torrents:/data/torrents
    network_mode: service:gluetun # run on the vpn network
    security_opt:
      - no-new-privileges:true
    restart: always

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8888:8888/tcp # HTTP proxy
      - 8388:8388/tcp # Shadowsocks
      - 8388:8388/udp # Shadowsocks
      - 8090:8090/tcp # port for qbittorrent
    volumes:
      - /volume1/docker/gluetun:/gluetun
    environment:
      - PUID=1234 #CHANGE_TO_YOUR_UID
      - PGID=65432 #CHANGE_TO_YOUR_GID
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - VPN_SERVICE_PROVIDER=NAMEOFYOURPROVIDER
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=YOUR-PRIVATE-KEY
      - WIREGUARD_PRESHARED_KEY
      - WIREGUARD_ADDRESSES=10.x.x.x
      - SERVER_COUNTRIES=VPNSERVERCOUNTRY #Change based on the Wiki
      - HTTPPROXY=off #change to on if you wish to enable
      - SHADOWSOCKS=off #change to on if you wish to enable
      - FIREWALL_OUTBOUND_SUBNETS=172.20.0.0/16,192.168.0.0/24
#      - FIREWALL_VPN_INPUT_PORTS=12345
      - UPDATER_PERIOD=24h
    network_mode: synobridge
    labels:
      - com.centurylinklabs.watchtower.enable=false
    security_opt:
      - no-new-privileges:true
    restart: always
    
  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1234 #CHANGE_TO_YOUR_UID
      - PGID=65432 #CHANGE_TO_YOUR_GID
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - WEBUI_PORT=8090
      - UMASK=022
    volumes:
      - /volume1/docker/qbittorrent:/config
      - /volume1/data/torrents:/data/torrents
    network_mode: service:gluetun # run on the vpn network
    security_opt:
      - no-new-privileges:true
    restart: always

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8888:8888/tcp # HTTP proxy
      - 8388:8388/tcp # Shadowsocks
      - 8388:8388/udp # Shadowsocks
      - 8090:8090/tcp # port for qbittorrent
    volumes:
      - /volume1/docker/gluetun:/gluetun
    environment:
      - VPN_SERVICE_PROVIDER=airvpn
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=
      - WIREGUARD_PRESHARED_KEY=
      - WIREGUARD_ADDRESSES=
      - TZ=Europe/London
      - PUID=1234
      - PGID=65432
      - HTTPPROXY=off
      - SHADOWSOCKS=off
      - FIREWALL_OUTBOUND_SUBNETS=172.20.0.0/16,192.168.0.0/24
      - FIREWALL_VPN_INPUT_PORTS=12345
      - UPDATER_PERIOD=24h
    network_mode: synobridge
    labels:
      - com.centurylinklabs.watchtower.enable=false
    security_opt:
      - no-new-privileges:true
    restart: always

  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1234 #CHANGE_TO_YOUR_UID
      - PGID=65432 #CHANGE_TO_YOUR_GID
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - WEBUI_PORT=8090
      - UMASK=022
    volumes:
      - /volume1/docker/qbittorrent:/config
      - /volume1/data/torrents:/data/torrents
    network_mode: service:gluetun # run on the vpn network
    security_opt:
      - no-new-privileges:true
    restart: always

ProtonVPN WireGuard Preset

This is the correct setup for using Proton VPN it makes use of the ‘custom’ compose in order to use WireGuard and also the correct port forwarding settings.

Thanks to Geebru on Discord for the settings and screenshots

1. Use any name you like
2. Select GNU/Linux
3. Turn on the following
   • Block malware only
   • Moderate NAT
   • NAT-PMP (Port Forwarding)
   • VPN Accelerator
4. Select a server that is physcially close to you and low usage
   • Ensure its a P2P server (double left and right arrows)

You can then layer in the WireGuard details it provides you into the compose below.

(Note Proton Wireguard keys expire after 12 months so you will need to renew them after that period of time)

YAML

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8888:8888/tcp # HTTP proxy
      - 8388:8388/tcp # Shadowsocks
      - 8388:8388/udp # Shadowsocks
      - 8090:8090/tcp # port for qbittorrent
    volumes:
      - /volume1/docker/gluetun:/gluetun
      - /volume1/docker/gluetun/auth:/gluetun/auth
    environment:
      - PUID=1234 #CHANGE_TO_YOUR_UID
      - PGID=65432 #CHANGE_TO_YOUR_GID
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - VPN_SERVICE_PROVIDER=custom
      - VPN_TYPE=wireguard
      - WIREGUARD_ENDPOINT_IP=xxx.xx.xx.xx
      - WIREGUARD_ENDPOINT_PORT=51820
      - WIREGUARD_PUBLIC_KEY=
      - WIREGUARD_PRIVATE_KEY=
      - WIREGUARD_ADDRESSES=xx.x.x.x/32
      - VPN_PORT_FORWARDING=on
      - VPN_PORT_FORWARDING_PROVIDER=protonvpn
      - HTTPPROXY=off
      - SHADOWSOCKS=off
      - FIREWALL_OUTBOUND_SUBNETS=172.20.0.0/16,192.168.4.0/24
      - UPDATER_PERIOD=24h
    network_mode: synobridge
    labels:
      - com.centurylinklabs.watchtower.enable=false
    security_opt:
      - no-new-privileges:true
    restart: always
      
  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1234 #CHANGE_TO_YOUR_UID
      - PGID=65432 #CHANGE_TO_YOUR_GID
      - TZ=Europe/London #CHANGE_TO_YOUR_TZ
      - WEBUI_PORT=8090
      - UMASK=022
      - DOCKER_MODS=ghcr.io/t-anc/gsp-qbittorent-gluetun-sync-port-mod:main #GSP MOD SEE STEPS
      - GSP_GTN_API_KEY= "" #GSP MOD SEE STEPS
      - GSP_SLEEP=120 #GSP MOD SEE STEPS
      - GSP_MINIMAL_LOGS=false #GSP MOD SEE STEPS
      - GSP_QBT_USERNAME= #GSP MOD SEE STEPS
      - GSP_QBT_PASSWORD= #GSP MOD SEE STEPS
      - GSP_QBT_ADDR="http://nasip:8090"
    volumes:
      - /volume1/docker/qbittorrent:/config
      - /volume1/data/torrents:/data/torrents
    network_mode: service:gluetun # run on the vpn network
    security_opt:
      - no-new-privileges:true
    restart: always

Proton VPN Port Forwarding Extra Steps

Previously the GSP Mod was in the FAQ, it is now part of this compose as it makes sense to just include it in your setup otherwise you are missing out on the Port Forwarding proton provides.

Lets do a few extra steps to get it running this won’t take long!

GlueTUN Control Server

As of version 3.41 of GlueTUN the control server requires authentication to access it and send commands, so we need to set up a config file to ensure GSP can query the available ports.

Create a new folder /docker/gluetun/auth and then using a text editor create a file named config.toml within that path.

config.toml

[[roles]]
name = "t-anc/GSP-Qbittorent-Gluetun-sync-port-mod"
routes = ["GET /v1/openvpn/portforwarded"]
auth = "apikey"
# This is an example, generate your own. See bellow.
apikey = "place key between quotes"

The only edit required is the apikey variable to obtain one we need to issue a command via SSH to GlueTUN, so log in to your NAS and then enter the command below (It will download the latest GlueTUN image for you) copy the key that is provided by GlueTUN into the file between the double quotes and save it.

YAML

sudo docker run --rm qmcgaw/gluetun genkey

Keep hold of the key for a few more minutes as we need it again for the compose

GSP : Qbittorrent – Gluetun synchronised port mod

The following environment variables need to be edited to ensure the mod functions, I recommend getting GlueTUN started up before coming back and editing these as you need some items that are only available after first set up.

Variable	Setting
GSP_GTN_API_KEY	This is the same key we placed in the config.toml above
GSP_SLEEP	This defines how often to check for a newly assigned port the default is 120 seconds
GSP_MINIMAL_LOGS	We default this to FALSE in order to see that the mod is working, however you can change to TRUE after setup is confirmed as working correctly
GSP_QBT_USERNAME	Your qBittorrent username
GSP_QBT_PASSWORD	Your qBittorrent password (if you have special characters in the password use “doublequotes” around the password)
GSP_QBT_ADDR	Insert you NAS IP address http://nasip:8090

Note: you will need to circle back and update the username and password for qBittorrent after the first setup.

Once you have configured the above you should be set and the mod will be updating your port directly into qBittorrent when it changes.

Carry on with the rest of the guide..

Docker Compose General Edits

IDs and Timezone

First look for the lines below, they appear twice each, these control the containers access to our filesystem and also the user the containers run as.

Ports and Proxies

In the top Gluetun section you will notice that we have some additional ports assigned for a http proxy and Shadowsocks Proxy – this means you can direct traffic from other devices or applications on your network through the container! If you want to use these change the following.

Firewall Outbound Subnet

This section controls your ability to access the UIs of any containers running through the GlueTUN containers network.

      - FIREWALL_OUTBOUND_SUBNETS=172.20.0.0/16,192.168.0.0/24

The first part ‘172.20.0.0/16’ don’t edit as this is our ‘synobridge’ network and allows other containers such as Radarr to access the download client.

We need to change the second IP after the comma this allows us to access the WebUI and containers via out local network.

This IP address (subnet) is easy to figure out. If you NAS IP is 192.168.0.27 your subnet is 192.168.0.0/24 (notice I just changed the last number before the /24 to 0)

Firewall Input Ports (Port Forwarding)

This line is #commented out by default, if your VPN provider offers port forwarding remove the # from the start of the line and change the port number(s) in line with the ones provided to you. Make sure you also manually update the ‘Listening Port’ in qbit once you are running.

      - FIREWALL_VPN_INPUT_PORTS=12345,56789

Volumes

By default, I have assumed you have your config files stored on /volume1 if these are located on another volume amend these lines accordingly.

      - /volume1/docker/gluetun:/gluetun
      - /volume1/docker/qbittorrent:/config
      - /volume1/data/torrents:/data/torrents      

Watchtower Exclusion

You don’t need to change this, I added a label to avoid Watchtower automatically updating the GlueTUN container as it will always break the overall project which can be inconvenient if you are not around to fix it. You can update the container using the mini guide on the left menu of the site.

    labels:
      - com.centurylinklabs.watchtower.enable=false

Docker Compose – Provider Specific Edits

This next bit is important and if you don’t pay attention to the details you will have a harder time connecting up to your VPN provider, if you used the pre-configured settings for AirVPN or ProtonVPN skip this section.

Open up the GlueTun Wiki and in the list find your provider.

Let’s use AirVPN as our example.

On the page you will see a number of key sections highlighting the variables that work with AirVPN.

Note ignore the ‘docker run’ code it’s not relevant for what we are doing.

Read the compose section and make note of what is shown for either WireGuard or OpenVPN dependent on what you are using to connect and then make the same amendments to the compose you copied earlier.

Key differences are generally the SERVER_COUNTRIES / SERVER_CITIES or what keys are required and IP addresses etc.

I have provided some common defaults in the compose for you, but you need to amend them in line with your providers page.

If your provider is not supported, you can make a request on GitHub to add it, or you can follow the custom providers guidance on GlueTUNs WIKI.

Once you have checked for your provider, make the appropriate edits to the compose accordingly.

That completes the edits to the compose!

Click ‘Next’

You do not need to enable anything on the ‘Web portal settings’ screen click ‘Next’ again

On the final screen click Done which will begin the download of the container images and once downloaded they will be launched!

The images will now be downloaded and extracted. You should see ‘Code 0’ when it has finished.

You will now see your vpn-project running both containers should have a green status on the left-hand side.

Firewall Exceptions

(Skip if you don’t have the Firewall configured)

If you have the Synology Firewall enabled please see this additional guide for further info on exceptions and correct set up.

Final qBittorrent Setup

Changing the default WebUI login and password

If you skip this step you won’t be able to log in.

Now the container has started open it in the Docker UI and go to the Log tab. Within the logs you will see the login details

Now before doing any more of the guide go to the Web UI by going to the IP of your NAS followed by port 8090 and log in. Then on the WebUI tab change the defaults to your own and save them.

As we have used /data/torrents as the mount point for our downloads we need to make sure qBittorrent uses this same file path. Open the settings and edit the following paths and save.

In prior versions of this guide I had a command to unzip RAR and ZIP files, I have removed this as it is not reliable, check out Unpackerr from the menu.

Advanced Network Settings (Use the TUN Device)

The last step is to tell qBittorrent to only use the tun0 interface for its traffic, go to the Advanced tab then from the ‘Network Interfaces’ drop down select ‘tun0’ and click Apply, If this doesn’t appear the first time you may need to completely reboot your NAS.

I am not going to walk through all the other settings as you can customise these as you wish.

That’s it you are completely set up, you can now start up the Project again from the ‘Project’ tab.

I recommend having a quick read through the FAQ as it covers some questions you may have!

FAQs

Q: My GlueTUN is unhealthy what can I do?

A: The GlueTUN logs should be your first point of call, they will tell you if you have key issues with the configuration that are sometimes easily remedied. If you are still stuck leave a comment on this post, include the contents of your compose and also the log file (Use my PrivateBin https://paste.drfrankenstein.co.uk) remove passwords or WireGuard keys!

Or Join Discord for some more immediate help..

Q: How can I update the GlueTUN containers?

A: See the Updating Containers section on the menu.

Q: How can I be sure the VPN connection is working?

A: Go to the TorGuard Check My Torrent IP site, right-click on the Green banner and copy the link (it’s a Magnet link) Then add this link into qBittorrent and start the torrent. Keeping the site open after a few seconds the site will show the IP address of the connection it finds. This will be of the VPN provider not your home IP. (Please note the torrent doesn’t actually download anything it’s purely doing an IP check)

Q: I am getting the ‘errored’ status for all my torrents

This is very likely a permissions issue, go to the User and Group guide and see the permission fixes towards the bottom.

Q: Everything seems to be connected but nothing is downloading.

Try grabbing the Ubuntu torrent as that is a sure fire way of testing as generally it has over 3k seeds.

Are you using TorGuard – If so they block torrents on their US servers. Change to another country – Also while you are at it, you may need to configure port forwarding in your TorGuard account.

Q: My container doesn’t seem to start on a reboot even with the TUN script.

A: I have seen this a few times and usually relates to the VPN not completing its connection fast enough before containers using the VPN start. You can try setting an additional startup script by doing the following.

Head into Control Panel and go to Task Scheduler Click Create > Triggered Task > User Defined Task

In the ‘Task Settings’ tab enter the following and then click Save

sleep 120
docker-compose -f /volume1/docker/projects/vpnproject-compose/compose.yaml down 
wait
docker-compose -f /volume1/docker/projects/vpnproject-compose/compose.yaml up -d

Once added Save and Container Manager will rebuild the project with the mod enabled, you will see it working in the qBittorrent containers log.

Q: I tried to start Deluge / qBittorrent manually, and it says ‘Container must join at least one network’

A: This is due to the Synology Container Manager GUI not understanding that the container will be on the GlueTUN ‘network’. You will need to start the container via the Project as it is part of the overall Project compose.

Q: How can I add additional services to the VPN container?

See some of my other GlueTUN related guides as they show the steps required to add other containers to GlueTUN

Looking for some help, join our Discord community

If you are struggling with any steps in the guides or looking to branch out into other containers join our Discord community!

Buy me a beverage!

If you have found my site useful please consider pinging me a tip as it helps cover the cost of running things or just lets me stay hydrated. Plus 10% goes to the devs of the apps I do guides for every year.