Gluetun: configurar port forwarding para torrents

Por que nada consegue estabelecer ligação sem uma porta encaminhada

O encaminhamento de portas do Gluetun pede ao fornecedor de VPN que associe uma porta pública no endereço de saída do fornecedor ao seu contentor. Esta é a única forma de outro peer iniciar uma ligação ao seu cliente de torrents. Sem esse mapeamento, o túnel funciona, os downloads decorrem e nada chega espontaneamente. Todas as ligações funcionais são iniciadas primeiro pelo seu cliente.

O mecanismo é o NAT (tradução de endereços de rede). O seu contentor partilha o endereço de saída do fornecedor com muitos outros clientes. Quando o seu cliente inicia uma ligação para o exterior, o fornecedor regista esse fluxo e envia as respostas de volta pelo túnel. Uma ligação recebida de um peer desconhecido não corresponde a nenhum fluxo registado. Por isso, o pacote chega ao endereço de saída e é descartado nesse ponto. O seu cliente continua a conseguir ligar-se a todos os peers que aceitam ligações, pelo que os downloads terminam e o problema pode passar despercebido. É durante o seeding que o problema se manifesta, porque um seeder é uma máquina à qual outras pessoas se ligam.

Uma porta de entrada aberta altera duas coisas. Entra mais rapidamente num swarm, porque os peers que não conseguem aceitar ligações também passam a conseguir ligar-se a si. Além disso, pode fazer upload para esses peers.

Por que a maioria dos provedores de VPN não oferece encaminhamento de portas

Uma porta encaminhada é um recurso escasso num endereço partilhado. O provedor reserva um número de porta num IP de saída para um cliente e passa a responder pelo que esse cliente fizer através dela. Vários provedores de grande dimensão removeram esse recurso e apontaram o tratamento de abusos como motivo. Considere o suporte como uma questão de categoria, não como uma caixa de seleção: pergunte se o provedor oferece encaminhamento de portas atualmente, no seu plano e nos servidores que pode realmente selecionar.

Quando existe encaminhamento, a porta é dinâmica. Ela pertence à sessão VPN, não à sua conta, e pode ter um número diferente depois de cada reconexão. A Private Internet Access fornece uma porta assinada que o gluetun atualiza, e a documentação upstream informa que a mesma porta é mantida durante 60 dias, desde que faça bind mount do diretório /gluetun para que o estado sobreviva a um reinício. A ProtonVPN atribui uma porta aleatória através de NAT-PMP (protocolo de mapeamento de portas NAT), com um lease curto que tem de ser renovado continuamente. Por isso, definir a porta uma única vez no cliente nunca funciona de forma permanente.

Provedores aos quais o gluetun pode solicitar uma porta

A partir do gluetun v3.41.3, lançado em 30 July 2026, a integração nativa valida quatro nomes de provedores: Private Internet Access, ProtonVPN, Perfect Privacy e PrivateVPN. Ative-a com VPN_PORT_FORWARDING=on, que é off por padrão. Guias mais antigos usam PORT_FORWARDING ou PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING. Ambos continuam a funcionar nesta versão como nomes compatíveis com versões anteriores, mas serão removidos.

Dois detalhes do provedor determinam se a solicitação pode ser concluída. O ProtonVPN exige um plano pago, e o NAT-PMP precisa estar ativado: habilite NAT-PMP (Port Forwarding) nas opções da VPN ao gerar a configuração do WireGuard ou acrescente +pmp ao seu nome de utilizador quando usar OpenVPN. No OpenVPN, o Private Internet Access tem PORT_FORWARD_ONLY, que restringe a seleção de servidores aos servidores compatíveis com port forwarding. Assim, você não se conecta a um servidor que nunca ofereceu esse recurso. WireGuard e OpenVPN diferem na forma como a porta é solicitada, portanto consulte a página do seu provedor antes de escolher.

Quando o gluetun usa uma configuração personalizada em vez de um provedor integrado, VPN_PORT_FORWARDING_PROVIDER identifica a API que o gluetun deve chamar. A página oficial do Private Internet Access associa essa variável a VPN_PORT_FORWARDING_USERNAME e VPN_PORT_FORWARDING_PASSWORD, que transportam as credenciais da conta necessárias para a solicitação da porta.

Ative o encaminhamento de portas do gluetun no docker compose

Isto pressupõe que o túnel já funciona. Se não funcionar, comece por encaminhar o tráfego dos contentores Docker através do gluetun e volte quando os downloads estiverem a funcionar.

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

Fixe a tag. qmcgaw/gluetun:latest acompanha o branch master, onde os componentes internos do encaminhamento de portas estão a sofrer alterações para a v4. Uma imagem sem tag fixa pode alterar o comportamento na próxima docker compose pull. Mantenha a chave privada fora do ficheiro compose com um ficheiro de ambiente para segredos do compose.

Onde o gluetun escreve a porta encaminhada

O Gluetun expõe a porta em três locais, e todos contêm o mesmo valor.

Ele regista a porta uma vez por aquisição. A linha é port forwarded is 45678, e no port forwarded quando o pedido não produz nenhum valor.

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

Ele escreve o número no ficheiro indicado por VPN_PORT_FORWARDING_STATUS_FILE, que por predefinição é /tmp/gluetun/forwarded_port. O ficheiro contém uma porta por linha, é escrito com o modo 0644 e recebe como proprietário o PUID e o PGID do contentor. Quando o encaminhamento para, o gluetun limpa o ficheiro em vez de o apagar, para que um consumidor possa ler um ficheiro vazio em vez de encontrar um ficheiro inexistente.

docker exec gluetun cat /tmp/gluetun/forwarded_port

Ele disponibiliza o valor no servidor de controlo, que escuta em :8000 por predefinição e é configurado por HTTP_CONTROL_SERVER_ADDRESS.

curl -s http://127.0.0.1:8000/v1/portforward

{"port":45678,"ports":[45678]}

O Gluetun também abre essa porta na sua própria firewall da interface VPN. Por isso, FIREWALL_VPN_INPUT_PORTS não é necessário enquanto a integração nativa estiver a tratar do encaminhamento. Essa variável aplica-se ao outro caso: um fornecedor que o gluetun não consegue consultar, quando recebeu uma porta estática por outro canal e tem de a permitir manualmente.

Uma destas três opções é persistente e as outras duas não são. A documentação upstream marca o ficheiro de estado como obsoleto na v4.0.0, e GET /v1/openvpn/portforwarded já responde com 301 Moved Permanently, apontando para /v1/portforward. O código novo deve ler o servidor de controlo.

Por que o cliente tem de receber a porta em cada reconexão

Um cliente BitTorrent guarda a sua porta de escuta na própria configuração e mantém esse número após os reinícios. A porta encaminhada é uma propriedade da sessão VPN. Depois de uma reconexão, os dois números deixam de coincidir. O fornecedor encaminha então uma porta onde nada está à escuta, enquanto o cliente escuta numa porta que não está encaminhada. As reconexões não são raras: podem ocorrer devido ao reinício de um contentor, a uma alteração no servidor, a uma ligação interrompida cujo túnel é reiniciado pela verificação de estado do gluetun ou a uma concessão que não pôde ser renovada. O resultado é uma configuração que estava acessível ontem e hoje está silenciosamente inacessível, sem qualquer erro em nenhum dos logs.

Por isso, a porta tem de ser aplicada no momento em que o gluetun a obtém. Há duas formas de fazer essa ligação, e diferem no processo que executa o trabalho.

Opção 1: o gluetun publica a porta com um comando up

VPN_PORT_FORWARDING_UP_COMMAND é executado quando o encaminhamento de portas é ativado, e VPN_PORT_FORWARDING_DOWN_COMMAND é executado quando é desativado. O Gluetun substitui {{PORT}} (a primeira porta), {{PORTS}} (todas as portas, separadas por vírgulas) e {{VPN_INTERFACE}} (o nome da interface do túnel, tun0 por predefinição) antes de executar o comando. A sintaxe do shell requer um invólucro /bin/sh -c explícito. Este é o exemplo do qBittorrent a montante, escrito como duas entradas de ambiente do 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'

Cada campo dessa chamada tem uma função. listen_port é a nova porta. current_network_interface associa o qBittorrent ao túnel. Definir random_port como false impede que o qBittorrent escolha a sua própria porta no arranque seguinte. Definir upnp como false impede que tente mapear uma porta através de um router que não existe.

Esta abordagem tem dois requisitos. A interface web do qBittorrent deve responder em 127.0.0.1:8080 a partir do interior do contentor gluetun. Isto acontece automaticamente quando o cliente partilha o namespace de rede do gluetun. Além disso, Bypass authentication for clients on localhost (bypass_local_auth) deve estar ativado, porque o comando não envia credenciais. O comando down é necessário porque o qBittorrent nem sempre restabelece a porta depois de uma desconexão.

O comando é executado dentro do contentor gluetun, baseado em Alpine, que inclui wget. Essa imagem não contém curl. Um comando que indique um binário inexistente na imagem falha sempre que o encaminhamento de portas é ativado.

Opção 2: um processo fora do gluetun lê a porta

O outro padrão executa um processo pequeno junto do gluetun. Esse processo obtém a porta e envia-a para o cliente através da própria API do cliente. Leia-a a partir do servidor de controlo:

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

Também pode ler o ficheiro, se o processo tiver acesso a ele. /tmp/gluetun/forwarded_port encontra-se dentro do contentor gluetun. Por isso, um sidecar precisa de um volume partilhado montado em /tmp/gluetun nos dois contentores. Em alternativa, pode apontar VPN_PORT_FORWARDING_STATUS_FILE para um caminho dentro de um volume que já esteja montado.

A autenticação é importante. Na versão v3.41.3, a rota GET /v1/portforward pertence a uma função predefinida chamada public, com auth = "none". Por isso, responde sem credenciais, e os logs do gluetun registam um aviso que começa por route GET /v1/portforward is unprotected by default, please set up authentication. O projeto upstream vai fechar esse acesso numa versão posterior. Defina já uma função no ficheiro montado através de bind em /gluetun/auth/config.toml:

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

Gere uma chave com docker run --rm qmcgaw/gluetun:v3.41.3 genkey e envie-a no cabeçalho X-API-Key. HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE faz o mesmo que uma variável de ambiente codificada em JSON quando preferir não montar um ficheiro. Publicar a porta 8000 sem uma função permite que qualquer pessoa com acesso a ela controle o estado da VPN. Por isso, decida deliberadamente até onde essa porta deve ser acessível ao definir como aceder ao gluetun a partir do host e de outros contentores.

Escolha o comando up quando o cliente expuser uma API que uma chamada wget possa controlar. O comando é executado exatamente uma vez por evento e não deixa nada em execução. Escolha um processo externo quando o cliente precisar de um fluxo de início de sessão, de reescrever um ficheiro de configuração ou de reiniciar. Em uma stack de serviços de arranque atrás de um único contentor gluetun, isto normalmente resulta num único processo de consulta, porque só o cliente de torrents precisa da porta.

A armadilha: partilhar o namespace não define a porta de escuta

Esta falha é a que mais tempo desperdiça. network_mode: "service:gluetun" coloca o cliente no namespace de rede do gluetun, por isso o cliente recebe o endereço VPN, as rotas do túnel e as regras de firewall do gluetun. Nada disso define a porta de escuta do cliente. O gluetun abre a porta encaminhada na interface VPN, os pacotes destinados a essa porta chegam ao namespace e, se o cliente escutar numa porta diferente, o kernel não tem nenhum processo para os receber. A ligação é recusada ou expira, embora todas as verificações de saída indiquem um estado normal. A porta encaminhada e a porta de escuta do cliente são dois números distintos. A tarefa consiste em mantê-los iguais.

Compare os valores em vez de os adivinhar. Ambos os comandos são executados no mesmo namespace:

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]*'

Há outra configuração que encaminha as pessoas na direção errada. VPN_PORT_FORWARDING_LISTENING_PORT redireciona o tráfego recebido na porta encaminhada para uma porta local fixa através do iptables. A documentação do projeto recomenda não usar esta opção com clientes de torrents, porque o cliente anuncia a sua própria porta de escuta aos trackers e peers. Assim, o swarm fica a conhecer o número errado.

Como provar que a porta encaminhada está acessível

O indicador de ligação do próprio cliente reflete as ligações de saída aos trackers. Por isso, pode ficar verde mesmo quando ninguém consegue ligar-se a si. Faça o teste com um listener que controla, a partir de uma rede fora do túnel. O projeto upstream fornece uma ferramenta pequena para este fim. Pare primeiro o cliente torrent, porque dois processos não podem associar-se à mesma porta.

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

Dentro do contentor, altere amd64 para a arquitetura da sua CPU e 4567 para a porta encaminhada:

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"

Agora descubra o endereço de saída que o gluetun está a utilizar. A resposta está em JSON e o endereço encontra-se no campo public_ip.

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

Abra http://<that address>:4567 a partir de um dispositivo que não esteja na mesma VPN. Um telemóvel com dados móveis funciona. Uma página que mostre o endereço IP e o user agent do seu browser, juntamente com um pedido correspondente registado pelo port-checker, significa que o TCP de entrada chega ao namespace. Um timeout significa que não chega, e a causa está acima do cliente. Pare a ferramenta com CTRL+C, saia da shell com exit e inicie novamente o cliente. Este teste verifica apenas TCP. O DHT (distributed hash table) e o tráfego uTP utilizam UDP no mesmo número de porta, o que este teste não abrange.

Modos de falha e mensagens que verá

Não existe qualquer linha de porta no log. Nenhum pedido de porta foi feito. Confirme se a variável chegou efetivamente ao container com docker exec gluetun printenv | grep PORT_FORWARDING, pois definir uma variável no serviço errado do compose é uma causa comum.

Gluetun recusa iniciar e apresenta uma mensagem sobre o provider. VPN_PORT_FORWARDING_PROVIDER é validado com base nos quatro nomes suportados. Um erro de digitação faz o container parar, em vez de funcionar silenciosamente sem encaminhamento.

O log indica no port forwarded. O Gluetun fez o pedido, mas o provider não devolveu nada. No ProtonVPN, isso normalmente significa que NAT-PMP não estava ativado na configuração gerada ou que o plano não inclui port forwarding. No Private Internet Access, normalmente significa que o servidor selecionado não oferece essa funcionalidade.

A porta é atribuída, mas não é possível estabelecer ligações de entrada. Compare a porta encaminhada com a porta de escuta do cliente usando os dois comandos acima. Se forem iguais, verifique se o cliente está associado à interface do túnel e se a opção de porta aleatória está desativada, pois essa opção altera a porta de escuta em cada arranque.

O comando up parece não fazer nada. Execute o comando exato dentro do container para ver o erro: docker exec gluetun /bin/sh -c '<your command>'. curl: not found é o resultado habitual, porque a imagem inclui apenas wget.

401 Unauthorized a partir do servidor de controlo. Definiu uma configuração de autenticação, mas a role não inclui a route que está a chamar. As routes são correspondidas pela combinação de método e path. Por isso, uma role que inclua apenas /v1/portforward não abrange GET /v1/portforward.

Uma porta diferente no Private Internet Access após cada reinício. Faça bind mount de /gluetun para que o estado da porta guardado sobreviva ao reinício. Sem esse volume, o Gluetun solicita uma porta nova em cada arranque.

FAQ

Por que os meus torrents fazem download, mas nunca recebem ligações de entrada?

Sem uma porta encaminhada, o fornecedor de VPN não tem uma regra NAT que envie pacotes de entrada de nenhuma porta para o seu túnel. Por isso, as ligações que não foram iniciadas por si são descartadas no endereço de saída. Os downloads continuam a funcionar porque o seu cliente abre essas ligações e consegue contactar qualquer peer que aceite ligações. O seeding e a entrada em swarms ficam prejudicados, porque ambos dependem de outros utilizadores conseguirem contactá-lo. A solução é usar um fornecedor que ofereça encaminhamento de portas, configurar VPN_PORT_FORWARDING=on no gluetun e aplicar a porta resultante à porta de escuta do cliente.

O gluetun funciona com o encaminhamento de portas de qualquer fornecedor de VPN?

Não. O gluetun v3.41.3 tem integração nativa com quatro fornecedores: Private Internet Access, ProtonVPN, Perfect Privacy e PrivateVPN. Qualquer fornecedor fora dessa lista falha a validação de VPN_PORT_FORWARDING_PROVIDER e o contentor termina durante o arranque. Se o seu fornecedor atribuir uma porta estática através do próprio painel de controlo, o gluetun não pode solicitá-la por si. No entanto, FIREWALL_VPN_INPUT_PORTS permite essa porta fixa através da firewall do gluetun. As políticas dos fornecedores mudam, por isso consulte a página atual do fornecedor antes de comprar um plano para este fim.

Tenho de atualizar a porta depois de cada reconexão?

Sim, e essa atualização deve ser automática. A porta encaminhada pertence à sessão da VPN. Por isso, um reinício do contentor, uma alteração de servidor ou uma renovação de concessão falhada pode gerar um número novo, enquanto o cliente mantém a porta guardada na própria configuração. Pode deixar o gluetun enviá-la através de VPN_PORT_FORWARDING_UP_COMMAND, que é executado assim que o encaminhamento fica ativo. Em alternativa, execute um processo pequeno que leia GET /v1/portforward do servidor de controlo e escreva o valor no cliente através da respetiva API.

Como verifico se a porta encaminhada está realmente aberta?

Execute um listener nessa porta exata dentro do namespace de rede do gluetun e ligue-se a ele a partir do exterior da VPN. Pare primeiro o cliente de torrents para libertar a porta. Depois, execute o binário upstream de verificação de portas dentro do contentor gluetun com --listening-address=":<port>". Obtenha o endereço de saída através de curl -s http://127.0.0.1:8000/v1/publicip/ip e abra http://<address>:<port> num telemóvel com dados móveis. O aparecimento de um pedido no log do verificador de portas prova que o tráfego TCP de entrada chegou. Um timeout significa que não chegou, independentemente do ícone de estado apresentado pelo cliente.