SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Port forwarding Gluetun per client torrent

I download funzionano ma non ricevi connessioni? Configura il port forwarding di Gluetun, aggiorna la porta nel client a ogni riconnessione e verifica il risultato.

Perché nulla si connette in ingresso senza una porta inoltrata

Il port forwarding di Gluetun chiede al provider VPN di associare una porta pubblica sull'indirizzo di uscita del provider al container. È l'unico modo che consente a un altro peer di avviare una connessione verso il client torrent. Senza questa associazione, il tunnel è operativo e i download funzionano, ma non arriva mai nulla spontaneamente. Ogni connessione funzionante è stata avviata dal client.

Il meccanismo coinvolto è il NAT (network address translation). Il container condivide l'indirizzo di uscita del provider con molti altri clienti. Quando il client apre una connessione verso l'esterno, il provider registra il flusso e invia le risposte attraverso il tunnel. La connessione in ingresso avviata dal peer di un altro utente non corrisponde ad alcun flusso registrato. Il pacchetto raggiunge quindi l'indirizzo di uscita e viene scartato. Il client continua a raggiungere tutti i peer che sono a loro volta raggiungibili. Per questo i download terminano e il problema può non essere evidente. Il problema emerge durante il seeding, perché un seeder è un computer al quale si connettono altri utenti.

Una porta aperta in ingresso cambia due aspetti. Il client entra più rapidamente nello swarm, perché i peer che non possono accettare connessioni possono ora raggiungerlo. Inoltre, il client può caricare dati verso quei peer.

Perché la maggior parte dei provider VPN non offre il port forwarding

Una porta inoltrata è una risorsa limitata su un indirizzo condiviso. Il provider riserva un numero di porta su un indirizzo IP di uscita per un cliente e risponde delle operazioni che il cliente esegue tramite quella porta. Diversi provider di grandi dimensioni hanno rimosso questa funzione, indicando la gestione degli abusi come motivazione. Considerate il supporto come una domanda specifica, non come una semplice casella da selezionare: chiedete se il provider offre oggi il port forwarding, se è disponibile nel vostro piano e se è attivo sui server che potete effettivamente selezionare.

Quando il forwarding è disponibile, la porta è dinamica. È associata alla sessione VPN e non al vostro account, quindi può cambiare dopo ogni riconnessione. Private Internet Access assegna una porta firmata che gluetun aggiorna; la documentazione upstream specifica che la stessa porta resta disponibile per 60 giorni, a condizione di eseguire il bind mount della directory /gluetun, in modo che lo stato venga mantenuto dopo un riavvio. ProtonVPN assegna una porta casuale tramite NAT-PMP (NAT port mapping protocol), con un lease di breve durata che deve essere rinnovato continuamente. Per questo motivo, impostare la porta una sola volta nel client non è sufficiente.

Quali provider può interrogare gluetun per una porta

A partire da gluetun v3.41.3, rilasciata il 30 luglio 2026, l'integrazione nativa convalida quattro nomi di provider: Private Internet Access, ProtonVPN, Perfect Privacy e PrivateVPN. Abilitatela con VPN_PORT_FORWARDING=on, che è off per impostazione predefinita. Le guide meno recenti utilizzano PORT_FORWARDING o PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING. In questa versione funzionano ancora entrambi come nomi retrocompatibili, ma sono destinati a essere dismessi.

Due dettagli del provider determinano se la richiesta può avere successo. ProtonVPN richiede un piano a pagamento e NAT-PMP deve essere attivo: abilitate NAT-PMP (Port Forwarding) nelle opzioni VPN durante la generazione della configurazione WireGuard, oppure aggiungete +pmp al vostro nome utente se utilizzate OpenVPN. Private Internet Access su OpenVPN dispone di PORT_FORWARD_ONLY, che limita la selezione ai soli server che supportano il forwarding, evitando di collegarsi a server che non lo hanno mai implementato. WireGuard e OpenVPN differiscono nel modo in cui la porta viene richiesta, quindi consultate la pagina del vostro provider prima di scegliere.

Quando gluetun esegue una configurazione personalizzata invece di un provider integrato, VPN_PORT_FORWARDING_PROVIDER specifica l'API che gluetun deve chiamare. La pagina di riferimento di Private Internet Access associa tale variabile a VPN_PORT_FORWARDING_USERNAME e VPN_PORT_FORWARDING_PASSWORD, che contengono le credenziali dell'account necessarie per la richiesta della porta.

Attivare il port forwarding di gluetun in docker compose

Questa procedura presuppone che il tunnel sia già operativo. In caso contrario, iniziare da instradare il traffico dei container Docker attraverso gluetun e tornare qui quando i download funzionano.

services:
  gluetun:
    image: qmcgaw/gluetun:v3.41.3
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8080:8080/tcp
      - 8000:8000/tcp
    volumes:
      - ./gluetun:/gluetun
    environment:
      - VPN_SERVICE_PROVIDER=protonvpn
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=${WIREGUARD_PRIVATE_KEY}
      - VPN_PORT_FORWARDING=on
      - TZ=Etc/UTC
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:5.2.3
    container_name: qbittorrent
    network_mode: "service:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent:/config
      - ./downloads:/downloads
    depends_on:
      - gluetun
    restart: unless-stopped

Fissare il tag. qmcgaw/gluetun:latest segue il branch master, nel quale le funzionalità interne del port forwarding stanno cambiando in vista della versione v4; un'immagine senza tag fissato può quindi cambiare comportamento al successivo docker compose pull. Tenere la chiave privata fuori dal file compose usando un file env per i secret di compose.

Dove gluetun scrive la porta inoltrata

Gluetun espone la porta in tre punti, che riportano tutti lo stesso valore.

La registra nei log una volta per ogni acquisizione. La riga contiene port forwarded is 45678 oppure no port forwarded quando la richiesta non restituisce alcun valore.

docker logs gluetun 2>&1 | grep -i "port forwarded"

Scrive il numero nel file indicato da VPN_PORT_FORWARDING_STATUS_FILE, che per impostazione predefinita è /tmp/gluetun/forwarded_port. Il file contiene una porta per riga, viene scritto con la modalità 0644 e riceve come proprietari il PUID e il PGID del container. Quando l'inoltro si interrompe, gluetun svuota il file invece di eliminarlo. Un consumer può quindi leggere un file vuoto anziché ricevere un errore perché il file non esiste.

docker exec gluetun cat /tmp/gluetun/forwarded_port

Espone il valore sul control server, che per impostazione predefinita è in ascolto su :8000 ed è configurato tramite HTTP_CONTROL_SERVER_ADDRESS.

curl -s http://127.0.0.1:8000/v1/portforward
{"port":45678,"ports":[45678]}

Gluetun apre inoltre quella porta nel proprio firewall sull'interfaccia VPN. Per questo, FIREWALL_VPN_INPUT_PORTS non è necessario quando l'integrazione nativa svolge questa funzione. Questa variabile serve nell'altro caso: quando gluetun non può interrogare un provider che assegna una porta statica fuori banda e occorre consentirla manualmente.

Uno dei tre metodi è persistente, mentre gli altri due non lo sono. La documentazione upstream indica il file di stato come deprecato in v4.0.0, e GET /v1/openvpn/portforwarded risponde già con 301 Moved Permanently indicando /v1/portforward. Per le nuove implementazioni è consigliabile leggere il control server.

Perché il client deve ricevere la porta a ogni riconnessione

Un client torrent memorizza la porta su cui è in ascolto nella propria configurazione e mantiene quel numero anche dopo i riavvii. La porta inoltrata è una proprietà della sessione VPN. Dopo una riconnessione, i due numeri non coincidono: il provider associa quindi una porta su cui non è in ascolto alcun servizio, mentre il client utilizza una porta che il provider non inoltra. Le riconnessioni non sono rare: possono essere causate dal riavvio di un container, da una modifica del server, da una disconnessione del tunnel che il controllo di integrità di gluetun riavvia oppure dal mancato rinnovo di un lease. Il risultato è una configurazione che ieri era raggiungibile e oggi non lo è più, senza errori nei log.

La porta deve quindi essere applicata nel momento in cui gluetun la acquisisce. Esistono due modalità per configurare questo comportamento, che differiscono per il processo incaricato di eseguire l'operazione.

Opzione 1: gluetun imposta la porta con un comando up

VPN_PORT_FORWARDING_UP_COMMAND viene eseguito quando il port forwarding diventa disponibile, mentre VPN_PORT_FORWARDING_DOWN_COMMAND viene eseguito quando termina. Gluetun sostituisce {{PORT}} (la prima porta), {{PORTS}} (tutte le porte, separate da virgole) e {{VPN_INTERFACE}} (il nome dell'interfaccia del tunnel, tun0 per impostazione predefinita) prima di eseguire il comando. La sintassi della shell richiede un wrapper /bin/sh -c esplicito. Questo è l'esempio upstream per qBittorrent, scritto come due voci di ambiente di Compose:

      - VPN_PORT_FORWARDING_UP_COMMAND=/bin/sh -c 'wget -O- -nv --retry-connrefused --post-data "json={\"listen_port\":{{PORT}},\"current_network_interface\":\"{{VPN_INTERFACE}}\",\"random_port\":false,\"upnp\":false}" http://127.0.0.1:8080/api/v2/app/setPreferences'
      - VPN_PORT_FORWARDING_DOWN_COMMAND=/bin/sh -c 'wget -O- -nv --retry-connrefused --post-data "json={\"listen_port\":0,\"current_network_interface\":\"lo\"}" http://127.0.0.1:8080/api/v2/app/setPreferences'

Ogni campo di questa chiamata ha uno scopo. listen_port è la nuova porta. current_network_interface associa qBittorrent al tunnel. Impostare random_port su false impedisce a qBittorrent di scegliere una propria porta al successivo avvio. Impostare upnp su false impedisce al programma di tentare di mappare una porta tramite un router che non è presente.

Questo approccio richiede due condizioni. L'interfaccia web di qBittorrent deve essere abilitata e in ascolto sulla porta 8080. La condivisione del namespace di rete di gluetun consente a qBittorrent di rispondere su 127.0.0.1:8080 dall'interno del container gluetun. Inoltre, Bypass authentication for clients on localhost (bypass_local_auth) deve essere abilitato, perché il comando non invia credenziali. Il comando down è necessario perché qBittorrent non ristabilisce sempre la porta dopo una disconnessione.

Il comando viene eseguito all'interno del container gluetun, basato su Alpine e dotato di wget. Nell'immagine non è presente curl. Un comando che richiama un binario assente nell'immagine fallisce ogni volta che il port forwarding diventa disponibile.

Opzione 2: un processo esterno a gluetun legge la porta

L’altro schema usa un processo di piccole dimensioni accanto a gluetun. Il processo recupera la porta e la comunica al client tramite la relativa API. Leggetela dal control server:

port=$(curl -s http://127.0.0.1:8000/v1/portforward | jq -r .port)

In alternativa, leggete il file se il processo può accedervi. /tmp/gluetun/forwarded_port si trova all’interno del container gluetun. Un sidecar deve quindi usare un volume condiviso, montato su /tmp/gluetun in entrambi i container. In alternativa, impostate VPN_PORT_FORWARDING_STATUS_FILE su un percorso all’interno di un volume già montato.

L’autenticazione è importante. Nella v3.41.3, la route GET /v1/portforward appartiene a un ruolo predefinito denominato public con auth = "none". Di conseguenza, risponde senza credenziali e gluetun registra un avviso che inizia con route GET /v1/portforward is unprotected by default, please set up authentication. In una versione successiva, il progetto upstream eliminerà questa possibilità. La documentazione attuale del control server descrive già tutte le route come private per impostazione predefinita. Definite ora un ruolo nel file montato tramite bind mount su /gluetun/auth/config.toml:

roles = [
  { name = "qbittorrent", routes = ["GET /v1/portforward"], auth = "apikey", apikey = "myapikey" }
]

Generate una chiave con docker run --rm qmcgaw/gluetun:v3.41.3 genkey e inviatela nell’header X-API-Key. HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE definisce un ruolo predefinito come una variabile d’ambiente con codifica JSON, applicata a tutte le route non coperte dai ruoli presenti nel file. Dopo aver definito un ruolo qualsiasi, la v3.41.3 non applica più il ruolo incorporato public. Ogni route chiamata in seguito deve quindi essere inclusa in un ruolo oppure nel ruolo predefinito configurato. Se non definite alcun ruolo, il ruolo incorporato public copre anche PUT /v1/vpn/status. In questo caso, la porta 8000 pubblicata senza configurazione di autenticazione consente a chiunque possa raggiungerla di controllare lo stato della VPN. Stabilite deliberatamente l’ambito di esposizione quando valutate come raggiungere gluetun dall’host e dagli altri container.

Scegliete il comando up quando il client espone un’API che può essere gestita con una sola chiamata wget. Il comando viene eseguito una volta per ogni evento e non richiede un processo persistente. Scegliete un processo esterno quando il client richiede una procedura di accesso, la riscrittura di un file di configurazione o un riavvio. In uno stack arr dietro un unico container gluetun, il risultato è in genere un solo processo di polling, perché soltanto il client torrent utilizza la porta.

La trappola: condividere lo spazio dei nomi non imposta la porta di ascolto

Questo errore fa perdere più tempo di qualsiasi altro. network_mode: "service:gluetun" inserisce il client nello spazio dei nomi di rete di gluetun, quindi il client usa l'indirizzo IP della VPN, le route del tunnel e le regole firewall di gluetun. Nessuno di questi elementi imposta la porta di ascolto del client. Gluetun apre la porta inoltrata sull'interfaccia VPN, i pacchetti destinati a quella porta arrivano nello spazio dei nomi e, se il client è in ascolto su una porta diversa, il kernel non ha alcun processo a cui consegnarli. La connessione viene rifiutata oppure va in timeout, mentre tutti i controlli sul traffico in uscita risultano corretti. La porta inoltrata e la porta di ascolto del client sono due numeri distinti; il compito consiste nel mantenerli uguali.

Confrontale invece di procedere per tentativi. Entrambi i comandi vengono eseguiti nello stesso spazio dei nomi:

docker exec gluetun cat /tmp/gluetun/forwarded_port
docker exec gluetun wget -qO- http://127.0.0.1:8080/api/v2/app/preferences | grep -o '"listen_port":[0-9]*'

Un'altra impostazione porta spesso nella direzione sbagliata. VPN_PORT_FORWARDING_LISTENING_PORT reindirizza il traffico in ingresso dalla porta inoltrata a una porta locale fissa usando iptables. La documentazione upstream sconsiglia di usarla con i client torrent, perché il client comunica ai tracker e ai peer la propria porta di ascolto e quindi la swarm apprende il numero errato.

Come dimostrare che la porta inoltrata è raggiungibile

L'indicatore di connessione del client riflette le connessioni in uscita ai tracker, quindi può diventare verde anche se nessuno riesce a raggiungerti. Esegui il test con un listener sotto il tuo controllo, da una rete esterna al tunnel. Il progetto upstream pubblica un piccolo strumento per questo scopo. Arresta prima il client torrent, perché due processi non possono associare la stessa porta.

docker stop qbittorrent
docker exec -it gluetun /bin/sh

All'interno del container, sostituisci amd64 con l'architettura della CPU e 4567 con la porta inoltrata:

wget -qO port-checker https://github.com/qdm12/port-checker/releases/download/v0.4.0/port-checker_0.4.0_linux_amd64
chmod +x port-checker
./port-checker --listening-address=":4567"

Ora individua l'indirizzo di uscita utilizzato da gluetun. La risposta è in formato JSON e l'indirizzo si trova nel campo public_ip.

curl -s http://127.0.0.1:8000/v1/publicip/ip

Quella richiesta senza credenziali risponde in tre casi: con v3.41.3 in esecuzione senza configurazione di autenticazione, quando il ruolo integrato public la autorizza; con una configurazione di autenticazione che include GET /v1/publicip/ip in un ruolo dotato di auth = "none"; oppure con HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE='{"auth":"none"}' quando nessun ruolo nel file copre la route. La documentazione upstream definisce none come autenticazione non richiesta. Se invece hai definito un ruolo apikey come nell'Opzione 2, aggiungi GET /v1/publicip/ip al suo routes e invia la relativa chiave, ad esempio curl -s -H "X-API-Key: myapikey" http://127.0.0.1:8000/v1/publicip/ip.

Apri http://<that address>:4567 da un dispositivo che non si trova sulla stessa VPN. È sufficiente uno smartphone con la rete dati mobile attiva. Una pagina che mostra l'indirizzo IP e lo user agent del browser, insieme a una richiesta corrispondente registrata da port-checker, dimostra che il traffico TCP in ingresso raggiunge il namespace. Un timeout indica che non lo raggiunge e che la causa si trova a un livello superiore rispetto al client. Arresta lo strumento con CTRL+C, esci dalla shell con exit e avvia nuovamente il client. Questo controllo verifica soltanto TCP. Il traffico DHT (distributed hash table) e uTP usa UDP sulla stessa porta numerica, ma questo test non lo verifica.

Modalità di errore e stringhe visualizzate

Nel log non compare alcuna riga relativa alla porta. Nessun componente ha richiesto una porta. Verificate con docker exec gluetun printenv | grep PORT_FORWARDING che la variabile sia effettivamente arrivata nel container, perché definirla nel servizio Compose sbagliato è una causa comune.

Gluetun non si avvia e segnala un problema relativo al provider. VPN_PORT_FORWARDING_PROVIDER viene convalidato rispetto ai quattro nomi supportati. Un errore di digitazione arresta il container invece di eseguirlo senza inoltro.

Il log contiene no port forwarded. Gluetun ha inviato la richiesta, ma il provider non ha restituito alcun valore. Con ProtonVPN, di solito significa che NAT-PMP non era abilitato nella configurazione generata oppure che il piano non include il port forwarding. Con Private Internet Access, di solito significa che il server selezionato non lo supporta.

La porta viene assegnata, ma non è possibile stabilire connessioni in ingresso. Confrontate la porta inoltrata con la porta di ascolto del client usando i due comandi precedenti. Se coincidono, verificate che il client sia associato all'interfaccia del tunnel e che l'opzione della porta casuale sia disabilitata, perché a ogni avvio questa opzione riscrive la porta di ascolto.

Il comando up sembra non fare nulla. Eseguite il comando esatto all'interno del container per visualizzare l'errore: docker exec gluetun /bin/sh -c '<your command>'. curl: not found è il risultato consueto, perché l'immagine include soltanto wget.

401 Unauthorized dal control server. Nessun ruolo gestisce la route chiamata oppure tutti i ruoli corrispondenti rifiutano la richiesta perché le credenziali sono mancanti o errate. Un HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE configurato gestisce le route non elencate nel file. Ogni route è definita da metodo e path, ad esempio GET /v1/portforward. Una route definita soltanto come /v1/portforward non produce un 401: gluetun termina invece durante l'avvio.

Una porta diversa su Private Internet Access dopo ogni riavvio. Eseguite il bind mount di /gluetun per mantenere lo stato della porta salvato dopo il riavvio. Senza quel volume, gluetun richiede una nuova porta a ogni avvio.

FAQ

Perché i torrent vengono scaricati, ma non ricevo mai connessioni in ingresso?

Senza una porta inoltrata, il provider VPN non dispone di una regola NAT che invii i pacchetti in ingresso su una porta qualsiasi al tuo tunnel, quindi le connessioni che non hai avviato tu vengono scartate all'indirizzo di uscita. I download continuano a funzionare perché è il tuo client ad aprire queste connessioni e può raggiungere qualsiasi peer connettibile. Il seeding e l'ingresso negli swarm ne risentono, perché entrambi dipendono dalla possibilità che altri peer ti raggiungano. La soluzione consiste nell'utilizzare un provider che offra il port forwarding, VPN_PORT_FORWARDING=on in gluetun e applicare la porta risultante alla porta in ascolto del client.

gluetun funziona con il port forwarding di qualsiasi provider VPN?

No. gluetun v3.41.3 integra nativamente quattro provider: Private Internet Access, ProtonVPN, Perfect Privacy e PrivateVPN. Qualsiasi provider non incluso nell'elenco non supera la validazione per VPN_PORT_FORWARDING_PROVIDER e il container si arresta all'avvio. Se il provider assegna una porta statica tramite il proprio pannello di controllo, gluetun non può richiederla al suo posto, ma FIREWALL_VPN_INPUT_PORTS consente a quella porta fissa di attraversare il firewall di gluetun. Le policy dei provider cambiano, quindi consulta la pagina aggiornata del provider prima di acquistare un piano per questo scopo.

Devo aggiornare la porta dopo ogni riconnessione?

Sì, e l'aggiornamento dovrebbe essere automatico. La porta inoltrata appartiene alla sessione VPN, quindi un riavvio del container, un cambio di server o un rinnovo del lease non riuscito possono produrre un nuovo numero, mentre il client conserva la porta nella propria configurazione. Puoi lasciare che gluetun la comunichi tramite VPN_PORT_FORWARDING_UP_COMMAND, che viene eseguito non appena il port forwarding è attivo, oppure eseguire un processo che legge GET /v1/portforward dal control server e scrive il valore nel client tramite la relativa API.

Come posso verificare che la porta inoltrata sia effettivamente aperta?

Esegui un listener su quella porta esatta all'interno del network namespace di gluetun e collegati a esso dall'esterno della VPN. Arresta prima il client torrent per liberare la porta, quindi esegui il binario port-checker upstream all'interno del container gluetun con --listening-address=":<port>". Recupera l'indirizzo di uscita da curl -s http://127.0.0.1:8000/v1/publicip/ip, aggiungendo -H "X-API-Key: <key>" se il ruolo che include GET /v1/publicip/ip usa auth = "apikey", e apri http://<address>:<port> da un telefono con la rete dati mobile attiva. La comparsa di una richiesta nel log di port-checker dimostra che il traffico TCP in ingresso arriva. Un timeout indica che non arriva, indipendentemente da ciò che mostra l'icona di stato del client.

Questo articolo ti è stato utile?