SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor · Bijgewerkt 2026-11-12

Docker-containers via Gluetun en een VPN routeren

Koppel containers met network_mode: service:gluetun en publiceer poorten op Gluetun. Zo voorkomt u verdwenen poorten en de Docker-fout over port bindings.

Waarom poorten verdwijnen wanneer u Docker-containers via een VPN routeert

Om Docker-containers via een VPN te routeren, geeft u één container de tunnel en koppelt u de overige containers aan de netwerk-namespace daarvan met network_mode: "service:gluetun". Die koppeling is het onderdeel dat gebruikers vaak verrast. De gekoppelde container heeft geen eigen netwerk meer, waardoor de gepubliceerde poorten en de Docker-servicenaam komen te vervallen. Publiceer de poorten in plaats daarvan op de VPN-container; andere containers bereiken de applicatie vervolgens via de naam van de VPN-container.

Laat u een ports:-blok staan in de gekoppelde container, dan weigert Docker deze volledig aan te maken:

Error response from daemon: conflicting options: port publishing and the container type network mode

De tool die hier wordt gebruikt is Gluetun, een container die verbinding maakt met een commerciële VPN-provider (virtual private network) via WireGuard of OpenVPN en over een eigen firewall beschikt. Release v3.41.3 is de huidige versie per oktober 2026. De voorbeelden gebruiken Mullvad met WireGuard, dus u heeft een account en een sleutel van uw provider nodig. Als u de tunnel liever op eigen hardware beëindigt, bouwt het draaien van uw eigen WireGuard-server op een VPS de andere kant van de verbinding, en wg-easy in Docker verpakt dit in een webinterface.

Wat network_mode: "service:gluetun" daadwerkelijk doet

Elke Docker-container krijgt normaal gesproken een eigen netwerknamespace: eigen interfaces, routingtabel, firewallregels en luisterende sockets. De modus service: slaat deze stap over en start de container in de namespace van gluetun. Eén namespace betekent één IP-adres. Dat heeft zes gevolgen.

  • De app heeft geen eigen adres. Het adres is dat van gluetun.
  • De app is niet verbonden met een Docker-netwerk. De servicenaam wordt daardoor niet geregistreerd en kan niet worden resolved. Andere containers moeten gluetun gebruiken.
  • Containers binnen dezelfde namespace bereiken elkaar via localhost.
  • Twee containers in één namespace kunnen niet op dezelfde poort luisteren. De documentatie van Gluetun is hierover duidelijk: er is geen workaround.
  • Capabilities behoren toe aan een container, niet aan een namespace. Gluetun heeft NET_ADMIN en /dev/net/tun, omdat het de tunnelinterface aanmaakt. De gekoppelde container erft deze niet.
  • Compose weigert elk bestand waarin een service zowel network_mode als networks instelt. Verbind gluetun met uw netwerken. De app maakt daar dan gebruik van.

Als u gluetun herstart, wordt de verbinding van alles wat eraan is gekoppeld verbroken. Dit gedrag is gedocumenteerd. Daarom herstart gluetun het VPN-proces in de container in plaats van af te sluiten wanneer de verbinding wegvalt. Nadat u gluetun zelf hebt herstart of opnieuw hebt aangemaakt, herstart u de containers die eraan zijn gekoppeld.

Het werkende compose-bestand

services:
  gluetun:
    image: qmcgaw/gluetun:v3
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - VPN_SERVICE_PROVIDER=mullvad
      - VPN_TYPE=wireguard
      - SERVER_CITIES=Amsterdam
      - TZ=Europe/Amsterdam
    env_file:
      - ./gluetun.env
    volumes:
      - ./gluetun:/gluetun
    ports:
      - 127.0.0.1:8080:8080/tcp
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: "service:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Amsterdam
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent:/config
      - ./downloads:/downloads
    depends_on:
      gluetun:
        condition: service_healthy
    restart: unless-stopped

De tag :v3 is de nieuwste stabiele release in de v3-reeks. De tag :latest verwijst naar de laatste commit van de master-branch. Dat is de ontwikkelversie. Gebruik daarom :v3 op een machine waarop u op dinsdag geen fouten wilt onderzoeken.

WEBUI_PORT=8080 moet overeenkomen met de gepubliceerde poort, omdat qBittorrent binnen de namespace van gluetun bindt en de publish-regel verkeer van de host naar poort 8080 daar doorstuurt. Als u het ene nummer zonder het andere wijzigt, reageert de poort nergens op. Met 127.0.0.1:8080:8080 blijft de webinterface bereikbaar via het loopbackadres van de host. Een kale 8080:8080 publiceert op elke interface en voegt zelf een firewallregel toe. Daardoor kunnen door Docker gepubliceerde poorten ufw rechtstreeks omzeilen.

Start de containers en controleer ze daarna in deze volgorde:

docker compose up -d
docker compose ps
docker compose logs gluetun | tail -30

docker compose ps moet gluetun als healthy weergeven en qbittorrent als running. Controleer vervolgens het externe adres vanuit de namespace. Deze controle bepaalt of de rest correct werkt:

docker run --rm --network=container:gluetun alpine:3.22 sh -c "apk add wget && wget -qO- https://ipinfo.io"

Het veld ip in die JSON moet het adres van uw VPN-provider zijn. Als daar het eigen adres van uw server staat, bevindt de applicatie zich niet in de tunnel. Alles hieronder werkt dan anders dan beschreven.

Houd de sleutels buiten het compose-bestand

gluetun.env bevat de referentiegegevens en blijft buiten git:

WIREGUARD_PRIVATE_KEY=wOEI9rqqbDwnN8/Bpp22sVz48T71vJ4fYmFWujulwUU=
WIREGUARD_ADDRESSES=10.64.222.21/32

Beide waarden komen uit een WireGuard-configuratiebestand dat u in het accountgedeelte van uw provider genereert. Stel de bestandsmodus in op 600. Wees duidelijk over wat dit oplevert: de sleutel blijft buiten uw repository, maar docker inspect gluetun toont nog steeds elke omgevingsvariabele aan iedereen die toegang heeft tot de Docker-socket. Omgevingsbestanden en secrets in Docker Compose behandelt de sterkere opties.

Hoe een container buiten de tunnel communiceert met een container binnen de tunnel

Beide richtingen werken en gebruiken elk een andere naam. De twee containers hebben een gedeeld Docker-netwerk nodig; dit moet het netwerk van gluetun zijn, aangezien de gekoppelde container zelf geen netwerk heeft. Hoe Docker Compose-netwerken zijn bedraad behandelt de standaardinstellingen.

Gebruik van buiten naar binnen de naam van gluetun en de poort waarop de applicatie luistert. Een reverse proxy-container bereikt de webinterface van qBittorrent via gluetun:8080. Hiervoor is geen ports:-vermelding nodig, omdat verkeer tussen containers op het Docker-netwerk blijft en nooit een hostpoort raakt.

Gebruik van binnen naar buiten de servicenaam van de andere container, bijvoorbeeld postgres:5432. Sinds v3.41 lost gluetun andere containernamen op vanuit zijn eigen namespace. Gebruik deze versie of nieuwer als een naam niet wordt omgezet.

De firewall van gluetun bepaalt wie een verbinding mag openen. Verkeer vanaf het eigen Docker-netwerk van gluetun is toegestaan. Een client op een ander subnet, een laptop op uw LAN of een container op een afzonderlijk bridge-netwerk, heeft een retourpad nodig dat door de firewall en routering van gluetun wordt toegestaan:

FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24

De gedocumenteerde betekenis is exact: door komma's gescheiden subnetten waartoe gluetun en de containers die de netwerkstack delen, toegang hebben.

Inkomende verbindingen vanaf het internet vormen een apart probleem. De peers van een torrent-client komen binnen via de VPN-zijde, dus het publiceren van poort 6881 op de host heeft voor hen geen zin. U heeft een doorgestuurde poort van uw provider nodig, en die poort moet worden vermeld in FIREWALL_VPN_INPUT_PORTS, wat poorten vanaf de VPN-serverzijde toestaat. Mullvad, gebruikt in dit voorbeeld, ondersteunt geen port forwarding, dus dit vereist een provider die dat wel doet. Dit is het onderdeel dat de meeste mediastacks gebouwd met Docker Compose niet werkend achterlaten.

De kill switch: wat gebeurt er als de tunnel wegvalt

Dit patroon bewijst zijn waarde bij storingen. De gekoppelde container deelt de interfaces en routeringstabel van Gluetun. De firewall van Gluetun blokkeert regulier internetverkeer buiten de tunnel, terwijl het VPN-server-eindpunt, lokaal Docker-verkeer en geconfigureerde uitzonderingen worden toegestaan. Deze firewall voorkomt dat het verkeer terugvalt op de standaardinterface wanneer de tunnel wegvalt. Er is geen moment waarop pakketten via de standaardinterface lekken terwijl een client opnieuw verbinding maakt.

Gluetun bewaakt zijn eigen verbinding. Elke minuut verstuurt het een ICMP echo (een ping) naar de adressen in HEALTH_ICMP_TARGET_IPS, die standaard op 1.1.1.1,8.8.8.8 staan. Als ICMP niet is toegestaan, valt deze controle terug op een plaintext UDP DNS-query. Elke vijf minuten voert het een volledige TCP- en TLS-dial (transport layer security) uit naar HEALTH_TARGET_ADDRESSES, standaard cloudflare.com:443,github.com:443. Wanneer deze falen, herstart het de VPN binnen de container en logt dit:

WARN [vpn] restarting VPN because it failed to pass the healthcheck: periodic check: dialing: dial tcp4: lookup cloudflare.com: i/o timeout

Lees de logs van de gekoppelde container met deze volgorde in gedachten. Regels zoals connection refused, operation not permitted en i/o timeout in de applicatie zijn gevolgen van een dode tunnel, geen oorzaken. De documentatie van Gluetun vermeldt dit expliciet, omdat gebruikers het gevolg rapporteren en daar urenlang naar zoeken.

HEALTH_RESTART_VPN=on is de standaardinstelling en moet ingeschakeld blijven. Schakel deze alleen uit tijdens het debuggen van een specifieke fout, want als deze uitstaat, blijft een dode tunnel dood.

Volgorde: voorkom dat de stack start voordat de tunnel actief is

De image bevat een Docker healthcheck:

HEALTHCHECK --interval=5s --timeout=5s --start-period=10s --retries=3 CMD /gluetun-entrypoint healthcheck

Dit commando voert een tweede, kortstondige kopie van gluetun uit die de health server van de actieve instantie op http://127.0.0.1:9999/ bevraagt. Een werkende tunnel antwoordt met 200 OK. Een defecte tunnel antwoordt met 500 Internal server error inclusief een foutmelding, waarna Docker de container na drie opeenvolgende mislukte checks als ongezond markeert.

condition: service_healthy is wat hierop wacht. Een standaard depends_on: [gluetun] wacht enkel tot de container is gestart; dit gebeurt enkele seconden voordat de handshake is voltooid. Hierdoor start de applicatie in een dood netwerk en geeft deze vaak op bij de eerste verbindingspoging. Healthchecks in Docker Compose behandelt de syntaxis en de timing-velden.

Eén beperking zorgt vaak voor verwarring. Compose evalueert die voorwaarde wanneer de stack wordt gestart. Het stopt of herstart de applicatie niet als gluetun later ongezond wordt. De interne auto-healing van gluetun vangt dit scenario op; daarom herstart het proces de VPN-verbinding in plaats van de container.

Controleer op een DNS-lek voordat u de configuratie vertrouwt

DNS (domain name system) is het lek dat overblijft na een correcte tunnel. Gluetun draait zijn eigen resolver binnen de namespace en stuurt queries standaard via DoT (DNS over TLS) door naar Cloudflare: DNS_UPSTREAM_RESOLVER_TYPE=dot en DNS_UPSTREAM_RESOLVERS=cloudflare. Wijzig deze instellingen niet; uw opzoekingen zijn dan versleuteld en verlopen via de tunnel.

De instelling die dit proces verstoort wanneer deze naar een lokale resolver wijst, is DNS_UPSTREAM_PLAIN_ADDRESSES. Gebruikers grijpen hiernaar wanneer een naam niet wordt omgezet en zij willen dat hun router of de resolver van hun provider het antwoord geeft. De documentatie van Gluetun waarschuwt dat queries die naar een resolver op uw Docker-bridge of LAN worden gestuurd, buiten de VPN-tunnel lekken. Een publieke plaintext-resolver ontvangt queries nog steeds via de tunnel, maar de VPN-provider kan deze inzien en wijzigen. De WireGuard-versie van dezelfde fout wordt behandeld in DNS die stopt met omzetten via een WireGuard-tunnel.

Om dit te testen, stelt u SHADOWSOCKS=on en SHADOWSOCKS_PASSWORD in op gluetun, publiceert u 8388:8388/tcp en 8388:8388/udp, maakt u vervolgens verbinding met een Shadowsocks-client die is geconfigureerd om UDP DNS te tunnelen en laadt u een DNS-lektest. Het resultaat moet uw provider of Cloudflare tonen, nooit uw thuisrouter. De eigen documentatie van Gluetun waarschuwt dat sommige lektesten vreemde resultaten rapporteren, omdat de resolver binnen de namespace een lokale caching-tussenpersoon is in plaats van de server die uiteindelijk antwoordt. Beschouw een verkeerd land of de resolver van uw eigen ISP als een reëel signaal.

Tailscale toevoegen naast de VPN-sidecar, en welke krijgt voorrang

Tailscale is een overlay-netwerk gebaseerd op WireGuard voor het bereiken van uw eigen machines. Gebruikers draaien het vaak naast een provider-VPN om een beheerpad naar de stack te behouden. Het delen van een namespace betekent ook het delen van firewallregels, dus de twee moeten compatibele firewall- en routeringsinstellingen hebben. De documentatie van Tailscale stelt de standaard: het fungeert als een overlay-netwerk, het routeert alleen verkeer tussen apparaten waarop Tailscale draait, en het raakt uw openbare internetverkeer niet aan.

Het antwoord hangt dus af van één instelling.

  • Tailscale in zijn eigen container, standaardconfiguratie: het ziet het uitgaande verkeer van de applicatie nooit. Gluetun verzorgt al dit verkeer. Een proces in de Tailscale-container bereikt de applicatie op gluetun:8080 via een gedeeld Docker-netwerk; het blootstellen van die verbinding aan tailnet-clients vereist forwarding of een proxy.
  • Tailscale gekoppeld aan de namespace van gluetun met network_mode: "service:gluetun": in de standaard userspace-netwerkmodus, TS_USERSPACE is ingeschakeld, creëert tailscaled helemaal geen interface en werkt het als een SOCKS5- of HTTP-proxy, waardoor het de routering niet kan wijzigen. Gluetun verzorgt nog steeds het reguliere uitgaande verkeer, tenzij een applicatie expliciet die proxy gebruikt.
  • Hetzelfde, met TS_USERSPACE=false: Tailscale heeft zijn eigen /dev/net/tun-apparaat en mogelijkheden nodig omdat deze niet bij de namespace horen. Tailscaled creëert een tunnelapparaat en installeert op Linux normaal gesproken individuele IPv4 peer /32-routes in plaats van één route voor 100.64.0.0/10. Het instellen van alleen TS_USERSPACE=false schakelt de geaggregeerde route niet in. Het installeert subnetroutes van andere nodes alleen als u --accept-routes doorgeeft via TS_EXTRA_ARGS. TS_ROUTES werkt in de andere richting: het adverteert subnetten die deze container kan bereiken naar de rest van uw tailnet, het equivalent van tailscale set --advertise-routes=, en voegt hier geen routes toe. Openbaar verkeer verlaat nog steeds het netwerk via gluetun.
  • Kernel-netwerken in de namespace van gluetun met een exit node geselecteerd, sudo tailscale set --exit-node=<exit-node-ip>: Tailscale installeert standaardroutes in die namespace, maar de firewall van Gluetun kan dat pad blokkeren. Het selecteren van een exit node in een aparte container wijzigt de routes van de applicatie niet, en de userspace-modus verzorgt alleen verkeer dat expliciet via de proxy wordt verstuurd. Combineer geen concurrerende standaardroutes in de namespace van gluetun. Eén standaardroute, één eigenaar.

Als die geadverteerde routes het doel zijn, en u wilt dat het hele privénetwerk achter de box bereikbaar is in plaats van alleen de box zelf, dan behandelt het draaien van een Tailscale subnet router op een VPS de goedkeuring van de route, de IP-forwarding en de client-side vlag die TS_ROUTES op zichzelf onvoltooid laat.

Als Tailscale aanwezig is om u een beheer-URL te geven in plaats van een route, plaatsen tailscale serve en tailscale funnel HTTPS voor een lokale HTTP-service, waarbij alleen funnel deze openstelt voor het openbare internet. De documentatie van Tailscale Serve ondersteunt alleen http://127.0.0.1 als HTTP-proxy-doel. Een gedeeld Docker-netwerk maakt http://gluetun:8080 geen ondersteund doel. Deel de netwerk-namespace van gluetun met network_mode: "service:gluetun" en richt u op http://127.0.0.1:8080.

Een bijwerking is zichtbaar wanneer Tailscale in de tunnel draait. De peers zien het adres van de VPN-provider, dus verwacht dat het vaker terugvalt op relays. tailscale status toont relay "..." naast een peer in plaats van direct wanneer dat is gebeurd. De verbinding werkt, maar is trager. Als de overlay het enige is wat u daadwerkelijk nodig had, is het verschil tussen standaard WireGuard en Tailscale het betere startpunt.

Wat er misgaat en de melding die u zult zien

Docker weigert de app-container aan te maken. Error response from daemon: conflicting options: port publishing and the container type network mode betekent dat een ports:-blok nog steeds op de gekoppelde service staat. Verplaats dit naar gluetun.

Compose weigert het volledige bestand. Een service kan niet tegelijkertijd network_mode en networks instellen. Plaats de netwerken op gluetun.

Een andere container kan de app niet resolven. curl: (6) Could not resolve host: qbittorrent is correct gedrag, omdat de gekoppelde container geen netwerk heeft toegevoegd en geen naam heeft geregistreerd. Gebruik gluetun en de poort.

De tweede gekoppelde container start niet. Twee processen in dezelfde namespace kunnen niet dezelfde poort binden, en de verliezende partij meldt dat het adres al in gebruik is. Wijzig de interne poort van de app of start een tweede gluetun.

De app heeft geen netwerk nadat u gluetun heeft aangepast. Het herstarten of opnieuw aanmaken van gluetun verbreekt de verbinding voor alles wat eraan gekoppeld is. Herstart die containers.

Kleine pagina's laden, maar grote pagina's blijven hangen. Dit is MTU (maximum transmission unit). De tunnel voegt overhead toe en iets in het pad laat de te grote pakketten vallen zonder een foutmelding terug te sturen. Controleer WIREGUARD_MTU, waarvan de standaardwaarde in v3.41.3 1320 is, en verlaag deze als het pad kleinere pakketten vereist. De development-image gebruikt path MTU discovery wanneer deze instelling niet is ingesteld.

Gluetun wordt nooit healthy. De opstartcontrole benoemt de eerste verdachten: WARN [vpn] restarting VPN because it failed to pass the healthcheck: startup check: dialing: dial tcp4: lookup cloudflare.com: i/o timeout. Controleer of de sleutel is verlopen, vervolgens of de serverlijst verouderd is, en daarna of uw host-firewall uitgaand UDP blokkeert.

FAQ

Waarom werken de gepubliceerde poorten van mijn container niet meer achter Gluetun?

Omdat network_mode: "service:gluetun" de container in de netwerk-namespace van Gluetun plaatst, en een namespace heeft één IP-adres en één set luisterende poorten. De applicatie blijft luisteren, maar de publish-regel moet aanwezig zijn op de container die de namespace beheert. Verplaats de ports:-lijst naar de gluetun-service. Als u deze op de gekoppelde service laat staan, zal Docker deze niet eens aanmaken: Error response from daemon: conflicting options: port publishing and the container type network mode.

Hoe bereik ik een container binnen de VPN-tunnel vanuit een container daarbuiten?

Gebruik de servicenaam van gluetun en de poort waarop de applicatie luistert, bijvoorbeeld gluetun:8080. De gekoppelde container bevindt zich op geen enkel eigen Docker-netwerk, dus de eigen naam wordt nooit omgezet. Voor verkeer tussen containers hoeft niets gepubliceerd te worden. Andersom bereikt een container binnen de namespace een externe container via de servicenaam, zoals postgres:5432, op Gluetun v3.41 en nieuwer. Een client op een ander subnet, zoals een laptop op uw LAN, heeft een retourpad nodig dat door de firewall en routering van gluetun wordt toegestaan; voeg dat subnet toe aan FIREWALL_OUTBOUND_SUBNETS.

Werkt Gluetun als een kill switch wanneer de VPN wegvalt?

Ja, mits de firewall is ingeschakeld. De gekoppelde container deelt de interfaces en routes van Gluetun, en de firewall blokkeert regulier internetverkeer buiten de tunnel terwijl de VPN-server-endpoint, lokaal Docker-verkeer en geconfigureerde uitzonderingen worden toegestaan. Gluetun herstart de VPN vervolgens intern, waarbij WARN [vpn] restarting VPN because it failed to pass the healthcheck wordt gelogd, in plaats van af te sluiten, omdat elke gekoppelde container zijn netwerk verliest wanneer gluetun zelf herstart.

Tailscale en Gluetun in dezelfde stack: welke verzorgt het uitgaande verkeer?

Gluetun verzorgt het reguliere uitgaande verkeer, tenzij u dit expliciet via Tailscale verstuurt. Tailscale routeert standaard alleen verkeer tussen apparaten in uw tailnet en laat openbaar verkeer ongemoeid. In de standaard userspace-modus van de container-image wordt er helemaal geen interface aangemaakt, dus kan het de routering niet beïnvloeden. Met TS_USERSPACE=false krijgt Linux normaal gesproken individuele IPv4 peer /32-routes in plaats van een geaggregeerde 100.64.0.0/10-route, plus subnetroutes van andere nodes alleen als u --accept-routes via TS_EXTRA_ARGS toevoegt. TS_ROUTES adverteert de subnetten van deze container naar uw tailnet en voegt geen lokale routes toe. Het selecteren van een exit node met sudo tailscale set --exit-node=<exit-node-ip> installeert standaardroutes alleen in de namespace die gebruikmaakt van de kernel-netwerkfunctionaliteit van Tailscale; een afzonderlijke container wijzigt de routes van de applicatie niet, en de userspace-modus transporteert alleen verkeer dat via de proxy wordt verstuurd. Kies één product om de standaardroute te beheren in plaats van beide te stapelen.

Was dit artikel nuttig?