SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Gluetun: raggiungere host e altri container

Un container dietro gluetun non ha interfacce proprie: pubblica le porte su gluetun e abilita solo le subnet necessarie fuori dal tunnel VPN.

Cosa accade quando un container si unisce alla rete di gluetun

Un container che imposta network_mode: service:gluetun non dispone di interfacce di rete proprie. Si unisce al namespace di rete di gluetun. Di conseguenza, la pubblicazione delle porte e le regole del firewall non sono più proprietà di quel container, ma del servizio gluetun. Tutte le risposte riportate di seguito derivano da questo fatto.

Un namespace di rete è una copia privata dello stack di rete del kernel. Include interfacce, tabella di routing, regole del firewall e socket in ascolto propri. Docker ne assegna uno a ogni container per impostazione predefinita. Quando si specifica network_mode: service:gluetun, Docker salta questo passaggio e inserisce il nuovo container nel namespace già utilizzato da gluetun. Il container mantiene il proprio filesystem, ma non i propri /etc/hosts o /etc/resolv.conf. Docker gli fornisce gli stessi file utilizzati da gluetun, con conseguenze importanti nei passaggi successivi.

È possibile verificarlo direttamente.

docker inspect -f '{{.HostConfig.NetworkMode}}' qbittorrent

Il comando stampa container: seguito dall'ID del container gluetun, mentre per un container normale stamperebbe bridge. Questa guida prosegue da instradare il traffico Docker attraverso una VPN con gluetun: il tunnel funziona, ma ora nessuno riesce a comunicare con il container.

Pubblicare la porta su gluetun, non sull'applicazione

Lasciare un blocco ports: sul servizio che imposta network_mode impedisce a Docker di creare il container:

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

Il motivo è diretto. Pubblicare una porta significa aggiungere una regola NAT (Network Address Translation) che inoltra una porta dell'host nello spazio dei nomi di rete del container, ma questo container non dispone di uno spazio dei nomi proprio. Spostare la mappatura sul servizio gluetun. Il numero della porta non cambia, perché l'applicazione continua a rimanere in ascolto su quella porta nello spazio dei nomi condiviso.

services:
  gluetun:
    ports:
      - "8080:8080/tcp"   # qBittorrent web UI

  qbittorrent:
    network_mode: "service:gluetun"
    # no ports: block here

Un blocco expose: sul servizio dipendente fallisce allo stesso modo, con conflicting options: port exposing and the container type network mode, e anche un blocco networks: nello stesso servizio interrompe l'avvio: Compose segnala che il servizio dichiara network_mode e networks, che sono mutuamente esclusivi, e rifiuta di caricare del tutto il file.

Una conseguenza si manifesta in seguito. Tutti i container nello spazio dei nomi condividono un unico spazio delle porte. Di conseguenza, due applicazioni che usano entrambe 8080 per impostazione predefinita entrano in conflitto e la seconda ad avviarsi fallisce con un errore che indica che l'indirizzo è già in uso. Cambiare una delle due applicazioni nella relativa configurazione, ad esempio la variabile WEBUI_PORT nell'immagine LinuxServer qBittorrent, quindi pubblicare il nuovo numero su gluetun.

Come comunicano tra loro i container dietro gluetun?

All'interno del namespace condividono già un'interfaccia loopback. Un container dietro gluetun raggiunge il container affine all'indirizzo 127.0.0.1:<port> senza usare alcuna rete Docker.

Dall'esterno del namespace, il container non ha un nome. Il DNS integrato di Docker risolve il nome di un servizio nell'indirizzo di quel servizio su una rete definita dall'utente, ma questo container non ha un indirizzo su alcuna rete. Di conseguenza, un container normale come Sonarr non raggiunge il client torrent all'indirizzo http://qbittorrent:8080. Lo raggiunge all'indirizzo http://gluetun:8080, perché il socket è in ascolto nel namespace di gluetun, sull'indirizzo di gluetun. Questo comportamento può sorprendere chi conosce il funzionamento delle reti e dei nomi dei servizi di Docker Compose e si aspetta che venga applicata la consueta risoluzione dei nomi. Funziona anche senza pubblicare porte sull'host, perché entrambi i container si trovano sulla stessa rete Compose.

Controlla il DNS prima di eseguire qualsiasi altra attività di debug. Gluetun esegue il proprio server DNS all'interno del namespace e Docker assegna a ogni container dietro gluetun lo stesso file /etc/resolv.conf di gluetun. Le risoluzioni richieste dall'applicazione passano quindi dal resolver di gluetun, non da quello dell'host. Per impostazione predefinita, questo resolver rifiuta inoltre le risposte che puntano a indirizzi privati. Per questo motivo, un nome che viene risolto sull'host può non essere risolto all'interno del container. La documentazione di gluetun specifica che questi hostname devono essere elencati in DNS_REBINDING_PROTECTION_EXEMPT_HOSTNAMES.

docker exec qbittorrent cat /etc/resolv.conf

Come raggiungo un servizio in esecuzione sull'host Docker?

Usa host.docker.internal. Richiede due impostazioni, entrambe sul servizio gluetun, perché ci sono due problemi distinti.

Prima viene il nome. Un container dietro gluetun legge il /etc/hosts di gluetun e Docker rifiuta una voce extra_hosts su un servizio che imposta network_mode con conflicting options: custom host-to-IP mapping and the network mode. La voce deve quindi appartenere a gluetun e ogni container nello stesso namespace la vede.

  gluetun:
    extra_hosts:
      - "host.docker.internal:host-gateway"

host-gateway è un valore speciale che Docker sostituisce con un indirizzo interno dell'host stesso. In una normale installazione Docker su Linux, è l'indirizzo del bridge docker0, generalmente 172.17.0.1. Verifica il tuo con ip -4 addr show docker0 sulla VPS. Docker Desktop risolve autonomamente questo nome. Per questo le guide scritte per un laptop omettono la riga extra_hosts, mentre lo stesso file poi non funziona su un server.

La route viene dopo. Aggiungere il nome indica soltanto al container quale indirizzo usare. Il pacchetto continua però a uscire tramite la route predefinita di gluetun, che è il tunnel, e il firewall di gluetun lo scarta. Il sintomo è una connessione che resta in attesa e poi va in timeout, non una connessione rifiutata. Un rifiuto indica che il pacchetto è arrivato e qualcosa ha risposto negativamente. Un timeout indica che il pacchetto non è mai arrivato.

  gluetun:
    environment:
      - FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32

Controlla quindi che il servizio sull'host sia effettivamente in ascolto su quell'indirizzo. Un server PostgreSQL associato soltanto a 127.0.0.1 non è raggiungibile da un container con un proprio namespace di rete. Questo vale per ogni container dietro gluetun, indipendentemente dal tunnel, perché 127.0.0.1 nel namespace è il loopback del namespace stesso. Soltanto un container che usa la rete dell'host condivide il loopback dell'host, mentre un container dietro gluetun ha già usato il proprio network_mode per gluetun. Associa invece PostgreSQL a 172.17.0.1: accetterà connessioni dai container senza esporsi sull'interfaccia pubblica. Verifica con ss -lntp | grep 5432 sull'host.

Cosa modifica realmente FIREWALL_OUTBOUND_SUBNETS

La documentazione di gluetun lo descrive come l’elenco, separato da virgole, delle subnet che gluetun e i container che condividono il suo stack di rete possono raggiungere e specifica che comporta modifiche al firewall e al routing. Entrambi gli aspetti sono importanti. Gluetun aggiunge una route per ogni subnet elencata tramite il gateway del bridge Docker, quindi i pacchetti diretti a quegli indirizzi escono tramite eth0 invece di passare dal tunnel. Apre inoltre il firewall per queste subnet, perché altrimenti gluetun elimina il traffico in uscita che non è diretto al server VPN.

Specifica il valore senza spazi dopo le virgole.

      - FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32,192.168.1.0/24,100.64.7.9/32

Due proprietà sono facili da trascurare. Questa è un’impostazione a livello di namespace, quindi si applica a ogni container che usa gluetun, non soltanto a quello considerato. Inoltre riguarda solo il traffico in uscita: controlla le connessioni avviate da un container. Le connessioni che arrivano a una porta pubblicata seguono un percorso diverso e non richiedono alcuna voce qui.

Accesso all’interfaccia web da un peer Tailscale

Tailscale assegna a ogni macchina un indirizzo in 100.64.0.0/10, l’intervallo riservato al carrier-grade NAT. Su una tailnet personale, tutto questo non comporta costi, anche se il limite di sei utenti del piano gratuito determina se la situazione resta invariata quando altre persone devono accedere alle stesse interfacce. I dispositivi degli utenti sono illimitati in tutti i piani. I server e gli altri dispositivi con tag vengono conteggiati separatamente: la pagina dei prezzi di Tailscale indica 50 risorse con tag incluse, con un costo aggiuntivo di $1 al mese per ciascuna risorsa. Poiché la fatturazione considera altrimenti gli utenti e non le macchine, il costo effettivo di una tailnet a pagamento dipende soprattutto dal numero di persone invitate, non dal numero di container esposti. Le due direzioni richiedono configurazioni diverse.

Il traffico in ingresso è il caso più semplice. La pubblicazione di 8080:8080 su gluetun associa quella porta a tutti gli indirizzi dell'host, incluso l’interfaccia tailscale0 dell’host; un peer può quindi aprire http://<machine-name>:8080 e raggiungere il container. Gluetun non interviene in questo percorso, perché la regola NAT di Docker si trova sull’host, al di fuori del namespace.

Per rendere l’interfaccia raggiungibile soltanto tramite la tailnet, associa la porta pubblicata all’indirizzo Tailscale dell’host invece che a tutti gli indirizzi.

    ports:
      - "100.101.102.103:8080:8080/tcp"

Trova quell’indirizzo con tailscale ip -4 sull’host. In questo caso, l’associazione è un controllo più efficace di una regola firewall, perché la porta non viene mai aperta sull’interfaccia pubblica. Se preferisci raggiungere l’interfaccia tramite un nome HTTPS invece che tramite host e porta, tailscale serve può fare da proxy per la porta pubblicata; tuttavia serve e funnel differiscono per chi può raggiungerla e solo uno dei due mantiene l’interfaccia all’interno della tailnet. Questo evita anche il problema descritto in Pubblicazione diretta delle porte Docker oltre ufw. Il pattern sidecar di Tailscale per Compose elimina completamente la porta sull’host, ma funziona inserendo l’applicazione nel namespace di rete del sidecar; inoltre, un container che passa attraverso gluetun ha già utilizzato il proprio unico network_mode su gluetun.

Il traffico in uscita è il punto in cui FIREWALL_OUTBOUND_SUBNETS torna rilevante. Se un container deve chiamare un peer, aggiungi l’indirizzo di quel peer e preferisci un /32 per peer invece dell’intero /10. Se la macchina che stai chiamando si trova su una rete privata raggiunta tramite un VPS che annuncia quella subnet alla tua tailnet, indica l’intervallo annunciato invece dell’indirizzo 100.x del router e verifica che l’host abbia accettato quelle route. Per impostazione predefinita, i nomi MagicDNS non vengono risolti all’interno del container, perché il container usa il server DNS di gluetun invece del resolver dell’host. Usa quindi l’indirizzo numerico 100.x oppure associa il nome a un indirizzo con una riga extra_hosts nel servizio gluetun. L’opzione DNS_UPSTREAM_PLAIN_ADDRESSES di gluetun può inoltrare le query a un altro resolver, ma le invia tutte in testo non cifrato. La documentazione di gluetun ne sconsiglia l’uso perché le query verso un indirizzo privato escono dal tunnel VPN. Lo stesso vale quando esegui un server di controllo Tailscale con Headscale.

Un file compose completo per la struttura più comune

Un client di download dietro la VPN, due interfacce Web raggiungibili soltanto sulla tailnet e un container che legge un database PostgreSQL in esecuzione sull'host.

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-stopped

Leggere il file per comprenderne la struttura, non per i nomi dei prodotti. Entrambe le interfacce Web sono pubblicate su gluetun e associate all'indirizzo tailnet dell'host, quindi rispondono su Tailscale e in nessun altro punto. Anche la riga extra_hosts si trova su gluetun, perché Prowlarr legge /etc/hosts di gluetun quando risolve host.docker.internal, mentre Docker rifiuterebbe la riga se fosse definita direttamente su Prowlarr. FIREWALL_OUTBOUND_SUBNETS definisce due indirizzi singoli: l'indirizzo del bridge Docker dell'host, che consente a Prowlarr di aprire una connessione al database, e un peer della tailnet.

Il server PostgreSQL è volutamente assente dal file. È in esecuzione sul VPS come normale servizio di sistema e resta in ascolto su 172.17.0.1:5432. È lo stesso livello architetturale di uno stack arr su Docker Compose, con il database spostato fuori da Docker.

Tenere la chiave privata WireGuard fuori dal file compose. ${WIREGUARD_PRIVATE_KEY} legge da un file .env nella stessa directory, secondo il modello descritto in file env e secret per Docker Compose. La clausola condition: service_healthy usa l'healthcheck già incluso nell'immagine gluetun, quindi nessun servizio viene avviato finché il tunnel non segnala di essere attivo. Gli healthcheck di Compose spiegano la struttura generale.

Pubblicare su ogni indirizzo invece che soltanto sulla tailnet

Rimuovere il prefisso dell'indirizzo e i binding delle porte su 0.0.0.0, che include l'IP pubblico del VPS. Eseguire questa modifica soltanto dietro un firewall sotto il proprio controllo e leggere prima la nota su ufw riportata sopra.

    ports:
      - "8080:8080/tcp"

Confermare che il tunnel stia ancora trasportando traffico

Eseguire la stessa richiesta due volte: una dall'interno del namespace e una dall'host, quindi confrontare i risultati.

docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org
curl -s https://api.ipify.org

La prima dovrebbe restituire l'indirizzo di uscita del provider VPN. La seconda dovrebbe restituire l'indirizzo del VPS. Se coincidono, il traffico del container non passa attraverso il tunnel. Fino a quando il problema non viene corretto, tutte le altre correzioni descritte in questa guida sono irrilevanti.

Le regole e le tabelle di routing mostrano quale traffico passa dal tunnel e quale lo bypassa.

docker run --rm --network=container:gluetun alpine:3.22 sh -c 'ip rule show; ip route show table 51820; ip route show table 199'

Con la configurazione WireGuard descritta in questa guida, gluetun assegna all'interfaccia del tunnel il nome wg0. Il nome tun0 è soltanto quello predefinito per OpenVPN. Gluetun mantiene inoltre la route predefinita del tunnel fuori dalla tabella di routing principale. ip rule show dovrebbe contenere una regola che invia alla tabella 51820 tutto il traffico non contrassegnato da WireGuard stesso, e quella tabella dovrebbe contenere una route predefinita su wg0. La tabella 199 contiene una route per ogni voce in FIREWALL_OUTBOUND_SUBNETS; ciascuna punta al gateway del bridge Docker su eth0, e la relativa regola viene verificata subito prima di quella del tunnel. Un semplice ip route show continua a mostrare la route predefinita del bridge Docker su eth0. È previsto e non costituisce una perdita di traffico, perché entrambe le regole di gluetun vengono verificate prima della tabella principale. Qualsiasi route presente nella tabella 199 ma non elencata da voi indica traffico che bypassa la VPN.

Il control server di gluetun può restituire lo stesso IP pubblico sulla porta 8000, all'indirizzo /v1/publicip/ip, ma per impostazione predefinita solo dopo aver configurato l'autenticazione. La documentazione di gluetun specifica che ora tutte le route del control server sono private per impostazione predefinita, quindi una richiesta semplice a quel percorso fallisce. Configurarlo con un file di autenticazione montato tramite bind su /gluetun/auth/config.toml usando il metodo basic o apikey, quindi riavviare gluetun. Il file Compose riportato sopra monta già ./gluetun su /gluetun, quindi il file deve trovarsi in ./gluetun/auth/config.toml sull'host. La variabile HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE è il metodo più rapido. Impostarla su {"auth":"none"} disabilita completamente l'autenticazione; la documentazione lo sconsiglia vivamente. In una release precedente alla v3.39.1 il server non è protetto in questo modo e la documentazione avverte di considerare attendibile qualsiasi client che possa raggiungerlo.

La fuga causata da una subnet errata

FIREWALL_OUTBOUND_SUBNETS è un'apertura intenzionale nel firewall, quindi l'ampiezza dell'apertura determina l'ampiezza del rischio. Ecco quattro modi per renderla eccessiva:

  • 0.0.0.0/0 invia tutto il traffico all'esterno del tunnel. I due controlli dell'indirizzo IP riportati sopra rilevano questo problema alla prima esecuzione, perché restituiscono lo stesso indirizzo.
  • Un intervallo più ampio del necessario. Aprire 10.0.0.0/8 per raggiungere un solo computer su 10.0.1.7 espone anche tutti gli indirizzi che un peer torrent potrebbe pubblicizzare in quell'intervallo. Scrivi 10.0.1.7/32.
  • Un intervallo che si sovrappone agli indirizzi utilizzati dal tunnel. La documentazione di gluetun avverte che, in questo caso, gluetun invia il traffico VPN attraverso il bridge, interrompendo il port forwarding. Controlla il valore WIREGUARD_ADDRESSES prima di aprire una subnet privata qualsiasi.
  • 100.64.0.0/10 per Tailscale. In questo modo vengono aperti circa quattro milioni di indirizzi per raggiungere un solo peer. Elenca i peer necessari come voci /32.

Ricorda che l'impostazione riguarda l'intero namespace. Aprire una subnet affinché un indexer possa raggiungere un servizio sull'host apre la stessa subnet anche per il client torrent che condivide quel namespace. Ripeti il controllo dell'IP pubblico dopo ogni modifica a questa variabile, perché è l'unico test che mostra se la modifica ha prodotto il risultato previsto.

Cosa si rompe quando riavvii gluetun

Gluetun gestisce il namespace, quindi il ciclo di vita di gluetun coincide con quello del namespace. L'avvio di un container dipendente mentre gluetun è inattivo fallisce immediatamente:

Error response from daemon: cannot join network namespace of a non running container: container <id> is exited

Il riavvio di gluetun senza ricreare il gruppo produce un errore meno evidente. I container dipendenti continuano a essere in esecuzione mentre il namespace a cui sono collegati viene ricreato sotto di loro, quindi docker ps segnala che tutto è operativo, ma nessun servizio risponde. Dopo qualsiasi modifica al servizio gluetun, ricrea l'intero gruppo invece di riavviarne un solo componente.

docker compose up -d --force-recreate

Lo stesso vale per gli aggiornamenti delle immagini. Se scarichi una nuova immagine di gluetun e ricrei solo quel servizio, gli altri continuano a puntare a un namespace che non esiste più.

FAQ

Perché Docker mostra il messaggio "port publishing and the container type network mode"?

Perché un blocco ports: è ancora presente in un servizio che imposta anche network_mode: service:gluetun. La pubblicazione di una porta aggiunge una regola NAT che inoltra una porta dell'host allo spazio dei nomi di rete del container. Un container in questa modalità non dispone di un proprio spazio dei nomi. Elimina il blocco ports: da quel servizio e aggiungi la stessa mappatura al servizio gluetun. Il numero di porta resta invariato, perché l'applicazione continua a essere in ascolto su quella porta nello spazio dei nomi condiviso.

Come raggiungono gli altri container un servizio che si trova dietro gluetun?

I container nello stesso spazio dei nomi si raggiungono tramite 127.0.0.1. I container esterni usano il nome del servizio gluetun. Di conseguenza, http://gluetun:8080 funziona mentre http://qbittorrent:8080 no. Il container dell'applicazione non dispone di un indirizzo su alcuna rete Docker. Il server DNS integrato non ha quindi alcun indirizzo da risolvere per il suo nome. Per questo non serve pubblicare una porta, purché entrambi i container condividano una rete Compose.

Cosa devo inserire in FIREWALL_OUTBOUND_SUBNETS?

Solo gli indirizzi a cui un container dietro gluetun deve avviare una connessione, specificandoli nel modo più restrittivo possibile. Un singolo computer è un /32. Le due voci più comuni sono l'host Docker, indicato da 172.17.0.1/32, e un /32 per ogni peer Tailscale che vuoi raggiungere. Non aggiungere mai 0.0.0.0/0 e non aggiungere mai un intervallo che si sovrapponga agli indirizzi del tunnel VPN. Le connessioni in ingresso a una porta pubblicata non richiedono alcuna voce in questa variabile.

Perché il container non riesce a risolvere i nomi MagicDNS di Tailscale?

MagicDNS funziona configurando il resolver dell'host per usare il server DNS di Tailscale. Il container non usa però il resolver dell'host. Usa il /etc/resolv.conf condiviso con gluetun, che punta al server DNS del servizio gluetun. Verifica con docker exec <container> cat /etc/resolv.conf. Usa l'indirizzo numerico 100.x del peer oppure associa il nome a un indirizzo con una voce extra_hosts nel servizio gluetun. Gluetun può inoltrare le richieste a un altro resolver tramite DNS_UPSTREAM_PLAIN_ADDRESSES, ma in questo modo le invia in chiaro e la documentazione sconsiglia questa configurazione.

Come verifico che il traffico passi ancora attraverso la VPN?

Esegui una richiesta dallo spazio dei nomi e la stessa richiesta dall'host, quindi confronta le risposte. docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org dovrebbe restituire l'indirizzo di uscita del provider VPN, mentre curl -s https://api.ipify.org eseguito sul VPS restituisce l'indirizzo del VPS. Se le due risposte coincidono, il tunnel non trasporta il traffico del container. Ripeti questo controllo dopo ogni modifica a FIREWALL_OUTBOUND_SUBNETS.

Questo articolo ti è stato utile?