Passo a passo: habilitar e depurar IPv6 em containers Docker e bridge network no Debian (guia prático)

Docker & Containers · Por Kevin Marcondes · Publicado em 22/10/2026 · 9 min de leitura

ponte suspensa sobre um rio com edifícios ao fundo e céu claro — Metáfora visual para 'bridge' e infraestrutura de rede em tutoriais técnicos Foto: Hao Liang / Pexels

Este passo a passo: habilitar e depurar IPv6 em containers Docker e bridge network no Debian mostra, do zero, como ativar suporte no kernel/sysctl, ajustar o daemon.json, criar uma bridge com IPv6 e validar conectividade. Você vai subir containers com endereços IPv6 e terá um roteiro de diagnóstico para rotas, firewall e problemas de alocação.

Pré-requisitos e como o IPv6 funciona no Docker

Você precisa de acesso root ao host Debian e Docker instalado. Se faltar, instale seguindo este guia: como instalar Docker e Docker Compose.

O Docker só atribui IPv6 se o daemon estiver com IPv6 ativado e a rede tiver uma sub-rede IPv6. Por padrão, o bridge “docker0” vem apenas com IPv4.

Para redes internas, use endereços ULA (fd00::/8). Para tráfego global, é melhor ter um prefixo roteado pelo provedor para o host.

Se você reiniciar o Docker, containers em execução serão interrompidos. Planeje uma janela e use Compose para subir novamente rapidamente.

Este é um passo a passo prático e direto para habilitar e depurar IPv6 em containers Docker e bridge network no Debian, com foco em testes e diagnóstico.

Acesso root ou sudo ao servidor Debian
Docker e Docker Compose instalados
Possível prefixo IPv6 público roteado (para Internet IPv6)
Backup do /etc/docker/daemon.json se já existir
Janela para reiniciar o serviço Docker

1) Verifique suporte IPv6 no host Debian

Antes de mexer no Docker, confirme que o kernel não está com IPv6 desativado e que há rotas v6 no host. Se o host não tiver IPv6 global, ainda é possível usar ULA internamente.

Se o comando de disable_ipv6 retornar 1, o IPv6 está desativado. Habilitaremos no próximo passo.

# 1. Checar se o IPv6 está habilitado no kernel
sysctl net.ipv6.conf.all.disable_ipv6

# 2. Ver endereços IPv6 do host (global e link-local)
ip -6 addr show

# 3. Rotas IPv6
ip -6 route

# 4. Teste de conectividade externa IPv6 (opcional)
ping -6 -c 2 2606:4700:4700::1111 || true

2) Ative IPv6 e encaminhamento no kernel (sysctl)

Habilite IPv6 no host e o encaminhamento entre interfaces. Isso permite que o bridge do Docker troque pacotes IPv6. Aplicar sysctl afeta a rede; execute em janela segura.

Defina accept_ra=2 para permitir roteamento mesmo com RA. Em servidores, isso evita perder rota padrão quando forwarding está ativo.

Parâmetro	O que faz	Quando usar
net.ipv6.conf.all.disable_ipv6=0	Liga suporte IPv6 no kernel	Sempre que quiser IPv6
net.ipv6.conf.all.forwarding=1	Permite roteamento/encaminhamento IPv6	Necessário para bridges Docker
net.ipv6.conf.all.accept_ra=2	Aceita RA mesmo roteando	Útil quando a rede envia RA

cat >/etc/sysctl.d/10-ipv6-docker.conf <<'EOF'
net.ipv6.conf.all.disable_ipv6 = 0
net.ipv6.conf.default.disable_ipv6 = 0
net.ipv6.conf.all.forwarding = 1
net.ipv6.conf.default.forwarding = 1
net.ipv6.conf.all.accept_ra = 2
net.ipv6.conf.default.accept_ra = 2
EOF

# Aplica tudo que está em /etc/sysctl.d
sysctl --system

3) Habilite IPv6 no Docker daemon (daemon.json)

Ative IPv6 no Docker e defina uma faixa ULA para a alocação de endereços. O Docker usará essa faixa para redes bridge quando configuradas com IPv6.

Se já existir daemon.json, una os campos manualmente para não perder configurações. Reiniciar o Docker derruba containers em execução.

mkdir -p /etc/docker
cat >/etc/docker/daemon.json <<'EOF'
{
  "ipv6": true,
  "fixed-cidr-v6": "fd00:dead:beef::/48",
  "ip6tables": true
}
EOF

# Reinicie o Docker (interrompe containers em execução)
systemctl restart docker && systemctl status --no-pager docker

4) Crie uma bridge Docker com sub-rede IPv6 dedicada

Crie uma rede bridge explícita com IPv6. Separe sub-redes por ambiente para evitar conflitos. O gateway IPv6 do bridge será o endereço do host nessa rede.

Após criar, inspecione a rede para confirmar a presença de Subnet e Gateway IPv6.

# Cria uma rede bridge com IPv4 e IPv6
# Ajuste as faixas conforme sua política de endereçamento
NETWORK_NAME=brv6

docker network create \
  --driver bridge \
  --subnet 172.18.0.0/16 \
  --ipv6 \
  --subnet fd00:dead:beef:1::/64 \
  --gateway fd00:dead:beef:1::1 \
  "$NETWORK_NAME"

# Verifique a configuração
docker network inspect "$NETWORK_NAME" | grep -E 'IPv6|Subnet|Gateway' -n

5) Suba containers e teste IPv6 (Docker Compose)

Você pode ativar IPv6 diretamente no Compose definindo a rede com enable_ipv6 e IPAM. Neste exemplo, a rede é criada pelo Compose e o serviço recebe IPv6 automaticamente.

Depois de subir, entre no container e verifique o endereço e a rota padrão IPv6.

# docker-compose.yml
version: "3.9"
services:
  app:
    image: alpine:3
    command: ["sh","-lc","ip -6 addr show dev eth0; ip -6 route; sleep 3600"]
    networks:
      - brv6

networks:
  brv6:
    driver: bridge
    enable_ipv6: true
    ipam:
      config:
        - subnet: 172.19.0.0/16
        - subnet: fd00:dead:beef:2::/64
          gateway: fd00:dead:beef:2::1

6) Depuração: rotas, regras de firewall e logs do Docker

Se o container não recebe IPv6, confirme se a rede foi criada com IPv6 e se o daemon está com ipv6=true. Em seguida, verifique rotas e regras de firewall.

Debian usa iptables-nft por padrão. O Docker manipula regras ip6tables quando ip6tables=true. Adapte sua política de firewall para permitir tráfego do bridge.

Para hardening do host e cgroup v2 no Docker, veja: cgroup v2 + systemd para Docker e checklist de segurança para VPS.

Confirme IPv6 na rede: docker network inspect
Cheque rotas no host e no container
Revise ip6tables/nftables para bloqueios
Veja logs do Docker por erros de rede

# Inspecione a rede
docker network inspect brv6

# Rotas IPv6 no host
ip -6 route

# Regras IPv6 (iptables-nft)
ip6tables -L -n -v | sed -n '1,120p'

# (Opcional) Ver regras nftables
nft list ruleset | grep -i ip6 || true

# Logs recentes do Docker
journalctl -u docker --since -2h | tail -n +1

7) Checklist de verificação e testes práticos

Siga este checklist para confirmar o funcionamento. Se um item falhar, volte uma etapa e revise a configuração.

Monitore o ambiente de forma contínua. Para métricas e painéis com Compose, veja: Prometheus e Grafana com Docker Compose.

Este passo a passo: habilitar e depurar IPv6 em containers Docker e bridge network no Debian garante que você valide cada camada: kernel, daemon, rede e aplicação.

docker info mostra IPv6: true
docker network inspect lista Subnet e Gateway IPv6
Container tem endereço fd00:... em eth0
Container consegue ping -6 o gateway do bridge
Host consegue ping -6 o container por endereço ULA
Rotas IPv6 existem no host e no container

8) Problemas comuns e soluções rápidas

Alguns erros aparecem com frequência quando ativamos IPv6 em containers. Veja as correções típicas abaixo. Não prometa NAT66 sem avaliar riscos; prefira prefixo roteado do provedor.

Para reduzir indisponibilidade ao reiniciar o Docker em produção, considere estratégias como blue-green com Compose: deploy blue-green.

Se precisar relembrar o fluxo completo, retorne ao passo a passo: habilitar e depurar IPv6 em containers Docker e bridge network no Debian e revalide cada etapa.

Container só tem fe80:: (link-local): recrie a rede com --ipv6 e IPAM v6 no Compose.
Sem Internet IPv6 usando ULA: peça um /64 roteado ao provedor ou use túnel. NAT66 é possível, porém não padronizado e complexo.
Forwarding desligado: garanta net.ipv6.conf.all.forwarding=1 e aplique sysctl --system.
Firewall bloqueando: revise chains IPv6 e deixe o bridge do Docker transitar conforme política.
daemon.json sobrescrito: una as chaves; reinicie o Docker após validar JSON.
Mudanças somem no reboot: use arquivos em /etc/sysctl.d e não edite apenas sysctl em runtime.

Perguntas frequentes

O Docker vem com IPv6 habilitado por padrão?

Não. Você precisa ativar "ipv6": true no daemon.json e usar redes bridge criadas com IPv6. Sem isso, containers só recebem IPv4. Depois, crie a rede com sub-rede fd00::/64 ou defina enable_ipv6 no Docker Compose.

Preciso que minha VPS tenha IPv6 público para usar IPv6 nos containers?

Apenas se quiser tráfego IPv6 para a Internet. Para comunicação interna entre containers e host, ULA (fd00::/8) funciona. Para Internet, prefira um prefixo público roteado e encaminhe ao bridge correspondente.

Dá para ativar IPv6 só no Docker Compose?

Sim. Defina enable_ipv6: true na rede do Compose e configure IPAM com uma sub-rede IPv6. O daemon do Docker também precisa estar com ipv6=true, caso contrário o Docker não alocará endereços v6.

Uso iptables ou nftables com Docker e IPv6 no Debian?

Debian usa iptables-nft por padrão. O Docker manipula regras ip6tables quando ip6tables=true. Ajuste sua política de firewall para permitir o tráfego das bridges. Verifique com ip6tables -L -n -v e nft list ruleset.

Reiniciar o Docker causa indisponibilidade? Como minimizar?

Sim, reiniciar o Docker interrompe containers. Planeje janela de mudança e orquestre a volta com Compose. Estratégias como blue-green ajudam a reduzir impacto em produção; veja o tutorial de deploy blue-green com Compose.

Precisa de uma revisão da sua configuração Docker/IPv6?

Se a ativação de IPv6 esbarrou em roteamento, firewall ou integração com Compose, podemos analisar sua stack e propor correções seguras.

Falar sobre diagnóstico IPv6 no Docker