Gluetun netwerk: communicatie met host en containers
Een container in de Gluetun namespace heeft geen eigen netwerkinterface. Publiceer poorten via Gluetun en beperk de toegang tot subnets voor een veilige configuratie.
Wat gebeurt er wanneer een container toetreedt tot het netwerk van gluetun
Een container die network_mode: service:gluetun instelt, beschikt niet over eigen netwerkinterfaces. Deze treedt toe tot de netwerk-namespace van gluetun, waardoor het publiceren van poorten en firewallregels geen eigenschappen meer zijn van die container, maar van de gluetun-service. Elk onderstaand antwoord vloeit voort uit dit ene feit.
Een netwerk-namespace is de private kopie van een netwerkstack door de kernel: met eigen interfaces, een eigen routeringstabel, eigen firewallregels en eigen listening sockets. Docker geeft elke container er standaard één. Wanneer u network_mode: service:gluetun schrijft, slaat Docker die stap over en plaatst de nieuwe container in de namespace die al eigendom is van gluetun. De container behoudt zijn eigen bestandssysteem, maar niet zijn eigen /etc/hosts of /etc/resolv.conf: Docker geeft de container dezelfde bestanden die gluetun gebruikt, en dat is later van belang.
U kunt dit direct waarnemen.
docker inspect -f '{{.HostConfig.NetworkMode}}' qbittorrentDit drukt container: af, gevolgd door het container-ID van gluetun, terwijl een normale container bridge zou afdrukken. Deze handleiding gaat verder waar Docker-verkeer routeren via een VPN met gluetun ophield: de tunnel werkt, en nu kan niets meer communiceren met de container.
Publiceer de poort op gluetun, niet op de applicatie
Laat een ports:-blok staan op de service die network_mode instelt en Docker weigert de container aan te maken:
Error response from daemon: conflicting options: port publishing and the container type network modeDe reden is direct. Het publiceren van een poort betekent het toevoegen van een NAT-regel (network address translation) die een hostpoort doorstuurt naar de eigen netwerk-namespace van een container, en deze container heeft er geen. Verplaats de mapping naar de gluetun-service. Het poortnummer verandert niet, omdat de applicatie nog steeds op die poort luistert binnen de gedeelde namespace.
services:
gluetun:
ports:
- "8080:8080/tcp" # qBittorrent web UI
qbittorrent:
network_mode: "service:gluetun"
# no ports: block hereEen expose:-blok op de afhankelijke service faalt op dezelfde manier, met conflicting options: port exposing and the container type network mode, en een networks:-blok daar is ook een harde stop: Compose meldt dat de service wederzijds uitsluitende network_mode en networks declareert, en weigert het bestand volledig te laden.
Eén consequentie wordt later merkbaar. Elke container in de namespace deelt één enkele poortruimte, dus twee applicaties die beide standaard op 8080 staan, botsen, en de tweede die start faalt met een foutmelding dat het adres al in gebruik is. Wijzig er een in de eigen configuratie, bijvoorbeeld de WEBUI_PORT-variabele op de LinuxServer qBittorrent-image, en publiceer vervolgens het nieuwe nummer op gluetun.
Hoe bereiken containers achter gluetun elkaar?
Binnen de namespace delen zij al een loopback-interface. Een container achter gluetun bereikt zijn sibling op 127.0.0.1:<port> zonder dat er een Docker-netwerk aan te pas komt.
Van buiten de namespace heeft de container geen naam. De ingebouwde DNS van Docker vertaalt een servicenaam naar het adres van die service op een door de gebruiker gedefinieerd netwerk, en deze container heeft geen adres op enig netwerk. Een normale container zoals Sonarr bereikt de torrent-client daarom niet op http://qbittorrent:8080. Deze bereikt de client op http://gluetun:8080, omdat de socket luistert in de namespace van gluetun, op het adres van gluetun. Dit verrast mensen die weten hoe Docker Compose-netwerken en servicenamen werken en verwachten dat de gebruikelijke naamgeving van toepassing is. Het werkt ook zonder iets naar de host te publiceren, aangezien beide containers zich op hetzelfde Compose-netwerk bevinden.
Controleer de DNS voordat u iets anders debugt. Gluetun draait zijn eigen DNS-server binnen de namespace en Docker geeft elke container achter gluetun hetzelfde /etc/resolv.conf-bestand als gluetun, waardoor de opzoekingen van uw applicatie via de resolver van gluetun verlopen in plaats van via die van de host. Standaard weigert die resolver ook antwoorden die naar privéadressen wijzen; dit is de reden waarom een naam die op de host wel wordt omgezet, binnen de container kan falen. De documentatie van gluetun stelt dat dergelijke hostnamen in DNS_REBINDING_PROTECTION_EXEMPT_HOSTNAMES moeten worden vermeld.
docker exec qbittorrent cat /etc/resolv.confHoe bereik ik een service die op de Docker-host draait?
Gebruik host.docker.internal. Dit vereist twee instellingen, beide op de gluetun-service, omdat er twee verschillende zaken niet correct zijn geconfigureerd.
De naam komt eerst. Een container achter gluetun leest de /etc/hosts van gluetun, en Docker weigert een extra_hosts-vermelding op een service die network_mode instelt met conflicting options: custom host-to-IP mapping and the network mode. De vermelding hoort dus bij gluetun, waarna elke container in de namespace deze kan zien.
gluetun:
extra_hosts:
- "host.docker.internal:host-gateway"host-gateway is een speciale waarde die Docker vervangt door een intern adres van de host zelf. Op een standaard Linux Docker-installatie is dat het adres van de docker0-bridge, meestal 172.17.0.1. Controleer dit op de VPS met ip -4 addr show docker0. Docker Desktop lost deze naam zelf op; daarom slaan handleidingen die op een laptop zijn geschreven de regel extra_hosts over, waarna hetzelfde bestand op een server faalt.
De route komt als tweede. Het toevoegen van de naam vertelt de container alleen welk adres gebruikt moet worden. Het pakket verlaat het systeem nog steeds via de standaardroute van gluetun, wat de tunnel is, en de firewall van gluetun blokkeert het. Het symptoom is een verbinding die blijft hangen en vervolgens een timeout geeft, in plaats van een geweigerde verbinding. Een weigering betekent dat het pakket is aangekomen en dat er een antwoord is ontvangen. Een timeout betekent dat het pakket nooit is aangekomen.
gluetun:
environment:
- FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32Controleer vervolgens of de host-service daadwerkelijk luistert op dat adres. Een PostgreSQL-server die alleen is gebonden aan 127.0.0.1 is onbereikbaar vanuit elke container die een eigen netwerk-namespace heeft. Dit geldt voor elke container achter gluetun, ongeacht de tunnel, omdat 127.0.0.1 binnen de namespace de eigen loopback van die namespace is. Alleen een container die gebruikmaakt van host-networking deelt de loopback van de host, en een container achter gluetun heeft zijn network_mode al toegewezen aan gluetun. Bind PostgreSQL in plaats daarvan aan 172.17.0.1: dit accepteert verbindingen van containers terwijl de service buiten de publieke interface blijft. Controleer dit op de host met ss -lntp | grep 5432.
Wat FIREWALL_OUTBOUND_SUBNETS daadwerkelijk wijzigt
De documentatie van gluetun beschrijft dit als de door komma's gescheiden subnetten waartoe gluetun en de containers die de netwerkstack delen toegang hebben, en merkt op dat dit wijzigingen in de firewall en routering met zich meebrengt. Beide aspecten zijn van belang. Gluetun voegt voor elk vermeld subnet een route toe via de Docker bridge-gateway, zodat pakketten voor die adressen via eth0 vertrekken in plaats van via de tunnel. Het opent ook de firewall voor deze subnetten, omdat gluetun anders uitgaand verkeer blokkeert dat niet bestemd is voor de VPN-server.
Voer de waarde in zonder spaties na de komma's.
- FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32,192.168.1.0/24,100.64.7.9/32Twee eigenschappen worden vaak over het hoofd gezien. Dit is een instelling op namespace-niveau, dus deze is van toepassing op elke container achter gluetun, niet alleen op de container die u in gedachten had. Bovendien betreft het alleen uitgaand verkeer: het regelt verbindingen die een container zelf initieert. Verbindingen die binnenkomen op een gepubliceerde poort volgen een ander pad en hoeven hier niet te worden ingevoerd.
Toegang tot de web-UI vanaf een Tailscale-peer
Tailscale geeft elke machine een adres in 100.64.0.0/10, het bereik dat is gereserveerd voor carrier-grade NAT. Dit kost niets binnen een persoonlijk tailnet, hoewel de limiet van zes gebruikers in het gratis abonnement bepaalt of dit zo blijft zodra andere mensen toegang nodig hebben tot dezelfde UI's. Het aantal gebruikersapparaten is onbeperkt in elk abonnement. Servers en andere getagde apparaten worden apart geteld: de prijspagina van Tailscale vermeldt 50 inbegrepen getagde resources, met extra resources voor $1 per maand per stuk. Aangezien de facturering verder gebruikers telt in plaats van machines, hangt wat een betaald tailnet daadwerkelijk kost grotendeels af van hoeveel mensen u uitnodigt, niet van hoeveel containers u aan hen blootstelt. De twee richtingen vereisen verschillende aanpakken.
Inkomend verkeer is de eenvoudige variant. Het publiceren van 8080:8080 op gluetun bindt die poort aan alle adressen van de host, en de tailscale0-interface van de host is er daar een van, dus een peer opent http://<machine-name>:8080 en bereikt de container. Docker past NAT toe op de host en de firewall van gluetun staat inkomend verkeer naar het Docker-subnet toe.
Om de UI alleen bereikbaar te maken via het tailnet, bindt u de gepubliceerde poort aan het Tailscale-adres van de host in plaats van aan elk adres.
ports:
- "100.101.102.103:8080:8080/tcp"Zoek dat adres met tailscale ip -4 op de host. Binding is hier een sterkere controle dan een firewallregel, omdat de poort helemaal niet wordt geopend op de publieke interface. Als u de UI liever bereikt via een HTTPS-naam dan via een host en poort, kan tailscale serve die gepubliceerde poort fronten, hoewel serve en funnel verschillen in wie er uiteindelijk toegang toe heeft en slechts een van de twee de UI op het tailnet houdt. Het omzeilt ook het probleem in Docker dat poorten direct langs ufw publiceert. Het Tailscale sidecar-patroon voor Compose gaat verder en verwijdert de hostpoort volledig, maar dit werkt door de applicatie in de netwerk-namespace van de sidecar te plaatsen, en een container achter gluetun heeft zijn enige network_mode al aan gluetun toegewezen.
Uitgaand verkeer is waar FIREWALL_OUTBOUND_SUBNETS terugkeert. Als een container een peer moet aanroepen, voeg dan het adres van die peer toe en geef de voorkeur aan een /32 per peer boven het gehele /10. Als de machine die u aanroept zich op een privénetwerk bevindt dat wordt bereikt via een VPS die dat subnet adverteert aan uw tailnet, vermeld dan het geadverteerde bereik in plaats van het eigen 100.x-adres van de router, en bevestig dat de host zelf die routes heeft geaccepteerd. MagicDNS-namen worden standaard niet omgezet in de container, omdat de container de DNS-server van gluetun gebruikt in plaats van de resolver van de host. Gebruik daarom het numerieke 100.x-adres of pin de naam met een extra_hosts-regel in de gluetun-service. De DNS_UPSTREAM_PLAIN_ADDRESSES-optie van gluetun kan query's doorsturen naar een andere resolver, maar dit verstuurt elke query in platte tekst. De documentatie van gluetun raadt dit af omdat query's naar een privéadres uit de VPN-tunnel lekken. Hetzelfde geldt wanneer u uw eigen Tailscale-controleserver met Headscale draait.
Een compleet compose-bestand voor de gangbare opzet
Een downloadclient achter de VPN, twee web-UI's die alleen op de tailnet reageren, en één container die een PostgreSQL-database op de host uitleest.
services:
gluetun:
image: qmcgaw/gluetun:latest
container_name: gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
ports:
- "127.0.0.1:8000:8000/tcp" # gluetun control server, host only
- "100.101.102.103:8080:8080/tcp" # qBittorrent UI, tailnet only
- "100.101.102.103:9696:9696/tcp" # Prowlarr UI, tailnet only
extra_hosts:
- "host.docker.internal:host-gateway"
volumes:
- ./gluetun:/gluetun
environment:
- VPN_SERVICE_PROVIDER=mullvad
- VPN_TYPE=wireguard
- WIREGUARD_PRIVATE_KEY=${WIREGUARD_PRIVATE_KEY}
- WIREGUARD_ADDRESSES=${WIREGUARD_ADDRESSES}
- SERVER_CITIES=Amsterdam
- FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32,100.64.7.9/32
- TZ=Europe/Amsterdam
restart: unless-stopped
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
network_mode: "service:gluetun"
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Amsterdam
- WEBUI_PORT=8080
volumes:
- ./qbittorrent:/config
- /srv/downloads:/downloads
depends_on:
gluetun:
condition: service_healthy
restart: unless-stopped
prowlarr:
image: lscr.io/linuxserver/prowlarr:latest
network_mode: "service:gluetun"
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Amsterdam
- PROWLARR__POSTGRES__HOST=host.docker.internal
- PROWLARR__POSTGRES__PORT=5432
- PROWLARR__POSTGRES__USER=prowlarr
- PROWLARR__POSTGRES__PASSWORD=${PROWLARR_DB_PASSWORD}
- PROWLARR__POSTGRES__MAINDB=prowlarr-main
- PROWLARR__POSTGRES__LOGDB=prowlarr-log
volumes:
- ./prowlarr:/config
depends_on:
gluetun:
condition: service_healthy
restart: unless-stoppedBestudeer het bestand voor het patroon in plaats van de productnamen. Beide UI's zijn gepubliceerd op gluetun en gebonden aan het tailnet-adres van de host, waardoor ze alleen via Tailscale bereikbaar zijn. De extra_hosts-regel bevindt zich ook op gluetun, omdat Prowlarr de /etc/hosts van gluetun leest bij het resolven van host.docker.internal; Docker zou de regel op Prowlarr zelf weigeren. FIREWALL_OUTBOUND_SUBNETS benoemt twee specifieke adressen: het Docker bridge-adres van de host, zodat Prowlarr een databaseverbinding kan openen, en één tailnet-peer.
De PostgreSQL-server ontbreekt bewust in het bestand. Deze draait op de VPS als een reguliere systeemservice die luistert op 172.17.0.1:5432. Dit is dezelfde gelaagdheid als een arr-stack op Docker Compose, waarbij de database buiten Docker is geplaatst.
Houd de WireGuard private key buiten het compose-bestand. ${WIREGUARD_PRIVATE_KEY} leest vanuit een .env-bestand ernaast, een patroon dat wordt behandeld in env-bestanden en secrets voor Docker Compose. De condition: service_healthy-clausule gebruikt de healthcheck die de gluetun-image standaard bevat, zodat niets start voordat de tunnel als actief wordt gerapporteerd. Compose healthchecks leggen de algemene vorm uit.
Publiceren op elk adres in plaats van alleen het tailnet
Verwijder het adres-prefix en de port-binds op 0.0.0.0, wat ook het publieke IP van de VPS omvat. Doe dit alleen achter een firewall die u beheert, en lees eerst de ufw-opmerking hierboven.
ports:
- "8080:8080/tcp"Bevestig dat de tunnel verkeer verwerkt
Voer hetzelfde verzoek twee keer uit: één keer vanuit de namespace en één keer vanaf de host, en vergelijk de resultaten.
docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org
curl -s https://api.ipify.orgDe eerste opdracht moet het exit-adres van uw VPN-provider tonen. De tweede moet het adres van de VPS tonen. Als deze overeenkomen, gaat het verkeer van de container niet door de tunnel. Elke correctie in deze handleiding is dan zinloos totdat dit is opgelost.
De routeringsregels en tabellen tonen wat wel en wat niet via de tunnel verloopt.
docker run --rm --network=container:gluetun alpine:3.22 sh -c 'ip rule show; ip route show table 51820; ip route show table 199'Bij de WireGuard-configuratie in deze handleiding noemt gluetun de tunnelinterface wg0. De naam tun0 is enkel de standaardinstelling voor OpenVPN. Gluetun houdt de standaardroute van de tunnel bovendien buiten de hoofdrouteringstabel. ip rule show hoort een regel te bevatten die al het verkeer dat niet door WireGuard zelf is gemarkeerd, naar tabel 51820 stuurt. Die tabel moet een standaardroute op wg0 bevatten. Tabel 199 bevat één route per item in FIREWALL_OUTBOUND_SUBNETS, die elk naar de Docker-bridge-gateway op eth0 wijzen; de bijbehorende regel wordt vlak voor die van de tunnel gecontroleerd. Een standaard ip route show toont nog steeds de eigen standaardroute van Docker op eth0. Dit is verwacht gedrag en geen lek, omdat beide regels van gluetun vóór de hoofdtabel worden gecontroleerd. Elke route in tabel 199 die u niet zelf heeft opgegeven, is verkeer dat de VPN omzeilt.
De control server van gluetun kan hetzelfde publieke IP-adres rapporteren op poort 8000, via /v1/publicip/ip, maar standaard pas nadat u authenticatie heeft ingesteld. De documentatie van gluetun stelt dat alle routes van de control server tegenwoordig standaard privé zijn, waardoor een simpel verzoek aan dat pad faalt. Configureer dit met een authenticatiebestand dat via een bind mount op /gluetun/auth/config.toml is gekoppeld, gebruikmakend van de basic of apikey methode, en herstart vervolgens gluetun. Het compose-bestand hierboven koppelt ./gluetun al aan /gluetun, dus het bestand moet op de host op ./gluetun/auth/config.toml worden geplaatst. De variabele HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE is de snellere methode. Deze instellen op {"auth":"none"} schakelt authenticatie volledig uit, wat in de documentatie sterk wordt afgeraden. In versies vóór v3.39.1 is de server niet op deze manier beveiligd en waarschuwt de documentatie u om iedereen die de server kan bereiken te vertrouwen.
Het lek dat een verkeerd subnet creëert
FIREWALL_OUTBOUND_SUBNETS is een gat dat u bewust in de firewall slaat, dus de grootte van het gat is de grootte van het risico. Vier fouten om te vermijden:
0.0.0.0/0faalt bij configuratievalidatie metoutbound subnet has an unspecified address: 0.0.0.0/0. Gluetun wijst het af in plaats van alles buiten de tunnel te routeren.- Een bereik dat breder is dan het doel. Het openen van
10.0.0.0/8om één machine op10.0.1.7te bereiken, opent ook elk adres dat een torrent-peer in dat bereik zou kunnen adverteren. Schrijf10.0.1.7/32. - Een bereik dat overlapt met de eigen adressen van de tunnel. De documentatie van gluetun waarschuwt dat gluetun hierdoor VPN-verkeer via de bridge verstuurt, wat port forwarding verstoort. Controleer uw
WIREGUARD_ADDRESSES-waarde voordat u een privébereik opent. 100.64.0.0/10voor Tailscale. Dat zijn ongeveer vier miljoen adressen die worden geopend zodat één peer kan worden bereikt. Vermeld de peers die u nodig heeft als/32-vermeldingen.
Onthoud dat de instelling de gehele namespace beslaat. Het openen van een subnet zodat een indexer een hostservice kan bereiken, opent hetzelfde subnet voor de torrent-client die die namespace deelt. Voer de controle van het publieke IP-adres opnieuw uit na elke wijziging van deze variabele, omdat dit de enige test is die aantoont of de wijziging het beoogde effect had.
Wat er misgaat bij het herstarten van gluetun
Gluetun beheert de namespace; de levenscyclus van gluetun is daarom gelijk aan de levenscyclus van de namespace. Het starten van een afhankelijke container terwijl gluetun offline is, mislukt direct:
Error response from daemon: cannot join network namespace of a non running container: container <id> is exitedHet herstarten van gluetun op zijn plek is een minder opvallende fout. De afhankelijke containers blijven draaien terwijl de namespace waaraan ze gekoppeld zijn onder hen opnieuw wordt opgebouwd. Hierdoor rapporteert docker ps dat alles in orde is, terwijl er geen antwoord komt. Na elke wijziging aan de gluetun-service dient u de gehele groep opnieuw aan te maken in plaats van slechts één onderdeel te herstarten.
docker compose up -d --force-recreateHetzelfde geldt voor image-updates. Het ophalen van een nieuwe gluetun-image en het opnieuw aanmaken van alleen die service zorgt ervoor dat de andere containers verwijzen naar een namespace die niet langer bestaat.
FAQ
Waarom geeft Docker de melding "port publishing and the container type network mode"?
Omdat een ports:-blok nog aanwezig is op een service die ook network_mode: service:gluetun instelt. Het publiceren van een poort voegt een NAT-regel toe die een hostpoort doorstuurt naar de eigen netwerk-namespace van een container, en een container in deze modus heeft die niet. Verwijder het ports:-blok uit die service en voeg de identieke mapping toe aan de gluetun-service. Het poortnummer blijft gelijk, aangezien de applicatie nog steeds op die poort luistert binnen de gedeelde namespace.
Hoe bereiken andere containers een service die achter gluetun draait?
Containers binnen dezelfde namespace bereiken elkaar via 127.0.0.1. Containers daarbuiten gebruiken de servicenaam van gluetun, dus http://gluetun:8080 werkt waar http://qbittorrent:8080 dat niet doet. De applicatiecontainer heeft geen adres op een Docker-netwerk, waardoor de ingebouwde DNS-server geen naam kan omzetten. Hiervoor is geen poortpublicatie nodig, zolang beide containers een Compose-netwerk delen.
Wat moet ik invullen bij FIREWALL_OUTBOUND_SUBNETS?
Alleen de adressen waar een container achter gluetun een verbinding mee moet opzetten, zo specifiek mogelijk geschreven. Eén enkele machine is een /32. De twee meest voorkomende vermeldingen zijn de Docker-host op 172.17.0.1/32 en één /32 voor elke Tailscale-peer die u aanroept. Voeg nooit 0.0.0.0/0 toe en gebruik nooit een bereik dat overlapt met de tunneladressen van uw eigen VPN. Inkomende verbindingen naar een gepubliceerde poort hebben hier geen vermelding nodig.
Waarom kan de container mijn Tailscale MagicDNS-namen niet omzetten?
MagicDNS werkt door de resolver van de host naar de DNS-server van Tailscale te laten wijzen, en de container gebruikt de resolver van de host niet. Deze gebruikt de /etc/resolv.conf die hij deelt met gluetun, welke naar de eigen DNS-server van gluetun wijst. Controleer dit met docker exec <container> cat /etc/resolv.conf. Gebruik het numerieke 100.x-adres van de peer, of koppel de naam vast met een extra_hosts-vermelding op de gluetun-service. Gluetun kan queries doorsturen naar een andere resolver met DNS_UPSTREAM_PLAIN_ADDRESSES, maar dit verstuurt ze in platte tekst en de documentatie raadt dit af.
Hoe bevestig ik dat verkeer nog steeds via de VPN verloopt?
Voer één verzoek uit vanuit de namespace en hetzelfde verzoek vanaf de host, en vergelijk vervolgens de antwoorden. docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org zou het exit-adres van uw VPN-provider moeten retourneren, terwijl curl -s https://api.ipify.org op de VPS het adres van de VPS retourneert. Twee overeenkomende antwoorden betekenen dat de tunnel het verkeer van de container niet transporteert. Voer deze controle opnieuw uit na elke wijziging in FIREWALL_OUTBOUND_SUBNETS.