WSL2: Guia avançado para configuração de rede, NAT e modos espelhados.

Informatec Digital » Recursos » WSL2: Guia avançado para configuração de rede, NAT e modos espelhados.

O WSL2 mudou completamente a forma como o Linux se integra ao Windows.Principalmente em tudo relacionado à rede: agora temos uma máquina virtual leve com sua própria pilha de rede, seu próprio endereço IP e regras de acesso separadas. Isso abre muitas possibilidades para desenvolvimento, testes, contêineres e ambientes de autohospedagem, mas também levanta preocupações quando os serviços se tornam inacessíveis, como aconteceu com o WSL1.

Entendendo a configuração de rede do WSL2, seus modos NAT e espelhado, o uso dos arquivos .wslconfig e wsl.conf e como eles interagem com firewalls, VPNs, Docker ou ferramentas como o Tailscale. Isso é fundamental para evitar dores de cabeça. Vamos ver passo a passo como toda essa configuração funciona, como expor serviços ao Windows e à LAN, quais comandos usar para obter os IPs corretos e quais opções de configuração avançadas você tem para ajustar seu ambiente, tornando-o estável e, acima de tudo, seguro.

Como a rede funciona na prática no WSL2

O WSL2 não compartilha mais a pilha de rede do host como o WSL1.Em vez disso, ele executa cada distribuição Linux dentro de uma pequena máquina virtual gerenciada pelo Hyper-V. Essa máquina virtual possui seu próprio adaptador virtual (geralmente eth0) e um endereço IP privado atribuído por um switch virtual interno.

Em seu modo padrão, o WSL2 utiliza uma arquitetura baseada em NAT. (Network Address Translation). O Windows atua como roteador/host e a distribuição Linux reside em uma sub-rede privada, normalmente dentro do intervalo. 172.16.0.0/12Essa sub-rede pode mudar após reinicializações ou reinicializações do WSL, algo que já enlouqueceu muita gente na hora de configurar regras de firewall estáticas.

Do ponto de vista prático, isso significa que o endereço IP da sua distribuição WSL2 não é estável nem diretamente acessível da LAN. Assim como no WSL1: por padrão, a conectividade entre o Windows e o WSL2 ocorre apenas por meio de regras de redirecionamento e NAT, e a exposição à rede local requer etapas adicionais ou o uso do modo espelhado.

Além dessa arquitetura básica, o Windows 11 22H2 e versões posteriores adicionam novos recursos de rede. (modo espelhado, dnsTunneling, autoProxy, firewall Hyper-V, etc.) que são controlados a partir do arquivo global .wslconfigenquanto certas opções dentro do Linux são gerenciadas com /etc/wsl.conf.

Identificar endereços IP no WSL2

Trabalhar com WSL2 envolve distinguir claramente entre dois cenários de IP.: quando você precisa do endereço IP da distribuição Linux e quando precisa do endereço IP do host Windows visualizado a partir do Linux. Cada um é resolvido com um comando diferente.

Cenário 1: No Windows, você deseja saber o endereço IP da distribuição WSL2. Para permitir que um aplicativo no host (por exemplo, um cliente, navegador ou ferramenta de teste) se conecte a um serviço em execução no Linux, você pode executar os seguintes comandos no Windows (usando o CMD ou o PowerShell):

wsl.exe --distribution <DistroName> hostname -i

Se você quiser usar a distribuição padrão, pode omitir o parâmetro de distribuição. e simplesmente ligue wsl.exe hostname -iEm segundo plano, este comando é executado no Linux. hostname --ip-addresses e retorna o endereço IP da instância. Um resultado típico seria algo como:

172.30.98.229

Cenário 2: A partir da distribuição Linux, você precisa saber o endereço IP do host Windows.Por exemplo, para conectar um aplicativo WSL2 a um servidor executado nativamente no Windows (Node.js, SQL Server, Caddy, etc.), você pode usar o seguinte comando no shell do Linux:

ip route show | grep -i default | awk '{ print $3 }'

A saída será o gateway padrão da VM WSL2., que corresponde ao endereço IP do host Windows visto do Linux, algo como:

172.30.96.1

Esse valor (por exemplo, 172.30.96.1) é o endereço para o qual seus clientes Linux devem apontar. Quando você deseja acessar serviços em execução no host Windows enquanto estiver no modo NAT clássico.

Modo NAT: comportamento padrão da rede WSL2

O WSL2 funciona em modo NAT por padrão, e para muitos ambientes de desenvolvimento simples, isso é mais do que suficiente.O importante é entender o que funciona "por si só" e o que não funciona, para não perder tempo perseguindo fantasmas.

Acessando serviços do Linux a partir do Windows usando localhostSe você executar um aplicativo de rede (por exemplo, um servidor Node.js, um servidor Flask ou um servidor SQL no Linux) em sua distribuição WSL2, poderá acessá-lo a partir do Windows usando localhost:puertoO Windows encaminha automaticamente as conexões recebidas para o endereço IP interno da máquina virtual WSL2.

Acessando serviços em execução no Windows a partir do LinuxÉ aqui que as coisas mudam. Para acessar um aplicativo de rede no host (como um servidor Node.js, SQL Server ou Caddy no Windows) a partir do WSL2, você precisa usar o endereço IP do host, conforme visto no Linux, obtido com o comando de rota padrão:

ip route show | grep -i default | awk '{ print $3 }'

Com esse endereço IP, você pode se conectar do Linux a qualquer serviço no host., por exemplo http://172.30.96.1:3000 Se o seu servidor Windows estiver escutando na porta 3000 em todas as interfaces.

Ao conectar-se usando IPs remotos (e não localhost), os aplicativos os enxergam como conexões de rede local (LAN).Isso significa que muitos servidores precisam ser configurados para escutar em 0.0.0.0 em vez de 127.0.0.1Por exemplo, com o Flask você poderia executar:

app.run(host='0.0.0.0')

Essa mudança melhora a acessibilidade, mas exige foco na segurança.Porque você está permitindo conexões da sua rede local, e não apenas do próprio computador.

Acessando o WSL2 a partir da rede local (LAN) usando NAT

Uma das mudanças mais irritantes ao migrar do WSL1 para o WSL2 é que as distribuições não são mais acessíveis diretamente da LAN.No WSL1, se o seu Windows estivesse visível na rede, os serviços da distribuição herdavam essa visibilidade quase sem esforço.

No WSL2, a máquina virtual possui seu próprio endereço IP privado e não é anunciada automaticamente na rede local (LAN).Para obter um comportamento semelhante ao anterior, no modo NAT você precisa criar um proxy de porta no Windows, como faria com qualquer máquina virtual Hyper-V.

O Windows inclui uma ferramenta clássica para isso: netsh interface portproxyUm comando típico para redirecionar uma porta do host para o IP/porta do WSL2 seria:

netsh interface portproxy add v4tov4 listenport=<puertoHost> listenaddress=0.0.0.0 connectport=<puertoWSL> connectaddress=(wsl hostname -I)

Na prática, você substituiria os marcadores por valores específicos., por exemplo:

netsh interface portproxy add v4tov4 listenport=4000 listenaddress=0.0.0.0 connectport=4000 connectaddress=192.168.101.100

Aqui listenaddress=0.0.0.0 Isso indica que o Windows ficará à escuta em todos os endereços IPv4 do host.e encaminhará o que chegar pela porta 4000 para 192.168.101.100:4000que seria o endereço IP do WSL2 obtido com:

• wsl hostname -I Ele fornece o endereço IP da distribuição Linux dentro da máquina virtual WSL2.
• cat /etc/resolv.conf Revela o endereço IP do host Windows Vista a partir do WSL2.

Com essa técnica, você pode tornar um serviço em execução no WSL2 acessível a partir de qualquer computador na rede local (LAN).contanto que o firewall do Windows permita e você tenha certeza de que está expondo um serviço de uma máquina virtual, e não o host diretamente.

IPv6 e recursos modernos de rede

O WSL2 também é compatível com IPv6, o que é especialmente relevante em ambientes modernos, VPNs e redes corporativas.Para lidar com endereços, os comandos básicos no Linux são equivalentes aos do IPv4:

• wsl hostname -i No Windows, para visualizar o endereço IP da distribuição WSL2.
• ip route show | grep -i default | awk '{ print $3 }' a partir do Linux para obter o endereço IP do host Windows

Onde o salto de qualidade no suporte a IPv6 e VPN é realmente perceptível é no modo de rede espelhada., disponível no Windows 11 22H2 e versões posteriores, que veremos em detalhes mais adiante.

Modo de rede espelhada: espelhando interfaces do Windows no Linux

Em computadores com Windows 11 22H2 ou superior, você pode ativar o modo de rede "espelhamento". No WSL2, o modelo muda completamente: em vez do NAT clássico, o Linux "enxerga" as interfaces de rede do Windows refletidas.

Para habilitá-lo, você precisa editar o arquivo. .wslconfig do seu usuário, encontrado em %UserProfile%\.wslconfigA partir do PowerShell com privilégios de administrador, você pode abri-lo com o seguinte comando:

notepad $env:USERPROFILE\.wslconfig

Dentro do arquivo, adicione (ou modifique) a seção [wsl2] para ativar o modo espelhado.:

[wsl2]
networkingMode=mirrored

Após salvar o arquivo, você precisa reiniciar o WSL2 para que as alterações entrem em vigor.Por exemplo, com:

wsl --shutdown

Ao reiniciar, o WSL utilizará a nova arquitetura de rede espelhada.o que traz diversas vantagens muito poderosas:

• Suporte nativo a IPv6 e integração aprimorada com redes corporativas e VPNs.
• Capacidade de conectar-se a serviços do Windows a partir do Linux usando 127.0.0.1 diretamente (embora não seja permitido) ::1 (como, por exemplo, um loopback IPv6 para isso)
• Suporte multicast aprimorado na integração Windows-Linux
• Acesso direto ao WSL a partir da LAN sem a necessidade do netsh portproxy.usando o endereço IP da própria máquina Windows

Habilitar esse modo resolve muitos dos problemas clássicos de NAT do WSL2. E é a opção recomendada na maioria dos ambientes modernos de desenvolvimento e auto-hospedagem, onde você pode usar uma versão atualizada do Windows 11.

Tunelamento DNS e o uso de proxies no WSL2

No Windows 11 22H2 e versões posteriores, a resolução de nomes do WSL2 também recebeu uma reformulação significativa.A chave reside em duas funcionalidades definidas em .wslconfig: dnsTunneling y autoProxy.

a opção dnsTunneling Está ativado por padrão na seção [wsl2]. Isso permite que as solicitações de DNS do Linux sejam tratadas por meio de um recurso de virtualização, em vez de serem enviadas como pacotes de rede normais. Isso melhora significativamente a compatibilidade com VPNs e configurações de rede complexas no host.

Por sua parte, o autoProxy=true Força o WSL a usar as configurações de proxy HTTP do Windows.Se o host estiver atrás de um proxy corporativo ou de segurança, o WSL2 herda essa configuração automaticamente, sem que você precise mexer manualmente com as variáveis ​​de ambiente.

Você poderia ter, por exemplo, algo assim no seu .wslconfig:

[wsl2]
dnsTunneling=true
autoProxy=true

Isso garante que a rede WSL2 se comporte de forma consistente com a configuração do host., especialmente útil em empresas com políticas rígidas de rede e filtragem.

Firewall do Hyper-V e exposição de serviços seguros

Em ambientes modernos, a rede WSL2 também passa por um firewall dedicado.A partir do WSL 2.0.9 no Windows 11 22H2, o recurso de firewall do Hyper-V está habilitado por padrão, adicionando uma camada extra de filtragem para o tráfego de máquinas virtuais (incluindo o tráfego do WSL2).

Se você estiver trabalhando no modo espelhado e quiser expor permanentemente os serviços WSL2 à LAN (por exemplo, APIs, painéis de controle ou serviços de hospedagem própria), você precisa garantir que as regras do firewall permitam isso.

Uma abordagem razoável usando o PowerShell com privilégios de administrador é criar uma regra do Hyper-V para redes privadas.:

New-NetFirewallHyperVRule -DisplayName "WSLPrivateInboundRule" -Profiles Private -Direction Inbound -Action Allow -VMCreatorId ((Get-NetFirewallHyperVVMCreator).VMCreatorId)

Se, por algum motivo, você quiser desativar essa proteção específica do Hyper-V, (Algo menos recomendado), você poderia usar:

Set-NetFirewallHyperVVMSetting -Name ((Get-NetFirewallHyperVVMCreator).VMCreatorId) -Enabled False

A ideia é manter o firewall ativo sempre que possível.Limitar as regras a redes privadas e apenas às portas realmente necessárias, reservando qualquer desativação em massa como último recurso e sempre com o objetivo de reforçar a configuração assim que tudo estiver funcionando.

Arquitetura de rede WSL2, X11 e intervalos 172.16.0.0/12

Um caso clássico que revela detalhes da rede WSL2 é o uso de aplicativos gráficos via X11.Por exemplo, iniciar o Xming no Windows e enviar aplicativos Linux via DISPLAY.

Ao atualizar do WSL1 para o WSL2, muitos usuários descobrem que o X para de funcionar. porque a rede deixa de ser "compartilhada" e se torna uma rede NAT virtual com intervalos como 172.16.0.0/12que também pode mudar após cada reinicialização do Windows ou do WSL.

Para fazer o X funcionar novamente com o Xming no WSL2, o truque usual é obter o endereço IP do Windows que o Linux vê. vestindo:

ens

DISPLAY=$(grep nameserver /etc/resolv.conf | cut -d' ' -f2):0

Em paralelo, é necessário ajustar o firewall do Windows para permitir o tráfego X11 dessa sub-rede NAT.Uma abordagem típica é editar a regra Xming adicionando o intervalo. 172.16.0.0/12 em TCP+UDP 6000.

Muitos acabam desativando a autenticação do Xming com a opção -acIsso efetivamente "abre as portas" para qualquer cliente X que chegue dessa rede. Funciona, mas do ponto de vista da segurança é bastante questionável, então vale a pena considerar soluções mais limitadas ou usar o WSLg (aplicativos GUI integrados) no Windows 11.

wsl.conf e .wslconfig: configuração avançada do WSL2

O WSL oferece dois arquivos de configuração principais que controlam tanto o comportamento da máquina virtual quanto o de cada distribuição.: /etc/wsl.conf (por distribuição) e %UserProfile%\.wslconfig (global para todas as distribuições WSL2).

wsl.conf reside dentro da distribuição Linux, em /etc/wsl.confÉ usado para configurar opções locais para essa distribuição: montagens automáticas, geração de hosts y resolv.confinteroperabilidade com Windows, usuário padrão, systemd, etc.

.wslconfig Ele é salvo fora do Linux, no perfil de usuário do Windows. (C:\Users\<Usuario>\.wslconfig) e controla os parâmetros globais da VM que alimenta o WSL2: memória, CPUs, kernel, modo de rede, firewall, DNS, tamanho do disco virtual, suporte à GUI, etc.

Um detalhe curioso é a "regra dos 8 segundos" ao alterar as configurações.Ao modificar qualquer um desses arquivos, você deve garantir que a máquina virtual do WSL esteja completamente desligada. Mesmo que você feche a janela da distribuição, ela pode permanecer na memória por alguns segundos.

Para forçar a reinicialização de um subsistema, você pode usar:

• wsl --list --running para verificar se há alguma distribuição ativa
• wsl --shutdown encerrar todas as distribuições de uma só vez
• wsl --terminate <distroName> para interromper uma distribuição específica

As alterações de configuração só são aplicadas quando o WSL é desligado e reiniciado.Algo que muitos ignoram e pensam que seus ajustes "não funcionam".

Principais opções do wsl.conf por seção

O arquivo wsl.conf É inspirado no formato clássico .ini, com seções e chaves.As seções principais são [automount], [network], [interop], [user], [boot], [gpu] y [time].

En [automount] Você controla como as unidades do Windows são montadas no Linux. (normalmente baixo) /mnt):

• enabled (bool, valor padrão verdadeiro)Se verdadeiro, C:/, D:/, etc., são montados automaticamente em /mnt/c, /mnt/d...
• mountFsTab (bool)Se for verdade, será processado. /etc/fstab ao iniciar a distribuição.
• root (corrente): diretório raiz onde as unidades serão montadas, por exemplo /windir/ para ter /windir/c.
• options (lista separada por vírgulas)Parâmetros específicos do DrvFs, como metadata, uid, gid, umask, fmask, dmask o case.

DrvFs é o sistema de arquivos que faz a ponte entre o Windows e o Linux., projetado para acessar NTFS a partir do WSL com controle de permissões, metadados e diferenciação entre maiúsculas e minúsculas.

Na seção [network] Você ajusta a geração automática de arquivos de rede.:

• generateHostsSe verdadeiro, o WSL gera automaticamente /etc/hosts.
• generateResolvConfSe for verdade, o WSL cria /etc/resolv.conf com DNS legado.
• hostname: nome do host que a distribuição utilizará.

A seção [interop] controla a interoperabilidade com o Windows:

• enabledHabilita ou desabilita a capacidade de iniciar processos do Windows a partir do WSL.
• appendWindowsPath: decide se deve adicionar caminhos do Windows a $PATH Linux.

En [user] Você pode especificar o usuário que será usado por padrão ao iniciar a distribuição.:

• default: nome de usuário que será iniciado por padrão no WSL.

A seção [boot] É particularmente útil no Windows 11 e no Server 2022. Para iniciar serviços automaticamente, como o Docker, dentro do WSL:

• command: sequência de comandos a serem executados ao iniciar o WSL, por exemplo service docker start.
• protectBinfmt: protege a geração de unidades do systemd quando o systemd está ativado.

Você também tem seções como [gpu] (habilitar o acesso à GPU do Windows a partir do Linux), e [time] para sincronizar o fuso horário com o WindowsIsso evita problemas quando você muda para o horário de verão ou viaja.

.wslconfig: Controle de máquina virtual WSL2

Enquanto o arquivo wsl.conf ajusta o comportamento de cada distribuição, o arquivo .wslconfig permite ajustar a máquina virtual compartilhada por todas as distribuições do WSL2.Este arquivo só é considerado por distribuições que funcionam como WSL2, não como WSL1.

Dentro .wslconfig a seção principal é [wsl2]onde você define os parâmetros principais:

• kernel y kernelModulesCaminhos absolutos do Windows para um kernel Linux personalizado e seus módulos.
• memory: Limite de memória da VM (padrão: 50% da RAM do host), por exemplo 4GB.
• processors: número de processadores lógicos atribuídos à máquina virtual.
• localhostForwarding: permite que portas abertas no WSL2 sejam acessíveis a partir do Windows usando localhost.
• swap y swapFileTamanho e caminho do arquivo de troca (swap) da máquina virtual.
• guiApplications: Ativa ou desativa o suporte a aplicativos com interface gráfica (WSLg).
• dnsProxyQuando você está no modo NAT, ele decide se o servidor DNS do Linux será a instância NAT do host ou uma cópia do DNS do Windows.
• networkingModeAqui você escolhe entre none, nat, bridged (obsoleto), mirrored o virtioproxy.
• firewall, dnsTunneling y autoProxyOpções que discutimos para melhor integrar a rede WSL com as políticas do Windows.
• defaultVhdSize: tamanho máximo do VHD onde o sistema de arquivos da distribuição está armazenado (padrão: 1 TB).

Há também uma seção [experimental] onde os recursos são ativados em testes como:

• autoMemoryReclaimConfigurações de recuperação automática de memória (desativada, gradual, dropCache).
• sparseVhdCriação de discos virtuais esparsos para economizar espaço.
• bestEffortDnsParsing y dnsTunnelingIpAddress: ajuste fino para tunelamento DNS.
• ignoredPorts: portas que os aplicativos Linux podem usar mesmo que estejam em uso no Windows quando você estiver no modo espelhado.
• hostAddressLoopbackPermite que o host e o contêiner se conectem usando os endereços IP locais do host no modo espelhado.

Configurar corretamente o arquivo .wslconfig faz toda a diferença entre uma máquina virtual que consome muitos recursos e um ambiente otimizado que funciona bem com o seu sistema Windows e a sua rede.especialmente se você trabalha com cargas de trabalho pesadas, contêineres ou várias distribuições simultâneas.

WSL2, Docker e redes para auto-hospedagem com Tailscale.

Um exemplo muito prático é o uso do WSL2 em servidores Windows (mesmo o Windows Server 2025) como uma plataforma de auto-hospedagem., combinando Ubuntu no WSL2, Docker Engine (sem Docker Desktop), Tailscale e um proxy reverso como o Caddy para expor serviços como n8n ou Supabase.

A ideia é ter um ambiente Docker estável dentro do WSL2, evitando os problemas do Docker Desktop em servidores.Ao instalar o Docker Engine diretamente no Ubuntu (WSL2), a rede de contêineres depende da rede WSL2, que por sua vez depende do modo NAT ou espelhado definido no arquivo .wslconfig.

Com o Tailscale instalado no WSL2, você pode publicar seus serviços em uma VPN mesh. Sem abrir portas no roteador e usando o Caddy como um proxy reverso para centralizar certificados TLS, rotas e balanceamento de carga leve entre os contêineres.

Para manter uma rede limpa, previsível e segura, é recomendável:

• Escolha um único modo de rede coerente (NAT ou espelhado) e documente-o.
• Evite conflitos de portas entre o Windows e o WSL2., confiando em ignoredPorts se você usar espelhamento
• Controle a exposição ao serviço somente através do Tailscale ou Caddy.em vez de abrir portas "por padrão" no firewall
• Automatize a inicialização do Docker, Tailscale e Caddy a partir de [boot] em wsl.conf para ter um ambiente mais próximo da produção

Com essa arquitetura, o WSL2 deixa de ser apenas uma ferramenta de desenvolvimento e pode se tornar uma plataforma de auto-hospedagem bastante robusta.desde que você aceite suas limitações (virtualização via Hyper-V, camada de rede adicional, etc.) e o configure com cuidado.

Melhores práticas para redes WSL2 para desenvolvimento e testes.

Além dos ajustes finos, existem algumas diretrizes que ajudam você a trabalhar confortavelmente com a rede WSL2. Sem ter que lidar constantemente com IPs, portas e firewalls.

Para serviços de desenvolvimento, utilize portas de alta resolução (acima de 1024). Evite portas privilegiadas ou muito utilizadas; isso minimiza conflitos e elimina a necessidade de privilégios adicionais.

Certifique-se de que o código e os dados estejam localizados dentro do sistema de arquivos Linux. (você ~/ ou rotas internas) em vez de trabalhar diretamente em /mnt/cPorque o acesso ao NTFS a partir do WSL é mais lento e pode penalizar serviços que exigem muita entrada/saída.

Automatize configurações de rede e regras de redirecionamento com scripts. Em PowerShell e Bash: por exemplo, um script que configura o WSL2 quando ele é iniciado. netsh portproxy (se você continuar com NAT) ou verifique as regras do firewall ao usar o espelhamento.

Evite depender da alteração de IPs. gerado pelo switch virtual interno. Sempre que possível, trabalhe com localhost, nomes de host ou entradas em /etc/hosts para seus serviços, para que uma mudança de IP não quebre metade da sua infraestrutura de testes.

Em ambientes profissionais ou de semi-produção, é melhor não confiar cegamente no encaminhamento automático do WSL.Configure explicitamente portas, proxies e regras de firewall para saber exatamente o que está exposto e onde.

Quando configurado corretamente, o WSL2 oferece uma rede isolada, porém flexível, perfeita para desenvolvimento avançado, testes de API, trabalho com contêineres e simulação de ambientes distribuídos.A chave é dominar os modos de rede (NAT vs. espelhado), os arquivos wsl.conf e .wslconfig, e a interação com o firewall e as ferramentas em seu conjunto de recursos (Docker, Tailscale, proxies reversos), para que o Windows e o Linux possam ser executados na mesma máquina sem sobreposição de portas ou comprometimento da segurança.