SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Gluetun: acessar o host e outros containers

Entenda por que o container atrás do Gluetun não tem interfaces próprias: publique portas no Gluetun e libere apenas as sub-redes necessárias fora do túnel.

O que acontece quando um container entra na rede do gluetun

Um container que define network_mode: service:gluetun não tem interfaces de rede próprias. Ele entra no namespace de rede do gluetun. Por isso, a publicação de portas e as regras de firewall deixam de ser propriedades desse container e passam a ser propriedades do serviço gluetun. Todas as respostas abaixo resultam desse facto.

Um namespace de rede é uma cópia privada da pilha de rede mantida pelo kernel. Tem as suas próprias interfaces, tabela de encaminhamento, regras de firewall e sockets em escuta. Por predefinição, o Docker atribui um namespace a cada container. Quando escreve network_mode: service:gluetun, o Docker ignora esse passo e coloca o novo container no namespace que o gluetun já possui. O container mantém o seu próprio sistema de ficheiros, mas não tem o seu próprio /etc/hosts nem /etc/resolv.conf. O Docker fornece-lhe os mesmos ficheiros que o gluetun utiliza, e isso será importante mais adiante.

Pode verificar isto diretamente.

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

Isto apresenta container:, seguido do ID do container gluetun. Num container normal, apresentaria bridge. Este guia continua a partir do ponto em que encaminhar o tráfego do Docker através de uma VPN com o gluetun termina: o túnel funciona, mas agora nada consegue comunicar com o container.

Publique a porta no gluetun, não na aplicação

Deixe um bloco ports: no serviço que define network_mode e o Docker recusa-se a criar o contentor:

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

O motivo é direto. Publicar uma porta significa adicionar uma regra NAT (network address translation) que encaminha uma porta do anfitrião para o namespace de rede próprio de um contentor, e este contentor não tem um. Mova o mapeamento para o serviço gluetun. O número da porta não muda, porque a aplicação continua a escutar nessa porta dentro do namespace partilhado.

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

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

Um bloco expose: no serviço dependente falha da mesma forma, com conflicting options: port exposing and the container type network mode, e um bloco networks: nesse serviço também impede o arranque: o Compose indica que o serviço declara network_mode e networks, que são mutuamente exclusivos, e recusa-se a carregar o ficheiro.

Há uma consequência que surge mais tarde. Todos os contentores no namespace partilham um único espaço de portas. Por isso, duas aplicações que usem 8080 por predefinição entram em conflito, e a segunda a arrancar falha com um erro de endereço já em uso. Altere uma delas na respetiva configuração, por exemplo a variável WEBUI_PORT na imagem LinuxServer qBittorrent, e publique o novo número no gluetun.

Como os containers atrás do gluetun comunicam entre si?

Dentro do namespace, eles já partilham uma interface de loopback. Um container atrás do gluetun alcança o seu container irmão em 127.0.0.1:<port> sem envolver nenhuma rede Docker.

A partir do exterior do namespace, o container não tem nome. O DNS integrado do Docker resolve o nome de um serviço para o endereço desse serviço numa rede definida pelo utilizador, mas este container não tem endereço em nenhuma rede. Por isso, um container normal, como o Sonarr, não alcança o cliente de torrents em http://qbittorrent:8080. Alcança-o em http://gluetun:8080, porque o socket está a escutar no namespace do gluetun, no endereço do gluetun. Isto surpreende quem conhece o funcionamento das redes e dos nomes de serviço do Docker Compose e espera que se aplique a nomenclatura habitual. Também funciona sem publicar nada no host, porque ambos os containers estão na mesma rede do Compose.

Verifique o DNS antes de depurar qualquer outra coisa. O gluetun executa o seu próprio servidor DNS dentro do namespace, e o Docker fornece a todos os containers atrás do gluetun o mesmo ficheiro /etc/resolv.conf que fornece ao gluetun. Assim, as consultas da aplicação passam pelo resolvedor do gluetun, e não pelo resolvedor do host. Por predefinição, esse resolvedor também recusa respostas que apontem para endereços privados. É por isso que um nome que resolve no host pode falhar dentro do container. A documentação do gluetun indica que esses nomes de host têm de ser listados em DNS_REBINDING_PROTECTION_EXEMPT_HOSTNAMES.

docker exec qbittorrent cat /etc/resolv.conf

Como acedo a um serviço em execução no Docker host?

Use host.docker.internal. Requer duas definições, ambas no serviço gluetun, porque há dois problemas diferentes.

O nome vem primeiro. Um container atrás do gluetun lê o /etc/hosts do gluetun, e o Docker rejeita uma entrada extra_hosts num serviço que define network_mode com conflicting options: custom host-to-IP mapping and the network mode. Por isso, a entrada pertence ao gluetun, e todos os containers nesse namespace conseguem vê-la.

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

host-gateway é um valor especial que o Docker substitui pelo endereço interno do próprio host. Numa instalação normal do Docker em Linux, esse é o endereço da bridge docker0, normalmente 172.17.0.1. Confirme o seu com ip -4 addr show docker0 na VPS. O Docker Desktop resolve este nome automaticamente. É por isso que os guias escritos para um laptop omitem a linha extra_hosts e o mesmo ficheiro falha depois num servidor.

A rota vem em segundo lugar. Adicionar o nome apenas informa o container sobre o endereço a utilizar. O pacote continua a sair pela rota predefinida do gluetun, que é o túnel, e a firewall do gluetun descarta-o. O sintoma é uma ligação que fica pendurada e depois expira, em vez de ser recusada. Uma recusa significa que o pacote chegou e algo respondeu negativamente. Um timeout significa que nunca chegou.

  gluetun:
    environment:
      - FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32

Depois, confirme que o serviço no host está efetivamente a escutar nesse endereço. Um servidor PostgreSQL ligado apenas a 127.0.0.1 fica inacessível a qualquer container que tenha o seu próprio namespace de rede. Isto inclui todos os containers atrás do gluetun, com ou sem túnel, porque 127.0.0.1 dentro do namespace é o loopback desse próprio namespace. Apenas um container que use a rede do host partilha o loopback do host, e um container atrás do gluetun já gastou o seu network_mode com o gluetun. Ligue o PostgreSQL a 172.17.0.1. Assim, aceita ligações dos containers sem ficar exposto na interface pública. Verifique com ss -lntp | grep 5432 no host.

O que FIREWALL_OUTBOUND_SUBNETS realmente altera

A documentação do gluetun descreve esta variável como as sub-redes, separadas por vírgulas, a que o gluetun e os contentores que partilham a sua pilha de rede podem aceder. Também indica que ela envolve alterações na firewall e no encaminhamento. As duas partes são importantes. O gluetun adiciona uma rota para cada sub-rede indicada através do gateway da bridge Docker. Assim, os pacotes destinados a esses endereços saem por eth0 em vez de passar pelo túnel. O gluetun também abre a firewall para essas sub-redes, porque, caso contrário, descarta o tráfego de saída que não se destina ao servidor VPN.

Escreva o valor sem espaços depois das vírgulas.

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

Há duas propriedades fáceis de ignorar. Esta é uma definição ao nível do namespace. Portanto, aplica-se a todos os contentores atrás do gluetun, e não apenas ao contentor pretendido. Além disso, aplica-se apenas ao tráfego de saída. A definição controla as ligações iniciadas por um contentor. As ligações que chegam a uma porta publicada seguem um caminho diferente e não precisam desta entrada.

Aceder à interface web a partir de um peer Tailscale

O Tailscale atribui a cada máquina um endereço em 100.64.0.0/10, o intervalo reservado para NAT de operadora. Nada disto tem custos numa tailnet pessoal, embora o limite de seis utilizadores do plano gratuito determine se isso continua a ser verdade quando outras pessoas precisam de acesso às mesmas interfaces. Os dispositivos dos utilizadores são ilimitados em todos os planos. Os servidores e outros dispositivos com tags são contabilizados separadamente: a página de preços do Tailscale indica 50 recursos com tags incluídos, com recursos adicionais a $1 por mês cada. Como a faturação conta, de resto, os utilizadores e não as máquinas, o custo efetivo de uma tailnet paga depende sobretudo do número de pessoas que convida, e não do número de contentores a que lhes dá acesso. As duas direções exigem trabalhos diferentes.

As ligações de entrada são simples. Publicar 8080:8080 no gluetun associa essa porta a todos os endereços do host, e a interface tailscale0 do host é um deles. Assim, um peer abre http://<machine-name>:8080 e chega ao contentor. O Docker aplica NAT no host, e a firewall do gluetun permite tráfego de entrada para a sub-rede Docker.

Para tornar a interface acessível apenas através da tailnet, associe a porta publicada ao endereço Tailscale do host, em vez de a todos os endereços.

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

Obtenha esse endereço com tailscale ip -4 no host. Neste caso, associar a porta é um controlo mais forte do que uma regra de firewall, porque a porta nunca é aberta na interface pública. Se preferir aceder à interface através de um nome HTTPS em vez de um host e uma porta, tailscale serve pode ficar à frente dessa porta publicada. No entanto, serve e funnel diferem quanto a quem consegue aceder-lhe e apenas uma das duas opções mantém a interface na tailnet. Isto também evita o problema descrito em Publicar portas do Docker diretamente para além do ufw. O padrão de sidecar Tailscale para o Compose vai mais longe e elimina completamente a porta do host, mas funciona colocando a aplicação no namespace de rede do sidecar, e um contentor atrás do gluetun já gastou o seu único network_mode no gluetun.

Nas ligações de saída, FIREWALL_OUTBOUND_SUBNETS volta a ser relevante. Se um contentor tiver de contactar um peer, adicione o endereço desse peer e prefira um /32 por peer em vez de usar toda a /10. Se a máquina contactada estiver numa rede privada alcançada através de um VPS que anuncia essa sub-rede à sua tailnet, indique o intervalo anunciado em vez do próprio endereço 100.x do router e confirme que o próprio host aceitou essas rotas. Os nomes MagicDNS não são resolvidos dentro do contentor por predefinição, porque o contentor usa o servidor DNS do gluetun em vez do resolvedor do host. Por isso, use o endereço numérico 100.x ou fixe o nome com uma linha extra_hosts no serviço gluetun. A opção DNS_UPSTREAM_PLAIN_ADDRESSES do gluetun pode encaminhar as consultas para outro resolvedor, mas envia todas as consultas em texto simples, e a documentação do gluetun desaconselha essa opção porque as consultas para um endereço privado escapam do túnel VPN. O mesmo se aplica quando executa o seu próprio servidor de controlo Tailscale com o Headscale.

Um ficheiro compose completo para a estrutura habitual

Um cliente de downloads atrás da VPN, duas interfaces Web que respondem apenas na tailnet e um contentor que lê uma base de dados PostgreSQL executada no 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

Leia o ficheiro para entender o padrão, não os nomes dos produtos. As duas interfaces são publicadas no gluetun e associadas ao endereço tailnet do host, por isso respondem na Tailscale e em nenhum outro local. A linha extra_hosts também fica no gluetun, porque o Prowlarr lê o /etc/hosts do gluetun quando resolve host.docker.internal, e o Docker recusaria a linha no próprio Prowlarr. FIREWALL_OUTBOUND_SUBNETS nomeia dois endereços individuais: o endereço da bridge Docker do host, para que o Prowlarr possa abrir uma ligação à base de dados, e um peer da tailnet.

O servidor PostgreSQL está deliberadamente ausente do ficheiro. É executado no VPS como um serviço normal do sistema e fica à escuta em 172.17.0.1:5432. Esta é a mesma camada de uma stack arr no Docker Compose, com a base de dados fora do Docker.

Mantenha a chave privada WireGuard fora do ficheiro compose. O ${WIREGUARD_PRIVATE_KEY} lê a partir de um ficheiro .env colocado ao lado dele. Este é o padrão explicado em ficheiros env e secrets para o Docker Compose. A cláusula condition: service_healthy usa o healthcheck que a imagem gluetun já inclui, por isso nada é iniciado até o túnel indicar que está ativo. Healthchecks do Compose explicam a estrutura geral.

Publicar em todos os endereços em vez de apenas na tailnet

Remova o prefixo de endereço e as associações de portas em 0.0.0.0, que inclui o IP público do VPS. Faça isto apenas atrás de uma firewall que controle e leia primeiro a nota sobre ufw acima.

    ports:
      - "8080:8080/tcp"

Confirme que o túnel continua a transportar tráfego

Execute o mesmo pedido duas vezes, uma vez a partir do namespace e outra vez a partir do host, e compare os resultados.

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

O primeiro deve apresentar o endereço de saída do seu fornecedor de VPN. O segundo deve apresentar o endereço do VPS. Se forem iguais, o tráfego do contentor não está a passar pelo túnel. Até corrigir isso, todas as restantes correções deste guia são irrelevantes.

As regras e as tabelas de encaminhamento mostram o que passa pelo túnel e o que não passa.

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

Com a configuração WireGuard usada neste guia, o gluetun atribui à interface do túnel o nome wg0. O nome tun0 é apenas o nome predefinido do OpenVPN. O gluetun também mantém a rota predefinida do túnel fora da tabela de encaminhamento principal. ip rule show deve incluir uma regra que envie para a tabela 51820 todo o tráfego que não seja marcado pelo próprio WireGuard, e essa tabela deve conter uma rota predefinida em wg0. A tabela 199 contém uma rota por cada entrada em FIREWALL_OUTBOUND_SUBNETS, apontando para o gateway da bridge Docker em eth0, e a respetiva regra é verificada imediatamente antes da regra do túnel. Um ip route show simples continua a apresentar a rota predefinida própria do Docker em eth0. Isto é esperado e não constitui uma fuga, porque ambas as regras do gluetun são verificadas antes da tabela principal. Qualquer rota na tabela 199 que não tenha listado corresponde a tráfego que ignora a VPN.

O servidor de controlo do gluetun pode apresentar o mesmo IP público na porta 8000, em /v1/publicip/ip, mas, por predefinição, só depois de configurar a autenticação. A documentação do gluetun indica que todas as rotas do servidor de controlo são agora privadas por predefinição, pelo que um pedido simples para esse caminho falha. Configure-o com um ficheiro de autenticação montado por bind em /gluetun/auth/config.toml, usando o método basic ou apikey, e reinicie o gluetun. O ficheiro Compose acima já monta ./gluetun em /gluetun, pelo que o ficheiro deve ficar em ./gluetun/auth/config.toml no host. A variável HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE é a opção mais rápida. Defini-la como {"auth":"none"} desativa completamente a autenticação, algo que a documentação classifica como fortemente desaconselhado. Numa release anterior à v3.39.1, o servidor não fica protegido desta forma, e a documentação alerta para confiar em qualquer sistema que consiga aceder-lhe.

A fuga criada por uma sub-rede incorreta

FIREWALL_OUTBOUND_SUBNETS é uma abertura intencional na firewall, por isso o tamanho da abertura corresponde ao tamanho do risco. Evite estes quatro erros:

  • 0.0.0.0/0 falha a validação da configuração com outbound subnet has an unspecified address: 0.0.0.0/0. O Gluetun rejeita-o em vez de encaminhar todo o tráfego para fora do túnel.
  • Um intervalo mais amplo do que o necessário. Abrir 10.0.0.0/8 para chegar a uma máquina em 10.0.1.7 também abre todos os endereços que um peer de torrents possa anunciar nesse intervalo. Escreva 10.0.1.7/32.
  • Um intervalo que se sobrepõe aos próprios endereços do túnel. A documentação do gluetun avisa que isto faz o gluetun enviar o tráfego VPN através da bridge, o que interrompe o encaminhamento de portas. Verifique o valor WIREGUARD_ADDRESSES antes de abrir qualquer intervalo privado.
  • 100.64.0.0/10 para o Tailscale. Isso abre aproximadamente quatro milhões de endereços para que um único peer possa ser alcançado. Indique os peers necessários como entradas /32.

Lembre-se de que esta definição abrange todo o namespace. Abrir uma sub-rede para que um indexador possa aceder a um serviço do host abre a mesma sub-rede para o cliente de torrents que partilha esse namespace. Volte a executar a verificação do IP público depois de cada alteração a esta variável, porque é o único teste que mostra se a alteração teve o efeito pretendido.

O que deixa de funcionar quando reinicia o gluetun

O gluetun é o proprietário do namespace. Por isso, o ciclo de vida do gluetun é também o ciclo de vida do namespace. Iniciar um contentor dependente enquanto o gluetun está parado falha imediatamente:

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

Reiniciar o gluetun no mesmo grupo causa uma falha menos evidente. Os contentores dependentes continuam em execução enquanto o namespace ao qual estão ligados é reconstruído por baixo deles. Assim, docker ps indica que está tudo saudável, mas nenhum serviço responde. Depois de qualquer alteração ao serviço gluetun, recrie o grupo inteiro em vez de reiniciar apenas uma parte.

docker compose up -d --force-recreate

O mesmo se aplica às atualizações das imagens. Extrair uma nova imagem do gluetun e recriar apenas esse serviço deixa os restantes contentores ligados a um namespace que já não existe.

FAQ

Por que o Docker apresenta "port publishing and the container type network mode"?

Isso acontece porque ainda existe um bloco ports: num serviço que também define network_mode: service:gluetun. A publicação de uma porta adiciona uma regra NAT que encaminha uma porta do host para o namespace de rede próprio do contentor, mas um contentor neste modo não tem um namespace próprio. Remova o bloco ports: desse serviço e adicione o mesmo mapeamento ao serviço gluetun. O número da porta permanece igual, porque a aplicação continua a escutar nessa porta dentro do namespace partilhado.

Como os outros contentores acedem a um serviço que está atrás do gluetun?

Os contentores dentro do mesmo namespace acedem uns aos outros através de 127.0.0.1. Os contentores fora dele usam o nome do serviço gluetun, por isso http://gluetun:8080 funciona, enquanto http://qbittorrent:8080 não funciona. O contentor da aplicação não tem um endereço em nenhuma rede Docker, portanto o servidor DNS integrado não tem nenhum endereço para resolver pelo nome do contentor. Não é necessária publicação de portas para isto, desde que ambos os contentores partilhem uma rede Compose.

O que devo colocar em FIREWALL_OUTBOUND_SUBNETS?

Apenas os endereços aos quais um contentor atrás do gluetun precisa de iniciar uma ligação, especificados com a maior restrição possível. Uma única máquina é um /32. As duas entradas mais comuns são o host Docker em 172.17.0.1/32 e um /32 para cada peer Tailscale ao qual se liga. Nunca adicione 0.0.0.0/0 e nunca adicione um intervalo que se sobreponha aos endereços do próprio túnel VPN. As ligações recebidas numa porta publicada não precisam de nenhuma entrada aqui.

Por que o contentor não consegue resolver os meus nomes MagicDNS do Tailscale?

O MagicDNS funciona configurando o resolver do host para usar o servidor DNS do Tailscale, mas o contentor não usa o resolver do host. Usa o /etc/resolv.conf que partilha com o gluetun, apontado para o próprio servidor DNS do gluetun. Confirme com docker exec <container> cat /etc/resolv.conf. Use o endereço numérico 100.x do peer ou associe o nome a um endereço através de uma entrada extra_hosts no serviço gluetun. O gluetun pode encaminhar consultas para outro resolver com DNS_UPSTREAM_PLAIN_ADDRESSES, mas isso envia as consultas em texto simples e a documentação recomenda não o fazer.

Como confirmo que o tráfego continua a passar pela VPN?

Execute um pedido dentro do namespace e o mesmo pedido no host. Depois, compare as respostas. docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org deve devolver o endereço de saída do seu fornecedor de VPN, enquanto curl -s https://api.ipify.org no VPS deve devolver o endereço do VPS. Duas respostas iguais significam que o túnel não está a transportar o tráfego do contentor. Repita esta verificação depois de cada alteração a FIREWALL_OUTBOUND_SUBNETS.

Este artigo foi útil?