Compartilhar via

Configuração de definições avançadas no WSL

Os arquivos wsl.conf e .wslconfig são usados para definir configurações avançadas no WSL que serão aplicadas na inicialização da VM do WSL. wsl.conf é usado para aplicar configurações por distribuição WSL e .wslconfig é usado para aplicar configurações globais ao WSL. Você pode ler mais sobre as diferenças abaixo.

Aspecto .wslconfig wsl.conf
Escopo Configurações gerais que se aplicam a todos os WSL Configurações somente para distribuições WSL
Configura Habilitação de recursos no WSL, configurações para a máquina virtual que alimenta o WSL 2 (RAM, kernel para inicialização, número de CPUs etc.) Configurações de distribuição no WSL, como opções de inicialização, montagem automática do DrvFs, rede, interoperabilidade com o sistema Windows, uso do systemd e usuário padrão
Localização %UserProfile%\.wslconfig, fora de uma distribuição WSL /etc/wsl.conf, enquanto estiver dentro de uma distribuição WSL

Atualmente, todas as configurações de .wslconfig se aplicam somente às distribuições do WSL 2. Saiba Como verificar a versão do WSL que você está executando.

A regra de 8 segundos para alterações de configuração

Você deve aguardar até que o subsistema que executa a distribuição do Linux pare completamente de ser executado e reinicie para que as atualizações de configuração apareçam. Normalmente, isso leva cerca de 8 segundos após o fechamento de TODAS as instâncias do shell de distribuição.

Se você iniciar uma distribuição (por exemplo, Ubuntu), modificar o arquivo de configuração, fechar a distribuição e reiniciá-la, você pode supor que as alterações de configuração entraram em vigor imediatamente. No momento, esse não é o caso, pois o subsistema ainda pode estar em execução. Você deve aguardar o subsistema parar antes de iniciar novamente para dar tempo suficiente para que suas alterações serem refletidas. Você pode verificar se a distribuição do Linux (shell) ainda está em execução após fechá-la usando o PowerShell com o comando: wsl --list --running. Se nenhuma distribuição estiver em execução, você receberá a resposta: "Não há distribuições em execução". Agora você pode reiniciar a distribuição para ver as atualizações de configuração aplicadas.

O comando wsl --shutdown é um caminho rápido para reiniciar as distribuições do WSL 2, mas desligará todas as distribuições em execução, portanto, use com cuidado. Você também pode usar wsl --terminate <distroName> para encerrar uma distribuição específica que está sendo executada instantaneamente.

wsl.conf

Defina as configurações locais com wsl.conf por distribuição para cada distribuição do Linux em execução no WSL 1 ou WSL 2.

  • Armazenado no diretório /etc da distribuição como um arquivo Unix.
  • Usado para definir as configurações por distribuição. As configurações definidas neste arquivo só serão aplicadas à distribuição específica do Linux que contém o diretório em que esse arquivo é armazenado.
  • Pode ser usado para distribuições executadas por qualquer das duas versões, WSL 1 ou WSL 2.
  • Para acessar o diretório /etc de uma distribuição instalada, use a linha de comando da distribuição com cd / para acessar o diretório raiz e, em seguida, ls para listar arquivos ou explorer.exe . para exibir no Explorador de Arquivos do Windows. O caminho do diretório deve ser semelhante a: /etc/wsl.conf.

Observação

Ajustar as configurações por distribuição com o arquivo wsl.conf só está disponível no Windows Build 17093 e posterior.

Configurações para wsl.conf

O arquivo wsl.conf define as configurações por distribuição. (Para a configuração global de distribuições do WSL 2, consulte .wslconfig).

O arquivo wsl.conf dá suporte a quatro seções: automount, network, interop, e user. (Modelado segundo as convenções de arquivos .ini, as chaves são declaradas em uma seção, como nos arquivos .gitconfig.) Consulte wsl.conf para obter informações sobre onde armazenar o arquivo wsl.conf.

Suporte ao systemd

Muitas distribuições do Linux executam “systemd” por padrão (incluindo o Ubuntu) e o WSL adicionou recentemente suporte para esse gerenciador de sistema/serviço para que o WSL seja ainda mais semelhante ao uso de suas distribuições favoritas do Linux em um computador bare-metal. Você precisará da versão 0.67.6 ou posterior do WSL para habilitar o systemd. Verifique sua versão do WSL com o comando wsl --version. Se precisar atualizar, você poderá obter a última versão do WSL na Microsoft Store. Saiba mais no comunicado do blog.

Para habilitar o systemd, abra seu arquivo wsl.conf em um editor de texto usando sudo para permissões de administrador e adicione estas linhas ao /etc/wsl.conf:

[boot]
systemd=true

Em seguida, você precisará encerrar sua distribuição do WSL usando wsl.exe --shutdown no PowerShell para reiniciar suas instâncias do WSL. Depois que a distribuição for reiniciada, o systemd deverá estar em execução. Você pode confirmar usando o seguinte comando: systemctl list-unit-files --type=service, que mostrará o status dos seus serviços.

Configurações de montagem automática

Rótulo da seção wsl.conf: [automount]

Chave Valor Padrão Observações
enabled booliano true true faz com que unidades fixas (ou seja, C:/ ou D:/) sejam montadas automaticamente com DrvFs em /mnt. false significa que as unidades não serão montadas automaticamente, mas você ainda poderá montá-las manualmente ou por meio de fstab.
mountFsTab booliano true O true define o /etc/fstab para ser processado no início do WSL. /etc/fstab é um arquivo no qual você pode declarar outros sistemas de arquivos, como um compartilhamento SMB. Assim, você pode montar esses sistemas de arquivos automaticamente no WSL na inicialização.
root cadeia de caracteres /mnt/ Define o diretório em que as unidades fixas serão montadas automaticamente. Por padrão, isso é definido como /mnt/, portanto, a unidade C do sistema de arquivos do Windows é montada em /mnt/c/. Se você alterar /mnt/ para /windir/, deverá esperar ver sua unidade C fixa montada em /windir/c.
options lista de valores separados por vírgulas, como uid, gid etc, confira opções de montagem automática abaixo "" Os valores da opção de montagem automática são listados abaixo e são acrescentados à cadeia de caracteres de opções de montagem padrão do DrvFs. Somente opções específicas do DrvFs podem ser especificadas.

As opções de montagem automática são aplicadas como opções de montagem para todas as unidades montadas automaticamente. Para alterar as opções somente para uma unidade específica, use o arquivo /etc/fstab. As opções que o binário de montagem normalmente analisa em um sinalizador não são compatíveis. Se você quiser especificar explicitamente essas opções, deverá incluir todas as unidades para as quais deseja fazer isso em /etc/fstab.

Opções de montagem automática

A configuração de diferentes opções de montagem para unidades do Windows (DrvFs) pode controlar como as permissões de arquivos são calculadas para arquivos do Windows. As seguintes opções estão disponíveis:

Chave Descrição Padrão
uid A ID de usuário usada para o proprietário de todos os arquivos A ID de usuário padrão da sua distribuição do WSL (na primeira instalação, o padrão dela é 1000)
gid A ID de grupo usada para o proprietário de todos os arquivos A ID de grupo padrão da sua distribuição do WSL (na primeira instalação, o padrão dela é 1000)
umask Uma máscara octal de permissões a serem excluídas para todos os arquivos e diretórios 022
fmask Uma máscara octal de permissões a serem excluídas para todos os arquivos 000
dmask Uma máscara octal de permissões a serem excluídas para todos os diretórios 000
metadata Se os metadados são adicionados aos arquivos do Windows para dar suporte a permissões do sistema Linux disabled
case Determina os diretórios tratados como com diferenciação de maiúsculas e minúsculas e se os novos diretórios criados com o WSL terão o sinalizador definido. Consulte diferenciação de maiúsculas e minúsculas para obter uma explicação detalhada das opções. As opções incluem off, dir, ou force. off

Por padrão, o WSL define o uid e o gid no valor do usuário padrão. Por exemplo, no Ubuntu, o usuário padrão é uid=1000, gid=1000. Se esse valor for usado para especificar uma opção diferente de gid ou uid, o valor de usuário padrão será substituído. Caso contrário, o valor padrão será sempre acrescentado.

As opções de umask, fmask, etc. mencionadas acima serão aplicadas somente quando a unidade do Windows for montada com metadados. Por padrão, os metadados não estão habilitados. Você pode encontrar mais informações sobre isso aqui.

Observação

as máscaras de permissão passam por uma operação OR lógica antes de serem aplicadas a arquivos ou diretórios.

O que é DrvFs?

DrvFs é um plug-in de sistema de arquivos para WSL que foi projetado para dar suporte à interoperabilidade entre o WSL e o sistema de arquivos do Windows. O DrvFs permite que o WSL monte unidades com sistemas de arquivos com suporte em /mnt, como /mnt/c, /mnt/d etc. Para obter mais informações sobre como especificar o comportamento padrão de diferenciação de maiúsculas e minúsculas ao montar unidades ou diretórios do Windows ou Linux, consulte a página diferenciação de maiúsculas e minúsculas.

Configurações de rede

Rótulo da seção wsl.conf: [network]

Chave Valor Padrão Observações
generateHosts booliano true true define o WSL para gerar /etc/hosts. O arquivo hosts contém um mapa estático do endereço IP correspondente de nomes de host.
generateResolvConf booliano true true define o WSL para gerar /etc/resolv.conf. O resolv.conf contém uma lista DNS que é capaz de resolver um determinado nome de host para seu endereço IP.
hostname cadeia de caracteres Nome do host do Windows Define o nome do host a ser usado para distribuição do WSL.

Configurações de interoperabilidade

Rótulo da seção wsl.conf: [interop]

Essas opções estão disponíveis no Insider Build 17713 e posterior.

Chave Valor Padrão Observações
enabled booliano true Definir essa chave determinará se o WSL dará suporte à inicialização de processos do Windows.
appendWindowsPath booliano true Definir essa chave determinará se o WSL adicionará elementos de caminho do Windows à variável de ambiente $PATH.

Configurações do usuário

Rótulo da seção wsl.conf: [user]

Essas opções estão disponíveis no Build 18980 e posterior.

Chave Valor Padrão Observações
default cadeia de caracteres O nome de usuário inicial criado na primeira execução Definir essa chave especifica em qual usuário será executado ao iniciar uma sessão do WSL pela primeira vez.

Configurações de inicialização

A configuração de Inicialização só está disponível no Windows 11 e no Server 2022.

Rótulo da seção wsl.conf: [boot]

Chave Valor Padrão Observações
command cadeia de caracteres "" Uma cadeia de caracteres do comando que você gostaria de executar quando a instância do WSL for iniciada. Esse comando é executado como o usuário raiz. Por exemplo: service docker start.
protectBinfmt booliano true Impede que o WSL gere unidades do systemd quando o systemd está habilitado.

Configurações de GPU

Rótulo da seção wsl.conf: [gpu]

Chave Valor Padrão Observações
enabled booliano true Permitir que aplicativos Linux acessem a GPU do Windows por meio da para-virtualização.

Configurações de tempo

Rótulo da seção wsl.conf: [time]

Chave Valor Padrão Observações
useWindowsTimezone booliano true Definir essa chave fará com que o WSL use e sincronize com o fuso horário definido no Windows.

Exemplo de arquivo wsl.conf

O arquivo de exemplo wsl.conf abaixo demonstra algumas das opções de configuração disponíveis. Neste exemplo, a distribuição é Ubuntu-20.04 e o caminho do arquivo é \\wsl.localhost\Ubuntu-20.04\etc\wsl.conf.

# Automatically mount Windows drive when the distribution is launched
[automount]

# Set to true will automount fixed drives (C:/ or D:/) with DrvFs under the root directory set above. Set to false means drives won't be mounted automatically, but need to be mounted manually or with fstab.
enabled = true

# Sets the directory where fixed drives will be automatically mounted. This example changes the mount location, so your C-drive would be /c, rather than the default /mnt/c. 
root = /

# DrvFs-specific options can be specified.  
options = "metadata,uid=1003,gid=1003,umask=077,fmask=11,case=off"

# Sets the `/etc/fstab` file to be processed when a WSL distribution is launched.
mountFsTab = true

# Network host settings that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, preventing WSL from the default behavior of auto-generating /etc/hosts, and sets generateResolvConf to false, preventing WSL from auto-generating /etc/resolv.conf, so that you can create your own (ie. nameserver 1.1.1.1).
[network]
hostname = DemoHost
generateHosts = false
generateResolvConf = false

# Set whether WSL supports interop processes like launching Windows apps and adding path variables. Setting these to false will block the launch of Windows processes and block adding $PATH environment variables.
[interop]
enabled = false
appendWindowsPath = false

# Set the user when launching a distribution with WSL.
[user]
default = DemoUser

# Set a command to run when a new WSL instance launches. This example starts the Docker container service.
[boot]
command = service docker start

.wslconfig

Defina as configurações globais com .wslconfig em todas as distribuições instaladas em execução no WSL.

  • O arquivo .wslconfig não existe por padrão. Ele deve ser criado e armazenado em seu diretório %UserProfile% para aplicar essas configurações.
  • Usado para definir as configurações globalmente em todas as distribuições do Linux instaladas em execução como a versão do WSL 2.
  • Pode ser usado apenas para distribuições executadas pelo WSL 2. As distribuições em execução como WSL 1 não serão afetadas por essa configuração, pois não estão em execução como uma máquina virtual.
  • Para acessar seu diretório %UserProfile%, no PowerShell, use cd ~ para acessar seu diretório inicial (que normalmente é seu perfil de usuário, C:\Users\<UserName>) ou você pode abrir o Explorador de Arquivos do Windows e inserir %UserProfile% na barra de endereços. O caminho do diretório deve ser semelhante a: C:\Users\<UserName>\.wslconfig.

O WSL detectará a existência desses arquivos, lerá o conteúdo e aplicará automaticamente as configurações sempre que você iniciar o WSL. Se o arquivo estiver ausente ou malformado (formatação de marcação inadequada), o WSL continuará a ser iniciado normalmente sem as configurações aplicadas.

Configurações para .wslconfig

O arquivo .wslconfig define as configurações globalmente para todas as distribuições do Linux em execução com o WSL 2. (Para configuração por distribuição, consulte wsl.conf).

Consulte .wslconfig para obter informações sobre onde armazenar o arquivo .wslconfig.

Observação

A definição de configurações globais com .wslconfig apenas está disponível para distribuições em execução como WSL 2 no Windows Build 19041 e posterior. Tenha em mente que talvez seja necessário executar wsl --shutdown para desligar a VM do WSL 2 e, em seguida, reiniciar a instância do WSL para que essas alterações entrem em vigor.

Esse arquivo pode conter as seguintes opções que afetam a VM que alimenta qualquer distribuição do WSL 2:

Configurações principais do WSL

Rótulo da seção .wslconfig: [wsl2]

Chave Valor Padrão Observações
kernel caminho A caixa de entrada fornecida pelo kernel da Microsoft Um caminho absoluto do Windows para um kernel personalizado do Linux.
kernelModules caminho Um caminho absoluto do Windows para um VHD de módulos de kernel do Linux personalizado.
memory dimensionar 50% da memória total no Windows Quanta memória atribuir à VM do WSL 2.
processors número O mesmo número de processadores lógicos no Windows Quantos processadores lógicos atribuir à VM do WSL 2.
localhostForwarding booliano true Booliano especificando se as portas associadas ao curinga ou localhost na VM do WSL 2 devem ser conectáveis do host por meio do localhost:port.
kernelCommandLine cadeia de caracteres "" Argumentos adicionais de linha de comando do kernel.
safeMode* booliano false Execute o WSL no “Modo de Segurança”, que desabilita muitos recursos e se destina a ser usado para recuperar distribuições que estão em estados inválidos. Disponível somente para Windows 11 e WSL versão 0.66.2 e posteriores.
swap dimensionar 25% do tamanho da memória no Windows arredondado para cima até o GB mais próximo Quanto espaço de troca adicionar à VM do WSL 2, 0 para nenhum arquivo de troca. A memória swap é uma RAM baseada em disco que é utilizada quando a necessidade de memória excede o limite no dispositivo de hardware.
swapFile caminho %USERPROFILE%\AppData\Local\Temp\swap.vhdx Um caminho absoluto do Windows para o disco rígido virtual de troca.
pageReporting booliano true A configuração padrão true permite que o Windows recupere a memória não utilizada alocada para a máquina virtual do WSL 2.
guiApplications booliano true Booliano para ativar ou desativar o suporte para aplicativos de GUI (WSLg) no WSL.
debugConsole* booliano false Booliano para ativar uma Janela do console de saída que mostra o conteúdo de dmesg no início de uma instância de distribuição do WSL 2. Disponível somente para Windows 11.
nestedVirtualization* booliano true Booliano para ativar ou desativar a virtualização aninhada, permitindo que outras VMs aninhadas sejam executadas dentro do WSL 2. Disponível somente para Windows 11.
vmIdleTimeout* número 60000 O número de milissegundos que uma VM está ociosa, antes de ser desativada. Disponível somente para Windows 11.
dnsProxy booliano true Aplicável somente ao networkingMode = NAT. Booliano para informar o WSL para configurar o servidor DNS no Linux para o NAT no host. A configuração como falso espelhará os servidores DNS do Windows para o Linux.
networkingMode** cadeia de caracteres NAT Se o valor for mirrored, isso ativa o modo de rede espelhada. Cadeias de caracteres padrão ou não reconhecidas resultam na rede NAT.
firewall** booliano true Definir isso como true permite que as regras do Firewall do Windows, bem como regras específicas do tráfego do Hyper-V, filtrem o tráfego de rede WSL.
dnsTunneling** booliano true Altera a forma como as solicitações DNS são feitas por proxy do WSL para o Windows
autoProxy* booliano true Força o WSL a usar as informações de proxy HTTP do Windows
defaultVhdSize dimensionar 1TB Defina o tamanho do VHD (Disco Rígido Virtual) que armazena o sistema de arquivos de distribuição do Linux (por exemplo, Ubuntu). Pode ser usado para limitar o tamanho máximo que um sistema de arquivos de distribuição tem permissão para assumir.

As entradas com o valor path devem ser caminhos do Windows com barras invertidas de escape, por exemplo: C:\\Temp\\myCustomKernel

As entradas com o valor size devem ser de um tamanho seguido por uma unidade, por exemplo, 8GB ou 512MB.

As entradas com um * depois do tipo de valor só estão disponíveis no Windows 11.

Entradas com um ** após o valor exigem Windows 11 versão 22H2 ou superior.

Configurações experimentais

Essas configurações são visualizações de aceitação de recursos experimentais que pretendemos tornar padrão no futuro.

Rótulo da seção .wslconfig: [experimental]

Chave Valor Padrão Observações
autoMemoryReclaim cadeia de caracteres dropCache Libera automaticamente a memória armazenada em cache depois de detectar o uso de CPU ocioso. Defina como gradual para liberação lenta e dropCache para liberação instantânea da memória em cache.
sparseVhd Bool false Quando definido como verdadeiro, qualquer VHD recém-criado será definido como esparso automaticamente.
bestEffortDnsParsing** Bool false Aplicável somente quando wsl2.dnsTunneling é definido como true. Quando definido como true, o Windows extrairá a pergunta da solicitação DNS e tentará resolvê-la, ignorando os registros desconhecidos.
dnsTunnelingIpAddress** cadeia de caracteres 10.255.255.254 Aplicável somente quando wsl2.dnsTunneling é definido como true. Especifica o nameserver que será configurado no arquivo resolv.conf do Linux quando o túnel DNS estiver habilitado.
initialAutoProxyTimeout* cadeia de caracteres 1000 Aplicável somente quando wsl2.autoProxy é definido como true. Configura por quanto tempo (em milissegundos) o WSL aguardará a recuperação de informações de proxy HTTP ao iniciar um contêiner WSL. Se as configurações de proxy forem resolvidas após esse tempo, a instância do WSL deverá ser reiniciada para usar as configurações de proxy recuperadas.
ignoredPorts** cadeia de caracteres nulo Aplicável somente quando wsl2.networkingMode é definido como mirrored. Especifica a quais portas os aplicativos Linux podem ser associados, mesmo que essa porta seja usada no Windows. Isso permite que os aplicativos ouçam em uma porta para tráfego puramente dentro do Linux, de modo que esses aplicativos não sejam bloqueados mesmo quando essa porta é usada para outras finalidades no Windows. Por exemplo, o WSL permitirá a associação à porta 53 no Linux para Docker Desktop, pois está escutando apenas as solicitações de dentro do contêiner do Linux. Deve ser formatado em uma lista separada por vírgulas, por exemplo: 3000,9000,9090
hostAddressLoopback** Bool false Aplicável somente quando wsl2.networkingMode é definido como mirrored. Quando definido como True, permitirá que o Contêiner se conecte ao Host, ou que o Host se conecte ao Contêiner, através de um endereço IP atribuído ao Host. O endereço de loopback 127.0.0.1 sempre pode ser usado, esta opção permite que todos os endereços IP locais atribuídos adicionalmente sejam usados também. Somente endereços IPv4 atribuídos ao host são suportados.

As entradas com um * depois do tipo de valor só estão disponíveis no Windows 11.

As entradas com um ** após o tipo de valor exigem Windows versão 22H2 ou superior.

Exemplo de arquivo .wslconfig

O arquivo de exemplo .wslconfig abaixo demonstra algumas das opções de configuração disponíveis. Neste exemplo, o caminho do arquivo é C:\Users\<UserName>\.wslconfig.

# Settings apply across all Linux distros running on WSL 2
[wsl2]

# Limits VM memory to use no more than 4 GB, this can be set as whole numbers using GB or MB
memory=4GB 

# Sets the VM to use two virtual processors
processors=2

# Specify a custom Linux kernel to use with your installed distros. The default kernel used can be found at https://github.com/microsoft/WSL2-Linux-Kernel
kernel=C:\\temp\\myCustomKernel

# Specify the modules VHD for the custum Linux kernel to use with your installed distros.
kernelModules=C:\\temp\\modules.vhdx

# Sets additional kernel parameters, in this case enabling older Linux base images such as Centos 6
kernelCommandLine = vsyscall=emulate

# Sets amount of swap storage space to 8GB, default is 25% of available RAM
swap=8GB

# Sets swapfile path location, default is %USERPROFILE%\AppData\Local\Temp\swap.vhdx
swapfile=C:\\temp\\wsl-swap.vhdx

# Disable page reporting so WSL retains all allocated memory claimed from Windows and releases none back when free
pageReporting=false

# Turn on default connection to bind WSL 2 localhost to Windows localhost. Setting is ignored when networkingMode=mirrored
localhostforwarding=true

# Disables nested virtualization
nestedVirtualization=false

# Turns on output console showing contents of dmesg when opening a WSL 2 distro for debugging
debugConsole=true

# Enable experimental features
[experimental]
sparseVhd=true

Recursos adicionais