Last updated on 27 April 2024
Important or Recent Updates
Historic Updates | Date |
---|---|
New DSM7.2 Container Manager Update (Beta/RC) | 26/04/2023 |
Added watchtower labels to the compose to allow updates and changed the proxies to off by default | 06/05/2023 |
Removed the Watchtower ‘Depends On’ Labels as they do not successfully update the GlueTUN container. Added an Exclusion label to the GlueTUN container, so it can just be manually updated. | 11/05/2023 |
Update includes: Firewall Input Ports for when your provider offers port forwarding, also a note in relation to volumes and added PUID/PGID settings for GlueTUN | 14/06/2023 |
Update for Wireguard Kernel Module Install which reduces overall CPU usage for Wireguard connections Please note if you previously followed this guide you can follow the new section to update your existing set up. | 21/09/2023 |
Added Health checks to dependent containers | 25/09/2023 |
Added an addition element to the compose to restrict the container from gaining additional privileges and umask environment variable | 25/10/2023 |
Updated with new steps to obtain and change WebUI password | 21/11/2023 |
Issue with passwords has been fixed in 4.6.2 so removed tty line from yaml | 29/11/2023 |
Swapped YAML to use Wireguard by default (Thanks Bob) (Thanks Andy for the original suggestion) | 22/01/2024 |
Amended the start up script folders to align with the changes made late November (Apologies) | 25/01/2024 |
Added – UPDATER_PERIOD=24h variable in order to ensure the latest server lists for your provider all pulled once a day | 27/04/2024 |
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 unlike some others. 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 such as Prowlarr, this is useful if you have torrent indexers blocked in your country.
In order for you to successfully use this guide please complete the three preceding guides
- Docker, Memory Recommendations and Limitations
- Step 1: Directory Setup Guide
- Step 2: Setting up a restricted Docker user
- Step 3: Setting up a Docker Bridge Network
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:
Section | Setting |
---|---|
Task: | VPNTUN |
User: | root |
Event: | Boot-up |
Enabled | Tick |
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 – Recommended for Performance & Reduced CPU Resource (not required for OpenVPN)
The default Gluetun Wireguard setup uses a ‘Userspace’ implementation of Wireguard which requires higher CPU resources. For example a 40MiB 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!
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.
- Find your model of NAS under the correct DSM version section (If you are following this guide it will be 7.2) and download the pre compiled .spk file
- Head into Package Manager and click ‘Manual Install’ on the top right and install the .spk file and untick the box to run after install
- Reboot
- SSH Into your NAS (Just like in the User Setup guide) and elevate yourself to root by typing
sudo -i
and entering your password - 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 Manager. 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.
When you have GlueTUN running check the log for this line [wireguard] Using available kernelspace implementation, and you know it is working. (Does not apply to OpenVPN)
On to the next part.
Container Manager
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:
Section | Setting |
---|---|
Project Name: | vpn-project |
Path: | /docker/projects/vpnproject-compose |
Source: | Create docker-compose.yml |
Next we are going to drop in our docker compose configuration copy all the code in the box below and paste it into line ‘1’ just like the screenshot
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 #change as per wiki
- WIREGUARD_PRIVATE_KEY=YOUR-PRIVATE-KEY #remove if using openvpn
- WIREGUARD_ADDRESSES=10.x.x.x #IP V4 Only - remove if using openvpn
- 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 #change this in line with your subnet see note on guide.
# - FIREWALL_VPN_INPUT_PORTS=12345 #uncomment this line and change the port as per the note on the guide
- 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
depends_on:
gluetun:
condition: service_healthy
security_opt:
- no-new-privileges:true
restart: always
What is a Docker Compose?!
The code we just dropped into Container Manager defines how we want each of the container’s setup. It is broken down into sections such as ports we want to access, which folders we want the container to use and what some variables to define where we live and settings for the container known as ‘Environment’ variables.
We will now make some important 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.
Variable | Value |
---|---|
PUID | (required) The UID you obtained in the user setup guide |
PGID | (required) The GID you obtained in the user setup guide |
TZ | (required) Your timezone wikipedia.org/wiki/List_of_tz_database_time_zones |
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.
Variable | Value |
---|---|
HTTPPROXY | off (default) on (enabled) |
SHADOWSOCKS | off (default) on (enabled) |
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 , 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
This part 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. This will also be the port used within the download client and will help overall connectivity.
If you do update this make sure you change the Listening Port in qBittorrent when setting up.
- 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
Important – 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
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. This is important as they can vary per provider so read everything on your providers page.
Key differences are generally the SERVER_COUNTRIES / SERVER_CITIES etc as they will vary so use the correct setting, your provider should have a list of Countries and Cities they support.
I have provided some common defaults in the compose for you but you need to amend them in line with your providers page.
- VPN_SERVICE_PROVIDER=NAMEOFYOURPROVIDER
- VPN_TYPE=wireguard
- WIREGUARD_PRIVATE_KEY=YOUR-PRIVATE-KEY
- WIREGUARD_ADDRESSES=10.x.x.x
- SERVER_COUNTRIES=VPNSERVERCOUNTRY
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.
Error: “gluetun is unhealthy”
At this stage if you receive an error relating to GlueTUN being unhealthy there is likely an error in the config file, this usually relates to the provider specific elements. If you check the logs for the GlueTUN container it will tell you why it couldn’t connect. If you get stuck drop me a comment with a copy of the logs via https://paste.drfrankenstein.co.uk.
Firewall Exceptions
(Skip if you don’t have the Firewall configured)
If you have enabled and configured the Synology Firewall you will need to create exceptions for any containers that have a Web UI or have any incoming or outgoing connections. This section covers the basics of how to add these. (Please note this is a generic section and will not show the specific ports used in this guide however it applies in the same way)
Also, I would like to refer people to the great guide on getting the Firewall correctly configured over on WunderTechs site.
Head into the Control Panel
> Security
> Firewall
, from here click Edit Rules
for the profile you set up when you enabled the Firewall.
Next click on Create
and you will see the screen below. Source IP and Action will be automatically selected to All and Allow, I will leave it up to you as to your own preference on whether you want to lock down specific Source IPs from having access. In this example we will leave as All.
You will now choose ‘Custom‘ and then the Custom
button
Now select Destination from the drop-down menu, most web based containers require TCP access but check the guide as it will show the port and protocol. Then add comma separated ports. Then press OK.
Click OK a couple of times to get back to the main screen. You will see by default the new rule is added to the bottom of the list. You must always have your Block All rule last in the list as the rules are applied top down so move your container up.
You have now completed the Firewall changes and can continue with the guide.
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.
Now continue on..
Final qBittorrent Setup
As we have used /data/torrents as the mount point for our downloads we need to make sure qBittorrent uses this same file path.
We need to change the file paths by editing the qBittorrent config file, before doing this stop both of the containers. Do this by selecting the Project from the main UI and under Action selecting ‘Stop’.
You can edit this file in a number of ways, but to keep the guide OS-agnostic we will be using the Synology Text Editor package which can be installed via Package Center.
Open Text Editor and browse to /docker/qbittorrent/qbittorrent and open the qBittorrent.conf then edit the file in line with the table below, once amended save the changes.
Original Value | New Value |
---|---|
Session\DefaultSavePath=/downloads/ | Session\DefaultSavePath=/data/torrents/completed |
Session\TempPath=/downloads/incomplete/ | Session\TempPath=/data/torrents/incoming/ |
Downloads\SavePath=/downloads/ | Downloads\SavePath=/data/torrents/completed |
Downloads\TempPath=/downloads/incomplete/ | Downloads\TempPath=/data/torrents/incoming/ |
You can now bring the containers back up again by starting the project back up.
Once the containers are running you can log into the Web UI by going to the IP of your NAS followed by port 8090
e.g. 192.168.0.30:8090
Log in with the username and password you created earlier.
Now you are in the UI click on settings cog at the top of the screen, we are going to change one more directory which is the watched folder to /data/torrents/watch. You can also turn on the option ‘keep incomplete torrents in:’ which should already have /data/torrents/incoming’ prefilled.
Next we are going to set a command to run when each torrent finishes to automatically extract any .rar files (Note if you have any issues with this I would recommend using Unpackerr the guide is on the menu)
Scroll down in the options to the ‘Run external program on torrent completion’ and enter the below, it tells qbittorrent to run unrar and extract the file to the same save path as the original file. This will not delete anything, so you can continue seeding.
unrar x "%D/*.r*" "%D/"
Advanced Network Settings
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: How can I update the GlueTUN containers?
A: See the Updating Containers section on the menu.
Q: How do I get my AirVPN details?
## Obtaining your WireGuard or OpenVPN details
- Login to your AirVPN account and go to the Client Area
- Click on `VPN Devices` and create a new device named `GlueTUN` (you can name this anything)
- Back in the Client Area select `Config Generator` and select the following:
- Linux
- Turn on either WireGuard or OpenVPN
- Choose the newly created `GlueTUN` device
- Select your preferred Server or Region
- Click Generate and download the config file.
### WireGuard Config
- In the config file you only require the following
Address = 10.141.x.x/32 #Nothing after this part
PrivateKey = uFdxxxxxxxxxxxxxxxx
PresharedKey = 4s2xxxxxxxxxxxxxxxxxxxx
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: Everything seems to be connected but nothing is downloading.
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.
Try grabbing the Ubuntu torrent as that is a sure fire way of testing as generally it has over 3k seeds.
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
Section | Setting |
---|---|
Task Name | DockerVPNBootUp |
User | Root |
Event | Boot Up |
Pre Task | Select the VPNTUN script from the drop-down that you created at the start of the guide |
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
Proton VPN Port Forwarding Extra Step
Proton doesn’t allow you to choose your own port for port forwarding, so we need to add another container to the compose in order for this to be automatically updated for us. (Please note I am unable to test this personally it is based on Feedback via our Discord channel)
First don’t uncomment this line in the compose leave it disabled# - FIREWALL_VPN_INPUT_PORTS=12345
Next copy the code below to bottom of the compose file and then amend the following only leave the other options.
TZ=
#ENTER YOUR TIMEZONEQBITTORRENT_SERVER
= NAS IP or 172.20.0.1QBITTORRENT_USER
=admin (change to the username you will be using later for qbit)QBITTORRENT_PASS
=adminadmin (change to the password you will be using later for qbit)
Once added continue with the guide 🙂
qbittorrent-natmap:
# https://github.com/soxfor/qbittorrent-natmap
image: ghcr.io/soxfor/qbittorrent-natmap:latest
container_name: qbittorrent-natmap
restart: always
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
- TZ=Europe/London #CHANGE_TO_YOUR_TZ
- QBITTORRENT_SERVER= #NAS IP or 172.20.0.1
- QBITTORRENT_PORT=8090
- QBITTORRENT_USER=admin
- QBITTORRENT_PASS=adminadmin
# - VPN_GATEWAY=
# - VPN_CT_NAME=gluetun
# - VPN_IF_NAME=tun0
# - CHECK_INTERVAL=300
# - NAT_LEASE_LIFETIME=300
network_mode: service:gluetun
depends_on:
qbittorrent:
condition: service_started
gluetun:
condition: service_healthy
security_opt:
- no-new-privileges:true
Q: How can I add additional services to the VPN container?
A: Adding additional containers to the VPN network is very easy. As you can see in the example below I have added Prowlarr to the bottom of the compose. The only amendments are that the ‘network_mode’ uses the Gluetun container and the ports for Prowlarr have been moved up to the Gluetun containers ports section.
Also see the separate Prowlarr guide on the left menu for setting up FlareSolver (In the Extras section)
- 9696:9696 # add this to the ports section of GlueTUN
#add the below to the bottom of the compose
linuxserver-prowlarr:
image: linuxserver/prowlarr:latest
container_name: prowlarr
environment:
- PUID=1234 #CHANGE_TO_YOUR_UID
- PGID=65432 #CHANGE_TO_YOUR_GID
- TZ=Europe/London #CHANGE_TO_YOUR_TZ
- UMASK=022
volumes:
- /volume1/docker/prowlarr:/config
network_mode: service:gluetun # run on the vpn network
depends_on:
gluetun:
condition: service_healthy
security_opt:
- no-new-privileges:true
restart: always
More will be added as questions come up
Buy Me a Coffee or a Beer
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 get the odd beverage. Plus 10% goes to the devs of the apps I do guides for every year.
Hi
So I now have qBit, Radarr, Sonarr, Prowlarr and Overseerr all running behind glueTUN.
I saw this week glueTun had an update available so I ran that but then it broke all the other apps. I deleted their containers and reran the Project build and it came good.
Is this the proper way to do it ?
Thanks
Hey, see the container update guide on the left menu, it has to two steps required to do it.
Hey there been trying for the last hour to fix my glutun setup. I am sure it is something dumb but I have no idea. Any help would be super appreciated.
I tried different variations of my devices IP, turn the country for my VPN comment off, and about 4-5 different variations of things.
Logs:
https://paste.drfrankenstein.co.uk/?83fc8d5083bc989a#DZeymr1wcMHacvCjw4Lp455aDUAASfpk7XX3YQuCXq4w
Hey, could I also see your YAML file details (remove any WireGuard keys first) If you don’t want to drop the info here publicly drop me a message via my Help Me! page.
Will post maybe will help someone else
https://paste.drfrankenstein.co.uk/?8d199f09ad70aa3f#3reEJmUGSBRW2zwHaHkdzdSxRNxW5e2L5ZZaknAjTdxE
Same thing happening for me. Only thing that changed is updating both containers and rebuilding the project.
2024-04-13T12:58:52-06:00 WARN [dns] cannot update files: Get “https://www.internic.net/domain/named.root”: dial tcp: lookup http://www.internic.net on 1.1.1.1:53: read udp 10.137.244.178:53798->1.1.1.1:53: i/o timeout
It may be worth sticking with a specific working version you can easily roll back by changing the version number in the image line
For example image:qmcgaw/gluetun:v3.37.0
https://hub.docker.com/r/qmcgaw/gluetun/tags
Hi, thanks for the guide.
I was able to follow all your instructions but for some reason I get an error when trying to start a download, despite having a “connected” status. using airvpn with portforwarding. any ideas as to why this could be? thanks.
Hey Ada – Could you be a bit more specific on the ‘Error’ you receive please is it ‘Errored’ in the torrent status? If so this could be a permission issue.
Hi Dr_Frankenstein,
Went through your guide to install qBittorrent, I don’t have any firewall settings and no VPN set up and won’t be setting one up.
It’s still showing “Connection status: firewalled”
Do you know of any fix?
Thanks,
Thai.
Did you open up the Port on your router and point it to the NAS IP address, so it has a direct connection to the qbit listening port?