DEV Community

Gabriel
Gabriel

Posted on

How to Actually Set Up the Gluetun VPN Killswitch

#selfhosted #vpn #docker #homelab

Most guides show you how to configure Gluetun. Almost none of them show you how to verify the killswitch is actually working — not just configured.

This is the gap. You can have Gluetun running, qBittorrent connecting through it, and still have a broken killswitch that leaks your real IP the moment the VPN drops. I learned this the hard way.

Here's how to set it up correctly and test it properly.

What the Killswitch Actually Does

Gluetun is a VPN client that runs as a Docker container. The killswitch ensures that if the VPN connection drops, all traffic from dependent containers stops completely - it doesn't fall back to your real IP.

The key mechanism: instead of connecting containers to Gluetun over a network bridge, dependent containers (qBittorrent, Radarr, Sonarr, Prowlarr) share Gluetun's network stack directly using network_mode: service:gluetun. This means they have no independent network access — if Gluetun goes down, they go offline.

The Compose Setup

Here's the correct pattern. Pay attention to network_mode — this is where most configs go wrong:

services:
  gluetun:
    image: qmcgaw/gluetun
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8080:8080   # qBittorrent web UI
      - 7878:7878   # Radarr
      - 8989:8989   # Sonarr
      - 9696:9696   # Prowlarr
    environment:
      - VPN_SERVICE_PROVIDER=nordvpn
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=${WIREGUARD_PRIVATE_KEY}
      - SERVER_COUNTRIES=${SERVER_COUNTRIES}
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: service:gluetun   # ← this is the killswitch
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - WEBUI_PORT=8080
    volumes:
      - ${CONFIG_PATH}/qbittorrent:/config
      - ${DOWNLOADS_PATH}:/downloads
    depends_on:
      - gluetun
    restart: unless-stopped

  radarr:
    image: lscr.io/linuxserver/radarr:latest
    container_name: radarr
    network_mode: service:gluetun   # ← same for all dependent services
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
    volumes:
      - ${CONFIG_PATH}/radarr:/config
      - ${MOVIES_PATH}:/movies
      - ${DOWNLOADS_PATH}:/downloads
    depends_on:
      - gluetun
    restart: unless-stopped
Enter fullscreen mode Exit fullscreen mode

Important: All ports for dependent containers must be declared on the gluetun service, not on the individual containers. Since they share Gluetun's network, they don't have their own ports to expose.

Verifying the Killswitch Works

This is the step most guides skip. Don't assume it's working — test it.

Step 1 - Confirm traffic is going through the VPN 

docker exec qbittorrent curl -s ifconfig.me
Enter fullscreen mode Exit fullscreen mode

This should return your VPN's IP address, not your home IP. If it returns your home IP, your network_mode config is wrong.

Step 2 - Test the killswitch 

# Stop Gluetun
docker stop gluetun

# Try to make a network request from qBittorrent
docker exec qbittorrent curl -s --max-time 5 ifconfig.me
Enter fullscreen mode Exit fullscreen mode

If the killswitch is working correctly, the curl command should hang and timeout — not return any IP at all. If it returns your home IP, the killswitch is not working.

Step 3 - Restore 

docker start gluetun
Enter fullscreen mode Exit fullscreen mode

Wait 10-15 seconds for the VPN to reconnect, then verify the VPN IP is back:

docker exec qbittorrent curl -s ifconfig.me
Enter fullscreen mode Exit fullscreen mode

Common Issues

curl returns your home IP after stopping Gluetun
Your containers aren't actually using network_mode: service:gluetun. Double-check the compose file — it's easy to have it on one container but not others.

qBittorrent web UI isn't accessible
Make sure the port is declared on the gluetun service, not on qbittorrent. This catches a lot of people.

Gluetun won't start
Check that /dev/net/tun exists on your host:

ls /dev/net/tun
Enter fullscreen mode Exit fullscreen mode

If it doesn't exist, run:

sudo mkdir -p /dev/net && sudo mknod /dev/net/tun c 10 200
Enter fullscreen mode Exit fullscreen mode

VPN keeps reconnecting
Try switching to a server closer to your location using the SERVER_COUNTRIES environment variable in your .env file.

Wrapping Up

The killswitch isn't magic — it's just Docker networking. Once you understand that network_mode: service:gluetun removes independent network access from dependent containers, the whole thing clicks.

The test in Step 2 is the one thing worth doing even if you skip everything else. A killswitch you haven't tested is the same as no killswitch.

I put together a full homelab starter kit with this mediastack config included, along with Immich, Jellyfin, Pi-hole, and Portainer — each with setup guides covering the non-obvious parts. If you're building out a similar setup, grab it here — launch code **LAUNCH* get it for $7 instead of the regular $9.*

Top comments (0)